Local Network
Boot a complete local Avalanche network with ICM relayer and signature aggregator
The local-network flow boots a complete stack with a single command and validates ICM/ICTT against real consensus and a real relayer: the Primary Network, an L1, Teleporter, the ICM relayer, and the signature aggregator.
Prerequisites
- Completed installation, including the contract dependencies.
That's all — pnpm run up auto-installs a pinned AvalancheGo + subnet-evm release on first run (cached under .interchain-kit/bin/) and rebuilds the workspace packages itself, so there's no AVALANCHEGO_PATH to set and no separate build step.
Boot the Network
pnpm run up # boots Primary Network + L1 + ICM + relayer + sigaggThe first run is a cold boot (~3 minutes) because it downloads the ICM services, starts the network, creates an L1, sets up the validator set, and launches the relayer and signature aggregator. Subsequent runs reuse a snapshot and are much faster.
What up does
pnpm run up runs the tmpnetjs producer, which orchestrates the full sequence:
- Spawns 5 primary-network nodes (AvalancheGo's preconfigured local stakers).
- Creates a subnet on the P-Chain.
- Issues a
CreateChainTxfor asubnet-evmL1 with theValidatorManagerproxy pre-allocated. - Spawns L1 validator + RPC nodes tracking the subnet.
- Converts the subnet to an L1 (
ConvertSubnetToL1Tx). - Initializes the validator set on the L1 via the signature aggregator + Warp.
- Deploys
TeleporterMessenger+TeleporterRegistryon every chain from a single-use deployer (so addresses match across chains — the relayer requires this). - Funds the relayer EOA on the C-Chain.
- Starts
icm-relayer(:8080) andsignature-aggregator(:8090) with peer discovery. - Writes
network.json,addresses.ts, and.envto.interchain-kit/artifacts/.
Generated Artifacts
Once the network is up, Interchain Kit writes everything your scripts need to .interchain-kit/artifacts/:
| File | Contents |
|---|---|
network.json | Network topology — chains, blockchain IDs, Teleporter/registry addresses, funded key |
addresses.ts | Deployed contract addresses, importable from TypeScript |
.env | Environment variables for the running network |
Your TypeScript scripts load network.json through loadNetwork() (see tmpnetjs SDK).
Build the Contracts
Before running any example, compile the contracts so the scripts can load their ABIs and bytecode from contracts/out/:
forge build --root contractsWhy this step is needed
The demo scripts read compiled artifacts (e.g. contracts/out/SimpleSender.sol/SimpleSender.json). If you skip this, you'll see Forge artifact not found: contracts/out/....
With the network running and the contracts built, you're ready to run the examples.
Stop and Clean Up
pnpm run down # stop processes (snapshot preserved for a fast next boot)
pnpm run clean # nuke data, snapshots, and logs in .interchain-kit/Use down when you want to pause and resume quickly. Use clean when a run failed partway and subsequent runs are reusing stale data — clean, then up again.
Lifecycle Commands
| Command | What it does |
|---|---|
pnpm test:harness | Run the Foundry harness tests (forge test --root contracts -vv) |
pnpm run build | Build the workspace packages (required before the first up) |
pnpm run up | Boot the full local network + ICM relayer + signature aggregator |
pnpm run down | Stop the running processes; keep the snapshot |
pnpm run clean | Remove all data, snapshots, and logs under .interchain-kit/ |
pnpm fmt | Format Solidity with forge fmt |
Ports
The local network binds the following ports. If a boot fails with "address already in use," find and stop whatever is holding the port (for example lsof -iTCP:8080 -sTCP:LISTEN).
| Service | Port(s) |
|---|---|
| Primary Network nodes | 9650 + 100*i (i.e. 9650, 9750, …) |
icm-relayer | 8080 (API) + 9090 (metrics) |
signature-aggregator | 8090 |
Hitting an error? See Troubleshooting.
Next Steps
Is this guide helpful?