create-avalanche-app 0.1.0 → 0.1.1

package/templates/icm-messenger/env.example

@@ -0,0 +1,6 @@
+# The ICM messenger template runs against a LOCAL devnet and uses a browser
+# wallet (Core / MetaMask). No environment variables are required.
+#
+# In your wallet, import the local EWOQ dev key (pre-funded on every local chain):
+#   0x56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027
+# Never use this key on a real network — it is publicly known.

package/templates/icm-messenger/gitignore

@@ -0,0 +1,15 @@
+node_modules/
+.next/
+out/
+*.tsbuildinfo
+next-env.d.ts
+.env
+.env.*
+!.env.example
+.DS_Store
+*.log
+
+# Foundry
+contracts/out/
+contracts/cache/
+contracts/broadcast/

package/templates/icm-messenger/icm.config.json

@@ -0,0 +1,6 @@
+{
+  "configured": false,
+  "teleporterMessenger": "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf",
+  "chain1": { "name": "chain1", "token": "TOK1", "evmChainId": 1001, "rpcUrl": "", "blockchainIdHex": "" },
+  "chain2": { "name": "chain2", "token": "TOK2", "evmChainId": 1002, "rpcUrl": "", "blockchainIdHex": "" }
+}

package/templates/icm-messenger/lib/devnet.ts

@@ -0,0 +1,58 @@
+/**
+ * Local ICM devnet configuration.
+ *
+ * `scripts/devnet.sh` spins up two Avalanche L1s with Interchain Messaging and a
+ * relayer, then writes the discovered RPC URLs and blockchain IDs into
+ * `icm.config.json`. This module turns that into AvaKit chains the app can use.
+ */
+
+import { type AvaChain, defineChain } from "@avakit/core/chains";
+import config from "../icm.config.json";
+
+export interface IcmChainConfig {
+  name: string;
+  token: string;
+  /** EVM chain id (for the wallet / RPC). */
+  evmChainId: number;
+  rpcUrl: string;
+  /** The bytes32 (Avalanche) blockchain ID in hex — Teleporter's routing key. */
+  blockchainIdHex: string;
+}
+
+export interface IcmConfig {
+  configured: boolean;
+  /** TeleporterMessenger predeploy, the same address on every ICM-enabled chain. */
+  teleporterMessenger: string;
+  chain1: IcmChainConfig;
+  chain2: IcmChainConfig;
+}
+
+export const icm = config as IcmConfig;
+
+/** True once `pnpm devnet` has filled in the two chains' RPC URLs. */
+export const isConfigured = Boolean(
+  icm.configured && icm.chain1.rpcUrl && icm.chain2.rpcUrl,
+);
+
+function toAvaChain(c: IcmChainConfig): AvaChain {
+  return defineChain({
+    id: c.evmChainId,
+    name: c.name,
+    rpcUrl: c.rpcUrl || "http://127.0.0.1:9650",
+    explorerUrl: "",
+    nativeCurrency: { name: c.token, symbol: c.token, decimals: 18 },
+    testnet: true,
+  });
+}
+
+export const chain1 = toAvaChain(icm.chain1);
+export const chain2 = toAvaChain(icm.chain2);
+
+/** The two local chains, indexed the way the UI pairs them. */
+export const localChains: [AvaChain, AvaChain] = [chain1, chain2];
+
+/** Blockchain ID (bytes32 hex) for a given local chain — needed to send to it. */
+export function blockchainIdOf(chain: AvaChain): `0x${string}` {
+  const hex = chain.id === icm.chain1.evmChainId ? icm.chain1.blockchainIdHex : icm.chain2.blockchainIdHex;
+  return hex as `0x${string}`;
+}

package/templates/icm-messenger/lib/messenger-artifact.ts

@@ -0,0 +1,184 @@
+// Auto-generated from contracts/src/AvaKitMessenger.sol via `forge build`.
+// Re-generate after editing the contract: cd contracts && forge build, then
+// copy abi + bytecode.object here. Lets the app deploy from the browser with
+// no Foundry required at runtime.
+
+import type { Abi, Hex } from "viem";
+
+export const abi = [
+  {
+    "type": "function",
+    "name": "TELEPORTER",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "address",
+        "internalType": "contract ITeleporterMessenger"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "lastMessage",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "string",
+        "internalType": "string"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "lastOriginSender",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "lastSourceBlockchainID",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "messagesReceived",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint256",
+        "internalType": "uint256"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "receiveTeleporterMessage",
+    "inputs": [
+      {
+        "name": "sourceBlockchainID",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "originSenderAddress",
+        "type": "address",
+        "internalType": "address"
+      },
+      {
+        "name": "message",
+        "type": "bytes",
+        "internalType": "bytes"
+      }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "sendMessage",
+    "inputs": [
+      {
+        "name": "destinationBlockchainID",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "destinationAddress",
+        "type": "address",
+        "internalType": "address"
+      },
+      {
+        "name": "message",
+        "type": "string",
+        "internalType": "string"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "messageID",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      }
+    ],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "event",
+    "name": "MessageReceived",
+    "inputs": [
+      {
+        "name": "sourceBlockchainID",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "originSender",
+        "type": "address",
+        "indexed": true,
+        "internalType": "address"
+      },
+      {
+        "name": "message",
+        "type": "string",
+        "indexed": false,
+        "internalType": "string"
+      }
+    ],
+    "anonymous": false
+  },
+  {
+    "type": "event",
+    "name": "MessageSent",
+    "inputs": [
+      {
+        "name": "messageID",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "destinationBlockchainID",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "destinationAddress",
+        "type": "address",
+        "indexed": false,
+        "internalType": "address"
+      },
+      {
+        "name": "message",
+        "type": "string",
+        "indexed": false,
+        "internalType": "string"
+      }
+    ],
+    "anonymous": false
+  }
+] as const satisfies Abi;
+
+export const bytecode = "0x6080604052348015600e575f5ffd5b506108f08061001c5f395ff3fe608060405234801561000f575f5ffd5b506004361061007a575f3560e01c80635be63c71116100585780635be63c71146100e4578063813275bc146100ed578063c0207bb814610108578063c868efaa14610111575f5ffd5b8063103070051461007e5780632ed2e8e0146100ae57806332970710146100cf575b5f5ffd5b600254610091906001600160a01b031681565b6040516001600160a01b0390911681526020015b60405180910390f35b6100c16100bc3660046104aa565b610126565b6040519081526020016100a5565b6100d76102a6565b6040516100a5919061052e565b6100c160035481565b61009173253b2784c75e510dd0ff1da844684a1ac0aa5fcf81565b6100c160015481565b61012461011f3660046104aa565b610331565b005b5f73253b2784c75e510dd0ff1da844684a1ac0aa5fcf6001600160a01b031663624488506040518060c00160405280888152602001876001600160a01b0316815260200160405180604001604052805f6001600160a01b031681526020015f81525081526020016203d09081526020015f67ffffffffffffffff8111156101af576101af610547565b6040519080825280602002602001820160405280156101d8578160200160208202803683370190505b50815260200186866040516020016101f1929190610583565b6040516020818303038152906040528152506040518263ffffffff1660e01b815260040161021f91906105e1565b6020604051808303815f875af115801561023b573d5f5f3e3d5ffd5b505050506040513d601f19601f8201168201806040525081019061025f9190610668565b905084817f4c6ebdf8689746d81e856c78d4049f7c9ae732786dd632398e24775ade8f62748686866040516102969392919061067f565b60405180910390a3949350505050565b5f80546102b2906106a3565b80601f01602080910402602001604051908101604052809291908181526020018280546102de906106a3565b80156103295780601f1061030057610100808354040283529160200191610329565b820191905f5260205f20905b81548152906001019060200180831161030c57829003601f168201915b505050505081565b3373253b2784c75e510dd0ff1da844684a1ac0aa5fcf146103ae5760405162461bcd60e51b815260206004820152602d60248201527f4176614b69744d657373656e6765723a2063616c6c6572206973206e6f74207460448201526c3432902a32b632b837b93a32b960991b606482015260840160405180910390fd5b5f6103bb828401846106db565b90505f6103c882826107da565b506001858155600280546001600160a01b0319166001600160a01b038716179055600380545f906103fa908490610895565b92505081905550836001600160a01b0316857fb668d57046ecd82ea44ba2a8fbfe10de34bec187561b8386394fed442e0de5468360405161043b919061052e565b60405180910390a35050505050565b80356001600160a01b0381168114610460575f5ffd5b919050565b5f5f83601f840112610475575f5ffd5b50813567ffffffffffffffff81111561048c575f5ffd5b6020830191508360208285010111156104a3575f5ffd5b9250929050565b5f5f5f5f606085870312156104bd575f5ffd5b843593506104cd6020860161044a565b9250604085013567ffffffffffffffff8111156104e8575f5ffd5b6104f487828801610465565b95989497509550505050565b5f81518084528060208401602086015e5f602082860101526020601f19601f83011685010191505092915050565b602081525f6105406020830184610500565b9392505050565b634e487b7160e01b5f52604160045260245ffd5b81835281816020850137505f828201602090810191909152601f909101601f19169091010190565b602081525f61059660208301848661055b565b949350505050565b5f8151808452602084019350602083015f5b828110156105d75781516001600160a01b03168652602095860195909101906001016105b0565b5093949350505050565b602081528151602082015260018060a01b0360208301511660408201525f604083015160018060a01b0381511660608401526020810151608084015250606083015160a0830152608083015160e060c084015261064261010084018261059e565b905060a0840151601f198483030160e085015261065f8282610500565b95945050505050565b5f60208284031215610678575f5ffd5b5051919050565b6001600160a01b03841681526040602082018190525f9061065f908301848661055b565b600181811c908216806106b757607f821691505b6020821081036106d557634e487b7160e01b5f52602260045260245ffd5b50919050565b5f602082840312156106eb575f5ffd5b813567ffffffffffffffff811115610701575f5ffd5b8201601f81018413610711575f5ffd5b803567ffffffffffffffff81111561072b5761072b610547565b604051601f8201601f19908116603f0116810167ffffffffffffffff8111828210171561075a5761075a610547565b604052818152828201602001861015610771575f5ffd5b816020840160208301375f91810160200191909152949350505050565b601f8211156107d557805f5260205f20601f840160051c810160208510156107b35750805b601f840160051c820191505b818110156107d2575f81556001016107bf565b50505b505050565b815167ffffffffffffffff8111156107f4576107f4610547565b6108088161080284546106a3565b8461078e565b6020601f82116001811461083a575f83156108235750848201515b5f19600385901b1c1916600184901b1784556107d2565b5f84815260208120601f198516915b828110156108695787850151825560209485019460019092019101610849565b508482101561088657868401515f19600387901b60f8161c191681555b50505050600190811b01905550565b808201808211156108b457634e487b7160e01b5f52601160045260245ffd5b9291505056fea2646970667358221220edd28d4270dcbf530c3f8f54e0b5659e1f054d971e767fac9a41dbc42de8ada264736f6c634300081c0033" as Hex;

package/templates/icm-messenger/llms.txt

@@ -0,0 +1,39 @@
+# __PROJECT_NAME__
+
+> An Avalanche cross-chain dapp scaffolded with AvaKit. Send a message between two Avalanche L1s using Interchain Messaging (ICM / Teleporter), against a one-command local devnet. Next.js + @avakit/react + shadcn/ui + Foundry + avalanche-cli.
+
+## Project map
+
+- [contracts/src/AvaKitMessenger.sol](contracts/src/AvaKitMessenger.sol): one contract that both sends and receives ICM messages (implements ITeleporterReceiver).
+- [lib/messenger-artifact.ts](lib/messenger-artifact.ts): compiled ABI + bytecode (browser deploy, no Foundry at runtime).
+- [scripts/devnet.sh](scripts/devnet.sh): one command — two local L1s with ICM + relayer.
+- [icm.config.json](icm.config.json): the two chains (RPC URL + hex blockchain ID); written by `pnpm devnet`.
+- [lib/devnet.ts](lib/devnet.ts): config → AvaKit chains + `blockchainIdOf()`.
+- [components/demo.tsx](components/demo.tsx): the Devnet Studio — live chain cards (block + ICM status), deploy on both chains, send, watch it arrive. Setup is a copy-command panel (never runs shell).
+- [CLAUDE.md](CLAUDE.md): agent guide (ICM API, the blockchainID-vs-chainId gotcha, rules).
+
+## Key facts
+
+- `destinationBlockchainID` is a **bytes32 hex blockchain ID**, NOT the EVM chainId. Use `blockchainIdOf(chain)`.
+- TeleporterMessenger predeploy: `0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf` (same on every ICM chain).
+- The receiver must `require(msg.sender == TeleporterMessenger)`.
+
+## Key APIs
+
+- Send: `AvaKitMessenger.sendMessage(destinationBlockchainID, destinationAddress, text)`
+- Receive: `receiveTeleporterMessage(sourceBlockchainID, originSender, message)` (stores `lastMessage`)
+- Deploy/read/write: `deployContract`, `getWalletClient`, `readContract`, `ensureChain` from `@avakit/core`
+- Wallet: `<ConnectAvalanche />`, `useAvaChain().setChain` to switch between the two L1s
+
+## Run it
+
+```
+pnpm devnet   # start 2 local L1s + ICM + relayer
+pnpm dev      # http://localhost:3000
+```
+
+## External docs
+
+- Avalanche ICM: https://build.avax.network/docs/cross-chain/teleporter/overview
+- ICM on a local network: https://build.avax.network/docs/cross-chain/icm-contracts/icm-contracts-on-local-network
+- Avalanche Builder Hub: https://build.avax.network/llms.txt

package/templates/icm-messenger/manifest.json

@@ -0,0 +1,6 @@
+{
+  "id": "icm-messenger",
+  "title": "ICM cross-chain messenger",
+  "description": "Send a message between two Avalanche L1s with Interchain Messaging (local devnet)",
+  "contracts": true
+}

package/templates/icm-messenger/next.config.ts

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

package/templates/icm-messenger/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "typecheck": "tsc --noEmit",
+    "devnet": "bash scripts/devnet.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/icm-messenger/postcss.config.mjs

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

package/templates/icm-messenger/scripts/devnet.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+#
+# One-command local ICM devnet.
+#
+# Spins up TWO Avalanche L1s (subnet-EVM) with Interchain Messaging (Teleporter)
+# and a relayer, all on a local network, then writes the discovered RPC URLs and
+# blockchain IDs into icm.config.json so the app can talk to both chains.
+#
+# Requires avalanche-cli. It downloads avalanchego + subnet-EVM on first run.
+
+set -uo pipefail
+
+CHAIN1="chain1"
+CHAIN2="chain2"
+EVM_CHAIN_ID_1=1001
+EVM_CHAIN_ID_2=1002
+TOKEN_1="TOK1"
+TOKEN_2="TOK2"
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CONFIG="$ROOT/icm.config.json"
+
+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 (it bundles nothing else you need):
+
+  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 devnet
+EOF
+  exit 1
+fi
+
+# --- 1. Create the two L1s (ICM + relayer are on by default) ----------------
+create_l1() {
+  local name="$1" cid="$2" tok="$3"
+  say "Creating L1 '$name' (evm chainId $cid)…"
+  avalanche blockchain create "$name" \
+    --evm --latest \
+    --evm-chain-id "$cid" \
+    --evm-token "$tok" \
+    --test-defaults \
+    --sovereign=false \
+    --icm \
+    --force </dev/null >/dev/null 2>&1 || die "Failed to create '$name'. Try: avalanche blockchain delete $name"
+}
+create_l1 "$CHAIN1" "$EVM_CHAIN_ID_1" "$TOKEN_1"
+create_l1 "$CHAIN2" "$EVM_CHAIN_ID_2" "$TOKEN_2"
+
+# --- 2. Deploy them to the local network ------------------------------------
+# The first deploy boots the local network (C-Chain included) and auto-deploys
+# the TeleporterMessenger + configures the relayer for every chain pair.
+say "Deploying '$CHAIN1' locally (this also starts the local network)…"
+avalanche blockchain deploy "$CHAIN1" --local </dev/null || die "Deploy of '$CHAIN1' failed."
+say "Deploying '$CHAIN2' locally…"
+avalanche blockchain deploy "$CHAIN2" --local </dev/null || die "Deploy of '$CHAIN2' failed."
+
+# --- 3. Discover RPC URL + hex blockchain ID for each chain -----------------
+# `describe` prints the RPC URL and the blockchain ID in hex. We grep by shape
+# (robust across CLI versions): the localhost RPC path, and a 0x + 64-hex id.
+discover() {
+  local name="$1" out rpc bid
+  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)"
+  # The bytes32 blockchain ID lives on the "BlockchainID (HEX)" row.
+  bid="$(printf '%s' "$out" | grep -iE 'BlockchainID \(HEX\)' | grep -oiE '0x[0-9a-f]{64}' | head -1)"
+  printf '%s\t%s' "$rpc" "$bid"
+}
+say "Reading chain details…"
+IFS=$'\t' read -r RPC1 BID1 < <(discover "$CHAIN1")
+IFS=$'\t' read -r RPC2 BID2 < <(discover "$CHAIN2")
+
+[ -n "$RPC1" ] && [ -n "$BID1" ] || die "Could not read '$CHAIN1' RPC/blockchain ID. Run: avalanche blockchain describe $CHAIN1"
+[ -n "$RPC2" ] && [ -n "$BID2" ] || die "Could not read '$CHAIN2' RPC/blockchain ID. Run: avalanche blockchain describe $CHAIN2"
+
+# --- 4. Write icm.config.json -----------------------------------------------
+cat > "$CONFIG" <<EOF
+{
+  "configured": true,
+  "teleporterMessenger": "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf",
+  "chain1": { "name": "$CHAIN1", "token": "$TOKEN_1", "evmChainId": $EVM_CHAIN_ID_1, "rpcUrl": "$RPC1", "blockchainIdHex": "$BID1" },
+  "chain2": { "name": "$CHAIN2", "token": "$TOKEN_2", "evmChainId": $EVM_CHAIN_ID_2, "rpcUrl": "$RPC2", "blockchainIdHex": "$BID2" }
+}
+EOF
+
+say "Wrote icm.config.json:"
+printf "   %s → %s\n   %s → %s\n" "$CHAIN1" "$RPC1" "$CHAIN2" "$RPC2"
+cat <<EOF
+
+✔ Local ICM devnet is up.
+
+Next:
+  1. In your wallet (Core / MetaMask), import the EWOQ dev key (pre-funded on both chains):
+       0x56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027
+  2. pnpm dev  →  http://localhost:3000
+  3. Deploy the messenger on both chains, then send a message across.
+
+Stop / reset the devnet:
+  avalanche network stop     # pause (keeps state)
+  avalanche network clean    # wipe (new blockchain IDs — re-run pnpm devnet)
+EOF

package/templates/icm-messenger/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"]
+}