@dcasegr/amm-client 0.0.0-stage → 0.38.2

package/dist/vendor/runar/runar-ir-schema/src/state-layout.js

@@ -0,0 +1,145 @@
+/**
+ * State-tail byte layout — the single source of truth for WHERE each
+ * serialized state field lives in a stateful contract's locking script.
+ *
+ * Mirrors the SDK's `serializeState` wire format exactly:
+ *
+ *   <code part> OP_RETURN <field0> <field1> ... <fieldN>
+ *
+ *   - bigint / int : 8 raw bytes, little-endian sign-magnitude (OP_NUM2BIN 8)
+ *   - bool         : 1 raw byte (0x00 / 0x01)
+ *   - PubKey       : 33 raw bytes          - Addr / Ripemd160 : 20 raw bytes
+ *   - Sha256       : 32 raw bytes          - Point            : 64 raw bytes
+ *   - P256Point    : 64 raw bytes          - P384Point        : 96 raw bytes
+ *   - anything else: push-data framed (variable length)
+ *
+ * The curve-point types are raw and fixed-width because `runar-lang`'s
+ * `P256Point` / `P384Point` cast constructors hard-assert 64 / 96 bytes, and
+ * all seven COMPILERS emit them as fixed raw slices in the state tail. An SDK
+ * that push-data frames them instead deploys a state section one (64 -> 0x40)
+ * or two (96 -> OP_PUSHDATA1) bytes longer than the script's own reader
+ * expects, and the first spend fails with the funds locked.
+ *
+ * Fields are concatenated in `StateField.index` order. FixedArray fields
+ * serialize as their flattened leaves back-to-back.
+ *
+ * Lives in runar-ir-schema so the compiler (which annotates `stateFields`
+ * in the artifact), the SDK's state codec, and any verifier tooling share
+ * ONE width table instead of re-deriving it.
+ */
+/**
+ * Fixed serialized widths (bytes) for scalar state-field types.
+ * Types absent from this table serialize as push-data framed variable-length
+ * values ('pushdata').
+ */
+export const STATE_FIELD_WIDTHS = {
+    int: { size: 8, encoding: 'num2bin-le8' },
+    bigint: { size: 8, encoding: 'num2bin-le8' },
+    bool: { size: 1, encoding: 'bool1' },
+    boolean: { size: 1, encoding: 'bool1' },
+    PubKey: { size: 33, encoding: 'raw' },
+    Addr: { size: 20, encoding: 'raw' },
+    Ripemd160: { size: 20, encoding: 'raw' },
+    Sha256: { size: 32, encoding: 'raw' },
+    Point: { size: 64, encoding: 'raw' },
+    P256Point: { size: 64, encoding: 'raw' },
+    P384Point: { size: 96, encoding: 'raw' },
+};
+/** Return the innermost scalar type of a (possibly nested) FixedArray string. */
+function unwrapFixedArrayLeaf(type) {
+    let current = type.trim();
+    while (current.startsWith('FixedArray<')) {
+        const inner = current.slice('FixedArray<'.length, -1);
+        let depth = 0;
+        let splitAt = -1;
+        for (let i = inner.length - 1; i >= 0; i--) {
+            const ch = inner[i];
+            if (ch === '>')
+                depth++;
+            else if (ch === '<')
+                depth--;
+            else if (ch === ',' && depth === 0) {
+                splitAt = i;
+                break;
+            }
+        }
+        if (splitAt < 0)
+            return current;
+        current = inner.slice(0, splitAt).trim();
+    }
+    return current;
+}
+/**
+ * Annotate state fields with their byte layout (`encoding`, `byteOffset`,
+ * `byteLength`, `tailOffset`). Returns NEW field objects (inputs are not
+ * mutated), sorted by `index` — the serialization order.
+ *
+ * `byteOffset` counts from the byte AFTER the OP_RETURN separator and is
+ * present only while every preceding field is fixed-length. `tailOffset` is
+ * a NEGATIVE offset from the END of the locking script and is present only
+ * when the field itself and every following field is fixed-length.
+ */
+export function annotateStateFieldLayout(fields) {
+    const sorted = [...fields].sort((a, b) => a.index - b.index);
+    const out = sorted.map(field => {
+        const annotated = { ...field };
+        if (field.fixedArray) {
+            // Flattened leaves serialize back-to-back; fixed only if the leaf is.
+            const leaf = STATE_FIELD_WIDTHS[unwrapFixedArrayLeaf(field.type)];
+            const count = field.fixedArray.syntheticNames.length;
+            if (leaf) {
+                annotated.encoding = leaf.encoding;
+                annotated.byteLength = leaf.size * count;
+            }
+            else {
+                annotated.encoding = 'pushdata';
+            }
+            return annotated;
+        }
+        const fixed = STATE_FIELD_WIDTHS[field.type];
+        if (fixed) {
+            annotated.encoding = fixed.encoding;
+            annotated.byteLength = fixed.size;
+        }
+        else {
+            annotated.encoding = 'pushdata';
+        }
+        return annotated;
+    });
+    // Forward pass: byteOffset while all preceding fields are fixed-length.
+    let offset = 0;
+    let frontFixed = true;
+    for (const f of out) {
+        if (frontFixed)
+            f.byteOffset = offset;
+        if (f.byteLength === undefined) {
+            frontFixed = false;
+        }
+        else {
+            offset += f.byteLength;
+        }
+    }
+    // Backward pass: tailOffset while the field and all following are fixed.
+    let fromEnd = 0;
+    for (let i = out.length - 1; i >= 0; i--) {
+        const f = out[i];
+        if (f.byteLength === undefined)
+            break;
+        fromEnd += f.byteLength;
+        f.tailOffset = -fromEnd;
+    }
+    return out;
+}
+/**
+ * Total serialized state length in bytes (after the OP_RETURN byte), or
+ * undefined when any field is variable-length.
+ */
+export function totalStateByteLength(fields) {
+    let total = 0;
+    for (const f of annotateStateFieldLayout(fields)) {
+        if (f.byteLength === undefined)
+            return undefined;
+        total += f.byteLength;
+    }
+    return total;
+}

package/dist/vendor/runar/runar-ir-schema/src/unknown-anf-kind-error.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Typed error thrown by ANF / Stack-IR / constant-fold dispatch sites when
+ * they encounter an ANFValue kind they don't recognize.
+ *
+ * Historically these dispatchers used silent `default:` fall-throughs that
+ * returned a no-op value (empty refs list, unchanged ANFValue, `false` for
+ * side-effect checks). Adding a new ANFValue variant and forgetting to wire
+ * it into all 14 dispatch sites (see CLAUDE.md § Adding a New ANF Value Kind)
+ * would then silently corrupt output instead of failing loudly.
+ *
+ * Every former silent default now throws this error so the regression is
+ * caught at the first dispatch site instead of leaking into Stack IR / hex.
+ */
+export declare class UnknownANFKindError extends Error {
+    readonly kind: string;
+    readonly location: string;
+    constructor(kind: string, location: string);
+}

package/dist/vendor/runar/runar-ir-schema/src/unknown-anf-kind-error.js

@@ -0,0 +1,25 @@
+/**
+ * Typed error thrown by ANF / Stack-IR / constant-fold dispatch sites when
+ * they encounter an ANFValue kind they don't recognize.
+ *
+ * Historically these dispatchers used silent `default:` fall-throughs that
+ * returned a no-op value (empty refs list, unchanged ANFValue, `false` for
+ * side-effect checks). Adding a new ANFValue variant and forgetting to wire
+ * it into all 14 dispatch sites (see CLAUDE.md § Adding a New ANF Value Kind)
+ * would then silently corrupt output instead of failing loudly.
+ *
+ * Every former silent default now throws this error so the regression is
+ * caught at the first dispatch site instead of leaking into Stack IR / hex.
+ */
+export class UnknownANFKindError extends Error {
+    kind;
+    location;
+    constructor(kind, location) {
+        super(`Unknown ANF kind '${kind}' encountered in ${location} — ` +
+            `if you added a new ANFValue variant, update all dispatch sites ` +
+            `(see CLAUDE.md § Adding a New ANF Value Kind for the 14-step recipe).`);
+        this.name = 'UnknownANFKindError';
+        this.kind = kind;
+        this.location = location;
+    }
+}

