create-citrea-dapp

Scaffold a Citrea ₿app with one command — Hardhat or Foundry, secure key management, optional Next.js frontend.

npx @winsznx/create-citrea-dapp

What you get

A complete, ready-to-deploy Citrea project, pre-configured for mainnet and testnet.

• Choice of framework: Hardhat 3 (TypeScript + configVariable keystore) or Foundry (forge + cast wallet keystore)
• Secure key management by default: encrypted keystores, zero plaintext keys, zero .env files with secrets
• Optional Next.js frontend: App Router + wagmi v2 + RainbowKit + Tailwind, with Citrea mainnet & testnet chain configs
• Sample Counter contract: auditable in 30 seconds, full test suite, event emission, revert paths
• Pre-configured networks: chain IDs, RPCs, explorer URLs, bridge links — all ready to go
• forge-std auto-installed if Foundry is on PATH

Quick start

npx @winsznx/create-citrea-dapp

The CLI asks 4 questions:

1. Project name
2. Framework — Hardhat or Foundry
3. Include frontend? — Yes (Next.js + wagmi + RainbowKit) or No (contracts only)
4. Network — Both, Mainnet only, or Testnet only

Then it scaffolds the project, installs dependencies, and prints the exact commands to set up your wallet and deploy.

Why this exists

Citrea launched mainnet on January 27, 2026 — the first ZK rollup on Bitcoin with BitVM-based trust-minimized bridging. But the developer ecosystem has critical onboarding gaps:

• No official CLI scaffold. Base has create-base-app, Arbitrum has the Orbit CLI, Stacks has clarinet. Citrea has nothing.
• Docs show plaintext keys. The official Hardhat guide literally recommends accounts: ["YOUR_PRIVATE_KEY"] in config — the #1 pattern Cyfrin warns against.
• No Foundry support. Official docs only cover Hardhat and Remix.
• No frontend guide. No wagmi chain config published anywhere for Citrea.

This tool fixes all of it in one command.

Network reference

| | Mainnet | Testnet | |--|---------|---------| | Chain ID | 4114 | 5115 | | RPC | https://rpc.mainnet.citrea.xyz | https://rpc.testnet.citrea.xyz | | Explorer | https://explorer.mainnet.citrea.xyz | https://explorer.testnet.citrea.xyz | | Bridge | https://citrea.xyz/bridge | — | | Faucet | — | https://ethglobal.com/faucet/citrea-testnet-5115 | | Native token | cBTC (18 decimals) | cBTC (18 decimals) | | Block time | ~2s | ~2s |

Security

The templates this tool ships follow the Cyfrin 2025-2026 recommended practices:

• Hardhat 3 configVariable() — keys resolved at runtime from an encrypted keystore, never in config files
• Foundry cast wallet import + --account deployer — encrypted on disk, decrypted in memory only
• .gitignore pre-configured for .env, artifacts/, cache/, broadcast/, out/, node_modules/
• No --private-key flag in any example command
• README sections dedicated to "do not commit keys" at point of use

Requirements

• Node.js 18+
• npm, pnpm, yarn, or bun (auto-detected)
• Hardhat projects: that's it — dependencies install via npm
• Foundry projects: Foundry must be installed for forge install, forge build, and forge test

Useful links

• Citrea docs
• Citrea Discord
• Citrea on X
• Citrea Bridge · Testnet Faucet (ETHGlobal)
• Citrea Explorer (Blockscout)

Community tool — not officially affiliated with Citrea.

License

MIT © 2026 Tim (winsznx)