Polygon PoS Development

说明文档

# Polygon PoS Development

End-to-end guide for developing and deploying smart contracts on Polygon PoS blockchain using Foundry.

## Overview

Polygon PoS is an EVM-compatible Proof-of-Stake sidechain for Ethereum with:
- Low transaction costs (fraction of a cent)
- Fast block times (~2 seconds)
- High throughput (65,000+ TPS theoretical)
- Full Ethereum tooling compatibility
- POL token for gas fees

**Default Network**: Amoy Testnet (Chain ID: 80002) - Use for all testing before mainnet.

---

## 🚀 Quick Navigation

**For Agents/Fast Deployment**: Jump to [Quick Start Path](#quick-start-path) (5-10 min)

**For Production/Thorough Testing**: Jump to [Complete Development Path](#complete-development-path) (30-60 min)

**For Reference**: See sections below for [Network Configuration](#network-configuration), [Faucets](#getting-testnet-tokens), [Troubleshooting](#troubleshooting)

---

## Two Development Paths

Choose based on your needs:

| Aspect | Quick Start Path | Complete Development Path |
|--------|------------------|---------------------------|
| **Time** | 5-10 minutes | 30-60 minutes |
| **Best for** | Prototypes, demos, simple contracts | Production, complex systems, mainnet |
| **Testing** | Basic compilation check | Unit tests, integration tests, fork tests |
| **Scripts Used** | None (direct forge commands) | Direct forge commands with all options |
| **Documentation** | Minimal | Full reference guides |
| **Verification** | Automatic during deploy | Multiple methods with troubleshooting |
| **Agent-Friendly** | ✅ Optimized for speed | ⚠️ Comprehensive but slower |

### Path 1: Quick Start (Minimal Time - Agent-Friendly)
**Best for**: Fast deployment, simple contracts, prototyping
**Time**: 5-10 minutes
**What you get**: Contract deployed and verified on testnet

Skip to [Quick Start Path](#quick-start-path) below.

### Path 2: Complete Guide (Full Development Workflow)
**Best for**: Production contracts, complex systems, thorough testing
**Time**: 30-60 minutes
**What you get**: Fully tested, optimized, and production-ready deployment

Skip to [Complete Development Path](#complete-development-path) below.

---

## Quick Start Path

**Goal**: Deploy a contract to Polygon Amoy testnet in minimal steps.

### Prerequisites

- Foundry installed: `curl -L https://foundry.paradigm.xyz | bash && foundryup`
- Wallet with private key
- Polygonscan API key (get from https://polygonscan.com/myapikey)

### Step 1: Create Project (30 seconds)

```bash
forge init my-polygon-project
cd my-polygon-project
```

### Step 2: Configure Environment (1 minute)

Create `.env` file:
```bash
PRIVATE_KEY=your_private_key_without_0x_prefix
```

### Step 3: Get Testnet Tokens (2 minutes)

Visit: https://www.alchemy.com/faucets/polygon-amoy
- Paste your wallet address
- Claim 0.2-0.5 POL (no signup needed)

### Step 4: Deploy (1 minute)

```bash
# Deploy to Amoy testnet
forge script script/Counter.s.sol:CounterScript \
    --rpc-url https://rpc-amoy.polygon.technology \
    --private-key $PRIVATE_KEY \
    --broadcast
```

**Done!** Your contract is deployed and verified on Amoy testnet.

View at: `https://amoy.polygonscan.com/address/YOUR_CONTRACT_ADDRESS`

---

## Complete Development Path

**Goal**: Production-ready deployment with comprehensive testing and optimization.

### Phase 1: Setup (5 minutes)

1. **Install Foundry**:
```bash
curl -L https://foundry.paradigm.xyz | bash
foundryup
```

2. **Initialize Project**:
```bash
forge init my-polygon-project
cd my-polygon-project
```

3. **Configure for Polygon**:

Update `foundry.toml` with Polygon settings:
```toml
[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc_version = "0.8.24"
optimizer = true
optimizer_runs = 200

[rpc_endpoints]
amoy = "https://rpc-amoy.polygon.technology"
polygon = "https://polygon-rpc.com"

[etherscan]
amoy = { key = "${POLYGONSCAN_API_KEY}", url = "https://api-amoy.polygonscan.com/api" }
polygon = { key = "${POLYGONSCAN_API_KEY}", url = "https://api.polygonscan.com/api" }
```

4. **Setup Environment**:

Create `.env` file:
```bash
PRIVATE_KEY=your_private_key
WALLET_ADDRESS=0xYourAddress
POLYGONSCAN_API_KEY=your_api_key
```

### Phase 2: Write & Test Contracts (10-20 minutes)

1. **Write Contract** (or use `assets/sample-contracts/HelloWorld.sol` as template)

2. **Write Tests**:
```solidity
// test/MyContract.t.sol
import "forge-std/Test.sol";
import "../src/MyContract.sol";

contract MyContractTest is Test {
    MyContract public myContract;
    
    function setUp() public {
        myContract = new MyContract();
    }
    
    function testDeployment() public {
        assertEq(myContract.owner(), address(this));
    }
}
```

3. **Run Tests**:
```bash
forge test -vvv                    # Run tests
forge test --gas-report            # Check gas usage
forge coverage                     # Check coverage
```

4. **Fork Testing** (optional):
```bash
# Test against real Polygon state
forge test --fork-url https://polygon-rpc.com
```

See `references/testing-strategies.md` for comprehensive testing patterns.

### Phase 3: Get Testnet Tokens (2-5 minutes)

Visit one of these faucets:

**Alchemy** (recommended - no auth): https://www.alchemy.com/faucets/polygon-amoy
**QuickNode**: https://faucet.quicknode.com/polygon/amoy
**GetBlock**: https://getblock.io/faucet/matic-amoy/
**Chainlink**: https://faucets.chain.link/polygon-amoy
**LearnWeb3**: https://learnweb3.io/faucets/polygon_amoy/

### Phase 4: Deploy to Testnet (2-5 minutes)
```bash
forge script script/Deploy.s.sol \
    --rpc-url amoy \
    --private-key $PRIVATE_KEY \
    --broadcast \
    --verify \
    --etherscan-api-key $POLYGONSCAN_API_KEY
```

Create a deployment script in `script/Deploy.s.sol`:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import "forge-std/Script.sol";
import "../src/YourContract.sol";

contract DeployScript is Script {
    function run() external {
        uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");
        
        vm.startBroadcast(deployerPrivateKey);
        
        // Deploy your contract
        YourContract yourContract = new YourContract();
        
        vm.stopBroadcast();
        
        console.log("Contract deployed to:", address(yourContract));
    }
}
```

See `references/foundry-deployment.md` for advanced deployment patterns.

### Phase 5: Verify Contract (1-2 minutes)

If not verified during deployment:
```bash
forge verify-contract \
    CONTRACT_ADDRESS \
    src/MyContract.sol:MyContract \
    --chain-id 80002 \
    --etherscan-api-key $POLYGONSCAN_API_KEY
```

See `references/contract-verification.md` for troubleshooting verification issues.

### Phase 6: Test on Testnet (5-10 minutes)

1. **View on Explorer**: https://amoy.polygonscan.com/address/CONTRACT_ADDRESS
2. **Interact with Contract**: Use cast or web interface
3. **Test All Functions**: Verify behavior matches expectations
4. **Monitor Gas Costs**: Check if optimization needed

### Phase 7: Deploy to Mainnet (5 minutes)

**⚠️ IMPORTANT: Complete mainnet deployment checklist first!**

See [Mainnet Deployment Checklist](#mainnet-deployment-checklist) below.

```bash
forge script script/Deploy.s.sol \
    --rpc-url polygon \
    --private-key $PRIVATE_KEY \
    --broadcast \
    --verify \
    --etherscan-api-key $POLYGONSCAN_API_KEY
```

**End of Complete Development Path** ✅

## Network Configuration

### Amoy Testnet (Recommended for Testing)

| Property | Value |
|----------|-------|
| Network Name | Polygon Amoy |
| Chain ID | 80002 |
| Currency | POL |
| RPC URL | https://rpc-amoy.polygon.technology |
| WebSocket | wss://polygon-amoy.drpc.org |
| Explorer | https://amoy.polygonscan.com |
| Faucets | Multiple (see below) |

### Polygon Mainnet

| Property | Value |
|----------|-------|
| Network Name | Polygon |
| Chain ID | 137 |
| Currency | POL |
| RPC URL | https://polygon-rpc.com |
| WebSocket | wss://polygon.drpc.org |
| Explorer | https://polygonscan.com |

## Getting Testnet Tokens

Multiple faucets available for Amoy testnet POL tokens.

### Quick Access

Run the faucet helper script:
```bash
./scripts/get-testnet-tokens.sh
```

### Available Faucets

**Alchemy Faucet** (Recommended - No auth required)
- URL: https://www.alchemy.com/faucets/polygon-amoy
- Amount: 0.5 POL/day (with account), 0.2 POL/day (without)
- Requirements: None

**QuickNode Faucet**
- URL: https://faucet.quicknode.com/polygon/amoy
- Amount: 0.1 POL/day (2x with tweet)
- Requirements: Connect wallet

**GetBlock Faucet**
- URL: https://getblock.io/faucet/matic-amoy/
- Amount: 0.1 POL/day
- Requirements: Login

**Chainlink Faucet**
- URL: https://faucets.chain.link/polygon-amoy
- Amount: 0.1 POL/day
- Requirements: GitHub auth

**LearnWeb3 Faucet**
- URL: https://learnweb3.io/faucets/polygon_amoy/
- Amount: 0.1 POL/day
- Requirements: GitHub auth

**Tips:**
- Most faucets limit to 1 request per 24 hours
- If rate-limited, try a different faucet
- Some offer bonus tokens for tweeting

## Deployment Workflow

### Environment Setup

Create `.env` file (see `assets/sample-contracts/.env.example`):
```bash
PRIVATE_KEY=your_private_key_here
WALLET_ADDRESS=0xYourAddress
POLYGONSCAN_API_KEY=your_api_key_here
```

Add to `.gitignore`:
```
.env
broadcast/
deployments/
```

### Deploy to Testnet

**Option 1: Use helper script** (recommended)
```bash
./scripts/deploy-foundry.sh
```

**Option 2: Manual deployment**
```bash
forge script script/Deploy.s.sol \
    --rpc-url amoy \
    --private-key $PRIVATE_KEY \
    --broadcast \
    --verify
```

**Option 3: Deploy without verification**
```bash
forge script script/Deploy.s.sol \
    --rpc-url amoy \
    --private-key $PRIVATE_KEY \
    --broadcast
```

### Deploy to Mainnet

**⚠️ IMPORTANT: Test thoroughly on Amoy first!**

```bash
# Use deployment script and select mainnet option
./scripts/deploy-foundry.sh
```

For detailed deployment patterns, see `references/foundry-deployment.md`.

## Testing Strategies

### Local Testing

Write tests in `test/` directory:
```solidity
// test/MyContract.t.sol
import "forge-std/Test.sol";
import "../src/MyContract.sol";

contract MyContractTest is Test {
    MyContract public myContract;
    
    function setUp() public {
        myContract = new MyContract();
    }
    
    function testFunction() public {
        // Test logic
    }
}
```

Run tests:
```bash
forge test              # Run all tests
forge test -vvv         # Verbose output
forge test --gas-report # Show gas usage
```

### Fork Testing

Test against real Polygon state:
```bash
forge test --fork-url https://polygon-rpc.com
```

### Testnet Testing

Deploy to Amoy and test with real transactions. See `references/testing-strategies.md` for comprehensive testing patterns.

## Contract Verification

Verification makes your contract code public and trustworthy.

### During Deployment (Recommended)

```bash
forge script script/Deploy.s.sol \
    --rpc-url amoy \
    --private-key $PRIVATE_KEY \
    --broadcast \
    --verify \
    --etherscan-api-key $POLYGONSCAN_API_KEY
```

### After Deployment

**Option 1: Use helper script**
```bash
./scripts/verify-contract.sh
```

**Option 2: Manual verification**
```bash
forge verify-contract \
    CONTRACT_ADDRESS \
    src/MyContract.sol:MyContract \
    --chain-id 80002 \
    --etherscan-api-key $POLYGONSCAN_API_KEY \
    --verifier-url https://api-amoy.polygonscan.com/api
```

### With Constructor Arguments

```bash
forge verify-contract \
    CONTRACT_ADDRESS \
    src/MyContract.sol:MyContract \
    --chain-id 80002 \
    --etherscan-api-key $POLYGONSCAN_API_KEY \
    --constructor-args $(cast abi-encode "constructor(address,uint256)" 0x123... 1000)
```

For troubleshooting verification issues, see `references/contract-verification.md`.

## Common Workflows

### Which Path Should I Use?

**Use Quick Start Path when**:
- You need fast deployment (prototyping, demos)
- Contract is simple and low-risk
- You're an AI agent with limited t...