@lumenwipe/sdk 0.1.0 → 0.5.1

package/dist/index.d.cts

@@ -36,6 +36,20 @@ export declare interface AccountState {
      *  numSubEntries on this account; populated via the Horizon adapter. */
     claimableBalances: ClaimableBalance[];
     subEntryMismatch: boolean;
+    /** 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
+     *  with a null `timestamp` and reflected in `defiPositionsWarnings` rather than being omitted. */
+    defiPositions: DefiPositionsResult;
+    /** Plain-language notices from `assessDefiPositionsGate` (issue #147) - stale/unconfirmed data
+     *  or an unrecognized position - reusing the exact same typed-blocker signal close/plan already
+     *  gates on, so the analysis view and the plan never disagree about what's trustworthy. Empty
+     *  when nothing needs flagging. */
+    defiPositionsWarnings: PlanBlocker[];
+    /** Soroban token balances held directly, best effort (see `SorobanTokensResult`). Absent on
+     *  account reads produced before this field existed; a consumer treats absence as "nothing
+     *  known", never as "nothing held". */
+    sorobanTokens?: SorobanTokensResult;
 }
 
 export declare interface AccountThresholds {
@@ -44,16 +58,134 @@ export declare interface AccountThresholds {
     high: number;
 }
 
-export declare type ApiErrorBody = StructuredApiError | PlainApiError;
+/**
+ * A live, non-zero SEP-41 allowance the account has granted a spender on one token
+ * (architecture.md §12). The amount always comes from a live `allowance(from, spender)` read -
+ * `approve` neither decrements on spend nor is the only way the amount could have changed since
+ * it was set, so the event that discovered the pair is never trusted for the amount itself.
+ */
+export declare interface Allowance {
+    /** The token contract, `C...`. */
+    token: string;
+    /** From the token's own `symbol()`, null when it does not answer. */
+    tokenSymbol: string | null;
+    /** From the token's own `decimals()`, null when it does not answer. */
+    tokenDecimals: number | null;
+    /** The approved spender. Almost always a contract (`C...`) - a DeFi protocol - but SEP-41's
+     *  `approve(from, spender, ...)` types `spender` as `Address`, so a plain account (`G...`) is a
+     *  legitimate, if unusual, spender too. */
+    spender: string;
+    /** The spender's protocol, when its address resolves to a known DeFi contract registry entry
+     *  on this network. Null does not mean unsafe - most legitimate spenders (a specific vault, an
+     *  integrator's own contract) are simply not in the registry. */
+    spenderProtocol: DefiProtocol | null;
+    /** Base units, integer string, as `allowance(from, spender)` reports it live on the ledger. */
+    amount: string;
+    /** The ledger this allowance expires at, from the most recent `approve` event that discovered
+     *  this pair. Null when the amount is confirmed live but no `approve` event for this exact pair
+     *  was found within the event scan's retention window (e.g. approved long enough ago that the
+     *  event has aged out) - the amount is still ground truth, the expiration simply is not
+     *  observable from this discovery path, since SEP-41's `allowance()` returns only the amount. */
+    expirationLedger: number | null;
+    /** Every source that proposed this pair. */
+    sources: AllowanceSource[];
+}
+
+/** How one candidate source fared, so the interface can say exactly what was consulted. */
+export declare interface AllowanceCoverage {
+    source: AllowanceSource;
+    status: "ok" | "failed" | "skipped";
+    detail?: string;
+}
+
+/** Where an allowance candidate (token, spender) pair came from before its live amount was
+ *  confirmed on the ledger. */
+export declare type AllowanceSource = "events" | "registry";
+
+/**
+ * Every live allowance the account has granted, across every token it has approved anything on.
+ * Soroban has no on-chain index of an account's approvals, so this is a best-effort union of
+ * candidate (token, spender) pairs - recent `approve` events naming this account as `from`, and
+ * the known DeFi contract registry's spenders crossed with a small curated token list - each
+ * confirmed by reading `allowance(from, spender)` on the ledger. A zero allowance, live or never
+ * granted, is not reported: only what is actually outstanding right now.
+ */
+export declare interface AllowancesResult {
+    allowances: Allowance[];
+    coverage: AllowanceCoverage[];
+    /** The ledger range the event scan covered, or null when it ran out of budget before starting. */
+    eventsScanned: {
+        fromLedger: number;
+        toLedger: number;
+    } | null;
+    /** Plain-language warnings: a source that failed, candidates dropped by the cap. */
+    warnings: PlanBlocker[];
+}
+
+export declare type ApiErrorBody = StructuredApiError;
+
+/** An `ErrorCode` the API can return, or `"upstream_error"` for a non-JSON failure from a proxy
+ *  or CDN in front of it. The open `string` arm keeps a newer API's code from breaking a build. */
+export declare type ApiErrorCode = ErrorCode | "upstream_error" | (string & {});
+
+export declare interface AquariusLpPosition extends DefiPositionBase {
+    protocol: "aquarius";
+    positionType: "lp";
+    shareAmount: string;
+    /** Reported by OctoPos alongside the LP position rather than as its own position. */
+    claimableAquaAmount?: string;
+    /** The pool's tokens in the pool's own order - the order `withdraw` pays them out and
+     *  `min_amounts` is given in. Read from the pool when detection can. */
+    tokens?: string[];
+    /** The pool's LP share token: a separate contract in Aquarius, where the account's shares live. */
+    shareToken?: string;
+    /** Which pool code the pool runs, from the registry. */
+    poolType?: AquariusPoolType;
+}
+
+/** Aquarius deploys three pool codes; only the share-based ones can be exited by shares. */
+export declare type AquariusPoolType = "constant_product" | "stable" | "concentrated";
 
 /**
- * What happens to a non-XLM balance before its trustline is removed.
+ * What happens to a non-XLM balance before the account is merged.
  *
  * `convert` swaps it to XLM and `issuer` sends it back to be burned - both end the close with the
  * position destroyed. `transfer` keeps the asset, as the asset, by paying it to another account
- * that already holds the trustline.
+ * (one that already holds the trustline, for a classic asset). `leave` applies only to a Soroban
+ * token balance, which sits in the token contract's storage and does not stop a merge: the user
+ * acknowledges that it stays with this address, recoverable only by funding the same key again.
+ * A classic trustline can never be left - the merge fails while it holds a balance.
  */
-export declare type AssetDisposition = "convert" | "issuer" | "transfer";
+export declare type AssetDisposition = "convert" | "issuer" | "transfer" | "leave";
+
+export declare interface BatchPlanResponse {
+    results: BatchPlanResult[];
+}
+
+/** One address's plan within a batch call - always present, even when the account could not be
+ *  read or planned safely (that failure surfaces as a `blocked` plan with its own blocker,
+ *  never as a missing entry). */
+export declare interface BatchPlanResult {
+    address: string;
+    plan: PlanResponse;
+}
+
+export declare interface BlendBorrowPosition extends DefiPositionBase {
+    protocol: "blend";
+    positionType: "borrow";
+    assetAddress: string;
+    dTokenAmount: string;
+    healthFactor?: string;
+}
+
+export declare interface BlendSupplyPosition extends DefiPositionBase {
+    protocol: "blend";
+    positionType: "supply";
+    assetAddress: string;
+    bTokenAmount: string;
+    /** True when this supply is also posted as backstop collateral. */
+    isBackstop?: boolean;
+}
 
 export declare interface BuildPlanResult {
     steps: PlannedStep[];
@@ -127,7 +259,14 @@ export declare interface CloseEngineDeps {
     /** Called after a transaction confirms, with the transaction and its hash. */
     onConfirmed?: (tx: CloseTransaction, hash: string) => void;
     onProgress?: (message: string) => void;
-    /** Safety bound so a misbehaving API can never spin the loop forever. */
+    /**
+     * Safety bound so a misbehaving API can never spin the loop 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
+     * any other close path never converges for whatever reason), this stops it after `maxRounds`
+     * with a clear thrown error instead of looping indefinitely.
+     */
     maxRounds?: number;
 }
 
@@ -147,6 +286,24 @@ export declare interface CloseTransaction {
     sourceSequence: string;
     validUntilLedger: number;
     covers: StepType[];
+    /**
+     * Which of the covered steps this transaction is for, by the same identity a plan step carries
+     * (`PlannedStep.affectedContract` for an exit, `affectedAsset` for an asset or token). `covers`
+     * names step TYPES, and a close can hold several steps of one type - three DeFi exits, two
+     * token transfers - so a client marking by type alone marked them all done off one transaction
+     * and stamped them all with its hash. The permanent receipt then listed one exit where three
+     * had run. Absent when the transaction covers every step of the types it names, which is the
+     * only shape an older client ever saw.
+     */
+    coversTargets?: string[];
+    /**
+     * 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
+     * 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.
+     */
+    needsSponsoredFee?: true;
     intent: TxIntent;
 }
 
@@ -171,6 +328,12 @@ export declare interface ConversionPath {
     destMin: string;
 }
 
+export declare interface DailyActivity {
+    /** UTC day, YYYY-MM-DD. */
+    date: string;
+    accountsClosed: number;
+}
+
 export declare interface DataEntry {
     key: string;
     value: string;
@@ -181,6 +344,20 @@ export declare interface DecisionAnswer {
     choice: string;
     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.
+         */
+        minAmountOut?: string;
+        /**
+         * Pinned alongside `minAmountOut`: which provider's quote the user was shown and accepted.
+         * The build re-quotes and builds through exactly this provider, never a different one that
+         * might look better right now but that the user never saw priced (architecture.md, this
+         * feature's spec §5.2).
+         */
+        provider?: "soroswap" | "xbull";
         /**
          * Required by the `transfer_to_account` choice: the `G...` address the balance is paid to.
          *
@@ -210,16 +387,155 @@ export declare interface DecisionPoint {
     required: boolean;
 }
 
+/** Keyed by asset/contract address. Built from OctoPos's queryKeys.tokenInfos. */
+export declare interface DefiEnrichmentEntry {
+    symbol: string;
+    decimals: number;
+    usdPrice: string | null;
+    priceSource: string | null;
+}
+
+export declare type DefiPosition = BlendSupplyPosition | BlendBorrowPosition | AquariusLpPosition | SoroswapLpPosition | PhoenixLpPosition | PhoenixStakePosition | FxdaoCdpPosition;
+
+declare interface DefiPositionBase {
+    protocol: DefiProtocol;
+    /** Pool, market, or vault contract this position lives in. */
+    contractAddress: string;
+    /** Human-readable view of the position, when the analysis could resolve one. */
+    display?: DefiPositionDisplay;
+    /** Left as an optional hook: the wasmHash -\> protocol-version contract registry
+     *  architecture.md describes does not exist in code yet (a later contribution). */
+    wasmHash?: string;
+    usdValue: string | null;
+}
+
+/**
+ * What a person should read about a position, in the protocol's own terms, resolved by the API
+ * from a live read at analysis time (issue #197). Presentation only: every field is nullable, a
+ * failed read leaves the whole object absent, and nothing here feeds the plan, the gate, or an
+ * exit - those re-read the ledger themselves.
+ */
+export declare interface DefiPositionDisplay {
+    /** The pool, pair, or vault by name (the protocol's own metadata or the registry label). */
+    pool: string | null;
+    /** Symbol of the position's asset; for an LP position the pair, e.g. "XLM/USDC". */
+    asset: string | null;
+    /** Underlying amount in the asset's own units as a decimal string - not shares or bTokens. */
+    amount: string | null;
+    /** The part of `amount` posted as collateral (lending protocols), decimal string; null when
+     *  the protocol has no such distinction. */
+    collateralAmount: string | null;
+    /** Current yield as a percentage with two decimals ("3.99"): earned on a supply, paid on debt. */
+    yieldPct: string | null;
+    yieldKind: "earned" | "paid" | null;
+    /** One protocol-specific clause the line ends with, e.g. what an LP share is worth in its two
+     *  tokens ("9.95 XLM + 19.90 USDC"). Null when there is nothing to add. */
+    detail?: string | null;
+}
+
+/**
+ * The normalized DeFi position model every downstream consumer (exit adapters, plan preview)
+ * depends on - no OctoPos-specific field names beyond this boundary (architecture.md §7.1).
+ */
+export declare interface DefiPositionsResult {
+    address: string;
+    network: Network;
+    positions: DefiPosition[];
+    unrecognizedPositions: UnrecognizedDefiPosition[];
+    enrichment: Record<string, DefiEnrichmentEntry>;
+    /** OctoPos's own freshness/provenance signal ("snapshot" | "empty" | "cache" | "not-tracked").
+     *  Passed through verbatim rather than architecture.md's described (but not actually shipped)
+     *  partial_result/attribution_confidence fields - see issue #147 for the gating that consumes
+     *  this. */
+    source: string;
+    timestamp: string | null;
+    queryKeys: DefiQueryKeys;
+}
+
+/**
+ * Lowercased from OctoPos's own SUPPLY/BORROW/LP/STAKE tags. FxDAO's COLLATERAL+BORROW pair is
+ * one vault - one exit unit per architecture.md §9.7 - so it collapses to a single "cdp" position
+ * carrying both legs rather than two positions. WALLET positions are out of scope: classic
+ * balances already come from AccountState.trustlines, and Soroban token balance handling is a
+ * separate Phase-2 deliverable, not this epic.
+ */
+export declare type DefiPositionType = "supply" | "borrow" | "lp" | "cdp" | "stake";
+
+/**
+ * Protocols LumenWipe knows how to act on: most are DeFi positions it knows how to exit
+ * (architecture.md §9's table); `xbull` is the one exception, a swap router with no position to
+ * exit, registered here only so it can share the contract registry's protocol-keyed lookups.
+ * OctoPos itself indexes more than this (e.g. "untangled-vault", "stellar-wallet") - those are
+ * dropped by the adapter rather than represented here, since the type system should not claim
+ * LumenWipe can act on a protocol it has no exit path for.
+ */
+export declare type DefiProtocol = "blend" | "aquarius" | "soroswap" | "phoenix" | "fxdao" | "xbull";
+
+export declare interface DefiQueryKeys {
+    rpcEndpoints: DefiRpcEndpoint[];
+    rpcPolicy: DefiRpcPolicy;
+    slices: Partial<Record<DefiProtocol, DefiQueryKeysSlice>>;
+}
+
+/**
+ * Ready-made ledger keys plus pool/vault metadata for one protocol, letting a caller read
+ * positions directly over RPC without OctoPos storing anything server-side (architecture.md
+ * §7.1). Passed through typed rather than discarded, since issue #148's RPC fallback needs
+ * exactly this and would otherwise have to refetch it.
+ */
+export declare interface DefiQueryKeysSlice {
+    protocol: string;
+    ledgerKeys: string[];
+    poolAddresses: string[];
+}
+
+/** A public Soroban RPC endpoint OctoPos suggests for a direct getLedgerEntries read. */
+export declare interface DefiRpcEndpoint {
+    url: string;
+    health: string;
+    avgLatencyMs: number;
+}
+
+export declare interface DefiRpcPolicy {
+    maxKeysPerCall: number;
+    recommendedConcurrency: number;
+    backoffOn429Ms: number[];
+    timeoutMs: number;
+}
+
 export declare type DemolishPhase = "IDLE" | "ANALYZING" | "PREFLIGHT_COMPLETE" | "SIGNER_SETUP" | "STEP_EXECUTING" | "STEP_CONFIRMED" | "STEP_FAILED" | "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" | "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" | "tx_not_verified" | "unauthorized" | "unprocessable_entity" | "unsupported_media_type" | "unsupported_memo_type" | "vault_undercollateralized" | "withdraw_before_repay";
+
+/** One transaction the close is expected to take. */
 export declare interface ExecutionTxBreakdown {
+    /** Position among the transactions, from 0, in the order they are built and submitted. */
     order: number;
+    /** The plan step types this transaction carries operations for. */
     covers: StepType[];
     reason?: "op_batch" | "defi_dependency";
 }
 
+/** Response from `POST /:network/fee-bump/sponsor`. */
+export declare interface FeeBumpSponsorResponse {
+    transaction: string;
+}
+
 export declare type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 
+export declare interface FxdaoCdpPosition extends DefiPositionBase {
+    protocol: "fxdao";
+    positionType: "cdp";
+    denomination: string;
+    collateralAmount: string;
+    debtAmount: string;
+}
+
 /** Response from `GET /health`. */
 export declare interface HealthResponse {
     status: string;
@@ -233,16 +549,6 @@ export declare class InsufficientSignatureWeightError extends Error {
     constructor(pending: PendingRound);
 }
 
-/**
- * One operation in a decoded close transaction.
- *
- * `source` is the account the operation acts as - the operation's own source account when it
- * carries one, otherwise the transaction's. It is what lets verification assert relationships
- * *between* operations rather than trusting each in isolation: in a mediated close the forward
- * payment must be sent by the very account the merge just paid into, which is what makes the
- * intermediary a conduit rather than a destination. Without it the only available check is
- * pinning the intermediary's address, which every consumer would then have to be told.
- */
 export declare type IntentOperation = IntentOperationBody & {
     source: string;
 };
@@ -293,15 +599,57 @@ export declare type IntentOperationBody = {
     type: "revoke_sponsorship";
     entryKind: "account" | "trustline" | "offer" | "data_entry" | "signer";
     owner: string;
+} | {
+    type: "invoke_host_function";
+    contract: string;
+    function: string;
+    /** The decoded arguments rendered for a human, in order. */
+    args: string[];
+    /** Every Stellar account (G...) named anywhere in the arguments or in the authorization
+     *  tree the signature would satisfy. A verifier insists these are all the closing account. */
+    accountsReferenced: string[];
+    /** Every contract (C...) named the same way, including nested calls the signature would
+     *  authorize. A verifier insists these are contracts the account is known to deal with. */
+    contractsReferenced: string[];
+    /** Address forms that cannot be pinned to anything (muxed accounts, claimable balances,
+     *  liquidity pools). A verifier refuses any. */
+    unsupportedAddressCount: number;
+    /** True when the signature would authorize more than the account's own plain contract
+     *  calls: another party's credentials, or a contract creation, in the auth entries. */
+    authorizesBeyondSelf: boolean;
+    /** How deep the authorization tree nests: 0 when every entry is a single plain call with
+     *  no sub-invocations, 1 when a call authorizes one level of nested calls, and so on. A
+     *  token transfer must be 0 - the token may not make the account authorize anything else. */
+    authDepth: number;
+    /** Every non-root call in the authorization tree - what the root call (a pool, router, or
+     *  backstop) would itself be authorized to do on the account's behalf, one level down. A
+     *  DeFi exit's top-level contract/function pinning says nothing about these: a hostile
+     *  build could keep a legitimate top-level call while hiding an unrelated transfer here. */
+    subInvocations: SubInvocationCall[];
 } | {
     type: "unknown";
 };
 
+/** Narrows an unknown error to a `LumenWipeApiError` carrying the given `code`. */
+export declare function isApiErrorCode<C extends ApiErrorCode>(error: unknown, code: C): error is LumenWipeApiError & {
+    code: C;
+};
+
+/** 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);
+}
+
 /** Thrown when the API responds with a non-2xx status. `body` is the parsed error payload. */
 export declare class LumenWipeApiError extends Error {
     readonly status: number;
     readonly body: unknown;
-    constructor(status: number, body: unknown);
+    readonly code: ApiErrorCode;
+    readonly details: unknown;
+    readonly retryAfterMs: number | undefined;
+    readonly requestId: string | undefined;
+    constructor(status: number, body: unknown, headers?: Pick<Headers, "get">);
 }
 
 /**
@@ -312,25 +660,42 @@ export declare class LumenWipeApiError extends Error {
 export declare class LumenWipeClient {
     private readonly http;
     private readonly defaultNetwork;
+    private readonly log;
+    private warnedDefaultNetwork;
     constructor(options: LumenWipeClientOptions);
-    health(): Promise<HealthResponse>;
-    getAccount(address: string, network?: Network): Promise<AccountState>;
+    private resolveNetwork;
+    health(options?: RequestOptions): Promise<HealthResponse>;
+    getAccount(address: string, network?: Network, options?: RequestOptions): Promise<AccountState>;
     getPaths(params: {
         fromAsset: string;
         amount: string;
-    }, network?: Network): Promise<PathResponse>;
-    closePlan(body: ClosePlanRequest, network?: Network): Promise<PlanResponse>;
+    }, network?: Network, options?: RequestOptions): Promise<PathResponse>;
+    closePlan(body: ClosePlanRequest, network?: Network, options?: RequestOptions): Promise<PlanResponse>;
     /**
      * Builds the next unsigned transaction(s) for a close. A close can span several
-     * transactions (a fused close, or separate claim / cleanup / mediator-merge steps),
+     * transactions (a single transaction, or separate claim / cleanup / mediator-merge steps),
      * so the response's `remaining.requiresAnotherCall` says whether more follow: sign and
      * submit the returned transactions in `order`, wait for confirmation, then call this
      * again until `requiresAnotherCall` is false.
      */
-    closeTransactions(body: CloseTransactionsRequest, network?: Network): Promise<TransactionsResponse>;
-    submit(signedXdr: string, network?: Network): Promise<SubmitResponse>;
-    mediatorCheck(address: string, network?: Network): Promise<MediatorCheckResult>;
-    mediatorSign(transaction: string, network?: Network): Promise<MediatorSignResponse>;
+    closeTransactions(body: CloseTransactionsRequest, network?: Network, options?: RequestOptions): Promise<TransactionsResponse>;
+    submit(signedXdr: string, network?: Network, options?: RequestOptions): Promise<SubmitResponse>;
+    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
+     *  envelope for an account that cannot pay its own fee (architecture.md §8.1). The caller
+     *  submits the returned XDR through `submit()`, exactly like any other close transaction. */
+    feeBumpSponsor(transaction: string, network?: Network, options?: RequestOptions): Promise<FeeBumpSponsorResponse>;
+    /** Every live SEP-41 allowance the account has granted (architecture.md §12). Independent of
+     *  closing an account - a standalone security utility. */
+    getAllowances(address: string, network?: Network, options?: RequestOptions): Promise<AllowancesResult>;
+    /** Builds the unsigned `approve(owner, spender, 0, 0)` transaction that revokes one allowance.
+     *  The caller signs and submits it through `submit()`, like any other transaction here. */
+    revokeAllowance(params: {
+        owner: string;
+        token: string;
+        spender: string;
+    }, network?: Network, options?: RequestOptions): Promise<RevokeAllowanceResponse>;
 }
 
 export declare interface LumenWipeClientOptions {
@@ -338,12 +703,16 @@ export declare interface LumenWipeClientOptions {
     baseUrl: string;
     /** Integrator API key, sent as `Authorization: Bearer <apiKey>`. */
     apiKey: string;
-    /** Default network for calls that omit it. Defaults to `"testnet"`. */
+    /** Default network for calls that omit it. Defaults to `"testnet"`, with a one-time notice. */
     network?: Network;
     /** 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 `submit` or `mediatorSign`. */
+    retry?: RetryOptions;
+    /** Receives one-time notices (plaintext `baseUrl`, defaulted network). Defaults to `console.warn`. */
+    logger?: (message: string) => void;
 }
 
 /** Thrown when a request exceeds the configured timeout. */
@@ -360,6 +729,8 @@ export declare interface MediatorCheckResult {
     exchangeName: string | null;
     /** Whether the server can actually perform the mediator flow (secret configured). */
     available: boolean;
+    /** Whether the exchange registry is inside its verification window; false means exchange closes are refused. */
+    registryFresh: boolean;
 }
 
 /** Response from `POST /:network/mediator/sign`. */
@@ -367,6 +738,16 @@ export declare interface MediatorSignResponse {
     transaction: string;
 }
 
+/** One verified, counted close transaction. */
+export declare interface MergeRecord {
+    txHash: string;
+    network: Network;
+    accountsClosed: number;
+    xlmStroops: string;
+    /** Ledger close time of the transaction, ISO 8601. */
+    timestamp: string;
+}
+
 export declare type Network = "mainnet" | "testnet";
 
 export declare interface OpenOffer {
@@ -395,10 +776,18 @@ export declare interface PendingRound {
     requiresAnotherCall: boolean;
 }
 
-/** @deprecated The API emits one envelope (`StructuredApiError`). Kept only so a consumer
- *  pinned to an older deployment still type-checks during a rollout; remove once none remain. */
-export declare interface PlainApiError {
-    error: string;
+export declare interface PhoenixLpPosition extends DefiPositionBase {
+    protocol: "phoenix";
+    positionType: "lp";
+    shareAmount: string;
+}
+
+export declare interface PhoenixStakePosition extends DefiPositionBase {
+    protocol: "phoenix";
+    positionType: "stake";
+    stakedAmount: string;
+    /** Unix seconds; unbonding requires the original stake's timestamp (architecture.md §9.6). */
+    stakedAtEpoch: string;
 }
 
 export declare interface PlanBlocker {
@@ -420,7 +809,15 @@ export declare interface PlannedStep {
     status: StepStatus;
     txHash: string | null;
     error: string | null;
+    /** What the user's own account paid for this step, once confirmed - exactly "0" when a
+     *  dedicated sponsor account covered the fee-bump instead. Otherwise the plan-time estimate
+     *  copied forward: the close-engine's confirmation callback carries only a tx hash, not the
+     *  fee Horizon actually charged, so this cannot correct for surge pricing. Absent until the
+     *  step is confirmed. */
+    actualFeeLumens?: string;
     affectedAsset?: string;
+    /** The pool, pair, or vault an EXIT_POSITIONS step leaves. */
+    affectedContract?: string;
     fallbackToIssuer?: boolean;
 }
 
@@ -438,8 +835,19 @@ export declare interface PlanResponse {
         feeStroops: string;
         freedReserveXlm: string;
     };
+    /**
+     * The transactions this close is expected to take, counted with the splitter the builder
+     * packs them with: Soroban token moves, the claim round, the classic close split at the
+     * per-transaction operation cap, and, for an exchange destination, the mediator transfer.
+     *
+     * `estimatedTransactionCount` is `null`, with `transactions` empty, when it cannot be known
+     * yet: the plan has a DeFi exit (its transaction count depends on live debt), a held token has
+     * no decision, or no destination was given. Never read it as a number without checking, and
+     * never show an unknown count as a figure. It is an estimate from the account as planned; the
+     * close re-reads live state each round.
+     */
     execution: {
-        estimatedTransactionCount: number;
+        estimatedTransactionCount: number | null;
         transactions: ExecutionTxBreakdown[];
     };
 }
@@ -455,6 +863,28 @@ export declare interface QuoteInfo {
     expiresAtLedger: number;
 }
 
+/** Response from `POST /v1/:network/stats/merges`. `counted` is false for an already-counted hash. */
+export declare interface RecordMergeResponse {
+    counted: boolean;
+}
+
+export declare interface RequestOptions {
+    /** Aborts the request. Rejects with `LumenWipeAbortError`, distinct from a timeout. */
+    signal?: AbortSignal;
+}
+
+export declare interface RetryOptions {
+    /** Total attempts including the first. Values below 2 disable retrying. */
+    attempts: number;
+    /** Base delay for exponential backoff when the response has no `Retry-After`. */
+    baseDelayMs: number;
+}
+
+/** Response from `POST /:network/allowances/revoke`. */
+export declare interface RevokeAllowanceResponse {
+    transaction: string;
+}
+
 /**
  * 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
@@ -465,6 +895,60 @@ export declare interface QuoteInfo {
  */
 export declare function runClose(deps: CloseEngineDeps, resume?: PendingRound): Promise<void>;
 
+/** A SEP-41 token balance the account holds in a contract's storage - not a classic trustline. */
+export declare interface SorobanTokenBalance {
+    /** The token contract, `C...`. */
+    contract: string;
+    /** Base units, integer string, as `balance(account)` reports it on the ledger. "0" only for a
+     *  token the account does not hold yet but a detected position's exit will pay out. */
+    balance: string;
+    /** From the contract's own `symbol()` / `decimals()`, null when it does not answer them. */
+    symbol: string | null;
+    decimals: number | null;
+    /** Every source that proposed this contract; the balance itself always comes from the ledger. */
+    sources: SorobanTokenSource[];
+}
+
+/** How one candidate source fared, so the interface can say exactly what was consulted. */
+export declare interface SorobanTokenCoverage {
+    source: SorobanTokenSource;
+    status: "ok" | "failed" | "skipped";
+    detail?: string;
+}
+
+/** Where a Soroban token candidate came from before its balance was confirmed on the ledger. */
+export declare type SorobanTokenSource = "explorer" | "positions" | "list" | "events" | "manual";
+
+/**
+ * Soroban token balances the account holds directly. Soroban has no per-account token index, so
+ * this is a best-effort union of candidate sources - an explorer, the tokens named by detected
+ * positions, bundled lists, recent on-chain `transfer`/`mint` events, and contracts the user added
+ * by hand - each confirmed by reading `balance(account)` on the ledger. What could not be read is
+ * listed, never dropped; classic assets' contracts are excluded (their balance is the trustline).
+ */
+export declare interface SorobanTokensResult {
+    tokens: SorobanTokenBalance[];
+    /** Candidate contracts whose balance could not be read (a hostile, broken, or archived token). */
+    unreadable: string[];
+    coverage: SorobanTokenCoverage[];
+    /** The ledger range the event scan covered, or null when it ran out of budget before starting. */
+    eventsScanned: {
+        fromLedger: number;
+        toLedger: number;
+    } | null;
+    /** Plain-language warnings for the plan: a source that failed, contracts that could not be read. */
+    warnings: PlanBlocker[];
+}
+
+export declare interface SoroswapLpPosition extends DefiPositionBase {
+    protocol: "soroswap";
+    positionType: "lp";
+    shareAmount: string;
+    /** The pair's two token contracts (token_0, token_1), read from the pair when detection can;
+     *  what a withdrawal receives and the exit's arguments name. */
+    tokens?: [string, string];
+}
+
 /**
  * A ledger entry this account currently sponsors, on another account (or itself, for
  * "account" - a fully-sponsored account creation). Mirrors the ledger-key kinds
@@ -495,19 +979,54 @@ export declare type SponsoredEntry = {
     balanceId: string;
 };
 
+/** Response from `GET /v1/:network/stats/feed`. `daily` is oldest first, one entry per day. */
+export declare interface StatsFeed {
+    totals: StatsTotals;
+    recent: MergeRecord[];
+    daily: DailyActivity[];
+}
+
+/** Response from `GET /v1/:network/stats`. Stroops are decimal strings: the total can exceed 2^53. */
+export declare interface StatsTotals {
+    network: Network;
+    accountsClosed: number;
+    xlmRecoveredStroops: string;
+}
+
 export declare type StepStatus = "pending" | "signing" | "submitted" | "confirmed" | "failed" | "skipped";
 
-export declare type StepType = "NORMALIZE_SIGNERS" | "REVOKE_SPONSORSHIP" | "REMOVE_DATA_ENTRIES" | "CANCEL_OFFERS" | "ADD_TRUSTLINE_FOR_CLAIM" | "CLAIM_BALANCES" | "HANDLE_ASSETS" | "REMOVE_TRUSTLINES" | "CLOSE_ACCOUNT" | "MERGE";
+export declare type StepType = "NORMALIZE_SIGNERS" | "REVOKE_SPONSORSHIP" | "REMOVE_DATA_ENTRIES" | "CANCEL_OFFERS" | "ADD_TRUSTLINE_FOR_CLAIM" | "CLAIM_BALANCES" | "EXIT_POSITIONS" | "HANDLE_ASSETS" | "REMOVE_TRUSTLINES" | "CLOSE_ACCOUNT" | "MERGE";
 
-/** Structured error body used by the v1 (`/v1/...`) endpoints. */
+/** The single error envelope every API error response carries. */
 export declare interface StructuredApiError {
     error: {
         code: string;
         message: string;
         details?: unknown;
+        requestId?: string;
     };
 }
 
+/**
+ * One operation in a decoded close transaction.
+ *
+ * `source` is the account the operation acts as - the operation's own source account when it
+ * carries one, otherwise the transaction's. It is what lets verification assert relationships
+ * *between* operations rather than trusting each in isolation: in a mediated close the forward
+ * payment must be sent by the very account the merge just paid into, which is what makes the
+ * intermediary a conduit rather than a destination. Without it the only available check is
+ * pinning the intermediary's address, which every consumer would then have to be told.
+ */
+/** One non-root call in a Soroban authorization tree: what a DeFi exit's own contract (a pool,
+ *  router, or backstop) would itself be authorized to call on the account's behalf. */
+export declare interface SubInvocationCall {
+    contract: string;
+    function: string;
+    /** The decoded arguments rendered for a human, in order - same rendering as the top-level
+     *  invocation's own `args`. */
+    args: string[];
+}
+
 /** Body for `POST /v1/:network/submit`. */
 export declare interface SubmitRequest {
     signedXdr: string;
@@ -574,4 +1093,17 @@ export declare interface TxIntent {
     operations: IntentOperation[];
 }
 
+/**
+ * A position tagged with a supported protocol whose shape the adapter could not validate. Kept
+ * distinct from "no position" so a caller (issue #147's gating) can surface it rather than treat
+ * a parse failure as an account with nothing to unwind - the "no silent skips" invariant applied
+ * to a provider field OctoPos does not formally type.
+ */
+export declare interface UnrecognizedDefiPosition {
+    protocol: DefiProtocol;
+    /** OctoPos's raw type tag (e.g. "SUPPLY"), kept for diagnostics even though it didn't parse. */
+    rawType: string;
+    reason: string;
+}
+
 export { }