@anywalletkit/wallet-btc 0.2.5 → 0.3.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { B as BtcClient, U as Utxo, a as BlockbookTx, b as BtcConfig, c as BtcTxDescription, d as BtcAddressType, e as BtcNetwork, f as BtcSpend, g as BtcTransferOptions, h as BtcMaxSpendableResult, i as BtcReceipt, j as BtcTransaction } from './history-B5fmsCjZ.cjs';
-export { k as BlockbookAddressPage, l as BlockbookClient, m as BlockbookTxDetails, n as BlockbookVin, o as BlockbookVout, p as BtcChainTx, q as BtcClientConfig, r as BtcHistoryCursor, s as BtcHistoryOptions, t as BtcHistoryPage, u as BtcHistoryRaw, v as BtcHistorySource, w as BtcTxInputDescription, x as BtcTxOutputDescription, y as BtcWarning, C as CAIP2_GENESIS, H as HistoryUnavailableError, z as btcExplorerTxUrl, A as createBtcHistory, D as decodeHistoryCursor, E as encodeHistoryCursor, F as mapBlockbookTx, G as unconfirmedOutgoing } from './history-B5fmsCjZ.cjs';
+import { B as BtcClient, U as Utxo, a as BlockbookTx, b as BtcConfig, c as BtcTxDescription, d as BtcAddressType, e as BtcNetwork, f as BtcSpend, g as BtcTransferOptions, h as BtcMaxSpendableResult, i as BtcReceipt, j as BtcTransaction } from './history-CasPAf7l.cjs';
+export { k as BlockbookAddressPage, l as BlockbookAddressTx, m as BlockbookClient, n as BlockbookTxDetails, o as BlockbookVin, p as BlockbookVout, q as BtcChainTx, r as BtcClientConfig, s as BtcHistoryCursor, t as BtcHistoryOptions, u as BtcHistoryPage, v as BtcHistoryRaw, w as BtcHistorySource, x as BtcTxInputDescription, y as BtcTxOutputDescription, z as BtcWarning, C as CAIP2_GENESIS, H as HistoryUnavailableError, A as btcExplorerTxUrl, D as createBtcHistory, E as decodeHistoryCursor, F as encodeHistoryCursor, G as mapBlockbookTx, I as unconfirmedOutgoing } from './history-CasPAf7l.cjs';
 import { Signer, IWalletAccountReadOnly, IWalletAccount, WriteOptions, TransferResult, WalletManager, FeeRates } from '@anywalletkit/core';
 import { Transaction } from '@scure/btc-signer';
 import { BTC_NETWORK } from '@scure/btc-signer/utils.js';
@@ -30,6 +30,24 @@ declare class TooManyInputsError extends Error {
 declare class UnsupportedAddressTypeError extends Error {
     constructor(message: string);
 }
+/**
+ * The transaction was handed to the network but no definitive answer came back (no response, a
+ * timeout, a 5xx, an unreadable body): it MAY be in the mempool. Do not build another spend of the
+ * same coins — watch `hash`, the txid computed before sending (round 3, M12).
+ */
+declare class BroadcastUnknownError extends Error {
+    /** Always true: the transaction may be on its way. */
+    readonly maybeSent = true;
+    /** The transaction id (hex). */
+    readonly hash: string;
+    constructor(hash: string, cause: unknown);
+}
+
+/**
+ * An endpoint answered with a refusal (HTTP 4xx other than 408, or an error body): nothing was
+ * taken. A thrown fetch, a timeout, a 5xx or a body that cannot be read may have been.
+ */
+declare function isAnsweredRefusal(e: unknown): boolean;
 
 /**
  * Esplora REST transport — the API served by mempool.space (`https://mempool.space/api`)
@@ -367,6 +385,12 @@ declare class WalletAccountBtc extends WalletAccountReadOnlyBtc implements IWall
     sendTransaction(tx: BtcTransaction, options?: WriteOptions): Promise<TransferResult>;
     /** Native BTC only (`token` is rejected). Subject to `transferMaxFee`. */
     transfer(o: BtcTransferOptions, writeOptions?: WriteOptions): Promise<TransferResult>;
+    /**
+     * Send once through the client. Only a node's refusal means nothing went out; "already in the
+     * mempool / block chain" means an earlier attempt delivered it; anything else may have landed and
+     * is a {@link BroadcastUnknownError} with the txid computed before sending (round 3, M12).
+     */
+    private broadcast;
     /** The same address as a {@link WalletAccountReadOnlyBtc}. */
     toReadOnlyAccount(): IWalletAccountReadOnly;
     dispose(): void;
@@ -402,4 +426,4 @@ declare class WalletManagerBtc extends WalletManager<WalletAccountBtc, BtcConfig
     getFeeRates(): Promise<FeeRates>;
 }
 
