@dcasegr/amm-client 0.0.0-stage → 0.38.2

package/dist/vendor/runar/runar-sdk/src/ordinals/envelope.js

@@ -0,0 +1,272 @@
+// ---------------------------------------------------------------------------
+// runar-sdk/ordinals/envelope.ts — Build and parse 1sat ordinal inscriptions
+// ---------------------------------------------------------------------------
+//
+// Envelope layout:
+//   OP_FALSE OP_IF PUSH("ord") OP_1 PUSH(<content-type>) OP_0 PUSH(<data>) OP_ENDIF
+//
+// Hex:
+//   00 63 03 6f7264 51 <push content-type> 00 <push data> 68
+//
+// The envelope is a no-op (OP_FALSE causes the IF block to be skipped)
+// and can be placed anywhere in a script without affecting execution.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Push-data encoding (same logic as contract.ts / state.ts, kept local to
+// avoid exporting private helpers from those modules)
+// ---------------------------------------------------------------------------
+function encodePushData(dataHex) {
+    if (dataHex.length === 0)
+        return '00'; // OP_0
+    const len = dataHex.length / 2;
+    if (len <= 75) {
+        return len.toString(16).padStart(2, '0') + dataHex;
+    }
+    else if (len <= 0xff) {
+        return '4c' + len.toString(16).padStart(2, '0') + dataHex;
+    }
+    else if (len <= 0xffff) {
+        const lo = (len & 0xff).toString(16).padStart(2, '0');
+        const hi = ((len >> 8) & 0xff).toString(16).padStart(2, '0');
+        return '4d' + lo + hi + dataHex;
+    }
+    const b0 = (len & 0xff).toString(16).padStart(2, '0');
+    const b1 = ((len >> 8) & 0xff).toString(16).padStart(2, '0');
+    const b2 = ((len >> 16) & 0xff).toString(16).padStart(2, '0');
+    const b3 = ((len >> 24) & 0xff).toString(16).padStart(2, '0');
+    return '4e' + b0 + b1 + b2 + b3 + dataHex;
+}
+/** Convert a UTF-8 string to its hex representation. */
+function utf8ToHex(str) {
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(str);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/** Convert a hex string to UTF-8. */
+function hexToUtf8(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+    }
+    const decoder = new TextDecoder();
+    return decoder.decode(bytes);
+}
+// ---------------------------------------------------------------------------
+// Build
+// ---------------------------------------------------------------------------
+/**
+ * Build a 1sat ordinals inscription envelope as hex.
+ *
+ * @param contentType - MIME type (e.g. "image/png", "application/bsv-20")
+ * @param data - Hex-encoded inscription content
+ * @returns Hex string of the full envelope script fragment
+ */
+export function buildInscriptionEnvelope(contentType, data) {
+    const contentTypeHex = utf8ToHex(contentType);
+    // OP_FALSE (00) OP_IF (63) PUSH "ord" (03 6f7264) OP_1 (51)
+    let hex = '006303' + '6f7264' + '51';
+    // PUSH content-type
+    hex += encodePushData(contentTypeHex);
+    // OP_0 (00) — content delimiter
+    hex += '00';
+    // PUSH data
+    hex += encodePushData(data);
+    // OP_ENDIF (68)
+    hex += '68';
+    return hex;
+}
+// ---------------------------------------------------------------------------
+// Parse / Find
+// ---------------------------------------------------------------------------
+/**
+ * Read a push-data value at the given hex offset. Returns the pushed data
+ * (hex) and the total number of hex chars consumed (including the length
+ * prefix).
+ */
+function readPushData(scriptHex, offset) {
+    if (offset + 2 > scriptHex.length)
+        return null;
+    const opcode = parseInt(scriptHex.slice(offset, offset + 2), 16);
+    if (opcode >= 0x01 && opcode <= 0x4b) {
+        const dataLen = opcode * 2;
+        if (offset + 2 + dataLen > scriptHex.length)
+            return null;
+        return { data: scriptHex.slice(offset + 2, offset + 2 + dataLen), bytesRead: 2 + dataLen };
+    }
+    else if (opcode === 0x4c) {
+        // OP_PUSHDATA1
+        if (offset + 4 > scriptHex.length)
+            return null;
+        const len = parseInt(scriptHex.slice(offset + 2, offset + 4), 16);
+        const dataLen = len * 2;
+        if (offset + 4 + dataLen > scriptHex.length)
+            return null;
+        return { data: scriptHex.slice(offset + 4, offset + 4 + dataLen), bytesRead: 4 + dataLen };
+    }
+    else if (opcode === 0x4d) {
+        // OP_PUSHDATA2
+        if (offset + 6 > scriptHex.length)
+            return null;
+        const lo = parseInt(scriptHex.slice(offset + 2, offset + 4), 16);
+        const hi = parseInt(scriptHex.slice(offset + 4, offset + 6), 16);
+        const len = lo | (hi << 8);
+        const dataLen = len * 2;
+        if (offset + 6 + dataLen > scriptHex.length)
+            return null;
+        return { data: scriptHex.slice(offset + 6, offset + 6 + dataLen), bytesRead: 6 + dataLen };
+    }
+    else if (opcode === 0x4e) {
+        // OP_PUSHDATA4
+        if (offset + 10 > scriptHex.length)
+            return null;
+        const b0 = parseInt(scriptHex.slice(offset + 2, offset + 4), 16);
+        const b1 = parseInt(scriptHex.slice(offset + 4, offset + 6), 16);
+        const b2 = parseInt(scriptHex.slice(offset + 6, offset + 8), 16);
+        const b3 = parseInt(scriptHex.slice(offset + 8, offset + 10), 16);
+        const len = b0 | (b1 << 8) | (b2 << 16) | (b3 << 24);
+        const dataLen = len * 2;
+        if (offset + 10 + dataLen > scriptHex.length)
+            return null;
+        return { data: scriptHex.slice(offset + 10, offset + 10 + dataLen), bytesRead: 10 + dataLen };
+    }
+    return null;
+}
+/**
+ * Compute the number of hex chars an opcode occupies (including its push
+ * data) so we can advance past it while walking a script.
+ */
+function opcodeSize(scriptHex, offset) {
+    if (offset + 2 > scriptHex.length)
+        return 2;
+    const opcode = parseInt(scriptHex.slice(offset, offset + 2), 16);
+    if (opcode >= 0x01 && opcode <= 0x4b) {
+        return 2 + opcode * 2;
+    }
+    else if (opcode === 0x4c) {
+        if (offset + 4 > scriptHex.length)
+            return 2;
+        const len = parseInt(scriptHex.slice(offset + 2, offset + 4), 16);
+        return 4 + len * 2;
+    }
+    else if (opcode === 0x4d) {
+        if (offset + 6 > scriptHex.length)
+            return 2;
+        const lo = parseInt(scriptHex.slice(offset + 2, offset + 4), 16);
+        const hi = parseInt(scriptHex.slice(offset + 4, offset + 6), 16);
+        return 6 + (lo | (hi << 8)) * 2;
+    }
+    else if (opcode === 0x4e) {
+        if (offset + 10 > scriptHex.length)
+            return 2;
+        const b0 = parseInt(scriptHex.slice(offset + 2, offset + 4), 16);
+        const b1 = parseInt(scriptHex.slice(offset + 4, offset + 6), 16);
+        const b2 = parseInt(scriptHex.slice(offset + 6, offset + 8), 16);
+        const b3 = parseInt(scriptHex.slice(offset + 8, offset + 10), 16);
+        return 10 + (b0 | (b1 << 8) | (b2 << 16) | (b3 << 24)) * 2;
+    }
+    return 2; // all other opcodes are 1 byte
+}
+/**
+ * Find the inscription envelope within a script hex string.
+ *
+ * Walks the script as Bitcoin Script opcodes (identical in shape to
+ * `findLastOpReturn` in state.ts) looking for the pattern:
+ *   OP_FALSE(00) OP_IF(63) PUSH3 "ord"(03 6f7264) ...
+ *
+ * @returns Hex-char offsets of the envelope, or null if not found.
+ */
+export function findInscriptionEnvelope(scriptHex) {
+    let offset = 0;
+    const len = scriptHex.length;
+    while (offset + 2 <= len) {
+        const opcode = parseInt(scriptHex.slice(offset, offset + 2), 16);
+        // Look for OP_FALSE (0x00)
+        if (opcode === 0x00) {
+            // Check: OP_IF (63) PUSH3 (03) "ord" (6f7264)
+            if (offset + 12 <= len &&
+                scriptHex.slice(offset + 2, offset + 4) === '63' && // OP_IF
+                scriptHex.slice(offset + 4, offset + 12) === '036f7264' // PUSH3 "ord"
+            ) {
+                const envelopeStart = offset;
+                // Skip: OP_FALSE(2) + OP_IF(2) + PUSH3 "ord"(8) = 12 hex chars
+                let pos = offset + 12;
+                // Expect OP_1 (0x51)
+                if (pos + 2 > len || scriptHex.slice(pos, pos + 2) !== '51') {
+                    offset += 2;
+                    continue;
+                }
+                pos += 2; // skip OP_1
+                // Read content-type push
+                const ctPush = readPushData(scriptHex, pos);
+                if (!ctPush) {
+                    offset += 2;
+                    continue;
+                }
+                pos += ctPush.bytesRead;
+                // Expect OP_0 (0x00) — content delimiter
+                if (pos + 2 > len || scriptHex.slice(pos, pos + 2) !== '00') {
+                    offset += 2;
+                    continue;
+                }
+                pos += 2; // skip OP_0
+                // Read data push
+                const dataPush = readPushData(scriptHex, pos);
+                if (!dataPush) {
+                    offset += 2;
+                    continue;
+                }
+                pos += dataPush.bytesRead;
+                // Expect OP_ENDIF (0x68)
+                if (pos + 2 > len || scriptHex.slice(pos, pos + 2) !== '68') {
+                    offset += 2;
+                    continue;
+                }
+                pos += 2; // skip OP_ENDIF
+                return { startHex: envelopeStart, endHex: pos };
+            }
+        }
+        // Advance past this opcode
+        offset += opcodeSize(scriptHex, offset);
+    }
+    return null;
+}
+/**
+ * Parse an inscription envelope from a script hex string.
+ *
+ * @returns The inscription data, or null if no envelope is found.
+ */
+export function parseInscriptionEnvelope(scriptHex) {
+    const bounds = findInscriptionEnvelope(scriptHex);
+    if (!bounds)
+        return null;
+    const envelopeHex = scriptHex.slice(bounds.startHex, bounds.endHex);
+    // Parse the envelope contents:
+    // 00 63 03 6f7264 51 <ct-push> 00 <data-push> 68
+    let pos = 12; // skip OP_FALSE + OP_IF + PUSH3 "ord"
+    pos += 2; // skip OP_1
+    const ctPush = readPushData(envelopeHex, pos);
+    if (!ctPush)
+        return null;
+    pos += ctPush.bytesRead;
+    pos += 2; // skip OP_0
+    const dataPush = readPushData(envelopeHex, pos);
+    if (!dataPush)
+        return null;
+    return {
+        contentType: hexToUtf8(ctPush.data),
+        data: dataPush.data,
+    };
+}
+/**
+ * Remove the inscription envelope from a script, returning the bare script.
+ *
+ * @returns Script hex with the envelope removed, or the original if none found.
+ */
+export function stripInscriptionEnvelope(scriptHex) {
+    const bounds = findInscriptionEnvelope(scriptHex);
+    if (!bounds)
+        return scriptHex;
+    return scriptHex.slice(0, bounds.startHex) + scriptHex.slice(bounds.endHex);
+}

