create-avalanche-app 0.1.4 → 0.1.6

package/templates/l1-launch/lib/token-artifact.ts

@@ -0,0 +1,239 @@
+// Auto-generated from contracts/src/AvaKitToken.sol via `forge build`.
+// Re-generate after editing the contract: cd contracts && forge build, then
+// copy abi + bytecode.object here.
+
+import type { Abi, Hex } from "viem";
+
+export const abi = [
+  {
+    "type": "function",
+    "name": "allowance",
+    "inputs": [
+      {
+        "name": "",
+        "type": "address",
+        "internalType": "address"
+      },
+      {
+        "name": "",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "approve",
+    "inputs": [
+      {
+        "name": "spender",
+        "type": "address",
+        "internalType": "address"
+      },
+      {
+        "name": "value",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "bool",
+        "internalType": "bool"
+      }
+    ],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "balanceOf",
+    "inputs": [
+      {
+        "name": "",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "decimals",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint8",
+        "internalType": "uint8"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "mint",
+    "inputs": [],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "name",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "string",
+        "internalType": "string"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "symbol",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "string",
+        "internalType": "string"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "totalSupply",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "transfer",
+    "inputs": [
+      {
+        "name": "to",
+        "type": "address",
+        "internalType": "address"
+      },
+      {
+        "name": "value",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "bool",
+        "internalType": "bool"
+      }
+    ],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "transferFrom",
+    "inputs": [
+      {
+        "name": "from",
+        "type": "address",
+        "internalType": "address"
+      },
+      {
+        "name": "to",
+        "type": "address",
+        "internalType": "address"
+      },
+      {
+        "name": "value",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "bool",
+        "internalType": "bool"
+      }
+    ],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "event",
+    "name": "Approval",
+    "inputs": [
+      {
+        "name": "owner",
+        "type": "address",
+        "indexed": true,
+        "internalType": "address"
+      },
+      {
+        "name": "spender",
+        "type": "address",
+        "indexed": true,
+        "internalType": "address"
+      },
+      {
+        "name": "value",
+        "type": "uint256",
+        "indexed": false,
+        "internalType": "uint256"
+      }
+    ],
+    "anonymous": false
+  },
+  {
+    "type": "event",
+    "name": "Transfer",
+    "inputs": [
+      {
+        "name": "from",
+        "type": "address",
+        "indexed": true,
+        "internalType": "address"
+      },
+      {
+        "name": "to",
+        "type": "address",
+        "indexed": true,
+        "internalType": "address"
+      },
+      {
+        "name": "value",
+        "type": "uint256",
+        "indexed": false,
+        "internalType": "uint256"
+      }
+    ],
+    "anonymous": false
+  }
+] as const satisfies Abi;
+
+export const bytecode = "0x6080604052348015600e575f5ffd5b5061066f8061001c5f395ff3fe608060405234801561000f575f5ffd5b506004361061009b575f3560e01c8063313ce56711610063578063313ce5671461013657806370a082311461015057806395d89b411461016f578063a9059cbb14610191578063dd62ed3e146101a4575f5ffd5b806306fdde031461009f578063095ea7b3146100e05780631249c58b1461010357806318160ddd1461010d57806323b872dd14610123575b5f5ffd5b6100ca6040518060400160405280600c81526020016b20bb30a5b4ba102a37b5b2b760a11b81525081565b6040516100d791906103f4565b60405180910390f35b6100f36100ee366004610444565b6101ce565b60405190151581526020016100d7565b61010b61023a565b005b6101155f5481565b6040519081526020016100d7565b6100f361013136600461046c565b6102b2565b61013e601281565b60405160ff90911681526020016100d7565b61011561015e3660046104a6565b60016020525f908152604090205481565b6100ca604051806040016040528060038152602001621052d560ea1b81525081565b6100f361019f366004610444565b61037e565b6101156101b23660046104c6565b600260209081525f928352604080842090915290825290205481565b335f8181526002602090815260408083206001600160a01b038716808552925280832085905551919290917f8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925906102289086815260200190565b60405180910390a35060015b92915050565b5f6102476012600a6105ee565b6102529060646105fc565b9050805f5f8282546102649190610613565b9091555050335f818152600160209081526040808320805486019055518481527fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef910160405180910390a350565b6001600160a01b0383165f9081526002602090815260408083203384529091528120805483919083906102e6908490610626565b90915550506001600160a01b0384165f9081526001602052604081208054849290610312908490610626565b90915550506001600160a01b038084165f81815260016020526040908190208054860190555190918616907fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef9061036c9086815260200190565b60405180910390a35060019392505050565b335f9081526001602052604081208054839190839061039e908490610626565b90915550506001600160a01b0383165f81815260016020526040908190208054850190555133907fddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef906102289086815260200190565b602081525f82518060208401528060208501604085015e5f604082850101526040601f19601f83011684010191505092915050565b80356001600160a01b038116811461043f575f5ffd5b919050565b5f5f60408385031215610455575f5ffd5b61045e83610429565b946020939093013593505050565b5f5f5f6060848603121561047e575f5ffd5b61048784610429565b925061049560208501610429565b929592945050506040919091013590565b5f602082840312156104b6575f5ffd5b6104bf82610429565b9392505050565b5f5f604083850312156104d7575f5ffd5b6104e083610429565b91506104ee60208401610429565b90509250929050565b634e487b7160e01b5f52601160045260245ffd5b6001815b60018411156105465780850481111561052a5761052a6104f7565b600184161561053857908102905b60019390931c92800261050f565b935093915050565b5f8261055c57506001610234565b8161056857505f610234565b816001811461057e5760028114610588576105a4565b6001915050610234565b60ff841115610599576105996104f7565b50506001821b610234565b5060208310610133831016604e8410600b84101617156105c7575081810a610234565b6105d35f19848461050b565b805f19048211156105e6576105e66104f7565b029392505050565b5f6104bf60ff84168361054e565b8082028115828204841417610234576102346104f7565b80820180821115610234576102346104f7565b81810381811115610234576102346104f756fea26469706673582212203ba8f5901a64d91a7beec3bdc98521ea0a7279a4ebafb699842fb133050e658e64736f6c634300081c0033" as Hex;

package/templates/l1-launch/llms.txt

@@ -0,0 +1,31 @@
+# __PROJECT_NAME__
+
+> Launch your own Avalanche L1 with one command, then explore it in a built-in dashboard (live blocks, transactions, balance, contract deploy). Next.js + @avakit/react + viem + avalanche-cli, no third-party explorer.
+
+## Project map
+
+- [scripts/l1.sh](scripts/l1.sh): `pnpm l1` — create + deploy a local Subnet-EVM L1, write l1.config.json.
+- [scripts/l1-fuji.sh](scripts/l1-fuji.sh): `pnpm l1:fuji` — deploy the L1 to the Fuji testnet (advanced).
+- [l1.config.json](l1.config.json): your chain (name, token, evmChainId, rpcUrl, blockchainIdHex, faucetAccount).
+- [lib/l1.ts](lib/l1.ts): config → AvaKit chain (`defineChain`) + `isConfigured`.
+- [components/demo.tsx](components/demo.tsx): the dashboard/explorer — polls RPC for blocks/txs/gas/balance, deploys + mints the demo token.
+- [contracts/src/AvaKitToken.sol](contracts/src/AvaKitToken.sol) + [lib/token-artifact.ts](lib/token-artifact.ts): bundled ERC-20 for browser deploy.
+- [CLAUDE.md](CLAUDE.md): agent guide — the flow, an explainer for every L1 config decision, the EWOQ warning, and the Fuji graduation path.
+
+## Key APIs
+
+- Chain: `chain` and `isConfigured` from `@/lib/l1`.
+- Explorer reads (all read-only viem): `getPublicClient(chain)` → `getBlockNumber()`, `getGasPrice()`, `getBlock({ blockNumber, includeTransactions: true })`, `getBalance({ address })`.
+- Deploy: `deployContract({ artifact: { abi, bytecode }, chain, provider, account })` from `@avakit/core`.
+- Write: `getWalletClient(chain, provider).writeContract({ address, abi, functionName: "mint", account })`.
+
+## Config decisions
+
+Subnet-EVM VM, EVM chain id (default 9999), native token symbol, `--sovereign=false` for a
+zero-prompt local chain (Fuji path uses a sovereign PoA L1), `--test-defaults` (EWOQ pre-funded).
+
+## External docs
+
+- Create/deploy an L1 locally: https://build.avax.network/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-locally
+- Deploy on Fuji: https://build.avax.network/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-on-fuji-testnet
+- avalanche-cli: https://build.avax.network/docs/tooling/avalanche-cli/get-avalanche-cli

package/templates/l1-launch/manifest.json

@@ -0,0 +1,6 @@
+{
+  "id": "l1-launch",
+  "title": "Launch your own L1",
+  "description": "Spin up your own Avalanche L1 with one command, then explore blocks, send txs, and deploy a contract in a built-in dashboard",
+  "contracts": true
+}

package/templates/l1-launch/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+};
+
+export default nextConfig;

package/templates/l1-launch/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "typecheck": "tsc --noEmit",
+    "l1": "bash scripts/l1.sh",
+    "l1:fuji": "bash scripts/l1-fuji.sh"
+  },
+  "dependencies": {
+    "@avakit/core": "__AVAKIT_DEP__",
+    "@avakit/react": "__AVAKIT_DEP__",
+    "lucide-react": "1.22.0",
+    "next": "16.2.9",
+    "next-themes": "0.4.6",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "viem": "2.54.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "4.3.2",
+    "@types/node": "26.0.1",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "postcss": "8.5.16",
+    "tailwindcss": "4.3.2",
+    "tw-animate-css": "1.4.0",
+    "typescript": "6.0.3"
+  }
+}

package/templates/l1-launch/pnpm-workspace.yaml

@@ -0,0 +1,11 @@
+# pnpm settings for this scaffolded app.
+# allowBuilds: pre-approve native postinstall scripts so `pnpm install` / `pnpm dev`
+#   don't fail with ERR_PNPM_IGNORED_BUILDS on pnpm 10+.
+# minimumReleaseAgeExclude: pnpm's supply-chain age gate blocks very fresh releases;
+#   exempt AvaKit's own packages so a new @avakit publish never breaks a fresh install
+#   (third-party deps keep the protection). Delete this file to opt back into defaults.
+allowBuilds:
+  sharp: true
+minimumReleaseAgeExclude:
+  - '@avakit/core'
+  - '@avakit/react'

package/templates/l1-launch/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/templates/l1-launch/scripts/l1-fuji.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+#
+# Graduate your L1 to the Fuji TESTNET (advanced).
+#
+# Unlike `pnpm l1` (fully local, instant, free), deploying to Fuji is a real,
+# multi-step operation. This script wraps the avalanche-cli commands and, where
+# the CLI needs interactive input or your own keys, walks you through it. Read
+# the caveats below before running — a Fuji L1 needs an always-on validator and
+# a periodically-topped-up balance, or it stops producing blocks.
+#
+# Configure via env (all optional; must match the chain you created with pnpm l1):
+#   L1_NAME=mychain FUJI_KEY=mykey pnpm l1:fuji
+
+set -uo pipefail
+
+NAME="${L1_NAME:-mychain}"
+KEY="${FUJI_KEY:-}"
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$ROOT/l1.config.json"
+
+say()  { printf "\033[1;37m▸\033[0m %s\n" "$1"; }
+warn() { printf "\033[1;33m!\033[0m %s\n" "$1"; }
+die()  { printf "\033[1;31m✖\033[0m %s\n" "$1" >&2; exit 1; }
+
+command -v avalanche >/dev/null 2>&1 || die "avalanche-cli not found. See CLAUDE.md."
+
+cat <<'EOF'
+────────────────────────────────────────────────────────────────────────
+Deploy your L1 to Fuji — what you need first (one-time):
+
+  1. A Fuji key funded with test AVAX:
+       avalanche key create mykey            # creates a key
+       # fund its C-Chain address from the Builder Hub faucet:
+       #   https://build.avax.network/console/primary-network/faucet
+       # then move funds to the P-Chain:
+       avalanche key transfer --key mykey --amount 2 --sender-blockchain c --receiver-blockchain p
+
+  2. Budget ~1-2 test AVAX PER validator — an L1 validator pays a continuous
+     P-Chain fee (~1 AVAX ≈ 1 month). When the balance hits zero the validator
+     goes inactive and your L1 STOPS. Top up with:
+       avalanche blockchain addValidator / IncreaseL1ValidatorBalance
+
+  3. A bootstrap validator node that STAYS RUNNING. Your machine can be it
+     (--use-local-machine below), but if this process exits, block production
+     stops. For an always-on chain, run a real node instead.
+────────────────────────────────────────────────────────────────────────
+EOF
+
+[ -n "$KEY" ] || die "Set FUJI_KEY to your funded avalanche-cli key name, e.g. FUJI_KEY=mykey pnpm l1:fuji"
+
+say "Deploying '$NAME' to Fuji with key '$KEY' (your machine as bootstrap validator)…"
+warn "This is interactive: the CLI will ask you to confirm the CreateSubnet / CreateChain /"
+warn "ConvertSubnetToL1 transactions and to set up the local-machine validator. Follow its prompts."
+
+# --use-local-machine turns this machine into the bootstrap validator; the CLI
+# handles subnet creation, chain creation, and conversion to a sovereign L1.
+avalanche blockchain deploy "$NAME" \
+  --fuji \
+  --key "$KEY" \
+  --use-local-machine \
+  || die "Fuji deploy did not complete. Re-run after addressing the CLI's output."
+
+# Discover the Fuji RPC + hex blockchain ID for the deployed L1.
+say "Reading Fuji chain details…"
+OUT="$(avalanche blockchain describe "$NAME" 2>/dev/null)"
+RPC="$(printf '%s' "$OUT" | grep -oE 'https?://[^ ]*/ext/bc/[A-Za-z0-9]+/rpc' | head -1)"
+BID="$(printf '%s' "$OUT" | grep -iE 'BlockchainID \(HEX\)' | grep -oiE '0x[0-9a-f]{64}' | head -1)"
+CID="$(printf '%s' "$OUT" | grep -iE 'ChainID' | grep -oE '[0-9]+' | head -1)"
+
+[ -n "$RPC" ] || die "Could not read the Fuji RPC. Run: avalanche blockchain describe $NAME"
+
+TOKEN="$(node -e "process.stdout.write(String(require('$CONFIG').token||'MYL1'))" 2>/dev/null || echo MYL1)"
+CID="${CID:-$(node -e "process.stdout.write(String(require('$CONFIG').evmChainId||9999))" 2>/dev/null || echo 9999)}"
+
+cat > "$CONFIG" <<EOF
+{
+  "configured": true,
+  "network": "fuji",
+  "name": "$NAME",
+  "token": "$TOKEN",
+  "evmChainId": $CID,
+  "rpcUrl": "$RPC",
+  "blockchainIdHex": "${BID:-}",
+  "faucetAccount": { "address": "", "privateKey": "" }
+}
+EOF
+
+say "Updated l1.config.json → $RPC (network: fuji)"
+cat <<EOF
+
+✔ Your L1 is on Fuji.
+
+  • pnpm dev → the built-in explorer now points at your Fuji L1's RPC.
+  • Connect your OWN funded wallet (no EWOQ on Fuji).
+  • Keep this machine / your validator node running, and keep the validator
+    balance topped up, or the L1 stops producing blocks.
+
+There is no automatic hosted explorer for a custom Fuji L1 — this app's built-in
+explorer is your window into the chain.
+EOF

package/templates/l1-launch/scripts/l1.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+#
+# Launch your own local Avalanche L1 — one command.
+#
+# Creates a Subnet-EVM blockchain and deploys it to a local Avalanche network,
+# then writes the discovered RPC URL + blockchain ID into l1.config.json so the
+# app can talk to your chain. Everything runs on your machine — no test AVAX, no
+# faucet, no always-on node. To graduate the same chain to the Fuji testnet, see
+# `pnpm l1:fuji` (scripts/l1-fuji.sh) and CLAUDE.md.
+#
+# Configure via env (all optional):
+#   L1_NAME=mychain L1_CHAIN_ID=9999 L1_TOKEN=MYL1 pnpm l1
+#
+# Requires avalanche-cli. It downloads avalanchego + Subnet-EVM on first run.
+
+set -uo pipefail
+
+NAME="${L1_NAME:-mychain}"
+CHAIN_ID="${L1_CHAIN_ID:-9999}"
+TOKEN="${L1_TOKEN:-MYL1}"
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$ROOT/l1.config.json"
+
+# EWOQ: avalanche-cli's well-known local dev key, pre-funded on every local
+# chain. PUBLIC — for local networks only, never a real network. Import it into
+# your wallet to transact on your L1.
+EWOQ_PK="0x56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027"
+EWOQ_ADDR="0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"
+
+say() { printf "\033[1;37m▸\033[0m %s\n" "$1"; }
+die() { printf "\033[1;31m✖\033[0m %s\n" "$1" >&2; exit 1; }
+
+# --- 0. avalanche-cli present? ---------------------------------------------
+if ! command -v avalanche >/dev/null 2>&1; then
+  cat >&2 <<'EOF'
+✖ avalanche-cli not found. Install it:
+
+  curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-cli/main/scripts/install.sh | sh -s -- -b /usr/local/bin
+
+  # or:  brew install ava-labs/tap/avalanche-cli
+
+Then re-run: pnpm l1
+EOF
+  exit 1
+fi
+
+# --- 1. Create the L1 -------------------------------------------------------
+# --sovereign=false keeps this fully non-interactive for local dev (a true
+# sovereign L1 prompts for a validator-manager owner). --test-defaults uses
+# local dev settings (EWOQ pre-funded, fast finality). CLAUDE.md explains each
+# knob (VM, consensus, chain ID, sovereignty) and the Fuji path uses a real
+# sovereign L1.
+say "Creating L1 '$NAME' (Subnet-EVM · chainId $CHAIN_ID · token $TOKEN)…"
+avalanche blockchain create "$NAME" \
+  --evm --latest \
+  --evm-chain-id "$CHAIN_ID" \
+  --evm-token "$TOKEN" \
+  --test-defaults \
+  --sovereign=false \
+  --force </dev/null >/dev/null 2>&1 \
+  || die "Failed to create '$NAME'. Try: avalanche blockchain delete $NAME"
+
+# --- 2. Deploy it to a local network ----------------------------------------
+say "Deploying '$NAME' locally (first run boots the local network)…"
+avalanche blockchain deploy "$NAME" --local </dev/null || die "Deploy of '$NAME' failed."
+
+# --- 3. Discover RPC URL + hex blockchain ID --------------------------------
+# `describe` prints both. We grep by shape (robust across CLI versions).
+say "Reading chain details…"
+OUT="$(avalanche blockchain describe "$NAME" 2>/dev/null)"
+RPC="$(printf '%s' "$OUT" | grep -oE 'http://127\.0\.0\.1:[0-9]+/ext/bc/[A-Za-z0-9]+/rpc' | head -1)"
+BID="$(printf '%s' "$OUT" | grep -iE 'BlockchainID \(HEX\)' | grep -oiE '0x[0-9a-f]{64}' | head -1)"
+
+[ -n "$RPC" ] || die "Could not read '$NAME' RPC. Run: avalanche blockchain describe $NAME"
+
+# --- 4. Write l1.config.json ------------------------------------------------
+cat > "$CONFIG" <<EOF
+{
+  "configured": true,
+  "network": "local",
+  "name": "$NAME",
+  "token": "$TOKEN",
+  "evmChainId": $CHAIN_ID,
+  "rpcUrl": "$RPC",
+  "blockchainIdHex": "${BID:-}",
+  "faucetAccount": { "address": "$EWOQ_ADDR", "privateKey": "$EWOQ_PK" }
+}
+EOF
+
+say "Wrote l1.config.json → $RPC"
+cat <<EOF
+
+✔ Your L1 is live locally.
+
+Next:
+  1. Import the EWOQ dev key into your wallet (Core / MetaMask) — pre-funded on your chain:
+       $EWOQ_PK
+     (public dev key, local only)
+  2. pnpm dev  →  http://localhost:3000  (your chain dashboard + explorer)
+  3. Deploy the demo token, watch blocks and transactions land in real time.
+
+Manage the network:
+  avalanche network stop     # pause (keeps state)
+  avalanche network clean    # wipe (new blockchain ID — re-run pnpm l1)
+
+Graduate to the Fuji testnet (advanced, needs test AVAX + an always-on node):
+  pnpm l1:fuji
+EOF

package/templates/l1-launch/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/token-bridge/CLAUDE.md

@@ -0,0 +1,70 @@
+# __PROJECT_NAME__ — cross-chain token bridge with ICTT (scaffolded with AvaKit)
+
+Operational guide for AI agents (Claude Code / Cursor) working in this project.
+
+## What this is
+
+A dapp that bridges an ERC-20 between two Avalanche L1s using **Interchain Token Transfer (ICTT)**.
+It runs against a **local devnet** of two L1s that `scripts/bridge.sh` (`pnpm bridge`) spins up — with
+Interchain Messaging, a relayer, and a full ICTT bridge (a demo token + Home + Remote) deployed and
+registered automatically.
+
+## Stack
+
+Next.js 16 (App Router) · React 19 · `@avakit/react` · `@avakit/core` · viem · shadcn/ui · avalanche-cli (local devnet) · ava-labs/icm-contracts (ICTT)
+
+## How ICTT works here
+
+- **ERC20TokenHome** (on chain1) holds the real ERC-20. When you bridge, it **locks** your tokens and
+  sends an ICM message to the remote.
+- **ERC20TokenRemote** (on chain2) **is itself an ERC-20** (the "bridged" token, symbol `TOK1.b`). On
+  arrival it **mints** to the recipient. Bridging back **burns** the remote token and **unlocks** the
+  original on the home chain.
+- A **TeleporterRegistry** on each chain points the ICTT contracts at the ICM messenger predeploy
+  (`0x253b…5fcf`). The relayer (started by `pnpm bridge`) carries the messages.
+
+## Architecture
+
+- `scripts/bridge.sh` (`pnpm bridge`) — creates + deploys two L1s, then runs `deploy-bridge.mjs`.
+- `scripts/deploy-bridge.mjs` — deploys the demo ERC-20 + TeleporterRegistry + Home on chain1, a
+  TeleporterRegistry + Remote on chain2, and calls `registerWithHome`. Uses viem + the embedded
+  artifacts + the public EWOQ key. Writes all addresses to `bridge.config.json`.
+- `lib/ictt-artifacts.json` — ABIs + bytecode for TeleporterRegistry, ERC20TokenHome,
+  ERC20TokenRemote, and the demo ERC-20, compiled from `ava-labs/icm-contracts` with the optimizer.
+- `lib/ictt.ts` — turns `bridge.config.json` into AvaKit chains + the addresses/ABIs the app uses.
+- `components/demo.tsx` — the bridge UI: balances on both chains, mint, and bridge in either direction.
+
+## The bridge flow (in the UI)
+
+1. `home → remote`: `approve(home, amount)` on the demo token, then `home.send(SendTokensInput, amount)`.
+   The home locks the token; the relayer delivers; the remote mints `TOK1.b` to you on chain2.
+2. `remote → home`: `remote.send(SendTokensInput, amount)` (no approval — the remote burns its own
+   ERC-20); the relayer delivers; the home unlocks your original token on chain1.
+
+`SendTokensInput` = `{ destinationBlockchainID (bytes32), destinationTokenTransferrerAddress,
+recipient, primaryFeeTokenAddress, primaryFee, secondaryFee, requiredGasLimit, multiHopFallback }`.
+On the local devnet, fees are 0, `primaryFeeTokenAddress` is the zero address, and
+`requiredGasLimit` is 250000. `destinationBlockchainID` is the bytes32 (Avalanche) blockchain ID in
+hex — NOT the EVM chainId — via `blockchainIdOf(chain)` in `lib/ictt.ts`.
+
+## Editing / regenerating the contracts
+
+The bundled artifacts are compiled from `ava-labs/icm-contracts` (`contracts/ictt`) with solc + the
+optimizer (runs 200) — the optimizer keeps ERC20TokenHome/Remote under the 24 KB EVM code-size limit.
+To regenerate, compile those contracts with any optimizing toolchain (Hardhat or solc standard-JSON)
+and replace the `abi`/`bytecode` in `lib/ictt-artifacts.json`. (Note: `avalanche interchain
+tokenTransferrer deploy` can also deploy an ICTT bridge, but it requires a specific pinned Foundry
+build to compile under the size limit — this template ships pre-compiled bytecode to avoid that.)
+
+## Rules
+
+- shadcn/ui only; `@avakit/react` components are shadcn-styled. Black & white for now; dark/light via next-themes; both must work.
+- Animations: Framer Motion or GSAP only.
+- Amounts are 18-decimal — always convert with `parseEther` / `formatEther`.
+- Never hardcode a real private key. The EWOQ key is a PUBLIC dev key — local devnet only.
+
+## Commands
+
+- `pnpm bridge` — spin up the 2-L1 devnet + deploy the ICTT bridge (writes `bridge.config.json`)
+- `pnpm dev` — dev server (http://localhost:3000)
+- `avalanche network stop | clean` — pause | wipe the local devnet