@blockula/sdk 0.5.1 → 1.0.0

package/dist/proof.d.ts

@@ -21,6 +21,12 @@ export declare const NAMESPACES: {
     readonly GRANTS: 25;
     readonly RESERVED_NAMES: 43;
     readonly FEATURES: 47;
+    /** A program's record, keyed by its address as a string (as accounts are). */
+    readonly PROGRAMS: 66;
+    readonly PROGRAM_CODE: 67;
+    readonly PROGRAM_INTERFACES: 68;
+    readonly PROGRAM_STORAGE: 69;
+    readonly PROGRAM_BLOB_REFS: 72;
 };
 /** Hash of an empty subtree. */
 export declare const EMPTY_HASH: Uint8Array<ArrayBuffer>;
@@ -124,3 +130,41 @@ export interface NameRecord {
     grace_blocks?: number;
 }
 export declare function decodeName(value: Uint8Array): NameRecord;
+/**
+ * A program's record as the state holds it (node/src/programs/state.rs `ProgramRecord`, format 1),
+ * decoded from the value `/api/proof/66/{address}` proves. `version_digest` isn't in the record:
+ * `Client.provenProgram` computes it from the record's own fields (`versionDigest`).
+ */
+export interface ProgramRecord {
+    /** The account whose transaction created it. */
+    creator: string;
+    created_at: number;
+    /** Lowercase hex, 64 characters. */
+    wasm_hash: string;
+    interface_hash: string;
+    version: number;
+    /** Stored as created, with no power until program upgrades exist. */
+    authority: string | null;
+    upgrade_delay_blocks: number;
+    /** 0 open, 1 additive. */
+    policy: "open" | "additive";
+    accepts_transfers: boolean;
+    /** Its storage entries: how many, Σ their accounted bytes, Σ their deposits (drops, as decimal strings). */
+    storage: {
+        items: number;
+        bytes: number;
+        deposit: string;
+    };
+    /** The part of those deposits the program paid itself. */
+    sponsored: string;
+    /** What its creator bonded for the record itself, and who. */
+    record_deposit: string;
+    record_payer: string;
+}
+/**
+ * Decodes a program record: the format byte (1: the only format this SDK reads, as the node's
+ * `Versioned` does) and the borsh body, field by field in the order the node writes them. Refuses
+ * a format it doesn't know, a bool or an option tag that isn't 0 or 1, text that isn't UTF-8 and
+ * bytes left over, so what it returns is what the state holds.
+ */
+export declare function decodeProgram(value: Uint8Array): ProgramRecord;

package/dist/proof.js

@@ -30,6 +30,13 @@ export const NAMESPACES = {
     // 44–46, upgrade 47); see node/src/state/mod.rs for what each holds.
     RESERVED_NAMES: 43,
     FEATURES: 47,
+    // Programs (protocol v2, docs/PROGRAMS-V0.md §4.1): empty until programs first switch on.
+    /** A program's record, keyed by its address as a string (as accounts are). */
+    PROGRAMS: 66,
+    PROGRAM_CODE: 67,
+    PROGRAM_INTERFACES: 68,
+    PROGRAM_STORAGE: 69,
+    PROGRAM_BLOB_REFS: 72,
 };
 /** Hash of an empty subtree. */
 export const EMPTY_HASH = new Uint8Array(32);
@@ -196,6 +203,20 @@ class Reader {
         this.at += 8;
         return v;
     }
