alkanes-cli guide

alkanes-cli ships a BuildInfo workbench – subcommands that reverse an alkane's build environment from its bytecode, reconstruct the wasm in a controlled sandbox, diff the two, and upload the result to the explorer. The output is a single self-contained BuildInfo JSON (schema 1.0.0) that fully specifies how to reproduce one alkane's on-chain wasm. The explorer's verifier consumes the same recipe, so a result you get locally is the same computation the explorer runs.

Status: the workbench is merged into kungfuflex/alkanes-rs (develop + main). The BuildInfo types and CLI live in crates/alkanes-cli-common/src/buildinfo/; the upload HTTP path lives in crates/alkanes-cli-sys behind the attest-upload feature (kept out of alkanes-web-sys so the wasm build stays lean). The released alkanes-cli binary enables both by default.

Install

Build the CLI from source – the workbench and upload are on by default, no extra features needed:

git clone https://github.com/kungfuflex/alkanes-rs
cd alkanes-rs
cargo build --release -p alkanes-cli
# binary at ./target/release/alkanes-cli

The build/build-info steps drive a Docker sandbox, so Docker must be available for those. reverse, verify, and upload are fully offline of Docker (upload just POSTs the JSON over HTTPS).

Subcommands

--at accepts either an alkane id (block:tx, fetched via --jsonrpc-url) or a local .wasm path. Offline is the default – jsonrpc is only needed to fetch an on-chain target.

The end-to-end workbench flow is build-info → upload: produce the recipe, then submit it.

1. Reverse – read the build environment out of the bytecode

# From a local .wasm (fully offline):
alkanes-cli build-info reverse --at ./free_mint.wasm --emit reversed.json

# From an on-chain id (fetches getbytecode via jsonrpc):
alkanes-cli -p mainnet --jsonrpc-url https://mainnet.subfrost.io/v4/jsonrpc \
  build-info reverse --at 4:797

The stderr readout summarizes what the wasm reveals: rustc, clang_vendor/clang_version, home, host_triple, and whether it links C.

2. build-info – the full pipeline

Point it at a git checkout of the alkane's source and the target, and it reverses, rebuilds in the sandbox, diffs, and emits the complete BuildInfo:

alkanes-cli -p mainnet --jsonrpc-url https://mainnet.subfrost.io/v4/jsonrpc \
  build-info ./free-mint --at 4:797 \
  --repo https://github.com/kungfuflex/free-mint \
  --package free-mint \
  --emit build-info.json

Flags: --repo, --commit, --package (-p in cargo terms), --features (comma-separated, e.g. mainnet), --emit.

3. build – reconstruct a wasm from a recipe

alkanes-cli build-info build build-info.json --out built.wasm
# built built.wasm (297481 bytes, sha256=8b51384a…)

4. verify – diff a candidate against the target

alkanes-cli build-info verify --at 4:797 built.wasm

For 4:797 this reports byte-exact (verdict reproducible). For a C-linking cross-host build like 4:76 (busd) it reports verified with the secp256k1 residual explained.

5. upload – submit a BuildInfo to the explorer

upload is the primary way to submit a recipe. It POSTs the BuildInfo JSON over the vendored tlsfetch h2 client (no curl, no reqwest) to <explorer-url>/api/v1/<key>/{attest,verify}:

# Default = attest: record the BuildInfo's verdict directly (admin `sfadm_…` key;
# the full BuildInfo is sent as the attestation `manifest`).
alkanes-cli upload build-info.json --api-key $SFADM_KEY

# --verify: POST the full fixture set to /verify so the server rebuilds + diffs.
alkanes-cli upload build-info.json --api-key $SUBFROST_API_KEY --verify

Flags: --api-key <KEY> (required), --explorer-url <url> (defaults to https://explorer.subfrost.io; must be https – the h2 client is TLS-only), --verify (switch from attest to a sandbox rebuild).

• attest (default) is admin-gated – it writes the verdict without a server-side rebuild, so it needs an sfadm_… admin key. Used for builds the Linux verifier can't reproduce byte-exact on its own.
• --verify works with any active key – the server rebuilds in-sandbox and only promotes on a match.

The BuildInfo artifact

A BuildInfo captures every axis that matters for a byte-exact rebuild. Abbreviated shape (see the JSON Schema build-info.schema.json in the crate for the full definition):

{
  "schema_version": "1.0.0",
  "identity":  { "target_source": "onchain", "alkane_id": "4:797", "target_sha256": "8b51384a…" },
  "source":    { "kind": "git", "repo": "…/free-mint", "commit": "e33d5e8", "package": "free-mint",
                 "build_command": "cargo build --release --locked --target wasm32-unknown-unknown -p free-mint" },
  "toolchain": { "rustc_version": "1.82.0", "host_triple": "1.82.0-x86_64-unknown-linux-gnu" },
  "c_toolchain": { "vendor": "Ubuntu", "version": "14.0.0",
                   "source": { "method": "apt", "apt_package": "clang-14" }, "c_object_host_dependent": false },
  "environment": { "home": "/home/lee" },
  "registry":  { "mode": "time-machine", "served_as": "index.crates.io",
                 "registry_hash": "index.crates.io-6f17d22bba15001f" },
  "git_deps":  [ { "url": "…/alkanes-rs", "rev": "d787cdd1…", "source_form": "bare" } ],
  "result":    { "verdict": "reproducible", "byte_exact": true, "normalized_match_pct": 100.0 }
}

Each axis is explained in Reproducible builds explained.

Submitting a result to the explorer

Use alkanes-cli upload (above) – it maps the BuildInfo onto the right request body for you and posts it over the vendored h2 client. That's how the ~30 alkanes verified this session were published.

If you'd rather hit the HTTP API directly (e.g. from a script without the CLI), the same POST /api/v1/{key}/verify endpoint accepts the fixture fields as raw JSON – a curl equivalent of upload --verify:

curl -sS -X POST https://explorer.subfrost.io/api/v1/$SUBFROST_API_KEY/verify \
  -H 'content-type: application/json' \
  -d '{
    "alkane": "4:797",
    "repo_url": "https://github.com/kungfuflex/free-mint",
    "commit": "e33d5e8",
    "package": "free-mint",
    "rustc": "1.82.0",
    "clang_version": "14.0.0",
    "home_dir": "/home/lee",
    "alkanes_rev": "d787cdd1f22ef1b7e32337fc531209df85ed1db8",
    "git_source_form": "bare"
  }'

Most of those fields are optional over the wire: the server auto-reverses the recipe (rustc, clang, HOME, host triple, git-dep revs, and the crates.io freeze) from the on-chain bytecode, so { alkane, repo_url, commit, package } alone verifies most alkanes – anything you send just overrides an auto value. The endpoint additionally accepts git_pins (multi-dep url rev [bare|rev] lines) and git_date (deploy-date freeze) for contracts that pin several git deps or ship no committed lock. See the /api/v1 reference for the full field list and the admin-only attest path.