@dcasegr/amm-client 0.0.0-stage → 0.38.2

package/dist/vendor/runar/runar-sdk/src/contract.d.ts

@@ -0,0 +1,443 @@
+import type { RunarArtifact } from '../../../../pool/runar-ir-schema.js';
+import type { Provider } from './providers/provider.js';
+import type { Signer } from './signers/signer.js';
+import type { TransactionData, UTXO, DeployOptions, CallOptions, PreparedCall } from './types.js';
+import type { Inscription } from './ordinals/types.js';
+import { Transaction as BsvTransaction } from '@bsv/sdk';
+/**
+ * Deep-review finding C8: opt-out for `finalizeCall`'s pre-broadcast local
+ * dry-run, plus the internal field that carries it from `prepareCall` to
+ * `finalizeCall`.
+ *
+ * This augments (does not redeclare) `CallOptions`/`PreparedCall` from
+ * `./types.js` — kept here rather than in types.ts so this change stays
+ * scoped to contract.ts, its only reader/writer, while that file is being
+ * edited concurrently by other work in this tree.
+ */
+declare module './types.js' {
+    interface CallOptions {
+        /**
+         * Run a local pre-broadcast Spend dry-run of the primary contract input
+         * before `finalizeCall` broadcasts (deep-review C8). The dry-run replays
+         * the fully-signed input through @bsv/sdk's production `Spend`
+         * interpreter (real BIP-143, real OP_CHECKSIG) and throws instead of
+         * broadcasting when the input would be rejected on-chain.
+         *
+         * **Default: OFF (opt-in).** C8 asked for this to default ON, and that is
+         * still the goal — but it is not yet safe to. The local harness currently
+         * produces at least one FALSE REJECTION: it rejects `Auction.bid()`
+         * (`codeseparator-signing.test.ts`, a real contract signed by a real
+         * `LocalSigner`) with "OP_CHECKSIGVERIFY requires that a valid signature
+         * is provided", while the independent real-crypto oracle
+         * (`conformance/witnesses/real-crypto/auction.json`, which drives the same
+         * method deploy->call->Spend through `runStatefulSpend`) ACCEPTS it — so
+         * the transaction is valid and the dry-run's tx modelling is wrong, not
+         * the signature. Nine other pre-existing tests fail the same way on
+         * synthetic stub artifacts whose scripts do not consume their pushed args
+         * (clean-stack violations).
+         *
+         * For a FAIL-CLOSED pre-broadcast gate a false rejection is worse than the
+         * hole it closes: it would block legitimate calls and strand funds. So the
+         * capability ships opt-in until its fidelity is proven against the
+         * real-crypto oracle across the fixture corpus. Flip the default to ON
+         * once `dryRunContractInput` agrees with `runStatefulSpend` on every
+         * `witnesses/real-crypto/*.json` accept case.
+         *
+         * Set `true` to opt in. Do not enable it for setups the local harness
+         * cannot model — e.g. a covenant whose correctness depends on OTHER
+         * inputs' final scripts that aren't known yet at `finalizeCall` time
+         * (multi-party assembly finished by a later step), or a
+         * deliberately-invalid tx built for negative testing.
+         */
+        dryRun?: boolean;
+    }
+    interface PreparedCall {
+        /** @internal C8 — carries CallOptions.dryRun into finalizeCall. */
+        _dryRun: boolean;
+    }
+}
+/**
+ * Producer-side marker (issue #106) for the deliberately-empty branch of an
+ * OR-CHECKSIG method — `checkSig(sigA, pkA) || checkSig(sigB, pkB)`, where
+ * `||` short-circuits (NEW-014), so the second `OP_CHECKSIG` runs only when the
+ * first branch FAILS — and when it does, the first ran with a non-empty
+ * signature. Only the
+ * matching branch supplies a real signature; the failing branch MUST push an
+ * empty signature (OP_0) or BIP146 NULLFAIL rejects the whole spend.
+ *
+ * Pass `EMPTY_SIG` as the call arg for the non-matching `Sig` slot: the SDK
+ * pushes OP_0 for it and never signs it, distinct from `null` (auto-sign) and
+ * an explicit hex-bytes value. Coexists with `null` at the same call —
+ * `call('execute', [null, EMPTY_SIG])` signs only slot 0.
+ *
+ * Uses the global symbol registry so identity holds across duplicate module
+ * instances (bundlers).
+ */
+export declare const EMPTY_SIG: unique symbol;
+/** Type guard: is this call arg the {@link EMPTY_SIG} marker (issue #106)? */
+export declare function isEmptySig(value: unknown): value is typeof EMPTY_SIG;
+/**
+ * True when the locking script looks like OR-CHECKSIG (OP_BOOLOR + OP_CHECKSIG)
+ * rather than multi-sig (OP_CHECKMULTISIG). Used to scope the multi-null-Sig
+ * soft warning so genuine checkMultiSig unlocks are not spammed.
+ *
+ * Exported for unit tests.
+ */
+export declare function isLikelyOrCheckSigMethod(artifact: {
+    asm?: string;
+    script?: string;
+    scriptHex?: string;
+}): boolean;
+/**
+ * Walk a hex-encoded script and return the byte offsets of every
+ * OP_CODESEPARATOR (0xab) that sits at a real opcode boundary (i.e. not inside
+ * push-data). Correctly skips all BSV push opcodes (0x01..0x4b,
+ * OP_PUSHDATA1/2/4).
+ *
+ * Used by getSubscriptForSigning to recover the true on-chain byte offsets when
+ * the in-memory constructor args don't reflect what was actually baked into the
+ * locking script (e.g. after fromTxid populates dummy placeholders).
+ */
+export declare function findCodesepOffsets(scriptHex: string): number[];
+/**
+ * Runtime wrapper for a compiled Runar contract.
+ *
+ * Handles deployment, method invocation, state tracking, and script
+ * construction. Works with any Provider and Signer implementation.
+ *
+ * ```ts
+ * const artifact = JSON.parse(fs.readFileSync('./artifacts/Counter.json', 'utf8'));
+ * const contract = new RunarContract(artifact, [0n]); // constructor args
+ * const { txid } = await contract.deploy(provider, signer, { satoshis: 10000 });
+ * ```
+ */
+export declare class RunarContract {
+    readonly artifact: RunarArtifact;
+    /**
+     * Constructor arguments for the contract, typed as `unknown[]` because
+     * they can be any of the Runar primitive types: `bigint`, `boolean`,
+     * `ByteString` (hex string), `PubKey` (hex string), etc. TypeScript
+     * generics are not practical here since the types depend on the specific
+     * contract being used and are only known at runtime from the ABI.
+     */
+    private readonly constructorArgs;
+    private _state;
+    private _codeScript;
+    private _inscription;
+    private currentUtxo;
+    /** Returns the current UTXO tracked by this contract, if any. */
+    getUtxo(): UTXO | null;
+    private _provider;
+    private _signer;
+    /**
+     * Witness values for intent-covenant intrinsic auto-injected params.
+     * `_prevOutScript_<i>` values are stored per-input-index in `_prevOutScripts`;
+     * `_serialisedOutputs` is stored in `_serialisedOutputs`. Both are hex strings
+     * (normalized in the setters). Read by the call-builder when assembling the
+     * unlocking script for methods that use `extractPrevOutputScript` /
+     * `requireOutputP2PKH`.
+     */
+    private _prevOutScripts;
+    private _serialisedOutputs;
+    constructor(artifact: RunarArtifact, constructorArgs: unknown[]);
+    /**
+     * Store a provider and signer on this contract so they don't need to be
+     * passed to every `deploy()` and `call()` invocation.
+     */
+    connect(provider: Provider, signer: Signer): void;
+    /**
+     * Attach a 1sat ordinals inscription to this contract. The inscription
+     * envelope is injected into the locking script between the compiled code
+     * and the state section (if any). Once deployed, the inscription is
+     * immutable — it persists identically across all state transitions.
+     *
+     * ```ts
+     * contract.withInscription({ contentType: 'image/png', data: pngHex });
+     * ```
+     *
+     * N-043 — THROWS when the envelope would break the contract's own
+     * `SIZE(_codePart)` pin. A stateful contract with a variable-length state
+     * section carries an equality pin on the deployed code-part length, and the
+     * envelope lands INSIDE the code part (see `getCodePartHex`). The compiler
+     * bakes that number before any inscription exists, so the pinned length and
+     * the real one differ by the envelope's size and every honest spend aborts
+     * at OP_VERIFY — with the funds already committed. Refusing here turns a
+     * permanent, silent lock into a loud error before a single satoshi moves.
+     */
+    withInscription(inscription: Inscription): this;
+    /**
+     * Verify that every equality `verify_code_part_len` pin the compiler baked
+     * into this artifact still describes the code part this contract produces.
+     *
+     * The check is the invariant itself, not a restatement of the compiler's
+     * derivation: it decodes the pinned number straight out of the emitted
+     * template and compares it to `getCodePartHex()`. So it permits every
+     * combination that actually works — a stateless contract or a fixed-size
+     * state layout carries no pin at all, and a lower-bound pin is satisfied by
+     * a longer code part — and rejects only the shape that would lock funds.
+     */
+    private assertCodePartLengthPinHonoured;
+    /** Returns the current inscription, if any. */
+    get inscription(): Inscription | null;
+    /**
+     * Resolve provider/signer: explicit args win, then connected, then error.
+     */
+    private resolveProviderSigner;
+    /**
+     * Deploy the contract by creating a UTXO with the locking script.
+     *
+     * Provider and signer can be passed explicitly or omitted to use
+     * the ones stored via `connect()`.
+     */
+    deploy(options: DeployOptions): Promise<{
+        txid: string;
+        tx: TransactionData;
+    }>;
+    deploy(provider: Provider, signer: Signer, options: DeployOptions): Promise<{
+        txid: string;
+        tx: TransactionData;
+    }>;
+    /**
+     * Deploy the contract using a BRC-100 wallet. The wallet owns the coins
+     * and creates the transaction itself via `createAction()`.
+     *
+     * Requires the contract to be connected to a `WalletProvider` (via `connect()`).
+     *
+     * @param options.satoshis     - Satoshis to lock in the contract output (default: 1).
+     * @param options.description  - Description for the wallet action.
+     */
+    deployWithWallet(options?: {
+        satoshis?: number;
+        description?: string;
+        /**
+         * R-062: builtins the caller accepts despite the compiler not claiming
+         * they are sound. Required — naming each one — when the artifact declares
+         * `unsoundPrimitives`; ignored otherwise. Same mechanism and same error as
+         * `DeployOptions.acknowledgeUnsound` on the ordinary `deploy()` path.
+         */
+        acknowledgeUnsound?: readonly string[];
+    }): Promise<{
+        txid: string;
+        outputIndex: number;
+    }>;
+    /**
+     * Call a public method on the contract (spend the UTXO).
+     *
+     * For stateful contracts, a new UTXO is created with the updated state.
+     * Provider and signer can be passed explicitly or omitted to use
+     * the ones stored via `connect()`.
+     */
+    call(methodName: string, args: unknown[], options?: CallOptions): Promise<{
+        txid: string;
+        tx: TransactionData;
+    }>;
+    call(methodName: string, args: unknown[], provider: Provider, signer: Signer, options?: CallOptions): Promise<{
+        txid: string;
+        tx: TransactionData;
+    }>;
+    /**
+     * Build the transaction for a method call without signing the primary
+     * contract input's Sig params. Returns a `PreparedCall` containing the
+     * BIP-143 sighash that external signers need, plus opaque internals for
+     * `finalizeCall()`.
+     *
+     * P2PKH funding inputs and additional contract inputs ARE signed with the
+     * connected signer. Only the primary contract input's Sig params are left
+     * as 72-byte placeholders.
+     */
+    prepareCall(methodName: string, args: unknown[], options?: CallOptions): Promise<PreparedCall>;
+    /**
+     * Complete a prepared call by injecting external signatures and broadcasting.
+     *
+     * @param prepared    — The `PreparedCall` returned by `prepareCall()`.
+     * @param signatures  — Map from arg index to DER signature hex (with sighash byte).
+     *                      Each key must be one of `prepared.sigIndices`.
+     */
+    finalizeCall(prepared: PreparedCall, signatures: Record<number, string>): Promise<{
+        txid: string;
+        tx: TransactionData;
+    }>;
+    /** Get the current contract state (for stateful contracts). */
+    get state(): Record<string, unknown>;
+    /** Update state values directly (for stateful contracts). */
+    setState(newState: Record<string, unknown>): void;
+    /**
+     * Supply the prev-output locking-script witness for input `inputIndex`.
+     * Required for methods that call `extractPrevOutputScript(inputIndex)`,
+     * which the compiler lowers into an auto-injected
+     * `_prevOutScript_<inputIndex>` ABI param.
+     *
+     * @param inputIndex the literal input index passed to extractPrevOutputScript
+     * @param bytes      hex string (with or without 0x prefix) or raw bytes
+     */
+    setPrevOutScript(inputIndex: number, bytes: string | Uint8Array): void;
+    /**
+     * Supply the serialised-outputs witness for the current call.
+     * Required for methods that call `requireOutputP2PKH(...)`, which the
+     * compiler lowers into an auto-injected `_serialisedOutputs` ABI param.
+     *
+     * @param bytes hex string (with or without 0x prefix) or raw bytes
+     */
+    setSerialisedOutputs(bytes: string | Uint8Array): void;
+    /**
+     * Build the trailing witness-hex for the auto-injected intent-intrinsic
+     * params of a method, in ABI order (`_prevOutScript_*` first, then
+     * `_serialisedOutputs`). Each value is pushed via PUSHDATA so that the
+     * on-chain method body's `load_param` lifts the exact bytes the caller set.
+     *
+     * Throws {@link WitnessValueMissingError} for any auto-injected param the
+     * caller hasn't supplied via setPrevOutScript / setSerialisedOutputs.
+     */
+    private buildIntentWitnessHex;
+    /**
+     * Get the full locking script hex for the contract.
+     *
+     * For stateful contracts this includes the code followed by OP_RETURN and
+     * the serialized state fields.
+     */
+    getLockingScript(): string;
+    /**
+     * Build the code portion of the locking script from the artifact and
+     * constructor args. This is the script without any state suffix.
+     */
+    private buildCodeScript;
+    /**
+     * Build the unlocking script for a method call.
+     *
+     * The unlocking script pushes the method arguments onto the stack in
+     * order, followed by a method selector (the method index as a Script
+     * number) if the contract has multiple public methods.
+     */
+    buildUnlockingScript(methodName: string, args: unknown[]): string;
+    /**
+     * Get the code script hex (locking script without state) for use as _codePart.
+     * Returns the code portion that the on-chain contract uses for output reconstruction.
+     * Includes the inscription envelope if one is attached — this is required for
+     * stateful contracts where the on-chain hashOutputs verification includes
+     * the envelope as part of the codePart.
+     *
+     * Public low-level assembly surface: needed for cross-artifact transaction
+     * assembly (see `assembleMultiContractCall`), where a spending tx mixes
+     * covenant inputs from DIFFERENT artifacts and each input's `_codePart` /
+     * continuation script must be built outside `call()`.
+     */
+    getCodePartHex(): string;
+    /**
+     * Adjust a code separator byte offset from the base (template) script to
+     * the fully-substituted script. Both constructor arg slots and codeSepIndex
+     * slots replace OP_0 (1 byte) with encoded push data, shifting subsequent
+     * byte offsets.
+     */
+    private adjustCodeSepOffset;
+    /**
+     * Resolve the adjusted codeSep index values for all codeSepIndex slots,
+     * processing them in ascending template byte-offset order so that each
+     * slot's value correctly accounts for earlier slots' expansions.
+     */
+    private _resolvedCodeSepSlotValues;
+    /**
+     * Get the subscript trimmed at the OP_CODESEPARATOR for a given method.
+     * Used for BIP-143 sighash computation for the user CHECKSIG whenever the
+     * script contains an OP_CODESEPARATOR before it (per BIP-143 / BSV consensus,
+     * for stateful AND terminal methods alike). Returns the full script unchanged
+     * when no OP_CODESEPARATOR is present.
+     *
+     * When `_codeScript` is set (the contract is loaded from chain, or the deploy
+     * script has already been built from real constructor args), walk the actual
+     * script and trim at the true on-chain byte position. This is required
+     * because `fromTxid` populates constructorArgs with dummy placeholders — the
+     * real arg bytes are already baked into the on-chain locking script — so
+     * `adjustCodeSepOffset` computes a shift of zero and returns the wrong offset
+     * whenever the OP_CODESEPARATOR sits after constructor slots that expand at
+     * deploy time. The symptom of using the wrong offset is NULLFAIL at
+     * OP_CHECKSIG for terminal methods.
+     *
+     * Public low-level assembly surface: multi-contract tx assembly must sign
+     * each covenant input's user `Sig` over ITS artifact's codesep-trimmed
+     * subscript, which `call()` only does for its own single primary input.
+     */
+    getSubscriptForSigning(fullScript: string, methodIndex?: number): string;
+    /**
+     * Wrap computeOpPushTx to automatically pass the correct codeSeparatorIndex.
+     * For multi-method contracts, each method has its own separator at a different
+     * byte offset. Uses codeSeparatorIndices[methodIndex] if available, otherwise
+     * falls back to the single codeSeparatorIndex.
+     *
+     * When `_codeScript` is set (chain-loaded, or a deploy script already built
+     * from real constructor args), byte-walk the actual script for the true
+     * on-chain OP_CODESEPARATOR offset — mirroring `getSubscriptForSigning`.
+     * `adjustCodeSepOffset` derives the shift from the in-memory
+     * `constructorArgs`, which are placeholders on the restore path (issue #132);
+     * the byte-walk is independent of those args. The template `adjustCodeSepOffset`
+     * path remains only for template-built (deploy-time) contracts.
+     *
+     * Public low-level assembly surface: each covenant input of a
+     * multi-contract tx needs its own OP_PUSH_TX signature + BIP-143 preimage
+     * computed against ITS artifact's code separator layout.
+     */
+    computeOpPushTxWithCodeSep(tx: BsvTransaction, inputIndex: number, subscript: string, satoshis: number, methodIndex?: number): {
+        sigHex: string;
+        preimageHex: string;
+    };
+    /**
+     * Build the prefix for an unlocking script: optionally _codePart.
+     * needsCodePart should be true only when the method constructs continuation outputs
+     * (non-terminal stateful calls). Terminal and stateless methods don't use _codePart.
+     *
+     * Public low-level assembly surface. BUG-100: the OP_PUSH_TX signature is
+     * derived on-chain from the preimage (see codegen emitCheckPreimageBinding),
+     * so NO signature is pushed here — the stateful unlock layout is
+     * `[_codePart?] args... [_changePKH _changeAmount] [_newAmount] txPreimage
+     * [selector]` (multi-contract assembly rebuilds it per input). `opSig` is
+     * accepted for call-site compatibility but ignored.
+     */
+    buildStatefulPrefix(_opSig: string, needsCodePart?: boolean): string;
+    /**
+     * Reconnect to an existing deployed contract from a known UTXO.
+     *
+     * This is the synchronous equivalent of `fromTxId()` — use it when the
+     * UTXO data is already available (e.g. from an overlay service or cache)
+     * without needing a Provider to fetch the transaction.
+     *
+     * @param artifact - The compiled artifact describing the contract.
+     * @param utxo     - The UTXO containing the contract output.
+     * @returns A RunarContract instance connected to the existing UTXO.
+     */
+    static fromUtxo(artifact: RunarArtifact, utxo: {
+        txid: string;
+        outputIndex: number;
+        satoshis: number;
+        script: string;
+    }): RunarContract;
+    /**
+     * Reconnect to an existing deployed contract from its deployment transaction.
+     *
+     * @param artifact     - The compiled artifact describing the contract.
+     * @param txid         - The transaction ID containing the contract UTXO.
+     * @param outputIndex  - The output index of the contract UTXO.
+     * @param provider     - Blockchain provider.
+     * @returns A RunarContract instance connected to the existing UTXO.
+     */
+    static fromTxId(artifact: RunarArtifact, txid: string, outputIndex: number, provider: Provider): Promise<RunarContract>;
+    private findMethod;
+}
+/**
+ * Encode an argument value as a Bitcoin Script push data element.
+ *
+ * Exported as part of the low-level assembly surface: downstream tooling
+ * (runar-testing's mock-preimage builders) and multi-contract tx assembly (and
+ * any external unlocking-script construction) must encode arguments
+ * byte-identically to `buildUnlockingScript` — share this, don't copy it.
+ */
+export declare function encodeArg(value: unknown): string;
+/**
+ * Encode a bigint as a minimally-encoded Bitcoin Script number push
+ * (OP_0 / OP_1..OP_16 / OP_1NEGATE / sign-magnitude LE push data).
+ * Exported as part of the low-level assembly surface.
+ */
+export declare function encodeScriptNumber(n: bigint): string;
+/**
+ * Encode raw hex bytes as a Bitcoin Script push (direct push / PUSHDATA1/2/4).
+ * Exported as part of the low-level assembly surface.
+ */
+export declare function encodePushData(dataHex: string): string;