@lumenwipe/sdk 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -14,6 +14,10 @@ export declare interface AccountState {
     thresholds: AccountThresholds;
     numSubEntries: number;
     numSponsoring: number;
+    /** Reserves another account pays for this one: its own base reserve when its creation was
+     *  sponsored, and each sponsored subentry. Lowers the minimum balance. Absent when the read
+     *  did not report it, which is treated as none. */
+    numSponsored?: number;
     /** Ledger entries this account currently sponsors (on other accounts, or itself via a
      *  fully-sponsored account creation). Populated by replaying sponsorship-relevant
      *  operations and re-verifying each candidate's live sponsor - see sponsorship.ts. */
@@ -35,7 +39,17 @@ export declare interface AccountState {
     /** Claimable balances where this account is listed as a claimant. Does not affect
      *  numSubEntries on this account; populated via the Horizon adapter. */
     claimableBalances: ClaimableBalance[];
+    /** True when the account holds more claimable balances than one read returns, so
+     *  `claimableBalances` is a bounded part of them. Set only by the account reader. While it is
+     *  set the merge is never built: the rest would be stranded. */
+    claimableBalancesMore?: boolean;
     subEntryMismatch: boolean;
+    /** Close time of the latest ledger (epoch seconds) when the claim predicates were judged.
+     *  Absent means it could not be read, and only unconditional claims count as claimable. */
+    ledgerCloseTime?: number;
+    /** The latest ledger the enumeration's reads reflect, for debugging. Absent when the provider
+     *  reports none. */
+    snapshotLedger?: number;
     /** Detected DeFi positions (Blend, Aquarius, Soroswap, Phoenix, FxDAO), resolved via OctoPos on
      *  mainnet or a direct contract read on testnet / mainnet degraded mode - architecture.md §7.1.
      *  Never absent: an unconfigured deployment or provider outage still returns a result, stamped
@@ -158,6 +172,13 @@ export declare type AquariusPoolType = "constant_product" | "stable" | "concentr
  */
 export declare type AssetDisposition = "convert" | "issuer" | "transfer" | "leave";
 
+/** Body for `POST /v1/:network/close/batch-plan`: up to 20 accounts planned into one shared
+ *  destination, read-only, with no decisions applied. */
+export declare interface BatchPlanRequest {
+    addresses: string[];
+    destination?: string;
+}
+
 export declare interface BatchPlanResponse {
     results: BatchPlanResult[];
 }
@@ -229,11 +250,81 @@ export declare type ClaimPredicate = {
     deadlineEpoch: string;
 };
 
+/**
+ * The swap quote on a convertible classic asset's `asset_disposition` subject (`subject.quote`),
+ * in stroops of XLM. Display data: the build re-quotes, and a convert answer carries its own floor
+ * in `params.minAmountOut`. Absent when the asset has no route, or when its balance is what a
+ * position's exit will pay in and is not known yet.
+ */
+export declare interface ClassicConversionQuote {
+    /** The XLM the route is expected to deliver for the balance the step will move. */
+    estimatedReceive: string;
+    /** The least XLM the route may deliver once slippage is applied. */
+    minAmountOut: string;
+}
+
 export declare type CloseApiStatus = "ready" | "needs_decisions" | "blocked" | "complete";
 
+/**
+ * One transaction in a `GET /v1/:network/close/delivered` answer. `delivered` means the ledger's
+ * own result for the confirmed transaction credited `amountStroops` of XLM to the destination,
+ * through a merge into it or, for a close routed through the relay account, the native payment
+ * that forwarded the merged balance. `unavailable` never carries an amount:
+ * - `not_found`: no provider holds the hash. It may be unknown, still pending, or older than the
+ *   providers keep.
+ * - `failed`: the transaction failed, so it moved nothing.
+ * - `no_delivery`: it confirmed, but no merge into the destination and no forward of a merged
+ *   balance to it is in it.
+ */
+export declare type CloseDeliveredEntry = {
+    hash: string;
+    status: "delivered";
+    ledger: number;
+    amountStroops: string;
+} | {
+    hash: string;
+    status: "unavailable";
+    reason: "not_found" | "failed" | "no_delivery";
+    /** Set when the transaction is on the ledger: failed or no_delivery. */
+    ledger?: number;
+};
+
+/**
+ * Response from `GET /v1/:network/close/delivered`. `entries` follow the order of the requested
+ * hashes. `totalStroops` is present only when every entry is `delivered`. XLM that reached the
+ * destination by any other operation, and any asset other than XLM, is not counted.
+ */
+export declare interface CloseDeliveredResponse {
+    destination: string;
+    entries: CloseDeliveredEntry[];
+    totalStroops?: string;
+}
+
+/** Thrown when a close cannot finish: the API kept asking for another call past the round
+ *  bound, or said another call is needed yet returned nothing to sign. Nothing is lost - the
+ *  API re-reads live state, so running the close again picks up where it stopped. */
+export declare class CloseDidNotConvergeError extends Error {
+    readonly rounds: number;
+    readonly bound: number;
+    readonly reason: CloseDidNotConvergeReason;
+    constructor(rounds: number, bound: number, reason: CloseDidNotConvergeReason);
+}
+
+export declare type CloseDidNotConvergeReason = "round_limit" | "empty_batch";
+
 export declare interface CloseEngineDeps {
-    /** Fetches the next round of unsigned transactions from the API (via the proxy). */
-    getTransactions: () => Promise<TransactionsResponse>;
+    /** Fetches the next round of unsigned transactions from the API (via the proxy). Pass
+     *  `planHash` on to `closeTransactions` when it is set. */
+    getTransactions: (request: {
+        planHash?: string;
+    }) => Promise<TransactionsResponse>;
+    /**
+     * The `planHash` of the plan the user reviewed. Sent with every fetch until the first
+     * transaction of this run confirms, and never after: from then on the account has changed on
+     * purpose. A round refused as `state_changed` while it was sent is not fetched again, since the
+     * reviewed plan itself is stale; `runClose` throws `CloseStateChangedError` at once.
+     */
+    planHash?: string;
     /**
      * Verifies one server-built transaction against what the client independently expects.
      * MUST throw on any mismatch. This is the trust anchor: the browser never signs a
@@ -253,14 +344,32 @@ export declare interface CloseEngineDeps {
         xdr: string;
         weight: number;
     }>;
+    /** Turns a signed envelope into the final one, adding any co-signature or sponsorship. Runs
+     *  once per transaction: a resend never comes back here. */
+    prepare?: (tx: CloseTransaction, xdr: string) => Promise<string>;
     /** Submits a transaction whose accumulated weight already meets its requirement; resolves
      *  to the tx hash. */
     submit: (tx: CloseTransaction, xdr: string) => Promise<string>;
-    /** Called after a transaction confirms, with the transaction and its hash. */
+    /** Settle unknown outcomes by hash instead of surfacing them. See `CloseReconciliation`. */
+    reconcile?: CloseReconciliation;
+    /** Called after a transaction confirms, with the transaction and its hash. With `reconcile`,
+     *  `covers` names a merge only when the client parsed one, whatever the API claimed. */
     onConfirmed?: (tx: CloseTransaction, hash: string) => void;
     onProgress?: (message: string) => void;
     /**
-     * Safety bound so a misbehaving API can never spin the loop forever. This is what covers
+     * Told each step of the close as it happens, in order: `preparing` before a round is fetched,
+     * then for each transaction `verifying`, `awaiting-signature` (the signer is asked),
+     * `submitting` (signed; from here on the network and any `prepare` step are waited on) and
+     * `confirmed`. A resumed transaction starts at `awaiting-signature`: it is not verified again.
+     * An observer only: each event is a fresh object, nothing it returns is awaited, and anything it
+     * throws or rejects with is ignored, so it can neither stop nor change the close.
+     */
+    onProgressEvent?: (event: CloseProgressEvent) => void;
+    /**
+     * Overrides the round bound. Without it the bound is derived each round from the API's own
+     * `remaining.steps` (rounds done, plus steps left, plus a margin), only ever raised and capped
+     * at 200, so a long close is not cut short and a misbehaving API still cannot spin forever.
+     * This is what covers
      * #59's mediator-cleanup concern: the API is stateless and re-reads live state every round,
      * so `remaining.requiresAnotherCall` for that flow reflects "cleanup still sees something to
      * remove," not a bounded countdown - if an asset keeps getting re-funded between rounds (or
@@ -268,6 +377,15 @@ export declare interface CloseEngineDeps {
      * with a clear thrown error instead of looping indefinitely.
      */
     maxRounds?: number;
+    /** Waits `ms` milliseconds; defaults to a timer. Injected so tests need not wait. */
+    sleep?: (ms: number) => Promise<void>;
+}
+
+/** Thrown when a transaction went out and neither a resend nor a lookup settled it. Not a failure:
+ *  it may still land. Pass `submission` back as `unresolved`, or to `resolveSubmission`. */
+export declare class CloseOutcomeUnknownError extends Error {
+    readonly submission: UnresolvedSubmission;
+    constructor(submission: UnresolvedSubmission);
 }
 
 /** Body for `POST /v1/:network/close/plan`. */
@@ -277,6 +395,77 @@ export declare interface ClosePlanRequest {
     decisions?: DecisionAnswer[];
 }
 
+/** What `onProgressEvent` is told: a round being fetched, or a transaction of it changing phase. */
+export declare type CloseProgressEvent = CloseRoundProgress | CloseTransactionProgress;
+
+/** Where a close is, as `onProgressEvent` reports it. */
+export declare type CloseProgressPhase = "preparing" | "verifying" | "awaiting-signature" | "submitting" | "confirmed";
+
+/** What `runClose` needs to settle an unknown outcome. Opt-in: without it a failed `submit` is
+ *  surfaced as it is, nothing is sent twice, and nothing here runs. */
+export declare interface CloseReconciliation {
+    /** The hash of the exact final envelope, computed locally with the client's own passphrase, so
+     *  the outer hash for a fee-bump. MUST NOT come from the API. */
+    hashOf: (signedXdr: string) => string;
+    /** Whether the client itself parsed an account merge of this account out of the envelope. */
+    closesAccount: (signedXdr: string) => boolean;
+    /** Unix seconds after which the envelope cannot land, from its own time bounds. */
+    validUntil: (signedXdr: string) => number | null;
+    /** Looks a hash up on the network, through `client.getTransaction` or a proxy of it. */
+    lookup: (hash: string) => Promise<TransactionLookupResponse>;
+    /** Told when a submission opens, before it is sent, and with null when it settles: persist it
+     *  and an interrupted close still knows what to look up. Rejecting the first call stops the
+     *  transaction unsent, which is what a caller that could not persist it should do. */
+    onSubmission?: (submission: UnresolvedSubmission | null) => void | Promise<void>;
+    /** A submission left over from an earlier run, settled first, by lookup only. */
+    unresolved?: UnresolvedSubmission;
+    /** A left-over submission confirmed: `onConfirmed` has no transaction to report for it. */
+    onResolved?: (submission: UnresolvedSubmission) => void;
+    /** Replaces `Date.now`, for tests. */
+    now?: () => number;
+}
+
+/** A round is being fetched. Nothing is known about its batch yet. */
+export declare interface CloseRoundProgress {
+    /** Always `preparing`. */
+    phase: "preparing";
+    /** Zero-based. */
+    round: number;
+}
+
+/** How a run ended. `mergeConfirmed` is true only with `reconcile`, for a transaction the client
+ *  parsed as a merge and saw confirmed under its own hash. Without `reconcile` it is always false:
+ *  `runClose` returning then says only that the API asked for no more calls, and `covers` is API
+ *  metadata, so a caller must establish the merge itself before calling the account closed. */
+export declare interface CloseRunResult {
+    mergeConfirmed: boolean;
+}
+
+/** Thrown when the account kept changing while the API prepared a round (`state_changed`).
+ *  Nothing was submitted for that round; plan again and run the close from the new plan. */
+export declare class CloseStateChangedError extends Error {
+    readonly apiError: unknown;
+    constructor(apiError: unknown);
+}
+
+/** Sub-entries and sponsorships the ledger still counts on an account. */
+export declare interface CloseStatusRemaining {
+    subentries: number;
+    sponsoring: number;
+    sponsored: number;
+}
+
+/**
+ * Response from `GET /v1/:network/close/status`. Informational: `closed` means the account is
+ * absent and the last operation in its history is a merge, never that a given close finished.
+ */
+export declare interface CloseStatusResponse {
+    source: string;
+    phase: "open" | "ready_to_merge" | "closed" | "unknown";
+    /** Present while the account is on the ledger. */
+    remaining?: CloseStatusRemaining;
+}
+
 export declare interface CloseTransaction {
     id: string;
     order: number;
@@ -299,7 +488,7 @@ export declare interface CloseTransaction {
     /**
      * True when the account cannot pay this transaction's own fee without dropping below its
      * reserve (architecture.md §8.1): the API built it with its own fee at zero, and the client
-     * must route the signed envelope through `POST /:network/fee-bump/sponsor` before submitting
+     * must route the signed envelope through `POST /v1/:network/fee-bump/sponsor` before submitting
      * it, instead of submitting it directly. Absent (not `false`) on every ordinary transaction -
      * an older client reading this field sees nothing here and simply submits as it always has.
      */
@@ -307,17 +496,55 @@ export declare interface CloseTransaction {
     intent: TxIntent;
 }
 
+/** Thrown when a lookup by the client's own hash shows the transaction failed on the ledger. */
+export declare class CloseTransactionFailedError extends Error {
+    readonly submission: UnresolvedSubmission;
+    constructor(submission: UnresolvedSubmission, message: string);
+}
+
+/** One transaction of the current batch moved to `phase`. */
+export declare interface CloseTransactionProgress {
+    /** `verifying`, `awaiting-signature` (the signer is asked), `submitting` (signed; the network
+     *  is waited on) or `confirmed`. */
+    phase: Exclude<CloseProgressPhase, "preparing">;
+    /** Zero-based. */
+    round: number;
+    /** Zero-based position of this transaction in its batch. */
+    txIndex: number;
+    /** How many transactions this batch holds. Exact for this batch only. */
+    txCount: number;
+    /** The steps this transaction covers. API metadata in every phase but `confirmed`, which carries
+     *  what `onConfirmed` is given: with `reconcile`, a merge only when the client parsed one. */
+    covers: CloseTransaction["covers"];
+    /** The API asked for another round after this batch. Each round is planned from live state, so
+     *  the close as a whole holds at least `txCount` transactions and its total is not known. */
+    moreRoundsExpected: boolean;
+}
+
 /** Body for `POST /v1/:network/close/transactions`. */
 export declare interface CloseTransactionsRequest {
     source: string;
     destination: string;
     decisions?: DecisionAnswer[];
     /**
-     * Deposit memo value for exchange destinations that require one. The memo type
-     * is taken from the exchange registry, not the client. Required when the
-     * destination is an exchange that mandates a memo.
+     * Deposit memo value. Required when the destination is an exchange that mandates a
+     * memo, or an account whose `config.memo_required` data entry is set (SEP-29). A blank
+     * memo counts as none. An id memo is a decimal uint64 with no leading zeros.
      */
     memo?: string;
+    /**
+     * The type of `memo`. For an exchange the registry lists, the registry's type is used and
+     * a different one is refused with `422 invalid_memo`; for any other destination this type
+     * is used, `text` when omitted. Has no effect without a memo.
+     */
+    memoType?: "text" | "id";
+    /**
+     * The `planHash` of the plan the user reviewed. Send it with the first call after that plan, and
+     * the API answers `409 state_changed` when the account's sequence or the answers differ from
+     * those the plan was built from. Leave it out once a transaction of the close has confirmed: the
+     * account has then changed on purpose.
+     */
+    planHash?: string;
 }
 
 export declare interface ConversionPath {
@@ -328,6 +555,15 @@ export declare interface ConversionPath {
     destMin: string;
 }
 
+/** Body for `POST /v1/integrator/keys`. Both fields are optional. */
+export declare interface CreateIntegratorKeyRequest {
+    /** A name for the key, 1 to 64 printable characters after trimming. */
+    label?: string;
+    /** The networks the key may call, at least one. Omit for every network. A scoped key is refused
+     *  on routes without a network. */
+    networks?: Network[];
+}
+
 export declare interface DailyActivity {
     /** UTC day, YYYY-MM-DD. */
     date: string;
@@ -345,10 +581,11 @@ export declare interface DecisionAnswer {
     params?: {
         maxSlippageBps?: number;
         /**
-         * Required by `convert_to_xlm` on a Soroban token: the least XLM, in stroops, the user was
-         * shown the swap would deliver (the plan's `quote.minAmountOut`). The build refuses a route
-         * that no longer clears it (`quote_drifted`) instead of swapping at a rate nobody agreed to,
-         * and the browser holds the built swap's own minimum to at least this figure.
+         * Required by `convert_to_xlm` on a Soroban token, optional on a classic asset: the least
+         * XLM, in stroops, the user was shown the conversion would deliver (the plan's
+         * `quote.minAmountOut`). The build refuses a route that no longer clears it
+         * (`quote_drifted`) instead of converting at a rate nobody agreed to, and the browser holds
+         * the built conversion's own minimum to at least this figure.
          */
         minAmountOut?: string;
         /**
@@ -381,8 +618,17 @@ export declare interface DecisionOption {
 export declare interface DecisionPoint {
     id: string;
     type: "asset_disposition" | "confirmation" | "choice" | "claimable_balance";
+    /** Shape depends on `type`. A convertible classic asset's subject carries a
+     *  `quote: ClassicConversionQuote`. A Soroban token's carries `quote` (with `priceImpactBps`,
+     *  `flags: TokenQuoteFlag[]` and an optional `runnerUp`) when convertible, else a
+     *  `reason: TokenUnquotedReason`. */
     subject: Record<string, unknown>;
     options: DecisionOption[];
+    /**
+     * The recommended option id, advisory only: nothing is applied for an unanswered decision. Empty
+     * when no option is safe to recommend, such as an asset with no swap route. A convertible asset
+     * defaults to converting; no decision ever recommends returning an asset to its issuer.
+     */
     default: string;
     required: boolean;
 }
@@ -503,14 +749,25 @@ export declare interface DefiRpcPolicy {
     timeoutMs: number;
 }
 
-export declare type DemolishPhase = "IDLE" | "ANALYZING" | "PREFLIGHT_COMPLETE" | "SIGNER_SETUP" | "STEP_EXECUTING" | "STEP_CONFIRMED" | "STEP_FAILED" | "COMPLETE" | "ABORTED";
+export declare type DemolishPhase = "IDLE" | "ANALYZING" | "PREFLIGHT_COMPLETE" | "SIGNER_SETUP" | "STEP_EXECUTING" | "STEP_CONFIRMED" | "STEP_FAILED" | "STEP_UNCONFIRMED" | "COMPLETE" | "ABORTED";
 
 /**
  * Every code the API can put in `error.code`. A code is a contract: it is added here first and
  * never renamed or removed without a deprecation window. The API's runtime list
  * (apps/api/src/common/error-codes.ts) is checked against this union at compile time.
  */
-export declare type ErrorCode = "account_not_found" | "account_read_failed" | "account_too_large" | "admin_api_not_configured" | "allowances_read_failed" | "api_key_not_found" | "aquarius_trustline_missing" | "backstop_emissions_unclaimed" | "backstop_token_unconvertible" | "backstop_withdrawal_cooling_down" | "backstop_withdrawal_not_queued" | "bad_request" | "blend_emissions_trustline_missing" | "blend_repay_asset_balance_unknown" | "blend_repay_asset_missing" | "confirmation_timeout" | "conversion_floor_missing" | "conversion_provider_unrecognized" | "defi_exit_blocked" | "defi_exit_unsupported" | "defi_position_unrecognized" | "defi_positions_blocked" | "defi_positions_stale" | "defi_positions_unavailable" | "destination_not_acknowledged" | "destination_read_failed" | "fee_bump_exceeds_cap" | "fee_bump_not_configured" | "forbidden" | "forward_amount_exceeds_balance" | "inner_fee_not_zero" | "integrator_api_not_configured" | "internal_error" | "invalid_address" | "invalid_addresses" | "invalid_body" | "invalid_challenge" | "invalid_decisions" | "invalid_destination" | "invalid_memo" | "invalid_network" | "invalid_owner" | "invalid_rate_limit" | "invalid_request" | "invalid_signature" | "invalid_signed_xdr" | "invalid_source" | "invalid_spender" | "invalid_token" | "invalid_tokens" | "invalid_transaction_xdr" | "invalid_tx_hash" | "issuer_read_failed" | "issuer_supply_not_acknowledged" | "key_limit_reached" | "mediator_key_misconfiguration" | "mediator_not_configured" | "memo_required" | "merge_destination_unusable" | "merged_account_not_found" | "missing_parameters" | "missing_transaction" | "needs_decisions" | "not_found" | "operation_not_sponsorable" | "owner_not_found" | "path_lookup_failed" | "payload_too_large" | "phoenix_trustline_missing" | "plan_failed" | "provider_response_unusable" | "quote_drifted" | "rate_limited" | "registry_expired" | "request_failed" | "revoke_build_failed" | "revoke_needs_restore" | "revoke_simulation_failed" | "revoke_unsafe" | "service_unavailable" | "signer_normalization_unsafe" | "soroban_token_conversion_failed" | "soroban_token_conversion_unavailable" | "soroban_token_conversion_unsafe" | "soroban_token_needs_restore" | "soroban_token_route_lost" | "soroban_token_transfer_failed" | "soroban_token_transfer_unsafe" | "soroban_token_unreadable" | "soroswap_trustline_missing" | "source_sequence_too_far" | "stats_unavailable" | "submit_failed" | "submit_rejected" | "too_many_addresses" | "transaction_structure_not_allowed" | "transactions_failed" | "transfer_destination_missing" | "transfer_destination_unusable" | "trustline_cannot_be_left" | "trustline_deauthorized_with_balance" | "trustline_maintain_liabilities_with_balance" | "tx_not_verified" | "unauthorized" | "unprocessable_entity" | "unsupported_media_type" | "unsupported_memo_type" | "vault_undercollateralized" | "withdraw_before_repay";
+export declare type ErrorCode = "account_not_found" | "account_read_failed" | "account_too_large" | "admin_api_not_configured" | "allowances_read_failed" | "api_key_not_found" | "aquarius_trustline_missing" | "backstop_emissions_unclaimed" | "backstop_token_unconvertible" | "backstop_withdrawal_cooling_down" | "backstop_withdrawal_not_queued" | "bad_request" | "blend_emissions_trustline_missing" | "blend_repay_asset_balance_unknown" | "blend_repay_asset_missing" | "claimable_balance_not_claimable_now" | "claimable_balance_reserve_short" | "claimable_balances_too_many" | "close_fee_balance_short" | "confirmation_timeout" | "conversion_floor_missing" | "conversion_impact_not_acknowledged" | "conversion_provider_unrecognized" | "defi_exit_blocked" | "defi_exit_unsupported" | "defi_position_unrecognized" | "defi_positions_blocked" | "defi_positions_stale" | "defi_positions_unavailable" | "destination_not_acknowledged" | "destination_read_failed" | "fee_bump_exceeds_cap" | "fee_bump_not_configured" | "forbidden" | "forward_amount_exceeds_balance" | "inner_fee_not_zero" | "integrator_api_not_configured" | "internal_error" | "invalid_address" | "invalid_addresses" | "invalid_body" | "invalid_challenge" | "invalid_decisions" | "invalid_destination" | "invalid_label" | "invalid_memo" | "invalid_network" | "invalid_networks" | "invalid_owner" | "invalid_plan_hash" | "invalid_rate_limit" | "invalid_request" | "invalid_signature" | "invalid_signed_xdr" | "invalid_source" | "invalid_spender" | "invalid_token" | "invalid_tokens" | "invalid_transaction_xdr" | "invalid_tx_hash" | "issuer_read_failed" | "issuer_supply_not_acknowledged" | "key_limit_reached" | "key_network_not_allowed" | "mediator_key_misconfiguration" | "mediator_not_configured" | "memo_required" | "merge_destination_unusable" | "merged_account_not_found" | "missing_parameters" | "missing_transaction" | "needs_decisions" | "not_found" | "operation_not_sponsorable" | "owner_not_found" | "path_lookup_failed" | "payload_too_large" | "phoenix_trustline_missing" | "plan_failed" | "provider_response_unusable" | "quote_drifted" | "rate_limited" | "registry_expired" | "request_failed" | "revoke_build_failed" | "revoke_needs_restore" | "revoke_simulation_failed" | "revoke_unsafe" | "route_lookup_unavailable" | "service_unavailable" | "signer_normalization_unsafe" | "soroban_token_conversion_failed" | "soroban_token_conversion_unavailable" | "soroban_token_conversion_unsafe" | "soroban_token_needs_restore" | "soroban_token_route_lost" | "soroban_token_transfer_failed" | "soroban_token_transfer_unsafe" | "soroban_token_unreadable" | "soroswap_trustline_missing" | "source_sequence_too_far" | "sponsor_source_unusable" | "sponsorship_budget_exhausted" | "state_changed" | "stats_unavailable" | "submit_failed" | "submit_rejected" | "time_bounds_required" | "too_many_addresses" | "transaction_expired" | "transaction_structure_not_allowed" | "transactions_failed" | "transfer_destination_missing" | "transfer_destination_unusable" | "trustline_cannot_be_left" | "trustline_deauthorized_with_balance" | "trustline_maintain_liabilities_with_balance" | "tx_not_verified" | "unauthorized" | "unprocessable_entity" | "unsupported_media_type" | "unsupported_memo_type" | "vault_undercollateralized" | "withdraw_before_repay";
+
+/** One exchange in the registry: whether a close into it needs the mediator, and its memo rule. */
+export declare interface ExchangeRegistryEntry {
+    address: string;
+    name: string;
+    domain: string;
+    requiresMediator: boolean;
+    requiresMemo: boolean;
+    /** The required memo type, if `requiresMemo` is true. */
+    memoType: "text" | "id" | "hash";
+}
 
 /** One transaction the close is expected to take. */
 export declare interface ExecutionTxBreakdown {
@@ -521,7 +778,7 @@ export declare interface ExecutionTxBreakdown {
     reason?: "op_batch" | "defi_dependency";
 }
 
-/** Response from `POST /:network/fee-bump/sponsor`. */
+/** Response from `POST /v1/:network/fee-bump/sponsor`. */
 export declare interface FeeBumpSponsorResponse {
     transaction: string;
 }
@@ -534,6 +791,31 @@ export declare interface FxdaoCdpPosition extends DefiPositionBase {
     denomination: string;
     collateralAmount: string;
     debtAmount: string;
+    /** The denomination's registered stablecoin (`Currency(denomination).contract`), the token a
+     *  repay burns. Read from the vault. */
+    debtToken?: string;
+}
+
+/** One indicator of `GET /health/deep`: `rpc_<network>` carries `responseTime` in ms (and a fixed
+ *  `message`, `"timeout"` or `"unreachable"`, when down); `exchange_registry` carries
+ *  `daysRemaining`, negative once the registry has expired. */
+export declare interface HealthDeepIndicator {
+    status: "up" | "down";
+    responseTime?: number;
+    message?: string;
+    daysRemaining?: number;
+}
+
+/**
+ * Body of `GET /health/deep`. It answers 200 with `status: "ok"` when Stellar RPC is reachable on
+ * every network, and 503 with this same shape and `status: "error"` when it is not: the indicators
+ * that failed are in `error`, the rest in `info`, and every one of them in `details`.
+ */
+export declare interface HealthDeepResponse {
+    status: "ok" | "error";
+    info: Record<string, HealthDeepIndicator>;
+    error: Record<string, HealthDeepIndicator>;
+    details: Record<string, HealthDeepIndicator>;
 }
 
 /** Response from `GET /health`. */
@@ -549,6 +831,72 @@ export declare class InsufficientSignatureWeightError extends Error {
     constructor(pending: PendingRound);
 }
 
+/** Response from `POST /v1/integrator/auth/challenge`: a SEP-53 message for the wallet to sign. */
+export declare interface IntegratorChallengeResponse {
+    message: string;
+    /** ISO 8601 time after which the challenge is rejected. */
+    expiresAt: string;
+}
+
+/** Response from `GET /v1/integrator/keys`. `usage` is null when the counts are unavailable. */
+export declare interface IntegratorKeyList {
+    keys: IntegratorKeyListEntry[];
+    usage: IntegratorOwnerUsage | null;
+}
+
+/** One entry of `GET /v1/integrator/keys`. `usage` is null when the counts are unavailable. */
+export declare interface IntegratorKeyListEntry extends IntegratorKeyRecord {
+    usage: IntegratorKeyUsage | null;
+}
+
+/** An API key as the integrator routes describe it. Never carries the raw secret. */
+export declare interface IntegratorKeyRecord {
+    /** The key's id (the SHA-256 hash of the secret). */
+    id: string;
+    /** ISO 8601. */
+    createdAt: string;
+    /** ISO 8601, or null while the key is active. */
+    revokedAt: string | null;
+    /** The previous key's id, if this key replaced one. */
+    rotatedFrom: string | null;
+    label: string | null;
+    /** The networks the key may call, or null for every network. */
+    networks: Network[] | null;
+    /** ISO 8601 time the key last authenticated a request, or null. Written at most once a minute. */
+    lastUsedAt: string | null;
+}
+
+/** One key's request counts. `rateLimitedLast30Days` counts 429s and is not part of the others. */
+export declare interface IntegratorKeyUsage {
+    today: number;
+    last30Days: number;
+    rateLimitedLast30Days: number;
+}
+
+/** A wallet's request counts, shared by all its keys. */
+export declare interface IntegratorOwnerUsage {
+    today: number;
+    last30Days: number;
+}
+
+/** Body for `POST /v1/integrator/auth/session`. */
+export declare interface IntegratorSessionRequest {
+    /** The Stellar account (G...) that signed the challenge. */
+    address: string;
+    /** The challenge message exactly as returned by the challenge call. */
+    message: string;
+    /** Base64 ed25519 signature over the SEP-53 digest of the message. */
+    signature: string;
+}
+
+/** Response from `POST /v1/integrator/auth/session`. */
+export declare interface IntegratorSessionResponse {
+    /** Bearer token for the key-management endpoints. */
+    token: string;
+    /** ISO 8601 time after which the token is rejected, 30 minutes after issue. */
+    expiresAt: string;
+}
+
 export declare type IntentOperation = IntentOperationBody & {
     source: string;
 };
@@ -635,10 +983,21 @@ export declare function isApiErrorCode<C extends ApiErrorCode>(error: unknown, c
     code: C;
 };
 
+/** True for an answer that says the request was refused, so nothing went on. Everything else, a
+ *  5xx, a timeout, a dropped connection or an unreadable body, leaves the outcome unknown. */
+export declare function isSubmitRefused(error: unknown): boolean;
+
+/** Response from `POST /v1/integrator/keys` and `POST /v1/integrator/keys/{id}/rotate`. `key` is
+ *  the raw secret, returned exactly once and never retrievable again. */
+export declare interface IssuedIntegratorKey {
+    key: string;
+    record: IntegratorKeyRecord;
+}
+
 /** Thrown when the caller's `signal` aborts a request. Distinct from a timeout. */
 export declare class LumenWipeAbortError extends Error {
-    readonly reason?: unknown | undefined;
-    constructor(reason?: unknown | undefined);
+    readonly reason?: unknown;
+    constructor(reason?: unknown);
 }
 
 /** Thrown when the API responds with a non-2xx status. `body` is the parsed error payload. */
@@ -664,13 +1023,25 @@ export declare class LumenWipeClient {
     private warnedDefaultNetwork;
     constructor(options: LumenWipeClientOptions);
     private resolveNetwork;
+    /** The `/v1/{network}` path for `rest`. The network is checked before any request is built. */
+    private v1;
     health(options?: RequestOptions): Promise<HealthResponse>;
+    /** Whether Stellar RPC is reachable on every network, and the days left on the exchange registry.
+     *  A degraded service answers 503, thrown as a `LumenWipeApiError` whose `body` is a
+     *  `HealthDeepResponse` with `status: "error"`. Never retried: the 503 is the answer. */
+    healthDeep(options?: RequestOptions): Promise<HealthDeepResponse>;
+    /** The exchange registry the API closes against. Do not rely on it past `validUntil`. */
+    getExchangeRegistry(options?: RequestOptions): Promise<ServedExchangeRegistry>;
     getAccount(address: string, network?: Network, options?: RequestOptions): Promise<AccountState>;
     getPaths(params: {
         fromAsset: string;
         amount: string;
     }, network?: Network, options?: RequestOptions): Promise<PathResponse>;
     closePlan(body: ClosePlanRequest, network?: Network, options?: RequestOptions): Promise<PlanResponse>;
+    /** Plans up to 20 accounts into one shared destination in one call. Read-only: no decisions are
+     *  applied, so plan each account with `closePlan` before closing it. An address that cannot be
+     *  read or planned comes back as a `blocked` plan, never as a missing entry. */
+    batchPlan(body: BatchPlanRequest, network?: Network, options?: RequestOptions): Promise<BatchPlanResponse>;
     /**
      * Builds the next unsigned transaction(s) for a close. A close can span several
      * transactions (a single transaction, or separate claim / cleanup / mediator-merge steps),
@@ -680,6 +1051,17 @@ export declare class LumenWipeClient {
      */
     closeTransactions(body: CloseTransactionsRequest, network?: Network, options?: RequestOptions): Promise<TransactionsResponse>;
     submit(signedXdr: string, network?: Network, options?: RequestOptions): Promise<SubmitResponse>;
+    /** Looks a transaction up by hash and sends nothing. `not_found` is not "did not land": the
+     *  transaction may be queued, or older than the window the response names. */
+    getTransaction(hash: string, network?: Network, options?: RequestOptions): Promise<TransactionLookupResponse>;
+    /** A close's phase and remaining work, from live state. Informational: a close is finished only
+     *  when the hash of the merge you signed is confirmed by `getTransaction`. */
+    closeStatus(source: string, network?: Network, options?: RequestOptions): Promise<CloseStatusResponse>;
+    /** The XLM confirmed close transactions delivered to `destination`, read from each one's ledger
+     *  result: a merge into it, or the relay account's forward of a merged balance. A hash that
+     *  cannot be read as delivered is an `unavailable` entry, not an error, and `totalStroops` is
+     *  set only when every entry is `delivered`. Pass 1 to 20 distinct hashes. */
+    closeDelivered(destination: string, hashes: readonly string[], network?: Network, options?: RequestOptions): Promise<CloseDeliveredResponse>;
     mediatorCheck(address: string, network?: Network, options?: RequestOptions): Promise<MediatorCheckResult>;
     mediatorSign(transaction: string, network?: Network, options?: RequestOptions): Promise<MediatorSignResponse>;
     /** Wraps a wind-down transaction (its own fee already zero) in a signed CAP-15 fee-bump
@@ -696,6 +1078,15 @@ export declare class LumenWipeClient {
         token: string;
         spender: string;
     }, network?: Network, options?: RequestOptions): Promise<RevokeAllowanceResponse>;
+    /** Accounts closed and XLM recovered through LumenWipe on the network. */
+    getStats(network?: Network, options?: RequestOptions): Promise<StatsTotals>;
+    /** The totals, the most recent closes and the daily activity on the network. */
+    getStatsFeed(network?: Network, options?: RequestOptions): Promise<StatsFeed>;
+    /** Counts a confirmed close that was submitted outside this API. The API re-reads the
+     *  transaction and counts it only if it built it, it confirmed and it merged an account;
+     *  `counted` is false for a hash already counted. Closes sent through `submit()` are counted
+     *  without this. */
+    recordMerge(txHash: string, network?: Network, options?: RequestOptions): Promise<RecordMergeResponse>;
 }
 
 export declare interface LumenWipeClientOptions {
@@ -709,12 +1100,57 @@ export declare interface LumenWipeClientOptions {
     fetch?: FetchLike;
     /** Per-request timeout in milliseconds. Defaults to 30000. `0`/`Infinity` disables it. */
     timeout?: number;
-    /** Opt-in retries. Off by default; never applied to `submit` or `mediatorSign`. */
+    /** Opt-in retries. Off by default; never applied to `submit`, `mediatorSign` or `healthDeep`. */
     retry?: RetryOptions;
     /** Receives one-time notices (plaintext `baseUrl`, defaulted network). Defaults to `console.warn`. */
     logger?: (message: string) => void;
 }
 
+/**
+ * Wallet-authenticated self-service API key management, kept apart from `LumenWipeClient` so the
+ * main client stays small. It takes no API key and never sends one: the challenge and session
+ * calls carry no `Authorization`, and the key calls carry only the session token passed to them.
+ *
+ * Sign in by signing the `challenge(address)` message with the wallet (SEP-53) and exchanging it
+ * through `session(...)` for a token valid for 30 minutes. Every key belongs to that wallet.
+ */
+export declare class LumenWipeIntegratorClient {
+    private readonly http;
+    constructor(options: LumenWipeIntegratorClientOptions);
+    /** A SEP-53 message for `address` (G...) to sign, valid until `expiresAt`. */
+    challenge(address: string, options?: RequestOptions): Promise<IntegratorChallengeResponse>;
+    /** Exchanges the signed challenge for a session token. */
+    session(request: IntegratorSessionRequest, options?: RequestOptions): Promise<IntegratorSessionResponse>;
+    /** The wallet's keys, each with its own request counts, and the wallet's total counts. */
+    listKeys(token: string, options?: RequestOptions): Promise<IntegratorKeyList>;
+    /** Creates a key, optionally named and limited to some networks. The raw `key` is in this
+     *  response only and can never be read again. */
+    createKey(token: string, request?: CreateIntegratorKeyRequest, options?: RequestOptions): Promise<IssuedIntegratorKey>;
+    /** Revokes one of the wallet's keys by its `id`. */
+    revokeKey(token: string, id: string, options?: RequestOptions): Promise<RevokedIntegratorKey>;
+    /** Revokes a key and issues its replacement, keeping its label and networks. The new raw `key`
+     *  is in this response only. */
+    rotateKey(token: string, id: string, options?: RequestOptions): Promise<IssuedIntegratorKey>;
+}
+
+export declare interface LumenWipeIntegratorClientOptions {
+    /** Base URL of the LumenWipe API, e.g. `https://api.lumenwipe.com`. */
+    baseUrl: string;
+    /** Custom fetch (for environments without a global `fetch`, or for testing). */
+    fetch?: FetchLike;
+    /** Per-request timeout in milliseconds. Defaults to 30000. `0`/`Infinity` disables it. */
+    timeout?: number;
+    /** Opt-in retries. Off by default; never applied to creating, revoking or rotating a key. */
+    retry?: RetryOptions;
+    /** Receives one-time notices (plaintext `baseUrl`). Defaults to `console.warn`. */
+    logger?: (message: string) => void;
+}
+
+/** Thrown before any request when `network` is not `"mainnet"` or `"testnet"`. */
+export declare class LumenWipeInvalidNetworkError extends Error {
+    constructor();
+}
+
 /** Thrown when a request exceeds the configured timeout. */
 export declare class LumenWipeTimeoutError extends Error {
     readonly timeoutMs: number;
@@ -733,7 +1169,7 @@ export declare interface MediatorCheckResult {
     registryFresh: boolean;
 }
 
-/** Response from `POST /:network/mediator/sign`. */
+/** Response from `POST /v1/:network/mediator/sign`. */
 export declare interface MediatorSignResponse {
     transaction: string;
 }
@@ -758,7 +1194,7 @@ export declare interface OpenOffer {
     price: string;
 }
 
-/** Response from `GET /:network/paths`. */
+/** Response from `GET /v1/:network/paths`. */
 export declare interface PathResponse {
     path: ConversionPath | null;
 }
@@ -774,12 +1210,23 @@ export declare interface PendingRound {
     accumulatedWeight: number;
     queue: CloseTransaction[];
     requiresAnotherCall: boolean;
+    /** Zero-based round of the run that stopped, as its progress events numbered it. Set by
+     *  `runClose`; a resume without it counts from round 0. */
+    round?: number;
+    /** Zero-based position of `tx` in its batch. Set by `runClose`; 0 when absent. */
+    txIndex?: number;
+    /** How many transactions that batch held. Set by `runClose`; when absent, `txIndex + 1` plus
+     *  the length of `queue`. */
+    txCount?: number;
 }
 
 export declare interface PhoenixLpPosition extends DefiPositionBase {
     protocol: "phoenix";
     positionType: "lp";
     shareAmount: string;
+    /** The pool's LP share token (`CONFIG.share_token`): a separate contract in Phoenix, where the
+     *  account's shares live and what a withdrawal transfers back to the pool. Read from the pool. */
+    shareToken?: string;
 }
 
 export declare interface PhoenixStakePosition extends DefiPositionBase {
@@ -863,6 +1310,11 @@ export declare interface QuoteInfo {
     expiresAtLedger: number;
 }
 
+/** Body for `POST /v1/:network/stats/merges`. */
+export declare interface RecordMergeRequest {
+    txHash: string;
+}
+
 /** Response from `POST /v1/:network/stats/merges`. `counted` is false for an already-counted hash. */
 export declare interface RecordMergeResponse {
     counted: boolean;
@@ -873,6 +1325,11 @@ export declare interface RequestOptions {
     signal?: AbortSignal;
 }
 
+/** Settles a submission by its own hash. A lookup that fails, or that answers for another hash,
+ *  settles nothing. The ledger close time in a `not_found` only ever delays giving up: past the
+ *  deadline by both clocks is the only way out, so neither clock can end the wait early alone. */
+export declare function resolveSubmission(submission: UnresolvedSubmission, lookup: (hash: string) => Promise<TransactionLookupResponse>, now?: () => number): Promise<SubmissionOutcome>;
+
 export declare interface RetryOptions {
     /** Total attempts including the first. Values below 2 disable retrying. */
     attempts: number;
@@ -880,11 +1337,16 @@ export declare interface RetryOptions {
     baseDelayMs: number;
 }
 
-/** Response from `POST /:network/allowances/revoke`. */
+/** Response from `POST /v1/:network/allowances/revoke`. */
 export declare interface RevokeAllowanceResponse {
     transaction: string;
 }
 
+/** Response from `POST /v1/integrator/keys/{id}/revoke`. */
+export declare interface RevokedIntegratorKey {
+    status: "revoked";
+}
+
 /**
  * Runs the full multi-round close. Each round: fetch a batch of unsigned transactions,
  * verify every one before signing, sign it, and submit only once its accumulated signing
@@ -893,7 +1355,22 @@ export declare interface RevokeAllowanceResponse {
  * envelope once a different signer is available. Pass that error's `.pending` back in as
  * `resume` to continue exactly where it stopped.
  */
-export declare function runClose(deps: CloseEngineDeps, resume?: PendingRound): Promise<void>;
+export declare function runClose(deps: CloseEngineDeps, resume?: PendingRound): Promise<CloseRunResult>;
+
+/**
+ * Response from `GET /v1/config/exchange-registry`. A consumer must refuse to rely on it past
+ * `validUntil` (YYYY-MM-DD): a close into an exchange with the wrong memo rule succeeds on-chain and
+ * is credited to nobody.
+ */
+export declare interface ServedExchangeRegistry {
+    version: string;
+    /** The date every entry was last checked against the exchanges' own deposit docs. */
+    lastVerified: string;
+    /** After this date the data is treated as unusable, not merely old. */
+    validUntil: string;
+    source: string;
+    entries: ExchangeRegistryEntry[];
+}
 
 /** A SEP-41 token balance the account holds in a contract's storage - not a classic trustline. */
 export declare interface SorobanTokenBalance {
@@ -979,6 +1456,14 @@ export declare type SponsoredEntry = {
     balanceId: string;
 };
 
+/** How long `runClose` waits before each of those re-fetches: about one ledger close, the time a
+ *  lagging read provider needs to catch up with a transaction that just confirmed. */
+export declare const STATE_CHANGED_REFETCH_DELAY_MS = 3000;
+
+/** How many times a round the API refused as `state_changed` is fetched again before the close
+ *  stops and asks for a new plan. */
+export declare const STATE_CHANGED_REFETCHES = 2;
+
 /** Response from `GET /v1/:network/stats/feed`. `daily` is oldest first, one entry per day. */
 export declare interface StatsFeed {
     totals: StatsTotals;
@@ -1027,6 +1512,40 @@ export declare interface SubInvocationCall {
     args: string[];
 }
 
+/** How long past a transaction's time bounds it is still treated as able to land. Absorbs a
+ *  client clock running ahead, and the ledger close that decides whether it was in time. */
+export declare const SUBMISSION_GIVE_UP_MARGIN_SECONDS = 120;
+
+/** Whether a submission is the close's merge. Only ever true for a merge the client parsed. */
+export declare const submissionClosesAccount: (submission: UnresolvedSubmission) => boolean;
+
+export declare type SubmissionOutcome = {
+    outcome: "confirmed";
+} | {
+    outcome: "failed";
+    message: string;
+} | {
+    outcome: "expired";
+} | {
+    outcome: "unknown";
+};
+
+/** How many more times a transaction whose outcome is unknown is sent, as the same bytes. */
+export declare const SUBMIT_RESEND_ATTEMPTS = 2;
+
+/** How long `runClose` waits before each of those: about one ledger close. */
+export declare const SUBMIT_RESEND_DELAY_MS = 5000;
+
+/**
+ * `error.details` of a `confirmation_timeout` from `POST /v1/:network/submit`. It is an error, not
+ * a 2xx, because a client that reads `hash` from a success would count the transaction confirmed.
+ * Compute the hash from the envelope you signed rather than taking this one on trust.
+ */
+export declare interface SubmitPendingDetails {
+    status: "pending";
+    hash: string;
+}
+
 /** Body for `POST /v1/:network/submit`. */
 export declare interface SubmitRequest {
     signedXdr: string;
@@ -1039,6 +1558,50 @@ export declare interface SubmitResponse {
     ledger: number;
 }
 
+/**
+ * Why a token's conversion is offered but not recommended (`subject.quote.flags`). Each one makes
+ * converting need the `conversion_impact:<contract>` acknowledgement. `high_impact`: the price
+ * impact is above 5%. `impact_unknown`: no price impact could be measured. `provider_disagreement`:
+ * the best quote is more than 10% above the other provider's.
+ */
+export declare type TokenQuoteFlag = "high_impact" | "impact_unknown" | "provider_disagreement";
+
+/**
+ * Why a held Soroban token was not quoted for conversion: `subject.reason` on its
+ * `asset_disposition` decision point when `subject.convertible` is false. `quote_limit`: past the
+ * first 20 tokens one plan quotes. `provider_unavailable`: a swap provider failed, was rate
+ * limited or ran out of time, so analyzing again may find a route. `no_route`: every provider
+ * consulted answered that it has none. `metadata_unreadable`: the token does not report its
+ * symbol or decimals, so no amount about it can be shown.
+ */
+export declare type TokenUnquotedReason = "quote_limit" | "provider_unavailable" | "no_route" | "metadata_unreadable";
+
+/**
+ * Response from `GET /v1/:network/transactions/:hash`. `not_found` names the ledger window one RPC
+ * provider searched: the transaction may still be queued, or be older than that window. Close times
+ * are unix seconds.
+ */
+export declare type TransactionLookupResponse = {
+    status: "confirmed";
+    hash: string;
+    ledger: number;
+} | {
+    status: "failed";
+    hash: string;
+    ledger: number;
+    message: string;
+    resultCode?: string;
+} | {
+    status: "not_found";
+    hash: string;
+    searched: {
+        oldestLedger: number;
+        oldestLedgerCloseTime: number;
+        latestLedger: number;
+        latestLedgerCloseTime: number;
+    };
+};
+
 export declare interface TransactionsResponse {
     planHash: string;
     status: CloseApiStatus;
@@ -1052,6 +1615,17 @@ export declare interface TransactionsResponse {
         steps: number;
         requiresAnotherCall: boolean;
     };
+    /**
+     * The closing account's signers and thresholds as read at the start of this round, the read
+     * the transactions were built from. A transaction can change them (signer normalization), so a
+     * client judges signing weight against this, with each confirmed `SetOptions` of the round
+     * applied on top, rather than against an earlier read. Absent from responses produced before
+     * this field existed.
+     */
+    sourceAccount?: {
+        signers: AccountSigner[];
+        thresholds: AccountThresholds;
+    };
 }
 
 /**
@@ -1114,4 +1688,19 @@ export declare interface UnrecognizedDefiPosition {
     reason: string;
 }
 
+/**
+ * A transaction handed to the network whose outcome is not settled. Never holds the envelope: a
+ * refresh looks this hash up, and does not send anything again. `covers` names a merge only when
+ * the client parsed one out of the envelope it signed.
+ */
+export declare interface UnresolvedSubmission {
+    /** Computed by the client from the final envelope, never taken from the API. */
+    hash: string;
+    covers: CloseTransaction["covers"];
+    /** Unix seconds after which the transaction cannot land; null when it has no time bounds. */
+    validUntil: number | null;
+    coversTargets?: string[];
+    needsSponsoredFee?: boolean;
+}
+
 export { }