package/dist/vendor/runar/runar-sdk/src/ordinals/types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Inscription data: content type and hex-encoded payload.
+ *
+ * The `data` field is a hex string representing the raw inscription bytes.
+ * For text content, encode the UTF-8 bytes as hex first. For BSV-20 JSON,
+ * use the `BSV20` / `BSV21` helper classes which handle encoding.
+ */
+export interface Inscription {
+    contentType: string;
+    data: string;
+}
+/**
+ * Hex-char offsets bounding an inscription envelope within a script.
+ * Used internally by `findInscriptionEnvelope` and `stripInscriptionEnvelope`.
+ */
+export interface EnvelopeBounds {
+    /** Hex-char offset where the envelope starts (at OP_FALSE). */
+    startHex: number;
+    /** Hex-char offset where the envelope ends (after OP_ENDIF). */
+    endHex: number;
+}

package/dist/vendor/runar/runar-sdk/src/ordinals/types.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// runar-sdk/ordinals/types.ts — Types for 1sat ordinals support
+// ---------------------------------------------------------------------------
+export {};

package/dist/vendor/runar/runar-sdk/src/providers/provider.d.ts

@@ -0,0 +1,65 @@
+import type { Transaction } from '@bsv/sdk';
+import type { TransactionData, UTXO } from '../types.js';
+export interface Provider {
+    /** Fetch a transaction by its txid (as a plain data shape). */
+    getTransaction(txid: string): Promise<TransactionData>;
+    /**
+     * Broadcast a transaction. Returns the txid on success.
+     * Accepts a @bsv/sdk Transaction object — implementations call
+     * `tx.toHex()` (or `tx.toHexEF()` for ARC) as needed.
+     */
+    broadcast(tx: Transaction): Promise<string>;
+    /** Get all UTXOs for a given address. */
+    getUtxos(address: string): Promise<UTXO[]>;
+    /**
+     * Get the UTXO holding a contract identified by its script hash.
+     * Returns null if no matching UTXO is found on chain.
+     */
+    getContractUtxo(scriptHash: string): Promise<UTXO | null>;
+    /** Return the network this provider is connected to. */
+    getNetwork(): 'mainnet' | 'testnet';
+    /**
+     * Get the current fee rate in satoshis per KB (1000 bytes).
+     * Defaults to 100 sat/KB for BSV (0.1 sat/byte standard relay fee).
+     */
+    getFeeRate(): Promise<number>;
+    /** Fetch the raw transaction hex by its txid. */
+    getRawTransaction(txid: string): Promise<string>;
+}
+/**
+ * Report a failure that is deliberately non-fatal (R-273).
+ *
+ * Four paths in this SDK — two overlay submissions, the funding broadcast and
+ * the BEEF parse after deploy — are fire-and-forget by design: the caller's
+ * transaction is already broadcast, and an indexing or caching failure must not
+ * turn a successful spend into a thrown error. They were written as
+ * `.catch(() => {})` and `catch { /* non-fatal *\/ }`, which is the intent
+ * correctly expressed and the evidence thrown away: an overlay that is down
+ * looks exactly like an overlay that is fine.
+ *
+ * `console.warn` is what the rest of this SDK already uses for advisory
+ * failures (contract.ts and providers/mock.ts), so these now match.
+ */
+export declare function warnNonFatal(context: string, err: unknown): void;
+/**
+ * Audit finding C4: project a locally-held @bsv/sdk `Transaction` into the
+ * plain `TransactionData` shape `getTransaction()` returns.
+ *
+ * Two call sites need exactly this, and they must not drift apart:
+ *   - `MockProvider.broadcast()` registers the tx it just accepted, so
+ *     `getTransaction()` can resolve it instead of throwing "not found".
+ *   - `RunarContract.deploy()` / `finalizeCall()` fall back to it when
+ *     `provider.getTransaction()` fails (a real node can 404 a transaction it
+ *     has accepted but not yet indexed).
+ *
+ * Both previously improvised their own shape, and the contract.ts one
+ * improvised an EMPTY one — `inputs: []`, `outputs: []` — indistinguishable
+ * from a confirmed transaction with no outputs, which is what made every
+ * post-broadcast `result.tx.outputs` assertion vacuous. Lives here because
+ * `providers/provider.ts` is a leaf both sides already import.
+ *
+ * `txid` is passed in rather than read off `tx`: the mock provider assigns
+ * synthetic txids, and the real deploy/call path uses the txid the provider
+ * returned from `broadcast()`.
+ */
+export declare function txToTransactionData(txid: string, tx: Transaction): TransactionData;

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

