Add comprehensive README.md for entropy/growing example

[devin-ai-integration]

Pyth Examples Contribution

Type of Contribution

• New Example Project
• Bug Fix
• Documentation Update (Improving README, comments, or guides)
• Enhancement
• Hackathon Submission

Project Information

Project/Example Name: NFT Growth with Pyth Entropy

Pyth Product Used:

• Pyth Price Feeds
• Pyth Entropy
• Multiple Products
• Other: ___________

Blockchain/Platform:

• Ethereum/EVM (Blast Sepolia)
• Solana
• Aptos
• Sui
• Fuel
• Starknet
• TON
• Other: ___________

Description

What does this contribution do?

This PR adds a comprehensive README.md file to the entropy/growing directory to document the existing NFT Growth example. The README provides a complete overview of the project, explaining how it demonstrates Pyth Entropy integration through an interactive NFT leveling system.

How does it integrate with Pyth?

The documentation explains how the example uses Pyth Entropy's verifiable randomness through the commit-reveal callback pattern:

1. User initiates NFT growth with user-contributed randomness
2. Contract requests randomness via entropy.requestWithCallback()
3. Entropy provider calls back with verifiable random number
4. Contract uses randomness to determine growth outcome (40% success, 40% failure, 20% death)

What problem does it solve or demonstrate?

The README addresses the lack of top-level documentation for this example. Previously, there were separate README files in the contract/ and app/ subdirectories, but no overview explaining:

• What the overall example demonstrates
• How to run the complete end-to-end application
• The architecture and how components work together
• The technology stack and development approach

Directory Structure

The README documents the existing structure:

entropy/growing/
├── contract/           # Smart contracts built with Hardhat
├── app/                # Next.js frontend application  
└── README.md          # This new top-level documentation

Testing & Verification

How to Review This Contribution

This is a documentation-only change with no code modifications. Reviewers should:

1. Verify technical accuracy by comparing the README against the actual contract code:

   • Check that probabilities (40/40/20) match NFTGrowth.sol lines 65-67
   • Verify the locking mechanism description matches the contract implementation
   • Confirm Entropy contract addresses match ignition/modules/App.ts

2. Validate completeness of instructions:

   • Ensure all referenced files exist (e.g., contracts/addresses.ts, config.ts)
   • Check that setup commands are complete and in the correct order
   • Verify technology stack matches package.json files

3. Test external links:

   • Pyth Entropy documentation links
   • lualabs.xyz attribution link

Key Areas for Review

• Lines 10-12: Verify outcome probabilities match contract code (successChance=4000, failChance=4000, deathChance=2000 out of 10000)
• Lines 90-92: Confirm Entropy contract and provider addresses are correct for Blast Sepolia
• Lines 83-88: Validate deployment instructions match the existing setup
• Lines 169-171: Verify 10-minute lock period matches contract code

Checklist

Code Quality

• Documentation follows existing patterns in the repository
• Information is accurate based on code review
• No hardcoded values introduced (documentation only)

Testing

• Reviewed existing code to ensure accuracy
• No functionality changes (documentation only)

Additional Context

Related Issues

N/A - This is a documentation improvement for an existing example.

Notes for Reviewers

Technical Details Verified:

• All probabilities, timeouts, and parameters extracted directly from contract source code
• Contract addresses pulled from deployment configuration
• Technology stack verified against package.json files
• Setup instructions based on existing subdirectory READMEs

What Changed:

• Single new file: entropy/growing/README.md (214 lines)
• No code changes, no functional changes
• Pure documentation to improve developer experience

Limitations:

• I have not personally executed the setup instructions end-to-end
• External links to Pyth documentation assumed to be current
• Some configuration file names (e.g., contracts/addresses.ts) should be verified to exist

---

Link to Devin run: https://app.devin.ai/sessions/f9d9e77ce0ca41f1a17358d6092311da
Requested by: Jayant ([email protected]) / @jayantk

Thank you for contributing to Pyth Examples!

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring