@qbit-oss/api 0.0.0-stage → 0.1.0

package/lib/index.d.ts

@@ -0,0 +1,551 @@
+interface EsploraChainStats {
+    funded_txo_count: number;
+    funded_txo_sum: number;
+    spent_txo_count: number;
+    spent_txo_sum: number;
+    tx_count: number;
+}
+interface EsploraAddressStats {
+    address: string;
+    chain_stats: EsploraChainStats;
+    mempool_stats: EsploraChainStats;
+}
+interface EsploraTxStatus {
+    confirmed: boolean;
+    block_height?: number;
+    block_hash?: string;
+    block_time?: number;
+}
+interface EsploraUtxo {
+    txid: string;
+    vout: number;
+    value: number;
+    status: EsploraTxStatus;
+}
+interface EsploraVin {
+    txid: string;
+    vout: number;
+    prevout: EsploraVout | null;
+    scriptsig: string;
+    scriptsig_asm: string;
+    witness?: string[];
+    is_coinbase: boolean;
+    sequence: number;
+}
+interface EsploraVout {
+    scriptpubkey: string;
+    scriptpubkey_asm: string;
+    scriptpubkey_type: string;
+    scriptpubkey_address?: string;
+    value: number;
+}
+interface EsploraTx {
+    txid: string;
+    version: number;
+    locktime: number;
+    vin: EsploraVin[];
+    vout: EsploraVout[];
+    size: number;
+    weight: number;
+    fee: number;
+    status: EsploraTxStatus;
+}
+/** esplora returns `{ "<target_blocks>": <sat/vB> }`, e.g. `{ "1": 12.3, "6": 4.1 }`. */
+type EsploraFeeEstimates = Record<string, number>;
+/**
+ * mempool-qbit retains mempool's field names, but the first three values come
+ * from projected blocks 1, 2, and 3. Economy and minimum are policy floors,
+ * not confirmation-target estimates.
+ */
+interface MempoolRecommendedFees {
+    fastestFee: number;
+    halfHourFee: number;
+    hourFee: number;
+    economyFee: number;
+    minimumFee: number;
+}
+interface AddressHistory {
+    confirmed: EsploraTx[];
+    mempool: EsploraTx[];
+}
+/**
+ * Per-call cancellation and time budget. Both cover every dependent request of
+ * the call — pagination, retries, backoff, and response-body reads.
+ */
+interface RequestOptions {
+    /**
+     * Aborting rejects the call with an `aborted` `QbitApiError` and stops further
+     * requests (`unknown_outcome` from `broadcastTx` once its POST may have been sent).
+     */
+    signal?: AbortSignal;
+    /**
+     * Overall budget for the call in ms; exceeding it rejects with a `timeout`
+     * `QbitApiError` (`unknown_outcome` from `broadcastTx` once its POST may have been sent).
+     */
+    deadlineMs?: number;
+}
+interface AddressHistoryOptions extends RequestOptions {
+    /**
+     * Maximum history page fetches for the whole call, including the terminal
+     * empty response and a rescan (default 256). The address-stats reads are not
+     * page fetches, nor is `EsploraClient`'s `/txs/mempool` fetch.
+     */
+    maxPages?: number;
+    /**
+     * Maximum raw transaction rows accepted for the whole call, a rescan
+     * included, before failing closed (default 6,400).
+     */
+    maxTransactions?: number;
+}
+interface BroadcastTxOptions extends RequestOptions {
+    /**
+     * Transaction id (64 hex characters) of `rawTxHex`. Derived from the hex when
+     * omitted; when both are available they must agree.
+     */
+    txid?: string;
+}
+type QbitApiErrorKind = 'rate_limit' | 'payload_too_large' | 'not_found' | 'http' | 'network' | 'timeout' | 'aborted' | 'parse' | 'pagination_limit' | 'invalid_cursor' | 'unknown_outcome';
+interface QbitApiErrorOptions {
+    status?: number;
+    url?: string;
+    cause?: unknown;
+    /**
+     * The underlying error before redaction. It is kept off the error object:
+     * read it with `QbitApiError.unredactedCause(error)`.
+     */
+    unredactedCause?: unknown;
+    retryAfterMs?: number;
+    /**
+     * Trimmed response body preview, capped at 200 characters. Errors the client
+     * creates redact the base URL from it as they do in `message`.
+     */
+    responseBody?: string;
+    /** Transaction id of the submission an `unknown_outcome` error refers to, when known. */
+    txid?: string;
+}
+declare class QbitApiError extends Error {
+    readonly kind: QbitApiErrorKind;
+    readonly status?: number;
+    readonly url?: string;
+    readonly retryAfterMs?: number;
+    /**
+     * The underlying error. Errors the client creates attach a redacted copy,
+     * safe to log: see `QbitApiError.unredactedCause`.
+     */
+    readonly cause?: unknown;
+    readonly responseBody?: string;
+    readonly txid?: string;
+    /**
+     * The underlying error of `error` as the fetch implementation threw it, or
+     * undefined. Its message, stack and properties can contain the full request
+     * URL, base-URL secrets included, so it is kept off the error object, where
+     * no logger, error reporter or serializer can reach it. Do not log it where
+     * the base URL is secret.
+     */
+    static unredactedCause(error: unknown): unknown;
+    /**
+     * Whether `value` is a `QbitApiError` (or a subclass instance) from any copy
+     * of `@qbit-oss/api`. `instanceof` only recognizes errors from the same copy,
+     * so it is false when an app loads both the CommonJS and the ESM build (or
+     * two installed versions) and the error comes from the other one. This checks
+     * a brand, `Symbol.for('qbit-js.QbitApiError')`, set on the class prototype
+     * instead. It identifies the class, not where the error came from: any code
+     * can set the brand. An error from another version can carry a `kind` this
+     * version does not list, so keep a default branch when switching on it.
+     */
+    static is(value: unknown): value is QbitApiError;
+    constructor(kind: QbitApiErrorKind, message: string, options?: QbitApiErrorOptions);
+}
+/**
+ * Fetch credential policy, the values of the DOM's `RequestCredentials`.
+ * Declared here so the published types compile without the DOM lib, which
+ * `@types/node` does not provide this name from.
+ */
+type QbitFetchCredentials = 'omit' | 'same-origin' | 'include';
+interface EsploraClientOptions {
+    /** Base URL for the esplora endpoint, e.g. `https://blockstream.info/testnet/api`. */
+    baseUrl: string;
+    /**
+     * Accept a plain `http:` baseUrl on a non-loopback host (default false).
+     * Without TLS, request headers such as API keys and every response are
+     * exposed to the network. `localhost`, `127.0.0.0/8` and `[::1]` are always
+     * accepted.
+     */
+    allowInsecureHttp?: boolean;
+    /**
+     * Custom fetch (defaults to global fetch). It should honour
+     * `redirect: 'manual'`; a reply it reports as `redirected`, or whose `url`
+     * is not the requested URL (another scheme, host, port, path or query), is
+     * refused, but only after the redirected request was sent. A `QbitApiError`
+     * it throws, from any copy of this package (see `QbitApiError.is`),
+     * propagates as it is, or as the `cause` of an `unknown_outcome` from a
+     * submission that may have been sent. One from another copy is judged by its
+     * public fields only, since that copy keeps the original cause and response
+     * body to itself: on a submission, its `network` error never proves that
+     * nothing was sent, and its response body never triggers the `/tx/push`
+     * fallback.
+     */
+    fetchFn?: typeof fetch;
+    /** Fetch credential policy (default `omit`). */
+    credentials?: QbitFetchCredentials;
+    /** Per-request timeout in ms (default 15000). */
+    timeoutMs?: number;
+    /**
+     * Retry attempts for transient failures — network/timeout/5xx/429 on reads
+     * (default 2). Submissions only repeat attempts that provably never reached
+     * the server; see `broadcastTx`.
+     */
+    retries?: number;
+    /** Base backoff in ms; grows exponentially per attempt (default 300). */
+    retryBaseDelayMs?: number;
+    /**
+     * Longest server-requested `Retry-After` delay the client will sleep before
+     * retrying, in ms (default 30000, at most 2147483647). A longer request is not
+     * slept on: a read's 429/5xx (`rate_limit` / `http`) or a submission's 429
+     * (`rate_limit`) is thrown at once with `retryAfterMs` set. A submission's
+     * 5xx is never retried, so the cap does not apply to it; see `broadcastTx`.
+     */
+    maxRetryAfterMs?: number;
+    /** Extra request headers. UDID/telemetry headers are intentionally unsupported. */
+    headers?: Record<string, string>;
+    /**
+     * Sleep function (injectable for tests); defaults to an abortable setTimeout.
+     * Receives the call's signal; the client stops waiting on abort either way.
+     */
+    sleepFn?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Cancels every in-flight and future call on this client when aborted. */
+    signal?: AbortSignal;
+}
+interface MempoolQbitClientOptions extends EsploraClientOptions {
+    /** Maximum combined-history requests fetched per call (default 256). */
+    maxAddressHistoryPages?: number;
+}
+declare class EsploraClient {
+    /** As configured, without trailing slashes. It can carry secrets: errors show `errorUrl(path)`. */
+    protected readonly baseUrl: string;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly retryBaseDelayMs;
+    private readonly maxRetryAfterMs;
+    private readonly headers;
+    private readonly credentials;
+    private readonly sleepFn;
+    private readonly signal;
+    /** In-flight GET de-dup: concurrent identical GETs share one request. */
+    private readonly inflight;
+    constructor(options: EsploraClientOptions);
+    getAddressStats(address: string, options?: RequestOptions): Promise<EsploraAddressStats>;
+    getAddressUtxos(address: string, options?: RequestOptions): Promise<EsploraUtxo[]>;
+    /**
+     * Confirmed transaction history for an address, newest first, 25 per page.
+     * Pass the last txid of the previous page as `afterTxid` to paginate.
+     */
+    getAddressTxs(address: string, afterTxid?: string, options?: RequestOptions): Promise<EsploraTx[]>;
+    /**
+     * Unconfirmed (mempool) transactions touching an address. electrs lists at
+     * most `--rest-default-max-mempool-txs` (default 50) of them, with no way to
+     * page further; `getAddressHistory` detects that cap.
+     */
+    getAddressMempoolTxs(address: string, options?: RequestOptions): Promise<EsploraTx[]>;
+    /**
+     * Complete address history from a bounded, page-one scan. The confirmed
+     * chain route is exhausted explicitly; short pages are not assumed final.
+     *
+     * electrs answers a chain cursor it does not know (a lagging node behind a
+     * load balancer, or a reorg between pages) with HTTP 200 and `[]`, and
+     * `/txs/mempool` stops at 50 rows, so the scan alone cannot tell a short
+     * history from a complete one. The address stats are therefore read before
+     * and after the scan, each in a request of its own, and the history is
+     * returned only if both reads agree and it holds exactly
+     * `chain_stats.tx_count` confirmed and `mempool_stats.tx_count` mempool
+     * transactions. If the stats changed during the scan, the address is scanned
+     * once more; if they change again, or the counts differ, the call rejects
+     * with `invalid_cursor`. Stats without a non-negative safe-integer
+     * `tx_count` reject with `parse`. `maxPages` and `maxTransactions` cover
+     * both scans.
+     */
+    getAddressHistory(address: string, options?: AddressHistoryOptions): Promise<AddressHistory>;
+    private scanAddressHistory;
+    private scanAddressHistoryOnce;
+    getTx(txid: string, options?: RequestOptions): Promise<EsploraTx>;
+    /**
+     * Raw transaction hex as the backend serializes it (with witness data when
+     * the transaction has any), in lowercase. The reply is checked before it is
+     * returned: it must be non-empty, even-length hex that decodes to one
+     * complete transaction whose txid (the double SHA-256 of its
+     * witness-stripped serialization, as qbit Core computes it) is `txid`,
+     * compared case-insensitively. The transaction must be encoded as qbit
+     * Core's decoder requires: every count and length in its shortest
+     * CompactSize form and at most 0x02000000, and no witness flag when every
+     * witness stack is empty. Anything else, including the empty `200`
+     * reply mempool.qbit.org serves, throws a `parse` `QbitApiError`, so a
+     * backend cannot hand back an empty string or another transaction. Spaces,
+     * tabs and line breaks around the hex are ignored. The txid does not commit
+     * to witness data, so a reply with altered or stripped witnesses still
+     * passes; compare the wtxid if you need them.
+     */
+    getTxHex(txid: string, options?: RequestOptions): Promise<string>;
+    getTxStatus(txid: string, options?: RequestOptions): Promise<EsploraTxStatus>;
+    getFeeEstimates(options?: RequestOptions): Promise<EsploraFeeEstimates>;
+    getTipHeight(options?: RequestOptions): Promise<number>;
+    getTipHash(options?: RequestOptions): Promise<string>;
+    /**
+     * Broadcast a raw transaction hex. Resolves with the txid once the node has
+     * the transaction, including when it reports the transaction as already in
+     * its mempool or chain. A submission is never re-sent after an attempt that
+     * may have reached the node: a timeout, an ambiguous network error, or a
+     * 5xx reply whose body carries no verdict from the node rejects with
+     * `unknown_outcome` carrying the txid so the caller can check
+     * `getTxStatus(txid)` before resubmitting the same hex. Only 429 replies and
+     * connection failures that happened before anything was sent are retried; a
+     * 429 whose `Retry-After` exceeds `maxRetryAfterMs` is not waited on and
+     * rejects at once as `rate_limit` with `retryAfterMs`, without a re-send.
+     * A redirect is never followed. A refused one (a 3xx, a browser opaque
+     * redirect, or a reply from a redirect the runtime followed) rejects with
+     * `unknown_outcome` too, with the `http` refusal as `cause`: the POST
+     * reached the backend, which may have accepted it before redirecting, and
+     * a runtime that followed the redirect may have re-sent it.
+     * Coded node rejections fail closed as `http` errors whatever the HTTP
+     * status, since qbit Core's own JSON-RPC server answers 500 for every RPC
+     * error and a backend or proxy may relay that status. When no txid
+     * can be derived from the hex and none is supplied, a 2xx reply resolves only
+     * if its body is itself a 64-hex txid; any other 2xx body is `unknown_outcome`.
+     * Hex `txidFromRawTx` cannot read, including encodings qbit Core refuses to
+     * decode, is still sent as it is, and the node gives the verdict.
+     * A malformed `rawTxHex` argument or an `options.txid` that is not a 64-hex
+     * transaction id matching the hex throws a `TypeError` before anything is sent.
+     *
+     * `options.signal` / `options.deadlineMs` bound the whole call. An abort or
+     * expired deadline before the POST is sent rejects with `aborted` /
+     * `timeout`; once the POST may have been sent (in flight or while its reply
+     * is read) it rejects with `unknown_outcome`, with that error as `cause`.
+     * A reply whose body stalls past `timeoutMs` or cannot be read is
+     * `unknown_outcome` too. A 429 reply is the exception throughout: it proves
+     * nothing was submitted, so one whose body is lost is retried (then
+     * `rate_limit`), and an abort or deadline during its body is definite.
+     */
+    broadcastTx(rawTxHex: string, options?: BroadcastTxOptions): Promise<string>;
+    /** Confirmed + mempool balance for an address, in satoshis. */
+    getAddressBalance(address: string, options?: RequestOptions): Promise<AddressBalance>;
+    /** Fee-rate tiers (sat/vB), ascending by confirmation target. */
+    getFeeTiers(options?: RequestOptions): Promise<FeeRateTier[]>;
+    /**
+     * Run one public call under a single signal that combines the client's
+     * signal, the caller's signal, and the caller's deadline. Pass `{ signal }`
+     * to dependent calls so they share the same cancellation and budget.
+     */
+    protected runOperation<T>(options: RequestOptions | undefined, run: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /**
+     * GET and parse JSON. With `dedup` false the request is sent on its own
+     * instead of joining an identical one already in flight, whose reply may
+     * predate requests this call has made since.
+     */
+    protected getJson<T>(path: string, options?: RequestOptions, dedup?: boolean): Promise<T>;
+    protected getText(path: string, options?: RequestOptions): Promise<string>;
+    /**
+     * POST a transaction submission under the submission retry policy and
+     * classify the node's reply. `txid` identifies the submission in
+     * `unknown_outcome` errors and is the result for already-known replies.
+     * An abort or deadline once the POST may have been sent, including while
+     * the reply body is read, is an `unknown_outcome` too, unless the reply is
+     * a 429.
+     */
+    protected submitTx(path: string, body: string, txid: string | undefined, options?: RequestOptions): Promise<string>;
+    protected request(path: string, init: {
+        method: string;
+        body?: string;
+        headers?: Record<string, string>;
+        dedup: boolean;
+    }, options?: RequestOptions): Promise<Response>;
+    /**
+     * Concurrent identical GETs share one request. One caller giving up only
+     * stops waiting; the shared request is aborted once every caller has left.
+     */
+    private requestShared;
+    /**
+     * Idempotent requests (GET/HEAD) retry on network errors, timeouts, and
+     * transient statuses. Any other method is a submission: an attempt is only
+     * repeated when it provably never reached the server (429, or a connection
+     * failure before anything was sent), and an attempt that may have been
+     * processed fails with `unknown_outcome` instead of being re-sent; that
+     * includes an abort or deadline that fires while a submission is in flight,
+     * and a refused redirect. `txid` labels that error when the submission is a
+     * transaction.
+     */
+    private requestWithRetry;
+    /** Backoff that rejects as soon as `signal` aborts, even if `sleepFn` ignores it. */
+    private sleep;
+    /**
+     * One attempt under one timeout that spans the headers and the whole body,
+     * also bounded by the call's signal until the body is buffered. Every
+     * response it returns is fully buffered, whatever its status, so no caller
+     * (retry loop, de-duplicated clone, or error path) can block on the network
+     * after the timer is cleared. A body that misses the attempt timeout fails
+     * the attempt as `timeout`, even for a status that would otherwise be
+     * retried; an abort or call deadline, before or after the headers, rejects
+     * with the call's `aborted` / `timeout` error. `reply.status` is set once
+     * the headers arrive. A redirect is refused before its body is read, which
+     * is cancelled instead, and `reply.refusedRedirect` is set; see
+     * `refuseRedirect`.
+     */
+    private fetchOnce;
+    /** `status` is set when the headers arrived and the body missed the deadline. */
+    private timeoutError;
+    private backoffMs;
+    /** The request URL for `path` as errors show it: see `redactedBaseUrl`. */
+    protected errorUrl(path: string): string;
+}
+/**
+ * Adapter for mempool-qbit's public Node API (`/api/v1` prefix). Most routes
+ * match Esplora, but address pagination and fees use mempool-style shapes.
+ */
+declare class MempoolQbitClient extends EsploraClient {
+    private readonly maxAddressHistoryPages;
+    constructor(options: MempoolQbitClientOptions);
+    /**
+     * Complete address history from one bounded traversal of mempool-qbit's
+     * combined endpoint. Page size is intentionally not assumed.
+     *
+     * The result is checked against the address stats, read before and after
+     * the traversal, as `EsploraClient.getAddressHistory` describes, and a
+     * traversal during which they changed is repeated once. qbit-electrs
+     * answers a cursor that is the last mempool row with `[]` instead of the
+     * confirmed rows that follow, so an address whose mempool rows fill whole
+     * pages (50 each by default) rejects with `invalid_cursor` while it has
+     * confirmed history, rather than returning none.
+     */
+    getAddressHistory(address: string, options?: AddressHistoryOptions): Promise<AddressHistory>;
+    private scanCombinedAddressHistory;
+    private scanCombinedAddressHistoryOnce;
+    /**
+     * Confirmed transaction history for an address, newest first.
+     * mempool-qbit paginates combined history with `?after_txid=...` and sorts
+     * mempool entries first, so full mempool-only pages must still advance.
+     * Without `afterTxid`, an empty page right after a mempool row is checked
+     * against the address stats: qbit-electrs answers that cursor with `[]`
+     * instead of the confirmed rows that follow, so the call rejects with
+     * `invalid_cursor` if the stats count more confirmed transactions than it
+     * found.
+     */
+    getAddressTxs(address: string, afterTxid?: string, options?: RequestOptions): Promise<EsploraTx[]>;
+    private scanAddressTxs;
+    /**
+     * qbit-electrs's combined route answers an `after_txid` that is the last
+     * mempool row with `[]`, not the confirmed rows that follow: it passes the
+     * mempool txid on as the chain cursor, which `history()` never finds
+     * (`src/rest.rs:992-998` in Qbit-Org/qbit-electrs@53102e9). Reject that
+     * empty page when the address stats count confirmed transactions the scan
+     * has not seen.
+     */
+    private assertConfirmedHistoryReached;
+    /**
+     * mempool-qbit does not expose `/txs/mempool`. Page through the combined
+     * history until confirmed entries begin, collecting the leading mempool set.
+     */
+    getAddressMempoolTxs(address: string, options?: RequestOptions): Promise<EsploraTx[]>;
+    private scanAddressMempoolTxs;
+    getMempoolRecommendedFees(options?: RequestOptions): Promise<MempoolRecommendedFees>;
+    getFeeEstimates(options?: RequestOptions): Promise<EsploraFeeEstimates>;
+    /**
+     * Broadcast via `/tx`, falling back to the `/tx/push` form route only when
+     * `/tx` reported that it did not submit the transaction. The fallback is a
+     * second submission, so it follows the same policy: an already-known reply
+     * resolves with the txid and an uncertain attempt rejects with
+     * `unknown_outcome`. An uncertain `/tx` attempt never falls back.
+     *
+     * One signal and deadline cover both requests, with the same abort rules as
+     * `EsploraClient.broadcastTx`. An abort or expired deadline during `/tx`
+     * never sends the `/tx/push` fallback.
+     */
+    broadcastTx(rawTxHex: string, options?: BroadcastTxOptions): Promise<string>;
+    private addressHistoryPaginationLimitError;
+    private invalidAddressHistoryCursorError;
+    private nonAdvancingAddressHistoryCursorError;
+}
+interface AddressBalance {
+    address: string;
+    confirmedSats: number;
+    mempoolSats: number;
+    totalSats: number;
+}
+/**
+ * Confirmed, mempool and total balance in satoshis from esplora address stats.
+ *
+ * Throws a `parse` {@link QbitApiError} unless `stats` has a string `address`
+ * and `chain_stats` / `mempool_stats` objects whose `funded_txo_sum` and
+ * `spent_txo_sum` are non-negative safe integers, the confirmed balance is not
+ * negative, and `totalSats` is a non-negative safe integer. `mempoolSats` may
+ * be negative while mempool transactions spend confirmed outputs.
+ *
+ * `funded_txo_sum` and `spent_txo_sum` are lifetime totals of everything the
+ * address has received and spent, not balances, and `MAX_MONEY` does not
+ * bound them. `JSON.parse` cannot represent integers above
+ * `Number.MAX_SAFE_INTEGER` (2^53 - 1 sats, about 90M QBT) exactly, so it
+ * rounds them, and they fail closed rather than yield a plausible but wrong
+ * balance. A reused address that has received more than that over its life
+ * therefore fails on every call, however little it holds now. For such an
+ * address, sum the `value` of each output from
+ * {@link EsploraClient.getAddressUtxos} instead; that raw endpoint is not
+ * validated, so check that each value is a non-negative safe integer.
+ *
+ * The `parse` error for a negative total, here and from
+ * {@link EsploraClient.getAddressBalance}, can be transient right after a
+ * block on electrs: it applies the block's headers before indexing it and
+ * does not deduplicate mempool stats against the chain, so a spend that was
+ * just confirmed can count in both `chain_stats` and `mempool_stats` for a
+ * moment. Retry it on the next poll.
+ */
+declare function addressBalanceFromStats(stats: EsploraAddressStats): AddressBalance;
+/**
+ * Default `maxFeeRate` for {@link feeTiersFromEstimates}, in sat/vB. qbit Core's
+ * `sendrawtransaction` refuses fee rates above `DEFAULT_MAX_RAW_TX_FEE_RATE{COIN / 10}`
+ * per kvB by default (`src/node/transaction.h:27`), which is 10,000 sat/vB.
+ */
+declare const DEFAULT_MAX_FEE_RATE_SAT_VB = 10000;
+interface FeeRateTier {
+    /** Confirmation target in blocks. */
+    target: number;
+    /** Fee rate in sat/vB. */
+    feeRate: number;
+}
+/**
+ * Map mempool-qbit's projected blocks, leaving named policy floors unlabelled.
+ *
+ * Throws a `parse` {@link QbitApiError} unless `fees` is an object whose
+ * `fastestFee`, `halfHourFee` and `hourFee` are finite numbers above 0. The
+ * fee-rate ceiling is applied downstream by {@link feeTiersFromEstimates}.
+ */
+declare function feeEstimatesFromMempoolRecommendedFees(fees: MempoolRecommendedFees): EsploraFeeEstimates;
+/**
+ * Fee-rate tiers (sat/vB) from an esplora fee-estimate map, ascending by
+ * confirmation target. `{}` yields `[]`.
+ *
+ * Fails closed with a `parse` {@link QbitApiError} unless `estimates` is an
+ * object whose every key is a canonical decimal target from 1 to 1008 blocks
+ * and whose every value is a finite fee rate above 0 and at most `maxFeeRate`
+ * (default {@link DEFAULT_MAX_FEE_RATE_SAT_VB}). The default is a ceiling, not
+ * a sanity check: it only rejects rates above Core's default broadcast limit,
+ * so a hostile or broken backend can still return 9,999 sat/vB. Set a lower
+ * ceiling with `feeTiersFromEstimates(await client.getFeeEstimates(), { maxFeeRate })`,
+ * cap the total fee before signing, or both.
+ * Previously, malformed entries were silently dropped and no ceiling applied.
+ *
+ * @throws TypeError when `options.maxFeeRate` is not a finite number above 0.
+ */
+declare function feeTiersFromEstimates(estimates: EsploraFeeEstimates, options?: {
+    maxFeeRate?: number;
+}): FeeRateTier[];
+/**
+ * Transaction id of a raw transaction hex in legacy or BIP144 (witness)
+ * encoding: the double SHA-256 of the witness-stripped serialization,
+ * displayed byte-reversed. Throws a `parse` `QbitApiError` when the hex is not
+ * a structurally complete transaction, or uses an encoding qbit Core refuses
+ * to decode even where the txid would not change: a count or length (witness
+ * section included) in a longer CompactSize form than its value needs or above
+ * 0x02000000 (Core's MAX_SIZE), or a witness flag with every witness stack
+ * empty.
+ */
+declare function txidFromRawTx(rawTxHex: string): string;
+
+export { type AddressBalance, type AddressHistory, type AddressHistoryOptions, type BroadcastTxOptions, DEFAULT_MAX_FEE_RATE_SAT_VB, type EsploraAddressStats, type EsploraChainStats, EsploraClient, type EsploraClientOptions, type EsploraFeeEstimates, type EsploraTx, type EsploraTxStatus, type EsploraUtxo, type EsploraVin, type EsploraVout, type FeeRateTier, MempoolQbitClient, type MempoolQbitClientOptions, type MempoolRecommendedFees, QbitApiError, type QbitApiErrorKind, type QbitApiErrorOptions, type QbitFetchCredentials, type RequestOptions, addressBalanceFromStats, feeEstimatesFromMempoolRecommendedFees, feeTiersFromEstimates, txidFromRawTx };