@@ -0,0 +1,59 @@
+// ---------------------------------------------------------------------------
+// runar-sdk/providers/provider.ts — Provider interface for blockchain access
+// ---------------------------------------------------------------------------
+/**
+ * Report a failure that is deliberately non-fatal (R-273).
+ *
+ * Four paths in this SDK — two overlay submissions, the funding broadcast and
+ * the BEEF parse after deploy — are fire-and-forget by design: the caller's
+ * transaction is already broadcast, and an indexing or caching failure must not
+ * turn a successful spend into a thrown error. They were written as
+ * `.catch(() => {})` and `catch { /* non-fatal *\/ }`, which is the intent
+ * correctly expressed and the evidence thrown away: an overlay that is down
+ * looks exactly like an overlay that is fine.
+ *
+ * `console.warn` is what the rest of this SDK already uses for advisory
+ * failures (contract.ts and providers/mock.ts), so these now match.
+ */
+export function warnNonFatal(context, err) {
+    console.warn(`runar-sdk: ${context} (non-fatal):`, err);
+}
+/**
+ * Audit finding C4: project a locally-held @bsv/sdk `Transaction` into the
+ * plain `TransactionData` shape `getTransaction()` returns.
+ *
+ * Two call sites need exactly this, and they must not drift apart:
+ *   - `MockProvider.broadcast()` registers the tx it just accepted, so
+ *     `getTransaction()` can resolve it instead of throwing "not found".
+ *   - `RunarContract.deploy()` / `finalizeCall()` fall back to it when
+ *     `provider.getTransaction()` fails (a real node can 404 a transaction it
+ *     has accepted but not yet indexed).
+ *
+ * Both previously improvised their own shape, and the contract.ts one
+ * improvised an EMPTY one — `inputs: []`, `outputs: []` — indistinguishable
+ * from a confirmed transaction with no outputs, which is what made every
+ * post-broadcast `result.tx.outputs` assertion vacuous. Lives here because
+ * `providers/provider.ts` is a leaf both sides already import.
+ *
+ * `txid` is passed in rather than read off `tx`: the mock provider assigns
+ * synthetic txids, and the real deploy/call path uses the txid the provider
+ * returned from `broadcast()`.
+ */
+export function txToTransactionData(txid, tx) {
+    return {
+        txid,
+        version: tx.version,
+        inputs: tx.inputs.map((input) => ({
+            txid: input.sourceTXID ?? input.sourceTransaction?.id('hex') ?? '',
+            outputIndex: input.sourceOutputIndex,
+            script: input.unlockingScript?.toHex() ?? '',
+            sequence: input.sequence ?? 0xffffffff,
+        })),
+        outputs: tx.outputs.map((out) => ({
+            satoshis: out.satoshis ?? 0,
+            script: out.lockingScript.toHex(),
+        })),
+        locktime: tx.lockTime,
+        raw: tx.toHex(),
+    };
+}

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

