crypto-aio 0.0.2 → 0.1.0

package/dist/adapters/utxo/spend.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XPUB_CHANGE_SEARCH = exports.MAX_OUTPUTS = exports.assertNative = void 0;
+exports.plannedOutputs = plannedOutputs;
+exports.senderOf = senderOf;
+exports.walletOf = walletOf;
+exports.changeAddressOf = changeAddressOf;
+exports.spendable = spendable;
+exports.rateOf = rateOf;
+const error_1 = require("../../core/errors/error");
+const fee_1 = require("../../core/model/fee");
+const address_1 = require("./address");
+const context_1 = require("./context");
+var context_2 = require("./context");
+Object.defineProperty(exports, "assertNative", { enumerable: true, get: function () { return context_2.assertNative; } });
+const bip32_1 = require("@scure/bip32");
+const hd_1 = require("../../core/signing/hd");
+const fees_1 = require("./fees");
+const reader_1 = require("./reader");
+/**
+ * The most outputs one transfer may pay (`limits().maxOutputs`), enforced here because
+ * the core only reports it. Library policy: 1,000 taproot outputs are about 43 kvB, far
+ * below the 100 kvB standard size.
+ */
+exports.MAX_OUTPUTS = 1_000;
+/** The intent's outputs as scripts; each must be a standard address and above dust. */
+function plannedOutputs(ctx, outputs) {
+    if (outputs.length === 0) {
+        throw new error_1.ValidationError('INVALID_INTENT', 'at least one output is required');
+    }
+    if (outputs.length > exports.MAX_OUTPUTS) {
+        throw new error_1.ValidationError('INVALID_INTENT', `a transfer pays at most ${exports.MAX_OUTPUTS} outputs`);
+    }
+    return outputs.map((output) => {
+        const { script } = (0, address_1.decodeAddress)(output.to, ctx.config.address);
+        if (output.amount < (0, address_1.dustThreshold)(script, ctx.config.dustRelayFee)) {
+            throw new error_1.ValidationError('INVALID_AMOUNT', 'an output is below the dust threshold and would not be relayed');
+        }
+        return { script, value: output.amount };
+    });
+}
+function senderOf(ctx, from) {
+    const decoded = (0, address_1.decodeAddress)(from, ctx.config.address);
+    return { from: decoded, type: (0, address_1.walletTypeOf)(decoded) };
+}
+/**
+ * The wallet's scripts from its key, which must own the sending address: nothing is ever
+ * built for inputs the wallet's key cannot sign (`INVALID_INTENT`).
+ */
+function walletOf(ctx, sender, keys) {
+    const key = keys[0];
+    if (!key) {
+        throw new error_1.ValidationError('INVALID_INTENT', 'building a Bitcoin transaction needs the wallet public key');
+    }
+    const wallet = (0, address_1.walletAddress)(key.publicKey, sender.type, ctx.config.address);
+    if (wallet.address !== sender.from.canonical) {
+        throw new error_1.ValidationError('INVALID_INTENT', "the wallet's key does not own the sending address");
+    }
+    return { wallet, key };
+}
+/** How many indexes `changeAddressOf` searches on each chain of the wallet's xpub. */
+exports.XPUB_CHANGE_SEARCH = 20;
+/** The chains `xpubDerives` keeps, each as the addresses it derives. */
+const XPUB_CACHE_ENTRIES = 64;
+const xpubChains = new Map();
+/** The key at `path` below `root`, deriving each parent node once (`parents`). */
+function childKey(root, parents, path) {
+    const full = path.startsWith('m') ? path : `m/${path}`;
+    const cut = full.lastIndexOf('/');
+    const last = full.slice(cut + 1);
+    if (cut < 0 || !/^[0-9]{1,10}$/.test(last) || Number(last) >= bip32_1.HARDENED_OFFSET) {
+        throw new RangeError('not a plain child path');
+    }
+    const parentPath = full.slice(0, cut);
+    let parent = parents.get(parentPath);
+    if (!parent) {
+        parent = root.derive(parentPath);
+        parents.set(parentPath, parent);
+    }
+    const key = parent.deriveChild(Number(last)).publicKey;
+    if (!key)
+        throw new RangeError('no public key');
+    return key;
+}
+/**
+ * Whether the wallet's xpub derives `target` for the sender's address type, at indexes
+ * 0–19 of its configured path (default `0/{index}`) or of the change chain `1/{index}`. A
+ * bounded search: at most 40 child keys, and only after the key check failed. `wallet.hd`
+ * is the core's own `WalletHdOptions` (a caller's `hd` never reaches a driver), and its
+ * `xpub` is always a public key. An xpub of the other network class (a mainnet `xpub` on
+ * a test network, or the reverse) is `CONFIG_INVALID`.
+ *
+ * The search runs on every estimate, build, replacement and cancel, so it parses the xpub
+ * once, derives each chain node once, and keeps each chain's addresses (per xpub,
+ * versions, network, wallet type and template) in a bounded cache. The core's
+ * `deriveXpubChild` checks the key first (a public key of the network's class, no
+ * hardened segments), with its fixed texts, and derives any path this shortcut does not
+ * model.
+ */
+function xpubDerives(ctx, wallet, type, target) {
+    const hd = wallet.hd;
+    if (typeof hd?.xpub !== 'string' || hd.xpub.length === 0)
+        return false;
+    const xpub = hd.xpub;
+    const network = { testnet: ctx.network.testnet };
+    const templates = [
+        ...new Set([
+            typeof hd.xpubPath === 'string' ? hd.xpubPath : '0/{index}',
+            '1/{index}',
+        ]),
+    ];
+    const keyOf = (template) => JSON.stringify([
+        xpub,
+        hd.xpubVersions ?? null,
+        network.testnet,
+        ctx.config.address,
+        type,
+        template,
+    ]);
+    let root;
+    const parents = new Map();
+    for (const template of templates) {
+        const key = keyOf(template);
+        let chain = xpubChains.get(key);
+        if (chain) {
+            xpubChains.delete(key); // most recently used last
+        }
+        else {
+            const paths = [
+                ...new Set(Array.from({ length: exports.XPUB_CHANGE_SEARCH }, (_, index) => template.replace('{index}', String(index)))),
+            ];
+            if (!root) {
+                (0, hd_1.deriveXpubChild)(xpub, paths[0], hd.xpubVersions, network);
+                root = (0, hd_1.parseExtendedPublicKey)(xpub, hd.xpubVersions).node;
+            }
+            const addresses = new Set();
+            for (const path of paths) {
+                let child;
+                try {
+                    child = childKey(root, parents, path);
+                }
+                catch {
+                    child = (0, hd_1.deriveXpubChild)(xpub, path, hd.xpubVersions, network);
+                }
+                addresses.add((0, address_1.walletAddress)(child, type, ctx.config.address).address);
+            }
+            chain = addresses;
+        }
+        xpubChains.set(key, chain);
+        while (xpubChains.size > XPUB_CACHE_ENTRIES) {
+            xpubChains.delete(xpubChains.keys().next().value);
+        }
+        if (chain.has(target))
+            return true;
+    }
+    return false;
+}
+/**
+ * Where change goes. A configured `changeAddress` must be derivable from the wallet: the
+ * sending address, or any of the four wallet types of one of the wallet's keys (a bounded
+ * search, at most 4 per key). Otherwise it is refused with `CONFIG_INVALID`, naming no
+ * address, because a valid but mistyped address would lose every change output. The
+ * wallet opts out with `allowExternalChangeAddress: true`.
+ */
+function changeAddressOf(ctx, wallet, sender, keys) {
+    const { changeAddress, allowExternalChangeAddress } = (0, context_1.parseWalletOptions)(wallet, ctx.config);
+    if (!changeAddress)
+        return sender.from;
+    if (allowExternalChangeAddress)
+        return changeAddress;
+    const target = changeAddress.canonical;
+    if (target === sender.from.canonical)
+        return changeAddress;
+    for (const key of keys) {
+        for (const type of context_1.ADDRESS_TYPES) {
+            let derived;
+            try {
+                derived = (0, address_1.walletAddress)(key.publicKey, type, ctx.config.address).address;
+            }
+            catch {
+                continue; // e.g. an x-only key derives only p2tr
+            }
+            if (derived === target)
+                return changeAddress;
+        }
+    }
+    if (xpubDerives(ctx, wallet, sender.type, target))
+        return changeAddress;
+    throw new error_1.ConfigError('CONFIG_INVALID', "wallet.utxo.changeAddress is not derivable from the wallet's key; set wallet.utxo.allowExternalChangeAddress to send change elsewhere");
+}
+/**
+ * The wallet's outputs coin selection may spend. They are read as `listUnspent` reads them:
+ * an output the indexer lists twice alike counts once (the funds check sums them), and two
+ * listings that disagree decide nothing (retryable).
+ */
+async function spendable(ctx, from, exclude, minConfirmations, signal) {
+    const [utxos, tip] = await Promise.all([
+        (0, reader_1.listUnspent)(ctx, from, signal),
+        ctx.esplora.tipHeight((0, context_1.withSignal)(context_1.READ, signal)),
+    ]);
+    const held = new Set(exclude ?? []);
+    return utxos
+        .filter((utxo) => {
+        if (held.has(utxo.outpoint))
+            return false;
+        if (minConfirmations === 0)
+            return true;
+        if (!utxo.confirmed)
+            return false;
+        return tip - utxo.blockHeight + 1n >= BigInt(minConfirmations);
+    })
+        .map((utxo) => ({
+        outpoint: utxo.outpoint,
+        txid: utxo.txid,
+        vout: utxo.vout,
+        value: utxo.value,
+    }));
+}
+/** The fee rate (sat/kvB) of a speed or a `{ satPerVByte }` override. */
+async function rateOf(ctx, fee, signal) {
+    if ((0, fee_1.isFeeSpeed)(fee)) {
+        const estimates = await ctx.esplora.feeEstimates((0, context_1.withSignal)(context_1.READ, signal));
+        return (0, fees_1.rateForSpeed)(estimates, fee, ctx.config);
+    }
+    if (fee === null || typeof fee !== 'object') {
+        throw new error_1.ValidationError('INVALID_INTENT', 'fee must be a speed or { satPerVByte }');
+    }
+    return (0, fees_1.rateFromOverride)(fee, ctx.config);
+}
+//# sourceMappingURL=spend.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spend.js","sourceRoot":"","sources":["../../../src/adapters/utxo/spend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What coin selection spends and pays: the planned outputs of an intent (strict addresses,\n * no dust), the wallet's eligible outputs (not reserved by another live Operation, and\n * confirmed as deeply as `minInputConfirmations` asks), and the fee rate of a fee spec.\n *\n * This module loads bitcoinjs-lib (`spendable` reads through `reader.ts`, which imports the\n * codec and `sdk.ts`), so only modules behind the manifest's `load()` may import it; an\n * SDK-free module (the plugin, an entry's types) must not.\n */\nimport type { WalletKey, WalletOptions } from '../../core/driver/types';\nimport { ConfigError, ValidationError } from '../../core/errors/error';\nimport { isFeeSpeed, type FeeOverride, type FeeSpeed } from '../../core/model/fee';\nimport {\n  decodeAddress,\n  dustThreshold,\n  walletAddress,\n  walletTypeOf,\n  type DecodedAddress,\n  type WalletAddress,\n} from './address';\nimport type { PlannedOutput, Spendable } from './coinselect';\nimport {\n  ADDRESS_TYPES,\n  READ,\n  parseWalletOptions,\n  withSignal,\n  type UtxoContext,\n} from './context';\n\nexport { assertNative } from './context';\nimport { HARDENED_OFFSET, type HDKey } from '@scure/bip32';\nimport { deriveXpubChild, parseExtendedPublicKey } from '../../core/signing/hd';\nimport type { WalletHdOptions } from '../../core/signing/wallet';\nimport { rateForSpeed, rateFromOverride } from './fees';\nimport { listUnspent } from './reader';\nimport type { UtxoAddressType } from './types';\n\n/**\n * The most outputs one transfer may pay (`limits().maxOutputs`), enforced here because\n * the core only reports it. Library policy: 1,000 taproot outputs are about 43 kvB, far\n * below the 100 kvB standard size.\n */\nexport const MAX_OUTPUTS = 1_000;\n\n/** The intent's outputs as scripts; each must be a standard address and above dust. */\nexport function plannedOutputs(\n  ctx: UtxoContext,\n  outputs: readonly { readonly to: string; readonly amount: bigint }[],\n): PlannedOutput[] {\n  if (outputs.length === 0) {\n    throw new ValidationError('INVALID_INTENT', 'at least one output is required');\n  }\n  if (outputs.length > MAX_OUTPUTS) {\n    throw new ValidationError(\n      'INVALID_INTENT',\n      `a transfer pays at most ${MAX_OUTPUTS} outputs`,\n    );\n  }\n  return outputs.map((output) => {\n    const { script } = decodeAddress(output.to, ctx.config.address);\n    if (output.amount < dustThreshold(script, ctx.config.dustRelayFee)) {\n      throw new ValidationError(\n        'INVALID_AMOUNT',\n        'an output is below the dust threshold and would not be relayed',\n      );\n    }\n    return { script, value: output.amount };\n  });\n}\n\n/** The sending wallet: its type (from the address; p2sh is p2sh-p2wpkh) and, with a key, its scripts. */\nexport interface Sender {\n  readonly from: DecodedAddress;\n  readonly type: UtxoAddressType;\n}\n\nexport function senderOf(ctx: UtxoContext, from: string): Sender {\n  const decoded = decodeAddress(from, ctx.config.address);\n  return { from: decoded, type: walletTypeOf(decoded) };\n}\n\n/**\n * The wallet's scripts from its key, which must own the sending address: nothing is ever\n * built for inputs the wallet's key cannot sign (`INVALID_INTENT`).\n */\nexport function walletOf(\n  ctx: UtxoContext,\n  sender: Sender,\n  keys: readonly WalletKey[],\n): { readonly wallet: WalletAddress; readonly key: WalletKey } {\n  const key = keys[0];\n  if (!key) {\n    throw new ValidationError(\n      'INVALID_INTENT',\n      'building a Bitcoin transaction needs the wallet public key',\n    );\n  }\n  const wallet = walletAddress(key.publicKey, sender.type, ctx.config.address);\n  if (wallet.address !== sender.from.canonical) {\n    throw new ValidationError(\n      'INVALID_INTENT',\n      \"the wallet's key does not own the sending address\",\n    );\n  }\n  return { wallet, key };\n}\n\n/** How many indexes `changeAddressOf` searches on each chain of the wallet's xpub. */\nexport const XPUB_CHANGE_SEARCH = 20;\n\n/** The chains `xpubDerives` keeps, each as the addresses it derives. */\nconst XPUB_CACHE_ENTRIES = 64;\nconst xpubChains = new Map<string, ReadonlySet<string>>();\n\n/** The key at `path` below `root`, deriving each parent node once (`parents`). */\nfunction childKey(root: HDKey, parents: Map<string, HDKey>, path: string): Uint8Array {\n  const full = path.startsWith('m') ? path : `m/${path}`;\n  const cut = full.lastIndexOf('/');\n  const last = full.slice(cut + 1);\n  if (cut < 0 || !/^[0-9]{1,10}$/.test(last) || Number(last) >= HARDENED_OFFSET) {\n    throw new RangeError('not a plain child path');\n  }\n  const parentPath = full.slice(0, cut);\n  let parent = parents.get(parentPath);\n  if (!parent) {\n    parent = root.derive(parentPath);\n    parents.set(parentPath, parent);\n  }\n  const key = parent.deriveChild(Number(last)).publicKey;\n  if (!key) throw new RangeError('no public key');\n  return key;\n}\n\n/**\n * Whether the wallet's xpub derives `target` for the sender's address type, at indexes\n * 0–19 of its configured path (default `0/{index}`) or of the change chain `1/{index}`. A\n * bounded search: at most 40 child keys, and only after the key check failed. `wallet.hd`\n * is the core's own `WalletHdOptions` (a caller's `hd` never reaches a driver), and its\n * `xpub` is always a public key. An xpub of the other network class (a mainnet `xpub` on\n * a test network, or the reverse) is `CONFIG_INVALID`.\n *\n * The search runs on every estimate, build, replacement and cancel, so it parses the xpub\n * once, derives each chain node once, and keeps each chain's addresses (per xpub,\n * versions, network, wallet type and template) in a bounded cache. The core's\n * `deriveXpubChild` checks the key first (a public key of the network's class, no\n * hardened segments), with its fixed texts, and derives any path this shortcut does not\n * model.\n */\nfunction xpubDerives(\n  ctx: UtxoContext,\n  wallet: WalletOptions,\n  type: UtxoAddressType,\n  target: string,\n): boolean {\n  const hd = wallet.hd as WalletHdOptions | undefined;\n  if (typeof hd?.xpub !== 'string' || hd.xpub.length === 0) return false;\n  const xpub = hd.xpub;\n  const network = { testnet: ctx.network.testnet };\n  const templates = [\n    ...new Set([\n      typeof hd.xpubPath === 'string' ? hd.xpubPath : '0/{index}',\n      '1/{index}',\n    ]),\n  ];\n  const keyOf = (template: string) =>\n    JSON.stringify([\n      xpub,\n      hd.xpubVersions ?? null,\n      network.testnet,\n      ctx.config.address,\n      type,\n      template,\n    ]);\n  let root: HDKey | undefined;\n  const parents = new Map<string, HDKey>();\n  for (const template of templates) {\n    const key = keyOf(template);\n    let chain = xpubChains.get(key);\n    if (chain) {\n      xpubChains.delete(key); // most recently used last\n    } else {\n      const paths = [\n        ...new Set(\n          Array.from({ length: XPUB_CHANGE_SEARCH }, (_, index) =>\n            template.replace('{index}', String(index)),\n          ),\n        ),\n      ];\n      if (!root) {\n        deriveXpubChild(xpub, paths[0] as string, hd.xpubVersions, network);\n        root = parseExtendedPublicKey(xpub, hd.xpubVersions).node;\n      }\n      const addresses = new Set<string>();\n      for (const path of paths) {\n        let child: Uint8Array;\n        try {\n          child = childKey(root, parents, path);\n        } catch {\n          child = deriveXpubChild(xpub, path, hd.xpubVersions, network);\n        }\n        addresses.add(walletAddress(child, type, ctx.config.address).address);\n      }\n      chain = addresses;\n    }\n    xpubChains.set(key, chain);\n    while (xpubChains.size > XPUB_CACHE_ENTRIES) {\n      xpubChains.delete(xpubChains.keys().next().value as string);\n    }\n    if (chain.has(target)) return true;\n  }\n  return false;\n}\n\n/**\n * Where change goes. A configured `changeAddress` must be derivable from the wallet: the\n * sending address, or any of the four wallet types of one of the wallet's keys (a bounded\n * search, at most 4 per key). Otherwise it is refused with `CONFIG_INVALID`, naming no\n * address, because a valid but mistyped address would lose every change output. The\n * wallet opts out with `allowExternalChangeAddress: true`.\n */\nexport function changeAddressOf(\n  ctx: UtxoContext,\n  wallet: WalletOptions,\n  sender: Sender,\n  keys: readonly WalletKey[],\n): DecodedAddress {\n  const { changeAddress, allowExternalChangeAddress } = parseWalletOptions(\n    wallet,\n    ctx.config,\n  );\n  if (!changeAddress) return sender.from;\n  if (allowExternalChangeAddress) return changeAddress;\n  const target = changeAddress.canonical;\n  if (target === sender.from.canonical) return changeAddress;\n  for (const key of keys) {\n    for (const type of ADDRESS_TYPES) {\n      let derived: string;\n      try {\n        derived = walletAddress(key.publicKey, type, ctx.config.address).address;\n      } catch {\n        continue; // e.g. an x-only key derives only p2tr\n      }\n      if (derived === target) return changeAddress;\n    }\n  }\n  if (xpubDerives(ctx, wallet, sender.type, target)) return changeAddress;\n  throw new ConfigError(\n    'CONFIG_INVALID',\n    \"wallet.utxo.changeAddress is not derivable from the wallet's key; set wallet.utxo.allowExternalChangeAddress to send change elsewhere\",\n  );\n}\n\n/**\n * The wallet's outputs coin selection may spend. They are read as `listUnspent` reads them:\n * an output the indexer lists twice alike counts once (the funds check sums them), and two\n * listings that disagree decide nothing (retryable).\n */\nexport async function spendable(\n  ctx: UtxoContext,\n  from: string,\n  exclude: readonly string[] | undefined,\n  minConfirmations: number,\n  signal?: AbortSignal,\n): Promise<Spendable[]> {\n  const [utxos, tip] = await Promise.all([\n    listUnspent(ctx, from, signal),\n    ctx.esplora.tipHeight(withSignal(READ, signal)),\n  ]);\n  const held = new Set(exclude ?? []);\n  return utxos\n    .filter((utxo) => {\n      if (held.has(utxo.outpoint)) return false;\n      if (minConfirmations === 0) return true;\n      if (!utxo.confirmed) return false;\n      return tip - (utxo.blockHeight as bigint) + 1n >= BigInt(minConfirmations);\n    })\n    .map((utxo) => ({\n      outpoint: utxo.outpoint,\n      txid: utxo.txid,\n      vout: utxo.vout,\n      value: utxo.value,\n    }));\n}\n\n/** The fee rate (sat/kvB) of a speed or a `{ satPerVByte }` override. */\nexport async function rateOf(\n  ctx: UtxoContext,\n  fee: FeeSpeed | FeeOverride,\n  signal?: AbortSignal,\n): Promise<bigint> {\n  if (isFeeSpeed(fee)) {\n    const estimates = await ctx.esplora.feeEstimates(withSignal(READ, signal));\n    return rateForSpeed(estimates, fee, ctx.config);\n  }\n  if (fee === null || typeof fee !== 'object') {\n    throw new ValidationError('INVALID_INTENT', 'fee must be a speed or { satPerVByte }');\n  }\n  return rateFromOverride(fee, ctx.config);\n}\n"]}

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

