Source browser API

Every alkane the explorer has verified carries its exact source with it: the repo, the commit, and – for private repos – a byte-for-byte copy of the source tree the sandbox reproduced the on-chain wasm from. The source-browser API exposes that tree programmatically, so any surface can render the same file browser you see on explorer.subfrost.io/alkane/{id}/source for any alkane we know about.

There are three read endpoints under https://explorer.subfrost.io/api/v1, all keyed by alkane id:

The data model

One TypeScript module defines the whole model – app/api/_lib/alkane-sources.ts – and both the API routes and any front-end component import it:

• AlkaneSource – resolved provenance + verify status for an alkane: { alkane, block, tx, verified, verdict, match_pct, origin, repo, owner, name, commit, subdir, package, entrypoint, private, fileCount }.
• SourceTree – { alkane, origin, repo, commit, subdir, entrypoint, nodes: SourceNode[] }.
• SourceNode – one entry in the tree: { path, type: "blob" | "tree", size? } (the GitHub git/trees shape).
• SourceBlob – one file's contents: { alkane, path, bytes, truncated, binary, text, base64? }. text is null for a binary or oversized file; binary files served from our DB carry a base64 payload instead.

Where the mapping lives

There is no static alkane → repo table. The mapping is resolved dynamically from the verifier – the same lookup the /verify route and the alkane source page use. When an alkane verifies, its VerificationRun records repo_url, commit, package, and (for private repos) an inline copy of the source. resolveSource(block, tx) reads that run and picks a serving origin:

• db – the verified source is served from our own build database (manifest.source.inline_files). This is the exact source the sandbox reproduced, and it works even when the origin repo is private – no GitHub call. Takes priority.
• github – a public repo, read live at the verified commit through the GitHub git/trees API (tree) and raw.githubusercontent.com (blob), cached by commit sha.
• none – the alkane has no verified source. The endpoints return 404.

Because the resolution keys off the verification record, an alkane only becomes browsable here after it verifies. To make one browsable, submit its source via /verify or alkanes-cli; a reproducible/verified verdict auto-promotes it.

Authentication

Same as the rest of the /api/v1 surface: the API key is a path segment – /api/v1/{apikey}/source/… – validated against the same subfrost:apikey:{key} store as mainnet.subfrost.io/v4/{key}. Auth is enforced at the tlsd edge-auth filter (which injects a trusted identity), with an in-process key check as fallback, so the rollout is order-independent. No separate secret. Any active key may read. Get an API key →

No valid key → 401.

GET /api/v1/{key}/source/{block}/{tx}

Provenance + verify status for an alkane's source, plus the entrypoint file a client should open first.

curl -sS https://explorer.subfrost.io/api/v1/$SUBFROST_API_KEY/source/2/0

{
  "ok": true,
  "source": {
    "alkane": "2:0",
    "block": "2",
    "tx": "0",
    "verified": true,
    "verdict": "reproducible",
    "match_pct": 100.0,
    "origin": "github",
    "repo": "https://github.com/kungfuflex/alkanes-rs",
    "owner": "kungfuflex",
    "name": "alkanes-rs",
    "commit": "fb11ee0e",
    "package": "alkanes-std-genesis-alkane-upgraded-eoa",
    "entrypoint": "src/lib.rs",
    "private": false,
    "fileCount": 214
  }
}

Errors: 401 invalid/inactive key, 400 bad alkane id, 404 no verified source, 502 verifier unreachable.

GET /api/v1/{key}/source/{block}/{tx}/tree

The full recursive file listing at the verified commit. nodes mirrors the GitHub git/trees shape – both blob (file) and tree (directory) entries, with size in bytes for blobs.

curl -sS https://explorer.subfrost.io/api/v1/$SUBFROST_API_KEY/source/32/0/tree

{
  "ok": true,
  "tree": {
    "alkane": "32:0",
    "origin": "db",
    "repo": "https://github.com/subfrost/subfrost-alkanes",
    "commit": "0748786d",
    "subdir": "crates/fr-btc",
    "entrypoint": "crates/fr-btc/src/lib.rs",
    "nodes": [
      { "path": "Cargo.toml", "type": "blob", "size": 412 },
      { "path": "crates", "type": "tree" },
      { "path": "crates/fr-btc", "type": "tree" },
      { "path": "crates/fr-btc/src/lib.rs", "type": "blob", "size": 18422 }
    ]
  }
}

Errors: 401, 400, 404 no verified source, 502 the listing failed (repo private on GitHub, deleted, or rate-limited).

GET /api/v1/{key}/source/{block}/{tx}/blob?path=…

The contents of one file. path must be a blob path from the tree. Returns a JSON SourceBlob by default; pass ?raw=1 for the raw bytes (text/plain, or application/octet-stream for a binary file).

curl -sS "https://explorer.subfrost.io/api/v1/$SUBFROST_API_KEY/source/2/0/blob?path=src/lib.rs"

{
  "ok": true,
  "blob": {
    "alkane": "2:0",
    "path": "src/lib.rs",
    "bytes": 18422,
    "truncated": false,
    "binary": false,
    "text": "use alkanes_runtime::runtime::AlkaneResponder;\n..."
  }
}

Raw bytes, for piping straight into a file or an editor pane:

curl -sS "https://explorer.subfrost.io/api/v1/$SUBFROST_API_KEY/source/2/0/blob?path=src/lib.rs&raw=1"

A file over 512 KB comes back with truncated: true (text sliced to the cap). Binary files served from the DB carry a base64 payload and text: null; ?raw=1 streams them as application/octet-stream.

Errors: 401, 400 bad alkane id / missing path, 404 no verified source or path not in tree, 502 upstream read failed.

Embedding the browser

The model maps one-to-one onto a two-pane browser (file tree + viewer):

1. GET …/source/{block}/{tx} – read entrypoint; if verified is false or you get 404, show "not verified yet".
2. GET …/tree – render nodes as a collapsible tree (fold blob paths on / into directories; tree nodes give you the empty dirs).
3. On file click, GET …/blob?path=… – render text with line numbers; if binary, show a "binary file" placeholder (or decode base64).

This is exactly what the explorer's own SourceBrowser component does – it consumes the same SourceNode / SourceBlob types from app/api/_lib/alkane-sources.ts.