package/dist/vendor/runar/runar-sdk/src/anf-interpreter.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Lightweight ANF interpreter for auto-computing state transitions.
+ *
+ * Given a compiled artifact's ANF IR, the current contract state, and
+ * method arguments, this interpreter walks the ANF bindings and computes
+ * the new state. It handles `update_prop` nodes to track state mutations,
+ * while skipping on-chain-only operations like `check_preimage`,
+ * `deserialize_state`, `get_state_script`, `add_output`, and `add_raw_output`.
+ *
+ * Three execution modes:
+ *
+ *  1. **Lenient** (`computeNewState`, `computeNewStateAndDataOutputs`) —
+ *     skips `assert` predicates so the SDK can pre-compute the post-state
+ *     even when arguments wouldn't actually pass the on-chain script. This
+ *     is the canonical use: auto-deriving `newState` for the next call.
+ *  2. **Strict** (`executeStrict`) — evaluates every `assert` predicate and
+ *     throws `AssertionFailureError` (carrying the contract method + ANF
+ *     binding name of the failing predicate) on the first false assert. Use
+ *     for "will this call go through?" / "would the asserts hold" smoke
+ *     tests off-chain before paying broadcast fees. Crypto built-ins
+ *     (`checkSig`, `checkMultiSig`, `checkPreimage`) still mock-return
+ *     `true` — only explicit `assert(...)` predicates are enforced.
+ *  3. **On-chain authoritative** (`executeOnChainAuthoritative`) — strict
+ *     assert enforcement PLUS real ECDSA / SHA-256 preimage verification
+ *     against a caller-supplied `sighash`. The signature shape requires the
+ *     caller to provide the sighash up front, so it is impossible to invoke
+ *     this mode accidentally without the cryptographic inputs. Use this to
+ *     validate the exact transaction the caller intends to broadcast: a
+ *     `checkSig(sig, pk)` only passes if the supplied DER signature
+ *     verifies against the supplied compressed public key over the
+ *     supplied sighash, and `checkPreimage(preimage)` only passes if
+ *     `SHA256(SHA256(preimage)) === sighash` (the canonical BIP-143
+ *     `OP_PUSH_TX` semantic).
+ */
+import type { ANFProgram } from '../../../../pool/runar-ir-schema.js';
+/**
+ * Compute the new state after executing a contract method.
+ *
+ * @param anf         The ANF IR from the compiled artifact.
+ * @param methodName  The method to execute (must be a public method).
+ * @param currentState  Current contract state (property name → value).
+ * @param args        Method arguments (param name → value).
+ * @param constructorArgs  Constructor arg values (declaration order) for readonly fields.
+ * @returns The updated state (merged with currentState).
+ */
+export interface DataOutputEntry {
+    satoshis: bigint | number;
+    script: string;
+}
+/**
+ * Raw outputs produced by `this.addRawOutput(satoshis, scriptBytes)` in the
+ * method body. `script` is the **caller-supplied** locking-script bytes
+ * (hex-encoded), in contrast to `DataOutputEntry.script`, which is the hex
+ * payload that becomes part of an `OP_RETURN` data output. The simulator
+ * cannot introspect these bytes — it surfaces them so a caller building
+ * the broadcast transaction off-chain can splice them in at the correct
+ * position. Entries appear in declaration order, after the state output
+ * and after `dataOutputs`.
+ */
+export interface RawOutputEntry {
+    satoshis: bigint | number;
+    script: string;
+}
+/**
+ * A single state-class output in the exact SOURCE order the method body emits
+ * it, capturing the interleaving of `this.addOutput(...)` (state continuation)
+ * and `this.addRawOutput(...)` (caller-supplied script). The compiler folds
+ * these into the continuation `hashOutputs` in this same order (see
+ * `packages/runar-compiler/src/passes/04-anf-lower.ts` — `add_output` and
+ * `add_raw_output` share one `addOutputRefs` list), so a transaction builder
+ * MUST emit them in this order or the on-chain state-check OP_VERIFY rejects
+ * (finding G1). `script` is populated for `raw` entries only; `state` entries
+ * take the freshly computed continuation locking script from the caller.
+ * Data outputs (`add_data_output`) are NOT included here — they are always
+ * emitted after every state-class output, in their own `dataOutputs` list.
+ */
+export interface OrderedOutputEntry {
+    kind: 'state' | 'raw';
+    satoshis: bigint;
+    script?: string;
+}
+/**
+ * The full result envelope produced by
+ * {@link computeNewStateAndDataOutputs}, {@link executeStrict}, and
+ * {@link executeOnChainAuthoritative}. All three modes return the same
+ * shape; mode-specific behaviour only changes whether asserts and crypto
+ * primitives are enforced or mocked, not what fields are populated.
+ */
+export interface ExecutionResult {
+    state: Record<string, unknown>;
+    dataOutputs: DataOutputEntry[];
+    rawOutputs: RawOutputEntry[];
+    /** State-class outputs (state continuation + raw) in source order. */
+    outputs: OrderedOutputEntry[];
+}
+export declare function computeNewState(anf: ANFProgram, methodName: string, currentState: Record<string, unknown>, args: Record<string, unknown>, constructorArgs?: unknown[]): Record<string, unknown>;
+/**
+ * Like {@link computeNewState} but also returns data outputs resolved
+ * from `this.addDataOutput(...)` and raw outputs resolved from
+ * `this.addRawOutput(...)` in the method body. Entries appear in
+ * declaration order and are what `buildCallTransaction` should emit
+ * between state outputs and the change output so the on-chain
+ * continuation-hash check passes.
+ */
+export declare function computeNewStateAndDataOutputs(anf: ANFProgram, methodName: string, currentState: Record<string, unknown>, args: Record<string, unknown>, constructorArgs?: unknown[]): ExecutionResult;
+/**
+ * Thrown by {@link executeStrict} on the first failing `assert` predicate.
+ * Carries enough context to point a developer at the exact ANF binding
+ * that aborted: the method being executed and the binding name (e.g.
+ * `assertPositive` from the source `assert(amount > 0)`).
+ */
+export declare class AssertionFailureError extends Error {
+    readonly methodName: string;
+    readonly bindingName: string;
+    constructor(methodName: string, bindingName: string);
+}
+/**
+ * Strict-mode counterpart to {@link computeNewStateAndDataOutputs}: walks
+ * the same ANF body but throws {@link AssertionFailureError} on the first
+ * `assert(predicate)` whose predicate evaluates to a falsy value. Use this
+ * before broadcasting a transaction to surface guard failures off-chain
+ * instead of relying on a node rejection. Crypto built-ins (`checkSig`,
+ * `checkMultiSig`, `checkPreimage`) still mock-return `true` — strict mode
+ * only enforces explicit `assert(...)` predicates.
+ */
+export declare function executeStrict(anf: ANFProgram, methodName: string, currentState: Record<string, unknown>, args: Record<string, unknown>, constructorArgs?: unknown[]): ExecutionResult;
+/**
+ * Required cryptographic context for {@link executeOnChainAuthoritative}.
+ *
+ * `sighash` is the 32-byte BIP-143 sighash digest the on-chain VM would
+ * verify signatures against (and that the caller would have signed with
+ * `LocalSigner.sign(...)` before broadcasting). The interpreter:
+ *
+ *  - verifies `checkSig(sig, pk)` by parsing `pk` as a compressed/uncompressed
+ *    secp256k1 point, parsing `sig` as DER (with optional trailing sighash byte
+ *    stripped), and calling `pubKey.verify(sighash, signature)` — a real
+ *    ECDSA verification. Any mismatch returns `false`, which then trips the
+ *    enclosing `assert(...)` and throws.
+ *  - verifies `checkMultiSig(sigs, pks)` by iterating signatures left-to-right
+ *    and consuming pubkeys greedily, mirroring Bitcoin's `OP_CHECKMULTISIG`.
+ *  - verifies `checkPreimage(preimage)` by computing `hash256(preimage)`
+ *    (i.e. `SHA256(SHA256(preimage))`) and comparing it to `sighash`
+ *    byte-for-byte — the on-chain `OP_PUSH_TX` semantic.
+ */
+export interface OnChainCryptoContext {
+    /** 32-byte BIP-143 sighash, as a hex string or `Uint8Array`. */
+    sighash: string | Uint8Array;
+}
+/**
+ * Like {@link executeStrict} but also performs real cryptographic
+ * verification of `checkSig`, `checkMultiSig`, and `checkPreimage` against
+ * the supplied `sighash`. Throws {@link AssertionFailureError} when any
+ * `assert(...)` (including the implicit one wrapping a failed crypto
+ * built-in) fires.
+ *
+ * The `ctx` parameter is mandatory and carries the sighash, so it is
+ * impossible to call this entry point accidentally without supplying the
+ * cryptographic inputs the verification needs.
+ */
+export declare function executeOnChainAuthoritative(anf: ANFProgram, methodName: string, currentState: Record<string, unknown>, args: Record<string, unknown>, constructorArgs: unknown[], ctx: OnChainCryptoContext): ExecutionResult;