Anvil Sol

0.3.4 verified Fri May 01 auth: no javascript

Anvil is a CLI tool that transpiles Anchor-based Solana programs to Pinocchio, native (solana-program), or Quasar Rust dialects, producing cargo-buildable projects from a single typed IR. Current stable version is 0.3.4, released with a weekly cadence. Key differentiators: deterministic emit with a validator, portability linting, CU benchmarking, and a migration safety analysis tool. Requires Bun >=1.0.0 and depends on litesvm, @solana/web3.js, and @noble/hashes as peer dependencies. Supports three targets with regression gates (21+ MUST_PASS for pinocchio and native).

Common errors

error bun: command not found ↓

cause Bun is not installed or not in PATH.

fix

Run 'curl -fsSL https://bun.sh/install | bash' to install Bun.

error Error: Cannot find module 'anvil-sol' ↓

cause Package not installed or wrong import path.

fix

Install globally with 'bun install -g anvil-sol' or run with 'bunx anvil-sol'.

error TypeError: anvil is not a function ↓

cause Using default import incorrectly; named exports are required.

fix

Use named imports like '{ compile }' instead of default import.

Warnings

breaking Requires Bun >=1.0.0 — Node.js and npm are not supported. ↓

fix Install Bun from https://bun.sh before using anvil-sol.

breaking ESM-only module — CommonJS require() will fail. ↓

fix Use import syntax or run via Bun which supports ESM.

gotcha Quasar target is experimental; cargo-build may fail and some CPIs emit TODO stubs. ↓

fix Use pinocchio or native targets for production.

deprecated The `anvil migrate diff` command is new in 0.3; older versions don't have it. ↓

fix Upgrade to >=0.3.0 for migration support.

Install

npm install anvil-sol

yarn add anvil-sol

pnpm add anvil-sol

Imports

default

wrong

const anvil = require('anvil-sol');

correct

import anvil from 'anvil-sol';

ESM-only; ESM support only from v0.3+.

compile

wrong

import { compile } from 'anvil-sol/compile';

correct

import { compile } from 'anvil-sol';

Named export; subpath imports not supported.

lint

wrong

const { lint } = await import('anvil-sol');

correct

import { lint } from 'anvil-sol';

Also top-level named export.

Quickstart

Shows installation, transpilation to Pinocchio, parsing to IR, portability linting, CU benchmarking, snapshotting, diffing, and migration analysis.

// Install globally
bun install -g anvil-sol

# Transpile an Anchor program to Pinocchio
anvil compile program.rs --target pinocchio --output ./out
cd ./out && cargo build

# Parse to IR
anvil parse program.rs --json

# Portability lint
anvil lint program.rs --target pinocchio

# Benchmark CU
anvil bench program.rs

# Snapshot CUs
anvil snapshot program.rs

# Diff IRs
anvil diff old.ir.json new.ir.json

# Migration analysis
anvil migrate diff old-layout.json new-layout.json
anvil migrate codegen old-layout.json new-layout.json --output migration.rs