ClawHub

Abi Toolchain

MCP Tools

ABI lifecycle management for smart contract projects. Use when your frontend is out of sync with contract changes, when you need to set up ABI generation in CI/CD, when dealing with ABI drift between deployments, managing proxy contract ABIs, or working with typechain/wagmi-generate/viem ABI types. Triggers on: ABI, typechain, wagmi generate, viem ABI, contract types, ABI drift, ABI mismatch, frontend out of sync with contract, ABI versioning, deployment artifacts, or any question about syncing frontend code to contract changes.

Audits

Pending
ClawScanReview

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPending

Multi-engine malware detections and file reputation.

Install

openclaw skills install abi-toolchain

ABI Toolchain

Treat your ABI like any other versioned artifact. Most frontend-contract sync bugs are ABI lifecycle problems in disguise.

Scripts

Ready-to-use tools in scripts/:

ScriptPurpose
sync-abi.shSync compiled ABIs from Foundry/Hardhat artifacts to frontend
abi-diff.jsCompare two ABI files: find added/removed/changed, flag breaking changes

sync-abi.sh

# Set which contracts to sync: create .abi-sync in your project root
echo "MyToken" >> .abi-sync
echo "MyVault:Vault" >> .abi-sync   # writes as Vault.json

# Run from your project root
ABI_SOURCE=out ABI_DEST=frontend/src/abis bash path/to/sync-abi.sh

# Or use defaults (Foundry: out/ → frontend/src/abis/)
bash scripts/sync-abi.sh

Handles both Foundry (out/Foo.sol/Foo.json) and Hardhat (artifacts/contracts/) artifacts. Uses jq if available, falls back to Python.

abi-diff.js

node scripts/abi-diff.js old/MyToken.json new/MyToken.json
# → { added: [], removed: [], changed: [], breaking: false, summary: "0 added, 0 removed, 1 changed" }

# Exit code 1 if breaking changes (useful in CI):
node scripts/abi-diff.js prev.json current.json || echo "BREAKING CHANGE"

Accepts raw ABI arrays or Foundry/Hardhat artifacts (auto-detected).

ABI Types Reference

See references/abi-formats.md for complete coverage of ABI entry types, function selectors, event topics, Foundry artifact structure, and common gotchas (tuples, uint vs uint256, as const).

The Core Problem

When a contract changes:

  1. New ABI gets compiled by Foundry/Hardhat
  2. Frontend still imports the old ABI from a file that wasn't updated
  3. Calls either fail silently or revert on-chain

The fix isn't careful manual updating — it's making the pipeline impossible to get wrong.

Pattern 1: Foundry → TypeScript Auto-Sync

After every forge build, auto-export ABIs to your frontend:

# scripts/sync-abi.sh
#!/bin/bash
set -e
CONTRACTS=("MyToken" "MyVault" "MyFactory")
SRC="out"           # Foundry output dir
DEST="frontend/src/abis"

mkdir -p $DEST

for contract in "${CONTRACTS[@]}"; do
  jq '.abi' "$SRC/$contract.sol/$contract.json" > "$DEST/$contract.json"
  echo "✅ Synced $contract ABI"
done

Add to foundry.toml as a post-build hook or wire into package.json:

{
  "scripts": {
    "build:contracts": "forge build && bash scripts/sync-abi.sh",
    "dev": "npm run build:contracts && next dev"
  }
}

Pattern 2: Typed ABIs with Viem (no codegen)

Viem's as const trick gives you full TypeScript types directly from your ABI JSON:

// abis/MyToken.ts — export from your synced JSON
export const myTokenAbi = [
  {
    name: 'transfer',
    type: 'function',
    stateMutability: 'nonpayable',
    inputs: [{ name: 'to', type: 'address' }, { name: 'amount', type: 'uint256' }],
    outputs: [{ name: '', type: 'bool' }],
  },
  // ...
] as const   // ← critical: makes TypeScript infer exact types

// Now readContract/writeContract will type-check function names and args
const result = await client.readContract({
  abi: myTokenAbi,
  functionName: 'transfer',  // ← autocompletes, typos caught at compile time
  args: ['0x...', 100n],     // ← arg types inferred
})

Pattern 3: Wagmi CLI Code Generation

For large projects, @wagmi/cli generates fully typed React hooks from your ABIs:

npm install --save-dev @wagmi/cli

// wagmi.config.ts
import { defineConfig } from '@wagmi/cli'
import { foundry, react } from '@wagmi/cli/plugins'

export default defineConfig({
  out: 'src/generated.ts',
  plugins: [
    foundry({ project: '../contracts' }),  // reads Foundry artifacts directly
    react(),                                // generates useReadMyToken, useWriteMyToken, etc.
  ],
})

npx wagmi generate   # regenerate on every contract change

Add to CI: npx wagmi generate && git diff --exit-code src/generated.ts — fails if ABI was changed but not regenerated.

Pattern 4: Proxy Contract ABIs

Proxy contracts (UUPS, Transparent) have two ABIs:

  1. Proxy ABI — just upgradeTo, upgradeToAndCall, admin functions
  2. Implementation ABI — your actual business logic

Always use the implementation ABI for user-facing calls, pointed at the proxy address:

// WRONG: using proxy ABI loses all your functions
const client = getContract({ address: proxyAddr, abi: proxyAbi })

// RIGHT: implementation ABI + proxy address
const client = getContract({ address: proxyAddr, abi: myContractV2Abi })

For Hardhat upgrades, the generated .json artifacts include the merged ABI automatically. For Foundry, merge manually:

# Merge proxy + implementation ABIs
jq -s '.[0].abi + .[1].abi | unique_by(.name)' \
  out/ERC1967Proxy.sol/ERC1967Proxy.json \
  out/MyContractV2.sol/MyContractV2.json \
  > frontend/src/abis/MyContractProxy.json

Pattern 5: CI/CD Enforcement

Block merges where ABI changed but frontend wasn't updated:

# .github/workflows/abi-check.yml
- name: Check ABI sync
  run: |
    forge build
    bash scripts/sync-abi.sh
    git diff --exit-code frontend/src/abis/
    # Fails if any ABI file was changed without committing the update

Common Failure Modes

SymptomCauseFix
function not found on-chainCalling old function name that was renamedRe-sync ABI, check function selector
TypeScript accepts wrong arg typeas const missing on ABIAdd as const to ABI definition
Proxy call revertsUsing proxy ABI instead of implementation ABIAlways use implementation ABI at proxy address
Works in dev, fails on mainnetABI from local build ≠ deployed contractPin ABI to verified deployment, not latest build
Wagmi hook types wrongGenerated file not up to dateRe-run npx wagmi generate

References

More in MCP Tools