@blockula/sdk 0.3.0 → 1.0.0

package/dist/programs.d.ts

@@ -0,0 +1,471 @@
+/** The most code one upload carries, in bytes (`MAX_CODE_BYTES`). */
+export declare const MAX_PROGRAM_CODE_BYTES: number;
+/** The most interface one upload carries, in bytes (`MAX_INTERFACE_BYTES`). */
+export declare const MAX_PROGRAM_INTERFACE_BYTES: number;
+/** The most input one call carries, in bytes (`MAX_INPUT`). */
+export declare const MAX_PROGRAM_INPUT_BYTES: number;
+/** The most calls one `call_program` runs (`MAX_CALLS`). */
+export declare const MAX_PROGRAM_CALLS = 8;
+/** The most programs one transaction binds (`MAX_BINDINGS`). */
+export declare const MAX_PROGRAM_BINDINGS = 16;
+/** What a program's record adds to program state's bytes, so what its creator bonds a deposit for (`RECORD_BYTES`). */
+export declare const PROGRAM_RECORD_BYTES = 256n;
+/** The fuel rate is in milli-drops per fuel: a fee is `rate × reserved / 1000` (`econ::RATE_SCALE`). */
+export declare const FUEL_RATE_SCALE = 1000n;
+/**
+ * A binding's version digest of 64 zeros: "any version of that program". A transaction that binds
+ * it runs whatever code the program has when it runs, which is not what its signer was shown: this
+ * SDK signs it only when asked to, never by default.
+ */
+export declare const ANY_PROGRAM_VERSION: string;
+/**
+ * The fuel schedule these numbers belong to (node/vm/src/meter.rs `SCHEDULE_V0`, `fuel.schedule`
+ * 0 in `/api/fees`). A node that prices fuel by another schedule, or reports other numbers for this
+ * one, is refused: the SDK prices what it signs with these.
+ */
+export declare const SCHEDULE_V0: Readonly<{
+    schedule: 0;
+    load_base: 10000n;
+    load_per_byte: 40n;
+    upload_base: 50000n;
+    upload_per_byte: 71n;
+}>;
+/**
+ * A node answered a question about programs with something no honest node says (a digest that isn't
+ * 64 lowercase hex, an amount that isn't a decimal string, a height the chain can't have, …). Nothing
+ * from the answer was used and nothing was signed on its word: ask another node.
+ */
+export declare class ProgramAnswerError extends Error {
+    readonly rpc: string;
+    readonly what: string;
+    readonly field: string;
+    readonly problem: string;
+    constructor(rpc: string, what: string, field: string, problem: string);
+}
+/** The chain hasn't switched programs on (`/api/fees` has no `fuel` section): nothing was signed. */
+export declare class ProgramsOffError extends Error {
+    readonly rpc: string;
+    constructor(rpc: string);
+}
+/**
+ * A transaction would reserve more fuel than one block counts (`program_max_block_fuel`), so no
+ * block could include it: refused before it's signed. `reserved` is its fuel to run plus the load
+ * of the code it declares.
+ */
+export declare class FuelReservationError extends Error {
+    readonly reserved: bigint;
+    readonly run: bigint;
+    readonly load: bigint;
+    readonly limit: bigint;
+    constructor(reserved: bigint, run: bigint, load: bigint, limit: bigint);
+}
+/**
+ * Text a node or a program chose, made inert before it's quoted anywhere (an error, a sentence):
+ * stripped of control, format (bidi, zero-width), private-use, surrogate and line and paragraph
+ * separator characters, as the MCP's `clean()` does. JSON quoting escapes control characters but
+ * not the format ones (U+202E would still reorder the line), so every quote goes through this first.
+ */
+export declare const plainText: (s: string) => string;
+/** An account as the node labels it. */
+export interface AccountLabel {
+    address: string;
+    /** A `.boo` name that account owns, or a system label: a stranger's text. */
+    name: string | null;
+    short: string;
+}
+/** A program's address as a caller gives it: never a name, which moves with its owner (docs/PROGRAMS-V0.md §8.1). */
+export declare function programAddressArg(s: unknown, what?: string): string;
+/** A code, interface or version digest as a caller gives it: 64 lowercase hex characters. */
+export declare function programHashArg(s: unknown, what: string): string;
+/** A method name: an identifier, as the chain's interfaces name them (`[a-z][a-z0-9_]{0,31}`). */
+export declare function programMethodArg(s: unknown): string;
+/** Bytes as a caller gives them (code, an interface, an input): raw, or lowercase hex of whole bytes; at most `max`. */
+export declare function programBytesArg(v: unknown, what: string, max: number): Uint8Array;
+/** A call's input as the request and the transaction carry it: lowercase hex, at most `MAX_PROGRAM_INPUT_BYTES`. */
+export declare const programInputArg: (v: unknown) => string;
+/** A fuel amount a caller gives: a whole number from 1 to 2^53 − 1 (the chain's own bound is lower). */
+export declare function positiveFuel(n: unknown): number;
+/** A type in an interface (node/src/programs/interface_json.rs `TypeJson`): scalars as strings, the rest as one-key objects. */
+export type ProgramType = string | {
+    bytes: number;
+} | {
+    text: number;
+} | {
+    option: ProgramType;
+} | {
+    vec: [ProgramType, number];
+};
+/** A method of a program's interface, as `/api/program` serves it. Its names are the deployer's. */
+export interface ProgramMethod {
+    /** The deployer's identifier for it: an untrusted claim. */
+    untrusted_name: string;
+    /** The method's selector, 16 hex: BLAKE3 of its name (`methodSelector`). */
+    selector: string;
+    /** What the chain enforces: `call` (a transaction), `view` (a read) or `init` (once, when the program is created). */
+    kind: "call" | "view" | "init";
+    payable: boolean;
+    args: {
+        untrusted_name: string;
+        type: ProgramType;
+    }[];
+    returns: ProgramType | null;
+}
+/**
+ * A program as a node serves it (`GET /api/program/{address}`), checked: its `version_digest` is
+ * the one its own hashes and version compute (so a node can't show one program's code under
+ * another's digest), and its numbers and digests are well formed. `proven: false`: this is one
+ * node's word (`Client.provenProgram` proves the record itself against witnesses).
+ */
+export interface ProgramInfo {
+    address: string;
+    creator: AccountLabel;
+    created_at: number;
+    code: {
+        wasm_hash: string;
+        size: number | null;
+        interface_hash: string;
+    };
+    version: number;
+    /** What a call to this program binds (`versionDigest`), recomputed from `code` and `version`, never taken on trust. */
+    version_digest: string;
+    authority: AccountLabel | null;
+    upgrade_delay_blocks: number;
+    policy: "open" | "additive";
+    /** The node's sentence about who may upgrade it: its words, not a rule. */
+    upgradability: string;
+    accepts_transfers: boolean;
+    /** Drops it holds, as a decimal string. */
+    balance: string;
+    storage: {
+        items: number;
+        bytes: number;
+        deposit: string;
+        sponsored: string;
+    };
+    record_deposit: string;
+    record_payer: AccountLabel;
+    /** Its interface's methods; `null` only if the node's state is broken. The names are the deployer's. */
+    methods: ProgramMethod[] | null;
+    /** Where `/api/proof` serves this record. */
+    proof_path: string;
+    /** The block the node read it at. */
+    height: number;
+    proven: false;
+}
+/** `GET /api/program/{address}` checked against what was asked (`address`) and the chain's clock (`clock`: refuses a height the chain can't have reached). */
+export declare function checkProgram(rpc: string, address: string, raw: unknown, clock?: (height: number) => void): ProgramInfo;
+/** A stored code as `GET /api/code/{hash}` serves it, checked. */
+export interface ProgramCodeInfo {
+    wasm_hash: string;
+    size: number;
+    /** The method names its exported functions carry (`bk_<name>`): the deployer's. */
+    untrusted_exports: string[];
+    uploader: AccountLabel | null;
+    /** What was bonded for it, drops. */
+    deposit: string | null;
+    /** How many programs use it. */
+    refs: number | null;
+    /** The block that stored it: usable from the block after. */
+    uploaded_at: number | null;
+    last_used_at: number | null;
+    /** The code itself, when it was asked for (`?wasm=1`) and its hash checked out. */
+    wasm?: Uint8Array;
+    height: number;
+}
+/** `GET /api/code/{hash}[?wasm=1]` checked: it's the code asked for, and when the bytes came they hash to it. */
+export declare function checkCode(rpc: string, hash: string, raw: unknown, wantWasm: boolean, clock?: (height: number) => void): ProgramCodeInfo;
+/** A stored interface as `GET /api/interface/{hash}` serves it, checked. */
+export interface ProgramInterfaceInfo {
+    interface_hash: string;
+    size: number;
+    /** The interface's format-1 bytes (docs/PROGRAMS-V0.md §3.2), which hash to `interface_hash`. */
+    bytes: Uint8Array;
+    hex: string;
+    /**
+     * The node's reading of those bytes as JSON (§3.4): every name in it is the deployer's. It isn't
+     * checked against the bytes (this SDK has no interface decoder yet): the bytes are what `interface_hash` names.
+     */
+    untrusted_interface: unknown;
+    uploader: AccountLabel | null;
+    deposit: string | null;
+    refs: number | null;
+    uploaded_at: number | null;
+    last_used_at: number | null;
+    height: number;
+}
+/** `GET /api/interface/{hash}` checked: it's the interface asked for, and its bytes hash to it. */
+export declare function checkInterface(rpc: string, hash: string, raw: unknown, clock?: (height: number) => void): ProgramInterfaceInfo;
+/** How a failed program run ended (docs/PROGRAMS-V0.md §8.1's table): numbers, never engine text. */
+export interface ProgramOutcome {
+    ok: boolean;
+    /** The outcome's number in §8.1's table (0 for ok). */
+    number: number;
+    /** `ok`, or the table's code: `trapped`, `aborted`, `commit`, `value_cap`, `exit_only`, `storage_limit`, `state_full`, `invalid_code`, `translation_refused`, `interface_mismatch`, `native`. */
+    code: string;
+    /** Where a trap or an abort began. */
+    program?: string;
+    trap?: {
+        number: number;
+        name: string;
+    };
+    abort_code?: number;
+    /** An abort's own message (at most 256 bytes, sanitized by the VM): the program's words. */
+    untrusted_message?: string;
+    commit_error?: number;
+    /** A value cap failure's cap and the control it would have left, drops. */
+    cap?: string;
+    control?: string;
+    rule?: {
+        number: number;
+        name: string;
+    };
+    func?: number;
+    offset?: number;
+}
+/**
+ * A failed outcome in words, from its numbers and the chain's own names for them (docs/PROGRAMS-V0.md
+ * §8.1): never engine text, and **never what the program wrote**: an abort's own message stays in
+ * `outcome.untrusted_message`, for the caller to show as data. These words end up in exceptions that
+ * agent frameworks hand to models, and a stranger's text doesn't belong in them. Tolerant of an
+ * outcome that wasn't checked (a field of another type reads as `?`): it never throws on a node's
+ * odd answer. `storageLimit` is the limit the failed transaction signed, drops: a call that traps
+ * `storage_limit` was refused its writes' deposit by it (the default for a call is 0, which consents
+ * to no new storage), and says so.
+ */
+export declare function outcomeWords(o: ProgramOutcome, storageLimit?: bigint): string;
+/** What a `View` method returned (`POST /api/program/{address}/view`), checked. */
+export interface ProgramViewResult {
+    ok: boolean;
+    outcome: ProgramOutcome;
+    /**
+     * What the method returned, lowercase hex: `""` when it returns nothing, `null` when it failed.
+     * It's the program's own claim: the chain checks none of it.
+     */
+    return_data: string | null;
+    fuel_used: number;
+    /** The newest block this node executed: the view read the state after it, and ran as of the block after. */
+    height: number;
+}
+export declare function checkView(rpc: string, address: string, raw: unknown, clock?: (height: number) => void): ProgramViewResult;
+/** The chain's fuel prices and program bounds now (`/api/fees`' `fuel` section), checked. Rates are milli-drops per fuel. */
+export interface ProgramFuel {
+    /** `on`; `exit_only` (switched off by governance: only calls that send no FANG); `paused` (nothing but a pause). */
+    status: "on" | "exit_only" | "paused";
+    /** What the next block charges. */
+    rate: bigint;
+    floor_rate: bigint;
+    /** The most the rate can reach in the next 17 blocks of full fuel: a fee priced with it covers any of them. */
+    suggested_rate: bigint;
+    max_tx_fuel: bigint;
+    max_block_fuel: bigint;
+    max_tx_code_bytes: number;
+    /** Program state's accounted bytes, and the soft cap its price curve doubles around. */
+    state_bytes: bigint;
+    state_soft_bytes: bigint;
+    /** What a byte of storage costs now, drops; `null` past the ceiling. */
+    storage_price: bigint | null;
+    paused_until: number | null;
+}
+/** `/api/fees`' `fuel` section: the chain's, or `ProgramsOffError` when it has none (programs never switched on). */
+export declare function checkFuel(rpc: string, raw: unknown): ProgramFuel;
+/** The programs parameters a client prices with (`/api/params`' `programs.params`), checked. */
+export interface ProgramParams {
+    /** Drops per accounted byte at an empty state (`program_storage_price`): the price curve doubles it. */
+    storage_price: bigint;
+    /** `program_min_upgrade_delay_blocks`: the notice an upgrade authority must give. */
+    min_upgrade_delay_blocks: number;
+}
+export declare function checkParams(rpc: string, raw: unknown): ProgramParams;
+/** The fuel to load one distinct code of `size` bytes (schedule 0: `load_base + load_per_byte × size`, §5.1). */
+export declare const loadFuel: (size: number | bigint) => bigint;
+/** The fuel an upload of `code` bytes of WebAssembly and `iface` bytes of interface reserves (§5.1's `upload_fuel`: its whole `exec`). */
+export declare const uploadFuel: (code: number | bigint, iface: number | bigint) => bigint;
+/** The fuel fee of `reserved` fuel at `rate` milli-drops per fuel: `rate × reserved / 1000`, rounded down (§5.1). Burned, never refunded. */
+export declare const fuelFee: (rate: bigint, reserved: bigint) => bigint;
+/** What a transaction reserves: its fuel to run, the load of the distinct code it declares, and the two together. */
+export interface FuelReservation {
+    run: bigint;
+    load: bigint;
+    reserved: bigint;
+}
+/**
+ * Whether a block could carry `run` fuel and the load of the `declared` code (each distinct code
+ * hash once, with its size): refused as admission refuses it, before anything is signed. A
+ * reservation past `max_block_fuel` is a `FuelReservationError`; code past what one transaction may
+ * load, or a fuel limit past `max_tx_fuel` (`execFuelLimited`: a create's or a call's own limit, not
+ * an upload's), is an `Error` that says so.
+ */
+export declare function reserveFuel(fuel: ProgramFuel, run: bigint, declared: Map<string, number>, execFuelLimited?: boolean): FuelReservation;
+/**
+ * The fuel limit a call or an initializer is signed with when the caller gives none (docs/PROGRAMS-V0.md
+ * §8.4): `min(program_max_tx_fuel, program_max_block_fuel − load)`, the most one transaction may run
+ * that a block can still carry beside the load of the `declared` code. With the parameters at their
+ * defaults that's `program_max_tx_fuel`; with `program_max_tx_fuel` = `program_max_block_fuel` (both
+ * legal) a bare `program_max_tx_fuel` would itself trip the refusal of a reservation past the block.
+ * When the load alone fills the block there is no room: 1, which `reserveFuel` then refuses in words.
+ */
+export declare function defaultFuelLimit(fuel: ProgramFuel, declared: Map<string, number>): bigint;
+/**
+ * The fuel fee of a reservation (drops) at the rate the next 17 blocks can reach (`suggested_rate`:
+ * what a transaction's `fee` is priced at, §5.5) and at the floor rate (what the tip cap is counted
+ * on: a block's rate is never below it), after holding it to `max_block_fuel` once more against
+ * these very prices. Burned, and never refunded: a transaction pays for what it reserves.
+ */
+export declare function priceFuel(fuel: ProgramFuel, r: FuelReservation): {
+    suggested: bigint;
+    floor: bigint;
+};
+/**
+ * Whether the chain's programs status admits this kind of transaction now: `on` admits all;
+ * `exit_only` only a call that sends no FANG (an exit); `paused` none. The node refuses the rest at
+ * submission, so this only says so before a signature (`sendsValue`: the transaction attaches FANG).
+ */
+export declare function checkProgramsStatus(fuel: ProgramFuel, kind: "upload" | "create" | "call", sendsValue: boolean): void;
+/**
+ * The price of a byte of program state when it holds `used` bytes (node/vm/src/storage.rs `price`):
+ * `base × 2^⌊8 × used / soft⌋`. `null` past the ceiling (`2 × soft`) or if the price wouldn't fit a u64.
+ */
+export declare function programStoragePrice(base: bigint, soft: bigint, used: bigint): bigint | null;
+/**
+ * What an upload bonds (node/src/program_cli.rs `Bounds::upload_deposit`, §2.2 step 5): each blob that
+ * isn't stored yet, code first, at the price once it lands. `null` past program state's ceiling.
+ */
+export declare function programUploadDeposit(fuel: ProgramFuel, params: ProgramParams, blobs: {
+    size: number;
+    isNew: boolean;
+}[]): bigint | null;
+/** What a create bonds for its record (§2.3 step 2): `PROGRAM_RECORD_BYTES` at the price once it lands. `null` past the ceiling. */
+export declare function programRecordDeposit(fuel: ProgramFuel, params: ProgramParams): bigint | null;
+/** A deposit and ten percent more: the default `storage_limit` of an upload or a create (§8.3), room for the price to move. */
+export declare const depositWithMargin: (deposit: bigint) => bigint;
+/** What a program transaction's fee was made of, drops (§8.1): their sum is what it was charged. */
+export interface ReceiptFee {
+    bytes: bigint;
+    fuel: bigint;
+    tip: bigint;
+}
+/** What a signer was debited outside the VM's own balance changes (§8.1), drops: `total` is the three parts' sum. */
+export interface OutsideVm {
+    record_deposit: bigint;
+    upload_deposit: bigint;
+    account_creation_fee: bigint;
+    total: bigint;
+}
+/** The facts of a program transaction: what the chain did, which the state holds too. */
+export interface ProgramFacts {
+    /** The VM's diff, net per account, drops (negative: a debit): a program's own sends and the signer's write bonds. Not the fee, not `outside_vm`. */
+    balance_changes: {
+        account: string;
+        change: bigint;
+    }[];
+    storage: {
+        bytes_delta: number;
+        bonded: bigint;
+        refunded: bigint;
+    };
+    outside_vm: OutsideVm;
+    /** Drops the VM's diff burned: the creation fees of the accounts a program's own sends opened. Taken from the programs' balances inside the diff, never the signer's. */
+    burned_by_programs: bigint;
+    fuel: {
+        limit: bigint;
+        load: bigint;
+        used: bigint;
+        reserved: bigint;
+        rate: bigint;
+    };
+    fee: ReceiptFee;
+    /** The program a create made. */
+    created: string | null;
+    upload: {
+        wasm_hash: string;
+        interface_hash: string;
+        new_code: boolean;
+        new_interface: boolean;
+        deposit: bigint;
+    } | null;
+}
+/** What the programs said happened: claims, which the chain checks nothing of. Method and event names are the deployer's. */
+export interface ProgramClaims {
+    return_data: {
+        program: string;
+        untrusted_method: string;
+        value: bigint;
+        data: string;
+    }[];
+    events: {
+        program: string;
+        untrusted_name: string;
+        data: string;
+    }[];
+    /** Set when the block's claims budget left this receipt's claims out (its facts are all kept). */
+    omitted: {
+        events: number;
+        event_bytes: number;
+        return_bytes: number;
+    } | null;
+}
+/** A program transaction's receipt as `/api/tx/{id}` serves it, checked: facts apart from claims. */
+export interface ProgramReceipt {
+    version: number;
+    kind: "upload" | "create" | "call";
+    outcome: ProgramOutcome;
+    facts: ProgramFacts;
+    claims: ProgramClaims;
+}
+/**
+ * The `program` section of a `/api/tx` answer, checked: `null` for a program transaction with no
+ * receipt to show (still pending, or its block pruned from this node). Every amount is a decimal
+ * string, every digest 64 lowercase hex, and the sums the node states are recomputed: the fee parts
+ * equal the transaction's `fee`, `outside_vm.total` is its parts' sum, `reserved` is `limit + load`.
+ * A transaction that isn't a program's carries no `program` key, and `ProgramAnswerError` says so.
+ */
+export declare function checkReceipt(rpc: string, tx: unknown): ProgramReceipt | null;
+/** What a program transaction's fee came to, drops: bytes, fuel and tip (§8.1's `Σ`). */
+export declare const chargedFee: (r: ProgramReceipt) => bigint;
+/** What the VM's diff did to `account`'s balance, drops (0 for an account it doesn't list). */
+export declare const vmChange: (r: ProgramReceipt, account: string) => bigint;
+/**
+ * How far a receipt's facts are from conserving FANG (docs/PROGRAMS-V0.md §8.1): Σ `balance_changes` +
+ * (`storage.bonded` − `outside_vm.record_deposit` − `outside_vm.upload_deposit` − `storage.refunded`) +
+ * `burned_by_programs`. The VM's diff conserves (what its programs moved and the deposits it bonded
+ * or freed, plus what it burned, sum to nothing), and a create's record deposit and an upload's are
+ * bonded outside it: so a receipt the chain wrote is 0 here, and `checkReceipt` refuses one that
+ * isn't. (The account creation fee a create burns from its signer is the signer's, not a program's:
+ * it's in `outside_vm`, not here.)
+ */
+export declare const conservationGap: (f: Pick<ProgramFacts, "balance_changes" | "storage" | "outside_vm" | "burned_by_programs">) => bigint;
+/**
+ * How the signer's balance moved, exactly (docs/PROGRAMS-V0.md §8.1, S6B-R1): Δbalance(signer) =
+ * −(fee total + `outside_vm.total`) + `balance_changes[signer]`. The fee is burned (and the tip goes
+ * to the proposer), the deposits and the account creation fee leave outside the VM, and the VM's diff
+ * holds what the programs moved, the signer's own write bonds among it. A failed transaction's receipt
+ * has no balance changes and nothing outside the VM: only the fee.
+ */
+export declare const signerChange: (r: ProgramReceipt, signer: string) => bigint;
+/** `reconcileSigner`'s answer: what the receipt says the signer's balance did, what it did, and whether they're the same. */
+export interface Reconciliation {
+    expected: bigint;
+    actual: bigint;
+    /** `actual − expected`: 0 when the balance moved exactly as the receipt says (nothing else touched the account between the two reads). */
+    difference: bigint;
+    exact: boolean;
+    /** Whether the receipt's own facts conserve FANG (`conservationGap` is 0): a receipt that doesn't can't be what the chain wrote. */
+    conserved: boolean;
+}
+/**
+ * The signer's balance before and after its program transaction (both in drops, read around it with
+ * nothing else touching the account), held to `signerChange`.
+ */
+export declare function reconcileSigner(r: ProgramReceipt, signer: string, before: bigint, after: bigint): Reconciliation;
+/** What a program transaction cost its signer, drops, from its receipt: the fee, what left outside the VM, what the VM took (the write bonds), and all of it. */
+export interface ProgramCost {
+    /** Bytes, fuel and tip. */
+    fee: bigint;
+    /** Deposits and the account creation fee that left outside the VM's diff. */
+    outside_vm: OutsideVm;
+    /** What the VM's diff took from the signer (positive: a debit): its write bonds, and FANG it sent. 0 or less when the programs paid it. */
+    vm: bigint;
+    /** `fee + outside_vm.total + vm`: the signer's whole debit. */
+    total: bigint;
+}
+export declare function programCost(r: ProgramReceipt, signer: string): ProgramCost;