/api/v1 reference
The explorer exposes a verification-ingest API at https://explorer.subfrost.io/api/v1. It has two routes: an open verify (sandbox rebuild → auto-promote on match) and an admin-only attest (direct write).
Authentication
The API key is part of the path: /api/v1/{apikey}/…. Keys are validated against the same subfrost:apikey:{key} store as mainnet.subfrost.io/v4/{key} – a key that works on the mainnet gateway works here. Get an API key →
- Any active key may call
verify. The verifier only promotes a source when the rebuilt wasm matches the on-chain bytecode, so a bad recipe just fails – nothing is trusted blindly. attestrequires an admin key (sfadm_…): the account hasadmin: true, or the key is listed in the server'sATTEST_ADMIN_KEYS.
This write surface fails closed: no valid key → 401. (This differs from the read gateway, which falls open to a rate-limited free tier.)
You rarely call these endpoints by hand:
alkanes-cli uploadmaps a BuildInfo onto the right body and POSTs it over a vendored h2 client (no curl). Thecurlexamples below are the raw-HTTP equivalents.
POST /api/v1/{key}/verify
Rebuild an alkane from a source recipe in the sandbox and diff against its on-chain bytecode. On a byte match the source auto-promotes to the alkane's verified-source panel.
Minimal recipe – the verifier auto-reverses the rest. You almost never need to fill the reproduction fixtures by hand. The verifier fetches the on-chain bytecode once and reverses the recipe out of it: the embedded panic paths carry the exact git-dep revs,
HOME, host triple, clang major, and rustc channel the origin built with, and the deploy tx's confirmation time gives the crates.io freeze date. So a body of just{ alkane, repo_url, commit, package, subdir }reproduces most alkanes on its own. Any field you do send overrides its auto-reversed value – supply one only to correct a mis-reversal.
Body – only alkane and repo_url are required; every remaining field is auto-reversed from the bytecode when omitted (send it only to override):
| Field | Notes |
|---|---|
alkane | Required. Alkane id as "block:tx" (e.g. "4:797"). |
repo_url | Required. Source git repo. |
commit | Commit / ref to build. |
package | Cargo package (-p). |
subdir | Sub-path within the repo, if the crate isn't at the root. |
rustc | rustc version (e.g. 1.82.0). |
alkanes_rev | Pinned alkanes-rs git rev. |
clang_version | clang version baked into producers (e.g. 14.0.0). |
home_dir | Build HOME (reconstructs registry/git/toolchain paths). |
freeze_commit | crates.io-index-archive commit for the registry time-machine. |
git_url | Explicit git dependency URL, when reconstructing a source-id. |
git_source_form | bare or rev – how the git dep's source-id was spelled in the lock. |
git_pins | Multiple git-dep pins at once – newline-separated url rev [bare|rev]. Pins every listed dep (a contract commonly pins both alkanes-rs and metashrew), which the single git_url/alkanes_rev pair can't express. Usually unnecessary: the auto-reverser derives these from the bytecode's checkout paths. |
git_date | Deploy date (YYYY-MM-DD or RFC3339). Date-freezes the crates.io index and any still-unpinned git dep to what existed then – the universal fix for a contract that ships no committed lock. Defaults to the deploy tx's block time. |
build_env | Extra build env vars. |
typo_fix | Normalizations applied before resolve (e.g. a malformed URL in Cargo.toml). |
Response – the verifier's JSON is passed through, including the verdict. A reproducible/verified verdict means the source is now promoted.
curl -sS -X POST https://explorer.subfrost.io/api/v1/$SUBFROST_API_KEY/verify \
-H 'content-type: application/json' \
-d '{
"alkane": "2:0",
"repo_url": "https://github.com/kungfuflex/alkanes-rs",
"commit": "fb11ee0e",
"package": "alkanes-std-genesis-alkane-upgraded-eoa",
"rustc": "1.86.0",
"clang_version": "20.1.7",
"home_dir": "/Users/kevinyao",
"git_source_form": "bare"
}'
The same alkane usually verifies from a minimal body – the verifier reverses the fixtures above (rustc, clang_version, home_dir, git pins, and the crates.io freeze) from the bytecode itself:
curl -sS -X POST https://explorer.subfrost.io/api/v1/$SUBFROST_API_KEY/verify \
-H 'content-type: application/json' \
-d '{
"alkane": "2:0",
"repo_url": "https://github.com/kungfuflex/alkanes-rs",
"commit": "fb11ee0e",
"package": "alkanes-std-genesis-alkane-upgraded-eoa"
}'
Errors: 401 invalid/inactive key, 400 bad alkane id / missing repo_url / bad JSON, 502 verifier unreachable.
POST /api/v1/{key}/attest admin
Directly record a bytecode → verified-source mapping without a sandbox rebuild. This exists for results proven out-of-band that the Linux verifier cannot itself reproduce byte-exact – the verified class: cross-host C-linking builds (e.g. 4:76 busd and the oyl implementations) whose host clang emits a slightly different secp256k1 C-object footprint. Admin-gated because it bypasses the diff check. alkanes-cli upload (without --verify) is the ergonomic way to call this – it sends the full BuildInfo as the manifest.
Body – repo_url required; identify the bytecode with either block+tx or wasm_sha256:
| Field | Notes |
|---|---|
block, tx | Alkane id parts (or use wasm_sha256). |
wasm_sha256 | Bytecode hash (alternative to block+tx). |
repo_url | Required. Source repo. |
commit, subdir, rustc, alkanes_rev | Source provenance, recorded verbatim. |
verdict | The attested verdict (e.g. verified). |
match_pct | Normalized match percentage. |
note | Free-text explanation of the residual. |
manifest | Optional structured manifest recorded with the attestation. |
curl -sS -X POST https://explorer.subfrost.io/api/v1/$SFADM_KEY/attest \
-H 'content-type: application/json' \
-d '{
"block": 4, "tx": 76,
"repo_url": "https://github.com/kungfuflex/alkanes-rs",
"verdict": "verified",
"match_pct": 99.997,
"note": "cross-host secp256k1 C-object memory-base residual (~6 bytes); logic + producers exact"
}'
Errors: 401 invalid key, 403 non-admin key, 400 missing repo_url or neither wasm_sha256 nor block+tx.