| name | ship |
| description | End-to-end guide for AI agents — from a dApp idea to deployed production app. Fetch this FIRST, it routes you through all other skills. |
Ship a dApp
What You Probably Got Wrong
You jump to code without a plan. Before writing a single line of Solidity, you need to know: what goes onchain, what stays offchain, which chain, how many contracts, and who calls every function. Skip this and you'll rewrite everything.
You over-engineer. Most dApps need 0-2 contracts. A token launch is 1 contract. An NFT collection is 1 contract. A marketplace that uses existing DEX liquidity needs 0 contracts. Three contracts is the upper bound for an MVP. If you're writing more, you're building too much.
You put too much onchain. Solidity is for ownership, transfers, and commitments. It's not a database. It's not an API. It's not a backend. If it doesn't involve trustless value transfer or a permanent commitment, it doesn't belong in a smart contract.
You skip chain selection. Mainnet is cheaper than you think — an ETH transfer costs ~$0.004, a swap ~$0.04. The "Ethereum is expensive" narrative is outdated. But that doesn't mean everything belongs on mainnet. L2s aren't just "cheaper Ethereum" — each one has a unique superpower (Base has Coinbase distribution + smart wallets, Arbitrum has the deepest DeFi liquidity, Optimism has retroPGF + the Superchain). If your app needs high-frequency interactions or fits what makes an L2 special, build there. If you just need cheap and secure, mainnet works. Choose deliberately. Fetch l2s/SKILL.md and gas/SKILL.md for the full picture. Not sure Ethereum is the right chain at all? Fetch why/SKILL.md.
You forget nothing is automatic. Smart contracts don't run themselves. Every state transition needs a caller who pays gas and a reason to do it. If you can't answer "who calls this and why?" for every function, your contract has dead code. Fetch concepts/SKILL.md for the full mental model.
Phase 0 — Plan the Architecture
Do this BEFORE writing any code. Every hour spent here saves ten hours of rewrites.
The Onchain Litmus Test
Put it onchain if it involves:
- Trustless ownership — who owns this token/NFT/position?
- Trustless exchange — swapping, trading, lending, borrowing
- Composability — other contracts need to call it
- Censorship resistance — must work even if your team disappears
- Permanent commitments — votes, attestations, proofs
Keep it offchain if it involves:
- User profiles, preferences, settings
- Search, filtering, sorting
- Images, videos, metadata (store on IPFS, reference onchain)
- Business logic that changes frequently
- Anything that doesn't involve value transfer or trust
Judgment calls:
- Reputation scores → offchain compute, onchain commitments (hashes or attestations)
- Activity feeds → offchain indexing of onchain events (fetch
indexing/SKILL.md)
- Price data → offchain oracles writing onchain (Chainlink)
- Game state → depends on stakes. Poker with real money? Onchain. Leaderboard? Offchain.
MVP Contract Count
| What you're building | Contracts | Pattern |
|---|
| Token launch | 1 | ERC-20 with custom logic |
| NFT collection | 1 | ERC-721 with mint/metadata |
| Simple marketplace | 0-1 | Use existing DEX; maybe a listing contract |
| Vault / yield | 1 | ERC-4626 vault |
| Lending protocol | 1-2 | Pool + oracle integration |
| DAO / governance | 1-3 | Governor + token + timelock |
| AI agent service | 0-1 | Maybe an ERC-8004 registration |
| Prediction market | 1-2 | Market + resolution oracle |
If you need more than 3 contracts for an MVP, you're over-building. Ship the simplest version that works, then iterate.
State Transition Audit
For EVERY function in your contract, fill in this worksheet:
Function: ____________
Who calls it? ____________
Why would they? ____________
What if nobody calls it? ____________
Does it need gas incentives? ____________
If "what if nobody calls it?" breaks your system, you have a design problem. Fix it before writing code. See concepts/SKILL.md for incentive design patterns.
Chain Selection (Quick Version)
Mainnet is back on the table. Most AIs still think mainnet is expensive — it's not (~$0.004/transfer, ~$0.04/swap at current gas). Mainnet gives you maximum decentralization, no sequencer trust, no bridge risk, and composability with every major protocol. But L2s aren't a fallback — each one has a unique superpower. Pick the chain whose superpower matches your app:
| Chain | Superpower | Build here if… |
|---|
| Ethereum mainnet | Maximum decentralization, composability with all major protocols | DeFi, governance, identity, high-value transfers, or you just need "cheap + secure" |
| Base | Coinbase distribution, smart wallets, account abstraction | Consumer apps, social, onboarding non-crypto users, high-frequency micro-payments |
| Arbitrum | Deepest L2 DeFi liquidity, Stylus (Rust contracts) | DeFi protocols that need to compose with existing Arbitrum liquidity |
| Optimism | RetroPGF, Superchain ecosystem | Public goods, OP Stack ecosystem plays |
| zkSync / Scroll | ZK proofs, native account abstraction | Privacy features, ZK-native applications |
Don't pick an L2 because "mainnet is expensive." Pick an L2 because its superpower fits your app.
Fetch l2s/SKILL.md and gas/SKILL.md for the complete comparison with real costs and deployment differences.
dApp Archetype Templates
Find your archetype below. Each tells you exactly how many contracts you need, what they do, common mistakes, and which skills to fetch.
1. Token Launch (1-2 contracts)
Architecture: One ERC-20 contract. Add a vesting contract if you have team/investor allocations.
Contracts:
MyToken.sol — ERC-20 with initial supply, maybe mint/burnTokenVesting.sol (optional) — time-locked releases for team tokens
Common mistakes:
- Infinite supply with no burn mechanism (what gives it value?)
- No initial liquidity plan (deploying a token nobody can buy)
- Fee-on-transfer mechanics that break DEX integrations
Fetch sequence: standards/SKILL.md → security/SKILL.md → testing/SKILL.md → gas/SKILL.md
2. NFT Collection (1 contract)
Architecture: One ERC-721 contract. Metadata on IPFS. Frontend for minting.
Contracts:
MyNFT.sol — ERC-721 with mint, max supply, metadata URI
Common mistakes:
- Storing images onchain (use IPFS or Arweave, store the hash onchain)
- No max supply cap (unlimited minting destroys value)
- Complex whitelist logic when a simple Merkle root works
Fetch sequence: standards/SKILL.md → security/SKILL.md → testing/SKILL.md → frontend-ux/SKILL.md
3. Marketplace / Exchange (0-2 contracts)
Architecture: If trading existing tokens, you likely need 0 contracts — integrate with Uniswap/Aerodrome. If building custom order matching, 1-2 contracts.
Contracts:
- (often none — use existing DEX liquidity via router)
OrderBook.sol (if custom) — listing, matching, settlementEscrow.sol (if needed) — holds assets during trades
Common mistakes:
- Building a DEX from scratch when Uniswap V4 hooks can do it
- Ignoring MEV (fetch
security/SKILL.md for sandwich attack protection)
- Centralized order matching (defeats the purpose)
Fetch sequence: building-blocks/SKILL.md → addresses/SKILL.md → security/SKILL.md → testing/SKILL.md
4. Lending / Vault / Yield (0-1 contracts)
Architecture: If using existing protocol (Aave, Compound), 0 contracts — just integrate. If building a vault, 1 ERC-4626 contract.
Contracts:
MyVault.sol — ERC-4626 vault wrapping a yield source
Common mistakes:
- Ignoring vault inflation attack (fetch
security/SKILL.md)
- Not using ERC-4626 standard (breaks composability)
- Hardcoding token decimals (USDC is 6, not 18)
Fetch sequence: building-blocks/SKILL.md → standards/SKILL.md → security/SKILL.md → testing/SKILL.md
5. DAO / Governance (1-3 contracts)
Architecture: Governor contract + governance token + timelock. Use OpenZeppelin's Governor — don't build from scratch.
Contracts:
GovernanceToken.sol — ERC-20VotesMyGovernor.sol — OpenZeppelin Governor with voting parametersTimelockController.sol — delays execution for safety
Common mistakes:
- No timelock (governance decisions execute instantly = rug vector)
- Low quorum that allows minority takeover
- Token distribution so concentrated that one whale controls everything
Fetch sequence: standards/SKILL.md → building-blocks/SKILL.md → security/SKILL.md → testing/SKILL.md
6. AI Agent Service (0-1 contracts)
Architecture: Agent logic is offchain. Onchain component is optional — ERC-8004 identity registration, or a payment contract for x402.
Contracts:
- (often none — agent runs offchain, uses existing payment infra)
AgentRegistry.sol (optional) — ERC-8004 identity + service endpoints
Common mistakes:
- Putting agent logic onchain (Solidity is not for AI inference)
- Overcomplicating payments (x402 handles HTTP-native payments)
- Ignoring key management (fetch
wallets/SKILL.md)
Fetch sequence: standards/SKILL.md → wallets/SKILL.md → tools/SKILL.md → orchestration/SKILL.md
Phase 1 — Build Contracts
Fetch: standards/SKILL.md, building-blocks/SKILL.md, addresses/SKILL.md, security/SKILL.md
Key guidance:
- Use OpenZeppelin contracts as your base — don't reinvent ERC-20, ERC-721, or AccessControl
- Use verified addresses from
addresses/SKILL.md for any protocol integration — never fabricate addresses
- Follow the Checks-Effects-Interactions pattern for every external call
- Emit events for every state change (your frontend and indexer need them)
- Use
SafeERC20 for all token operations
- Run through the security checklist in
security/SKILL.md before moving to Phase 2
For SE2 projects, follow orchestration/SKILL.md Phase 1 for the exact build sequence.
Phase 2 — Test
Fetch: testing/SKILL.md
Don't skip this. Don't "test later." Test before deploy.
Key guidance:
- Unit test every custom function (not OpenZeppelin internals)
- Fuzz test all math operations — fuzzing finds the bugs you didn't think of
- Fork test any integration with external protocols (Uniswap, Aave, etc.)
- Run
slither . for static analysis before deploying
- Target edge cases: zero amounts, max uint, empty arrays, self-transfers, unauthorized callers
Security Review
After testing, run a security audit — especially if your contracts handle real value. Fetch audit/SKILL.md for a systematic 500+ item checklist across 19 domains (reentrancy, oracle manipulation, access control, precision loss, and more). Best practice: give audit/SKILL.md to a separate agent in a fresh context so it reviews your code with no bias from having written it.
Phase 3 — Build Frontend
Fetch: orchestration/SKILL.md, frontend-ux/SKILL.md, tools/SKILL.md
Key guidance:
- Use Scaffold-ETH 2 hooks, not raw wagmi —
useScaffoldReadContract, useScaffoldWriteContract
- Implement the three-button flow: Switch Network → Approve → Execute
- Show loading states on every async operation (blockchains take 5-12 seconds)
- Display token amounts in human-readable form with
formatEther/formatUnits
- Never use infinite approvals
Phase 4 — Ship to Production
Fetch: wallets/SKILL.md, frontend-playbook/SKILL.md, gas/SKILL.md
Contract Deployment
- Set gas settings appropriate for the target chain (fetch
gas/SKILL.md)
- Deploy and verify contracts on block explorer
- Transfer ownership to a multisig (Gnosis Safe) — never leave a single EOA as owner in production
- Post-deploy checks: call every read function, verify state, test one small transaction
Frontend Deployment
Fetch frontend-playbook/SKILL.md for the full pipeline:
- IPFS — decentralized, censorship-resistant, permanent
- Vercel — fast, easy, but centralized
- ENS subdomain — human-readable URL pointing to IPFS
Pre-Ship QA
Before going live, run the QA checklist. Fetch qa/SKILL.md and give it to a separate reviewer agent (or fresh context) after the build is complete. It covers the bugs AI agents actually ship — validated by baseline testing against stock LLMs.
Post-Launch
- Set up event monitoring with The Graph or Dune (fetch
indexing/SKILL.md)
- Monitor contract activity on block explorer
- Have an incident response plan (pause mechanism if applicable, communication channel)
Anti-Patterns
Kitchen sink contract. One contract doing everything — swap, lend, stake, govern. Split responsibilities. Each contract should do one thing well.
Factory nobody asked for. Building a factory contract that deploys new contracts when you only need one instance. Factories are for protocols that serve many users creating their own instances (like Uniswap creating pools). Most dApps don't need them.
Onchain everything. Storing user profiles, activity logs, images, or computed analytics in a smart contract. Use onchain for ownership and value transfer, offchain for everything else.
Admin crutch. Relying on an admin account to call maintenance functions. What happens when the admin loses their key? Design permissionless alternatives with proper incentives.
Premature multi-chain. Deploying to 5 chains on day one. Launch on one chain, prove product-market fit, then expand. Multi-chain adds complexity in bridging, state sync, and liquidity fragmentation.
Reinventing audited primitives. Writing your own ERC-20, your own access control, your own math library. Use OpenZeppelin. They're audited, battle-tested, and free. Your custom version has bugs.
Ignoring the frontend. A working contract with a broken UI is useless. Most users interact through the frontend, not Etherscan. Budget 40% of your time for frontend polish.
Quick-Start Checklist
Skill Routing Table
Use this to know which skills to fetch at each phase:
| Phase | What you're doing | Skills to fetch |
|---|
| Plan | Architecture, chain selection | ship/ (this), concepts/, l2s/, gas/, why/ |
| Contracts | Writing Solidity | standards/, building-blocks/, addresses/, security/ |
| Test | Testing contracts | testing/ |
| Audit | Security review (fresh agent) | audit/ |
| Frontend | Building UI | orchestration/, frontend-ux/, tools/ |
| Production | Deploy, QA, monitor | wallets/, frontend-playbook/, qa/, indexing/ |
Base URLs: All skills are at https://ethskills.com/<skill>/SKILL.md