@@ -0,0 +1,167 @@
+/**
+ * SDK-free types of the UTXO family: the `ext.utxo` API, fee details and overrides, wallet
+ * options, and the Esplora wire types the driver reads. Nothing here imports an
+ * SDK, so the composition root can export these types.
+ */
+import type { FeeSpeed } from '../../core/model/fee';
+import type { CallOptions } from '../../core/transport/types';
+declare module '../../index' {
+    interface ChainRegistry {
+        bitcoin: {
+            family: 'utxo';
+            network: 'mainnet' | 'testnet' | 'testnet4' | 'signet' | 'regtest';
+        };
+    }
+    interface FamilyRegistry {
+        utxo: {
+            library: 'bitcoinjs-lib';
+            ext: UtxoExt;
+            fee: UtxoFeeDetails;
+        };
+    }
+}
+/** A network's address encoding: the bech32 human-readable part and base58 version bytes. */
+export interface AddressParams {
+    readonly bech32: string;
+    readonly pubKeyHash: number;
+    readonly scriptHash: number;
+}
+/** The address (and so the input) type of a UTXO wallet; `p2wpkh` is the default. */
+export type UtxoAddressType = 'p2wpkh' | 'p2sh-p2wpkh' | 'p2pkh' | 'p2tr';
+/** Every standard output type a UTXO transfer may pay to. */
+export type UtxoOutputType = 'p2pkh' | 'p2sh' | 'p2wpkh' | 'p2wsh' | 'p2tr';
+/** `WalletConfig.utxo`. */
+export interface UtxoWalletOptions {
+    readonly addressType?: UtxoAddressType;
+    /**
+     * Where change goes; default: the wallet's own address. It must be derivable from the
+     * wallet's key (any of the four address types), unless `allowExternalChangeAddress` is set.
+     */
+    readonly changeAddress?: string;
+    /**
+     * Send change to a `changeAddress` the wallet's key does not derive (default `false`).
+     * Change sent to a valid but foreign address is lost, so without it a mistyped address
+     * is refused.
+     */
+    readonly allowExternalChangeAddress?: boolean;
+}
+/** `FeeEstimate.details` of the `utxo` fee kind. */
+export interface UtxoFeeDetails {
+    /** The fee rate in satoshis per 1,000 virtual bytes (Bitcoin Core's unit). */
+    readonly satPerKvB: bigint;
+    /** Virtual size of the transaction, counting worst-case (72-byte) ECDSA signatures. */
+    readonly vsize: number;
+    readonly inputs: number;
+    /** Outputs including change. */
+    readonly outputs: number;
+    /** The change amount; `0n` when there is no change output. */
+    readonly change: bigint;
+    /** Index of the change output, or `-1` when there is none. */
+    readonly changeIndex: number;
+}
+/**
+ * An explicit UTXO fee (`TransferIntent.fee`): satoshis per virtual byte, as a bigint or a
+ * decimal string with at most three fractional digits (e.g. `'1.5'`).
+ */
+export type UtxoFeeOverride = {
+    readonly satPerVByte: bigint | string;
+};
+/** An unspent output of an address, as `ext.utxo.listUnspent` reports it. */
+export interface UtxoUnspent {
+    /** `txid:vout`, the reservation key of this output. */
+    readonly outpoint: string;
+    readonly txid: string;
+    readonly vout: number;
+    readonly value: bigint;
+    readonly confirmed: boolean;
+    readonly blockHeight?: bigint;
+}
+export interface UtxoSelectionRequest {
+    readonly from: string;
+    readonly outputs: readonly {
+        readonly to: string;
+        readonly amount: bigint;
+    }[];
+    readonly fee?: FeeSpeed | UtxoFeeOverride;
+    /** Outpoints to leave out (e.g. those held by live Operations). */
+    readonly exclude?: readonly string[];
+}
+/** A dry run of the configured coin selection. */
+export interface UtxoSelectionPreview {
+    /** The outputs it would spend (every eligible one when `sufficient` is `false`). */
+    readonly inputs: readonly {
+        readonly outpoint: string;
+        readonly value: bigint;
+    }[];
+    readonly fee: bigint;
+    readonly satPerKvB: bigint;
+    readonly vsize: number;
+    readonly change: bigint;
+    /** `false` when the eligible outputs cannot pay for the outputs and the fee. */
+    readonly sufficient: boolean;
+}
+/** `bc.ext.utxo`: the UTXO family extension. */
+export interface UtxoExt {
+    readonly utxo: {
+        /** Unspent outputs of an address (indexer), confirmed first, oldest first. */
+        listUnspent(address: string): Promise<readonly UtxoUnspent[]>;
+        /** What the configured coin selection would pick for these outputs. Signs nothing. */
+        coinSelection(request: UtxoSelectionRequest): Promise<UtxoSelectionPreview>;
+    };
+}
+/** The transport tags every UTXO I/O call carries (the `ChainDriver` contract table). */
+export type UtxoCallTags = Pick<CallOptions, 'purpose' | 'retry' | 'quorum' | 'quorumKey' | 'fanout' | 'signal'>;
+/** Esplora's `status` object of a transaction or of a spending transaction. */
+export interface EsploraStatus {
+    readonly confirmed: boolean;
+    readonly blockHeight?: bigint;
+    readonly blockHash?: string;
+    readonly blockTime?: number;
+}
+export interface EsploraOutput {
+    readonly script: string;
+    readonly type: string;
+    readonly address?: string;
+    readonly value: bigint;
+}
+export interface EsploraInput {
+    readonly txid: string;
+    readonly vout: number;
+    readonly coinbase: boolean;
+    readonly sequence: number;
+    /** `undefined` for a coinbase input. */
+    readonly prevout?: EsploraOutput;
+}
+export interface EsploraTx {
+    readonly txid: string;
+    readonly version: number;
+    readonly locktime: number;
+    readonly weight: number;
+    readonly fee: bigint;
+    readonly vin: readonly EsploraInput[];
+    readonly vout: readonly EsploraOutput[];
+    readonly status: EsploraStatus;
+}
+export interface EsploraBlock {
+    readonly hash: string;
+    readonly height: bigint;
+    readonly parentHash: string;
+    readonly timestamp: number;
+    readonly txCount: number;
+}
+export interface EsploraOutspend {
+    readonly spent: boolean;
+    readonly txid?: string;
+    readonly vin?: number;
+    readonly status?: EsploraStatus;
+}
+export interface EsploraUtxo {
+    readonly txid: string;
+    readonly vout: number;
+    readonly value: bigint;
+    readonly status: EsploraStatus;
+}
+export interface EsploraAddressStats {
+    readonly funded: bigint;
+    readonly spent: bigint;
+}

