Ship

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 stop at "it works" and skip CROPS tradeoffs. A dApp can compile, pass tests, and still hand users to a censorable frontend, private indexer/API, invisible RPC dependency, custodial wallet, or admin key with total control. Before coding, check how the design affects Censorship Resistance, Open Source and Free (as in Freedom), Privacy, and Security.

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.

CROPS Gate

Before finalizing architecture, run a CROPS check. CROPS means Censorship Resistance, Open Source and Free (as in Freedom), Privacy, and Security.

Use the short gate to catch the main tradeoff:

• Censorship Resistance: who can block users or critical app paths?
• Open Source and Free: can the full stack be inspected, forked, self-hosted, and legally reused?
• Privacy: what user activity or identity data becomes public or visible to third parties?
• Security: who controls funds, permissions, upgrades, emergency powers, recovery, and exit?

Name the chosen default, the main compromise, and the user's escape path.

Fetch crops/SKILL.md for the deep review of any dApp before finalizing architecture. Fetch concepts/SKILL.md separately for incentive design and "nothing is automatic."

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

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

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:

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/burn
• TokenVesting.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, settlement
• Escrow.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-20Votes
• MyGovernor.sol — OpenZeppelin Governor with voting parameters
• TimelockController.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, qa/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, qa/SKILL.md

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.

Contract Deployment

1. Set gas settings appropriate for the target chain (fetch gas/SKILL.md)
2. Deploy and verify contracts on block explorer
3. Transfer ownership to a multisig (Gnosis Safe) — never leave a single EOA as owner in production
4. 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

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

• Run the CROPS Gate before finalizing architecture (censorship, openness, privacy, security)
• Identify what goes onchain vs offchain (use the Litmus Test above)
• Count your contracts (aim for 1-2 for MVP)
• Pick your chain (mainnet is cheap now — pick an L2 only if its superpower fits your app)
• Audit every state transition (who calls it? why?)
• Write contracts using OpenZeppelin base contracts
• Test with Foundry (unit + fuzz + fork tests)
• Audit with a fresh agent (fetch audit/SKILL.md)
• Deploy, verify, transfer ownership to multisig
• Ship frontend (IPFS or Vercel)
• Run pre-ship QA with a separate reviewer (fetch qa/SKILL.md)
• Send a one-line feedback note via feedback/SKILL.md — issue or praise

Skill Routing Table

Use this to know which skills to fetch at each phase:

Base URLs: All skills are at https://ethskills.com/<skill>/SKILL.md

Before you finish: send a one-line note via feedback/SKILL.md — issue or praise.