-export { BlockbookTx, BtcAddressType, BtcClient, BtcConfig, BtcMaxSpendableResult, BtcNetwork, BtcReceipt, BtcSpend, BtcTransaction, BtcTransferOptions, BtcTxDescription, type CoinSelectOptions, type CoinSelection, DEFAULT_MAX_FEE_RATE, DUST_LIMIT_P2TR, DUST_LIMIT_P2WPKH, type DecodedAddress, type DescribeContext, EsploraClient, FINAL_SEQUENCE, INPUT_WEIGHT, MAX_UTXO_INPUTS, RBF_SEQUENCE, REGTEST_NETWORK, type ScriptKind, type SegwitType, type SelectionTarget, type SpendPlan, TooManyInputsError, type UnsafeTransactionCode, UnsafeTransactionError, UnsupportedAddressTypeError, Utxo, WalletAccountBtc, WalletAccountReadOnlyBtc, WalletManagerBtc, addressFor, addressFromPublicKey, addressFromScript, assertSafe, coinType, createClient, decodeAddress, WalletManagerBtc as default, describeTransaction, dustLimit, encodeMessageSignature, estimateVsize, magicHash, networkParams, outputVBytes, parseRawTransaction, purposeFor, recoverMessagePublicKey, scriptKind, selectAll, selectCoins, signMessage, signMessageWith, spendableUtxos };
+export { BlockbookTx, BroadcastUnknownError, BtcAddressType, BtcClient, BtcConfig, BtcMaxSpendableResult, BtcNetwork, BtcReceipt, BtcSpend, BtcTransaction, BtcTransferOptions, BtcTxDescription, type Built, type CoinSelectOptions, type CoinSelection, DEFAULT_MAX_FEE_RATE, DUST_LIMIT_P2TR, DUST_LIMIT_P2WPKH, type DecodedAddress, type DescribeContext, EsploraClient, FINAL_SEQUENCE, INPUT_WEIGHT, MAX_UTXO_INPUTS, RBF_SEQUENCE, REGTEST_NETWORK, type ScriptKind, type SegwitType, type SelectionTarget, type SpendPlan, TooManyInputsError, type UnsafeTransactionCode, UnsafeTransactionError, UnsupportedAddressTypeError, Utxo, WalletAccountBtc, WalletAccountReadOnlyBtc, WalletManagerBtc, addressFor, addressFromPublicKey, addressFromScript, assertSafe, coinType, createClient, decodeAddress, WalletManagerBtc as default, describeTransaction, dustLimit, encodeMessageSignature, estimateVsize, isAnsweredRefusal, magicHash, networkParams, outputVBytes, parseRawTransaction, purposeFor, recoverMessagePublicKey, scriptKind, selectAll, selectCoins, signMessage, signMessageWith, spendableUtxos };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BtcClient, U as Utxo, a as BlockbookTx, b as BtcConfig, c as BtcTxDescription, d as BtcAddressType, e as BtcNetwork, f as BtcSpend, g as BtcTransferOptions, h as BtcMaxSpendableResult, i as BtcReceipt, j as BtcTransaction } from './history-B5fmsCjZ.js';
-export { k as BlockbookAddressPage, l as BlockbookClient, m as BlockbookTxDetails, n as BlockbookVin, o as BlockbookVout, p as BtcChainTx, q as BtcClientConfig, r as BtcHistoryCursor, s as BtcHistoryOptions, t as BtcHistoryPage, u as BtcHistoryRaw, v as BtcHistorySource, w as BtcTxInputDescription, x as BtcTxOutputDescription, y as BtcWarning, C as CAIP2_GENESIS, H as HistoryUnavailableError, z as btcExplorerTxUrl, A as createBtcHistory, D as decodeHistoryCursor, E as encodeHistoryCursor, F as mapBlockbookTx, G as unconfirmedOutgoing } from './history-B5fmsCjZ.js';
+import { B as BtcClient, U as Utxo, a as BlockbookTx, b as BtcConfig, c as BtcTxDescription, d as BtcAddressType, e as BtcNetwork, f as BtcSpend, g as BtcTransferOptions, h as BtcMaxSpendableResult, i as BtcReceipt, j as BtcTransaction } from './history-CasPAf7l.js';
+export { k as BlockbookAddressPage, l as BlockbookAddressTx, m as BlockbookClient, n as BlockbookTxDetails, o as BlockbookVin, p as BlockbookVout, q as BtcChainTx, r as BtcClientConfig, s as BtcHistoryCursor, t as BtcHistoryOptions, u as BtcHistoryPage, v as BtcHistoryRaw, w as BtcHistorySource, x as BtcTxInputDescription, y as BtcTxOutputDescription, z as BtcWarning, C as CAIP2_GENESIS, H as HistoryUnavailableError, A as btcExplorerTxUrl, D as createBtcHistory, E as decodeHistoryCursor, F as encodeHistoryCursor, G as mapBlockbookTx, I as unconfirmedOutgoing } from './history-CasPAf7l.js';
 import { Signer, IWalletAccountReadOnly, IWalletAccount, WriteOptions, TransferResult, WalletManager, FeeRates } from '@anywalletkit/core';
 import { Transaction } from '@scure/btc-signer';
 import { BTC_NETWORK } from '@scure/btc-signer/utils.js';
@@ -30,6 +30,24 @@ declare class TooManyInputsError extends Error {
 declare class UnsupportedAddressTypeError extends Error {
     constructor(message: string);
 }
+/**
+ * The transaction was handed to the network but no definitive answer came back (no response, a
+ * timeout, a 5xx, an unreadable body): it MAY be in the mempool. Do not build another spend of the
+ * same coins — watch `hash`, the txid computed before sending (round 3, M12).
+ */
+declare class BroadcastUnknownError extends Error {
+    /** Always true: the transaction may be on its way. */
+    readonly maybeSent = true;
+    /** The transaction id (hex). */
+    readonly hash: string;
+    constructor(hash: string, cause: unknown);
+}
+
+/**
+ * An endpoint answered with a refusal (HTTP 4xx other than 408, or an error body): nothing was
+ * taken. A thrown fetch, a timeout, a 5xx or a body that cannot be read may have been.
+ */
+declare function isAnsweredRefusal(e: unknown): boolean;
 
 /**
  * Esplora REST transport — the API served by mempool.space (`https://mempool.space/api`)
@@ -367,6 +385,12 @@ declare class WalletAccountBtc extends WalletAccountReadOnlyBtc implements IWall
     sendTransaction(tx: BtcTransaction, options?: WriteOptions): Promise<TransferResult>;
     /** Native BTC only (`token` is rejected). Subject to `transferMaxFee`. */
     transfer(o: BtcTransferOptions, writeOptions?: WriteOptions): Promise<TransferResult>;
+    /**
+     * Send once through the client. Only a node's refusal means nothing went out; "already in the
+     * mempool / block chain" means an earlier attempt delivered it; anything else may have landed and
+     * is a {@link BroadcastUnknownError} with the txid computed before sending (round 3, M12).
+     */
+    private broadcast;
     /** The same address as a {@link WalletAccountReadOnlyBtc}. */
     toReadOnlyAccount(): IWalletAccountReadOnly;
     dispose(): void;
@@ -402,4 +426,4 @@ declare class WalletManagerBtc extends WalletManager<WalletAccountBtc, BtcConfig
     getFeeRates(): Promise<FeeRates>;
 }
 
-export { BlockbookTx, BtcAddressType, BtcClient, BtcConfig, BtcMaxSpendableResult, BtcNetwork, BtcReceipt, BtcSpend, BtcTransaction, BtcTransferOptions, BtcTxDescription, type CoinSelectOptions, type CoinSelection, DEFAULT_MAX_FEE_RATE, DUST_LIMIT_P2TR, DUST_LIMIT_P2WPKH, type DecodedAddress, type DescribeContext, EsploraClient, FINAL_SEQUENCE, INPUT_WEIGHT, MAX_UTXO_INPUTS, RBF_SEQUENCE, REGTEST_NETWORK, type ScriptKind, type SegwitType, type SelectionTarget, type SpendPlan, TooManyInputsError, type UnsafeTransactionCode, UnsafeTransactionError, UnsupportedAddressTypeError, Utxo, WalletAccountBtc, WalletAccountReadOnlyBtc, WalletManagerBtc, addressFor, addressFromPublicKey, addressFromScript, assertSafe, coinType, createClient, decodeAddress, WalletManagerBtc as default, describeTransaction, dustLimit, encodeMessageSignature, estimateVsize, magicHash, networkParams, outputVBytes, parseRawTransaction, purposeFor, recoverMessagePublicKey, scriptKind, selectAll, selectCoins, signMessage, signMessageWith, spendableUtxos };
+export { BlockbookTx, BroadcastUnknownError, BtcAddressType, BtcClient, BtcConfig, BtcMaxSpendableResult, BtcNetwork, BtcReceipt, BtcSpend, BtcTransaction, BtcTransferOptions, BtcTxDescription, type Built, type CoinSelectOptions, type CoinSelection, DEFAULT_MAX_FEE_RATE, DUST_LIMIT_P2TR, DUST_LIMIT_P2WPKH, type DecodedAddress, type DescribeContext, EsploraClient, FINAL_SEQUENCE, INPUT_WEIGHT, MAX_UTXO_INPUTS, RBF_SEQUENCE, REGTEST_NETWORK, type ScriptKind, type SegwitType, type SelectionTarget, type SpendPlan, TooManyInputsError, type UnsafeTransactionCode, UnsafeTransactionError, UnsupportedAddressTypeError, Utxo, WalletAccountBtc, WalletAccountReadOnlyBtc, WalletManagerBtc, addressFor, addressFromPublicKey, addressFromScript, assertSafe, coinType, createClient, decodeAddress, WalletManagerBtc as default, describeTransaction, dustLimit, encodeMessageSignature, estimateVsize, isAnsweredRefusal, magicHash, networkParams, outputVBytes, parseRawTransaction, purposeFor, recoverMessagePublicKey, scriptKind, selectAll, selectCoins, signMessage, signMessageWith, spendableUtxos };

package/dist/index.js

@@ -8,11 +8,15 @@ import {
   decodeCursor,
   encodeCursor,
   fetchWithTimeout,
+  isAlreadyKnown,
+  isAnsweredRefusal,
   isHex64,
   isRecord,
   mapBlockbookTx,
+  refusal,
+  refusedStatus,
   unconfirmedOutgoing
-} from "./chunk-4WUAN3DC.js";
+} from "./chunk-SIR2SRK2.js";
 
 // src/errors.ts
 import { InsufficientFundsError, NetworkError, SignerError } from "@anywalletkit/core";
@@ -38,6 +42,17 @@ var UnsupportedAddressTypeError = class extends Error {
     this.name = "UnsupportedAddressTypeError";
   }
 };
+var BroadcastUnknownError = class extends Error {
+  /** Always true: the transaction may be on its way. */
+  maybeSent = true;
+  /** The transaction id (hex). */
+  hash;
+  constructor(hash, cause) {
+    super(`Broadcast outcome unknown for ${hash}: ${cause instanceof Error ? cause.message.slice(0, 200) : String(cause).slice(0, 200)}`, { cause });
+    this.name = "BroadcastUnknownError";
+    this.hash = hash;
+  }
+};
 
 // src/esplora.ts
 import { NetworkError as NetworkError2 } from "@anywalletkit/core";
