diff --git a/.gitignore b/.gitignore
index 714dd4f..99ce320 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,11 +1,40 @@
+# Anchor
 .anchor
-.DS_Store
 target
 **/*.rs.bk
-node_modules
 test-ledger
+
+# Node.js
+node_modules
 .yarn
+bun.lockb
 
+# Environment files
 .env
-keypairs/
+.env.local
+.env.*.local
+
+# IDE
+.DS_Store
 /.idea/
+.vscode/
+*.swp
+*.swo
+
+# Keys and secrets
+keypairs/
+*.pem
+*.key
+
+# Build artifacts
+out/
+dist/
+build/
+
+# Logs
+*.log
+logs/
+
+# Cache
+.cache/
+.temp/
diff --git a/CLAUDE.md b/CLAUDE.md
index 0fd38c0..35dec99 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -70,7 +70,7 @@ bun run tx:wrap-token devnet-alpha
 
 ### Base Side
 - **Bridge.sol**: Main contract receiving calls from Solana and managing message execution
-- **Twin.sol**: Execution contract for each Solana sender pubkey  
+- **Twin.sol**: Execution contract for each Solana sender pubkey
 - **CrossChainERC20.sol**: Mintable/burnable ERC20 for cross-chain transfers
 - **CrossChainERC20Factory.sol**: Factory for deploying wrapped tokens
 
@@ -91,7 +91,7 @@ bun run tx:wrap-token devnet-alpha
 - Requires `testnet-admin` wallet account for deployments
 - Environment variables in `base/Makefile` for contract addresses
 
-### Solana Program  
+### Solana Program
 - Uses Anchor framework with Rust
 - Requires keypair files in `keypairs/` directory
 - Two environments: devnet-alpha and devnet-prod
@@ -105,6 +105,6 @@ bun run tx:wrap-token devnet-alpha
 ## Key Files to Understand
 
 - `base/src/Bridge.sol` - Core Base bridge logic
-- `solana/programs/bridge/src/lib.rs` - Solana program entry point  
+- `solana/programs/bridge/src/lib.rs` - Solana program entry point
 - `base/script/Deploy.s.sol` - Base deployment script
 - `solana/scripts/onchain/` - Solana transaction examples
\ No newline at end of file
diff --git a/README.md b/README.md
index 3ec53e4..01bd066 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,7 @@ A bridge between Base and blockchains outside the Ethereum ecosystem. Currently
 [![GitHub pull requests by-label](https://img.shields.io/github/issues-pr-raw/base/bridge)](https://github.com/base/bridge/pulls)
 [![GitHub Issues](https://img.shields.io/github/issues-raw/base/bridge.svg)](https://github.com/base/bridge/issues)
 
-## How it Works
+## How It Works
 
 This bridge allows you to:
 
diff --git a/base/.env.example b/base/.env.example
new file mode 100644
index 0000000..254611a
--- /dev/null
+++ b/base/.env.example
@@ -0,0 +1,18 @@
+# Base Bridge Environment Configuration
+# Copy this file to .env and update with your values
+
+# Environment (alpha or prod)
+BRIDGE_ENVIRONMENT=alpha
+
+# RPC URLs
+BASE_RPC=https://base-sepolia.cbhq.net
+# BASE_RPC=https://mainnet.base.org
+
+# Token Recipients (bytes32 format)
+SOLANA_SOL_RECEIVER=0x9827993b7b317eb6c74279d49074a13b33a3495a30637c86a7513922014ba424
+USER_SPL_ATA=0x6621d2d930ef7ada6260d3e0a5679a8fe81fde41262314f2efbf9c4c828550b1
+USER_REMOTE_ERC20_ATA=0x4394d16902c022f8f87c7667429bc8b2860d033e316b9f9515534505fae314e9
+USER_REMOTE_ETH_ATA=0x15e9307085f98b2e64eb3dd36b7fbafea201cc2a9fcb36c8c207e99bc7b97f30
+
+# Default bridge amount (in wei)
+AMOUNT=1000000000
\ No newline at end of file
diff --git a/base/Makefile b/base/Makefile
index 6656f48..e2db1c2 100644
--- a/base/Makefile
+++ b/base/Makefile
@@ -3,9 +3,9 @@
 BASE_RPC=https://base-sepolia.cbhq.net
 # BASE_RPC=https://mainnet.base.org
 
-# Update values in this section to specify token recipients / token amount
+# Update values in this section to specify token recipients and token amounts
 ####################################################################################################
-# alpha or prod
+# Environment: alpha or prod
 ENV_NAME=alpha
 
 SOLANA_SOL_RECEIVER = 0x9827993b7b317eb6c74279d49074a13b33a3495a30637c86a7513922014ba424
diff --git a/base/README.md b/base/README.md
index a40e88b..3c3d757 100644
--- a/base/README.md
+++ b/base/README.md
@@ -18,7 +18,7 @@ The Base Bridge contracts facilitate bidirectional communication between Base an
 
 ### Core Contracts
 
-- **Bridge**: Main contract that receives calls from Solana and manages message execution via Twin contracts. Bridge is also the entrypoint for sending messages to Solana
+- **Bridge**: Main contract that receives calls from Solana and manages message execution via Twin contracts. Bridge is also the entry point for sending messages to Solana
 - **Twin**: Execution contract specific to each Solana sender pubkey that processes calls from the bridge
 - **CrossChainERC20**: ERC20 token implementation that can be minted/burned by the bridge for cross-chain transfers
 - **CrossChainERC20Factory**: Factory contract for deploying wrapped tokens representing Solana tokens on Base
@@ -105,7 +105,7 @@ Custom bridging:
 BRIDGE_ENVIRONMENT=alpha LOCAL_TOKEN=0x123... REMOTE_TOKEN=0x456... TO=0x789... AMOUNT=1000000 forge script BridgeTokensToSolanaScript --account testnet-admin --rpc-url $BASE_RPC --broadcast -vvvv
 ```
 
-- `LOCAL_TOKEN`: address of ERC20 token on Base
-- `REMOTE_TOKEN`: bytes32 representation of SPL mint pubkey on Solana (`0x069be72ab836d4eacc02525b7350a78a395da2f1253a40ebafd6630000000000` for native SOL)
-- `TO`: bytes32 representation of Solana pubkey receiver (this is your Solana wallet address if bridging SOL and it should be your associated token account if bridging into an SPL token)
+- `LOCAL_TOKEN`: Address of ERC20 token on Base
+- `REMOTE_TOKEN`: Bytes32 representation of SPL mint pubkey on Solana (`0x069be72ab836d4eacc02525b7350a78a395da2f1253a40ebafd6630000000000` for native SOL)
+- `TO`: Bytes32 representation of Solana pubkey receiver (this is your Solana wallet address if bridging SOL and it should be your associated token account if bridging into an SPL token)
 - `AMOUNT`: The amount of Base tokens to bridge in wei
diff --git a/base/foundry.toml b/base/foundry.toml
index 824d5d2..d59e718 100644
--- a/base/foundry.toml
+++ b/base/foundry.toml
@@ -8,7 +8,7 @@ optimizer = true
 remappings = ["forge-std/=lib/forge-std/src/", "solady/=lib/solady/src/"]
 gas_limit = "18446744073709551615"
 
-# See more config options https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options
+# See more config options: https://github.com/foundry-rs/foundry/blob/master/crates/config/README.md#all-options
 [fmt]
 sort_imports = true
 wrap_comments = true
diff --git a/scripts/README.md b/scripts/README.md
index 28f5a94..95edee2 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -40,7 +40,7 @@ bun install
 
 ## Non-Interactive Mode
 
-All commands support non-interactive execution by providing required arguments:
+All commands support non-interactive execution by providing the required arguments:
 
 ```bash
 bun cli sol onchain bridge bridge-sol --cluster devnet --release prod --to 0x1234567890123456789012345678901234567890 --amount 10 --payer-kp config
diff --git a/setup.md b/setup.md
new file mode 100644
index 0000000..c93f16a
--- /dev/null
+++ b/setup.md
@@ -0,0 +1,108 @@
+# Base Bridge Setup Guide
+
+This guide will help you set up the Base Bridge development environment.
+
+## Prerequisites
+
+### Required Tools
+
+1. **Foundry** (for Base contracts)
+   - Install: `curl -L https://foundry.paradigm.xyz | bash && foundryup`
+   - Verify: `forge --version`
+
+2. **Bun** (for Solana scripts)
+   - Install: `curl -bsSf https://bun.sh/install | bash`
+   - Verify: `bun --version`
+
+3. **Rust & Cargo** (for Solana programs)
+   - Install: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+   - Install Solana CLI: `sh -c "$(curl -sSfL https://release.solana.com/stable/install)"`
+
+4. **Make** (build automation)
+   - Windows: Install via chocolatey `choco install make`
+   - macOS: `xcode-select --install`
+   - Linux: Usually pre-installed
+
+## Setup Steps
+
+### 1. Clone and Install Dependencies
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd bridge
+
+# Install Base contract dependencies
+cd base
+make deps
+cd ..
+
+# Install Solana script dependencies
+cd scripts
+bun install
+cd ..
+```
+
+### 2. Environment Configuration
+
+```bash
+# Copy environment template for Base
+cp base/.env.example base/.env
+
+# Edit base/.env with your configuration
+# Update recipient addresses and other parameters as needed
+```
+
+### 3. Wallet Setup
+
+```bash
+# Create testnet admin wallet for Base deployments
+cast wallet import testnet-admin --interactive
+
+# Generate Solana keypair (if needed)
+solana-keygen new --outfile ~/.config/solana/id.json
+
+# Fund your Solana account on devnet
+# Visit: https://solfaucet.com/
+```
+
+### 4. Build and Test
+
+```bash
+# Build Base contracts
+cd base
+forge build
+forge test
+
+# Build Solana programs
+cd ../solana
+cargo build-sbf
+cargo test
+```
+
+### 5. Deploy (Testnet)
+
+```bash
+# Deploy Base contracts
+cd base
+make deploy
+
+# Deploy Solana programs
+cd ../scripts
+bun cli sol program deploy
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Forge not found**: Ensure Foundry is installed and in your PATH
+2. **Bun not found**: Restart your terminal after installing Bun
+3. **Insufficient funds**: Ensure your wallets have enough testnet tokens
+4. **Build failures**: Check that all dependencies are properly installed
+
+### Getting Help
+
+- Check the individual README files in `base/`, `solana/`, and `scripts/` directories
+- Review the `CLAUDE.md` file for detailed architecture information
+- Open an issue on the repository for specific problems
\ No newline at end of file
diff --git a/solana/README.md b/solana/README.md
index 85a8df8..9a59b16 100644
--- a/solana/README.md
+++ b/solana/README.md
@@ -38,6 +38,6 @@ cargo test
 
 ## Usage
 
-Make sure you have a funded solana keypair in `~/.config/solana/id.json`. You can use the `solana-keygen new` command to generate a new keypair. You can use this solana faucet to fund your account on devnet: https://solfaucet.com/.
+Make sure you have a funded Solana keypair in `~/.config/solana/id.json`. You can use the `solana-keygen new` command to generate a new keypair. You can use this Solana faucet to fund your account on devnet: https://solfaucet.com/.
 
 The `scripts/` directory contains an interactive CLI for interacting with the program. See [scripts/README.md](../scripts/README.md) for detailed usage instructions and available commands.