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

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

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

---

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

---

Found something wrong, confusing, or genuinely helpful in this skill? Send a note via feedback/SKILL.md.