@@ -60,7 +75,11 @@ var EsploraClient = class {
   async request(path, init) {
     const url = `${this.base}${path}`;
     const res = await fetchWithTimeout(this.fetchFn, url, init, this.timeoutMs, this.base);
-    if (!res.ok) throw new NetworkError2(`Esplora request failed: ${res.status} ${res.statusText} (${url})`, { provider: this.base });
+    if (!res.ok) {
+      const reason = refusedStatus(res.status) ? (await res.text().catch(() => "")).slice(0, 200) : "";
+      const err = new NetworkError2(`Esplora request failed: ${res.status} ${res.statusText} (${url})${reason ? `: ${reason}` : ""}`, { provider: this.base });
+      throw refusedStatus(res.status) ? refusal(err) : err;
+    }
     return res;
   }
   async json(path, check) {
@@ -165,6 +184,7 @@ function createClient(config) {
   const attempts = list.length + (config.retries ?? 3);
   const call = (method) => async (...args) => {
     let last;
+    let answered = true;
     for (let i = 0; i < attempts; i++) {
       const c = list[i % list.length];
       const fn = c[method];
@@ -173,9 +193,11 @@ function createClient(config) {
         return await fn.apply(c, args);
       } catch (e) {
         last = e;
+        answered &&= isAnsweredRefusal(e);
       }
     }
-    throw new NetworkError3(`All BTC clients failed for ${method}`, { cause: last });
+    const err = new NetworkError3(`All BTC clients failed for ${method}`, { cause: last });
+    throw answered && last !== void 0 ? refusal(err) : err;
   };
   const out = {};
   for (const m of METHODS) out[m] = call(m);
@@ -396,11 +418,28 @@ function describeTransaction(tx, inputValues, ctx) {
   });
   const outputs = [];
   const warnings = /* @__PURE__ */ new Set();
+  const scriptOf = (address) => {
+    try {
+      return hex.encode(decodeAddress(address, ctx.network).script);
+    } catch {
+      return void 0;
+    }
+  };
+  const ownScript = scriptOf(ctx.ownAddress);
+  const intendedScript = ctx.intended ? scriptOf(ctx.intended.to) : void 0;
+  let recipientSeen = false;
   for (let i = 0; i < tx.outputsLength; i++) {
     const out = tx.getOutput(i);
     const value = out.amount ?? 0n;
     const address = tx.getOutputAddress(i, ctx.network);
-    const role = address !== void 0 && address === ctx.ownAddress ? "change" : ctx.intended === void 0 ? "recipient" : address !== void 0 && address === ctx.intended.to && value === ctx.intended.value ? "recipient" : "unknown";
+    const script = out.script ? hex.encode(out.script) : void 0;
+    const mine = script !== void 0 && script === ownScript;
+    let role;
+    if (ctx.intended === void 0) role = mine ? "change" : "recipient";
+    else if (!recipientSeen && script !== void 0 && script === intendedScript && value === ctx.intended.value) {
+      role = "recipient";
+      recipientSeen = true;
+    } else role = mine ? "change" : "unknown";
     if (out.script && value < dustLimit(scriptKind(out.script))) warnings.add("dust-output");
     outputs.push({ address, value, role });
   }
@@ -831,8 +870,7 @@ var WalletAccountBtc = class _WalletAccountBtc extends WalletAccountReadOnlyBtc
       fee = built.fee;
     }
     this.checkMax(fee, feeLimit(this._config.transactionMaxFee, options), "transaction");
-    const txid = await client.broadcast(rawHex);
-    return { hash: txid || hash, fee };
+    return { hash: await this.broadcast(client, rawHex, hash), fee };
   }
   /** Native BTC only (`token` is rejected). Subject to `transferMaxFee`. */
   async transfer(o, writeOptions = {}) {
@@ -841,8 +879,21 @@ var WalletAccountBtc = class _WalletAccountBtc extends WalletAccountReadOnlyBtc
     const client = this.requireClient("transfer");
     const built = await this.signSpend({ to: o.recipient, value: o.amount });
     this.checkMax(built.fee, feeLimit(this._config.transferMaxFee, writeOptions), "transfer");
-    const txid = await client.broadcast(built.tx.hex);
-    return { hash: txid || built.tx.id, fee: built.fee };
+    return { hash: await this.broadcast(client, built.tx.hex, built.tx.id), fee: built.fee };
+  }
+  /**
+   * Send once through the client. Only a node's refusal means nothing went out; "already in the
+   * mempool / block chain" means an earlier attempt delivered it; anything else may have landed and
+   * is a {@link BroadcastUnknownError} with the txid computed before sending (round 3, M12).
+   */
+  async broadcast(client, rawHex, txid) {
+    try {
+      return await client.broadcast(rawHex) || txid;
+    } catch (e) {
+      if (isAlreadyKnown(e)) return txid;
+      if (isAnsweredRefusal(e)) throw e;
+      throw new BroadcastUnknownError(txid, e);
+    }
   }
   /** The same address as a {@link WalletAccountReadOnlyBtc}. */
   toReadOnlyAccount() {
@@ -916,6 +967,7 @@ var WalletManagerBtc = class extends WalletManager {
 };
 export {
   BlockbookClient,
+  BroadcastUnknownError,
   CAIP2_GENESIS,
   DEFAULT_MAX_FEE_RATE,
   DUST_LIMIT_P2TR,
@@ -949,6 +1001,7 @@ export {
   encodeCursor as encodeHistoryCursor,
   encodeMessageSignature,
   estimateVsize,
+  isAnsweredRefusal,
   magicHash,
   mapBlockbookTx,
   networkParams,