--- name: polygon-pos-dev description: Comprehensive guide for Polygon PoS blockchain development. Use when deploying smart contracts to Polygon, testing on Amoy testnet, getting test tokens from faucets, or verifying contracts on Polygonscan. Supports Foundry framework with deployment scripts and testing strategies. ---

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 (5-10 min)

For Production/Thorough Testing: Jump to Complete Development Path (30-60 min)

For Reference: See sections below for Network Configuration, Faucets, 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 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 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)

forge init my-polygon-project
cd my-polygon-project

Step 2: Configure Environment (1 minute)

Create .env file:

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)

# 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:

curl -L https://foundry.paradigm.xyz | bash
foundryup

1. Initialize Project:

forge init my-polygon-project
cd my-polygon-project

1. Configure for Polygon:

Update foundry.toml with Polygon settings:

[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" }

1. Setup Environment:

Create .env file:

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)

1. Write Tests:

// 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));
    }
}

1. Run Tests:

forge test -vvv                    # Run tests
forge test --gas-report            # Check gas usage
forge coverage                     # Check coverage

1. Fork Testing (optional):

# 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)

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:

// 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:

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 below.

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)

...