@lumenwipe/sdk 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -146,6 +146,31 @@ var LumenWipeClient = class {
       transaction
     });
   }
+  /** 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, network = this.defaultNetwork) {
+    return this.http.request("POST", `/${network}/fee-bump/sponsor`, {
+      transaction
+    });
+  }
+  /** Every live SEP-41 allowance the account has granted (architecture.md §12). Independent of
+   *  closing an account - a standalone security utility. */
+  getAllowances(address, network = this.defaultNetwork) {
+    return this.http.request(
+      "GET",
+      `/${network}/allowances/${encodeURIComponent(address)}`
+    );
+  }
+  /** 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, network = this.defaultNetwork) {
+    return this.http.request(
+      "POST",
+      `/${network}/allowances/revoke`,
+      params
+    );
+  }
 };
 
 // src/close-engine.ts

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,118 @@ export declare interface AccountThresholds {
     high: number;
 }
 
+/**
+ * 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 | PlainApiError;
 
+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 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 +243,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 +270,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;
 }
 
@@ -181,6 +322,13 @@ 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;
         /**
          * Required by the `transfer_to_account` choice: the `G...` address the balance is paid to.
          *
@@ -210,6 +358,120 @@ 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 actually knows how to exit (architecture.md §9's table). 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";
+
+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";
 
 export declare interface ExecutionTxBreakdown {
@@ -218,8 +480,21 @@ export declare interface ExecutionTxBreakdown {
     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 +508,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,6 +558,33 @@ 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";
 };
@@ -331,6 +623,20 @@ export declare class LumenWipeClient {
     submit(signedXdr: string, network?: Network): Promise<SubmitResponse>;
     mediatorCheck(address: string, network?: Network): Promise<MediatorCheckResult>;
     mediatorSign(transaction: string, network?: Network): 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): 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): 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): Promise<RevokeAllowanceResponse>;
 }
 
 export declare interface LumenWipeClientOptions {
@@ -395,6 +701,20 @@ export declare interface PendingRound {
     requiresAnotherCall: boolean;
 }
 
+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;
+}
+
 /** @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 {
@@ -420,7 +740,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;
 }
 
@@ -455,6 +783,11 @@ export declare interface QuoteInfo {
     expiresAtLedger: 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 +798,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
@@ -497,7 +884,7 @@ export declare type SponsoredEntry = {
 
 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. */
 export declare interface StructuredApiError {
@@ -508,6 +895,26 @@ export declare interface StructuredApiError {
     };
 }
 
+/**
+ * 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 +981,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 { }

package/dist/index.d.ts

@@ -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,118 @@ export declare interface AccountThresholds {
     high: number;
 }
 
+/**
+ * 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 | PlainApiError;
 
+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 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 +243,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 +270,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;
 }
 
@@ -181,6 +322,13 @@ 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;
         /**
          * Required by the `transfer_to_account` choice: the `G...` address the balance is paid to.
          *
@@ -210,6 +358,120 @@ 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 actually knows how to exit (architecture.md §9's table). 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";
+
+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";
 
 export declare interface ExecutionTxBreakdown {
@@ -218,8 +480,21 @@ export declare interface ExecutionTxBreakdown {
     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 +508,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,6 +558,33 @@ 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";
 };
@@ -331,6 +623,20 @@ export declare class LumenWipeClient {
     submit(signedXdr: string, network?: Network): Promise<SubmitResponse>;
     mediatorCheck(address: string, network?: Network): Promise<MediatorCheckResult>;
     mediatorSign(transaction: string, network?: Network): 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): 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): 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): Promise<RevokeAllowanceResponse>;
 }
 
 export declare interface LumenWipeClientOptions {
@@ -395,6 +701,20 @@ export declare interface PendingRound {
     requiresAnotherCall: boolean;
 }
 
+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;
+}
+
 /** @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 {
@@ -420,7 +740,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;
 }
 
@@ -455,6 +783,11 @@ export declare interface QuoteInfo {
     expiresAtLedger: 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 +798,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
@@ -497,7 +884,7 @@ export declare type SponsoredEntry = {
 
 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. */
 export declare interface StructuredApiError {
@@ -508,6 +895,26 @@ export declare interface StructuredApiError {
     };
 }
 
+/**
+ * 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 +981,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 { }

package/dist/index.js

@@ -116,6 +116,31 @@ var LumenWipeClient = class {
       transaction
     });
   }
+  /** 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, network = this.defaultNetwork) {
+    return this.http.request("POST", `/${network}/fee-bump/sponsor`, {
+      transaction
+    });
+  }
+  /** Every live SEP-41 allowance the account has granted (architecture.md §12). Independent of
+   *  closing an account - a standalone security utility. */
+  getAllowances(address, network = this.defaultNetwork) {
+    return this.http.request(
+      "GET",
+      `/${network}/allowances/${encodeURIComponent(address)}`
+    );
+  }
+  /** 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, network = this.defaultNetwork) {
+    return this.http.request(
+      "POST",
+      `/${network}/allowances/revoke`,
+      params
+    );
+  }
 };
 
 // src/close-engine.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenwipe/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Typed fetch client for the LumenWipe API - non-custodial Stellar account closing.",
   "license": "Apache-2.0",
   "type": "module",
@@ -41,18 +41,20 @@
     "account-merge"
   ],
   "scripts": {
-    "build": "bun run --filter '@lumenwipe/types' build && tsup src/index.ts --format esm,cjs --clean && tsc -p tsconfig.build.json && api-extractor run --local && cp dist/index.d.ts dist/index.d.cts",
+    "build": "bun run build:types && api-extractor run --local && cp dist/index.d.ts dist/index.d.cts",
+    "build:types": "bun run --filter '@lumenwipe/types' build && tsup src/index.ts --format esm,cjs --clean && tsc -p tsconfig.build.json",
+    "check-api": "api-extractor run",
     "type-check": "tsc --noEmit && tsc -p tests/tsconfig.json --noEmit",
     "lint": "eslint src",
     "test": "bun test tests"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.58.12",
-    "@types/bun": "^1.3.14",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
+    "@microsoft/api-extractor": "^7.59.0",
+    "@types/bun": "^1.4.0",
+    "@typescript-eslint/eslint-plugin": "^8.69.0",
+    "@typescript-eslint/parser": "^8.69.0",
     "eslint": "^8.57.1",
-    "tsup": "^8.3.0",
+    "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "@lumenwipe/types": "workspace:*"
   }