+    /** `n` raw bytes. */
+    fixed(n) {
+        this.need(n);
+        const v = this.b.subarray(this.at, this.at + n);
+        this.at += n;
+        return v;
+    }
+    /** A borsh bool: one byte, 0 or 1 and nothing else. */
+    bool() {
+        const v = this.u8();
+        if (v > 1)
+            throw new Error(`record holds ${v} where a bool should be`);
+        return v === 1;
+    }
     str() {
         const n = this.u32();
         this.need(n);
@@ -253,3 +274,44 @@ export function decodeName(value) {
     rec.grace_blocks = sat(r.u64());
     return rec;
 }
+/** A number the record holds as a u64, which must be one JSON and JS carry exactly. */
+const exactCount = (v, what) => {
+    if (v > BigInt(Number.MAX_SAFE_INTEGER))
+        throw new Error(`a program record's ${what} (${v}) is past 2^53 − 1, which this SDK can't carry exactly`);
+    return Number(v);
+};
+/**
+ * Decodes a program record: the format byte (1: the only format this SDK reads, as the node's
+ * `Versioned` does) and the borsh body, field by field in the order the node writes them. Refuses
+ * a format it doesn't know, a bool or an option tag that isn't 0 or 1, text that isn't UTF-8 and
+ * bytes left over, so what it returns is what the state holds.
+ */
+export function decodeProgram(value) {
+    const r = new Reader(value);
+    const format = r.u8();
+    if (format !== 1)
+        throw new Error(`program record format ${format}: this SDK reads format 1`);
+    const creator = r.str();
+    const created_at = exactCount(r.u64(), "created_at");
+    const wasm_hash = bytesToHex(r.fixed(32));
+    const interface_hash = bytesToHex(r.fixed(32));
+    const version = r.u32();
+    const hasAuthority = r.u8();
+    if (hasAuthority > 1)
+        throw new Error(`a program record's authority has option tag ${hasAuthority}`);
+    const authority = hasAuthority === 1 ? r.str() : null;
+    const upgrade_delay_blocks = exactCount(r.u64(), "upgrade_delay_blocks");
+    const policyByte = r.u8();
+    if (policyByte > 1)
+        throw new Error(`a program record's policy is ${policyByte}: this SDK knows open (0) and additive (1)`);
+    const accepts_transfers = r.bool();
+    const items = exactCount(r.u64(), "items");
+    const bytes = exactCount(r.u64(), "bytes");
+    const deposit = r.u64().toString();
+    const sponsored = r.u64().toString();
+    const record_deposit = r.u64().toString();
+    const record_payer = r.str();
+    if (r.at !== value.length)
+        throw new Error("a program record has bytes after its last field");
+    return { creator, created_at, wasm_hash, interface_hash, version, authority, upgrade_delay_blocks, policy: policyByte === 0 ? "open" : "additive", accepts_transfers, storage: { items, bytes, deposit }, sponsored, record_deposit, record_payer };
+}

package/dist/tx.d.ts

@@ -321,7 +321,93 @@ export type Action = {
     type: "admit_validator";
     validator: string;
     epoch: number;
+}
+/**
+ * Upload a program's code (WebAssembly 1.0) and its interface (format 1), both lowercase hex,
+ * bonding a storage deposit for each that isn't stored yet: at most `storage_limit` drops. The
+ * code is usable from the block after the upload's; a create names the two by their hashes
+ * (`wasmHash`, `interfaceHash`).
+ */
+ | {
+    type: "upload_code";
+    wasm: string;
+    interface: string;
+    storage_limit: string;
+}
+/**
+ * Create a program from stored code and interface, named by their hashes (64 lowercase hex). Its
+ * address is `programAddress(from, nonce)`: don't send FANG there before the create has applied
+ * (a failed create spends its nonce, stranding whatever was sent). `authority` (an address, or
+ * null for an immutable program), `upgrade_delay_blocks` and `policy` are stored with no power
+ * until program upgrades exist; an immutable program has delay 0 and policy "open". `init` runs
+ * the interface's `Init` method, present exactly when the interface declares one; without it,
+ * `fuel_limit` is 0 and there are no bindings.
+ */
+ | {
+    type: "create_program";
+    wasm_hash: string;
+    interface_hash: string;
+    authority?: string | null;
+    upgrade_delay_blocks: number;
+    policy: ProgramPolicy;
+    accepts_transfers: boolean;
+    init?: InitCall | null;
+    fuel_limit: number;
+    storage_limit: string;
+    bindings: ProgramBinding[];
+}
+/**
+ * Call programs: 1–8 calls run in order, all or nothing, sharing `fuel_limit` (1 to 20,000,000,
+ * and at most the chain's `program_max_tx_fuel`) and `storage_limit` (the most their storage
+ * deposits may bond, drops). Each call names the `versionDigest` of the program it was shown. The
+ * code a call may reach is the calls' own programs' and the `bindings`'.
+ */
+ | {
+    type: "call_program";
+    calls: ProgramCall[];
+    fuel_limit: number;
+    storage_limit: string;
+    bindings: ProgramBinding[];
+}
+/** An active validator (from its own account or its owner's) votes to pause programs; they pause once f + 1 of the epoch's validators have. */
+ | {
+    type: "programs_pause";
 };
+/**
+ * What a `create_program`'s authority may later do to it, once program upgrades exist (inert in
+ * v0; node/src/types.rs `ProgramPolicy`): replace its code freely ("open"), or only with code
+ * whose interface keeps every method ("additive").
+ */
+export type ProgramPolicy = "open" | "additive";
+/**
+ * A `create_program`'s initializer (node/src/types.rs `InitCall`): the interface's `Init` method,
+ * its input (lowercase hex) and the FANG sent with it (drops; only if the method is payable).
+ */
+export interface InitCall {
+    method: string;
+    input: string;
+    value: string;
+}
+/**
+ * One call of a `call_program` (node/src/types.rs `ProgramCall`): a program (by address), the
+ * `versionDigest` of it the signer was shown (never 64 zeros), a method of kind `Call`, its input
+ * (lowercase hex) and the FANG sent with it (drops; only if the method is payable).
+ */
+export interface ProgramCall {
+    program: string;
+    version_digest: string;
+    method: string;
+    input: string;
+    value: string;
+}
+/**
+ * A program whose code a program action may reach besides its calls' own (node/src/types.rs
+ * `Binding`): by address, at the version digest given, or at any version for 64 zeros.
+ */
+export interface ProgramBinding {
+    program: string;
+    version_digest: string;
+}
 /**
  * What a ghost action carries (node/src/types.rs `GhostBundle`), every field lowercase hex: the
  * chain `instance` (from `/api/ghost`), the `anchor` root, two 32-byte `nullifiers` and
@@ -467,6 +553,8 @@ export declare const u64Field: (v: unknown, what?: string) => bigint;
 export declare function genesisHashBytes(genesisHash: string): Uint8Array;
 /** Unsigned ghost txs (`private_transfer`, `unshield`): no key signs them, their proof authorizes them. */
 export declare function isUnsignedAction(a: Action): boolean;
+/** A program action (tags 62–64 and 69, node/src/types.rs `Action::is_program`). */
+export declare function isProgramAction(a: Action): boolean;
 /**
  * The bytes a key signs (node/src/types.rs `Tx::signing_bytes`). For an unsigned ghost tx this is
  * its whole wire form instead: `BLOCKULA_GHOST_V1 ‖ chain_id ‖ genesis hash ‖ fee ‖ tip ‖ valid_until ‖ action`.
@@ -505,6 +593,53 @@ export declare function actionDigest(action: Action): string;
  * stored, resolved), title and link. Compute it from the proposal you show the voter.
  */
 export declare function proposalDigest(kind: ProposalKind, title: string, url?: string): string;
+/**
+ * The contexts of programs' five digests, each BLAKE3 in derive-key mode: node/src/programs/digest.rs
+ * `CODE_CONTEXT`, `INTERFACE_CONTEXT`, `VERSION_CONTEXT` and `ADDRESS_CONTEXT`, and the VM's
+ * `SELECTOR_CONTEXT` (node/vm/src/interface.rs), the selector's only home on the node.
+ */
+export declare const PROGRAM_DIGEST_CONTEXTS: Readonly<{
+    code: "blockula program code v1";
+    interface: "blockula program interface v1";
+    version: "blockula program version v1";
+    address: "blockula program address v1";
+    method: "blockula program method v1";
+}>;
+/** Every v0 program's version (node/src/programs/digest.rs `FIRST_VERSION`): only a program upgrade, in a later protocol version, raises it. */
+export declare const FIRST_PROGRAM_VERSION = 1;
+/**
+ * The hash that names a program's code (node/src/programs/digest.rs `wasm_hash`): BLAKE3-KDF("blockula
+ * program code v1", wasm), as 64 lowercase hex. A `create_program` names its code by it, once an
+ * `upload_code` of the same bytes (as bytes, or lowercase hex) has applied.
+ */
+export declare function wasmHash(wasm: Uint8Array | string): string;
+/** The hash that names an interface, its format-1 bytes (node/src/programs/digest.rs `interface_hash`): as `wasmHash`, under "blockula program interface v1". */
+export declare function interfaceHash(iface: Uint8Array | string): string;
+/**
+ * What a call to `program` binds (node/src/programs/digest.rs `version_digest`): BLAKE3-KDF("blockula
+ * program version v1", the program's address as a string field (u16 LE length, its bytes) ‖ its
+ * code's hash ‖ its interface's hash ‖ its version, u32 LE), as 64 lowercase hex. A call runs only
+ * while this is the program's digest in force, so it runs the code its signer was shown: compute it
+ * from the record you show (its hashes and version), rather than sign a digest a node reported.
+ */
+export declare function versionDigest(program: string, wasmHashHex: string, interfaceHashHex: string, version?: number): string;
+/**
+ * The address of the program `creator` creates with its transaction of `nonce` (node/src/programs/digest.rs
+ * `program_address`): bech32m(prefix, BLAKE3-KDF("blockula program address v1", the creator's 32
+ * address bytes ‖ nonce u64 LE)). `prefix` defaults to the creator's own (a chain admits only its
+ * prefix, so for any create it runs the two are the same).
+ *
+ * Don't send FANG to it before the create has applied: a create that fails spends its nonce, no
+ * later create reaches the address, and what was sent there is stranded for good (docs/PROGRAMS-V0.md
+ * §2.3). Fund a program through its initializer's value, or by transfer once it exists.
+ */
+export declare function programAddress(creator: string, nonce: number | bigint | string, prefix?: string): string;
+/**
+ * A method's selector (node/vm/src/interface.rs `selector`): the first 8 bytes of
+ * BLAKE3-KDF("blockula program method v1", its name), as 16 lowercase hex. An interface's methods
+ * have distinct selectors. Only identifiers are method names, so anything else is refused.
+ */
+export declare function methodSelector(name: string): string;
 /** One claim of a Séance pair, as the juror judged it. */
 export interface SeanceClaimRef {
     id: number;

package/dist/tx.js

@@ -1,6 +1,7 @@
 // Canonical transaction encoding. Must stay byte-identical to node/src/types.rs `Tx::signing_bytes`.
 import { blake3 } from "@noble/hashes/blake3.js";
 import { bytesToHex, concatBytes, hexToBytes } from "@noble/hashes/utils.js";
+import { bech32m } from "@scure/base";
 export const PUBLIC_KEY_LEN = 1952;
 export const SIGNATURE_LEN = 3309;
 /** Domain of the unsigned ghost wire form (`private_transfer`, `unshield`). */
@@ -57,6 +58,24 @@ export function uintField(v, max, what = "integer field") {
 }
 /** A u64 field (`uintField` up to 2^64 − 1). */
 export const u64Field = (v, what) => uintField(v, U64_LIMIT - 1n, what);
+/**
+ * A bytes field as the node's JSON carries it (node/src/types.rs `HexBytes`): lowercase hex, two
+ * digits a byte. The node's parser refuses uppercase and odd lengths, so this does too, instead of
+ * signing bytes the node can't read back from the JSON.
+ */
+function lowerHexBytes(v, what) {
+    if (typeof v !== "string")
+        throw new TypeError(`${what} must be a string of lowercase hex`);
+    if (!/^(?:[0-9a-f]{2})*$/.test(v))
+        throw new Error(`${what} must be lowercase hex, two digits a byte`);
+    return hexToBytes(v);
+}
+/** An entry of a list field (a program call, a binding, an initializer): a JSON object. */
+function fields(v, what) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        throw new TypeError(`${what} must be an object`);
+    return v;
+}
 class Writer {
     parts = [];
     bytes(b) { for (const x of b)
@@ -106,6 +125,20 @@ class Writer {
         for (const x of xs)
             this.str(x, what);
     }
+    /** Bytes with a u32 length (node/src/types.rs `put_bytes`: a program's code, interface and inputs), from lowercase hex. */
+    putBytes(hex, what = "bytes field") {
+        const b = lowerHexBytes(hex, what);
+        this.u32(b.length, `${what} length`);
+        this.bytes(b);
+    }
+    /** A u8 count, then each entry (a program action's calls and bindings). More than 255 are refused, never wrapped. */
+    entries(xs, what, each) {
+        if (!Array.isArray(xs))
+            throw new TypeError(`${what} must be an array`);
+        this.u8(xs.length, `${what} count`);
+        for (const x of xs)
+            each(fields(x, `each of ${what}`));
+    }
     done() { return Uint8Array.from(this.parts); }
 }
 /** A chain's genesis hash as its 32 bytes (`/api/status` `genesis_hash`, lowercase hex). */
@@ -119,6 +152,10 @@ export function genesisHashBytes(genesisHash) {
 export function isUnsignedAction(a) {
     return a.type === "private_transfer" || a.type === "unshield";
 }
+/** A program action (tags 62–64 and 69, node/src/types.rs `Action::is_program`). */
+export function isProgramAction(a) {
+    return a.type === "upload_code" || a.type === "create_program" || a.type === "call_program" || a.type === "programs_pause";
+}
 /**
  * The bytes a key signs (node/src/types.rs `Tx::signing_bytes`). For an unsigned ghost tx this is
  * its whole wire form instead: `BLOCKULA_GHOST_V1 ‖ chain_id ‖ genesis hash ‖ fee ‖ tip ‖ valid_until ‖ action`.
@@ -380,6 +417,9 @@ function encodeAction(w, a) {
         case "multisig_propose":
             if (a.action.type === "multisig_propose")
                 throw new Error("a multisig proposal can't contain another");
+            // The node won't decode one (docs/PROGRAMS-V0.md §2.1, "No nesting").
+            if (isProgramAction(a.action))
+                throw new Error("a multisig proposal can't hold a program action");
             w.u8(43);
             encodeAction(w, a.action);
             break;
@@ -444,10 +484,76 @@ function encodeAction(w, a) {
             w.str(a.validator);
             w.int(a.epoch, "epoch");
             break;
+        // Programs (docs/PROGRAMS-V0.md §2.2–2.5). Counts are a u8; byte fields a u32 length (`putBytes`).
+        case "upload_code":
+            w.u8(62);
+            w.putBytes(a.wasm, "wasm");
+            w.putBytes(a.interface, "interface");
+            w.u64(a.storage_limit, "storage_limit");
+            break;
+        case "create_program": {
+            w.u8(63);
+            w.str(a.wasm_hash, "wasm_hash");
+            w.str(a.interface_hash, "interface_hash");
+            w.str(authorityField(a.authority), "authority");
+            w.int(a.upgrade_delay_blocks, "upgrade_delay_blocks");
+            w.u8(policyByte(a.policy));
+            w.bool(a.accepts_transfers, "accepts_transfers");
+            // `init`: a presence byte, then the method, its input and value (absent or null: none, as the node reads the JSON).
+            if (a.init === undefined || a.init === null)
+                w.u8(0);
+            else {
+                const init = fields(a.init, "init");
+                w.u8(1);
+                w.str(init.method, "init.method");
+                w.putBytes(init.input, "init.input");
+                w.u64(init.value, "init.value");
+            }
+            w.int(a.fuel_limit, "fuel_limit");
+            w.u64(a.storage_limit, "storage_limit");
+            encodeBindings(w, a.bindings);
+            break;
+        }
+        case "call_program":
+            w.u8(64);
+            w.entries(a.calls, "calls", (c) => { w.str(c.program, "calls.program"); w.str(c.version_digest, "calls.version_digest"); w.str(c.method, "calls.method"); w.putBytes(c.input, "calls.input"); w.u64(c.value, "calls.value"); });
+            w.int(a.fuel_limit, "fuel_limit");
+            w.u64(a.storage_limit, "storage_limit");
+            encodeBindings(w, a.bindings);
+            break;
+        case "programs_pause":
+            w.u8(69);
+            break;
         default:
             throw new Error(`unknown action type ${a.type}`);
     }
 }
+/** A program action's bindings (node/src/types.rs `put_bindings`): a u8 count, then each program and version digest. */
+function encodeBindings(w, bindings) {
+    w.entries(bindings, "bindings", (b) => { w.str(b.program, "bindings.program"); w.str(b.version_digest, "bindings.version_digest"); });
+}
+/**
+ * A create's `authority` as the codec writes it (an optional string: `""` for none). The node
+ * reads JSON `""` as an authority that isn't an address, and refuses it, but its bytes would be
+ * an immutable program's: so `""` is refused here, never signed as the other.
+ */
+function authorityField(authority) {
+    if (authority === undefined || authority === null)
+        return "";
+    if (authority === "")
+        throw new Error('authority must be an address, or null for an immutable program (not "")');
+    if (typeof authority !== "string")
+        throw new TypeError("authority must be a string (an address) or null");
+    return authority;
+}
+/** A program policy's byte (node/src/types.rs `ProgramPolicy::byte`). */
+function policyByte(policy) {
+    if (policy === "open")
+        return 0;
+    if (policy === "additive")
+        return 1;
+    throw new Error(`policy must be "open" or "additive", not ${typeof policy === "string" ? JSON.stringify(policy) : typeof policy}`);
+}
 /** A bundle without its proof, raw and in wire order: what the sighash covers. */
 function encodeBundlePublic(w, b) {
     w.fixed(b.instance, 32);
@@ -661,6 +767,113 @@ function digestOf(what, context, encode) {
     }
     return bytesToHex(blake3(w.done(), { context: utf8.encode(context) }));
 }
+// ---- Programs' digests (node/src/programs/digest.rs, docs/PROGRAMS-V0.md §2.1), checked offline
+// against test/program-vectors.json, which the node writes. Frozen with protocol v2. ----
+/**
+ * The contexts of programs' five digests, each BLAKE3 in derive-key mode: node/src/programs/digest.rs
+ * `CODE_CONTEXT`, `INTERFACE_CONTEXT`, `VERSION_CONTEXT` and `ADDRESS_CONTEXT`, and the VM's
+ * `SELECTOR_CONTEXT` (node/vm/src/interface.rs), the selector's only home on the node.
+ */
+export const PROGRAM_DIGEST_CONTEXTS = Object.freeze({
+    code: "blockula program code v1",
+    interface: "blockula program interface v1",
+    version: "blockula program version v1",
+    address: "blockula program address v1",
+    method: "blockula program method v1",
+});
+/** Every v0 program's version (node/src/programs/digest.rs `FIRST_VERSION`): only a program upgrade, in a later protocol version, raises it. */
+export const FIRST_PROGRAM_VERSION = 1;
+/** Address prefixes (index.ts `KNOWN_PREFIXES`, node/src/crypto.rs `KNOWN_PREFIXES`), kept here so this module imports nothing of the SDK's. */
+const ADDRESS_PREFIXES = ["boo", "tboo"];
+/**
+ * A canonical address's prefix and 32 bytes (node/src/crypto.rs `parse_address`): a known prefix,
+ * and only the exact rendering, so neither uppercase nor another checksum aliases the account.
+ * Programs are named by address, never by name.
+ */
+function parseAddress(s, what) {
+    if (typeof s === "string" && s.length <= 90) {
+        try {
+            const { prefix, words } = bech32m.decode(s);
+            const bytes = bech32m.fromWords(words);
+            if (ADDRESS_PREFIXES.includes(prefix) && bytes.length === 32 && bech32m.encode(prefix, words) === s)
+                return { prefix, bytes };
+        }
+        catch {
+            // Not bech32m: refused below.
+        }
+    }
+    throw new Error(`${what} must be an address (boo1… or tboo1…), not ${typeof s === "string" ? JSON.stringify(s) : typeof s}`);
+}
+/** A 32-byte digest as a program action's JSON carries it: 64 lowercase hex (node/src/types.rs `check_hex_32`). */
+function hex32(v, what) {
+    if (typeof v !== "string" || !/^[0-9a-f]{64}$/.test(v))
+        throw new Error(`${what} must be 32 bytes of lowercase hex`);
+    return hexToBytes(v);
+}
+/** BLAKE3 in derive-key mode (the node's `blake3::derive_key`). */
+const deriveKey = (context, input) => blake3(input, { context: utf8.encode(context) });
+/** Bytes, or lowercase hex as `upload_code` carries them. */
+const bytesOf = (v, what) => (v instanceof Uint8Array ? v : lowerHexBytes(v, what));
+/**
+ * The hash that names a program's code (node/src/programs/digest.rs `wasm_hash`): BLAKE3-KDF("blockula
+ * program code v1", wasm), as 64 lowercase hex. A `create_program` names its code by it, once an
+ * `upload_code` of the same bytes (as bytes, or lowercase hex) has applied.
+ */
+export function wasmHash(wasm) {
+    return bytesToHex(deriveKey(PROGRAM_DIGEST_CONTEXTS.code, bytesOf(wasm, "wasm")));
+}
+/** The hash that names an interface, its format-1 bytes (node/src/programs/digest.rs `interface_hash`): as `wasmHash`, under "blockula program interface v1". */
+export function interfaceHash(iface) {
+    return bytesToHex(deriveKey(PROGRAM_DIGEST_CONTEXTS.interface, bytesOf(iface, "interface")));
+}
+/**
+ * What a call to `program` binds (node/src/programs/digest.rs `version_digest`): BLAKE3-KDF("blockula
+ * program version v1", the program's address as a string field (u16 LE length, its bytes) ‖ its
+ * code's hash ‖ its interface's hash ‖ its version, u32 LE), as 64 lowercase hex. A call runs only
+ * while this is the program's digest in force, so it runs the code its signer was shown: compute it
+ * from the record you show (its hashes and version), rather than sign a digest a node reported.
+ */
+export function versionDigest(program, wasmHashHex, interfaceHashHex, version = FIRST_PROGRAM_VERSION) {
+    parseAddress(program, "program");
+    const w = new Writer();
+    w.str(program, "program");
+    w.bytes(hex32(wasmHashHex, "wasm_hash"));
+    w.bytes(hex32(interfaceHashHex, "interface_hash"));
+    w.u32(version, "version");
+    return bytesToHex(deriveKey(PROGRAM_DIGEST_CONTEXTS.version, w.done()));
+}
+/**
+ * The address of the program `creator` creates with its transaction of `nonce` (node/src/programs/digest.rs
+ * `program_address`): bech32m(prefix, BLAKE3-KDF("blockula program address v1", the creator's 32
+ * address bytes ‖ nonce u64 LE)). `prefix` defaults to the creator's own (a chain admits only its
+ * prefix, so for any create it runs the two are the same).
+ *
+ * Don't send FANG to it before the create has applied: a create that fails spends its nonce, no
+ * later create reaches the address, and what was sent there is stranded for good (docs/PROGRAMS-V0.md
+ * §2.3). Fund a program through its initializer's value, or by transfer once it exists.
+ */
+export function programAddress(creator, nonce, prefix) {
+    const c = parseAddress(creator, "creator");
+    const p = prefix ?? c.prefix;
+    if (!ADDRESS_PREFIXES.includes(p))
+        throw new Error(`unknown address prefix ${p}`);
+    const w = new Writer();
+    w.bytes(c.bytes);
+    w.u64(nonce, "nonce");
+    return bech32m.encode(p, bech32m.toWords(deriveKey(PROGRAM_DIGEST_CONTEXTS.address, w.done())));
+}
+/** A method name: an identifier, `[a-z][a-z0-9_]{0,31}` (node/vm `abi::is_ident`). */
+const METHOD_NAME = /^[a-z][a-z0-9_]{0,31}$/;
+/**
+ * A method's selector (node/vm/src/interface.rs `selector`): the first 8 bytes of
+ * BLAKE3-KDF("blockula program method v1", its name), as 16 lowercase hex. An interface's methods
+ * have distinct selectors. Only identifiers are method names, so anything else is refused.
+ */
+export function methodSelector(name) {
+    if (typeof name !== "string" || !METHOD_NAME.test(name))
+        throw new Error(`a method name is an identifier ([a-z][a-z0-9_]{0,31}), not ${typeof name === "string" ? JSON.stringify(name) : typeof name}`);
+    return bytesToHex(deriveKey(PROGRAM_DIGEST_CONTEXTS.method, utf8.encode(name)).subarray(0, 8));
+}
 /**
  * What a `commit_votes` binds (node/src/types.rs `seance_pairs_digest`): the Séance, the juror and,
  * per assigned pair in order, both claims' ids, repos and PR numbers.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blockula/sdk",
-  "version": "0.5.1",
-  "description": "\ud83e\udddb TypeScript SDK for Blockula \u2014 post-quantum wallets (ML-DSA-65), .boo names, transfers",
+  "version": "1.0.0",
+  "description": "\ud83e\udddb TypeScript SDK for Blockula: wallets with post-quantum signatures (ML-DSA-65), .boo names and transfers. Experimental software, provided as is under MIT.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,9 +16,10 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "tsx test/e2e.ts",
+    "test": "tsx test/e2e.ts && tsx test/e2e-integrators.ts",
+    "test:programs": "tsx test/e2e-programs.ts",
     "test:kat": "tsx test/kat.ts",
-    "test:vectors": "tsx test/passkey-vectors.ts && tsx test/proof-vectors.ts && tsx test/tx-vectors.ts && tsx test/unit.ts"
+    "test:vectors": "tsx test/passkey-vectors.ts && tsx test/proof-vectors.ts && tsx test/tx-vectors.ts && tsx test/program-vectors.ts && tsx test/programs.ts && tsx test/unit.ts && tsx test/integrators.ts && tsx test/examples.ts"
   },
   "license": "MIT",
   "dependencies": {
@@ -29,7 +30,7 @@
   "devDependencies": {
     "@types/node": "*",
     "tsx": "*",
-    "typescript": "*"
+    "typescript": "^7.0.2"
   },
   "author": "Jack Dishman",
   "keywords": [