crypto-aio 0.0.2 → 0.1.0

package/dist/adapters/utxo/coinselect.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vsizeOf = exports.MAX_STANDARD_WEIGHT = void 0;
+exports.txWeight = txWeight;
+exports.selectCoins = selectCoins;
+/**
+ * Transaction size and coin selection (pure; `accumulative`, the default, and
+ * `all`). Sizes are exact weight units with worst-case signatures (a low-s DER ECDSA
+ * signature is at most 71 bytes plus the sighash byte; BIP340 is 64 bytes), so the signed
+ * transaction is never larger than estimated and its fee rate never lower. Change below the
+ * dust threshold is not created; its value goes to the fee (bounded by the absurd-fee guard).
+ */
+const error_1 = require("../../core/errors/error");
+const address_1 = require("./address");
+const fees_1 = require("./fees");
+/** Bitcoin Core's `MAX_STANDARD_TX_WEIGHT` (policy.h). */
+exports.MAX_STANDARD_WEIGHT = 400_000;
+/** Per input: non-witness bytes (outpoint, script, sequence) and witness bytes. */
+const INPUT_SIZE = {
+    // 32 + 4 + 1 (empty script) + 4; witness: count, 72-byte signature push, 33-byte key push.
+    p2wpkh: { base: 41, witness: 1 + 1 + 72 + 1 + 33 },
+    // scriptSig: 1 (length) + 1 (push) + 22-byte redeem script.
+    'p2sh-p2wpkh': { base: 32 + 4 + 1 + 23 + 4, witness: 1 + 1 + 72 + 1 + 33 },
+    // scriptSig: 1 (length) + 1 + 72 + 1 + 33.
+    p2pkh: { base: 32 + 4 + 1 + 107 + 4, witness: 0 },
+    // witness: count, 64-byte signature push (SIGHASH_DEFAULT).
+    p2tr: { base: 41, witness: 1 + 1 + 64 },
+};
+/** The weight of a transaction spending `inputs` inputs of one type to these outputs. */
+function txWeight(inputType, inputs, outputScriptLengths) {
+    const size = INPUT_SIZE[inputType];
+    let base = 4 +
+        (0, address_1.compactSize)(inputs) +
+        inputs * size.base +
+        (0, address_1.compactSize)(outputScriptLengths.length) +
+        4;
+    for (const length of outputScriptLengths)
+        base += 8 + (0, address_1.compactSize)(length) + length;
+    const witness = size.witness > 0 ? 2 + inputs * size.witness : 0;
+    return base * 4 + witness;
+}
+const vsizeOf = (weight) => Math.ceil(weight / 4);
+exports.vsizeOf = vsizeOf;
+const byValue = (a, b) => a.value === b.value ? (a.outpoint < b.outpoint ? -1 : 1) : a.value > b.value ? -1 : 1;
+function assertStandard(weight) {
+    if (weight > exports.MAX_STANDARD_WEIGHT) {
+        throw new error_1.ValidationError('INVALID_INTENT', 'the transaction would exceed the standard size (400,000 weight units)');
+    }
+}
+/** Picks inputs for the outputs at `rate`; deterministic for the same candidates. */
+function selectCoins(request) {
+    const { outputs, inputType, rate, changeScript } = request;
+    const required = request.required ?? [];
+    // An outpoint is spent once, even when a listing names it twice (a node would refuse the
+    // transaction as `bad-txns-inputs-duplicate`, which ends the Attempt as rejected).
+    const seen = new Set(required.map((input) => input.outpoint));
+    const pool = [];
+    for (const candidate of request.candidates) {
+        if (seen.has(candidate.outpoint))
+            continue;
+        seen.add(candidate.outpoint);
+        pool.push(candidate);
+    }
+    pool.sort(byValue);
+    const scripts = outputs.map((o) => o.script.length);
+    const target = outputs.reduce((sum, o) => sum + o.value, 0n);
+    const dust = (0, address_1.dustThreshold)(changeScript, request.dustRelayFee);
+    const marginal = (0, fees_1.feeAt)(rate, (0, exports.vsizeOf)(txWeight(inputType, 1, []) - txWeight(inputType, 0, [])));
+    const settle = (inputs) => {
+        const total = inputs.reduce((sum, i) => sum + i.value, 0n);
+        const bare = (0, exports.vsizeOf)(txWeight(inputType, inputs.length, scripts));
+        if (total < target + (0, fees_1.feeAt)(rate, bare))
+            return undefined;
+        const withChangeWeight = txWeight(inputType, inputs.length, [
+            ...scripts,
+            changeScript.length,
+        ]);
+        const withChange = (0, exports.vsizeOf)(withChangeWeight);
+        const change = total - target - (0, fees_1.feeAt)(rate, withChange);
+        if (change >= dust) {
+            assertStandard(withChangeWeight);
+            return {
+                ok: true,
+                inputs,
+                change,
+                fee: total - target - change,
+                vsize: withChange,
+            };
+        }
+        assertStandard(txWeight(inputType, inputs.length, scripts));
+        return { ok: true, inputs, change: 0n, fee: total - target, vsize: bare };
+    };
+    const everything = [...required, ...pool];
+    if (request.strategy === 'all') {
+        const done = everything.length > 0 ? settle(everything) : undefined;
+        if (done)
+            return done;
+    }
+    else {
+        const chosen = [...required];
+        const first = chosen.length > 0 ? settle(chosen) : undefined;
+        if (first)
+            return first;
+        for (const candidate of pool) {
+            if (candidate.value <= marginal)
+                continue; // costs more to spend than it is worth
+            chosen.push(candidate);
+            const done = settle(chosen);
+            if (done)
+                return done;
+        }
+        // `marginal` rounds one input's cost up on its own, but a step in the whole
+        // transaction's size can be a vbyte or a satoshi less: a skipped output may still pay
+        // its way, so everything is tried before a shortfall is reported.
+        if (chosen.length < everything.length) {
+            const done = settle(everything);
+            if (done)
+                return done;
+        }
+    }
+    const vsize = (0, exports.vsizeOf)(txWeight(inputType, everything.length, scripts));
+    const fee = (0, fees_1.feeAt)(rate, vsize);
+    return {
+        ok: false,
+        required: target + fee,
+        available: everything.reduce((sum, i) => sum + i.value, 0n),
+        fee,
+        vsize,
+    };
+}
+//# sourceMappingURL=coinselect.js.map

