Crate kascov_decode

Expand description

Name Kaspa covenant programs from their bytes.

This is the decoder behind every name kascov.io shows. A covenant’s output commits to a program by hash (P2SH), and the spend that consumes it reveals the program as the last push of its signature script. Given those bytes, this crate says what the program is: which SilverScript or Argent build, which launchpad, market or token family, and what sits in its labelled fields. It reads nothing but the bytes it is given: no node, no network, no database.

use kascov_decode::{p2sh_reveal, Registry};

// a KaspaCom token program on testnet-10, and the signature script of
// the spend that revealed it (fixtures/PROVENANCE.md says where each
// came from)
let program = include_bytes!("../fixtures/recovery/kcom_2671_parent_56fc521e_0.bin");
let spend = include_bytes!("../fixtures/recovery/kcom_witness_7d5f35f0.bin");

let decoded = Registry::default().decode(0, program);
assert_eq!(decoded.template, Some("KaspaCom · token"));

// the output that spend consumed commits to the program's BLAKE2b-256
let hash = blake2b_simd::Params::new().hash_length(32).hash(program);
let spk = [&[0xaa, 0x20][..], hash.as_bytes(), &[0x87]].concat();
assert_eq!(p2sh_reveal(&spk, spend).as_deref(), Some(&program[..]));

Where to start:

Registry tries each template decoder in turn. When none matches, the always-correct fallback is a plain opcode disassembly.
report gives the answers of the kascov-decode command as JSON.
p2sh_reveal checks a spend’s revealed program against the output it spends, the same test kascov runs on every spend.
argent recognizes programs Argent generated and computes the template hash that names their build.
kcc20 and kcc0020 read token cells; kcc1 holds the KCC-0001 byte layouts and hashes they build on.
disasm is the opcode table and disassembler, covenant and ZK opcodes included.

Modules§

argent: ARGENT build recognition: deciding, from bytes alone, whether a revealed program came out of argent’s code generator, which generation of the SilverScript compiler lowered it, and cutting it into the (head, state, code) split whose §8.3 TemplateHash names its BUILD.
disasm: Kaspa Script disassembler, covering the post-Toccata opcode set (KIP-17 introspection + covenant + ZK opcodes included).
kcc0020: KCC-0020 conformance primitives — the merged token convention (kaspanet/kccs, Draft at commit ea5176aa), byte layouts only.
kcc1: KCC-0001 conformance primitives — byte layouts and hash derivations from “Covenant definition, concepts, bytes layout and ABI” (kaspanet/kccs, merged Draft at commit ea5176aa). Section numbers in doc comments refer to that text. Invocation arguments use PushMinimal, which is encode_push in the crate root; only the KCC1-specific encodings live here.
kcc20: KCC20 state-level helpers: typed access to the “KCC20 token” state fields and the splice-and-hash primitive that proves an output’s hidden state.
observed: Skeletons derived from real revealed programs observed on chain.
report: The answers the kascov-decode command gives, as values, so that every front end (the command, the WebAssembly build) says the same thing about the same bytes. Nothing here reads anything but its arguments.
vesting: Proving a creator through a KRON vesting lock.

Structs§

Decoded: What a decoder could make of a covenant state script.
DisasmDecoder: Fallback: full disassembly. Always succeeds.
Field: A labeled state field extracted by a template decoder.
P2pkStateDecoder: <push 32/33 bytes> OpCheckSig — the plain pay-to-pubkey state carried by most covenants observed on TN10 (and the [[Covenant Lab]] ones).
P2shCommitmentDecoder: OpBlake2b <32-byte hash> OpEqual — a P2SH commitment: the program is revealed at spend time (see p2sh_reveal).
Registry: Try registered decoders in order, ending with the disassembly fallback.
RepeatSkeleton: A compiled-contract family whose builds differ only by how many times one instruction block repeats (e.g. genesis0’s slot-mint emits one amount+script check per collection output). Matched as prefix · group×N · suffix with N >= min_repeats; the group’s pushes are per-repeat slots, so every arity of the family decodes to one name.
Skeleton
TemplateDecoder: Matches compiled contracts against known skeletons.

Constants§

SILVERSCRIPT_DUMPS: Every embedded SilverScript example dump as (family name, generation, dump A, dump B), in registration order. The web port (web/disasm.js) mirrors this table byte for byte and its test reads it from here.
SILVERSCRIPT_GENERATIONS: The SilverScript compiler generations kascov can name, as (generation id, repository and revision). The id is what a Skeleton::generation, a Decoded::generation and the worker’s /compile report carry; the revision is the commit the dumps of that generation were produced with.
SILVERSCRIPT_GEN_D25BD34: kaspanet/silverscript at d25bd34: the generation the first dumps came from. Dispatches on a numeric selector and ends an entrypoint chain with 67 75 00 69. No worker ships it; old on-chain reveals match it.
SILVERSCRIPT_GEN_FORK: michaelsutton/silverscript at d57e5dff, the rev argent 05ba4b2 pins and the compiler behind kascov’s stdin wrapper (tools/silverc). Numeric selector, 6a terminator, 36-byte P2PK locks built by one OpCat less.
SILVERSCRIPT_GEN_V1: kaspanet/silverscript v1.0.0 (3ed9733), the upstream silverc CLI. Dispatches on a four-byte KCC-1 tag (76 04 <tag> 87 63 75), checks pubkey/sig argument sizes in-script, and hashes with BLAKE3.

Traits§

StateDecoder

Functions§

encode_push: Canonical push encoding — the bytes the SilverScript compiler’s ScriptBuilder emits for a pushed value. Mirrors encodePush in web/disasm.js; used to re-encode argument slots when emitting a contract.
p2sh_hash: The committed hash of a canonical Kaspa P2SH script-public-key (OpBlake2b OpData32 <hash> OpEqual), if spk has that shape.
p2sh_reveal: Spend-time reveal: when a P2SH state UTXO is spent, the signature script’s final push is the program the covenant actually ran. Returns it only if its blake2b-256 matches the committed hash.
silverscript_sentinels: The dump-A sentinel values of one example family, labelled in constructor order. Shared by every generation of the family.
silverscript_skeletons: One skeleton per (family, generation) in SILVERSCRIPT_DUMPS order: the d25bd34 cut of each family first, so a caller that takes the first skeleton of a name (kascov-labkit’s demos) keeps emitting the bytes it always did.
snum: Minimal script-number encoding of the sentinel ints used in the dumps. Minimal script-number (little-endian, sign-guard) encoding of a non-negative integer — used for pledge/period args and entrypoint selectors when emitting a contract or building a spend witness.
x402_skeletons: The kaspa-x402 payment-channel skeletons. Separate from the silverscript example contracts: same compiler, different project, and alpha releases may re-cut the template — a new generation gets a NEW derive here, never an edit of this one, so already-closed channels keep decoding.
zk_system: Guess which zero-knowledge proving system a covenant script hands to OpZkPrecompile (KIP-16, opcode 0xa6). Best effort: the verifier pops a verifying key, a proof, and public inputs off the stack, so the data pushes in the program encode those shapes. We key on the two systems’ very different proof sizes and prefer None over a shaky guess.