berachain · okjintao · May 7, 2025 · May 8, 2025 · May 8, 2025 · May 8, 2025
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,28 @@
+# Guide Addition/Update
+
+## Description
+Brief description of the guide or changes
+
+## Type of Change
+- [ ] New guide
+- [ ] Update to existing guide
+- [ ] Bug fix
+- [ ] Documentation update
+
+## Guide Details
+- Name: 
+- Category: (e.g., Smart Contracts, Frontend, Infrastructure)
+- Dependencies Added:
+- Network: (e.g., Bepolia, Mainnet)
+
+## Checklist
+- [ ] Follows guide structure
+- [ ] README.md includes all required sections
+- [ ] WALKTHROUGH.md includes all required sections
+- [ ] Uses @branch/berachain-config for network config
+- [ ] All scripts tested end-to-end
+- [ ] Environment variables documented
+- [ ] No sensitive data in code or docs
+
+## Additional Notes
+Any additional context or notes for reviewers 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,71 @@
+# Contributing to Berachain Guides
+
+Thanks for your interest in contributing to Berachain Guides! This document provides guidelines and standards for adding new guides or improving existing ones.
+
+## Guide Structure
+
+Each guide should be placed in the `apps/` directory and follow this structure:
+
+```
+apps/your-guide-name/
+├── README.md           # Setup and quick start
+├── WALKTHROUGH.md      # Detailed process explanation
+├── contracts/          # Smart contracts (if applicable)
+├── scripts/           # Deployment/interaction scripts
+├── .env.example       # Example environment variables
+└── package.json       # Dependencies and scripts
+```
+
+## Documentation Standards
+
+### README.md
+- Clear prerequisites
+- Step-by-step setup instructions
+- Project structure
+- Common issues and solutions
+- Network details
+- Links to additional resources
+
+### WALKTHROUGH.md
+- Detailed process explanation
+- Code snippets with context
+- Example outputs
+- Troubleshooting guide
+- Next steps
+
+## Code Standards
+
+1. **Dependencies**
+   - Use `@branch/berachain-config` for network configuration
+   - Keep dependencies up to date
+   - Document any special requirements
+
+2. **Scripts**
+   - Include clear error handling
+   - Add helpful console output
+   - Document all environment variables
+
+3. **Contracts**
+   - Include NatSpec comments
+   - Follow Solidity style guide
+   - Add test cases where applicable
+
+## Pull Request Process
+
+1. Create a new branch from `main`
+2. Follow the PR template
+3. Ensure all tests pass
+4. Update documentation as needed
+5. Get at least one review before merging
+
+## Adding a New Guide
+
+1. Create a new directory in `apps/`
+2. Follow the guide structure above
+3. Use existing guides as templates
+4. Test the guide end-to-end
+5. Submit a PR with the template
+
+## Questions?
+
+Feel free to open an issue or reach out to the team! 
diff --git a/README.md b/README.md
@@ -4,43 +4,103 @@ A collection of [Berachain](https://docs.berachain.com/learn/) EVM examples: cod
 
 ## Requirements
 
-- NVM or Node `v18.18.2+`
 - pnpm (recommended)
 
-## Turborepo Folder Structure
+## Documentation Tree
 
-This Turborepo includes the following packages/apps:
+```
+📚 Berachain Guides
+├── 📦 Core Packages
+│   ├── 📄 berachain-config/                           # Network & RPC configurations
+│   │   ├── 📄 README.md                               # Integration patterns & security
+│   │   ├── 📄 viem/                                   # Viem integration utilities
+│   │   └── 📄 ethers/                                 # Ethers integration utilities
+│   ├── 📄 typescript-config/                          # Shared TypeScript configs
+│   ├── 📄 eslint-config/                              # Shared ESLint configs
+│   └── 📄 ui/                                         # Shared UI components
+│
+├── 📱 Smart Contract Development
+│   ├── 📄 Basic Deployment
+│   │   ├── 📄 viem-solc-helloworld/                   # Viem + Solc example
+│   │   ├── 📄 ethers6-solc-helloworld/                # Ethers + Solc example
+│   │   └── 📄 foundry-erc20/                          # Foundry ERC20 example
+│   │
+│   ├── 📄 Hardhat Examples
+│   │   ├── 📄 hardhat-viem-helloworld/                # Hardhat + Viem
+│   │   ├── 📄 hardhat-ethers6-erc1155/                # Hardhat + Ethers
+│   │   └── 📄 hardhat-contract-verification/          # Contract verification
+│   │
+│   └── 📄 Advanced Patterns
+│       ├── 📄 openzeppelin-upgrades/                  # Upgrade patterns
+│       ├── 📄 berachain-governance-proposal/          # Governance
+│       ├── 📄 gelato-vrf/                             # Chainlink VRF
+│       └── 📄 layerzero-oft/                          # Cross-chain
+│
+├── 🌐 Frontend Integration
+│   ├── 📄 Web Applications
+│   │   ├── 📄 walletconnect-nextjs/                   # WalletConnect
+│   │   ├── 📄 particle-auth-core-vite/                # Particle Network
+│   │   ├── 📄 rainbowkit-vite/                        # RainbowKit
+│   │   └── 📄 thirdweb-connectwallet-nextjs/          # Thirdweb
+│   │
+│   └── 📄 Mobile
+│       └── 📄 walletconnect-expo/                     # React Native
+│
+└── 🛠️ Infrastructure & Tools
+    ├── 📄 Indexing & Data
+    │   ├── 📄 goldsky-subgraph/                       # The Graph
+    │   ├── 📄 envio-indexer-erc20/                    # Envio
+    │   └── 📄 erpc-proxy-caching/                     # RPC caching
+    │
+    ├── 📄 Oracle Integration
+    │   ├── 📄 pyth-oracle/                            # Price feeds
+    │   └── 📄 pyth-entropy/                           # Entropy
+    │
+    └── 📄 Development Tools
+        ├── 📄 local-docker-devnet/                    # Local dev
+        ├── 📄 node-scripts/                           # Utilities
+        └── 📄 berps-bot/                              # Trading bot
+```
 
-### Apps
+## Quick Start
 
-- `apps/ethers6-solc-helloworld` - Deploy HelloWorld contract with ethers6
-- `apps/viem-solc-helloworld` - Deploy HelloWorld contract with viem
-- `apps/foundry-erc20` - Deploy ERC20 contract with foundry
-- `apps/hardhat-ethers6-erc1155` - Deploy ERC1155 contract with hardhat ethers6
-- `apps/hardhat-viem-helloworld` - Deploy HelloWorld contract with hardhat viem
-- `apps/walletconnect-nextjs` - WalletConnect Web3Modal frontend contract deployment
+1. Install dependencies:
+   ```bash
+   pnpm install
+   ```
 
-## Quick Start
+2. Set up environment variables:
+   ```bash
+   cp .env.example .env
+   ```
 
-Install dependencies for all apps and packages.
+3. Deploy a contract:
+   ```bash
+   # Deploy ERC20 contract
+   pnpm deploy:berachain --filter foundry-erc20 --no-cache
+   ```
 
-```bash
-# FROM: ./
+## Getting Started
 
-pnpm install;
-```
+1. **Core Concepts**
+   - Start with `berachain-config` to understand network integration
+   - Review basic contract deployment examples
 
-Create and modify your `.env` and make the modifications you need to it.
+2. **Choose Your Path**
+   - Smart Contract Development: Start with basic deployment examples
+   - Frontend Integration: Begin with wallet connection examples
+   - Infrastructure: Explore indexing and oracle examples
 
-```bash
-cp .env.example .env;
-```
+3. **Advanced Topics**
+   - Contract upgrades and governance
+   - Cross-chain functionality
+   - Advanced indexing patterns
 
-If you'd like to deploy to the chain:
+## Contributing
 
-```bash
-# FROM: ./
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
 
-# IMPORTANT: --no-cache is important to avoid caching the result of the deployments
-pnpm deploy:berachain --filter foundry-erc20 --no-cache;
-```
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
diff --git a/apps/viem-solc-helloworld/.env.example b/apps/viem-solc-helloworld/.env.example
@@ -1,16 +1,2 @@
-# Chain Configurations
-CHAIN_ID=
-NETWORK_NAME=berachainTestnet
-CURRENCY_DECIMALS=18
-CURRENCY_NAME=BERA Token
-CURRENCY_SYMBOL=BERA
-
-# API key for Beratrail Block Explorer, can be any value for now
-BLOCK_EXPLORER_NAME=Beratrail
-BLOCK_EXPLORER_API_KEY=xxxxx
-BLOCK_EXPLORER_API_URL=
-BLOCK_EXPLORER_URL=
-
-# Wallet + RPC configurations
-RPC_URL=https://artio.rpc.berachain.com/
+# Your wallet private key (without 0x prefix)
 WALLET_PRIVATE_KEY=YOUR_WALLET_PRIVATE_KEY
diff --git a/apps/viem-solc-helloworld/README.md b/apps/viem-solc-helloworld/README.md
@@ -0,0 +1,99 @@
+# Viem + Solc Hello World Example 🚀
+
+A simple example of deploying a smart contract on Berachain using Viem and Solc. This guide will help you get started with smart contract development on Berachain.
+
+## Prerequisites 📋
+
+Before you begin, make sure you have:
+- Node.js v20+ installed
+- A Berachain wallet with some test tokens
+- Your wallet's private key (we'll help you set this up)
+
+## Quick Start 🚀
+
+1. **Clone and Install**
+   ```bash
+   git clone <repository-url>
+   cd viem-solc-helloworld
+   pnpm install
+   ```
+
+2. **Environment Setup**
+   ```bash
+   # Copy the example environment file
+   cp .env.example .env
+   ```
+
+   Then open `.env` and add your wallet's private key:
+   ```
+   WALLET_PRIVATE_KEY=your_private_key_here
+   ```
+
+3. **Deploy Your Contract**
+   ```bash
+   pnpm deploy:berachain
+   ```
+
+## Project Structure 📁
+
+```
+viem-solc-helloworld/
+├── contracts/              # Your Solidity contracts
+│   └── HelloWorld.sol     # The contract we'll deploy
+├── scripts/               # Deployment scripts
+│   └── deploy.ts         # Main deployment script
+├── .env.example          # Example environment file
+└── package.json          # Project dependencies
+```
+
+## What's Inside? 🔍
+
+- A simple "Hello World" smart contract
+- A deployment script using Viem and Solc
+- Configuration for Berachain network
+
+## Need More Details? 📚
+
+Check out the [WALKTHROUGH.md](./WALKTHROUGH.md) for a detailed explanation of the deployment process and code snippets.
+
+## Common Setup Issues 🔧
+
+1. **Node.js Version**
+   - Make sure you're using Node.js v20 or higher
+   - You can check your version with `node --version`
+
+2. **Private Key Format**
+   - Your private key should start with `0x`
+   - Keep it secure and never share it
+
+3. **Test Tokens**
+   - You'll need some test tokens for deployment
+   - Get them from the Berachain faucet
+
+## Need Help? 🤝
+
+If you run into any issues:
+- Check the error message carefully
+- Make sure all prerequisites are met
+- Verify your environment variables are set correctly
+
+Happy coding! 🌟
+
+## Network Details
+
+The contract is deployed to Berachain Bepolia testnet with the following configuration:
+- Network Name: Berachain Bepolia
+- Chain ID: 80069
+- RPC URL: https://bepolia.rpc.berachain.com
+- Explorer: https://bepolia.beratrail.io
+
+## Additional Resources
+
+- [Viem Documentation](https://viem.sh)
+- [Solc-js Documentation](https://github.com/ethereum/solc-js#readme)
+- [Berachain Documentation](https://docs.berachain.com/)
+- [@branch/berachain-config Package](../../packages/berachain-config/README.md)
+
+## Detailed Walkthrough
+
+For a detailed explanation of the deployment process and script functionality, see [WALKTHROUGH.md](./WALKTHROUGH.md).