@dcasegr/amm-client 0.0.0-stage → 0.38.2

package/dist/vendor/runar/runar-sdk/src/providers/wallet-provider.js

@@ -0,0 +1,297 @@
+// ---------------------------------------------------------------------------
+// runar-sdk/providers/wallet-provider.ts — BRC-100 wallet provider
+// ---------------------------------------------------------------------------
+//
+// Provider implementation that uses a BRC-100 wallet for UTXO management,
+// GorillaPool ARC for broadcast (EF format), and an optional overlay
+// service for tx indexing.
+// ---------------------------------------------------------------------------
+import { txToTransactionData, warnNonFatal } from './provider.js';
+import { buildP2PKHScript } from '../script-utils.js';
+import { Transaction, } from '@bsv/sdk';
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+/**
+ * The default ARC broadcaster. This is a MAINNET endpoint — see R-179 for why
+ * that matters at construction time.
+ */
+const MAINNET_ARC_URL = 'https://arc.gorillapool.io';
+// ---------------------------------------------------------------------------
+// WalletProvider
+// ---------------------------------------------------------------------------
+export class WalletProvider {
+    wallet;
+    signer;
+    basket;
+    fundingTag;
+    arcUrl;
+    overlayUrl;
+    overlayTopics;
+    _network;
+    _feeRate;
+    broadcaster;
+    txCache = new Map();
+    constructor(options) {
+        this.wallet = options.wallet;
+        this.signer = options.signer;
+        this.basket = options.basket;
+        this.fundingTag = options.fundingTag ?? 'funding';
+        this._network = options.network ?? 'mainnet';
+        // R-179: arcUrl and network used to be defaulted independently, so a
+        // provider configured for testnet reported getNetwork() === 'testnet' and
+        // broadcast every transaction to the MAINNET ARC, with nothing to say so.
+        // There is no canonical testnet ARC endpoint in this repo to default to,
+        // so a testnet provider has to name its own rather than inherit one that
+        // points at real money. The sibling GorillaPoolProvider derives its base
+        // URL from the network for the same reason.
+        if (options.arcUrl) {
+            this.arcUrl = options.arcUrl;
+        }
+        else if (this._network === 'mainnet') {
+            this.arcUrl = MAINNET_ARC_URL;
+        }
+        else {
+            throw new Error(`WalletProvider: no default ARC endpoint for network '${this._network}' — ` +
+                `${MAINNET_ARC_URL} is a MAINNET broadcaster. Pass arcUrl explicitly.`);
+        }
+        this.overlayUrl = options.overlayUrl;
+        this.overlayTopics = options.overlayTopics;
+        this._feeRate = options.feeRate ?? 100;
+        this.broadcaster = options.broadcaster;
+    }
+    // -------------------------------------------------------------------------
+    // Typed accessors (used by RunarContract.deployWithWallet; also lets
+    // consumers reach the wallet without reaching into internals)
+    // -------------------------------------------------------------------------
+    /** The BRC-100 wallet client this provider wraps. */
+    get walletClient() {
+        return this.wallet;
+    }
+    /** The wallet basket used for UTXO management. */
+    get basketName() {
+        return this.basket;
+    }
+    // -------------------------------------------------------------------------
+    // Transaction cache
+    // -------------------------------------------------------------------------
+    /** Cache a raw tx hex by its txid (for EF parent lookups). */
+    cacheTx(txid, rawHex) {
+        this.txCache.set(txid, rawHex);
+    }
+    /**
+     * Fetch raw tx hex: local cache → overlay → throw.
+     *
+     * Protected so subclasses can supply parents from another source (their
+     * own index, a node RPC, …); the EF assembly in `broadcastTx` dispatches
+     * through the override.
+     */
+    async fetchRawTx(txid) {
+        const cached = this.txCache.get(txid);
+        if (cached)
+            return cached;
+        if (this.overlayUrl) {
+            const resp = await fetch(`${this.overlayUrl}/api/tx/${txid}/hex`);
+            if (resp.ok) {
+                const hex = (await resp.text()).trim();
+                this.txCache.set(txid, hex);
+                return hex;
+            }
+        }
+        throw new Error(`WalletProvider: could not fetch parent tx ${txid} (not in cache${this.overlayUrl ? ', overlay returned error' : ''})`);
+    }
+    // -------------------------------------------------------------------------
+    // Broadcast
+    // -------------------------------------------------------------------------
+    /**
+     * Broadcast a transaction via ARC in EF format.
+     *
+     * Protected so subclasses can reroute broadcast (e.g. through an overlay
+     * that gates admission) while `broadcast()` and `ensureFunding()` keep
+     * dispatching through the override.
+     */
+    async broadcastTx(tx) {
+        // Attach source transactions for EF format
+        for (const input of tx.inputs) {
+            if (input.sourceTransaction)
+                continue;
+            const parentTxid = input.sourceTXID;
+            if (!parentTxid)
+                continue;
+            const parentHex = await this.fetchRawTx(parentTxid);
+            input.sourceTransaction = Transaction.fromHex(parentHex);
+        }
+        // Issue #107: when a broadcaster is injected, delegate to it so the SDK and
+        // the calling layer share ONE broadcaster instance/config (keeps parent +
+        // child at the same ARC deployment → avoids SEEN_IN_ORPHAN_MEMPOOL). The
+        // structured BroadcastFailure is flattened into a thrown Error to preserve
+        // the existing `broadcast()` contract.
+        if (this.broadcaster) {
+            const result = await this.broadcaster.broadcast(tx);
+            if (result.status === 'error') {
+                throw new Error(`WalletProvider: injected broadcaster failed (${result.code}): ${result.description}`);
+            }
+            const txid = result.txid;
+            this.txCache.set(txid, tx.toHex());
+            if (this.overlayUrl && this.overlayTopics && this.overlayTopics.length > 0) {
+                this.submitToOverlay(tx).catch((e) => warnNonFatal('overlay submission', e));
+            }
+            return txid;
+        }
+        const efBytes = tx.toEFUint8Array();
+        const resp = await fetch(`${this.arcUrl}/v1/tx`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/octet-stream' },
+            body: efBytes.buffer,
+        });
+        if (!resp.ok) {
+            const body = await resp.text();
+            throw new Error(`WalletProvider: ARC broadcast failed (${resp.status}): ${body}`);
+        }
+        const result = (await resp.json());
+        const txid = result.txid;
+        // Cache for future EF lookups
+        this.txCache.set(txid, tx.toHex());
+        // Fire-and-forget: submit to overlay for indexing
+        if (this.overlayUrl && this.overlayTopics && this.overlayTopics.length > 0) {
+            this.submitToOverlay(tx).catch((e) => warnNonFatal('overlay submission', e));
+        }
+        return txid;
+    }
+    /** Submit a transaction to the overlay for indexing (non-fatal).
+     * Protected so subclasses can adapt the submit request to their overlay. */
+    async submitToOverlay(tx) {
+        if (!this.overlayUrl || !this.overlayTopics)
+            return;
+        const beef = tx.toBEEF();
+        await fetch(`${this.overlayUrl}/submit`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Topics': JSON.stringify(this.overlayTopics),
+            },
+            body: JSON.stringify({
+                beef: Array.from(beef),
+                topics: this.overlayTopics,
+            }),
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Provider interface
+    // -------------------------------------------------------------------------
+    /**
+     * Get UTXOs from the wallet's basket.
+     * Returns only spendable P2PKH UTXOs locked to the signer's derived key.
+     */
+    async getUtxos(_address) {
+        const result = await this.wallet.listOutputs({
+            basket: this.basket,
+            tags: [this.fundingTag],
+            tagQueryMode: 'all',
+            include: 'locking scripts',
+            limit: 100,
+            seekPermission: false,
+        });
+        const derivedPubKey = await this.signer.getPublicKey();
+        const expectedScript = buildP2PKHScript(derivedPubKey);
+        const utxos = [];
+        for (const out of result.outputs) {
+            if (!out.spendable || !out.lockingScript)
+                continue;
+            if (out.lockingScript !== expectedScript)
+                continue;
+            const [txid, voutStr] = out.outpoint.split('.');
+            utxos.push({
+                txid: txid,
+                outputIndex: Number(voutStr),
+                satoshis: out.satoshis,
+                script: out.lockingScript,
+            });
+        }
+        return utxos;
+    }
+    async getTransaction(txid) {
+        // R-151: this used to fall back to
+        //   { txid, version: 1, inputs: [], outputs: [], locktime: 0 }
+        // on a cache miss OR a parse failure, so a caller could not tell "this
+        // transaction has no outputs" from "I could not find this transaction".
+        // The same shape was already fixed once in this SDK — txToTransactionData
+        // in providers/provider.ts is that remediation — and never applied here.
+        const cached = this.txCache.get(txid);
+        if (cached === undefined) {
+            throw new Error(`WalletProvider.getTransaction: transaction ${txid} is not in the provider's ` +
+                `cache. A wallet provider only knows transactions it has broadcast or been ` +
+                `given via cacheTx().`);
+        }
+        let tx;
+        try {
+            tx = Transaction.fromHex(cached);
+        }
+        catch (e) {
+            throw new Error(`WalletProvider.getTransaction: cached hex for ${txid} did not parse as a ` +
+                `transaction: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return txToTransactionData(txid, tx);
+    }
+    async broadcast(tx) {
+        return this.broadcastTx(tx);
+    }
+    async getContractUtxo(_scriptHash) {
+        // Contract UTXOs typically come from overlay services or app logic,
+        // not from the wallet provider.
+        return null;
+    }
+    getNetwork() {
+        return this._network;
+    }
+    async getRawTransaction(txid) {
+        return this.fetchRawTx(txid);
+    }
+    async getFeeRate() {
+        return this._feeRate;
+    }
+    // -------------------------------------------------------------------------
+    // Funding
+    // -------------------------------------------------------------------------
+    /**
+     * Ensure there are enough P2PKH funding UTXOs in the wallet basket.
+     * Creates a new funding UTXO via the wallet if the balance is insufficient.
+     *
+     * @param minSatoshis - Minimum total satoshis required.
+     */
+    async ensureFunding(minSatoshis) {
+        const address = await this.signer.getAddress();
+        const utxos = await this.getUtxos(address);
+        const totalAvailable = utxos.reduce((sum, u) => sum + u.satoshis, 0);
+        if (totalAvailable >= minSatoshis)
+            return;
+        const derivedPubKey = await this.signer.getPublicKey();
+        const lockingScript = buildP2PKHScript(derivedPubKey);
+        const fundAmount = minSatoshis - totalAvailable;
+        const result = await this.wallet.createAction({
+            description: 'Runar contract funding',
+            outputs: [{
+                    lockingScript,
+                    satoshis: fundAmount,
+                    outputDescription: 'Funding UTXO',
+                    basket: this.basket,
+                    tags: [this.fundingTag],
+                }],
+        });
+        // Cache the funding tx so child txs can build EF
+        if (result.tx) {
+            try {
+                const tx = Transaction.fromAtomicBEEF(result.tx);
+                const rawHex = tx.toHex();
+                const txid = result.txid || '';
+                if (txid)
+                    this.txCache.set(txid, rawHex);
+                // Broadcast to ARC (may already be known — non-fatal)
+                await this.broadcastTx(Transaction.fromHex(rawHex)).catch((e) => warnNonFatal('funding-tx broadcast', e));
+            }
+            catch (e) {
+                warnNonFatal('funding-tx parse', e);
+            }
+        }
+    }
+}

package/dist/vendor/runar/runar-sdk/src/script-utils.d.ts

@@ -0,0 +1,54 @@
+import type { RunarArtifact } from '../../../../pool/runar-ir-schema.js';
+/**
+ * Hash a 66- or 130-char hex secp256k1 public key into its 40-char hex
+ * hash160 (RIPEMD160(SHA256(pubkey))). Used as the `changePKH` argument
+ * to contract methods and as the input to `buildP2PKHScript`.
+ */
+export declare function pubkeyToPKH(pubkeyHex: string): string;
+/**
+ * Build a standard P2PKH locking script hex from an address, pubkey hash,
+ * or public key.
+ *
+ *   OP_DUP OP_HASH160 OP_PUSH20 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
+ *   76      a9         14        <20 bytes>    88              ac
+ *
+ * Accepted input formats:
+ * - 40-char hex: treated as raw 20-byte pubkey hash (hash160)
+ * - 66-char hex: compressed public key (auto-hashed via hash160)
+ * - 130-char hex: uncompressed public key (auto-hashed via hash160)
+ * - Other: decoded as Base58Check P2PKH address (mainnet version 0x00, or
+ *   testnet/regtest version 0x6f), payload required to be exactly 20 bytes
+ *
+ * Round-three audit M-2: the Base58Check branch used to concatenate whatever
+ * payload came back, with no length and no version check — @bsv/sdk verifies
+ * the checksum, and nothing else. Three measured consequences:
+ *
+ * - a WIF private key (version 0x80, 33-byte payload) produced a 38-byte
+ *   script whose trailing push runs off the end: unparseable, and any change
+ *   sent there is permanently unspendable;
+ * - an xpub (version 0x0488B21E, 78-byte payload) produced an 82-byte script
+ *   with no error raised at all;
+ * - a P2SH address (version 0x05 / 0xc4) produced a syntactically PERFECT
+ *   25-byte script that is a burn — the payload is a script hash, and only
+ *   the version byte says so.
+ *
+ * All three are reachable from `DeployOptions.changeAddress` /
+ * `CallOptions.changeAddress`, which are public caller-supplied fields. Six
+ * peer tiers already gate this; Java's `Base58Check.decodeP2PKH` checks both
+ * length and version, and is the shape followed here.
+ */
+export declare function buildP2PKHScript(addressOrPubKey: string): string;
+export declare function decodeScriptNumber(dataHex: string): bigint;
+/**
+ * Extract constructor argument values from a compiled on-chain script.
+ *
+ * Uses `artifact.constructorSlots` to locate each constructor arg at its
+ * byte offset, reads the push data, and deserializes according to the
+ * ABI param type.
+ */
+export declare function extractConstructorArgs(artifact: RunarArtifact, scriptHex: string): Record<string, unknown>;
+/**
+ * Determine whether a given on-chain script was produced from the given
+ * contract artifact (regardless of what constructor args were used).
+ */
+export declare function matchesArtifact(artifact: RunarArtifact, scriptHex: string): boolean;

package/dist/vendor/runar/runar-sdk/src/script-utils.js

@@ -0,0 +1,252 @@
+// ---------------------------------------------------------------------------
+// runar-sdk/script-utils.ts — Script utilities
+// ---------------------------------------------------------------------------
+import { Hash, Utils } from '@bsv/sdk';
+import { abiValueEncoding } from '../../../../pool/runar-ir-schema.js';
+import { findLastOpReturn } from './state.js';
+/**
+ * Hash a 66- or 130-char hex secp256k1 public key into its 40-char hex
+ * hash160 (RIPEMD160(SHA256(pubkey))). Used as the `changePKH` argument
+ * to contract methods and as the input to `buildP2PKHScript`.
+ */
+export function pubkeyToPKH(pubkeyHex) {
+    return Utils.toHex(Hash.hash160(Utils.toArray(pubkeyHex, 'hex')));
+}
+/**
+ * Build a standard P2PKH locking script hex from an address, pubkey hash,
+ * or public key.
+ *
+ *   OP_DUP OP_HASH160 OP_PUSH20 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
+ *   76      a9         14        <20 bytes>    88              ac
+ *
+ * Accepted input formats:
+ * - 40-char hex: treated as raw 20-byte pubkey hash (hash160)
+ * - 66-char hex: compressed public key (auto-hashed via hash160)
+ * - 130-char hex: uncompressed public key (auto-hashed via hash160)
+ * - Other: decoded as Base58Check P2PKH address (mainnet version 0x00, or
+ *   testnet/regtest version 0x6f), payload required to be exactly 20 bytes
+ *
+ * Round-three audit M-2: the Base58Check branch used to concatenate whatever
+ * payload came back, with no length and no version check — @bsv/sdk verifies
+ * the checksum, and nothing else. Three measured consequences:
+ *
+ * - a WIF private key (version 0x80, 33-byte payload) produced a 38-byte
+ *   script whose trailing push runs off the end: unparseable, and any change
+ *   sent there is permanently unspendable;
+ * - an xpub (version 0x0488B21E, 78-byte payload) produced an 82-byte script
+ *   with no error raised at all;
+ * - a P2SH address (version 0x05 / 0xc4) produced a syntactically PERFECT
+ *   25-byte script that is a burn — the payload is a script hash, and only
+ *   the version byte says so.
+ *
+ * All three are reachable from `DeployOptions.changeAddress` /
+ * `CallOptions.changeAddress`, which are public caller-supplied fields. Six
+ * peer tiers already gate this; Java's `Base58Check.decodeP2PKH` checks both
+ * length and version, and is the shape followed here.
+ */
+export function buildP2PKHScript(addressOrPubKey) {
+    let pubKeyHash;
+    if (/^[0-9a-fA-F]{40}$/.test(addressOrPubKey)) {
+        // Already a raw 20-byte pubkey hash in hex
+        pubKeyHash = addressOrPubKey;
+    }
+    else if (/^[0-9a-fA-F]{66}$/.test(addressOrPubKey) || /^[0-9a-fA-F]{130}$/.test(addressOrPubKey)) {
+        // Compressed (33 bytes) or uncompressed (65 bytes) public key — hash it
+        pubKeyHash = pubkeyToPKH(addressOrPubKey);
+    }
+    else {
+        // Decode Base58Check address to extract the 20-byte pubkey hash. The
+        // checksum is verified by `fromBase58Check` itself (it throws
+        // `Invalid checksum`); length and version are checked here (M-2).
+        const decoded = Utils.fromBase58Check(addressOrPubKey);
+        const dataHex = typeof decoded.data === 'string'
+            ? decoded.data
+            : Utils.toHex(decoded.data);
+        const prefixHex = typeof decoded.prefix === 'string'
+            ? decoded.prefix
+            : Utils.toHex(decoded.prefix);
+        if (dataHex.length !== 40) {
+            throw new Error(`buildP2PKHScript: '${addressOrPubKey}' is not a P2PKH address — its Base58Check ` +
+                `payload is ${dataHex.length / 2} bytes, expected 20. A WIF private key, an ` +
+                'xpub/xprv, or any other Base58Check string is not an address; pass a P2PKH ' +
+                'address, a 40-char hash160, or a 66-/130-char public key.');
+        }
+        if (prefixHex !== '00' && prefixHex !== '6f') {
+            throw new Error(`buildP2PKHScript: '${addressOrPubKey}' is not a P2PKH address — Base58Check ` +
+                `version byte 0x${prefixHex}, expected 0x00 (mainnet) or 0x6f (testnet/regtest). ` +
+                'A P2SH address (0x05 / 0xc4) carries a SCRIPT hash: wrapping it in a P2PKH ' +
+                'script produces a well-formed script that burns the output.');
+        }
+        pubKeyHash = dataHex;
+    }
+    return '76a914' + pubKeyHash + '88ac';
+}
+// ---------------------------------------------------------------------------
+// Constructor arg extraction
+// ---------------------------------------------------------------------------
+function readScriptElement(hex, offset) {
+    const opcode = parseInt(hex.slice(offset, offset + 2), 16);
+    if (opcode === 0x00)
+        return { dataHex: '', totalHexChars: 2, opcode };
+    if (opcode >= 0x01 && opcode <= 0x4b) {
+        const dataLen = opcode * 2;
+        return { dataHex: hex.slice(offset + 2, offset + 2 + dataLen), totalHexChars: 2 + dataLen, opcode };
+    }
+    if (opcode === 0x4c) {
+        const len = parseInt(hex.slice(offset + 2, offset + 4), 16);
+        const dataLen = len * 2;
+        return { dataHex: hex.slice(offset + 4, offset + 4 + dataLen), totalHexChars: 4 + dataLen, opcode };
+    }
+    if (opcode === 0x4d) {
+        const lo = parseInt(hex.slice(offset + 2, offset + 4), 16);
+        const hi = parseInt(hex.slice(offset + 4, offset + 6), 16);
+        const len = lo | (hi << 8);
+        const dataLen = len * 2;
+        return { dataHex: hex.slice(offset + 6, offset + 6 + dataLen), totalHexChars: 6 + dataLen, opcode };
+    }
+    if (opcode === 0x4e) {
+        const b0 = parseInt(hex.slice(offset + 2, offset + 4), 16);
+        const b1 = parseInt(hex.slice(offset + 4, offset + 6), 16);
+        const b2 = parseInt(hex.slice(offset + 6, offset + 8), 16);
+        const b3 = parseInt(hex.slice(offset + 8, offset + 10), 16);
+        const len = b0 | (b1 << 8) | (b2 << 16) | (b3 << 24);
+        const dataLen = len * 2;
+        return { dataHex: hex.slice(offset + 10, offset + 10 + dataLen), totalHexChars: 10 + dataLen, opcode };
+    }
+    return { dataHex: '', totalHexChars: 2, opcode };
+}
+export function decodeScriptNumber(dataHex) {
+    if (dataHex.length === 0)
+        return 0n;
+    const bytes = [];
+    for (let i = 0; i < dataHex.length; i += 2)
+        bytes.push(parseInt(dataHex.slice(i, i + 2), 16));
+    const negative = (bytes[bytes.length - 1] & 0x80) !== 0;
+    bytes[bytes.length - 1] &= 0x7f;
+    let result = 0n;
+    for (let i = bytes.length - 1; i >= 0; i--)
+        result = (result << 8n) | BigInt(bytes[i]);
+    if (result === 0n)
+        return 0n;
+    return negative ? -result : result;
+}
+function interpretScriptElement(opcode, dataHex, type) {
+    // Table-driven, NOT a hand-maintained `case` list: every spelling the
+    // compiler can emit must land in the right branch, and the two that did not
+    // (`RabinSig`/`RabinPubKey`, and the canonical `boolean`) each turned a
+    // value into a hex string here. `abiValueEncoding` is the same table the
+    // compiler stamps `ConstructorSlot.valueEncoding` from, so a new alias can
+    // only ever be added in one place.
+    switch (abiValueEncoding(type)) {
+        case 'scriptnum': {
+            if (opcode === 0x00)
+                return 0n;
+            if (opcode >= 0x51 && opcode <= 0x60)
+                return BigInt(opcode - 0x50);
+            if (opcode === 0x4f)
+                return -1n;
+            return decodeScriptNumber(dataHex);
+        }
+        case 'bool': {
+            if (opcode === 0x00)
+                return false;
+            if (opcode === 0x51)
+                return true;
+            return dataHex !== '00';
+        }
+        default: {
+            // S1: a ByteString (or other non-numeric) ctor arg whose 1-byte value
+            // was MINIMALDATA-encoded as OP_1..OP_16 / OP_1NEGATE carries no
+            // separate data bytes in the script — `readScriptElement` reports an
+            // empty `dataHex` for these opcodes (they aren't direct pushes or
+            // OP_PUSHDATA*). The opcode itself IS the value; reconstruct it
+            // instead of forwarding the (empty) dataHex. OP_0 correctly falls
+            // through to `dataHex` (the empty string), matching OP_0's true
+            // semantics (pushes `[]`, not a 1-byte `0x00`).
+            if (opcode >= 0x51 && opcode <= 0x60)
+                return (opcode - 0x50).toString(16).padStart(2, '0');
+            if (opcode === 0x4f)
+                return '81';
+            return dataHex;
+        }
+    }
+}
+/**
+ * Extract constructor argument values from a compiled on-chain script.
+ *
+ * Uses `artifact.constructorSlots` to locate each constructor arg at its
+ * byte offset, reads the push data, and deserializes according to the
+ * ABI param type.
+ */
+export function extractConstructorArgs(artifact, scriptHex) {
+    if (!artifact.constructorSlots || artifact.constructorSlots.length === 0)
+        return {};
+    let codeHex = scriptHex;
+    if (artifact.stateFields && artifact.stateFields.length > 0) {
+        const opReturnPos = findLastOpReturn(scriptHex);
+        if (opReturnPos !== -1)
+            codeHex = scriptHex.slice(0, opReturnPos);
+    }
+    // Walk EVERY slot in byte order. A constructor param referenced more than
+    // once in the contract body emits one slot per reference, and each
+    // occurrence's encoded width contributes to the cumulative offset shift —
+    // deduplicating before the walk drops those widths and mis-aligns every
+    // later slot on artifacts with repeated references. The VALUE is taken
+    // from the first occurrence per param.
+    const slots = [...artifact.constructorSlots].sort((a, b) => a.byteOffset - b.byteOffset);
+    const result = {};
+    const assigned = new Set();
+    let cumulativeShift = 0;
+    for (const slot of slots) {
+        const adjustedHexOffset = (slot.byteOffset + cumulativeShift) * 2;
+        const elem = readScriptElement(codeHex, adjustedHexOffset);
+        // Template placeholders are exactly 1 byte, so the shift contributed by
+        // each occurrence is its encoded width minus that byte.
+        cumulativeShift += elem.totalHexChars / 2 - 1;
+        if (assigned.has(slot.paramIndex))
+            continue;
+        assigned.add(slot.paramIndex);
+        const param = artifact.abi.constructor.params[slot.paramIndex];
+        if (!param)
+            continue;
+        result[param.name] = interpretScriptElement(elem.opcode, elem.dataHex, param.type);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Script matching
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether a given on-chain script was produced from the given
+ * contract artifact (regardless of what constructor args were used).
+ */
+export function matchesArtifact(artifact, scriptHex) {
+    let codeHex = scriptHex;
+    if (artifact.stateFields && artifact.stateFields.length > 0) {
+        const opReturnPos = findLastOpReturn(scriptHex);
+        if (opReturnPos !== -1)
+            codeHex = scriptHex.slice(0, opReturnPos);
+    }
+    const template = artifact.script;
+    if (!artifact.constructorSlots || artifact.constructorSlots.length === 0)
+        return codeHex === template;
+    const seenOffsets = new Set();
+    const slots = [...artifact.constructorSlots]
+        .sort((a, b) => a.byteOffset - b.byteOffset)
+        .filter((slot) => { if (seenOffsets.has(slot.byteOffset))
+        return false; seenOffsets.add(slot.byteOffset); return true; });
+    let templatePos = 0;
+    let codePos = 0;
+    for (const slot of slots) {
+        const slotHexOffset = slot.byteOffset * 2;
+        const templateSegment = template.slice(templatePos, slotHexOffset);
+        const codeSegment = codeHex.slice(codePos, codePos + templateSegment.length);
+        if (templateSegment !== codeSegment)
+            return false;
+        templatePos = slotHexOffset + 2;
+        const elemOffset = codePos + templateSegment.length;
+        const elem = readScriptElement(codeHex, elemOffset);
+        codePos = elemOffset + elem.totalHexChars;
+    }
+    return template.slice(templatePos) === codeHex.slice(codePos);
+}

package/dist/vendor/runar/runar-sdk/src/signers/signer.d.ts

@@ -0,0 +1,17 @@
+export interface Signer {
+    /** Get the hex-encoded compressed public key (33 bytes = 66 hex chars). */
+    getPublicKey(): Promise<string>;
+    /** Get the BSV address (Base58Check-encoded). */
+    getAddress(): Promise<string>;
+    /**
+     * Sign a transaction input.
+     *
+     * @param txHex       - The full raw transaction hex being signed.
+     * @param inputIndex  - Index of the input being signed.
+     * @param subscript   - The locking script of the UTXO being spent (hex).
+     * @param satoshis    - The satoshi value of the UTXO being spent.
+     * @param sigHashType - Sighash flags (defaults to ALL | FORKID = 0x41).
+     * @returns The DER-encoded signature with sighash byte appended, hex-encoded.
+     */
+    sign(txHex: string, inputIndex: number, subscript: string, satoshis: number, sigHashType?: number): Promise<string>;
+}

package/dist/vendor/runar/runar-sdk/src/signers/signer.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// runar-sdk/signers/signer.ts — Signer interface
+// ---------------------------------------------------------------------------
+export {};

package/dist/vendor/runar/runar-sdk/src/spend-safety.d.ts

@@ -0,0 +1,31 @@
+/**
+ * NEW-005: @bsv/sdk's `Spend` destroys the scripts it is given.
+ *
+ * `Spend` pushes a script chunk's `data` array onto its stack BY REFERENCE, and
+ * at least one opcode mutates its operand in place — `OP_NUM2BIN` does
+ * `rawnum[rawnum.length - 1] &= 0x7f` (see `Spend.js`) to strip the sign bit
+ * before zero-padding. A stateful continuation serialises every mutable state
+ * field with OP_NUM2BIN, so evaluating a call that writes a NEGATIVE
+ * unlocking-script push into state permanently clears the sign bit of that push
+ * inside the caller's own `Script` object: a `-34` push becomes `+34`.
+ *
+ * The corruption is invisible to serialisation. `Script.fromBinary` seeds
+ * `rawBytesCache`/`hexCache` from the original bytes, and mutating
+ * `chunks[i].data` does not invalidate them, so `toHex()` keeps returning the
+ * true bytes and nothing wrong is ever broadcast. The damage is confined to the
+ * NEXT in-memory evaluation of the same object, which sees the wrong value and
+ * rejects a transaction the network accepts — a FALSE REJECTION.
+ *
+ * Every `new Spend(...)` must therefore be handed scripts it is free to
+ * destroy. `fromHex` re-parses into fresh chunks with fresh `data` arrays.
+ *
+ * Only the two scripts `Spend` EXECUTES need detaching. The `outputs` array is
+ * read solely by `TransactionSignature.formatBytes`, which serialises each
+ * output's locking script and never pushes it, so passing `tx.outputs` by
+ * reference is harmless (and cheaper than deep-copying every output script).
+ */
+import { LockingScript, UnlockingScript, type Script } from '@bsv/sdk';
+/** A private copy of `script` that `Spend` may corrupt without consequence. */
+export declare function detachLockingScript(script: Script): LockingScript;
+/** A private copy of `script` that `Spend` may corrupt without consequence. */
+export declare function detachUnlockingScript(script: Script): UnlockingScript;