Polkadot AI Starter Kit

A production-ready Claude Code configuration for building on Polkadot Asset Hub EVM. Optimized for minimal code, pnpm monorepos, and AI-assisted development.

Target Chain: Paseo Asset Hub (testnet) → Polkadot Asset Hub (mainnet)

Philosophy: Least code wins. Exceptional organization. No bloat.

New Developer? Start Here

What You Can Build

Smart Contracts on Polkadot Asset Hub (Solidity, EVM-compatible)
Upgradeable Contracts using OpenZeppelin UUPS pattern
Decentralized Frontends hosted on Bulletin Chain with .dot domains
Full-Stack dApps with pnpm monorepo structure

Prerequisites

Tool	Install	Purpose
Claude Code	CLI tool	AI-assisted development
Foundry	`curl -L https://foundry.paradigm.xyz \| bash`	Solidity development
pnpm	`npm install -g pnpm`	Package management
Bun	`curl -fsSL https://bun.sh/install \| bash`	For dotNS CLI
Node.js 22+	`fnm install 22`	Required for dotns WebSocket
p1p CLI	See `cli-setup.md`	Secret management
dotns CLI	See `cli-setup.md`	Frontend deployment

Your Journey (Zero to Deployed)

1. Copy this kit to your project
       ↓
2. Write your smart contract
       ↓
3. Test locally with Anvil
       ↓
4. Deploy to Previewnet (no tokens needed!)
       ↓
5. Deploy to Paseo testnet
       ↓
6. Build frontend, deploy to Bulletin
       ↓
7. Register .dot domain
       ↓
8. Deploy to Polkadot mainnet

5-Minute Quick Start

# 1. Create and initialize Foundry project
mkdir my-polkadot-app && cd my-polkadot-app
forge init --no-git

# 2. Copy in starter kit files
git clone https://github.com/CoachCoe/AIStarterKit.git temp
cp -r temp/.claude temp/CLAUDE.md temp/.env.example temp/.gitignore .
rm -rf temp

# 3. Initialize git and install dependencies
git init
forge install OpenZeppelin/openzeppelin-contracts
forge install OpenZeppelin/openzeppelin-contracts-upgradeable

# 4. Start Claude Code
claude

# 5. Ask Claude to help you build!
# "Create a simple token contract and deploy to Previewnet"

Quick Start (Detailed)

1. Copy to Your Project

# Clone this repo
git clone https://github.com/your-org/polkadot-ai-starter-kit.git

# Copy to your project
cp -r AIStarterKit/.claude my-app2
cp AIStarterKit/CLAUDE.md my-app2

# Customize CLAUDE.md for your project

2. Initialize Foundry (for Smart Contracts)

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

# Initialize in your project
forge init --no-git --force

# Install OpenZeppelin
git init
forge install OpenZeppelin/openzeppelin-contracts
forge install OpenZeppelin/openzeppelin-contracts-upgradeable

3. Configure Environment

Option A: Using p1p (Recommended)

Store secrets in a decentralized locker instead of local files:

# Install p1p CLI (see cli-setup.md for full instructions)
cd polkadot-1p && pnpm install && pnpm -F @locker/cli build
cd packages/cli && npm link

# Sign in and create locker
p1p signin --mnemonic
p1p locker create -n "app3"

# Store secrets
p1p item create -l "app3" -t "contracts" \
  --category custom \
  --field private_key="0x..." \
  --field deployer_address="0x..."

# Copy .env.p1p.example to your project
cp AIStarterKit/.env.p1p.example .env.p1p
# Edit .env.p1p to use your locker name

Option B: Using .env (Traditional)

# Create .env (never commit this!)
cat > .env << 'EOF'
PRIVATE_KEY=0x...
ADMIN_ADDRESS=0x...
PASEO_RPC_URL=https://paseo-asset-hub-eth-rpc.polkadot.io
POLKADOT_RPC_URL=https://polkadot-asset-hub-eth-rpc.polkadot.io
EOF

What's Included

.claude/
├── AGENTS.md                      # Agent constraints (READ FIRST)
├── SOURCES.md                     # Reference repos for skill updates
├── settings.local.json            # Permissions
├── skills/
│   ├── cli-setup.md               # Install p1p + dotns CLIs
│   ├── locker-structure.md        # p1p secret organization
│   ├── end-to-end-deployment.md   # Full deployment guide
│   ├── code-quality.md            # Minimal code philosophy
│   ├── testing.md                 # Test patterns (TypeScript)
│   ├── security.md                # Security baseline
│   ├── previewnet.md              # Ephemeral dev network
│   ├── asset-hub-evm.md           # Polkadot Asset Hub config
│   ├── upgradeable-contracts.md   # OpenZeppelin UUPS patterns
│   ├── deploy-contracts/          # Contract deployment
│   ├── deploy-frontend/           # Bulletin + DotNS deployment
│   ├── p1p-secrets/               # Secret management
│   ├── foundry-testing/           # Solidity test patterns
│   ├── mutation-testing/          # Stryker mutation testing
│   └── skill-creator/             # Create new skills
└── commands/
    └── sync-skills.md             # Skill sync workflow