package/dist/adapters/utxo/coinselect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coinselect.js","sourceRoot":"","sources":["../../../src/adapters/utxo/coinselect.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Transaction size and coin selection (pure; `accumulative`, the default, and\n * `all`). Sizes are exact weight units with worst-case signatures (a low-s DER ECDSA\n * signature is at most 71 bytes plus the sighash byte; BIP340 is 64 bytes), so the signed\n * transaction is never larger than estimated and its fee rate never lower. Change below the\n * dust threshold is not created; its value goes to the fee (bounded by the absurd-fee guard).\n */\nimport { ValidationError } from '../../core/errors/error';\nimport { compactSize, dustThreshold } from './address';\nimport { feeAt } from './fees';\nimport type { CoinSelectionStrategy } from './network';\nimport type { UtxoAddressType } from './types';\n\n/** Bitcoin Core's `MAX_STANDARD_TX_WEIGHT` (policy.h). */\nexport const MAX_STANDARD_WEIGHT = 400_000;\n\n/** Per input: non-witness bytes (outpoint, script, sequence) and witness bytes. */\nconst INPUT_SIZE: Readonly<Record<UtxoAddressType, { base: number; witness: number }>> = {\n  // 32 + 4 + 1 (empty script) + 4; witness: count, 72-byte signature push, 33-byte key push.\n  p2wpkh: { base: 41, witness: 1 + 1 + 72 + 1 + 33 },\n  // scriptSig: 1 (length) + 1 (push) + 22-byte redeem script.\n  'p2sh-p2wpkh': { base: 32 + 4 + 1 + 23 + 4, witness: 1 + 1 + 72 + 1 + 33 },\n  // scriptSig: 1 (length) + 1 + 72 + 1 + 33.\n  p2pkh: { base: 32 + 4 + 1 + 107 + 4, witness: 0 },\n  // witness: count, 64-byte signature push (SIGHASH_DEFAULT).\n  p2tr: { base: 41, witness: 1 + 1 + 64 },\n};\n\n/** The weight of a transaction spending `inputs` inputs of one type to these outputs. */\nexport function txWeight(\n  inputType: UtxoAddressType,\n  inputs: number,\n  outputScriptLengths: readonly number[],\n): number {\n  const size = INPUT_SIZE[inputType];\n  let base =\n    4 +\n    compactSize(inputs) +\n    inputs * size.base +\n    compactSize(outputScriptLengths.length) +\n    4;\n  for (const length of outputScriptLengths) base += 8 + compactSize(length) + length;\n  const witness = size.witness > 0 ? 2 + inputs * size.witness : 0;\n  return base * 4 + witness;\n}\n\nexport const vsizeOf = (weight: number): number => Math.ceil(weight / 4);\n\nexport interface Spendable {\n  /** `txid:vout`. */\n  readonly outpoint: string;\n  readonly txid: string;\n  readonly vout: number;\n  readonly value: bigint;\n}\n\nexport interface PlannedOutput {\n  readonly script: Uint8Array;\n  readonly value: bigint;\n}\n\nexport interface SelectionRequest {\n  /** Eligible outputs of the wallet (already filtered for reservations and confirmations). */\n  readonly candidates: readonly Spendable[];\n  /** Inputs that must be spent (an RBF replacement keeps every earlier input). */\n  readonly required?: readonly Spendable[];\n  readonly outputs: readonly PlannedOutput[];\n  readonly changeScript: Uint8Array;\n  readonly inputType: UtxoAddressType;\n  /** sat/kvB. */\n  readonly rate: bigint;\n  readonly dustRelayFee: bigint;\n  readonly strategy: CoinSelectionStrategy;\n}\n\nexport interface Selection {\n  readonly ok: true;\n  readonly inputs: readonly Spendable[];\n  readonly change: bigint;\n  readonly fee: bigint;\n  readonly vsize: number;\n}\n\nexport interface Shortfall {\n  readonly ok: false;\n  readonly required: bigint;\n  readonly available: bigint;\n  /** The fee of spending every eligible output (for an estimate that cannot be met). */\n  readonly fee: bigint;\n  readonly vsize: number;\n}\n\nconst byValue = (a: Spendable, b: Spendable): number =>\n  a.value === b.value ? (a.outpoint < b.outpoint ? -1 : 1) : a.value > b.value ? -1 : 1;\n\nfunction assertStandard(weight: number): void {\n  if (weight > MAX_STANDARD_WEIGHT) {\n    throw new ValidationError(\n      'INVALID_INTENT',\n      'the transaction would exceed the standard size (400,000 weight units)',\n    );\n  }\n}\n\n/** Picks inputs for the outputs at `rate`; deterministic for the same candidates. */\nexport function selectCoins(request: SelectionRequest): Selection | Shortfall {\n  const { outputs, inputType, rate, changeScript } = request;\n  const required = request.required ?? [];\n  // An outpoint is spent once, even when a listing names it twice (a node would refuse the\n  // transaction as `bad-txns-inputs-duplicate`, which ends the Attempt as rejected).\n  const seen = new Set(required.map((input) => input.outpoint));\n  const pool: Spendable[] = [];\n  for (const candidate of request.candidates) {\n    if (seen.has(candidate.outpoint)) continue;\n    seen.add(candidate.outpoint);\n    pool.push(candidate);\n  }\n  pool.sort(byValue);\n  const scripts = outputs.map((o) => o.script.length);\n  const target = outputs.reduce((sum, o) => sum + o.value, 0n);\n  const dust = dustThreshold(changeScript, request.dustRelayFee);\n  const marginal = feeAt(\n    rate,\n    vsizeOf(txWeight(inputType, 1, []) - txWeight(inputType, 0, [])),\n  );\n\n  const settle = (inputs: readonly Spendable[]): Selection | undefined => {\n    const total = inputs.reduce((sum, i) => sum + i.value, 0n);\n    const bare = vsizeOf(txWeight(inputType, inputs.length, scripts));\n    if (total < target + feeAt(rate, bare)) return undefined;\n    const withChangeWeight = txWeight(inputType, inputs.length, [\n      ...scripts,\n      changeScript.length,\n    ]);\n    const withChange = vsizeOf(withChangeWeight);\n    const change = total - target - feeAt(rate, withChange);\n    if (change >= dust) {\n      assertStandard(withChangeWeight);\n      return {\n        ok: true,\n        inputs,\n        change,\n        fee: total - target - change,\n        vsize: withChange,\n      };\n    }\n    assertStandard(txWeight(inputType, inputs.length, scripts));\n    return { ok: true, inputs, change: 0n, fee: total - target, vsize: bare };\n  };\n\n  const everything = [...required, ...pool];\n  if (request.strategy === 'all') {\n    const done = everything.length > 0 ? settle(everything) : undefined;\n    if (done) return done;\n  } else {\n    const chosen: Spendable[] = [...required];\n    const first = chosen.length > 0 ? settle(chosen) : undefined;\n    if (first) return first;\n    for (const candidate of pool) {\n      if (candidate.value <= marginal) continue; // costs more to spend than it is worth\n      chosen.push(candidate);\n      const done = settle(chosen);\n      if (done) return done;\n    }\n    // `marginal` rounds one input's cost up on its own, but a step in the whole\n    // transaction's size can be a vbyte or a satoshi less: a skipped output may still pay\n    // its way, so everything is tried before a shortfall is reported.\n    if (chosen.length < everything.length) {\n      const done = settle(everything);\n      if (done) return done;\n    }\n  }\n  const vsize = vsizeOf(txWeight(inputType, everything.length, scripts));\n  const fee = feeAt(rate, vsize);\n  return {\n    ok: false,\n    required: target + fee,\n    available: everything.reduce((sum, i) => sum + i.value, 0n),\n    fee,\n    vsize,\n  };\n}\n"]}

package/dist/adapters/utxo/context.d.ts

@@ -0,0 +1,57 @@
+/**
+ * What every UTXO port is built from, the transport tags of the `ChainDriver` contract
+ * table, and the wallet options every builder call parses.
+ */
+import type { WalletOptions } from '../../core/driver/types';
+import type { AssetRef } from '../../core/model/asset';
+import type { Logger } from '../../core/events/logger';
+import type { ChainInfo, NetworkInfo } from '../../core/model/chain';
+import { type DecodedAddress } from './address';
+import type { EsploraClient } from './esplora';
+import type { UtxoNetworkConfig } from './network';
+import type { UtxoAddressType, UtxoCallTags } from './types';
+export interface UtxoContext {
+    readonly esplora: EsploraClient;
+    readonly chain: ChainInfo;
+    readonly network: NetworkInfo;
+    readonly config: UtxoNetworkConfig;
+    readonly log: Logger;
+}
+export declare const READ: UtxoCallTags;
+export declare const MONITOR: UtxoCallTags;
+export declare const PROOF: UtxoCallTags;
+export declare const withSignal: (tags: UtxoCallTags, signal?: AbortSignal) => UtxoCallTags;
+/**
+ * Runs `work` on each item, at most `limit` at a time. After a failure the
+ * other runners stop at their next step, and the first failure is thrown.
+ */
+export declare function forEachBounded<T>(items: readonly T[], limit: number, work: (item: T) => Promise<void>): Promise<void>;
+/**
+ * On a proof path only a definitive negative proof may answer "no"
+ * (for Bitcoin: a quorum-attested final spend by another transaction). Every other RPC or
+ * HTTP error decides nothing: a non-retryable provider error, such as a CDN or proxy 400,
+ * 410 or 422 (the transport's `RPC_ERROR`, ambiguous or not) or a 401/403
+ * (`PROVIDER_MISCONFIGURED`), becomes a retryable `PROVIDER_UNAVAILABLE` here, so the monitor
+ * never rethrows it. Retryable provider errors already decide nothing and pass unchanged, as
+ * do Esplora's own 404s, which the client maps to `null` first. The cost is liveness only.
+ */
+export declare function proofRead<T>(read: () => Promise<T>): Promise<T>;
+export declare const ADDRESS_TYPES: readonly UtxoAddressType[];
+export interface ParsedWalletOptions {
+    readonly addressType: UtxoAddressType;
+    readonly changeAddress?: DecodedAddress;
+    /** The explicit opt-out for a change address the wallet's key does not derive. */
+    readonly allowExternalChangeAddress: boolean;
+}
+/**
+ * `WalletConfig.utxo`, validated (`CONFIG_INVALID`): the address type, the change address
+ * and its opt-out. Whether the wallet derives the change address is checked where the
+ * wallet's keys are known (`changeAddressOf`, `spend.ts`).
+ */
+export declare function parseWalletOptions(wallet: WalletOptions | undefined, config: UtxoNetworkConfig): ParsedWalletOptions;
+export declare function assertNative(asset: AssetRef): void;
+/** Splits an `inputs` ordering entry (`txid:vout`); malformed data decides nothing. */
+export declare function parseOutpoint(outpoint: string): {
+    txid: string;
+    vout: number;
+};

package/dist/adapters/utxo/context.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADDRESS_TYPES = exports.withSignal = exports.PROOF = exports.MONITOR = exports.READ = void 0;
+exports.forEachBounded = forEachBounded;
+exports.proofRead = proofRead;
+exports.parseWalletOptions = parseWalletOptions;
+exports.assertNative = assertNative;
+exports.parseOutpoint = parseOutpoint;
+const error_1 = require("../../core/errors/error");
+const names_1 = require("../../core/util/names");
+const address_1 = require("./address");
+exports.READ = { purpose: 'read', retry: 'safe' };
+exports.MONITOR = { purpose: 'monitor', retry: 'safe' };
+exports.PROOF = { purpose: 'proof', retry: 'safe', quorum: 'proof' };
+const withSignal = (tags, signal) => signal ? { ...tags, signal } : tags;
+exports.withSignal = withSignal;
+/**
+ * Runs `work` on each item, at most `limit` at a time. After a failure the
+ * other runners stop at their next step, and the first failure is thrown.
+ */
+async function forEachBounded(items, limit, work) {
+    let next = 0;
+    let failed = false;
+    const runner = async () => {
+        while (!failed && next < items.length) {
+            const item = items[next++];
+            try {
+                await work(item);
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, runner));
+}
+/**
+ * On a proof path only a definitive negative proof may answer "no"
+ * (for Bitcoin: a quorum-attested final spend by another transaction). Every other RPC or
+ * HTTP error decides nothing: a non-retryable provider error, such as a CDN or proxy 400,
+ * 410 or 422 (the transport's `RPC_ERROR`, ambiguous or not) or a 401/403
+ * (`PROVIDER_MISCONFIGURED`), becomes a retryable `PROVIDER_UNAVAILABLE` here, so the monitor
+ * never rethrows it. Retryable provider errors already decide nothing and pass unchanged, as
+ * do Esplora's own 404s, which the client maps to `null` first. The cost is liveness only.
+ */
+async function proofRead(read) {
+    try {
+        return await read();
+    }
+    catch (error) {
+        if ((0, error_1.isCryptoAioError)(error) && error.category === 'provider' && !error.retryable) {
+            throw new error_1.ProviderError('PROVIDER_UNAVAILABLE', 'the proof read failed on this endpoint; nothing is decided', { cause: error });
+        }
+        throw error;
+    }
+}
+exports.ADDRESS_TYPES = [
+    'p2wpkh',
+    'p2sh-p2wpkh',
+    'p2pkh',
+    'p2tr',
+];
+const WALLET_OPTION_KEYS = ['addressType', 'changeAddress', 'allowExternalChangeAddress'];
+/**
+ * `WalletConfig.utxo`, validated (`CONFIG_INVALID`): the address type, the change address
+ * and its opt-out. Whether the wallet derives the change address is checked where the
+ * wallet's keys are known (`changeAddressOf`, `spend.ts`).
+ */
+function parseWalletOptions(wallet, config) {
+    const raw = wallet?.utxo;
+    if (raw === undefined)
+        return { addressType: 'p2wpkh', allowExternalChangeAddress: false };
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new error_1.ConfigError('CONFIG_INVALID', 'wallet.utxo must be an object');
+    }
+    const options = raw;
+    // The accepted names, never the caller's key (it may be a pasted secret).
+    if (Object.keys(options).some((key) => !WALLET_OPTION_KEYS.includes(key))) {
+        throw new error_1.ConfigError('CONFIG_INVALID', `wallet.utxo has an ${(0, names_1.unknownName)('option', WALLET_OPTION_KEYS)}`);
+    }
+    const type = options.addressType ?? 'p2wpkh';
+    if (!exports.ADDRESS_TYPES.includes(type)) {
+        throw new error_1.ConfigError('CONFIG_INVALID', `wallet.utxo.addressType must be one of ${exports.ADDRESS_TYPES.join(', ')}`);
+    }
+    let changeAddress;
+    if (options.changeAddress !== undefined) {
+        try {
+            changeAddress = (0, address_1.decodeAddress)(options.changeAddress, config.address);
+        }
+        catch {
+            throw new error_1.ConfigError('CONFIG_INVALID', 'wallet.utxo.changeAddress is not a valid address on this network');
+        }
+    }
+    const external = options.allowExternalChangeAddress ?? false;
+    if (typeof external !== 'boolean') {
+        throw new error_1.ConfigError('CONFIG_INVALID', 'wallet.utxo.allowExternalChangeAddress must be a boolean');
+    }
+    return {
+        addressType: type,
+        ...(changeAddress ? { changeAddress } : {}),
+        allowExternalChangeAddress: external,
+    };
+}
+function assertNative(asset) {
+    if (asset !== 'native') {
+        throw new error_1.UnsupportedCapabilityError('UNSUPPORTED_CAPABILITY', 'Bitcoin has no tokens; only the native asset can be sent');
+    }
+}
+/** Splits an `inputs` ordering entry (`txid:vout`); malformed data decides nothing. */
+function parseOutpoint(outpoint) {
+    const match = /^([0-9a-f]{64}):(0|[1-9][0-9]{0,9})$/.exec(outpoint);
+    if (!match || Number(match[2]) > 0xffffffff) {
+        throw new error_1.ProviderError('PROVIDER_UNAVAILABLE', 'malformed outpoint in the ordering');
+    }
+    return { txid: match[1], vout: Number(match[2]) };
+}
+//# sourceMappingURL=context.js.map

package/dist/adapters/utxo/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/adapters/utxo/context.ts"],"names":[],"mappings":";;;AAuCA,wCAmBC;AAWD,8BAaC;AAuBD,gDAgDC;AAED,oCAOC;AAGD,sCAMC;AAtKD,mDAKiC;AAEjC,iDAAoD;AAGpD,uCAA+D;AAalD,QAAA,IAAI,GAAiB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AACxD,QAAA,OAAO,GAAiB,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC9D,QAAA,KAAK,GAAiB,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAEjF,MAAM,UAAU,GAAG,CAAC,IAAkB,EAAE,MAAoB,EAAgB,EAAE,CACnF,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AADzB,QAAA,UAAU,cACe;AAEtC;;;GAGG;AACI,KAAK,UAAU,cAAc,CAClC,KAAmB,EACnB,KAAa,EACb,IAAgC;IAEhC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,MAAM,GAAG,KAAK,IAAmB,EAAE;QACvC,OAAO,CAAC,MAAM,IAAI,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAM,CAAC;YAChC,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,GAAG,IAAI,CAAC;gBACd,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IACF,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;AACnF,CAAC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,SAAS,CAAI,IAAsB;IACvD,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,IAAA,wBAAgB,EAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,KAAK,UAAU,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;YACjF,MAAM,IAAI,qBAAa,CACrB,sBAAsB,EACtB,4DAA4D,EAC5D,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAEY,QAAA,aAAa,GAA+B;IACvD,QAAQ;IACR,aAAa;IACb,OAAO;IACP,MAAM;CACP,CAAC;AASF,MAAM,kBAAkB,GAAG,CAAC,aAAa,EAAE,eAAe,EAAE,4BAA4B,CAAC,CAAC;AAE1F;;;;GAIG;AACH,SAAgB,kBAAkB,CAChC,MAAiC,EACjC,MAAyB;IAEzB,MAAM,GAAG,GAAG,MAAM,EAAE,IAAI,CAAC;IACzB,IAAI,GAAG,KAAK,SAAS;QACnB,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,0BAA0B,EAAE,KAAK,EAAE,CAAC;IACtE,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,mBAAW,CAAC,gBAAgB,EAAE,+BAA+B,CAAC,CAAC;IAC3E,CAAC;IACD,MAAM,OAAO,GAAG,GAAwC,CAAC;IACzD,0EAA0E;IAC1E,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,kBAAkB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QAC1E,MAAM,IAAI,mBAAW,CACnB,gBAAgB,EAChB,sBAAsB,IAAA,mBAAW,EAAC,QAAQ,EAAE,kBAAkB,CAAC,EAAE,CAClE,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,IAAI,QAAQ,CAAC;IAC7C,IAAI,CAAC,qBAAa,CAAC,QAAQ,CAAC,IAAuB,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,mBAAW,CACnB,gBAAgB,EAChB,0CAA0C,qBAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACrE,CAAC;IACJ,CAAC;IACD,IAAI,aAAyC,CAAC;IAC9C,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACxC,IAAI,CAAC;YACH,aAAa,GAAG,IAAA,uBAAa,EAAC,OAAO,CAAC,aAAuB,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACjF,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,mBAAW,CACnB,gBAAgB,EAChB,kEAAkE,CACnE,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,0BAA0B,IAAI,KAAK,CAAC;IAC7D,IAAI,OAAO,QAAQ,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,mBAAW,CACnB,gBAAgB,EAChB,0DAA0D,CAC3D,CAAC;IACJ,CAAC;IACD,OAAO;QACL,WAAW,EAAE,IAAuB;QACpC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,0BAA0B,EAAE,QAAQ;KACrC,CAAC;AACJ,CAAC;AAED,SAAgB,YAAY,CAAC,KAAe;IAC1C,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvB,MAAM,IAAI,kCAA0B,CAClC,wBAAwB,EACxB,0DAA0D,CAC3D,CAAC;IACJ,CAAC;AACH,CAAC;AAED,uFAAuF;AACvF,SAAgB,aAAa,CAAC,QAAgB;IAC5C,MAAM,KAAK,GAAG,sCAAsC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACpE,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,EAAE,CAAC;QAC5C,MAAM,IAAI,qBAAa,CAAC,sBAAsB,EAAE,oCAAoC,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAW,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9D,CAAC","sourcesContent":["/**\n * What every UTXO port is built from, the transport tags of the `ChainDriver` contract\n * table, and the wallet options every builder call parses.\n */\nimport type { WalletOptions } from '../../core/driver/types';\nimport {\n  ConfigError,\n  ProviderError,\n  UnsupportedCapabilityError,\n  isCryptoAioError,\n} from '../../core/errors/error';\nimport type { AssetRef } from '../../core/model/asset';\nimport { unknownName } from '../../core/util/names';\nimport type { Logger } from '../../core/events/logger';\nimport type { ChainInfo, NetworkInfo } from '../../core/model/chain';\nimport { decodeAddress, type DecodedAddress } from './address';\nimport type { EsploraClient } from './esplora';\nimport type { UtxoNetworkConfig } from './network';\nimport type { UtxoAddressType, UtxoCallTags } from './types';\n\nexport interface UtxoContext {\n  readonly esplora: EsploraClient;\n  readonly chain: ChainInfo;\n  readonly network: NetworkInfo;\n  readonly config: UtxoNetworkConfig;\n  readonly log: Logger;\n}\n\nexport const READ: UtxoCallTags = { purpose: 'read', retry: 'safe' };\nexport const MONITOR: UtxoCallTags = { purpose: 'monitor', retry: 'safe' };\nexport const PROOF: UtxoCallTags = { purpose: 'proof', retry: 'safe', quorum: 'proof' };\n\nexport const withSignal = (tags: UtxoCallTags, signal?: AbortSignal): UtxoCallTags =>\n  signal ? { ...tags, signal } : tags;\n\n/**\n * Runs `work` on each item, at most `limit` at a time. After a failure the\n * other runners stop at their next step, and the first failure is thrown.\n */\nexport async function forEachBounded<T>(\n  items: readonly T[],\n  limit: number,\n  work: (item: T) => Promise<void>,\n): Promise<void> {\n  let next = 0;\n  let failed = false;\n  const runner = async (): Promise<void> => {\n    while (!failed && next < items.length) {\n      const item = items[next++] as T;\n      try {\n        await work(item);\n      } catch (error) {\n        failed = true;\n        throw error;\n      }\n    }\n  };\n  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, runner));\n}\n\n/**\n * On a proof path only a definitive negative proof may answer \"no\"\n * (for Bitcoin: a quorum-attested final spend by another transaction). Every other RPC or\n * HTTP error decides nothing: a non-retryable provider error, such as a CDN or proxy 400,\n * 410 or 422 (the transport's `RPC_ERROR`, ambiguous or not) or a 401/403\n * (`PROVIDER_MISCONFIGURED`), becomes a retryable `PROVIDER_UNAVAILABLE` here, so the monitor\n * never rethrows it. Retryable provider errors already decide nothing and pass unchanged, as\n * do Esplora's own 404s, which the client maps to `null` first. The cost is liveness only.\n */\nexport async function proofRead<T>(read: () => Promise<T>): Promise<T> {\n  try {\n    return await read();\n  } catch (error) {\n    if (isCryptoAioError(error) && error.category === 'provider' && !error.retryable) {\n      throw new ProviderError(\n        'PROVIDER_UNAVAILABLE',\n        'the proof read failed on this endpoint; nothing is decided',\n        { cause: error },\n      );\n    }\n    throw error;\n  }\n}\n\nexport const ADDRESS_TYPES: readonly UtxoAddressType[] = [\n  'p2wpkh',\n  'p2sh-p2wpkh',\n  'p2pkh',\n  'p2tr',\n];\n\nexport interface ParsedWalletOptions {\n  readonly addressType: UtxoAddressType;\n  readonly changeAddress?: DecodedAddress;\n  /** The explicit opt-out for a change address the wallet's key does not derive. */\n  readonly allowExternalChangeAddress: boolean;\n}\n\nconst WALLET_OPTION_KEYS = ['addressType', 'changeAddress', 'allowExternalChangeAddress'];\n\n/**\n * `WalletConfig.utxo`, validated (`CONFIG_INVALID`): the address type, the change address\n * and its opt-out. Whether the wallet derives the change address is checked where the\n * wallet's keys are known (`changeAddressOf`, `spend.ts`).\n */\nexport function parseWalletOptions(\n  wallet: WalletOptions | undefined,\n  config: UtxoNetworkConfig,\n): ParsedWalletOptions {\n  const raw = wallet?.utxo;\n  if (raw === undefined)\n    return { addressType: 'p2wpkh', allowExternalChangeAddress: false };\n  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {\n    throw new ConfigError('CONFIG_INVALID', 'wallet.utxo must be an object');\n  }\n  const options = raw as Readonly<Record<string, unknown>>;\n  // The accepted names, never the caller's key (it may be a pasted secret).\n  if (Object.keys(options).some((key) => !WALLET_OPTION_KEYS.includes(key))) {\n    throw new ConfigError(\n      'CONFIG_INVALID',\n      `wallet.utxo has an ${unknownName('option', WALLET_OPTION_KEYS)}`,\n    );\n  }\n  const type = options.addressType ?? 'p2wpkh';\n  if (!ADDRESS_TYPES.includes(type as UtxoAddressType)) {\n    throw new ConfigError(\n      'CONFIG_INVALID',\n      `wallet.utxo.addressType must be one of ${ADDRESS_TYPES.join(', ')}`,\n    );\n  }\n  let changeAddress: DecodedAddress | undefined;\n  if (options.changeAddress !== undefined) {\n    try {\n      changeAddress = decodeAddress(options.changeAddress as string, config.address);\n    } catch {\n      throw new ConfigError(\n        'CONFIG_INVALID',\n        'wallet.utxo.changeAddress is not a valid address on this network',\n      );\n    }\n  }\n  const external = options.allowExternalChangeAddress ?? false;\n  if (typeof external !== 'boolean') {\n    throw new ConfigError(\n      'CONFIG_INVALID',\n      'wallet.utxo.allowExternalChangeAddress must be a boolean',\n    );\n  }\n  return {\n    addressType: type as UtxoAddressType,\n    ...(changeAddress ? { changeAddress } : {}),\n    allowExternalChangeAddress: external,\n  };\n}\n\nexport function assertNative(asset: AssetRef): void {\n  if (asset !== 'native') {\n    throw new UnsupportedCapabilityError(\n      'UNSUPPORTED_CAPABILITY',\n      'Bitcoin has no tokens; only the native asset can be sent',\n    );\n  }\n}\n\n/** Splits an `inputs` ordering entry (`txid:vout`); malformed data decides nothing. */\nexport function parseOutpoint(outpoint: string): { txid: string; vout: number } {\n  const match = /^([0-9a-f]{64}):(0|[1-9][0-9]{0,9})$/.exec(outpoint);\n  if (!match || Number(match[2]) > 0xffffffff) {\n    throw new ProviderError('PROVIDER_UNAVAILABLE', 'malformed outpoint in the ordering');\n  }\n  return { txid: match[1] as string, vout: Number(match[2]) };\n}\n"]}

package/dist/adapters/utxo/decode.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Esplora transactions as `DriverTransaction`s (SDK-free). Every output whose script has an
+ * address is a `vout:<n>` transfer from the input addresses; an output this
+ * library cannot name that carries value (a future witness version, a bare script) makes the
+ * decoding `partial`. Addresses are derived from the scripts, never taken from the server's
+ * `scriptpubkey_address`, which a server could leave out (making a deposit `partial`) or
+ * change (crediting another address). A Bitcoin transaction that is in a block has executed:
+ * `success` is `true` (general decoding reports the chain as it is).
+ */
+import type { DriverTransaction, DriverTxObservation } from '../../core/driver/types';
+import { type AddressParams } from './address';
+import type { EsploraStatus, EsploraTx } from './types';
+export declare function observationOf(txid: string, status: EsploraStatus): DriverTxObservation;
+export declare function decodeTransaction(tx: EsploraTx, params: AddressParams): DriverTransaction;

package/dist/adapters/utxo/decode.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observationOf = observationOf;
+exports.decodeTransaction = decodeTransaction;
+const bytes_1 = require("../../core/util/bytes");
+const address_1 = require("./address");
+function observationOf(txid, status) {
+    return status.confirmed
+        ? {
+            seen: 'block',
+            txHash: txid,
+            blockHeight: status.blockHeight,
+            blockHash: status.blockHash,
+            success: true,
+        }
+        : { seen: 'mempool', txHash: txid };
+}
+/** The canonical address an output's script pays on this network, or `undefined`. */
+function addressOf(output, params) {
+    return (0, address_1.addressFromScript)((0, bytes_1.fromHex)(output.script), params)?.canonical;
+}
+function decodeTransaction(tx, params) {
+    const coinbase = tx.vin.some((input) => input.coinbase);
+    const senders = tx.vin.map((input) => input.prevout ? addressOf(input.prevout, params) : undefined);
+    const recipients = tx.vout.map((output) => addressOf(output, params));
+    const from = [
+        ...new Set(senders.filter((address) => address !== undefined)),
+    ];
+    const transfers = [];
+    let partial = false;
+    tx.vout.forEach((output, n) => {
+        const to = recipients[n];
+        if (to === undefined) {
+            if (output.value > 0n)
+                partial = true;
+            return;
+        }
+        transfers.push({
+            locator: `vout:${n}`,
+            from,
+            to,
+            asset: 'native',
+            amount: output.value,
+            source: 'native',
+        });
+    });
+    return {
+        id: tx.txid,
+        observation: observationOf(tx.txid, tx.status),
+        ...(coinbase ? {} : { fee: [{ asset: 'native', amount: tx.fee }] }),
+        transfers,
+        decoding: partial ? 'partial' : 'complete',
+        ...(tx.status.blockTime !== undefined ? { timestamp: tx.status.blockTime } : {}),
+        details: {
+            version: tx.version,
+            locktime: tx.locktime,
+            weight: tx.weight,
+            vin: tx.vin.map((input, n) => {
+                const address = senders[n];
+                return {
+                    txid: input.txid,
+                    vout: input.vout,
+                    coinbase: input.coinbase,
+                    sequence: input.sequence,
+                    ...(input.prevout
+                        ? {
+                            value: input.prevout.value,
+                            ...(address !== undefined ? { address } : {}),
+                        }
+                        : {}),
+                };
+            }),
+            vout: tx.vout.map((output, n) => {
+                const address = recipients[n];
+                return {
+                    n,
+                    value: output.value,
+                    type: output.type,
+                    ...(address !== undefined ? { address } : {}),
+                };
+            }),
+        },
+    };
+}
+//# sourceMappingURL=decode.js.map

package/dist/adapters/utxo/decode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.js","sourceRoot":"","sources":["../../../src/adapters/utxo/decode.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Esplora transactions as `DriverTransaction`s (SDK-free). Every output whose script has an\n * address is a `vout:<n>` transfer from the input addresses; an output this\n * library cannot name that carries value (a future witness version, a bare script) makes the\n * decoding `partial`. Addresses are derived from the scripts, never taken from the server's\n * `scriptpubkey_address`, which a server could leave out (making a deposit `partial`) or\n * change (crediting another address). A Bitcoin transaction that is in a block has executed:\n * `success` is `true` (general decoding reports the chain as it is).\n */\nimport type {\n  DriverTransaction,\n  DriverTransfer,\n  DriverTxObservation,\n} from '../../core/driver/types';\nimport { fromHex } from '../../core/util/bytes';\nimport { addressFromScript, type AddressParams } from './address';\nimport type { EsploraOutput, EsploraStatus, EsploraTx } from './types';\n\nexport function observationOf(txid: string, status: EsploraStatus): DriverTxObservation {\n  return status.confirmed\n    ? {\n        seen: 'block',\n        txHash: txid,\n        blockHeight: status.blockHeight as bigint,\n        blockHash: status.blockHash as string,\n        success: true,\n      }\n    : { seen: 'mempool', txHash: txid };\n}\n\n/** The canonical address an output's script pays on this network, or `undefined`. */\nfunction addressOf(output: EsploraOutput, params: AddressParams): string | undefined {\n  return addressFromScript(fromHex(output.script), params)?.canonical;\n}\n\nexport function decodeTransaction(\n  tx: EsploraTx,\n  params: AddressParams,\n): DriverTransaction {\n  const coinbase = tx.vin.some((input) => input.coinbase);\n  const senders = tx.vin.map((input) =>\n    input.prevout ? addressOf(input.prevout, params) : undefined,\n  );\n  const recipients = tx.vout.map((output) => addressOf(output, params));\n  const from = [\n    ...new Set(senders.filter((address): address is string => address !== undefined)),\n  ];\n  const transfers: DriverTransfer[] = [];\n  let partial = false;\n  tx.vout.forEach((output, n) => {\n    const to = recipients[n];\n    if (to === undefined) {\n      if (output.value > 0n) partial = true;\n      return;\n    }\n    transfers.push({\n      locator: `vout:${n}`,\n      from,\n      to,\n      asset: 'native',\n      amount: output.value,\n      source: 'native',\n    });\n  });\n  return {\n    id: tx.txid,\n    observation: observationOf(tx.txid, tx.status),\n    ...(coinbase ? {} : { fee: [{ asset: 'native' as const, amount: tx.fee }] }),\n    transfers,\n    decoding: partial ? 'partial' : 'complete',\n    ...(tx.status.blockTime !== undefined ? { timestamp: tx.status.blockTime } : {}),\n    details: {\n      version: tx.version,\n      locktime: tx.locktime,\n      weight: tx.weight,\n      vin: tx.vin.map((input, n) => {\n        const address = senders[n];\n        return {\n          txid: input.txid,\n          vout: input.vout,\n          coinbase: input.coinbase,\n          sequence: input.sequence,\n          ...(input.prevout\n            ? {\n                value: input.prevout.value,\n                ...(address !== undefined ? { address } : {}),\n              }\n            : {}),\n        };\n      }),\n      vout: tx.vout.map((output, n) => {\n        const address = recipients[n];\n        return {\n          n,\n          value: output.value,\n          type: output.type,\n          ...(address !== undefined ? { address } : {}),\n        };\n      }),\n    },\n  };\n}\n"]}

package/dist/adapters/utxo/driver.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The UTXO driver factory: validated network config, endpoint probes on both transports,
+ * and the ports. Loaded only by the manifest's `load()`, with bitcoinjs-lib.
+ */
+import type { DriverFactory } from '../../core/driver/types';
+import { networkOf } from './codec';
+import { bitcoin } from './sdk';
+export interface UtxoNativeClient {
+    /** The bitcoinjs-lib module, with this library's `@noble/curves` ECC backend installed. */
+    readonly bitcoin: typeof bitcoin;
+    /** A fresh copy of this network's bitcoinjs parameters. */
+    readonly network: ReturnType<typeof networkOf>;
+    /** A GET to the handle's Esplora (`rpc`) endpoints, through the policy-wrapped transport. */
+    esplora<T = unknown>(path: string, responseType?: 'json' | 'text'): Promise<T>;
+}
+export declare const utxoDriverFactory: DriverFactory;

package/dist/adapters/utxo/driver.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.utxoDriverFactory = void 0;
+const error_1 = require("../../core/errors/error");
+const builder_1 = require("./builder");
+const codec_1 = require("./codec");
+const context_1 = require("./context");
+const esplora_1 = require("./esplora");
+const network_1 = require("./network");
+const proofs_1 = require("./proofs");
+const reader_1 = require("./reader");
+const sdk_1 = require("./sdk");
+const preview_1 = require("./preview");
+const spend_1 = require("./spend");
+function probes(expectedIdentity) {
+    const text = (call, path, route) => call.http({ method: 'GET', path, route, responseType: 'text' });
+    return {
+        identity: async (call) => (0, esplora_1.parseHash)(await text(call, '/block-height/0', '/block-height/:height')),
+        expectedIdentity,
+        height: async (call) => (0, esplora_1.parseHeight)(await text(call, '/blocks/tip/height', '/blocks/tip/height')),
+    };
+}
+exports.utxoDriverFactory = {
+    async create(ctx) {
+        const config = (0, network_1.utxoNetworkConfig)(ctx.chain, ctx.network, ctx.options);
+        if (!ctx.indexer) {
+            throw new error_1.ConfigError('CONFIG_INVALID', 'the UTXO driver requires an indexer provider');
+        }
+        // Both transports, before any traffic: the genesis-hash probe keeps an endpoint of
+        // another network out of the `rpc` reads and the `indexer` reads alike.
+        ctx.transport.setProbes(probes(config.genesisHash));
+        ctx.indexer.setProbes(probes(config.genesisHash));
+        const esplora = new esplora_1.EsploraClient(ctx.transport, ctx.indexer);
+        const utxo = {
+            esplora,
+            chain: ctx.chain,
+            network: ctx.network,
+            config,
+            log: ctx.log,
+        };
+        const network = (0, codec_1.networkOf)(config.address);
+        const builder = (0, builder_1.utxoBuilder)(utxo, network);
+        return {
+            ordering: 'inputs',
+            capabilities: config.capabilities,
+            address: (0, reader_1.addressCodec)(utxo),
+            reader: (0, reader_1.chainReader)(utxo),
+            builder,
+            broadcaster: (0, builder_1.utxoBroadcaster)(utxo),
+            proofs: (0, proofs_1.proofSource)(utxo),
+            replacement: (0, builder_1.utxoReplacement)(utxo, network),
+            blocks: (0, proofs_1.blockSource)(utxo),
+            history: (0, reader_1.addressHistory)(utxo),
+            ext: {
+                utxo: {
+                    listUnspent: (address) => (0, reader_1.listUnspent)(utxo, address),
+                    coinSelection: (request) => (0, preview_1.coinSelectionPreview)(utxo, request),
+                },
+            },
+            limits: () => ({ maxOutputs: spend_1.MAX_OUTPUTS }),
+            createNativeClient: () => {
+                // The doc's promise: taproot works on this module (and a swapped backend is undone).
+                (0, sdk_1.useNobleEcc)();
+                const client = {
+                    bitcoin: sdk_1.bitcoin,
+                    network: { ...network, bip32: { ...network.bip32 } },
+                    esplora: (path, responseType = 'json') => ctx.transport.http({ method: 'GET', path, route: '/native', responseType }, context_1.READ),
+                };
+                return { client };
+            },
+        };
+    },
+};
+//# sourceMappingURL=driver.js.map

package/dist/adapters/utxo/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../../src/adapters/utxo/driver.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The UTXO driver factory: validated network config, endpoint probes on both transports,\n * and the ports. Loaded only by the manifest's `load()`, with bitcoinjs-lib.\n */\nimport type { ChainDriver, DriverContext, DriverFactory } from '../../core/driver/types';\nimport { ConfigError } from '../../core/errors/error';\nimport type { EndpointCall, HealthProbes } from '../../core/transport/types';\nimport { utxoBroadcaster, utxoBuilder, utxoReplacement } from './builder';\nimport { networkOf } from './codec';\nimport { READ, type UtxoContext } from './context';\nimport { EsploraClient, parseHash, parseHeight } from './esplora';\nimport { utxoNetworkConfig } from './network';\nimport { blockSource, proofSource } from './proofs';\nimport { addressCodec, addressHistory, chainReader, listUnspent } from './reader';\nimport { bitcoin, useNobleEcc } from './sdk';\nimport { coinSelectionPreview } from './preview';\nimport { MAX_OUTPUTS } from './spend';\nimport type { UtxoExt } from './types';\n\nexport interface UtxoNativeClient {\n  /** The bitcoinjs-lib module, with this library's `@noble/curves` ECC backend installed. */\n  readonly bitcoin: typeof bitcoin;\n  /** A fresh copy of this network's bitcoinjs parameters. */\n  readonly network: ReturnType<typeof networkOf>;\n  /** A GET to the handle's Esplora (`rpc`) endpoints, through the policy-wrapped transport. */\n  esplora<T = unknown>(path: string, responseType?: 'json' | 'text'): Promise<T>;\n}\n\nfunction probes(expectedIdentity: string): HealthProbes {\n  const text = (call: EndpointCall, path: string, route: string) =>\n    call.http<string>({ method: 'GET', path, route, responseType: 'text' });\n  return {\n    identity: async (call) =>\n      parseHash(await text(call, '/block-height/0', '/block-height/:height')),\n    expectedIdentity,\n    height: async (call) =>\n      parseHeight(await text(call, '/blocks/tip/height', '/blocks/tip/height')),\n  };\n}\n\nexport const utxoDriverFactory: DriverFactory = {\n  async create(ctx: DriverContext): Promise<ChainDriver> {\n    const config = utxoNetworkConfig(ctx.chain, ctx.network, ctx.options);\n    if (!ctx.indexer) {\n      throw new ConfigError(\n        'CONFIG_INVALID',\n        'the UTXO driver requires an indexer provider',\n      );\n    }\n    // Both transports, before any traffic: the genesis-hash probe keeps an endpoint of\n    // another network out of the `rpc` reads and the `indexer` reads alike.\n    ctx.transport.setProbes(probes(config.genesisHash));\n    ctx.indexer.setProbes(probes(config.genesisHash));\n    const esplora = new EsploraClient(ctx.transport, ctx.indexer);\n    const utxo: UtxoContext = {\n      esplora,\n      chain: ctx.chain,\n      network: ctx.network,\n      config,\n      log: ctx.log,\n    };\n    const network = networkOf(config.address);\n    const builder = utxoBuilder(utxo, network);\n    return {\n      ordering: 'inputs',\n      capabilities: config.capabilities,\n      address: addressCodec(utxo),\n      reader: chainReader(utxo),\n      builder,\n      broadcaster: utxoBroadcaster(utxo),\n      proofs: proofSource(utxo),\n      replacement: utxoReplacement(utxo, network),\n      blocks: blockSource(utxo),\n      history: addressHistory(utxo),\n      ext: {\n        utxo: {\n          listUnspent: (address: string) => listUnspent(utxo, address),\n          coinSelection: (request: Parameters<UtxoExt['utxo']['coinSelection']>[0]) =>\n            coinSelectionPreview(utxo, request),\n        },\n      } satisfies UtxoExt,\n      limits: () => ({ maxOutputs: MAX_OUTPUTS }),\n      createNativeClient: () => {\n        // The doc's promise: taproot works on this module (and a swapped backend is undone).\n        useNobleEcc();\n        const client: UtxoNativeClient = {\n          bitcoin,\n          network: { ...network, bip32: { ...network.bip32 } },\n          esplora: <T>(path: string, responseType: 'json' | 'text' = 'json') =>\n            ctx.transport.http<T>(\n              { method: 'GET', path, route: '/native', responseType },\n              READ,\n            ),\n        };\n        return { client };\n      },\n    };\n  },\n};\n"]}

package/dist/adapters/utxo/ecc.d.ts

@@ -0,0 +1,9 @@
+import { isXOnlyPoint } from './address';
+export interface XOnlyTweakResult {
+    readonly parity: 0 | 1;
+    readonly xOnlyPubkey: Uint8Array;
+}
+export declare const nobleEcc: Readonly<{
+    isXOnlyPoint: typeof isXOnlyPoint;
+    xOnlyPointAddTweak(point: Uint8Array, tweak: Uint8Array): XOnlyTweakResult | null;
+}>;

package/dist/adapters/utxo/ecc.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nobleEcc = void 0;
+/**
+ * bitcoinjs-lib's ECC interface (`isXOnlyPoint`, `xOnlyPointAddTweak`) over
+ * `@noble/curves`. SDK-free: bitcoinjs checks it against its own vectors when
+ * `initEccLib` installs it.
+ */
+const secp256k1_1 = require("@noble/curves/secp256k1");
+const address_1 = require("./address");
+exports.nobleEcc = Object.freeze({
+    isXOnlyPoint: address_1.isXOnlyPoint,
+    xOnlyPointAddTweak(point, tweak) {
+        if (!(0, address_1.isXOnlyPoint)(point) || tweak.length !== 32)
+            return null;
+        const t = secp256k1_1.schnorr.utils.bytesToNumberBE(tweak);
+        if (t >= secp256k1_1.secp256k1.CURVE.n)
+            return null;
+        const P = secp256k1_1.schnorr.utils.lift_x(secp256k1_1.schnorr.utils.bytesToNumberBE(point));
+        const Q = t === 0n ? P : P.add(secp256k1_1.secp256k1.ProjectivePoint.BASE.multiply(t));
+        if (Q.equals(secp256k1_1.secp256k1.ProjectivePoint.ZERO))
+            return null;
+        return { parity: Q.hasEvenY() ? 0 : 1, xOnlyPubkey: Q.toRawBytes(true).slice(1) };
+    },
+});
+//# sourceMappingURL=ecc.js.map

package/dist/adapters/utxo/ecc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecc.js","sourceRoot":"","sources":["../../../src/adapters/utxo/ecc.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,uDAA6D;AAC7D,uCAAyC;AAO5B,QAAA,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IACpC,YAAY,EAAZ,sBAAY;IACZ,kBAAkB,CAAC,KAAiB,EAAE,KAAiB;QACrD,IAAI,CAAC,IAAA,sBAAY,EAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;QAC7D,MAAM,CAAC,GAAG,mBAAO,CAAC,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,qBAAS,CAAC,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACxC,MAAM,CAAC,GAAG,mBAAO,CAAC,KAAK,CAAC,MAAM,CAAC,mBAAO,CAAC,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;QACrE,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,qBAAS,CAAC,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3E,IAAI,CAAC,CAAC,MAAM,CAAC,qBAAS,CAAC,eAAe,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1D,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACpF,CAAC;CACF,CAAC,CAAC","sourcesContent":["/**\n * bitcoinjs-lib's ECC interface (`isXOnlyPoint`, `xOnlyPointAddTweak`) over\n * `@noble/curves`. SDK-free: bitcoinjs checks it against its own vectors when\n * `initEccLib` installs it.\n */\nimport { schnorr, secp256k1 } from '@noble/curves/secp256k1';\nimport { isXOnlyPoint } from './address';\n\nexport interface XOnlyTweakResult {\n  readonly parity: 0 | 1;\n  readonly xOnlyPubkey: Uint8Array;\n}\n\nexport const nobleEcc = Object.freeze({\n  isXOnlyPoint,\n  xOnlyPointAddTweak(point: Uint8Array, tweak: Uint8Array): XOnlyTweakResult | null {\n    if (!isXOnlyPoint(point) || tweak.length !== 32) return null;\n    const t = schnorr.utils.bytesToNumberBE(tweak);\n    if (t >= secp256k1.CURVE.n) return null;\n    const P = schnorr.utils.lift_x(schnorr.utils.bytesToNumberBE(point));\n    const Q = t === 0n ? P : P.add(secp256k1.ProjectivePoint.BASE.multiply(t));\n    if (Q.equals(secp256k1.ProjectivePoint.ZERO)) return null;\n    return { parity: Q.hasEvenY() ? 0 : 1, xOnlyPubkey: Q.toRawBytes(true).slice(1) };\n  },\n});\n"]}