package/dist/adapters/utxo/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/utxo/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * SDK-free types of the UTXO family: the `ext.utxo` API, fee details and overrides, wallet\n * options, and the Esplora wire types the driver reads. Nothing here imports an\n * SDK, so the composition root can export these types.\n */\nimport type { FeeSpeed } from '../../core/model/fee';\nimport type { CallOptions } from '../../core/transport/types';\n\n// Augment the registries through the package entry, as users do with 'crypto-aio'.\ndeclare module '../../index' {\n  interface ChainRegistry {\n    bitcoin: {\n      family: 'utxo';\n      network: 'mainnet' | 'testnet' | 'testnet4' | 'signet' | 'regtest';\n    };\n  }\n  interface FamilyRegistry {\n    utxo: { library: 'bitcoinjs-lib'; ext: UtxoExt; fee: UtxoFeeDetails };\n  }\n}\n\n/** A network's address encoding: the bech32 human-readable part and base58 version bytes. */\nexport interface AddressParams {\n  readonly bech32: string;\n  readonly pubKeyHash: number;\n  readonly scriptHash: number;\n}\n\n/** The address (and so the input) type of a UTXO wallet; `p2wpkh` is the default. */\nexport type UtxoAddressType = 'p2wpkh' | 'p2sh-p2wpkh' | 'p2pkh' | 'p2tr';\n\n/** Every standard output type a UTXO transfer may pay to. */\nexport type UtxoOutputType = 'p2pkh' | 'p2sh' | 'p2wpkh' | 'p2wsh' | 'p2tr';\n\n/** `WalletConfig.utxo`. */\nexport interface UtxoWalletOptions {\n  readonly addressType?: UtxoAddressType;\n  /**\n   * Where change goes; default: the wallet's own address. It must be derivable from the\n   * wallet's key (any of the four address types), unless `allowExternalChangeAddress` is set.\n   */\n  readonly changeAddress?: string;\n  /**\n   * Send change to a `changeAddress` the wallet's key does not derive (default `false`).\n   * Change sent to a valid but foreign address is lost, so without it a mistyped address\n   * is refused.\n   */\n  readonly allowExternalChangeAddress?: boolean;\n}\n\n/** `FeeEstimate.details` of the `utxo` fee kind. */\nexport interface UtxoFeeDetails {\n  /** The fee rate in satoshis per 1,000 virtual bytes (Bitcoin Core's unit). */\n  readonly satPerKvB: bigint;\n  /** Virtual size of the transaction, counting worst-case (72-byte) ECDSA signatures. */\n  readonly vsize: number;\n  readonly inputs: number;\n  /** Outputs including change. */\n  readonly outputs: number;\n  /** The change amount; `0n` when there is no change output. */\n  readonly change: bigint;\n  /** Index of the change output, or `-1` when there is none. */\n  readonly changeIndex: number;\n}\n\n/**\n * An explicit UTXO fee (`TransferIntent.fee`): satoshis per virtual byte, as a bigint or a\n * decimal string with at most three fractional digits (e.g. `'1.5'`).\n */\nexport type UtxoFeeOverride = { readonly satPerVByte: bigint | string };\n\n/** An unspent output of an address, as `ext.utxo.listUnspent` reports it. */\nexport interface UtxoUnspent {\n  /** `txid:vout`, the reservation key of this output. */\n  readonly outpoint: string;\n  readonly txid: string;\n  readonly vout: number;\n  readonly value: bigint;\n  readonly confirmed: boolean;\n  readonly blockHeight?: bigint;\n}\n\nexport interface UtxoSelectionRequest {\n  readonly from: string;\n  readonly outputs: readonly { readonly to: string; readonly amount: bigint }[];\n  readonly fee?: FeeSpeed | UtxoFeeOverride;\n  /** Outpoints to leave out (e.g. those held by live Operations). */\n  readonly exclude?: readonly string[];\n}\n\n/** A dry run of the configured coin selection. */\nexport interface UtxoSelectionPreview {\n  /** The outputs it would spend (every eligible one when `sufficient` is `false`). */\n  readonly inputs: readonly { readonly outpoint: string; readonly value: bigint }[];\n  readonly fee: bigint;\n  readonly satPerKvB: bigint;\n  readonly vsize: number;\n  readonly change: bigint;\n  /** `false` when the eligible outputs cannot pay for the outputs and the fee. */\n  readonly sufficient: boolean;\n}\n\n/** `bc.ext.utxo`: the UTXO family extension. */\nexport interface UtxoExt {\n  readonly utxo: {\n    /** Unspent outputs of an address (indexer), confirmed first, oldest first. */\n    listUnspent(address: string): Promise<readonly UtxoUnspent[]>;\n    /** What the configured coin selection would pick for these outputs. Signs nothing. */\n    coinSelection(request: UtxoSelectionRequest): Promise<UtxoSelectionPreview>;\n  };\n}\n\n/** The transport tags every UTXO I/O call carries (the `ChainDriver` contract table). */\nexport type UtxoCallTags = Pick<\n  CallOptions,\n  'purpose' | 'retry' | 'quorum' | 'quorumKey' | 'fanout' | 'signal'\n>;\n\n/** Esplora's `status` object of a transaction or of a spending transaction. */\nexport interface EsploraStatus {\n  readonly confirmed: boolean;\n  readonly blockHeight?: bigint;\n  readonly blockHash?: string;\n  readonly blockTime?: number;\n}\n\nexport interface EsploraOutput {\n  readonly script: string;\n  readonly type: string;\n  readonly address?: string;\n  readonly value: bigint;\n}\n\nexport interface EsploraInput {\n  readonly txid: string;\n  readonly vout: number;\n  readonly coinbase: boolean;\n  readonly sequence: number;\n  /** `undefined` for a coinbase input. */\n  readonly prevout?: EsploraOutput;\n}\n\nexport interface EsploraTx {\n  readonly txid: string;\n  readonly version: number;\n  readonly locktime: number;\n  readonly weight: number;\n  readonly fee: bigint;\n  readonly vin: readonly EsploraInput[];\n  readonly vout: readonly EsploraOutput[];\n  readonly status: EsploraStatus;\n}\n\nexport interface EsploraBlock {\n  readonly hash: string;\n  readonly height: bigint;\n  readonly parentHash: string;\n  readonly timestamp: number;\n  readonly txCount: number;\n}\n\nexport interface EsploraOutspend {\n  readonly spent: boolean;\n  readonly txid?: string;\n  readonly vin?: number;\n  readonly status?: EsploraStatus;\n}\n\nexport interface EsploraUtxo {\n  readonly txid: string;\n  readonly vout: number;\n  readonly value: bigint;\n  readonly status: EsploraStatus;\n}\n\nexport interface EsploraAddressStats {\n  readonly funded: bigint;\n  readonly spent: bigint;\n}\n"]}