.env.p1p.example                   # Template for p1p secrets
CLAUDE.md                          # Project architecture template

Polkadot Network Configuration

Development Workflow

Local Anvil → Previewnet → Paseo → Mainnet
   (fast)    (no faucet)  (public)  (prod)

Network Endpoints

Network	RPC	Use Case
Previewnet	`https://previewnet.substrate.dev/eth-rpc`	Development (pre-funded)
Paseo	`https://paseo-asset-hub-eth-rpc.polkadot.io`	Integration testing
Polkadot	`https://polkadot-asset-hub-eth-rpc.polkadot.io`	Production

Previewnet (Recommended for Development)

No faucet needed - accounts are pre-funded
Ephemeral - reset anytime
Full stack - Asset Hub, People Chain, Bulletin, IPFS
Web UI: https://previewnet.substrate.dev

Get Paseo Testnet Tokens (for integration testing)

Get PAS from Polkadot Faucet
Bridge to Asset Hub Paseo

Skills Reference

Getting Started

Skill	Use When
`cli-setup.md`	Installing p1p and dotns CLIs
`locker-structure.md`	Setting up p1p secrets for your project
`end-to-end-deployment.md`	Full deployment walkthrough (zero to mainnet)

Polkadot-Specific

Skill	Use When
`previewnet.md`	Local development, no faucet needed
`asset-hub-evm.md`	Deploying to Asset Hub, network config
`upgradeable-contracts.md`	UUPS proxy patterns, storage layout
`deploy-contracts/`	Contract deployment workflow
`deploy-frontend/`	Bulletin Chain + DotNS (requires PoP setup)
`p1p-secrets/`	Secret management with p1p CLI
`host-api.md`	Triangle/Host API (early-stage, evolving)
`foundry-testing/`	Writing Solidity tests

General Development

Skill	Use When
`code-quality.md`	Writing any code, refactoring
`testing.md`	TypeScript testing, coverage
`security.md`	Input validation, security review
`mutation-testing/`	Evaluating test effectiveness

Customization

1. Update CLAUDE.md

Edit for your project:

Project name and description
Directory structure
Technology stack
Domain-specific terminology

2. Add Domain Skills

Create new skills for your project domains:

mkdir .claude/skills/my-skill

Use the skill-creator/ skill for guidance on structure.

3. Configure Permissions

Edit .claude/settings.local.json to auto-approve commands for your workflow.

Deployment Workflow

1. Local Development (Anvil)

# Start local chain
anvil --chain-id 420420421

# Deploy (new terminal)
forge script script/Deploy.s.sol --rpc-url local --broadcast

2. Previewnet (No Tokens Needed)

# Pre-funded accounts - no .env required
forge script script/Deploy.s.sol \
  --rpc-url https://previewnet.substrate.dev/eth-rpc \
  --broadcast \
  --slow \
  -vvvv

3. Paseo Testnet (Integration Testing)

# Option A: Using p1p (recommended)
p1p run --env-file .env.p1p -- forge script script/Deploy.s.sol \
  --rpc-url paseo \
  --broadcast \
  --slow \
  -vvvv

# Option B: Using .env
source .env
forge script script/Deploy.s.sol \
  --rpc-url paseo \
  --broadcast \
  --slow \
  -vvvv

4. Mainnet (Production)

# Option A: Using p1p (recommended)
p1p run --env-file .env.p1p -- forge script script/Deploy.s.sol \
  --rpc-url polkadot \
  --broadcast \
  --slow \
  -vvvv

# Option B: Using .env
source .env
forge script script/Deploy.s.sol \
  --rpc-url polkadot \
  --broadcast \
  --slow \
  -vvvv

Frontend Deployment (Bulletin + DotNS)

Deploy your frontend to Polkadot's decentralized infrastructure with a .dot domain.

First-Time Setup (Required)

cd dotns-sdk/packages/cli

# Get mnemonic from p1p (or use $DOTNS_MNEMONIC if set manually)
export DOTNS_MNEMONIC=$(p1p read "p1p://my-project/dotns/customFields.mnemonic" -n)

