Scaffold-HBAR (Hedera)

A Hedera-ready monorepo for building dApps with Next.js, Hardhat or Foundry, and Hedera networks (testnet, mainnet, local fork). Generated by create-scaffold-hbar or used as the production template when you run npx create-scaffold-hbar@latest.

Prerequisites

• Node.js >= 20.18.3
• Yarn — required (this project uses Yarn workspaces; npm and pnpm are not supported)
  Install via Corepack: corepack enable && corepack prepare yarn@stable --activate
• Git
• If using Foundry: Foundry (forge, cast, anvil)

Quick start

1. Create a new project (recommended):

 npx create-scaffold-hbar@latest

Follow the prompts to pick a template (blank, payments-scheduler, or hedera-demo), frontend, Solidity framework (Hardhat or Foundry), and network. 2. Or use this repo as the template (e.g. after cloning or downloading):

 yarn install
 yarn hardhat:chain    # terminal 1: start local Hedera-forked node
 yarn hardhat:deploy --network localhost   # terminal 2: deploy to the running fork (8545)
 yarn next:start    # terminal 3: start Next.js app

Open http://localhost:3000 and use the Debug Contracts page to interact with your contracts.

Available templates (create-scaffold-hbar)

The create-scaffold-hbar CLI resolves templates from this repository's template branches. Current built-in templates are:

Template	Branch	What you get
blank	templates/blank-template	Minimal baseline scaffold with no opinionated app features; ideal starting point for custom products.
payments-scheduler	templates/payments-scheduler	Starter for scheduled-payment style flows, with app and contract structure tailored for recurring/payment orchestration patterns using HSS.
hedera-demo	templates/hedera-demo	Hedera demo/proofwall-style starter focused on showcasing Hedera integrations with Hedera Services[HTS, HCS, MirroNode] and end-to-end demo UX.

Template selection examples

# Interactive
npx create-scaffold-hbar@latest

# Explicit built-in template key
npx create-scaffold-hbar@latest --template blank
npx create-scaffold-hbar@latest --template payments-scheduler
npx create-scaffold-hbar@latest --template hedera-demo

Deploy and verify on Hedera

To deploy or verify on Hedera testnet, you need a deployer account with testnet HBAR. Generate or import one with your selected framework command, such as yarn hardhat:account:generate, yarn hardhat:account:import, yarn foundry:account:generate, or yarn foundry:account:import, then fund it using the Hedera Portal faucet. Without funds, deploy and verify will fail with "Sender account not found".

Hardhat

• Deploy to Hedera testnet:
  From repo root (you will be prompted to decrypt your deployer key):

  yarn hardhat:deploy --network hederaTestnet

  Or use yarn hardhat:deploy --network hedera_testnet (same network, alternate name).
• Verify on Hashscan: After deploy, run (no extra arguments needed; uses last deployment):

yarn hardhat:verify:testnet   # chain 296
yarn hardhat:verify:mainnet   # chain 295

Foundry

• Deploy to Hedera testnet:
  Use a keystore with testnet HBAR (fund via Hedera Portal faucet). From repo root or packages/foundry:

  yarn foundry:deploy --network hedera_testnet

  Or from packages/foundry: make deploy with RPC_URL and account set via env / Makefile.
• Verify on Hashscan:
  After deploy, run (no extra arguments needed):

  yarn foundry:verify:testnet   # 296
  yarn foundry:verify:mainnet   # 295

Verified contracts appear on Hashscan (testnet) or Hashscan (mainnet).

Local testing with Hedera forking

You can test contracts and the app locally against a Hedera-forked execution environment before deploying to public networks.

Hardhat local workflow

Details and rationale (including localhost vs default hardhat network) are in packages/hardhat/README.md.

1. Start a local chain (Hedera forking enabled in scripts):

yarn hardhat:chain

2. Deploy contracts to the running node on http://127.0.0.1:8545:

yarn hardhat:deploy --network localhost

yarn hardhat:deploy without --network localhost targets the in-process hardhat network, not this long-running fork.

3. Run Hardhat tests:

yarn hardhat:test

4. Run the app against local contracts:

yarn next:start

Foundry local workflow

This path uses Foundry (packages/foundry) while sharing the same local JSON-RPC started by yarn hardhat:chain from the repo root. Details: packages/foundry/README.md.

1. Start the local chain first:

yarn hardhat:chain

2. Run Foundry tests against that JSON-RPC:

yarn foundry:test:local

3. Optionally run Foundry tests directly against Hedera RPC endpoints (no local node):

yarn foundry:test:testnet
yarn foundry:test:mainnet

This keeps local testing on a single path and avoids chain id drift between different local node commands.

Project layout

• packages/hardhat — Hardhat config, contracts, deploy/ scripts, tests, verifyHedera.js
• packages/foundry — Forge config, contracts, script/ deploy scripts, tests, scripts-js/verifyHedera.js
• packages/nextjs — Next.js app, RainbowKit, wagmi, scaffold config

Network and RPC URLs are in packages/hardhat/hardhat.config.ts or packages/foundry/foundry.toml.

Links

• Hedera Documentation
• Hashscan — block explorer
• Hedera Token Service (HTS)
• create-scaffold-hbar — CLI to scaffold Hedera dApps