package/dist/core/assets/service.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedSelection } from '../config/types';
+import type { ChainDriver } from '../driver/types';
+import { type AssetInfo, type AssetRef } from '../model/asset';
+import type { Catalogs } from '../registry/plugin';
+/**
+ * Resolves asset inputs strictly within one chain/network. Token metadata is cached per
+ * container, and so is a token's own permanent failure (only a non-retryable
+ * crypto-aio `ASSET_RESOLUTION` error, e.g. for a contract with no usable `decimals`), so a
+ * junk token seen in every scanned block is queried once. Every other failure (a retryable
+ * one of any code, any other provider error, or a foreign error) is dropped from the cache,
+ * and the next resolution queries again: a provider fault must never pin a token.
+ */
+export declare class AssetService {
+    #private;
+    private readonly catalogs;
+    constructor(catalogs: () => Catalogs);
+    resolve(selection: ResolvedSelection, driver: ChainDriver, input: AssetRef | string | undefined): Promise<AssetInfo>;
+}

package/dist/core/assets/service.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssetService = void 0;
+const error_1 = require("../errors/error");
+const asset_1 = require("../model/asset");
+/**
+ * Resolves asset inputs strictly within one chain/network. Token metadata is cached per
+ * container, and so is a token's own permanent failure (only a non-retryable
+ * crypto-aio `ASSET_RESOLUTION` error, e.g. for a contract with no usable `decimals`), so a
+ * junk token seen in every scanned block is queried once. Every other failure (a retryable
+ * one of any code, any other provider error, or a foreign error) is dropped from the cache,
+ * and the next resolution queries again: a provider fault must never pin a token.
+ */
+class AssetService {
+    catalogs;
+    #metadata = new Map();
+    constructor(catalogs) {
+        this.catalogs = catalogs;
+    }
+    async resolve(selection, driver, input) {
+        const chain = selection.chain.id;
+        const network = selection.network.id;
+        const catalogs = this.catalogs();
+        if (input === undefined || input === 'native')
+            return catalogs.assets.native(chain, network);
+        if (typeof input === 'string') {
+            if (!(0, asset_1.isAssetId)(input))
+                return catalogs.assets.resolveAlias(chain, network, input);
+            const parsed = (0, asset_1.parseAssetId)(input);
+            if (parsed.chain !== chain || parsed.network !== network) {
+                throw new error_1.ValidationError('ASSET_RESOLUTION', `asset '${input}' belongs to ${parsed.chain}:${parsed.network}, not ${chain}:${network}`);
+            }
+            return this.resolve(selection, driver, parsed.ref);
+        }
+        const ref = driver.reader.normalizeTokenRef
+            ? driver.reader.normalizeTokenRef(input)
+            : input;
+        const id = (0, asset_1.assetId)(chain, network, ref);
+        const known = catalogs.assets.get(id);
+        if (known)
+            return known;
+        const lookup = driver.reader.getTokenMetadata;
+        if (!selection.capabilities.has('tokens') || !lookup) {
+            throw new error_1.UnsupportedCapabilityError('UNSUPPORTED_CAPABILITY', `chain '${chain}' does not support tokens`);
+        }
+        let pending = this.#metadata.get(id);
+        if (!pending) {
+            pending = lookup.call(driver.reader, ref);
+            this.#metadata.set(id, pending);
+            pending.catch((error) => {
+                if (!(0, error_1.isCryptoAioError)(error, 'ASSET_RESOLUTION') || error.retryable)
+                    this.#metadata.delete(id);
+            });
+        }
+        const metadata = await pending;
+        const problem = (0, asset_1.metadataProblem)(metadata);
+        if (problem)
+            throw new error_1.ValidationError('ASSET_RESOLUTION', `token '${id}' has unusable metadata: ${problem}`);
+        return Object.freeze({
+            id,
+            chain,
+            network,
+            ref,
+            metadata: Object.freeze({ ...metadata }),
+        });
+    }
+}
+exports.AssetService = AssetService;
+//# sourceMappingURL=service.js.map