# 1. Set Personhood (REQUIRED - cannot skip)
bun run dotns-sdk/packages/cli/src/cli/index.ts pop set full -m "$DOTNS_MNEMONIC"

# 2. Authorize for Bulletin storage
bun run dotns-sdk/packages/cli/src/cli/index.ts bulletin authorize <your-address> -m "$DOTNS_MNEMONIC"

# 2b. If that doesn't work, use the *faucet* at the following site to authorize your account:
https://paritytech.github.io/polkadot-bulletin-chain/authorizations

Deploy Frontend

# Build (IMPORTANT ensure vite.config.ts has base: './')
pnpm build

# Get mnemonic from p1p
export DOTNS_MNEMONIC=$(p1p read "p1p://my-project/dotns/customFields.mnemonic" -n)

# 1. Upload to Bulletin
bun run dotns-sdk/packages/cli/src/cli/index.ts bulletin upload ./dist --parallel --print-contenthash
 --bulletin-rpc wss://paseo-bulletin-rpc.polkadot.io -m "$DOTNS_MNEMONIC"

# 2. Register your domain
bun run dotns-sdk/packages/cli/src/cli/index.ts register domain -n <domain-name> -m "$DOTNS_MNEMONIC"

# 3. Then set the content hash (using the CID from your bulletin upload)
bun run dotns-sdk/packages/cli/src/cli/index.ts content set <domain-name> <cid> -m "$DOTNS_MNEMONIC"

See deploy-frontend/ skill for full details and p1p-secrets/ for secret management.

Example Project Structure (pnpm Monorepo)

my-polkadot-project/
├── .claude/                  # AI configuration (from this kit)
├── packages/
│   ├── contracts/            # Foundry project
│   │   ├── contracts/        # Solidity source
│   │   ├── script/           # Deployment scripts
│   │   ├── test/             # Foundry tests
│   │   ├── lib/              # Dependencies
│   │   └── foundry.toml
│   └── web/                  # Frontend (optional)
│       ├── src/
│       ├── vite.config.ts    # Must have base: './'
│       └── package.json
├── pnpm-workspace.yaml       # Workspace config
├── package.json              # Root scripts
├── CLAUDE.md
└── .env                      # Never commit!

pnpm-workspace.yaml

packages:
  - 'packages/*'

Key Differences from Ethereum

Native Token: DOT (not ETH) - accessed via msg.value
Gas Prices: Generally lower than Ethereum mainnet
Block Time: ~6 seconds (faster than Ethereum)
Block Explorer: Use Subscan, not Etherscan
Contract Verification: Manual (no Etherscan API)

Keeping Skills Updated

Skills are based on patterns from reference repositories. See .claude/SOURCES.md for:

GitHub URLs for all reference repos
Which skills come from which repos
How to check for updates

# Quick update check
cd polkadot-refs
for repo in */; do git -C "$repo" pull; done

Resources

Previewnet - Ephemeral dev network (no faucet needed)
Asset Hub Documentation
Polkadot Faucet
Paseo Subscan
Foundry Book
OpenZeppelin Contracts

Reference Repositories

paritytech/polkadot-1p - p1p CLI, decentralized secret management
paritytech/dotns-sdk - DotNS CLI, Bulletin Chain uploads
paritytech/product-infrastructure - Previewnet, deployment
Agent-Skills-for-Context-Engineering - Skill patterns

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.claude		.claude
scripts		scripts
templates		templates
.env.example		.env.example
.env.p1p.example		.env.p1p.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Polkadot AI Starter Kit

New Developer? Start Here

What You Can Build

Prerequisites

Your Journey (Zero to Deployed)

5-Minute Quick Start

Quick Start (Detailed)

1. Copy to Your Project

2. Initialize Foundry (for Smart Contracts)

3. Configure Environment

What's Included

Polkadot Network Configuration

Development Workflow

Network Endpoints

Previewnet (Recommended for Development)

Get Paseo Testnet Tokens (for integration testing)

Skills Reference

Getting Started

Polkadot-Specific

General Development

Customization

1. Update CLAUDE.md

2. Add Domain Skills

3. Configure Permissions

Deployment Workflow

1. Local Development (Anvil)

2. Previewnet (No Tokens Needed)

3. Paseo Testnet (Integration Testing)

4. Mainnet (Production)

Frontend Deployment (Bulletin + DotNS)

First-Time Setup (Required)

Deploy Frontend

Example Project Structure (pnpm Monorepo)

pnpm-workspace.yaml

Key Differences from Ethereum

Keeping Skills Updated

Resources

Reference Repositories

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages