@aibtc/mcp-server 1.43.0 → 1.45.0

package/dist/transactions/builder.js

@@ -3,113 +3,63 @@ import { hexToBytes } from "@stacks/common";
 import { getStacksNetwork, getApiBaseUrl } from "../config/networks.js";
 import { getHiroApi } from "../services/hiro-api.js";
 import { resolveDefaultFee } from "../utils/fee.js";
+import { getTrackedNonce, recordNonceUsed, resetTrackedNonce, reconcileWithChain, } from "../services/nonce-tracker.js";
 // ---------------------------------------------------------------------------
-// Pending nonce tracking (fixes back-to-back tx nonce collision, issue #326)
+// Pending nonce tracking (unified via SharedNonceTracker, issue #413)
+//
+// All nonce state is now managed by src/services/nonce-tracker.ts which
+// persists to ~/.aibtc/nonce-state.json. This module delegates to the tracker
+// and keeps the same public API surface for backward compatibility.
 // ---------------------------------------------------------------------------
-/**
- * How long a locally-tracked pending nonce is considered fresh.
- * If no new transaction has been broadcast within this window the counter is
- * stale (the tx likely confirmed or was dropped) and we fall back to the
- * network value on the next call.
- */
-const STALE_NONCE_MS = 10 * 60 * 1000; // 10 minutes
-/**
- * Maximum number of addresses tracked simultaneously in pendingNonces and
- * pendingNonceTimestamps. When this limit is reached the oldest entry (by
- * insertion order) is evicted before a new one is added. This prevents
- * unbounded memory growth in long-running server processes (issue #336).
- */
-export const MAX_NONCE_ENTRIES = 100;
-/**
- * Evict the oldest entry from a Map when it has reached MAX_NONCE_ENTRIES.
- * JS Maps iterate in insertion order, so map.keys().next() yields the oldest
- * key — no additional bookkeeping is needed.
- */
-function evictOldestIfFull(map) {
-    if (map.size >= MAX_NONCE_ENTRIES) {
-        const oldestKey = map.keys().next().value;
-        if (oldestKey !== undefined) {
-            map.delete(oldestKey);
-        }
-    }
-}
-/**
- * In-memory map of STX address -> next expected nonce for non-sponsored txs.
- * Updated after each successful broadcast so sequential calls don't re-use
- * the same network nonce before the first tx lands in the mempool.
- * Bounded to MAX_NONCE_ENTRIES entries; oldest evicted on overflow (issue #336).
- */
-const pendingNonces = new Map();
-/**
- * Tracks when each address last advanced its local nonce counter.
- * Used to detect stale entries: if no transaction was sent within STALE_NONCE_MS
- * the counter is expired and the network value is authoritative again.
- * Bounded to MAX_NONCE_ENTRIES entries; oldest evicted on overflow (issue #336).
- */
-const pendingNonceTimestamps = new Map();
-/**
- * Exported references to the internal nonce Maps for unit testing only.
- * Do not use these outside of test files.
- */
-export const _testingNonceMaps = {
-    pendingNonces,
-    pendingNonceTimestamps,
-    STALE_NONCE_MS,
-};
 /**
  * Reset the pending nonce for an address (called on wallet unlock/lock/switch
  * so the counter re-syncs with the chain on the next transaction).
  */
-export function resetPendingNonce(address) {
-    pendingNonces.delete(address);
-    pendingNonceTimestamps.delete(address);
+export async function resetPendingNonce(address) {
+    await resetTrackedNonce(address);
 }
 /**
  * Force-resync the local pending nonce for an address.
  * Identical to resetPendingNonce but exported under a name that makes the
  * intent clear for the recover_sponsor_nonce tool's resync-local-nonce action.
  */
-export function forceResyncNonce(address) {
-    resetPendingNonce(address);
+export async function forceResyncNonce(address) {
+    await resetPendingNonce(address);
 }
 /**
  * Fetch the next nonce to use for `address`.
  *
  * Algorithm:
- * 1. Fetch `possible_next_nonce` and `detected_missing_nonces` from Hiro.
- * 2. If the local counter exists but is older than STALE_NONCE_MS, discard it
- *    so a stale counter never permanently blocks a recovered wallet.
- * 3. Return max(possible_next_nonce, local_pending) so rapid sequential calls
+ * 1. Check the shared nonce tracker for a locally-tracked next nonce.
+ * 2. Fetch `possible_next_nonce` and `detected_missing_nonces` from Hiro.
+ * 3. Reconcile: if chain advanced past local, update tracker.
+ * 4. Return max(chain_next, local_tracked) so rapid sequential calls
  *    get strictly increasing nonces even before the mempool reflects the first tx.
- * 4. Warn if the network reports missing nonces — gaps below the pending counter
- *    can cause the queue to stall until the gaps are filled.
+ * 5. Warn if the network reports missing nonces.
  */
 async function getNextNonce(address, network) {
-    // Stale-timeout: discard local counter if it hasn't been refreshed recently.
-    const lastAdvanced = pendingNonceTimestamps.get(address);
-    const isStale = lastAdvanced !== undefined && Date.now() - lastAdvanced > STALE_NONCE_MS;
-    if (isStale) {
-        pendingNonces.delete(address);
-        pendingNonceTimestamps.delete(address);
-    }
-    const pending = pendingNonces.get(address) ?? 0n;
+    // Read local tracker state (no network call)
+    const localNext = await getTrackedNonce(address);
     try {
         const hiroApi = getHiroApi(network);
         const nonceInfo = await hiroApi.getNonceInfo(address);
         const networkNext = BigInt(nonceInfo.possible_next_nonce);
+        // Reconcile: if chain advanced past local state, update the tracker
+        await reconcileWithChain(address, nonceInfo.possible_next_nonce);
         // Warn about detected nonce gaps that could stall the queue.
         if (nonceInfo.detected_missing_nonces && nonceInfo.detected_missing_nonces.length > 0) {
             console.warn(`[nonce] detected_missing_nonces for ${address}: [${nonceInfo.detected_missing_nonces.join(", ")}]. ` +
                 `These gaps may stall pending transactions. Use recover_sponsor_nonce with action=fill-gaps to resolve.`);
         }
-        return networkNext > pending ? networkNext : pending;
+        const localNextBig = localNext !== null ? BigInt(localNext) : 0n;
+        return networkNext > localNextBig ? networkNext : localNextBig;
     }
     catch (err) {
         // Fallback: if we have a fresh local counter, use it to keep the queue moving
         // even when Hiro is temporarily unreachable (e.g., between rapid sequential calls).
-        if (pending > 0n) {
-            console.warn(`[nonce] API call failed, using local pending counter (${pending}) for ${address}:`, err);
-            return pending;
+        if (localNext !== null && localNext > 0) {
+            console.warn(`[nonce] API call failed, using local tracked nonce (${localNext}) for ${address}:`, err);
+            return BigInt(localNext);
         }
         throw err;
     }
@@ -118,22 +68,14 @@ async function getNextNonce(address, network) {
  * Record that a transaction with `nonce` was successfully broadcast for
  * `address`, so the next call advances past it.
  *
- * Exported for unit testing. Not part of the public API.
+ * @param txid - Optional transaction ID for the pending log. Pass empty string
+ *               if not available (e.g., legacy callers).
  */
-export function advancePendingNonce(address, nonce) {
-    const next = nonce + 1n;
-    const current = pendingNonces.get(address) ?? 0n;
-    if (next > current) {
-        // Evict oldest entry before inserting a new address to keep maps bounded.
-        // Only evict when this is a new address — updates to existing keys don't
-        // change Map size so no eviction is needed.
-        if (!pendingNonces.has(address)) {
-            evictOldestIfFull(pendingNonces);
-            evictOldestIfFull(pendingNonceTimestamps);
-        }
-        pendingNonces.set(address, next);
-        pendingNonceTimestamps.set(address, Date.now());
-    }
+export function advancePendingNonce(address, nonce, txid = "") {
+    // Delegate to shared tracker (fire-and-forget since callers are sync)
+    recordNonceUsed(address, Number(nonce), txid).catch((err) => {
+        console.error(`[nonce] Failed to record nonce ${nonce} for ${address}:`, err);
+    });
 }
 /**
  * Transfer STX tokens to a recipient
@@ -160,7 +102,7 @@ export async function transferStx(account, recipient, amount, memo, fee) {
     if ("error" in broadcastResponse) {
         throw new Error(`Broadcast failed: ${broadcastResponse.error} - ${broadcastResponse.reason}`);
     }
-    advancePendingNonce(account.address, nonce);
+    advancePendingNonce(account.address, nonce, broadcastResponse.txid);
     return {
         txid: broadcastResponse.txid,
         rawTx: transaction.serialize(),
@@ -193,7 +135,7 @@ export async function callContract(account, options) {
     if ("error" in broadcastResponse) {
         throw new Error(`Broadcast failed: ${broadcastResponse.error} - ${broadcastResponse.reason}`);
     }
-    advancePendingNonce(account.address, nonce);
+    advancePendingNonce(account.address, nonce, broadcastResponse.txid);
     return {
         txid: broadcastResponse.txid,
         rawTx: transaction.serialize(),
@@ -222,7 +164,7 @@ export async function deployContract(account, options) {
     if ("error" in broadcastResponse) {
         throw new Error(`Broadcast failed: ${broadcastResponse.error} - ${broadcastResponse.reason}`);
     }
-    advancePendingNonce(account.address, nonce);
+    advancePendingNonce(account.address, nonce, broadcastResponse.txid);
     return {
         txid: broadcastResponse.txid,
         rawTx: transaction.serialize(),

package/dist/transactions/builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/transactions/builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/transactions/builder.ts"],"names":[],"mappings":"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"}

package/dist/transactions/sponsor-builder.d.ts

@@ -13,24 +13,18 @@ export interface SponsorRelayResponse {
     retryAfter?: number;
 }
 /**
- * High-level helper: build a sponsored contract call, submit to relay, and
- * return a TransferResult. Resolves the API key and handles relay errors.
- *
- * This is the primary entry point for services that need sponsored contract calls.
+ * Build and submit a sponsored contract call via the relay.
+ * Falls back to direct submission (sender pays fee) when the relay is unavailable.
  */
 export declare function sponsoredContractCall(account: Account, options: ContractCallOptions, network: Network): Promise<TransferResult>;
 /**
- * High-level helper: build a sponsored STX transfer, submit to relay, and
- * return a TransferResult. Resolves the API key and handles relay errors.
- *
- * This is the primary entry point for services that need sponsored STX transfers.
+ * Build and submit a sponsored STX transfer via the relay.
+ * Falls back to direct submission (sender pays fee) when the relay is unavailable.
  */
 export declare function sponsoredStxTransfer(account: Account, recipient: string, amount: bigint, memo: string | undefined, network: Network): Promise<TransferResult>;
 /**
- * High-level helper: build a sponsored contract deploy, submit to relay, and
- * return a TransferResult. Resolves the API key and handles relay errors.
- *
- * This is the primary entry point for services that need sponsored contract deployments.
+ * Build and submit a sponsored contract deploy via the relay.
+ * Falls back to direct submission (sender pays fee) when the relay is unavailable.
  */
 export declare function sponsoredContractDeploy(account: Account, options: ContractDeployOptions, network: Network): Promise<TransferResult>;
 //# sourceMappingURL=sponsor-builder.d.ts.map

package/dist/transactions/sponsor-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sponsor-builder.d.ts","sourceRoot":"","sources":["../../src/transactions/sponsor-builder.ts"],"names":[],"mappings":"AAMA,OAAO,EAAoB,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEvE,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAExG,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8BD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,cAAc,CAAC,CAyBzB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,cAAc,CAAC,CAsBzB;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,cAAc,CAAC,CAqBzB"}
+{"version":3,"file":"sponsor-builder.d.ts","sourceRoot":"","sources":["../../src/transactions/sponsor-builder.ts"],"names":[],"mappings":"AAMA,OAAO,EAAoB,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEvE,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAwDxG,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8DD;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,cAAc,CAAC,CAiBzB;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,cAAc,CAAC,CAczB;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,cAAc,CAAC,CAazB"}

package/dist/transactions/sponsor-builder.js

@@ -1,6 +1,51 @@
 import { makeSTXTokenTransfer, makeContractCall, makeContractDeploy, PostConditionMode, } from "@stacks/transactions";
 import { getStacksNetwork } from "../config/networks.js";
-import { getSponsorRelayUrl, getSponsorApiKey } from "../config/sponsor.js";
+import { getSponsorRelayUrl, getSponsorApiKey, isFallbackEnabled } from "../config/sponsor.js";
+import { callContract, transferStx, deployContract } from "./builder.js";
+import { recordNonceUsed } from "../services/nonce-tracker.js";
+import { isRelayHealthy } from "../utils/relay-health.js";
+/**
+ * Relay-side error codes and keywords that indicate a nonce conflict on the
+ * relay, not a user-side error. When these are present the tx itself is valid
+ * and a direct fallback makes sense.
+ */
+const NONCE_FAULT_PATTERNS = [
+    "ConflictingNonceInMempool",
+    "TooMuchChaining",
+    "BadNonce",
+    "nonce",
+];
+/**
+ * Returns true when a failed relay response is caused by a relay-side nonce
+ * problem rather than a user-side error (bad args, insufficient balance, etc).
+ */
+function isRelayNonceFault(response) {
+    const code = response.code ?? "";
+    const error = response.error ?? "";
+    const details = response.details ?? "";
+    const haystack = `${code} ${error} ${details}`.toLowerCase();
+    return NONCE_FAULT_PATTERNS.some((p) => haystack.includes(p.toLowerCase()));
+}
+/**
+ * Decide whether to fall back to direct submission for a relay failure.
+ * Returns { shouldFallback: true, reason } or { shouldFallback: false }.
+ */
+async function evaluateFallback(response, network) {
+    if (!isFallbackEnabled()) {
+        return { shouldFallback: false };
+    }
+    if (isRelayNonceFault(response)) {
+        return {
+            shouldFallback: true,
+            reason: `relay nonce error: ${response.code ?? response.error}`,
+        };
+    }
+    const healthy = await isRelayHealthy(network);
+    if (!healthy) {
+        return { shouldFallback: true, reason: "relay unhealthy" };
+    }
+    return { shouldFallback: false };
+}
 /**
  * Format a failed SponsorRelayResponse into an error message
  */
@@ -26,81 +71,78 @@ function resolveSponsorApiKey(account) {
     return apiKey;
 }
 /**
- * High-level helper: build a sponsored contract call, submit to relay, and
- * return a TransferResult. Resolves the API key and handles relay errors.
+ * Submit a sponsored transaction to the relay and handle the response.
  *
- * This is the primary entry point for services that need sponsored contract calls.
+ * Shared logic for all three sponsored helpers (contract call, STX transfer,
+ * contract deploy). Each caller builds its own transaction and provides a
+ * fallback function for direct submission when the relay is unavailable.
  */
-export async function sponsoredContractCall(account, options, network) {
+async function submitSponsoredTransaction(account, transaction, network, directFallback) {
     const apiKey = resolveSponsorApiKey(account);
-    const networkName = getStacksNetwork(network);
+    const senderNonce = Number(transaction.auth.spendingCondition.nonce);
+    const serializedTx = transaction.serialize();
+    const response = await submitToSponsorRelay(serializedTx, network, apiKey);
+    if (!response.success) {
+        const { shouldFallback, reason } = await evaluateFallback(response, network);
+        if (shouldFallback) {
+            console.warn(`[sponsor] Relay unavailable or nonce error (${reason}), falling back to direct submission (sender pays fee)`);
+            const result = await directFallback();
+            return { ...result, fallback: true, fallbackReason: reason };
+        }
+        throw new Error(formatRelayError(response));
+    }
+    await recordNonceUsed(account.address, senderNonce, response.txid);
+    return { txid: response.txid, rawTx: serializedTx };
+}
+/**
+ * Build and submit a sponsored contract call via the relay.
+ * Falls back to direct submission (sender pays fee) when the relay is unavailable.
+ */
+export async function sponsoredContractCall(account, options, network) {
     const transaction = await makeContractCall({
         contractAddress: options.contractAddress,
         contractName: options.contractName,
         functionName: options.functionName,
         functionArgs: options.functionArgs,
         senderKey: account.privateKey,
-        network: networkName,
+        network: getStacksNetwork(network),
         postConditionMode: options.postConditionMode || PostConditionMode.Deny,
         postConditions: options.postConditions || [],
         sponsored: true,
         fee: 0n,
     });
-    const serializedTx = transaction.serialize();
-    const response = await submitToSponsorRelay(serializedTx, network, apiKey);
-    if (!response.success) {
-        throw new Error(formatRelayError(response));
-    }
-    return { txid: response.txid, rawTx: serializedTx };
+    return submitSponsoredTransaction(account, transaction, network, () => callContract(account, options));
 }
 /**
- * High-level helper: build a sponsored STX transfer, submit to relay, and
- * return a TransferResult. Resolves the API key and handles relay errors.
- *
- * This is the primary entry point for services that need sponsored STX transfers.
+ * Build and submit a sponsored STX transfer via the relay.
+ * Falls back to direct submission (sender pays fee) when the relay is unavailable.
  */
 export async function sponsoredStxTransfer(account, recipient, amount, memo, network) {
-    const apiKey = resolveSponsorApiKey(account);
-    const networkName = getStacksNetwork(network);
     const transaction = await makeSTXTokenTransfer({
         recipient,
         amount,
         senderKey: account.privateKey,
-        network: networkName,
+        network: getStacksNetwork(network),
         memo: memo || "",
         sponsored: true,
         fee: 0n,
     });
-    const serializedTx = transaction.serialize();
-    const response = await submitToSponsorRelay(serializedTx, network, apiKey);
-    if (!response.success) {
-        throw new Error(formatRelayError(response));
-    }
-    return { txid: response.txid, rawTx: serializedTx };
+    return submitSponsoredTransaction(account, transaction, network, () => transferStx(account, recipient, amount, memo));
 }
 /**
- * High-level helper: build a sponsored contract deploy, submit to relay, and
- * return a TransferResult. Resolves the API key and handles relay errors.
- *
- * This is the primary entry point for services that need sponsored contract deployments.
+ * Build and submit a sponsored contract deploy via the relay.
+ * Falls back to direct submission (sender pays fee) when the relay is unavailable.
  */
 export async function sponsoredContractDeploy(account, options, network) {
-    const apiKey = resolveSponsorApiKey(account);
-    const networkName = getStacksNetwork(network);
     const transaction = await makeContractDeploy({
         contractName: options.contractName,
         codeBody: options.codeBody,
         senderKey: account.privateKey,
-        network: networkName,
+        network: getStacksNetwork(network),
         sponsored: true,
         fee: 0n,
     });
-    const serializedTx = transaction.serialize();
-    const response = await submitToSponsorRelay(serializedTx, network, apiKey);
-    if (!response.success) {
-        throw new Error(formatRelayError(response));
-    }
-    return { txid: response.txid, rawTx: serializedTx };
+    return submitSponsoredTransaction(account, transaction, network, () => deployContract(account, options));
 }
 /**
  * Submit a serialized transaction to the sponsor relay

package/dist/transactions/sponsor-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"sponsor-builder.js","sourceRoot":"","sources":["../../src/transactions/sponsor-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sponsor-builder.js","sourceRoot":"","sources":["../../src/transactions/sponsor-builder.ts"],"names":[],"mappings":"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"}

package/dist/utils/relay-health.d.ts

@@ -9,6 +9,7 @@ export interface StuckTransaction {
     txid: string;
     nonce: number;
     pendingSeconds: number;
+    sponsor_nonce?: number;
 }
 export interface RelayHealthStatus {
     healthy: boolean;
@@ -29,6 +30,19 @@ export interface RelayHealthStatus {
     stuckTransactions?: StuckTransaction[];
     issues?: string[];
 }
+/**
+ * Known sponsor addresses for each network.
+ * Only mainnet has a known relay sponsor address.
+ */
+export declare const SPONSOR_ADDRESSES: Partial<Record<Network, string>>;
+/**
+ * Lightweight relay health probe — returns true only if the relay /health
+ * endpoint responds within 5 seconds with HTTP 200 and status "ok".
+ *
+ * Use this on the hot path (e.g., before deciding to fall back to direct
+ * submission) where the full checkRelayHealth() diagnostics are unnecessary.
+ */
+export declare function isRelayHealthy(network: Network): Promise<boolean>;
 /**
  * Check relay health and sponsor nonce status
  */
@@ -57,9 +71,4 @@ export declare function attemptRbf(network: Network, txids?: string[], apiKey?:
  * Gracefully returns { supported: false } if the relay returns 404 or 501.
  */
 export declare function attemptFillGaps(network: Network, nonces?: number[], apiKey?: string): Promise<RelayRecoveryResult>;
-/**
- * Wait with exponential backoff when relay nonce issues are detected
- * Returns recommended wait time in milliseconds
- */
-export declare function getRelayBackoffDelay(attempt: number, hasNonceGaps: boolean): number;
 //# sourceMappingURL=relay-health.d.ts.map

package/dist/utils/relay-health.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relay-health.d.ts","sourceRoot":"","sources":["../../src/utils/relay-health.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGrD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE;QACZ,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,OAAO,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAUD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA4HnF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAuDzE;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAiDlH;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAiDxH;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,GAAG,MAAM,CASnF"}
+{"version":3,"file":"relay-health.d.ts","sourceRoot":"","sources":["../../src/utils/relay-health.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGrD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE;QACZ,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,aAAa,EAAE,MAAM,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,OAAO,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAE9D,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAqBvE;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA6HnF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAuDzE;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAwDD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAW5G;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAWlH"}