@@ -0,0 +1,94 @@
+import type { Provider } from './provider.js';
+import type { Signer } from '../signers/signer.js';
+import type { TransactionData, UTXO } from '../types.js';
+import { Transaction, type WalletClient, type Broadcaster } from '@bsv/sdk';
+export interface WalletProviderOptions {
+    /** BRC-100 WalletClient instance. */
+    wallet: WalletClient;
+    /** Signer derived from the same wallet (e.g. WalletSigner). */
+    signer: Signer;
+    /** Wallet basket name for UTXO management (e.g. 'my-app'). */
+    basket: string;
+    /** Tag for funding UTXOs within the basket (default: 'funding'). */
+    fundingTag?: string;
+    /**
+     * ARC broadcast endpoint. Defaults to the MAINNET endpoint
+     * ('https://arc.gorillapool.io') and is therefore REQUIRED when `network` is
+     * anything other than 'mainnet' — see R-179.
+     */
+    arcUrl?: string;
+    /** Overlay service URL for tx submission and raw tx lookups (optional). */
+    overlayUrl?: string;
+    /** Overlay topic names for tx submission (optional, e.g. ['tm_myapp']). */
+    overlayTopics?: string[];
+    /** Network (default: 'mainnet'). */
+    network?: 'mainnet' | 'testnet';
+    /** Fee rate in sats/KB (default: 100, i.e. 0.1 sat/byte). */
+    feeRate?: number;
+    /**
+     * Injected `@bsv/sdk` Broadcaster (issue #107). When provided, `broadcast()`
+     * delegates to this instance instead of the hardcoded ARC URL, so the SDK
+     * and a downstream layer (e.g. wallet-toolbox) share ONE broadcaster/config
+     * — keeping parent and child txs at the same ARC deployment (avoids
+     * `SEEN_IN_ORPHAN_MEMPOOL`). Additive and non-breaking; omit for the default
+     * ARC path.
+     */
+    broadcaster?: Broadcaster;
+}
+export declare class WalletProvider implements Provider {
+    protected readonly wallet: WalletClient;
+    protected readonly signer: Signer;
+    protected readonly basket: string;
+    protected readonly fundingTag: string;
+    protected readonly arcUrl: string;
+    protected readonly overlayUrl: string | undefined;
+    protected readonly overlayTopics: string[] | undefined;
+    protected readonly _network: 'mainnet' | 'testnet';
+    protected readonly _feeRate: number;
+    protected readonly broadcaster: Broadcaster | undefined;
+    protected readonly txCache: Map<string, string>;
+    constructor(options: WalletProviderOptions);
+    /** The BRC-100 wallet client this provider wraps. */
+    get walletClient(): WalletClient;
+    /** The wallet basket used for UTXO management. */
+    get basketName(): string;
+    /** Cache a raw tx hex by its txid (for EF parent lookups). */
+    cacheTx(txid: string, rawHex: string): void;
+    /**
+     * 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.
+     */
+    protected fetchRawTx(txid: string): Promise<string>;
+    /**
+     * 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.
+     */
+    protected broadcastTx(tx: Transaction): Promise<string>;
+    /** Submit a transaction to the overlay for indexing (non-fatal).
+     * Protected so subclasses can adapt the submit request to their overlay. */
+    protected submitToOverlay(tx: Transaction): Promise<void>;
+    /**
+     * Get UTXOs from the wallet's basket.
+     * Returns only spendable P2PKH UTXOs locked to the signer's derived key.
+     */
+    getUtxos(_address: string): Promise<UTXO[]>;
+    getTransaction(txid: string): Promise<TransactionData>;
+    broadcast(tx: any): Promise<string>;
+    getContractUtxo(_scriptHash: string): Promise<UTXO | null>;
+    getNetwork(): 'mainnet' | 'testnet';
+    getRawTransaction(txid: string): Promise<string>;
+    getFeeRate(): Promise<number>;
+    /**
+     * 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.
+     */
+    ensureFunding(minSatoshis: number): Promise<void>;
+}