package/dist/core/assets/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../src/core/assets/service.ts"],"names":[],"mappings":";;;AAEA,2CAIyB;AACzB,0CASwB;AAGxB;;;;;;;GAOG;AACH,MAAa,YAAY;IAGM;IAFpB,SAAS,GAAG,IAAI,GAAG,EAAmC,CAAC;IAEhE,YAA6B,QAAwB;QAAxB,aAAQ,GAAR,QAAQ,CAAgB;IAAG,CAAC;IAEzD,KAAK,CAAC,OAAO,CACX,SAA4B,EAC5B,MAAmB,EACnB,KAAoC;QAEpC,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QACjC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,QAAQ;YAC3C,OAAO,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC,IAAA,iBAAS,EAAC,KAAK,CAAC;gBAAE,OAAO,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YAClF,MAAM,MAAM,GAAG,IAAA,oBAAY,EAAC,KAAK,CAAC,CAAC;YACnC,IAAI,MAAM,CAAC,KAAK,KAAK,KAAK,IAAI,MAAM,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;gBACzD,MAAM,IAAI,uBAAe,CACvB,kBAAkB,EAClB,UAAU,KAAK,gBAAgB,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,OAAO,SAAS,KAAK,IAAI,OAAO,EAAE,CACzF,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;QACrD,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,iBAAiB;YACzC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,KAAK,CAAC;YACxC,CAAC,CAAC,KAAK,CAAC;QACV,MAAM,EAAE,GAAG,IAAA,eAAO,EAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;QACxC,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtC,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;QACxB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC;QAC9C,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACrD,MAAM,IAAI,kCAA0B,CAClC,wBAAwB,EACxB,UAAU,KAAK,2BAA2B,CAC3C,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YAC1C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;YAChC,OAAO,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBAC/B,IAAI,CAAC,IAAA,wBAAgB,EAAC,KAAK,EAAE,kBAAkB,CAAC,IAAI,KAAK,CAAC,SAAS;oBACjE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC9B,CAAC,CAAC,CAAC;QACL,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC;QAC/B,MAAM,OAAO,GAAG,IAAA,uBAAe,EAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,OAAO;YACT,MAAM,IAAI,uBAAe,CACvB,kBAAkB,EAClB,UAAU,EAAE,4BAA4B,OAAO,EAAE,CAClD,CAAC;QACJ,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,EAAE;YACF,KAAK;YACL,OAAO;YACP,GAAG;YACH,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAC;SACzC,CAAC,CAAC;IACL,CAAC;CACF;AA/DD,oCA+DC","sourcesContent":["import type { ResolvedSelection } from '../config/types';\nimport type { ChainDriver } from '../driver/types';\nimport {\n  UnsupportedCapabilityError,\n  ValidationError,\n  isCryptoAioError,\n} from '../errors/error';\nimport {\n  assetId,\n  isAssetId,\n  metadataProblem,\n  parseAssetId,\n  type AssetId,\n  type AssetInfo,\n  type AssetMetadata,\n  type AssetRef,\n} from '../model/asset';\nimport type { Catalogs } from '../registry/plugin';\n\n/**\n * Resolves asset inputs strictly within one chain/network. Token metadata is cached per\n * container, and so is a token's own permanent failure (only a non-retryable\n * crypto-aio `ASSET_RESOLUTION` error, e.g. for a contract with no usable `decimals`), so a\n * junk token seen in every scanned block is queried once. Every other failure (a retryable\n * one of any code, any other provider error, or a foreign error) is dropped from the cache,\n * and the next resolution queries again: a provider fault must never pin a token.\n */\nexport class AssetService {\n  readonly #metadata = new Map<AssetId, Promise<AssetMetadata>>();\n\n  constructor(private readonly catalogs: () => Catalogs) {}\n\n  async resolve(\n    selection: ResolvedSelection,\n    driver: ChainDriver,\n    input: AssetRef | string | undefined,\n  ): Promise<AssetInfo> {\n    const chain = selection.chain.id;\n    const network = selection.network.id;\n    const catalogs = this.catalogs();\n    if (input === undefined || input === 'native')\n      return catalogs.assets.native(chain, network);\n    if (typeof input === 'string') {\n      if (!isAssetId(input)) return catalogs.assets.resolveAlias(chain, network, input);\n      const parsed = parseAssetId(input);\n      if (parsed.chain !== chain || parsed.network !== network) {\n        throw new ValidationError(\n          'ASSET_RESOLUTION',\n          `asset '${input}' belongs to ${parsed.chain}:${parsed.network}, not ${chain}:${network}`,\n        );\n      }\n      return this.resolve(selection, driver, parsed.ref);\n    }\n    const ref = driver.reader.normalizeTokenRef\n      ? driver.reader.normalizeTokenRef(input)\n      : input;\n    const id = assetId(chain, network, ref);\n    const known = catalogs.assets.get(id);\n    if (known) return known;\n    const lookup = driver.reader.getTokenMetadata;\n    if (!selection.capabilities.has('tokens') || !lookup) {\n      throw new UnsupportedCapabilityError(\n        'UNSUPPORTED_CAPABILITY',\n        `chain '${chain}' does not support tokens`,\n      );\n    }\n    let pending = this.#metadata.get(id);\n    if (!pending) {\n      pending = lookup.call(driver.reader, ref);\n      this.#metadata.set(id, pending);\n      pending.catch((error: unknown) => {\n        if (!isCryptoAioError(error, 'ASSET_RESOLUTION') || error.retryable)\n          this.#metadata.delete(id);\n      });\n    }\n    const metadata = await pending;\n    const problem = metadataProblem(metadata);\n    if (problem)\n      throw new ValidationError(\n        'ASSET_RESOLUTION',\n        `token '${id}' has unusable metadata: ${problem}`,\n      );\n    return Object.freeze({\n      id,\n      chain,\n      network,\n      ref,\n      metadata: Object.freeze({ ...metadata }),\n    });\n  }\n}\n"]}

package/dist/core/blockchain/default-ref.d.ts

@@ -0,0 +1,4 @@
+import type { HandleOptions } from '../config/types';
+import type { Blockchain } from './handle';
+export declare function setDefaultBlockchainFactory(create: (config: HandleOptions) => Blockchain): void;
+export declare function defaultBlockchain(config: HandleOptions): Blockchain;

package/dist/core/blockchain/default-ref.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setDefaultBlockchainFactory = setDefaultBlockchainFactory;
+exports.defaultBlockchain = defaultBlockchain;
+const error_1 = require("../errors/error");
+let factory;
+function setDefaultBlockchainFactory(create) {
+    factory = create;
+}
+function defaultBlockchain(config) {
+    if (!factory) {
+        throw new error_1.ConfigError('CONFIG_INVALID', 'the default container is not initialized; import from the package entry point');
+    }
+    return factory(config);
+}
+//# sourceMappingURL=default-ref.js.map

package/dist/core/blockchain/default-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-ref.js","sourceRoot":"","sources":["../../../src/core/blockchain/default-ref.ts"],"names":[],"mappings":";;AAMA,kEAIC;AAED,8CAQC;AAnBD,2CAA8C;AAG9C,IAAI,OAA4D,CAAC;AAEjE,SAAgB,2BAA2B,CACzC,MAA6C;IAE7C,OAAO,GAAG,MAAM,CAAC;AACnB,CAAC;AAED,SAAgB,iBAAiB,CAAC,MAAqB;IACrD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,mBAAW,CACnB,gBAAgB,EAChB,+EAA+E,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;AACzB,CAAC","sourcesContent":["import type { HandleOptions } from '../config/types';\nimport { ConfigError } from '../errors/error';\nimport type { Blockchain } from './handle';\n\nlet factory: ((config: HandleOptions) => Blockchain) | undefined;\n\nexport function setDefaultBlockchainFactory(\n  create: (config: HandleOptions) => Blockchain,\n): void {\n  factory = create;\n}\n\nexport function defaultBlockchain(config: HandleOptions): Blockchain {\n  if (!factory) {\n    throw new ConfigError(\n      'CONFIG_INVALID',\n      'the default container is not initialized; import from the package entry point',\n    );\n  }\n  return factory(config);\n}\n"]}