diff --git a/docs.json b/docs.json index 392d16b0..85ce8a9d 100644 --- a/docs.json +++ b/docs.json @@ -2830,6 +2830,13 @@ "group": "Developer Tools", "pages": [ "solutions/tools/playground", + { + "group": "Scaffold HBAR", + "pages": [ + "solutions/tools/scaffold-hbar/index", + "solutions/tools/scaffold-hbar/scaffold-ui" + ] + }, "solutions/tools/code-repo", "solutions/tools/custodians-library", "solutions/tools/custodians-library-usage", diff --git a/solutions/tools/scaffold-hbar/index.mdx b/solutions/tools/scaffold-hbar/index.mdx new file mode 100644 index 00000000..cd1b4491 --- /dev/null +++ b/solutions/tools/scaffold-hbar/index.mdx @@ -0,0 +1,417 @@ +--- +title: "Scaffold HBAR" +description: "Scaffold Hedera dApps from the command line. Pick a template, frontend, and Solidity framework—then get a runnable project in one step." +--- + +## What is Scaffold HBAR? + +Scaffold HBAR is an interactive CLI tool (similar to `create-next-app` or `create-react-app`) for the Hedera ecosystem. It generates monorepo projects with: + +- **Smart contracts** (Hardhat or Foundry) +- **Frontend** (Next.js App Router with RainbowKit, wagmi, and viem) +- **Hedera network configuration** (Testnet or Mainnet with Hashio RPC) +- **Pre-built UI components** for wallet connection, address display, and HBAR input + + + + Create your first Hedera dApp in under a minute + + + Browse pre-built templates for common use cases + + + Shared components, hooks, and MCP server for AI agents + + + Source code and contributing guide + + + +--- + +## Quick Start + +### Prerequisites + +Before using Scaffold HBAR, ensure you have: + +- **Node.js** ≥ 20.18.3 — [nodejs.org](https://nodejs.org/) +- **Git** with `user.name` and `user.email` configured — [git-scm.com](https://git-scm.com/) +- **Yarn** (scaffolded projects use Yarn workspaces): + ```bash + corepack enable && corepack prepare yarn@stable --activate + ``` + +If you choose **Foundry** as the Solidity framework: + +```bash +curl -L https://foundry.paradigm.xyz | bash +foundryup +``` + +### Create a New Project + +Run the CLI with npx: + +```bash +npx create-scaffold-hbar@latest +``` + +You'll be prompted to select: + +1. **Project name** — Directory name for your new project +2. **Template** — Starting point for your dApp (blank, HTS token, NFT, etc.) +3. **Frontend** — `nextjs-app` or `none` (contracts only) +4. **Solidity framework** — `foundry`, `hardhat`, or `none` +5. **Network** — `testnet` or `mainnet` + + + +For CI pipelines or scripting, use flags to skip prompts: + +```bash +# Accept all defaults (blank template, Foundry, testnet) +npx create-scaffold-hbar@latest --yes + +# Full customization +npx create-scaffold-hbar@latest my-scheduler-app \ + --template payments-scheduler \ + --frontend nextjs-app \ + --solidity-framework foundry \ + --network testnet +``` + +| Flag | Description | +|------|-------------| +| `-y, --yes` | Use defaults for all prompts | +| `-t, --template ` | Template key (see [Available Templates](#available-templates)) | +| `-f, --frontend ` | `nextjs-app` or `none` | +| `-s, --solidity-framework ` | `foundry`, `hardhat`, or `none` | +| `--network ` | `testnet` or `mainnet` | +| `--skip-install` | Don't run `yarn install` after scaffolding | + + + +### Start Development + +After scaffolding, start the development servers: + + + +```bash +cd my-hedera-dapp + +# Terminal 1: Start local chain +yarn foundry:chain + +# Terminal 2: Deploy contracts +yarn foundry:deploy + +# Terminal 3: Start frontend +yarn next:start +``` + + +```bash +cd my-hedera-dapp + +# Terminal 1: Start local chain +yarn hardhat:chain + +# Terminal 2: Deploy contracts +yarn hardhat:deploy + +# Terminal 3: Start frontend +yarn next:start +``` + + + +Open [http://localhost:3000](http://localhost:3000) to see your dApp. + +--- + +## Available Templates + +Scaffold HBAR includes starter templates for common Hedera use cases. The CLI fetches templates dynamically from `templates/*` branches: + +| Template | CLI Value | Description | Framework | +|----------|-----------|-------------|-----------| +| **Blank Starter** | `blank` | Minimal baseline scaffold with no opinionated features—ideal starting point for custom dApps | Foundry or Hardhat | +| **Hedera Native** | `hedera-demo` | Demo focused on Hedera-native services (HTS, HCS, Mirror Node) with end-to-end UI—no Solidity contracts | Next.js only | +| **Onchain Cron Job** | `payments-scheduler` | Scheduled payments using Hedera Schedule Service (HSS) with a ScheduledVault pattern and pluggable strategies (e.g., DCA) | Foundry | +| **Bridge** | `bridge` | Cross-chain bridge connecting Ethereum Sepolia and Hedera Testnet with Axelar, CCIP, or LayerZero providers | Foundry | +| **Oracles** | `oracles` | Provider-agnostic oracle pattern with adapters for Chainlink, Supra, and Pyth price feeds | Foundry | +| **Tokenize Subscriptions** | `tokenise-subscriptions` | SubRent NFT marketplace—tokenize subscriptions (gym, WiFi, streaming) as HTS NFTs with rental and sales | Hardhat | +| **x402 Pay-Per-Use** | `x402-pay-per-use` | Pay-per-download file marketplace using the x402 protocol with HashPack payments and MinIO storage | Hardhat | + + +**Template selection:** +```bash +# Interactive mode shows all available templates +npx create-scaffold-hbar@latest + +# Or specify directly +npx create-scaffold-hbar@latest --template payments-scheduler +npx create-scaffold-hbar@latest --template hedera-demo +``` + + + +Templates are maintained in the [scaffold-hbar repository](https://github.com/buidler-labs/scaffold-hbar) as separate branches (`templates/*`). The CLI fetches templates at runtime, so you always get the latest version. + + +--- + +## External Templates + +Beyond the built-in templates, Scaffold HBAR supports **external templates** from any GitHub repository. This allows the community to create and share specialized templates. + +### Using External Templates + +Specify an external template using the `owner/repo` or `owner/repo#branch` format: + +```bash +# Use the main branch +npx create-scaffold-hbar@latest --template hedera-dev/template-hedera-lz-app + +# Use a specific branch +npx create-scaffold-hbar@latest --template hedera-dev/template-hedera-lz-app#main +``` + +The CLI fetches the template via [giget](https://github.com/unjs/giget), so any public GitHub repository can serve as a template. + +### Featured: LayerZero on Hedera Template + +The [template-hedera-lz-app](https://github.com/hedera-dev/template-hedera-lz-app) is a comprehensive tutorial template for building cross-chain applications using LayerZero V2 on Hedera. + +```bash +npx create-scaffold-hbar@latest my-lz-app --template hedera-dev/template-hedera-lz-app +``` + +**What you'll build:** + +| Chapter | Topic | Description | +|---------|-------|-------------| +| 1 | Cross-Chain OFT | Send native ETH from Base Sepolia to Hedera as an HTS-wrapped token | +| 2 | Cross-Chain Vault | ERC4626 vault with omnichain deposits and share token redemptions | +| 3 | ETF Strategy | Auto-investing vault that swaps deposits into a 50/50 HBAR + HUSTLERS basket via SaucerSwap | + +**Architecture:** + +``` +BASE (Spoke) HEDERA (Hub) +┌─────────────────┐ ┌─────────────────────────┐ +│ MyNativeOFT │◄──── LayerZero ──►│ MyHTSConnector │ +│ Adapter │ │ (wraps ETH as HTS) │ +└─────────────────┘ └─────────────────────────┘ +``` + + +This template uses **pnpm** (not Yarn) and requires testnet funds on both Base Sepolia and Hedera Testnet. See the [template README](https://github.com/hedera-dev/template-hedera-lz-app) for complete setup instructions. + + +### Creating Your Own Template + +Any GitHub repository can be used as an external template. To make your template compatible: + +1. **Structure** — Use a monorepo layout with `packages/` for contracts and frontend +2. **Manifest** (optional) — Add a `template.json` to specify capabilities: + +```json +{ + "create-scaffold-hbar": { + "capabilities": { + "frontend": ["nextjs-app"], + "solidityFramework": ["hardhat"], + "packageManager": ["pnpm", "yarn"] + }, + "defaults": { + "frontend": "nextjs-app", + "solidityFramework": "hardhat" + } + } +} +``` + +3. **Share** — Users can scaffold with `npx create-scaffold-hbar@latest --template your-org/your-repo` + +--- + +## Project Structure + +A scaffolded project has this structure: + +``` +my-hedera-dapp/ +├── packages/ +│ ├── foundry/ # OR hardhat/ (Solidity contracts) +│ │ ├── contracts/ # Smart contract source files +│ │ ├── script/ # Deployment scripts (Foundry) +│ │ ├── deploy/ # Deployment scripts (Hardhat) +│ │ └── test/ # Contract tests +│ │ +│ └── nextjs/ # Frontend application +│ ├── app/ # Next.js App Router pages +│ ├── components/ # React components +│ ├── contracts/ # Auto-generated contract ABIs +│ ├── hooks/ # Custom React hooks +│ └── services/ # Web3 service utilities +│ +├── package.json # Workspace configuration +└── yarn.lock +``` + +### Key Features + +**Auto-generated Contract Types** + +After deploying contracts, ABIs are automatically generated to `packages/nextjs/contracts/deployedContracts.ts`. This provides full TypeScript support when interacting with your contracts. + +**Pre-built Hooks** + +The frontend includes scaffold hooks for common operations: + +```typescript +import { useScaffoldReadContract, useScaffoldWriteContract } from "~~/hooks/scaffold-hbar"; + +// Read contract state +const { data: greeting } = useScaffoldReadContract({ + contractName: "YourContract", + functionName: "greeting", +}); + +// Write to contract +const { writeContractAsync } = useScaffoldWriteContract({ + contractName: "YourContract", +}); + +await writeContractAsync({ + functionName: "setGreeting", + args: ["Hello, Hedera!"], +}); +``` + +**Hedera-Optimized Configuration** + +Projects come pre-configured with: +- Hashio JSON-RPC endpoints for Testnet and Mainnet +- Mirror Node API integration +- Proper gas estimation for Hedera's fee model +- RainbowKit with Hedera wallet support + +--- + +## Common Commands + +| Command | Description | +|---------|-------------| +| `yarn foundry:chain` / `yarn hardhat:chain` | Start local development chain | +| `yarn foundry:deploy` / `yarn hardhat:deploy` | Deploy contracts | +| `yarn next:start` | Start Next.js frontend | +| `yarn next:build` | Build frontend for production | +| `yarn lint` | Run linters on all packages | +| `yarn format` | Format code with Prettier | +| `yarn foundry:test` / `yarn hardhat:test` | Run contract tests | + +--- + +## Deploying to Testnet + +1. **Get testnet HBAR** from the [Hedera Portal Faucet](https://portal.hedera.com/faucet) + +2. **Configure your account**: + + + +```bash +# Generate a new account +yarn foundry:account:generate + +# Or import an existing key +yarn foundry:account:import +``` + +Set your account alias in `packages/foundry/.env`: +```bash +ACCOUNT=your_keystore_alias +``` + + +```bash +# Generate a new account +yarn hardhat:account:generate + +# Or import an existing key +yarn hardhat:account:import +``` + +Set your private key in `packages/hardhat/.env`: +```bash +DEPLOYER_PRIVATE_KEY=your_private_key +``` + + + +3. **Deploy to testnet**: + +```bash +yarn foundry:deploy --network hedera_testnet +# or +yarn hardhat:deploy --network hederaTestnet +``` + +4. **Verify contracts** (optional): + +```bash +yarn foundry:verify:testnet 0xYourContractAddress contracts/YourContract.sol:YourContract +# or +yarn hardhat:verify:testnet +``` + +--- + +## Hedera Skills (AI-Assisted Development) + +All scaffolded projects include [Hedera Skills](https://github.com/hedera-dev/hedera-skills) by default—a collection of AI coding assistant skills that help you build on Hedera faster. + +**What's included:** + +- **Agent prompts** — Pre-configured prompts for Cursor, Claude Code, and other AI assistants +- **Code generation skills** — Hedera-specific patterns for HTS, HCS, smart contracts, and more +- **Documentation context** — Embedded Hedera docs for accurate AI responses + +Skills are installed automatically during scaffolding via: + +```bash +npx skills add hedera-dev/hedera-skills --all +``` + + +To skip Hedera Skills installation (e.g., for CI pipelines), use: +```bash +npx create-scaffold-hbar@latest --yes --skip-hedera-skills +``` + + +--- + +## Ecosystem + + + + Shared React components and hooks for Hedera dApps, plus an MCP server for AI-assisted development + + + AI coding assistant skills for Hedera development + + + +--- + +## Resources + +- [GitHub: create-scaffold-hbar](https://github.com/hedera-dev/create-scaffold-hbar) — CLI source and issues +- [GitHub: scaffold-hbar](https://github.com/hedera-dev/scaffold-hbar) — Templates repository +- [Hedera Portal](https://portal.hedera.com/) — Account creation and testnet faucet +- [HashScan](https://hashscan.io/) — Block explorer for Hedera diff --git a/solutions/tools/scaffold-hbar/scaffold-ui.mdx b/solutions/tools/scaffold-hbar/scaffold-ui.mdx new file mode 100644 index 00000000..708182d4 --- /dev/null +++ b/solutions/tools/scaffold-hbar/scaffold-ui.mdx @@ -0,0 +1,423 @@ +--- +title: "Scaffold UI" +description: "Shared React components, hooks, and an MCP server for building Hedera dApps with AI-assisted development." +--- + +## Overview + +**Scaffold UI** (`@scaffold-hbar-ui/*`) is a collection of React packages designed for Hedera and EVM-compatible dApps: + +| Package | Description | +|---------|-------------| +| `@scaffold-hbar-ui/components` | Address display, balance, HBAR input components | +| `@scaffold-hbar-ui/hooks` | Hedera account resolution, address formatting hooks | +| `@scaffold-hbar-ui/debug-contracts` | Contract debugging UI with multiplier inputs | +| `@scaffold-hbar-ui/mcp-server` | MCP server for AI-assisted development | + + + + Pre-built UI for addresses, balances, and inputs + + + Hedera account resolution and address utilities + + + AI agent integration for accurate code generation + + + Source code and examples + + + +--- + +## Installation + +Install the packages you need: + +```bash +# Core packages (most projects need both) +npm install @scaffold-hbar-ui/components @scaffold-hbar-ui/hooks + +# Optional: Contract debugging UI +npm install @scaffold-hbar-ui/debug-contracts +``` + +### Peer Dependencies + +Ensure you have these peer dependencies: + +```bash +npm install react viem wagmi @tanstack/react-query +``` + +### Styles + +Import the component styles in your app's root layout: + +```tsx +import "@scaffold-hbar-ui/components/styles.css"; + +// If using debug-contracts +import "@scaffold-hbar-ui/debug-contracts/styles.css"; +``` + +--- + +## Components + +### Address + +Displays an EVM address with a blockie avatar, copy button, and block explorer link. Automatically uses HashScan for Hedera chains. + +```tsx +import { Address } from "@scaffold-hbar-ui/components"; +import { hederaTestnet } from "viem/chains"; + +
+``` + +| Prop | Type | Description | +|------|------|-------------| +| `address` | `string` | The EVM address to display | +| `chain` | `Chain` | Viem chain for explorer links (uses HashScan for Hedera) | +| `format` | `"short"` \| `"long"` | Address display format | +| `size` | `"xs"` \| `"sm"` \| `"base"` \| `"lg"` \| `"xl"` \| `"2xl"` \| `"3xl"` | Component size | +| `disableAddressLink` | `boolean` | Disable the explorer link | + +### Balance + +Shows native token balance with automatic USD conversion. Uses HBAR pricing for Hedera chains. + +```tsx +import { Balance } from "@scaffold-hbar-ui/components"; +import { hederaTestnet } from "viem/chains"; + + +``` + +### HbarInput + +Number input optimized for HBAR amounts with tinybar conversion. + +```tsx +import { HbarInput } from "@scaffold-hbar-ui/components"; + +const [amount, setAmount] = useState(""); + + +``` + +### HederaAddressInput + +Input field that accepts both Hedera native addresses (`0.0.12345`) and EVM addresses (`0x...`), with validation and resolution. + +```tsx +import { HederaAddressInput } from "@scaffold-hbar-ui/components"; +import { hederaTestnet } from "viem/chains"; + +const [address, setAddress] = useState(""); + + +``` + +--- + +## Hooks + +### useAddress + +Formats EVM addresses with checksumming, short form display, and block explorer URLs. + +```tsx +import { useAddress } from "@scaffold-hbar-ui/hooks"; +import { hederaTestnet } from "viem/chains"; + +function AddressDisplay({ address }) { + const { + checkSumAddress, + shortAddress, + blockExplorerAddressLink, + blockieUrl, + isValidAddress, + } = useAddress({ address, chain: hederaTestnet }); + + return ( +
+ + {shortAddress} + + View on HashScan + +
+ ); +} +``` + +### useHederaAccountId + +Resolves a Hedera account ID (`0.0.12345`) from an EVM address by querying the Mirror Node. + +```tsx +import { useHederaAccountId } from "@scaffold-hbar-ui/hooks"; +import { hederaTestnet } from "viem/chains"; + +function AccountInfo({ evmAddress }) { + const { accountId, isLoading, status } = useHederaAccountId( + evmAddress, + hederaTestnet.id + ); + + if (isLoading) return Loading...; + + return Account: {accountId}; +} +``` + +### useHederaEvmAddress + +Resolves an EVM address from a Hedera native account ID. + +```tsx +import { useHederaEvmAddress } from "@scaffold-hbar-ui/hooks"; +import { hederaTestnet } from "viem/chains"; + +function EvmAddressDisplay({ accountId }) { + const { evmAddress, isLoading } = useHederaEvmAddress( + accountId, + hederaTestnet.id + ); + + return EVM: {evmAddress}; +} +``` + +### useHederaAddressInput + +Validates and resolves Hedera address input (either format). Powers the `HederaAddressInput` component. + +```tsx +import { useHederaAddressInput } from "@scaffold-hbar-ui/hooks"; + +const { + evmAddress, // Resolved EVM address (checksummed) + accountIdFromEvm, // Resolved account ID (if input was EVM) + error, // Validation error message + warning, // Warning message + isResolving, // Loading state +} = useHederaAddressInput({ + value: inputValue, + chainId: 296, // Hedera Testnet + debounceDelay: 400, +}); +``` + +### Mirror Node Resolution + +All Hedera account resolution uses the Mirror Node API directly: + +| Chain | Mirror Node URL | +|-------|----------------| +| Mainnet (295) | `https://mainnet.mirrornode.hedera.com` | +| Testnet (296) | `https://testnet.mirrornode.hedera.com` | + +--- + +## Debug Contracts + +The `@scaffold-hbar-ui/debug-contracts` package provides a contract interaction UI for development. + +### Contract Component + +Renders a form for interacting with deployed contracts—call read functions, execute writes, and view events. + +```tsx +import { Contract } from "@scaffold-hbar-ui/debug-contracts"; +import "@scaffold-hbar-ui/debug-contracts/styles.css"; +import { hederaTestnet } from "viem/chains"; + +const deployedContract = { + address: "0xYourContractAddress", + abi: [/* your ABI */], +}; + + +``` + +### IntegerInput + +Integer input with **decimal multiplier buttons** for converting human-readable amounts to chain units: + +- **×1e8** — Multiplies by 10^8 (tinybars → HBAR) +- **×1e18** — Multiplies by 10^18 (wei → ETH) + +```tsx +import { IntegerInput } from "@scaffold-hbar-ui/debug-contracts"; + +const [value, setValue] = useState(""); + + +``` + +--- + +## MCP Server for AI Agents + +The `@scaffold-hbar-ui/mcp-server` package exposes Scaffold UI documentation to AI coding assistants via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). + +### Why Use It? + +When building Hedera dApps with AI assistance (Cursor, Claude Desktop, etc.), the MCP server provides: + +- **Accurate imports** — AI knows the exact package exports +- **Correct props** — TypeScript signatures for all components and hooks +- **Working examples** — Real code snippets from the example app +- **Hedera-specific guidance** — Mirror Node URLs, chain IDs, HBAR formatting + +### Quick Setup + + + + +Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): + +```json +{ + "mcpServers": { + "scaffold-hbar-ui": { + "command": "npx", + "args": ["-y", "@scaffold-hbar-ui/mcp-server"] + } + } +} +``` + +Restart Cursor, then verify the server appears in Settings → MCP Servers. + + + + +Open Settings → Developer → Edit Config, then add: + +```json +{ + "mcpServers": { + "scaffold-hbar-ui": { + "command": "npx", + "args": ["-y", "@scaffold-hbar-ui/mcp-server"] + } + } +} +``` + +Restart Claude Desktop. + + + + +For local development (pointing at the cloned repo): + +```json +{ + "mcpServers": { + "scaffold-hbar-ui": { + "command": "node", + "args": ["/path/to/scaffold-hbar-ui/packages/mcp-server/dist/esm/bin/scaffold-hbar-ui-mcp.js"] + } + } +} +``` + +Build first with `pnpm build` in the mcp-server package. + + + + +### Available Tools + +The MCP server exposes these tools to AI agents: + +| Tool | Description | +|------|-------------| +| `search_components` | Find components by keyword | +| `search_hooks` | Find hooks by keyword | +| `get_component_props` | Get TypeScript props for a component | +| `get_hook_signature` | Get hook signature and return type | +| `get_component_example` | Get usage example for a component | +| `get_hook_example` | Get usage example for a hook | +| `get_installation_guide` | Get installation instructions | +| `get_theming_guide` | Get theming and styling info | + +### Example Prompts + +After configuring the MCP server, try these prompts: + +- *"Show me how to use the HederaAddressInput component with validation"* +- *"What hooks are available for Hedera account resolution?"* +- *"Get the props for the Address component"* + +### HTTP Mode (Remote Agents) + +For remote AI agents or server-side integrations: + +```bash +# Start HTTP server +PORT=3100 node ./dist/esm/bin/scaffold-hbar-ui-mcp.js --http + +# With authentication +SCAFFOLD_HBAR_UI_MCP_KEY=your-secret PORT=3100 node ./dist/esm/bin/scaffold-hbar-ui-mcp.js --http +``` + +Connect with: + +```json +{ + "mcpServers": { + "scaffold-hbar-ui": { + "url": "http://localhost:3100/mcp" + } + } +} +``` + +### Testing with MCP Inspector + +Debug the server visually with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector): + +```bash +npx @modelcontextprotocol/inspector npx @scaffold-hbar-ui/mcp-server +``` + +Open `http://localhost:6274` to browse tools, resources, and prompts interactively. + +--- + +## Resources + +- [GitHub: scaffold-hbar-ui](https://github.com/hedera-dev/scaffold-hbar-ui) — Source code +- [Example App](https://github.com/hedera-dev/scaffold-hbar-ui/tree/main/example) — Live demos of all components +- [MCP Documentation](https://modelcontextprotocol.io/) — Learn more about Model Context Protocol +- [npm: @scaffold-hbar-ui/components](https://www.npmjs.com/package/@scaffold-hbar-ui/components) +- [npm: @scaffold-hbar-ui/hooks](https://www.npmjs.com/package/@scaffold-hbar-ui/hooks)