@anywalletkit/wallet-btc 0.2.4 → 0.3.0

package/dist/index.d.cts

@@ -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`)
@@ -335,13 +353,13 @@ declare class WalletAccountBtc extends WalletAccountReadOnlyBtc implements IWall
      */
     private signInputs;
     private ctx;
-    private buildAndSign;
+    private signPlan;
     /**
      * Plan → sign → measure. The plan's fee assumes 72-byte DER signatures; if the
      * signed vsize somehow needs more, the difference comes out of change (never the
      * recipient) and the tx is re-signed once.
      */
-    protected buildSignedTransaction(spend: BtcSpend): Promise<Built>;
+    protected signSpend(spend: BtcSpend): Promise<Built>;
     private checkMax;
     /**
      * BIP-143 (p2wpkh) commits each input's signature to that input's CLAIMED amount
@@ -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 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

@@ -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`)
@@ -335,13 +353,13 @@ declare class WalletAccountBtc extends WalletAccountReadOnlyBtc implements IWall
      */
     private signInputs;
     private ctx;
-    private buildAndSign;
+    private signPlan;
     /**
      * Plan → sign → measure. The plan's fee assumes 72-byte DER signatures; if the
      * signed vsize somehow needs more, the difference comes out of change (never the
      * recipient) and the tx is re-signed once.
      */
-    protected buildSignedTransaction(spend: BtcSpend): Promise<Built>;
+    protected signSpend(spend: BtcSpend): Promise<Built>;
     private checkMax;
     /**
      * BIP-143 (p2wpkh) commits each input's signature to that input's CLAIMED amount
@@ -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 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-TZNOUBSP.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 });
   }
@@ -687,7 +726,7 @@ var WalletAccountBtc = class _WalletAccountBtc extends WalletAccountReadOnlyBtc
   ctx(intended) {
     return { network: this._network, ownAddress: this.address, intended, maxFeeRate: this.maxFeeRate };
   }
-  async buildAndSign(plan, to, recipientValue, change, lockTime, rbf) {
+  async signPlan(plan, to, recipientValue, change, lockTime, rbf) {
     const spend = spendInfo(this.publicKey, this._network, this.addressType);
     const tx = new Transaction2({ lockTime });
     const sequence = rbf ? RBF_SEQUENCE : FINAL_SEQUENCE;
@@ -705,7 +744,7 @@ var WalletAccountBtc = class _WalletAccountBtc extends WalletAccountReadOnlyBtc
    * signed vsize somehow needs more, the difference comes out of change (never the
    * recipient) and the tx is re-signed once.
    */
-  async buildSignedTransaction(spend) {
+  async signSpend(spend) {
     this.live();
     const plan = await this.planSpend(spend);
     await this.verifyPrevouts(plan.utxos);
@@ -713,7 +752,7 @@ var WalletAccountBtc = class _WalletAccountBtc extends WalletAccountReadOnlyBtc
     const rbf = spend.rbf ?? this._config.rbf ?? true;
     let change = plan.change;
     let fee = plan.fee;
-    let tx = await this.buildAndSign(plan, spend.to, plan.amount, change, lockTime, rbf);
+    let tx = await this.signPlan(plan, spend.to, plan.amount, change, lockTime, rbf);
     const required = BigInt(tx.vsize) * plan.feeRate;
     if (required > fee) {
       const delta = required - fee;
@@ -726,7 +765,7 @@ var WalletAccountBtc = class _WalletAccountBtc extends WalletAccountReadOnlyBtc
         fee = plan.fee + plan.change;
         change = 0n;
       } else fee = required;
-      tx = await this.buildAndSign(plan, spend.to, plan.amount, change, lockTime, rbf);
+      tx = await this.signPlan(plan, spend.to, plan.amount, change, lockTime, rbf);
       if (BigInt(tx.vsize) * plan.feeRate > fee) throw new Error("Fee shortfall after output rebalance.");
     }
     const ctx = this.ctx({ to: spend.to, value: plan.amount });
@@ -797,7 +836,7 @@ var WalletAccountBtc = class _WalletAccountBtc extends WalletAccountReadOnlyBtc
   /** "What you sign": the fully resolved spend (signed, NOT broadcast) or a caller's raw hex. */
   async describeTransaction(tx) {
     if (typeof tx === "string") return (await this.describeRaw(tx)).desc;
-    return (await this.buildSignedTransaction(tx)).desc;
+    return (await this.signSpend(tx)).desc;
   }
   /** Sign without broadcasting. Returns the raw transaction hex. Raw hex input gets the checks `sendTransaction` runs (prevouts through the client) and is returned unchanged, never re-signed. */
   async signTransaction(tx, options = {}) {
@@ -807,7 +846,7 @@ var WalletAccountBtc = class _WalletAccountBtc extends WalletAccountReadOnlyBtc
       this.checkMax(desc.fee, feeLimit(this._config.transactionMaxFee, options), "transaction");
       return tx;
     }
-    const { tx: built, fee } = await this.buildSignedTransaction(tx);
+    const { tx: built, fee } = await this.signSpend(tx);
     this.checkMax(fee, feeLimit(this._config.transactionMaxFee, options), "transaction");
     return built.hex;
   }
@@ -825,24 +864,36 @@ var WalletAccountBtc = class _WalletAccountBtc extends WalletAccountReadOnlyBtc
       hash = parsed.id;
       fee = desc.fee;
     } else {
-      const built = await this.buildSignedTransaction(tx);
+      const built = await this.signSpend(tx);
       rawHex = built.tx.hex;
       hash = built.tx.id;
       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 = {}) {
     if (o.token) throw new Error("Tokens are not supported on the bitcoin blockchain.");
     this.live();
     const client = this.requireClient("transfer");
-    const built = await this.buildSignedTransaction({ to: o.recipient, value: o.amount });
+    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,