@owney/sdk 0.7.28-beta.3 → 0.7.32-beta.1

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import * as viem from 'viem';
+import { Hex, Address } from 'viem';
 import { SIWXConfig } from '@reown/appkit-controllers';
 
 /**
@@ -220,7 +222,9 @@ type SwapOrderStatus = "pending" | "executed" | "expired" | "cancelled" | "refun
  * of the flow and the one place a user would otherwise think nothing is
  * happening.
  */
-type SwapStage = "withdrawing" | "withdrawn" | "quoting" | "wrapping" | "wrapped" | "approving" | "signing" | "swapping" | "swapped" | "depositing" | "refunding" | "refunded";
+type SwapStage = "withdrawing" | "withdrawn"
+/** Withdrawal incomplete or unconfirmed; no swap was submitted. */
+ | "withdrawal-incomplete" | "swap-unknown" | "swap-partial" | "swap-not-started" | "quoting" | "wrapping" | "wrapped" | "approving" | "building" | "signing" | "swapping" | "swapped" | "depositing" | "refunding" | "refunded";
 /**
  * Which way the funds travel, which decides what each side may be.
  *
@@ -246,19 +250,88 @@ type SwapQuoteParams = {
     direction?: SwapDirection;
 };
 
-type ZyfaiRpcUrlsConfig = Partial<Record<(typeof SUPPORTED_CHAIN_IDS)[number], string>>;
+type FundingOperationKind = "deposit" | "withdraw" | "swap_deposit" | "withdraw_swap";
+/** One leg of a ledger operation, as the API returns it. */
+type FundingOperationLeg = {
+    /** e.g. `agent:zyfai`, `swap`, `approval`. */
+    legKey: string;
+    agentType: string | null;
+    /** created | submitted | unknown | failed | confirmed */
+    status: string;
+    /** uint256 decimal string. */
+    confirmedAmountRaw: string | null;
+    /** bigint decimal string. */
+    blockNumber: string | null;
+    txHash: string | null;
+    /** ISO. Kept as stored: a confirmed -> failed leg keeps its value, so key off `status`. */
+    confirmedAt: string | null;
+    /** Lowercase agent wallet the leg moved funds to or from; null when unknown. */
+    agentWallet: string | null;
+    /** ISO. First time the provider's proxied history listed this leg's tx hash (Yieldseeker). Never cleared. */
+    providerIndexedAt: string | null;
+    /**
+     * ISO. When a proxied provider snapshot first showed this leg in net deposits
+     * (Yieldseeker). Never cleared. Null means "not booked or undecidable", never
+     * "definitely not booked".
+     */
+    providerBookedAt: string | null;
+};
+/** One ledger operation, as the API returns it. */
+type FundingOperationRow = {
+    /** First 8 hex chars of the client operation id, lowercase. */
+    reference: string;
+    /** Present only for operations whose id the caller passed in `ids`. */
+    clientOperationId?: string;
+    kind: FundingOperationKind;
+    /** created | submitted | unknown | failed | confirmed | partial */
+    status: string;
+    /** ISO. */
+    createdAt: string;
+    /** ISO. */
+    settledAt: string | null;
+    stuck: boolean;
+    legs: FundingOperationLeg[];
+};
+/** The newest server-side provider snapshot sample at or before a time. */
+type ProviderSnapshotSample = {
+    /** Signed decimal strings in the asset's base units, or null. */
+    netDepositsRaw: string | null;
+    cumulativeYieldRaw: string | null;
+    totalValueRaw: string | null;
+    /** ISO or null. */
+    providerUpdatedAt: string | null;
+    /** ISO. */
+    observedAt: string;
+};
+
+type RpcUrlsConfig = Partial<Record<(typeof SUPPORTED_CHAIN_IDS)[number], string>>;
+/** @deprecated Use RpcUrlsConfig. */
+type ZyfaiRpcUrlsConfig = RpcUrlsConfig;
 interface OwneySDKConfig {
     apiKey: string;
+    /**
+     * Optional per-chain RPC overrides used for application-owned reads and
+     * transaction receipt polling. Missing chains use the Owney routing API's
+     * read-only RPC proxy. No upstream RPC credentials are included in the SDK.
+     * Wallet providers remain responsible for account access, chain switching,
+     * signatures, and transaction submission.
+     */
+    rpcUrls?: RpcUrlsConfig;
     /**
      * Optional per-chain RPC overrides for Zyfai SDK network calls.
      * Example: { 8453: "https://...", 42161: "https://..." }
+     * @deprecated Use rpcUrls so every agent shares the same read transport.
      */
     zyfaiRpcUrls?: ZyfaiRpcUrlsConfig;
+    /** Optional Owney Yieldseeker proxy base URL override for integration tests. */
+    yieldseekerApiBaseUrl?: string;
+    /** Optional SIWE origin override. Defaults to the requesting browser origin. */
+    yieldseekerSiweOrigin?: string;
     /**
      * Optional override for the Owney routing API base URL used by all routing
-     * calls (defaults to the OWNEY_ROUTING_API_BASE_URL env var, then the
-     * production URL). Set this to point at a local/staging routing API,
-     * e.g. "http://localhost:3000", when testing sponsor changes.
+     * calls. RPC proxy requests use OWNEY_ROUTING_API_BASE_URL when this is
+     * omitted; without either value, all rpcUrls must be configured.
+     * Set this to a local/staging routing API when testing sponsor changes.
      */
     routingApiBaseUrl?: string;
     /**
@@ -267,6 +340,13 @@ interface OwneySDKConfig {
      * for apps that don't use the AppKit SIWX modal.
      */
     referralSource?: string;
+    /**
+     * Mini-app identifier (`web`, `base`, `ellipal` …) recorded on funding ledger
+     * operations. Not `referralSource`, which is a Zyfai attribution tag. The
+     * ledger records `unknown` when this is omitted. Lowercased before sending;
+     * a value that is not 1-32 of `a-z 0-9 _ -` after that is left out.
+     */
+    appName?: string;
     /**
      * Turn on the SDK's debug logging (default false). Traces the decisions that
      * are otherwise invisible — notably how the organization's agent policy is
@@ -276,15 +356,6 @@ interface OwneySDKConfig {
      * already-deployed app: set `globalThis.__OWNEY_DEBUG__ = true` in devtools.
      */
     debug?: boolean;
-    /**
-     * When true, the organization's pool policy is NOT applied on connect, so a
-     * user's own deposit-time pool selection (ROUT-569) is never overwritten by
-     * the org-level one on their next reconnect. Splitting and the rest of the
-     * org policy still apply. Turn this on in apps that expose the deposit-time
-     * Pools step (the spread flow); leave it off where the partner dashboard's
-     * pool customization is the source of truth.
-     */
-    userPoolCustomization?: boolean;
     /**
      * Absolute URL of an ERC-7677 paymaster service. When set, deposits go out as
      * an EIP-5792 `wallet_sendCalls` with `capabilities.paymasterService`, so a
@@ -296,6 +367,19 @@ interface OwneySDKConfig {
      * unresolvable. Omit it and every rail behaves exactly as before.
      */
     paymasterServiceUrl?: string;
+    /**
+     * Cross-device withdrawal reservation (default `"fail-open"`). `withdraw()`
+     * claims a hold on the owner's funds before any provider call; a hold held by
+     * another device or app rejects with `WITHDRAW_IN_PROGRESS` /
+     * `details.reason === "RESERVED_ELSEWHERE"`.
+     * - `"fail-open"`: when the reservation API cannot answer (network error,
+     *   timeout, 5xx, 404, 429, ...) the withdrawal proceeds as before.
+     * - `"fail-closed"`: it rejects with `WITHDRAW_RESERVATION_UNAVAILABLE`
+     *   before anything is submitted.
+     * - `"off"`: never calls the reservation API.
+     * `OWNEY_WITHDRAWAL_RESERVATION_DISABLED=1` in the environment acts as `"off"`.
+     */
+    withdrawalReservation?: "fail-open" | "fail-closed" | "off";
 }
 interface ConnectionState {
     provider: any;
@@ -309,7 +393,166 @@ type OwneySupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number];
 type OwneySupportedChains = (typeof SUPPORTED_CHAINS)[number];
 type OwneySupportedTokens = (typeof SUPPORTED_TOKENS)[number];
 
-type AgentId = "zyfai";
+/**
+ * One protocol's pool selection on one chain. `pools` holds Zyfai pool NAMES
+ * verbatim — matched case-sensitively by customizeBatch, and an unrecognised
+ * name makes Zyfai's rebalance engine skip the whole protocol, so these strings
+ * must not be normalised anywhere.
+ *
+ * An empty array means "no usable pools on this chain".
+ */
+type OrgPoolSelection = {
+    protocolId: string;
+    chainId: number;
+    pools: string[];
+};
+/**
+ * The partner's protocol/pool policy (ROUT-224). Sparse — only protocols they
+ * narrowed appear. Optional so an older routing API, which does not return the
+ * field, still parses; undefined and null both mean "change nothing".
+ */
+type OrgPoolPolicy = {
+    autoApproveProtocols: boolean;
+    autoApprovePools: boolean;
+    selections: OrgPoolSelection[];
+};
+/**
+ * The organization's agent execution policy, or null when the partner has never
+ * configured one — in which case the agents leave the user's profile alone.
+ */
+type OrgAgentConfig = {
+    splittingMode: "none" | "automatic" | "force";
+    minSplits: number | null;
+    poolPolicy?: OrgPoolPolicy | null;
+};
+
+type DepositCallback = (smartWalletAddress: string, chainId: number, amount: string) => Promise<`0x${string}`> | `0x${string}`;
+/**
+ * Read access to the funding ledger, given to agents by the client so they can
+ * hold earnings while a provider lags (spec B2). Both reads never throw:
+ * null means "no ledger information", and callers then behave as before.
+ */
+type AgentFundingLedgerAccess = {
+    /** `sdk.listFundingOperations` for this owner; null when the owner is not the connected one or on failure. */
+    listOperations(input: {
+        owner: string;
+        chainId: number;
+        asset: string;
+        since?: Date;
+    }): Promise<FundingOperationRow[] | null>;
+    /** The newest server provider-snapshot sample at or before `before`; null when none or on failure. */
+    providerSnapshot?(input: {
+        owner: string;
+        chainId: number;
+        asset: string;
+        agentWallet: string;
+        before: Date;
+    }): Promise<ProviderSnapshotSample | null>;
+};
+interface IAgent {
+    readonly id: string;
+    readonly supportedChainIds: readonly OwneySupportedChainId[];
+    readonly supportedAssets: readonly AgentSupportedAssets[];
+    /**
+     * Describes how `AgentBalance.tokens` relates to `positions`.
+     * Most adapters expose token totals that already include deployed positions.
+     * Providers such as Yieldseeker expose idle wallet tokens separately, so
+     * withdrawal planning must add matching position amounts.
+     */
+    readonly balanceComposition?: "tokens-include-positions" | "tokens-plus-positions";
+    /**
+     * Whether a withdrawal requires an owner-approved wallet transaction.
+     * Aggregate withdrawals run these agents before relayer-only agents so a
+     * rejected wallet request cannot happen after another leg has committed.
+     */
+    readonly withdrawalRequiresWalletApproval?: boolean;
+    disconnect(): Promise<void>;
+    activateAgent(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<void>;
+    /**
+     * Apply the organization's agent policy to this user's account.
+     *
+     * Optional: an agent that has no equivalent knob simply omits it, which is why
+     * this is not part of `activateAgent`'s signature. Declared on the interface
+     * rather than only on ZyfaiAgent so the contract stays agent-neutral — the
+     * ticket asks for a design that can also cover Surf, which has no adapter yet.
+     *
+     * Implementations must be **non-fatal**: this runs during activation as a side
+     * effect, so a failure has to leave the user connected and their profile
+     * unchanged rather than break the connect.
+     */
+    applyOrgPolicy?(state: ConnectionState, chainId: number, policy: OrgAgentConfig): Promise<void>;
+    deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback, onProgress?: FundingProgress, onBeforeSubmission?: (evidence: FundingEvidence) => void | Promise<void>): Promise<OwneyDepositResult>;
+    withdraw(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount?: string, onProgress?: FundingProgress, gasMode?: "auto" | "sponsored" | "paid", onBeforeSubmission?: FundingProgress, assertCurrent?: () => void): Promise<AgentWithdrawResult>;
+    /** Read-only MAX proof at the owner payout block; never sends another withdrawal. */
+    verifyWithdrawalCompletion?(state: ConnectionState, evidence: FundingEvidence): Promise<WithdrawalCompletion>;
+    /** A newly observed pool allocation invalidates this asset's portfolio cache only. */
+    invalidateAllocationRead?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): void;
+    /** Invalidate only the confirmed asset. This hook must not sign or submit transactions. */
+    invalidateFundingRead?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number, txHash?: string): void;
+    /** End accelerated balance reads only for the exact snapshot the caller displayed. */
+    endFundingBalanceRefresh?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
+    getFundingHistory?(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
+    getFundingWallet?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;
+    /** Verify the displayed remaining balance after a receipt-confirmed payout.
+     * Undefined means unknown; never substitute a failed read with zero. */
+    verifyWithdrawalBalance?(state: ConnectionState, evidence: FundingEvidence, balance: AgentBalance): Promise<AssetReadMetadata | undefined>;
+    /** Read-only chain proof when indexed withdrawal components are incomplete.
+     * Returns raw owner-withdrawable units; unavailable proof must throw.
+     * minimumAmount is the raw liquidity required from this agent for a typed
+     * plan, so adapters can expand discovery when known positions fall short. */
+    getWithdrawableBalance?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, minimumAmount?: bigint): Promise<bigint>;
+    /** Optional positive proof for a repeat deposit; unknown must fall back to portfolio validation. */
+    hasExistingDepositFunds?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
+    getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
+    getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
+    /** Funding-ledger read access for earnings holds. Optional; without it an agent behaves as before. */
+    setFundingLedgerAccess?(access: AgentFundingLedgerAccess | undefined): void;
+    /**
+     * A small, never-prompting read of the provider's earnings bookkeeping for a
+     * `provider.sample` ledger event (Zyfai). Null when unavailable; never throws.
+     */
+    providerEarningsSample?(state: ConnectionState, chainId: number): Promise<Record<string, unknown> | null>;
+    /**
+     * Refresh the agent's earnings snapshot when its backend supports doing so.
+     * Implementations own freshness and request-deduplication policy.
+     */
+    refreshEarnings?(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
+    getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays, 
+    /**
+     * Optional asset symbol ("USDC" / "WETH") scoping the daily series to a
+     * single asset on the chain. Agents without per-asset positions ignore it.
+     */
+    tokenSymbol?: string): Promise<AccountAgentApy>;
+    /**
+     * Daily cumulative earnings in token units, scoped to a chain/asset, using
+     * the provider's earnings basis. Include an opening snapshot when available
+     * so the "recent earnings" subline can difference the endpoints. (ROUT-452)
+     */
+    getDailyEarnings?(state: ConnectionState, chainId: number, days: LookbackDays, tokenSymbol?: string): Promise<AccountDailyEarnings>;
+    getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
+    getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
+    /**
+     * Ensure the given asset uses backend protocol auto-selection
+     * (`autoSelectProtocols: true`). Optional capability — only agents whose
+     * backend models per-asset protocol selection implement it. Returns whether
+     * a write occurred (`false` = already enabled / not supported).
+     */
+    ensureAutoSelectProtocols?(state: ConnectionState, chainId: number, asset: "USDC" | "WETH"): Promise<boolean>;
+    supportsAgentApyPeriod?(days: DailyApyDays): boolean;
+    getAgentApy(days: DailyApyDays, options?: AgentApyOptions): Promise<AgentApy>;
+}
+/**
+ * Optional filters for per-agent APY lookups.
+ * - `tokenSymbol` / `chainId` scope the APY to a specific asset+chain when
+ *   the underlying provider supports it (Zyfai). Agents whose backends do
+ *   not yet support per-asset APY will ignore these options.
+ */
+type AgentApyOptions = {
+    tokenSymbol?: string;
+    chainId?: number;
+};
+
+type AgentId = "zyfai" | "yieldseeker";
 type Asset = string;
 type AgentSupportedAsset = {
     readonly symbol: string;
@@ -358,43 +601,51 @@ type HistoryFilters = {
     tokenSymbol?: string;
 };
 type HistoryOptions = {
+    chainId?: number;
     agentId?: AgentId;
     filters?: HistoryFilters;
-    /**
-     * Chains to read, instead of the one `activateAgent` last set (ROUT-479).
-     *
-     * Each chain pages independently and the results merge into one
-     * chronological list, with every entry stamped with the chain it came from.
-     * Omit for the single-chain behaviour, which stays the default: fanning out
-     * by default would multiply every existing caller's request count.
-     */
-    chainIds?: OwneySupportedChainId[];
 };
 type WithdrawOptions = {
+    /** Internal orchestration observation deadline; never retries a send. */
+    observationDeadline?: number;
+    assertCurrent?: () => void;
+    /** Yieldseeker V2 only. "auto" requests sponsorship for a verified V2 wallet. */
+    gasMode?: "auto" | "sponsored" | "paid";
+    /** Exclude unresolved providers from aggregate withdrawals; direct agent requests are unchanged. */
+    excludeAgentIds?: AgentId[];
+    onProgress?: FundingProgress;
+    /**
+     * Durable pre-dispatch checkpoint for adapters with a recoverable operation ID.
+     * Rejection prevents submission; progress observers remain non-fatal.
+     */
+    onBeforeSubmission?: FundingProgress;
     asset: Asset;
     amount?: string;
     agentId?: AgentId;
-    /**
-     * Chain to withdraw from. Defaults to the chain `activateAgent` last set.
-     * See `DepositOptions.chainId` — the same rules apply.
-     */
-    chainId?: number;
+    /** Called after each agent returns; callback failures never change a financial result. */
+    onAgentResult?: (agentId: AgentId, result: AgentWithdrawResult) => void;
+    /** Funding ledger reference (a UUID). Defaults to a new random UUID; apps pass
+     * their own so the app record and the ledger share one reference. It is also
+     * the withdrawal reservation's operationId. */
+    operationId?: string;
+    /**
+     * Cross-device withdrawal reservation options.
+     * - `override`: the `reference` from an overridable `RESERVED_ELSEWHERE`
+     *   error, sent after the user chose "Withdraw anyway".
+     * - `supersedesOperationId`: an earlier operation of this SDK (for example
+     *   the sponsored attempt a paid retry replaces). Its hold is released when
+     *   this SDK still has that operation's holder token; otherwise ignored.
+     */
+    reservation?: WithdrawalReservationOptions;
+};
+/** `WithdrawOptions.reservation`: see there. */
+type WithdrawalReservationOptions = {
+    override?: string;
+    supersedesOperationId?: string;
 };
 type AccountApyOptions = {
     agentId?: AgentId;
     days: LookbackDays;
-    /**
-     * Chain to scope the daily series to, instead of the one `activateAgent`
-     * last set (ROUT-479).
-     *
-     * `"all"` blends every chain the wallet held that day, which is what the
-     * chart's "All chains" filter asks for. Unlike the history and earnings
-     * reads this needs no fan-out: the provider's daily-APY payload is already
-     * wallet-wide and names each position's chain, so the scope is a filter over
-     * one response rather than several calls. Omit for the active chain, which
-     * stays the default.
-     */
-    chainId?: OwneySupportedChainId | "all";
     /**
      * Optional asset symbol (e.g. "USDC", "WETH") to scope the daily APY series
      * to a specific asset on the active chain. Without it the series blends every
@@ -412,14 +663,6 @@ type AccountApyOptions = {
 type DailyEarningsOptions = {
     agentId?: AgentId;
     days: LookbackDays;
-    /**
-     * Chains to read, instead of the one `activateAgent` last set (ROUT-479).
-     *
-     * The same asset is summed across them — USDC on Base and USDC on Arbitrum
-     * are the same unit. Different assets stay apart, as they already do within
-     * one chain. Omit for the single-chain behaviour, which stays the default.
-     */
-    chainIds?: OwneySupportedChainId[];
     /**
      * Optional asset symbol (e.g. "USDC", "WETH") scoping the series to one
      * asset on the active chain.
@@ -445,154 +688,176 @@ type AgentsApyOptions = {
     chainId?: number;
 };
 type DepositOptions = {
+    /** Optional synchronous foreground ownership fence for the default Permit2 rail.
+     * Throw to stop preparation/dispatch and late journal writes after lease/session loss. */
+    assertSubmissionCurrent?: () => void;
+    /** Resume only these already signed relayer bytes; never create a new authorization. */
+    resumeTxHash?: `0x${string}`;
+    onProgress?: FundingProgress;
+    /** Awaited immediately before dispatch. Throwing prevents submission.
+     * All legs of an atomic batch are checkpointed together. */
+    onBeforeSubmission?: (evidence: FundingEvidence[]) => void | Promise<void>;
     amount: string;
     asset: Asset;
     depositCallback?: DepositCallback;
     agentId?: AgentId;
     onApproved?: () => void;
-    /**
-     * Chain to deposit on. Defaults to the chain `activateAgent` last set, so
-     * omitting it behaves exactly as before.
-     *
-     * Pass it to fund several chains in a row without re-activating between
-     * them (ROUT-245's spread strategies). It selects the target; it does not
-     * replace activation, which is what populates `activeAgents`, and it does
-     * not remove the wallet's network switch — the default deposit callbacks
-     * still put the wallet on this chain before signing, since a deposit
-     * signature is EIP-712 with the chain in its domain.
-     */
-    chainId?: number;
+    /** Funding ledger reference (a UUID). Defaults to a new random UUID; apps pass
+     * their own so the app record and the ledger share one reference. */
+    operationId?: string;
 };
 
-/**
- * One protocol's pool selection on one chain. `pools` holds Zyfai pool NAMES
- * verbatim — matched case-sensitively by customizeBatch, and an unrecognised
- * name makes Zyfai's rebalance engine skip the whole protocol, so these strings
- * must not be normalised anywhere.
- *
- * An empty array means "no usable pools on this chain".
- */
-type OrgPoolSelection = {
-    protocolId: string;
-    chainId: number;
-    pools: string[];
+type FundingStage = "pending" | "confirmed" | "unknown" | "failed" | "not-applicable";
+/** Vault inventory retained before the MAX payout. No signatures or secrets. */
+type WithdrawalCompletionContext = {
+    vaults: string[];
+    userId: string;
+    agentId: string;
+    inventoryComplete: boolean;
 };
-/**
- * The partner's protocol/pool policy (ROUT-224). Sparse — only protocols they
- * narrowed appear. Optional so an older routing API, which does not return the
- * field, still parses; undefined and null both mean "change nothing".
- */
-type OrgPoolPolicy = {
-    autoApproveProtocols: boolean;
-    autoApprovePools: boolean;
-    selections: OrgPoolSelection[];
+type WithdrawalCompletion = {
+    status: "complete" | "remaining" | "unavailable";
+    reason?: string;
+    checkedVaults?: number;
 };
-/**
- * The organization's agent execution policy, or null when the partner has never
- * configured one — in which case the agents leave the user's profile alone.
- */
-type OrgAgentConfig = {
-    splittingMode: "none" | "automatic" | "force";
-    minSplits: number | null;
-    poolPolicy?: OrgPoolPolicy | null;
+/** Hash-bound v0.6 recovery metadata. Deliberately excludes the owner signature. */
+type UnsignedUserOperationEvidence = {
+    sender: string;
+    nonce: string;
+    initCode: string;
+    callData: string;
+    callGasLimit: string;
+    verificationGasLimit: string;
+    preVerificationGas: string;
+    maxFeePerGas: string;
+    maxPriorityFeePerGas: string;
+    paymasterAndData: string;
 };
-
-/**
- * Pool policy: Owney's org-level protocol/pool policy -> Zyfai's two mismatched
- * write shapes.
- *
- * Zyfai splits "which protocols and pools may this user's funds sit in" across
- * two calls that do not share an axis:
- *
- *   updateUserProfile({ protocols })   per ASSET,            chain-agnostic
- *   customizeBatch([{ protocolId,      per (PROTOCOL, CHAIN), asset-agnostic
- *                      chainId, pools, autoselect }])
- *
- * `protocols` is an explicit ALLOW-LIST: a protocol left out of it is disabled
- * for that asset, on every chain, immediately. `customizeBatch` is the opposite
- * shape — one record per (protocol, chain) pair, asset-agnostic, and per
- * docs.zyf.ai it "creates or updates a record for the (user, protocol, chain)
- * combination"; "previous customizations for the same combination are
- * overwritten".
- *
- * That second property is the reason this file exists rather than a single
- * flat translation: customizeBatch overwrites only the combinations it is
- * GIVEN. The partner's stored policy (`OrgPoolPolicy.selections`) is sparse —
- * only the protocols they actually narrowed appear — but the payload we send
- * must be EXHAUSTIVE over every (protocol, chain) pair Zyfai offers this user.
- * If we only sent the narrowed pairs, a partner who restricts Morpho, saves,
- * then later re-ticks every pool box would never be able to undo it: nothing
- * in the (sparse) policy would tell us to send a record clearing it, and the
- * old restrictive record would stay live on the user's profile forever.
- *
- * Pure functions, kept out of the agent so the mapping is testable without a
- * Zyfai client. See splitting.ts for the same pattern on the other lever.
- */
-
-/** One selectable pool, with the figures the deposit-time Pools step shows. */
-type AvailablePool = {
-    chainId: number;
-    token: string;
-    name: string;
-    /** combined_apy (pool + rewards), already a percent. null when absent. */
-    apy: number | null;
-    /** TVL in USD. null when absent. See ZyfCustomizationPoolInfo: `tvl` is in
-     *  the pool's own token, `tvlUsd` is the dollar figure — only the latter is
-     *  safe to show with a currency symbol. */
-    tvlUsd: number | null;
-    /** Per-pool deep link (e.g. the Morpho vault page). null when absent. */
-    link: string | null;
-};
-/** Public Zyfai strategies used by deposit-time pool customization. */
-type PoolSelectionStrategy = "aggressive" | "yieldmaxxing";
-/** One asset's explicit choice for a protocol on one chain. */
-type UserPoolSelection = {
-    asset: "USDC" | "WETH";
-    protocolId: string;
-    chainId: number;
-    /** Names enabled by the user for this asset/protocol/chain. */
-    pools: string[];
-    /** Every name shown for this asset/protocol/chain in the superset catalog. */
-    availablePools: string[];
-};
-/** The complete saved draft for the asset/chain legs selected in the deposit. */
-type UserPoolSelectionRequest = {
-    strategies: Array<{
-        asset: "USDC" | "WETH";
-        strategy: PoolSelectionStrategy;
-    }>;
-    selections: UserPoolSelection[];
+type DepositAuthorizationReference = {
+    authorizationId: `0x${string}`;
+    predecessorTxHash?: `0x${string}`;
 };
-/** One protocol with its pools for the deposit asset — what the Pools step
- *  renders: a protocol row that opens to a list of selectable pools. */
-type PoolCatalogProtocol = {
-    protocolId: string;
-    name: string;
-    logo: string | null;
-    pools: AvailablePool[];
+type DepositReplacementValidation = {
+    authorizationId: `0x${string}`;
+    predecessorTxHash: `0x${string}`;
+    replacementTxHash: `0x${string}`;
 };
-
+/** Evidence about one provider leg. Amounts are token base units, never USD. */
+interface FundingEvidence {
+    agentId: AgentId;
+    chainId: number;
+    token: OwneySupportedTokens;
+    walletAddress: string;
+    agentWallet?: string;
+    maxCompletion?: WithdrawalCompletionContext;
+    maxCompletionCheck?: WithdrawalCompletion;
+    intendedAmount: string;
+    confirmedAmount?: string;
+    /** Receipt delivery and fulfillment of a typed requested amount are separate facts. */
+    amountCompletion?: "complete" | "shortfall";
+    /** Verified difference between the typed request and the actual owner payout. */
+    shortfallAmount?: string;
+    txHash?: string;
+    /** Persisted before a sponsored EOA operation is sent. */
+    userOpHash?: string;
+    /** Lets recovery verify a consumed nonce even if a bundler forgets the operation. */
+    userOperation?: UnsignedUserOperationEvidence;
+    /** Base Account calls ID used to recover an uncertain wallet submission. */
+    callsId?: string;
+    /** Deposit execution was attempted, rather than only prepared. Not confirmation. */
+    depositSubmission?: "started";
+    depositAuthorization?: DepositAuthorizationReference;
+    blockNumber?: string;
+    logIndexes?: number[];
+    transferLogs?: {
+        logIndex: number;
+        amountRaw: string;
+    }[];
+    /** Sanitized execution-request evidence. Attempted does not prove server acceptance. */
+    withdrawalRequest?: {
+        attempted: boolean;
+        method?: "GET" | "POST";
+        path?: "/users/withdraw" | "/users/partial-withdraw";
+        elapsedMs?: number;
+        /** Actual response status captured before the vendor replaces the HTTP error. */
+        httpStatus?: number;
+        failure?: "network" | "unauthorized" | "forbidden" | "rate-limited" | "insufficient-balance" | "session-key-missing" | "withdrawal-in-progress" | "other";
+        /** When the provider accepted the request without a hash (ms since epoch). */
+        acceptedAt?: number;
+    };
+    /** Where an on-chain payout search may start, for a hashless acceptance.
+     * `fromBlock` is the chain head read just before the request (decimal string). */
+    payoutSearch?: {
+        fromBlock?: string;
+    };
+    transfer: FundingStage;
+    registration: FundingStage;
+    delivery: FundingStage;
+}
+type FundingProgress = (evidence: FundingEvidence) => void;
+interface AssetReadMetadata {
+    chainId: number;
+    asset: string;
+    fetchedAt?: number;
+    /** When the underlying provider request started; preserved on cached reads. */
+    requestedAt?: number;
+    /** SDK cache generation, not an onchain block or provider timestamp. */
+    readVersion?: number;
+    providerUpdatedAt?: string;
+    snapshotId?: string;
+    blockNumber?: string;
+    netDepositsRaw?: string;
+    /** Display-only agreement with a post-payout read. Does not prove that
+     * provider accounting, history or allocations include the transaction. */
+    withdrawalCheck?: {
+        txHash: string;
+        blockNumber: string;
+    };
+    positionsStatus: "available" | "unavailable";
+}
 interface OwneyDepositResult {
+    evidence?: FundingEvidence;
     txHash: string;
     smartWallet: string;
     amount: string;
+    /** Funding ledger reference for this deposit (quote it in support tickets). */
+    operationId?: string;
 }
 interface OwneyMultiDepositResult {
     agentResults: Record<string, OwneyDepositResult>;
+    /** Funding ledger reference for this deposit (quote it in support tickets). */
+    operationId?: string;
 }
 interface AgentWithdrawResult {
+    evidence?: FundingEvidence;
     txHash?: string;
     type: "full" | "partial";
-    /** Smallest-unit amount, or a provider sentinel such as "all" for a full request. */
+    /** Owner payout or clearing all MAX positions still needs verification. */
+    completion?: "unverified";
+    /** Confirmed smallest-unit amount; "0" when no owner payout is verified.
+     * Legacy providers may return a sentinel such as "all" for a full request. */
     amount: string;
+    /** Yieldseeker typed withdrawal fulfilled after an exactly verified fee
+     * deduction. Amount remains the confirmed net owner payout, and the gross
+     * amount must equal that payout plus the fee, all in token base units. */
+    feeAdjustment?: {
+        grossAmount: string;
+        feeAmount: string;
+    };
+    /** Funding ledger reference for this withdrawal (quote it in support tickets).
+     * Set on the result of a single-agent `withdraw()`, not on per-agent entries. */
+    operationId?: string;
 }
 interface OwneyWithdrawResult {
     agentResult: Record<AgentId, AgentWithdrawResult>;
     /**
-     * Sum of reported smallest-unit amounts; null when a full withdrawal's
-     * amount is not yet known. An accepted request is not proof of settlement.
+     * Sum of confirmed smallest-unit amounts; null while any returned leg's
+     * payout is not yet known, including typed requests accepted asynchronously.
+     * Evidence-less custom adapters retain their confirmed-amount contract.
      */
     totalWithdrawn: string | null;
+    /** Funding ledger reference for this withdrawal (quote it in support tickets). */
+    operationId?: string;
 }
 interface OwneyToken {
     chain: OwneySupportedChains;
@@ -608,6 +873,10 @@ interface OwneyPosition {
     pool?: string;
     asset: string;
     amount: string;
+    /** Provider-native raw quantity; may represent vault shares, not the underlying asset. */
+    amountRaw?: string;
+    /** Withdrawable underlying asset amount in that asset's smallest units. */
+    withdrawableAmountRaw?: string;
     apy?: number;
     tvl?: number;
     /** Pool liquidity. Prepared slot — Zyfai will add this to its portfolio
@@ -638,10 +907,20 @@ interface OwneyPendingAllocation {
     since?: string;
 }
 interface AgentBalance {
+    readMetadata?: AssetReadMetadata[];
+    /** Authoritative native balances per asset/network, including idle and invested funds. */
+    assetBalances?: OwneyToken[];
     smartWallet?: `0x${string}`;
     totalBalance: string;
     /** Asset that `totalBalance` is denominated in. Currently always `"usdc"`. */
     totalBalanceAsset: string;
+    /**
+     * Describes whether `tokens` already includes deployed `positions`.
+     * Consumers must add matching positions only for `tokens-plus-positions`;
+     * doing so for Zyfai would double-count, while omitting it for Yieldseeker
+     * makes its balance disappear as soon as idle funds enter a vault.
+     */
+    balanceComposition?: "tokens-include-positions" | "tokens-plus-positions";
     tokens: OwneyToken[];
     /**
      * Per-protocol/pool positions when the agent's portfolio payload includes
@@ -651,34 +930,19 @@ interface AgentBalance {
     /** Funds received but not yet deployed. Omitted when nothing is pending. */
     pendingAllocations?: OwneyPendingAllocation[];
 }
-/**
- * One position drained by `withdrawAll()` — a chain and asset pair.
- *
- * Carries either a result or an error, never both: a leg that failed while
- * others succeeded is the normal case, not an exception, and the caller needs
- * to name the ones that did not arrive.
- */
-interface OwneyWithdrawAllLeg {
-    chainId: OwneySupportedChainId;
-    asset: OwneySupportedTokens;
-    /** What the position held when the sweep started. */
-    amount: string;
-    result?: OwneyWithdrawResult | AgentWithdrawResult;
-    error?: string;
-}
-interface OwneyWithdrawAllResult {
-    /** Every position attempted, in the order it was attempted. */
-    legs: OwneyWithdrawAllLeg[];
-}
 interface OwneyBalances {
     totalBalance: string;
     /** Asset that `totalBalance` is denominated in. Currently always `"usdc"`. */
     totalBalanceAsset: string;
     agentBalances: Record<AgentId, AgentBalance>;
-    /** Omitted agents failed to load; they must not be interpreted as zero. */
-    agentErrors?: Record<AgentId, string>;
+    /**
+     * Per-agent read failures when an aggregate balance request returned only a
+     * partial result. Callers may display the successful balances, but funding
+     * operations must not interpret a missing agent as having a zero balance.
+     */
+    agentErrors?: Partial<Record<AgentId, string>>;
     /** Absolute provider cooldown deadlines (Unix milliseconds). */
-    agentRetryAt?: Record<AgentId, number>;
+    agentRetryAt?: Partial<Record<AgentId, number>>;
 }
 interface AgentEarnings {
     smartWallet: `0x${string}`;
@@ -688,6 +952,10 @@ interface AgentEarnings {
 interface OwneyEarnings {
     totalEarnings: string;
     agentEarnings: Record<AgentId, AgentEarnings>;
+    /** Per-agent failures when an aggregate read returned a partial result. */
+    agentErrors?: Partial<Record<AgentId, string>>;
+    /** Absolute provider cooldown deadlines (Unix milliseconds). */
+    agentRetryAt?: Partial<Record<AgentId, number>>;
 }
 type ApyByChainAndAsset = Partial<Record<OwneySupportedChainId, Partial<Record<OwneySupportedTokens, number>>>>;
 /** A single day's net APY for the connected account, as a percentage number. */
@@ -702,28 +970,6 @@ interface ApyHistoryPoint {
         unit: string;
     };
 }
-/**
- * What the APY chart's chain/asset menus are allowed to offer, and how far
- * back each option reaches (ROUT-479).
- *
- * An option only earns a place if some day in the window held a real position
- * on it — a balance and a rate. Listing anything else would offer a filter
- * that draws a blank chart. `days` is what the menu prints beside each row,
- * and the legs genuinely differ: a wallet can hold USDC for a fortnight and
- * WETH for three days.
- */
-interface ApyCoverage {
-    chains: {
-        chainId: number;
-        days: number;
-    }[];
-    /** Legs whose `tokenSymbol` the provider left unset are absent — they cannot
-     *  be named, so they cannot be picked. Their chain still counts. */
-    assets: {
-        asset: string;
-        days: number;
-    }[];
-}
 interface AccountAgentApy {
     walletAddress: string;
     weightedApyAfterFee?: number;
@@ -734,8 +980,6 @@ interface AccountAgentApy {
      * date. Empty when the provider returns no daily history.
      */
     history?: ApyHistoryPoint[];
-    /** Which chains/assets this history can be filtered down to. */
-    coverage?: ApyCoverage;
 }
 interface OwneyAccountApy {
     totalApy: string;
@@ -757,6 +1001,15 @@ interface OwneyAllocationApy {
 }
 type HistoryAction = "Rebalance" | "Deposit" | "Top up" | "Withdraw" | "Earned";
 interface HistoryTransaction {
+    tokenAddress?: string;
+    agentWallet?: string;
+    logIndexes?: number[];
+    transferLogs?: {
+        logIndex: number;
+        amountRaw: string;
+    }[];
+    amountRaw?: string;
+    blockNumber?: string;
     txHashes: string[];
     chainId?: number;
     tokenSymbol?: string;
@@ -777,6 +1030,10 @@ interface RebalanceLog {
     tokenSymbol: string;
     amount: string;
     status: "success" | "failed";
+    /** Fee-net APY at execution time for the source leg, in percentage points. */
+    fromApy?: string;
+    /** Fee-net APY at execution time for the destination leg, in percentage points. */
+    toApy?: string;
 }
 interface AgentHistoryPosition {
     protocol: string;
@@ -785,17 +1042,10 @@ interface AgentHistoryPosition {
     amount?: string;
 }
 interface AgentHistoryEntry {
+    /** Stable provider/transfer identity, independent of row order. */
+    id?: string;
     agent: AgentId;
     action: HistoryAction;
-    /**
-     * Chain this entry came from, stamped by the history fan-out (ROUT-479).
-     *
-     * Absent on a single-chain read, where the caller already knows the chain.
-     * The entry has no chain of its own otherwise: `transactions[].chainId` is
-     * optional and missing whenever the indexer has not attached the transfer,
-     * so a row cannot be labelled from it reliably.
-     */
-    chainId?: OwneySupportedChainId;
     date: string;
     oldApy: string | null;
     newApy: string | null;
@@ -804,6 +1054,8 @@ interface AgentHistoryEntry {
     positions?: AgentHistoryPosition[];
 }
 interface OwneyAgentHistory {
+    agentErrors?: Partial<Record<AgentId, string>>;
+    agentRetryAt?: Partial<Record<AgentId, number>>;
     data: AgentHistoryEntry[];
     /** True iff a subsequent page exists; pair with `nextCursor`. */
     hasMore: boolean;
@@ -842,17 +1094,18 @@ interface AgentApy {
     detailedApys?: AgentApyDetails;
 }
 interface OwneyAgentApy {
-    agentApy: Record<AgentId, AgentApy>;
+    /** Agents without data for the requested period are omitted. */
+    agentApy: Partial<Record<AgentId, AgentApy>>;
 }
-/** One day's cumulative NET earnings for a single asset. */
+/** One day's cumulative earnings for a single asset. */
 interface DailyEarningsPoint {
     /** ISO date string for the day, e.g. "2026-09-01". */
     date: string;
     /**
-     * Earnings accumulated from the start of the returned series up to and
-     * including this day, net of the agent's performance fee, denominated in the
-     * asset's own units. A running total of daily deltas, so it measures the
-     * window — not the wallet's lifetime.
+     * Cumulative earnings in the asset's own units, using the provider's earnings
+     * basis. A provider may return lifetime totals or a running window total;
+     * difference the last and opening points to measure earnings over the window.
+     * Aggregate series normalize each component's opening value before summing.
      */
     amount: number;
 }
@@ -861,8 +1114,9 @@ interface AssetDailyEarnings {
     /** Asset symbol, e.g. "USDC" / "WETH". */
     asset: string;
     /**
-     * Ascending by date. Days the wallet held nothing of this asset are absent
-     * rather than zero — a zero would read as "earned nothing that day".
+     * Ascending by date, including an opening snapshot before the requested
+     * window when available. Provider gaps remain absent; aggregates carry the
+     * most recent cumulative value across dates reported by other providers.
      */
     points: DailyEarningsPoint[];
 }
@@ -879,96 +1133,50 @@ interface AccountDailyEarnings {
     assets: AssetDailyEarnings[];
 }
 
-type DepositCallback = (smartWalletAddress: string, chainId: number, amount: string) => Promise<`0x${string}`> | `0x${string}`;
-interface IAgent {
-    readonly id: string;
-    readonly supportedChainIds: readonly OwneySupportedChainId[];
-    readonly supportedAssets: readonly AgentSupportedAssets[];
-    disconnect(): Promise<void>;
-    activateAgent(state: ConnectionState, chainId: number): Promise<void>;
-    /**
-     * Apply the organization's agent policy to this user's account.
-     *
-     * Optional: an agent that has no equivalent knob simply omits it, which is why
-     * this is not part of `activateAgent`'s signature. Declared on the interface
-     * rather than only on ZyfaiAgent so the contract stays agent-neutral — the
-     * ticket asks for a design that can also cover Surf, which has no adapter yet.
-     *
-     * Implementations must be **non-fatal**: this runs during activation as a side
-     * effect, so a failure has to leave the user connected and their profile
-     * unchanged rather than break the connect.
-     */
-    applyOrgPolicy?(state: ConnectionState, chainId: number, policy: OrgAgentConfig): Promise<void>;
-    /**
-     * The deposit-time pool catalogue for one asset and strategy: protocols with
-     * their selectable pools and figures. Optional — an agent with no pool
-     * customization omits it. (ROUT-569)
-     */
-    getPoolCatalog?(params: {
-        asset: string;
-        strategy: "conservative" | "aggressive" | "yieldmaxxing";
-    }): Promise<PoolCatalogProtocol[]>;
-    /**
-     * Apply a user's own pool selection to their account, driven by the
-     * deposit-time Pools step. Optional, and non-fatal like `applyOrgPolicy`.
-     * (ROUT-569)
-     */
-    setPoolSelection?(selection: UserPoolSelectionRequest): Promise<void>;
-    deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback): Promise<OwneyDepositResult>;
-    withdraw(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount?: string): Promise<AgentWithdrawResult>;
-    getBalances(state: ConnectionState, chainId: number): Promise<AgentBalance>;
-    getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
-    /**
-     * Refresh the agent's earnings snapshot when its backend supports doing so.
-     * Implementations own freshness and request-deduplication policy.
-     */
-    refreshEarnings?(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
-    getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays, 
-    /**
-     * Optional asset symbol ("USDC" / "WETH") scoping the daily series to a
-     * single asset on the chain. Agents without per-asset positions ignore it.
-     */
-    tokenSymbol?: string, 
-    /**
-     * Chain the series is scoped to, when that differs from the chain the
-     * connection is on. `null` spans every chain the wallet held (ROUT-479);
-     * omitted means `chainId`. Kept apart from `chainId` because that one
-     * still resolves the wallet and must stay a real, connected chain.
-     */
-    scopeChainId?: number | null): Promise<AccountAgentApy>;
-    /**
-     * Daily cumulative NET earnings for the window, scoped to a chain/asset.
-     * Backs the "recent earnings" subline, whose figure must reconcile with the
-     * balance headline directly above it. (ROUT-452)
-     */
-    getDailyEarnings?(state: ConnectionState, chainId: number, days: LookbackDays, tokenSymbol?: string): Promise<AccountDailyEarnings>;
-    getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
-    getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
-    /**
-     * Ensure the given asset uses backend protocol auto-selection
-     * (`autoSelectProtocols: true`). Optional capability — only agents whose
-     * backend models per-asset protocol selection implement it. Returns whether
-     * a write occurred (`false` = already enabled / not supported).
-     */
-    ensureAutoSelectProtocols?(state: ConnectionState, chainId: number, asset: "USDC" | "WETH"): Promise<boolean>;
-    getAgentApy(days: DailyApyDays, options?: AgentApyOptions): Promise<AgentApy>;
-}
+type ReservationAgent = "zyfai" | "surfliquid" | "yieldseeker";
+type WithdrawalReservationMode = "fail-open" | "fail-closed" | "off";
+type ReservationReleaseReason = "confirmed" | "failed" | "not_submitted";
+/** What the 409 tells the app. The holding operation's id and token are never returned. */
+type WithdrawalReservationConflict = {
+    /** First 8 hex characters of the holding operation's id. */
+    reference: string;
+    ageSec: number;
+    expiresInSec: number;
+    agents: ReservationAgent[];
+    state: "preparing" | "dispatched";
+    /** True for an unproven hold: the app may resend with `override: reference`. */
+    overridable: boolean;
+};
+
 /**
- * Optional filters for per-agent APY lookups.
- * - `tokenSymbol` / `chainId` scope the APY to a specific asset+chain when
- *   the underlying provider supports it (Zyfai). Agents whose backends do
- *   not yet support per-asset APY will ignore these options.
+ * On-chain discovery of a hashless withdrawal's payout.
+ *
+ * Lists ERC-20 `Transfer` logs on the operation's token that reach the owner.
+ * The sender is never filtered: routed payouts hop through intermediaries.
+ * This only finds candidates; each one must still be proven with the receipt
+ * inspection (`inspectFunding(candidate, "withdraw", { requireAmountMatch: true })`).
  */
-type AgentApyOptions = {
-    tokenSymbol?: string;
-    chainId?: number;
+type WithdrawalPayoutCandidate = {
+    txHash: string;
+    /** Decimal block number. */
+    blockNumber: string;
+    logIndex: number;
+    /** Transferred amount in token base units. */
+    amountRaw: string;
+};
+type WithdrawalPayoutScan = {
+    candidates: WithdrawalPayoutCandidate[];
+    /** Last block scanned (inclusive, decimal). Pass it back as the next `cursor`. */
+    scannedTo: string;
 };
 
-type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_NOTHING_TO_WITHDRAW" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "SWAP_DISABLED" | "SWAP_RATE_LIMITED" | "SWAP_REQUEST_FAILED" | "SWAP_QUOTE_FAILED" | "SWAP_UNSUPPORTED_PAIR" | "SWAP_APPROVAL_REQUIRED" | "SWAP_BELOW_DEPOSIT_MINIMUM" | "SWAP_DEPOSIT_PENDING" | "SWAP_WALLET_PROMPT_TIMEOUT" | "SWAP_INSUFFICIENT_GAS" | "SWAP_NATIVE_UNSUPPORTED" | "SWAP_ORDER_EXPIRED" | "SWAP_ORDER_REFUNDED" | "SWAP_ORDER_CANCELLED" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "POOL_CATALOG_UNSUPPORTED" | "POOL_SELECTION_UNSUPPORTED" | "VALIDATION_INVALID_DAYS";
+type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "AGENT_ACTIVATION_PARTIAL_FAILURE" | "YIELDSEEKER_AGENT_MISSING" | "YIELDSEEKER_WALLET_UNVERIFIED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_IN_PROGRESS" | "DEPOSIT_CHECKPOINT_FAILED" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_INVALID_AMOUNT" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_IN_PROGRESS" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_BALANCE_UNAVAILABLE" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_UNCONFIRMED" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_SWAP_INCOMPLETE" | "WITHDRAW_FAILED" | "WITHDRAW_INVALID_AMOUNT" | "WITHDRAW_RESERVATION_UNAVAILABLE" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "AGENT_API_ERROR" | "AGENT_AUTH_FAILED" | "AGENT_INVALID_RESPONSE" | "AGENT_TIMEOUT" | "AGENT_TRANSACTION_REVERTED" | "AGENT_APY_PERIOD_UNSUPPORTED" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "SWAP_DISABLED" | "SWAP_RATE_LIMITED" | "SWAP_REQUEST_FAILED" | "SWAP_QUOTE_FAILED" | "SWAP_UNSUPPORTED_PAIR" | "SWAP_APPROVAL_REQUIRED" | "SWAP_BELOW_DEPOSIT_MINIMUM" | "SWAP_DEPOSIT_PENDING" | "SWAP_WALLET_PROMPT_TIMEOUT" | "SWAP_INSUFFICIENT_GAS" | "SWAP_NATIVE_UNSUPPORTED" | "SWAP_ORDER_EXPIRED" | "SWAP_ORDER_REFUNDED" | "SWAP_ORDER_CANCELLED" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "EARNINGS_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
 declare class OwneyError extends Error {
     readonly code: OwneyErrorCode;
     readonly details?: Record<string, unknown>;
     readonly agentId?: string;
+    /** Funding ledger reference, set when a funding operation fails. */
+    operationId?: string;
     constructor(code: OwneyErrorCode, message: string, details?: Record<string, unknown>, agentId?: string);
 }
 declare class AgentNotFoundError extends OwneyError {
@@ -989,41 +1197,35 @@ declare class AgentChainIncompatibleError extends OwneyError {
     }>, connectedChainId: number);
 }
 
-/**
- * Withdrawal swaps the user has walked away from, and how they ended.
- *
- * The deposit side has `swap.pending-deposit.ts` for the same shape of
- * problem, but the two are not symmetrical. A pending deposit is a JOB: the
- * money is in the wallet and an ordinary deposit finishes it. This is a
- * WATCH — the funds are in escrow, nothing the user does moves them along,
- * and the only question is where they ended up.
- *
- * That is the whole reason this exists. `withdrawAndSwap` used to hold the
- * screen for the entire escrow lifecycle, which on a slow mainnet fill is
- * minutes of a modal the user cannot leave (ROUT-242). Backgrounding it means
- * the outcome arrives after the UI that started it has gone, so the outcome
- * has to be written down somewhere the next render can find it.
- *
- * Only cross-chain swaps are recorded. A same-chain classic swap is one
- * transaction and resolves in seconds; a same-chain fusion order has no stored
- * preimages, so there would be nothing for a reloaded session to resume and
- * the record would sit at `swapping` for ever.
- *
- * Kept deliberately separate from the secret store. Secrets are retired the
- * moment an order reaches a verdict — that is a safety property, not a display
- * one — and the record has to outlive them so the user can still be told what
- * happened after they come back.
- */
-/**
- * `swapping` is the only non-terminal state. `unknown` is what a watch that
- * gave up looks like: we stopped polling before the order spoke, so the order
- * may well have filled. It is not a failure, and it must never be shown as
- * one.
- */
-type WithdrawSwapStatus = "swapping" | "landed" | "refunded" | "unknown";
+/** Durable intent and evidence, including the gap before an order exists. */
+type WithdrawalSwapRecovery = {
+    attemptId: string;
+    phase: "withdrawing" | "verifying" | "ready" | "submitted" | "incomplete";
+    baseline: string;
+    baselineBlock: string;
+    submittedAt: number;
+    deadline: number;
+    requested?: string;
+    agentId?: AgentId;
+    results?: Record<string, AgentWithdrawResult>;
+    evidence: Record<string, FundingEvidence>;
+    reason?: string;
+};
+/** Unknown and partial outcomes remain recoverable until settlement is verified. */
+type WithdrawSwapStatus = "swapping" | "landed" | "refunded" | "unknown" | "refund-pending" | "partially-filled" | "withdrawal-pending" | "withdrawal-incomplete" | "ready" | "not-swapped";
 type WithdrawSwapRecord = {
     /** Identity. One record per Fusion+ order. */
     orderHash: string;
+    walletAddress?: string;
+    txHash?: string;
+    /**
+     * The funding-ledger operation of this withdrawal and swap, reused when it
+     * is continued or rechecked. Absent on records written by an older SDK.
+     */
+    operationId?: string;
+    recovery?: WithdrawalSwapRecovery;
+    spent?: string;
+    dismissed?: boolean;
     status: WithdrawSwapStatus;
     /**
      * What actually left the agent, smallest unit of the SOURCE asset.
@@ -1060,7 +1262,7 @@ declare function subscribeWithdrawSwaps(listener: () => void): () => void;
  * Not after the swap resolves: the point is to survive the gap between submit
  * and settle, which is exactly when the user closes the tab.
  */
-declare function saveWithdrawSwap(record: WithdrawSwapRecord): void;
+declare function saveWithdrawSwap(record: WithdrawSwapRecord): boolean;
 /**
  * Move a record to its outcome.
  *
@@ -1074,8 +1276,8 @@ declare function saveWithdrawSwap(record: WithdrawSwapRecord): void;
 declare function updateWithdrawSwap(orderHash: string, patch: Partial<Omit<WithdrawSwapRecord, "orderHash">>): void;
 /** The user has read the outcome. Only they do this. */
 declare function clearWithdrawSwap(orderHash: string): void;
-/** Every record, newest first, sweeping anything past MAX_AGE_MS. */
-declare function listWithdrawSwaps(now?: number): WithdrawSwapRecord[];
+/** Visible records, newest first. Only verified terminal records expire by age. */
+declare function listWithdrawSwaps(now?: number, includeDismissed?: boolean): WithdrawSwapRecord[];
 
 /**
  * Swaps that landed but were never deposited.
@@ -1110,6 +1312,11 @@ type PendingDeposit = {
     agentId?: string;
     /** Epoch ms, for the sweep. */
     createdAt: number;
+    /**
+     * The swap's funding-ledger operation, so finishing the deposit reports into
+     * it. Absent on records written by an older SDK.
+     */
+    operationId?: string;
 };
 /** Every record, dismissed ones included, newest first. Sweeps as it goes. */
 declare function listPendingDeposits(now?: number): PendingDeposit[];
@@ -1124,22 +1331,80 @@ declare class OwneySDK {
      */
     private disabledAgents;
     private state;
+    private connectionRevision;
+    private disconnectingAgents;
     private apiKey;
     private orgAgentConfig;
     private orgAgentConfigPromise;
+    private rpcUrls?;
     private zyfaiRpcUrls?;
-    private userPoolCustomization;
+    private yieldseekerApiBaseUrl?;
+    private yieldseekerSiweOrigin?;
     private routingApiBaseUrl?;
     private referralSource?;
+    private readonly ledger;
+    private readonly reservationMode;
+    private readonly reservationTransport;
     private cachedSponsoredCallback;
     private cachedWethSponsoredCallback;
     private paymasterServiceUrl?;
     private cachedSponsoredCallsCallbacks;
     private readonly agentReads;
+    private readonly depositFamilyReads;
+    private readonly recoveredFundingReads;
+    private fundingBalanceChecks;
     private readonly activationChecks;
+    private readonly withdrawalSubmissions;
+    private readonly withdrawalSwapSubmissions;
     private readAgent;
     private initializingAgentsPromise;
     constructor(config: OwneySDKConfig);
+    /** Finishes a funding-ledger operation on success and adds its reference to
+     * the result. The result object is copied, never mutated or replaced.
+     * `OK` replaces any failure code an earlier attempt of the same operation
+     * recorded (a resumed pending deposit, a continuation). */
+    private ledgerSucceeded;
+    /** Tags a failure with its funding-ledger reference and finishes the
+     * operation. The error is never wrapped or replaced. */
+    private ledgerFailed;
+    /**
+     * Swap operations running right now, by operationId. A deposit or withdrawal
+     * started with one of these ids is the inner half of that swap and joins its
+     * operation instead of starting its own (see `startLedger`).
+     */
+    private readonly openSwapLedgers;
+    /**
+     * Starts a funding-ledger operation, or joins the open swap operation with
+     * the same id. A joined call reports its legs into the swap's operation and
+     * leaves finishing to the swap, so the operation gets one outcome, sent on
+     * one ordered request chain.
+     */
+    private startLedger;
+    /** Starts a swap's operation and opens it to the swap's inner deposit or
+     * withdrawal. Never throws: reporting never blocks a swap. */
+    private openSwapLedger;
+    private closeSwapLedger;
+    /** Reports one agent's withdrawal evidence as its leg. Never throws. */
+    private ledgerWithdrawalLeg;
+    /** Operation/leg/tx keys whose provider samples are already scheduled. */
+    private readonly providerSampleKeys;
+    /**
+     * For a confirmed leg of an operation this SDK reported, records the agent's
+     * own earnings bookkeeping as `provider.sample` events at confirmation, +5
+     * and +30 min (Zyfai; evidence for provider lag). Only agents that expose a
+     * never-prompting sample read take part. Fire-and-forget, never throws;
+     * a later sample is skipped once the wallet disconnects or changes.
+     */
+    private ledgerProviderSamples;
+    /**
+     * Funding-ledger read access handed to agents for earnings holds. Reads only
+     * for the connected owner; null otherwise and on any failure.
+     */
+    private agentLedgerAccess;
+    /** Reports the swap leg. Never throws: reporting never affects a swap. */
+    private ledgerSwap;
+    /** Reports the swap leg of a swap that threw, with any identifier it carried. */
+    private ledgerSwapFailed;
     /**
      * Establish connection state for all subsequent SDK calls.
      * Must be called once before any agent operation that requires a wallet.
@@ -1151,6 +1416,8 @@ declare class OwneySDK {
      * After calling this, `connect()` must be called again before using agent methods.
      */
     disconnect(): Promise<void>;
+    private clearConnectionState;
+    private disconnectAgents;
     private isAgentDisabled;
     /**
      * Check if the SDK has an active connection state.
@@ -1162,31 +1429,39 @@ declare class OwneySDK {
      * @returns The active chain ID, or `null` if `activateAgent` has not been called
      */
     getActiveChainId(): number | null;
+    /**
+     * The funding-ledger operations this app has for the connected wallet and
+     * `asset` (default chain: the active one). Never throws: resolves `null` when
+     * not connected, with no chain, when ledger reporting is disabled, or on any
+     * failure, which callers treat as "no ledger information".
+     *
+     * Full `clientOperationId`s come back only for ids passed in `ids`. The ids
+     * are trimmed and lowercased, non-uuid strings are dropped, and the first 50
+     * distinct ids (caller order) are sent; the rest are ignored.
+     */
+    listFundingOperations(opts: {
+        chainId?: number;
+        asset: string;
+        ids?: string[];
+        since?: Date;
+    }): Promise<FundingOperationRow[] | null>;
     private requireState;
     private requireChainId;
     private requireConnectedProvider;
-    /**
-     * Lazily builds (and caches) the default EIP-3009 sponsored deposit callback
-     * used when the caller omits `depositCallback`. Wraps the connected EIP-1193
-     * provider with viem `custom(provider)` to read token meta and sign the
-     * `TransferWithAuthorization`, then POSTs to the sponsor API.
-     */
+    private getPaidRpcClient;
+    /** Builds the default USDC batch callback for the connected wallet. */
     private getDefaultSponsoredCallback;
-    /**
-     * Lazily builds (and caches) the default Permit2 sponsored WETH deposit
-     * callback used when the caller omits `depositCallback` for a WETH
-     * deposit. Mirrors `getDefaultSponsoredCallback()` but signs a Permit2
-     * `PermitTransferFrom` instead of an EIP-3009 authorization.
-     */
+    /** Builds the wallet-native sponsored calls callback for compatible paymasters. */
     private getDefaultSponsoredCallsCallback;
     /**
      * Lazily builds (and caches) the default Permit2 sponsored WETH deposit
      * callback used when the caller omits `depositCallback` for a WETH deposit.
      * Mirrors `getDefaultSponsoredCallback()` but signs a Permit2
-     * `PermitTransferFrom` instead of an EIP-3009 authorization.
+     * single-use batch authorization instead of an EIP-3009 authorization.
      */
     private getDefaultWethSponsoredCallback;
     private getAgent;
+    getActiveAgentIds(): AgentId[];
     private getActiveAgents;
     /**
      * Read the org's agent policy once and reuse it. fetchOrgAgentConfig never
@@ -1219,7 +1494,8 @@ declare class OwneySDK {
      *   If provided, ALL specified agents must support the chainId or the call
      *   throws before activating any agent.
      */
-    activateAgent(chainId: number, agentId?: AgentId[]): Promise<void>;
+    activateAgent(chainId: number, agentId?: AgentId[], asset?: OwneySupportedTokens): Promise<void>;
+    private assertActivationSession;
     /**
      * Activate agents ONE AT A TIME, each followed by its org policy.
      *
@@ -1233,10 +1509,9 @@ declare class OwneySDK {
      * Serializing costs no real wall-clock: the user can only approve one prompt
      * at a time anyway.
      *
-     * Every agent is attempted even if an earlier one fails, so one declined
-     * signature can't deny the remaining agents their turn. The first failure is
-     * rethrown (matching the previous `Promise.all` rejection) once all agents
-     * have had a chance to activate.
+     * Stop at the first failure so a canceled sign-in does not open another
+     * agent's wallet prompt. Report any earlier successes for diagnostics; the
+     * app discards the session when the complete sign-in does not succeed.
      */
     private activateAgentsInTurn;
     /**
@@ -1247,7 +1522,8 @@ declare class OwneySDK {
      * @param options.asset - Asset symbol to deposit (e.g. "USDC")
      * @param options.depositCallback - Callback that performs the token transfer and returns a tx hash.
      *   When agentId is omitted, this callback is invoked once per eligible agent with that agent's
-     *   split amount and smart wallet address — expect multiple wallet prompts.
+     *   split amount and smart wallet address. Default sponsored deposits batch
+     *   all shares into one signature; custom callbacks still run once per agent.
      * @param options.agentId - Optional explicit target. Otherwise split equally,
      *   or fund remaining agents when a recovery deposit cannot meet every minimum.
      * @returns {OwneyDepositResult} for a single agent, or {OwneyMultiDepositResult} with per-agent results
@@ -1257,10 +1533,12 @@ declare class OwneySDK {
      * Invokes `agent.deposit` with the resolved sponsored callback, composing
      * two independent auto-recovery mechanisms:
      *
-     * 1. Missing Permit2 allowance: when the app did not supply its own
-     *    callback and the attempt fails with `PERMIT2_APPROVAL_REQUIRED` on a
-     *    WETH deposit, this is the wallet's first gasless WETH deposit. We send
-     *    the one-time (user-paid) Permit2 approval via `approvePermit2()` and
+     * 1. Missing Permit2 allowance outside the sponsored ERC-2612 path: when the
+     *    app did not supply its own callback and the attempt fails with
+     *    `PERMIT2_APPROVAL_REQUIRED`, this is the wallet's first Permit2 deposit
+     *    for that token. Native Base/Arbitrum USDC uses gasless ERC-2612 approval in
+     *    its sponsored deposit and never reaches this branch. Other tokens send
+     *    the one-time user-paid Permit2 approval via `approvePermit2()` and
      *    retry the SAME sponsored attempt once. Bounded to one approval attempt
      *    per call so a wallet/agent that keeps reporting the allowance as
      *    missing can't loop forever. If `approvePermit2()` itself throws (e.g.
@@ -1281,6 +1559,7 @@ declare class OwneySDK {
     private depositWithFallback;
     private getMinDepositAmount;
     private splitDepositAmount;
+    private formatAgentName;
     private validateMinDepositAmount;
     /**
      * Whether the user already holds a non-zero balance with `agent` for the
@@ -1289,25 +1568,70 @@ declare class OwneySDK {
      * false, so the minimum is enforced as today.
      */
     private hasExistingBalance;
-    /**
-     * Guard an explicitly requested chain against one agent's own list.
-     *
-     * Only reachable when the caller passes `chainId` — the activated chain has
-     * already been checked by `activateAgent`. Kept separate from
-     * `validateAssetSupport` so "this agent is not on Ethereum" does not arrive
-     * worded as "this agent does not support USDC".
-     */
-    private validateChainSupport;
-    /**
-     * Guard an explicitly requested chain before a fan-out.
-     *
-     * Without this the split simply produces no agents, and the caller is told
-     * their amount "cannot activate every eligible agent" against a combined
-     * minimum of 0 — an error about the amount when the chain is at fault.
-     */
-    private validateChainHasAgents;
     private validateAssetSupport;
     private getEligibleAgents;
+    /**
+     * Run owner-approved withdrawals before relayer-only withdrawals. Wallet
+     * approval is the only point at which the user can cancel the aggregate
+     * operation, so no relayer leg should commit before it has completed.
+     */
+    private orderAgentsForWithdrawal;
+    private isUserRejectedWithdrawal;
+    private captureReadScope;
+    /** Revalidate a saved transfer against the authenticated account and actual receipt. */
+    inspectFunding(evidence: FundingEvidence, direction: "deposit" | "withdraw", options?: {
+        balanceRefreshUntil?: number;
+        refreshBalance?: boolean;
+        requireAmountMatch?: boolean;
+    }): Promise<FundingEvidence>;
+    /**
+     * Lists on-chain payout candidates for a withdrawal the provider accepted
+     * without a hash: ERC-20 `Transfer` logs on the evidence's token that reach
+     * the owner, from `max(fromBlock, cursor − 20)` to `latest − 3`, chunked.
+     * Discovery only: prove each candidate with
+     * `inspectFunding({ ...evidence, txHash }, "withdraw", { requireAmountMatch: true })`.
+     *
+     * `fromBlock` defaults to `evidence.payoutSearch.fromBlock`; without either
+     * (legacy records) the start is estimated from
+     * `withdrawalRequest.acceptedAt ?? submittedAt` minus 5 minutes. Pass the
+     * returned `scannedTo` back as `cursor` to scan only new blocks.
+     * Never prompts and never throws: null on any failure or scope mismatch.
+     */
+    findWithdrawalPayoutCandidates(evidence: FundingEvidence, opts?: {
+        fromBlock?: string;
+        cursor?: string;
+        submittedAt?: number;
+    }): Promise<WithdrawalPayoutScan | null>;
+    /** Resolve a saved sponsored-withdrawal ID without opening a wallet prompt. */
+    resolveSponsoredWithdrawalEvidence(evidence: FundingEvidence, options?: {
+        submittedAt?: number;
+    }): Promise<FundingEvidence>;
+    /** Recover an EIP-5792 deposit or payout using this account's exact batch ID. */
+    resolveWalletCallsFundingEvidence(evidence: FundingEvidence, direction: "deposit" | "withdraw"): Promise<FundingEvidence>;
+    /** Whether a foreground deposit can resume the same signed batch, never a
+     * fresh authorization. The batch rail independently rechecks the exact plan. */
+    canResumePendingDeposit(evidences: FundingEvidence[], amount: string): Promise<boolean>;
+    /** Validate signed journal membership, never just a caller-supplied family ID. */
+    validateDepositReplacement(previous: FundingEvidence[], next: FundingEvidence[]): Promise<DepositReplacementValidation | undefined>;
+    /** Optional post-payout display proof; receipt verification and the provider
+     * adapter must agree before attaching it to this exact balance object. */
+    verifyWithdrawalBalance(evidence: FundingEvidence, balance: AgentBalance): Promise<AgentBalance>;
+    /** A display acknowledgement controls polling only; it never confirms a financial outcome. */
+    endFundingBalanceRefresh(evidence: FundingEvidence, read: AssetReadMetadata): boolean;
+    /** History lookup for receipt recovery; adapters may not authenticate or sign here. */
+    getFundingHistory(evidence: FundingEvidence, fromDate: string, options?: Pick<HistoryFilters, "cursor" | "toDate">): Promise<OwneyAgentHistory>;
+    recoverDepositRegistration(evidence: FundingEvidence): Promise<FundingEvidence>;
+    /** On-chain version and ownership status for this owner's Yieldseeker agent. */
+    getYieldseekerWalletStatus(asset: OwneySupportedTokens): Promise<YieldseekerWalletStatus | null>;
+    /** Deployment gate; an unavailable response keeps the current paid path. */
+    isYieldseekerWithdrawalSponsorshipAvailable(): Promise<boolean>;
+    isYieldseekerUpgradeSponsorshipAvailable(): Promise<boolean>;
+    private isYieldseekerSponsorshipAvailable;
+    /** Explicit V1-to-V2 upgrade, confirmed on chain before returning. */
+    upgradeYieldseekerWallet(asset: OwneySupportedTokens, gasMode?: "paid" | "sponsored"): Promise<{
+        txHash: viem.Hex;
+        status: YieldseekerWalletStatus;
+    }>;
     /** Lazily built so an app that never swaps pays nothing for it. */
     private swapApiClient?;
     private swapApi;
@@ -1352,45 +1676,15 @@ declare class OwneySDK {
      * would strand funds we might have been able to move.
      */
     /** ERC20 balance of the connected wallet, read through the wallet's own node. */
-    /**
-     * A read client pinned to `chainId`, over HTTP rather than the wallet.
-     *
-     * The swap rail has read this way from the start, and the reason is written
-     * out at `buildSwapDeps`: a provider-backed client reads from whatever chain
-     * the WALLET is on, which after a cross-chain swap is the source chain, not
-     * the one the funds landed on. The deposit's own reads did not, so a Permit2
-     * check for WETH on Arbitrum went to Base — where that address is not a
-     * contract at all, so viem got "0x" back and threw "The contract function
-     * 'allowance' returned no data".
-     */
-    private chainReader;
     private readTokenBalance;
     /** How much of `token` the wallet has already approved Permit2 to move. */
     private readTokenPermit2Allowance;
     /**
-     * How much of a landed swap to actually deposit.
-     *
-     * The swap reports what ARRIVED, and the deposit used to be handed that
-     * figure directly. It is the entire arrival, so there is no slack: anything
-     * that spends the target asset between the two fails the deposit outright.
-     *
-     * Something does. A first WETH deposit needs a one-time Permit2 approval,
-     * and that approval is a transaction. A wallet holding no native gas token -
-     * the normal state of someone who just swapped everything INTO WETH - pays
-     * for it out of the WETH. The deposit then asked for ~2e12 wei more than was
-     * left and refused with DEPOSIT_INSUFFICIENT_BALANCE, under a wrapper saying
-     * the funds were safe but unadded (ROUT-242).
-     *
-     * So the approval happens here, before the amount is settled, and the amount
-     * comes from a read taken after it. Two things this deliberately is not:
-     *
-     * - It is not a balance sweep. `received` is a DELTA over the pre-swap
-     *   balance, so a wallet already holding WETH reads far above it; depositing
-     *   the balance would move funds the user never offered. The arrival is the
-     *   ceiling and the balance is only ever allowed to lower it.
-     * - It does not touch USDC, which moves on signed typed data and so spends
-     *   nothing of the user's in between, nor a paymaster-configured client,
-     *   where the sponsor covers the transfer and Permit2 never applies.
+     * Finish any user-paid Permit2 approval before measuring the deposit.
+     * Wallets can charge approval gas in the received token (ROUT-242/544).
+     * Cap the result at the swap arrival to preserve pre-existing wallet funds.
+     * Native Base/Arbitrum USDC uses sponsored ERC-2612; configured paymaster
+     * wallet calls also cover approval without spending the received tokens.
      */
     private settleSwapDepositAmount;
     private walletSeesBalance;
@@ -1463,11 +1757,12 @@ declare class OwneySDK {
      * Every order is attempted even if an earlier one throws: they are unrelated
      * escrows, and one ending badly must not abandon the next one's secrets.
      * `unfinished` is not a verdict — the order may still settle, so unless the
-     * chain has said refunded or cancelled its preimages are kept.
+     * provider has confirmed full settlement or refund, its preimages are kept.
      */
     resumePendingSwaps(options?: {
         onStage?: (orderHash: string, stage: SwapStage) => void;
         timeoutMs?: number;
+        orderHash?: string;
     }): Promise<{
         orderHash: string;
         status: "completed" | "unfinished";
@@ -1585,6 +1880,14 @@ declare class OwneySDK {
         /** Percent, classic rail only. Fusion+ prices through its auction. */
         slippage?: number;
         onSwapProgress?: (stage: SwapStage) => void;
+        /** Destination balance baseline, read after the swap and before deposit preparation. */
+        onBeforeDeposit?: () => Promise<void>;
+        onDepositProgress?: FundingProgress;
+        onBeforeDepositSubmission?: DepositOptions["onBeforeSubmission"];
+        /** Stop a stale foreground attempt before it prepares or sends another transaction. */
+        assertCurrent?: () => void;
+        /** Funding-ledger reference for this swap and its deposit. Generated when omitted. */
+        operationId?: string;
     }): Promise<{
         swap: {
             received: string;
@@ -1598,6 +1901,24 @@ declare class OwneySDK {
          * want this one; `swap.received` stays what it says it is.
          */
         deposited: string;
+        /** Funding-ledger reference shared by the swap and its deposit. */
+        operationId?: string;
+    }>;
+    /** Read-only confirmation of a saved pre-swap withdrawal. Never withdraws or swaps. */
+    recheckWithdrawalSwap(id: string): Promise<WithdrawSwapRecord>;
+    /** Explicit foreground continuation: spends verified payouts, never withdraws again. */
+    continueWithdrawalSwap(id: string, callbacks?: Pick<Parameters<OwneySDK["withdrawAndSwap"]>[0], "onSwapProgress" | "onOrderSubmitted" | "onWithdrawalProgress" | "assertCurrent">): Promise<{
+        withdraw: OwneyWithdrawResult | AgentWithdrawResult;
+        /** What actually arrived in the wallet, smallest unit of the agent's asset. */
+        withdrawn: string;
+        swap: {
+            received: string;
+            spent?: string;
+            orderHash?: string;
+            txHash?: string;
+        };
+        /** Funding-ledger reference shared by the withdrawal and the swap. */
+        operationId?: string;
     }>;
     /**
      * Withdraw from an agent and swap the proceeds into whatever the user wants
@@ -1611,10 +1932,9 @@ declare class OwneySDK {
      * Quoting before the tokens land would size the swap against a balance that
      * is not there yet.
      *
-     * The swap is therefore sized from the MEASURED arrival, exactly as the
-     * deposit path sizes its deposit from the measured swap output. On a full
-     * withdrawal there is no other number available — "MAX" has no figure until
-     * the agent picks one.
+     * Wait for each participating agent's owner payout and size one swap from
+     * their confirmed net amounts. A first wallet increase cannot establish
+     * that every payout arrived. Failed or incomplete withdrawals stop here.
      *
      * **Failure here is not symmetrical with the deposit path.** A failed
      * deposit-swap leaves the user holding what they started with. A failed
@@ -1634,6 +1954,7 @@ declare class OwneySDK {
         to: {
             chainId: number;
             symbol: string;
+            decimals?: number;
         };
         /** Human units ("10.5"). Omit to withdraw the full agent balance. */
         amount?: string;
@@ -1641,6 +1962,8 @@ declare class OwneySDK {
         /** Percent, classic rail only. Fusion+ prices through its auction. */
         slippage?: number;
         onSwapProgress?: (stage: SwapStage) => void;
+        /** Receipt evidence for the existing funding/recovery tracker. */
+        onWithdrawalProgress?: FundingProgress;
         /**
          * Fires once the order is with the relayer, before the watch.
          *
@@ -1666,18 +1989,32 @@ declare class OwneySDK {
             withdrawn: string;
             /** Smallest unit of the destination — the auction's start, not its floor. */
             expected: string;
+            spent?: string;
+            durable?: boolean;
         }) => void;
         /** How long to wait for the withdrawal to land before giving up on the swap. */
         arrivalTimeoutMs?: number;
+        /** UI ownership fence, checked before each financial continuation. */
+        assertCurrent?: () => void;
+        /** Used only by explicit continueWithdrawalSwap; it never sends another withdrawal. */
+        recoveryId?: string;
+        /**
+         * Funding-ledger reference for this withdrawal and swap. Generated when
+         * omitted; a continuation reuses the one saved on its record.
+         */
+        operationId?: string;
     }): Promise<{
         withdraw: OwneyWithdrawResult | AgentWithdrawResult;
         /** What actually arrived in the wallet, smallest unit of the agent's asset. */
         withdrawn: string;
         swap: {
             received: string;
+            spent?: string;
             orderHash?: string;
             txHash?: string;
         };
+        /** Funding-ledger reference shared by the withdrawal and the swap. */
+        operationId?: string;
     }>;
     /**
      * Withdraw funds from a specific agent, or all agents that support the active chain+asset if agentId is omitted.
@@ -1689,25 +2026,62 @@ declare class OwneySDK {
      * @returns {AgentWithdrawResult} for a single agent, or {OwneyWithdrawResult} with per-agent results
      */
     withdraw(options: WithdrawOptions): Promise<OwneyWithdrawResult | AgentWithdrawResult>;
+    /**
+     * Claims the cross-device hold for every agent in the plan. Returns the hold,
+     * or undefined when the reservation is off or the API is unavailable and the
+     * mode is fail-open. Throws only before anything is submitted:
+     * - `WITHDRAW_IN_PROGRESS` / `RESERVED_ELSEWHERE` on a 409;
+     * - `WITHDRAW_RESERVATION_UNAVAILABLE` when unavailable and fail-closed.
+     */
+    private reserveWithdrawal;
+    /**
+     * The cached Yieldseeker SIWE proof, when Yieldseeker is active for this
+     * SDK. Cache only: never prompts. Yieldseeker signs on Base, so a claim on
+     * another chain falls back to the Base proof (the server checks the
+     * signature, the address and its age, not the chain).
+     */
+    private peekReservationProof;
+    /**
+     * Releases or keeps each agent's hold when `withdraw()` ends. Never throws.
+     * - unattempted agents: `not_submitted`;
+     * - `confirmed` / definitively `failed` legs: released;
+     * - pending/unknown legs (Zyfai's hashless acknowledgement): kept;
+     * - a throw without submission evidence: `not_submitted`;
+     * - Zyfai "withdrawal already in progress": kept, dispatch `provider_in_progress`.
+     */
+    private settleWithdrawalReservation;
+    /**
+     * Releases a withdrawal reservation this browser still holds (the holder
+     * token is kept per operationId). Use it when the app learns the outcome of a
+     * kept hold, for example a Zyfai payout that arrived later. Never throws; a
+     * hold this SDK does not know about is left to the server's expiry.
+     */
+    releaseWithdrawalReservation(operationId: string, reason: ReservationReleaseReason, agents?: ReservationAgent[]): Promise<void>;
+    /**
+     * Reports a withdrawal leg that was proven after its call ended (a hashless
+     * Zyfai payout found on chain or in history) to the funding ledger, then
+     * releases the withdrawal reservation this browser holds, as a fallback to
+     * the server's own release. Only evidence with a hash whose transfer and
+     * delivery are both confirmed is reported; anything else is ignored.
+     * The ledger PATCHes the existing operation (creating it only on a 404) and
+     * the server re-verifies the hash. Never throws.
+     */
+    reportWithdrawalRecovery(operationId: string, evidence: FundingEvidence): Promise<void>;
+    private withdrawFromAgents;
+    /** Read-only invalidation after new pool-deposit activity. Does not restart
+     * funding reconciliation, bypass cooldowns, or authorize a transaction. */
+    invalidateAllocationRead(scope: Pick<FundingEvidence, "agentId" | "walletAddress" | "chainId" | "token">): boolean;
     /**
      * Get the user's balances for a specific agent, or aggregated across all agents.
      * @param agentId - Optional. Agent to query. Omit for aggregated balances.
      * @returns {AgentBalance} for a single agent, or {OwneyBalances} with totalBalance and per-agent breakdown
      */
-    /**
-     * Withdraw every position the wallet holds, across chains and assets.
-     *
-     * `withdraw()` drains one asset on one chain, so this is N of those. It
-     * deliberately does not stop at the first failure: the funds in the other
-     * positions are just as withdrawable, and someone who asked for everything
-     * is better served by three of four than by none. Each leg reports its own
-     * outcome so the caller can name the ones that did not arrive; only a total
-     * failure throws.
-     *
-     * @returns {OwneyWithdrawAllResult} one leg per position attempted.
-     */
-    withdrawAll(): Promise<OwneyWithdrawAllResult>;
-    getBalances(agentId?: AgentId): Promise<OwneyBalances | AgentBalance>;
+    getBalances(agentId?: AgentId, options?: {
+        chainId?: number;
+        asset?: OwneySupportedTokens;
+    }): Promise<OwneyBalances | AgentBalance>;
+    /** Preserve failure objects for withdrawal recovery without changing public balance results. */
+    private readAggregatedBalances;
     /**
      * Get the user's on-chain earnings for a specific agent, or aggregated across all agents.
      * @param agentId - Optional. Agent to query. Omit for aggregated earnings.
@@ -1719,6 +2093,7 @@ declare class OwneySDK {
      * Agents without a refresh capability fall back to their current snapshot.
      */
     refreshEarnings(agentId?: AgentId): Promise<OwneyEarnings | AgentEarnings>;
+    private aggregateEarnings;
     /**
      * Get the weighted APY for the user's account over a time period.
      * When querying all agents, the total APY is a balance-weighted average.
@@ -1728,37 +2103,16 @@ declare class OwneySDK {
      * @returns {AccountAgentApy} for a single agent, or {OwneyAccountApy} with totalApy and per-agent breakdown
      */
     /**
-     * Daily cumulative NET earnings for the selected chain/asset, backing the
-     * "recent earnings" subline. Net is computed as Zyfai's own
-     * `lifetime + unrealized + current x 0.9`, so the figure reconciles with the
-     * balance headline rather than reading ~11% high. (ROUT-452)
+     * Daily cumulative earnings in the selected asset's units, backing the
+     * "recent earnings" subline. Each adapter uses its provider's earnings basis.
      *
      * Unlike getAccountApy this does NOT blend across agents: earnings are
      * summed, not weighted, and an agent that fails to report must not silently
      * subtract from the total. Without an agentId the series is the sum of the
      * agents that answered.
      */
-    getDailyEarnings({ agentId, days, tokenSymbol, chainIds, }: DailyEarningsOptions): Promise<AccountDailyEarnings>;
-    /**
-     * The deposit-time pool catalogue (ROUT-569): every protocol with its
-     * selectable pools (name, APY, TVL, link) for `asset` under `strategy`.
-     * Defaults to the zyfai agent, the only one with pool customization today.
-     */
-    getPoolCatalog(params: {
-        asset: OwneySupportedTokens;
-        strategy: "conservative" | "aggressive" | "yieldmaxxing";
-        agentId?: AgentId;
-    }): Promise<PoolCatalogProtocol[]>;
-    /**
-     * Apply a user's deposit-time pool selection to their account (ROUT-569).
-     * The request carries explicit pool choices plus the resulting strategy for
-     * each asset reviewed in the deposit flow.
-     */
-    setPoolSelection(params: {
-        selection: UserPoolSelectionRequest;
-        agentId?: AgentId;
-    }): Promise<void>;
-    getAccountApy({ agentId, days, tokenSymbol, chainId: scope, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
+    getDailyEarnings({ agentId, days, tokenSymbol, }: DailyEarningsOptions): Promise<AccountDailyEarnings>;
+    getAccountApy({ agentId, days, tokenSymbol, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
     /**
      * Get transaction history for a specific agent, or all agents.
      *
@@ -1792,14 +2146,17 @@ declare class OwneySDK {
      */
     ensureAutoSelectProtocols(asset: "USDC" | "WETH", agentId?: AgentId): Promise<boolean>;
     /**
-     * One-time, user-paid approval of Permit2 on the sponsored WETH token for
-     * the active chain. Required once per wallet per chain before gasless WETH
-     * deposits; afterwards deposit() is signature-only. Resolves only after the
-     * approval transaction is mined (1 confirmation), so a subsequent deposit()
-     * will see the new allowance; throws if the transaction reverted.
+     * User-paid approval of Permit2 on the selected token for the active chain.
+     * Grants the maximum ERC20 allowance so later deposits do not require another
+     * approval. Resolves after one confirmation so the subsequent deposit attempt
+     * sees the new allowance. Deposit retries pass their captured chain id so a
+     * concurrent activation cannot redirect the approval to another network.
+     *
+     * @param requiredAmount Raw base-unit amount the pending deposit must cover.
+     * @param expectedChainId Chain captured by the deposit that requested approval.
      * @returns the approval transaction hash.
      */
-    approvePermit2(asset?: "WETH"): Promise<`0x${string}`>;
+    approvePermit2(asset?: OwneySupportedTokens, requiredAmount?: bigint, expectedChainId?: OwneySupportedChainId, assertCurrent?: () => void): Promise<`0x${string}`>;
     /**
      * Get the agent's average APY performance over a time period. Does not require a wallet connection.
      * @param options - Contains agentId (optional) and days ("7D", "14D", or "30D")
@@ -1823,6 +2180,365 @@ declare class OwneySDK {
     getAllocationApy({ agentId, }?: AllocationApyOptions): Promise<OwneyAllocationApy>;
 }
 
+type YieldseekerAuthToken = {
+    message: string;
+    signature: Hex;
+};
+type YieldseekerAuthDependencies = {
+    origin?: string;
+    now?: () => Date;
+    nonce?: () => string;
+};
+
+type YieldseekerFetch = typeof fetch;
+
+type YieldseekerTransaction = {
+    from: `0x${string}`;
+    to: `0x${string}`;
+    data: `0x${string}`;
+    value: string;
+    chainId: number;
+};
+
+type YieldseekerWalletStatus = {
+    agentWallet: Address;
+    owner: Address;
+    ownerPath: "eoa" | "smart";
+    asset: Address;
+    implementation: Address;
+    version: "v1" | "v2" | "unknown";
+    upgradeAvailable: boolean;
+    /** The factory, owner, base asset, and provider wallet mapping all agree. */
+    verified: boolean;
+};
+
+type YieldseekerAgentOptions = {
+    baseUrl?: string;
+    routingApiBaseUrl?: string;
+    fetchFn?: YieldseekerFetch;
+    auth?: YieldseekerAuthDependencies;
+    /** Dedicated read transport; Base is used for receipt polling. */
+    rpcUrls?: RpcUrlsConfig;
+    /** Test seam for the wallet-submission/receipt boundary. */
+    transactionExecutor?: (state: ConnectionState, chainId: number, transaction: YieldseekerTransaction, onReceipt?: (receipt: viem.TransactionReceipt) => void) => Promise<Hex>;
+    /** Test seam for transactions submitted outside transactionExecutor. */
+    unwindReceiptWaiter?: (state: ConnectionState, chainId: number, transactionHash: Hex) => Promise<void>;
+};
+declare class YieldseekerAgent implements IAgent {
+    readonly id = "yieldseeker";
+    readonly balanceComposition: "tokens-plus-positions";
+    readonly withdrawalRequiresWalletApproval = true;
+    readonly supportedChainIds: readonly [8453];
+    readonly supportedAssets: readonly [{
+        readonly chainId: 8453;
+        readonly chain: "BASE";
+        readonly assets: readonly [{
+            readonly symbol: "USDC";
+            readonly minDepositAmount: "10000000";
+        }, {
+            readonly symbol: "WETH";
+            readonly minDepositAmount: "1";
+        }];
+    }];
+    private readonly api;
+    private readonly auth;
+    private readonly rpcUrls?;
+    private readonly owneyApiKey;
+    private readonly routingApiBaseUrl?;
+    private receiptClient?;
+    private readonly withdrawalVersionCache;
+    private readonly pendingWalletStatus;
+    /** Lowercase Agent Wallet -> when this instance's deploy request succeeded. */
+    private readonly recentDeployments;
+    private readonly pendingUpgrades;
+    private readonly transactionExecutor?;
+    private readonly unwindReceiptWaiter?;
+    private readonly agentContexts;
+    private readonly walletContexts;
+    private readonly agentAccountReads;
+    private readonly reportedAccounts;
+    private readonly missingSlots;
+    private readonly freshListReads;
+    private readonly knownContextKeys;
+    private readonly pendingSlotInvalidations;
+    private readonly balanceContexts;
+    private readonly balanceVaults;
+    private readonly users;
+    private readonly pendingAgents;
+    private readonly pendingWalletContexts;
+    private readonly readCache;
+    private readonly pendingReads;
+    private readGeneration;
+    private readonly portfolioVersions;
+    private readonly liquidityVersions;
+    private readonly snapshotFailures;
+    private readonly standardReadFailures;
+    private readonly endpointReadFailures;
+    private readonly reconcileUntil;
+    private readonly allocationRefresh;
+    private readonly activityRefreshUntil;
+    private readonly snapshotMovements;
+    private readonly movementEpochs;
+    private readonly settlementChecks;
+    private ledgerAccess?;
+    private readonly ledgerReads;
+    /** contextKey -> movements this instance started settling (by tx hash) and how they refresh:
+     * awaiting the ledger, refreshed when ready (ledger), or on the timed backoff (legacy). */
+    private readonly localMovements;
+    /** contextKey -> tx hash -> refresh-when-ready state of a ledger movement. */
+    private readonly refreshPlans;
+    /** contextKey -> the agent's ledger movements from the latest ledger read. */
+    private readonly ledgerMovementCache;
+    /** Contexts whose next snapshot request is a refresh-when-ready force. */
+    private readonly readyForces;
+    private readonly serverBaselines;
+    private readonly snapshotHistory;
+    /** contextKey -> the history key its refresh plans persist forced times under. */
+    private readonly planHistoryKeys;
+    /** A ledger read slower than this counts as "no ledger information" for that read. */
+    private ledgerBudgetMs;
+    /** slotKey -> the last successful ledger rows and when they arrived. */
+    private readonly lastLedgerRows;
+    private readonly vaultOptions;
+    private readonly pendingVaultOptions;
+    private readonly assetApyStats;
+    private readonly pendingAssetApyStats;
+    constructor(owneyApiKey: string, options?: YieldseekerAgentOptions);
+    private getReceiptClient;
+    /** Reads the actual proxy implementation; Yieldseeker's API walletType is not a version check. */
+    getWalletStatus(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, useCachedV2?: boolean): Promise<YieldseekerWalletStatus | null>;
+    /** Reads (or reuses the 15-minute verified V2 hint for) this exact context's wallet. */
+    private readWalletStatus;
+    /**
+     * Deposits go only to a wallet whose identity is verified on chain (factory
+     * mapping, owner, base asset, FACTORY). The API key is public, so the wallet
+     * the provider API returned is not trusted on its own. V1 wallets still
+     * accept deposits: only identity is required, not the V2 implementation.
+     * A failed read fails closed (reason UNAVAILABLE): an unverified wallet never
+     * receives funds. Session changes keep their own NOT_CONNECTED error.
+     */
+    private assertDepositWalletVerified;
+    private rememberWalletStatus;
+    /** Explicit owner action. This never runs as a side effect of withdrawal. */
+    upgradeWallet(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, gasMode?: "paid" | "sponsored"): Promise<{
+        txHash: Hex;
+        status: YieldseekerWalletStatus;
+    }>;
+    disconnect(): Promise<void>;
+    activateAgent(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<void>;
+    deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback, onProgress?: FundingProgress, onBeforeSubmission?: (evidence: FundingEvidence) => void | Promise<void>): Promise<OwneyDepositResult>;
+    withdraw(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, amount?: string, onProgress?: FundingProgress, gasMode?: "auto" | "sponsored" | "paid", onBeforeSubmission?: FundingProgress, assertOperation?: () => void): Promise<AgentWithdrawResult>;
+    private withdrawInternal;
+    /** Fresh position amounts for withdrawal planning, net of reserved fees. */
+    getWithdrawableBalance(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, minimumAmount?: bigint): Promise<bigint>;
+    /**
+     * The cached SIWE proof, decoded, for the withdrawal reservation claim's
+     * owner proof. Only a proof already in the cache: this never prompts the
+     * wallet and never throws. Never log the result.
+     */
+    peekReservationProof(state: ConnectionState, chainId: number): YieldseekerAuthToken | undefined;
+    /** Recheck MAX without re-unwinding, paying out, or requesting a signature. */
+    verifyWithdrawalCompletion(state: ConnectionState, evidence: FundingEvidence): Promise<WithdrawalCompletion>;
+    private readVaultShares;
+    private validateWithdrawalPositions;
+    private withdrawalVaultHints;
+    private readWithdrawalPositions;
+    private resolveWithdrawalLiquidity;
+    getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
+    verifyWithdrawalBalance(state: ConnectionState, evidence: FundingEvidence, balance: AgentBalance): Promise<AssetReadMetadata | undefined>;
+    invalidateAllocationRead(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): void;
+    invalidateFundingRead(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number, txHash?: string): void;
+    endFundingBalanceRefresh(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
+    getFundingWallet(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;
+    hasExistingDepositFunds(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
+    getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
+    getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays, tokenSymbol?: string): Promise<AccountAgentApy>;
+    getDailyEarnings(state: ConnectionState, chainId: number, days: LookbackDays, tokenSymbol?: string): Promise<AccountDailyEarnings>;
+    getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
+    getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
+    getAgentApy(days: DailyApyDays, options?: AgentApyOptions): Promise<AgentApy>;
+    supportsAgentApyPeriod(days: DailyApyDays): boolean;
+    private loadAssetApyStats;
+    private loadVaultOptions;
+    private userKey;
+    /** One deposit/withdraw slot: owner, chain and asset. */
+    private slotKey;
+    /**
+     * One agent's portfolio state. Includes the agentId so duplicate or renamed
+     * agents for the same asset never share caches, versions or settlement.
+     */
+    private contextKey;
+    /**
+     * Context keys an asset-only call applies to: the selected agent when known,
+     * else every agent of the slot seen this session.
+     */
+    private slotContextKeys;
+    /**
+     * Apply an asset-only invalidation. Before any agent of the slot resolves,
+     * queue it so the first resolved agents still see it (as the slot-keyed
+     * state did before contexts were keyed by agentId).
+     */
+    private invalidateSlot;
+    /** Record the selected agent for a slot; queued invalidations are now settled. */
+    private selectContext;
+    private assertSession;
+    private cachedRead;
+    private agentListKey;
+    private listAgents;
+    /**
+     * The routing API's stored accounts for owner+chain, read once per session.
+     * Resolves null when unavailable (callers keep name matching) and never
+     * rejects. A failure is retried after a short window.
+     */
+    private agentAccounts;
+    /** Yieldseeker accounts for one slot (returned addresses are compared lowercase). */
+    private slotAccounts;
+    private agentFits;
+    /**
+     * The listed agent of the slot whose resolved wallet is in the
+     * highest-priority set of `priorities` (index 0 first). Hinted agentIds are
+     * resolved first and a hinted top-priority match ends the search; then other
+     * listed agents, at most YIELDSEEKER_WALLET_MATCH_LIMIT wallets in total.
+     */
+    private agentWithWallet;
+    /**
+     * chooseAgent, re-reading a cached list once (bypassing its cache) when the
+     * verified agent is missing. A slot still missing after that re-read is
+     * remembered for the list cache window, so later reads fail from the cached
+     * list without another re-read.
+     */
+    private chooseAgentRefreshing;
+    private isSlotMissing;
+    /**
+     * The agent that serves deposits and withdrawals for a slot (Ruling 23):
+     * 1. the listed fitting agent whose wallet is the verified account's wallet,
+     *    whatever its name; the stored agentId is only a hint;
+     * 2. else a listed fitting agent whose wallet is a superseded account's wallet;
+     * 3. else the fitting agent named "owney" (first use, migration, or a
+     *    verified wallet that is not a fitting listed agent);
+     * 4. else, with a verified account, throw YIELDSEEKER_AGENT_MISSING (never
+     *    create); without one, undefined (the caller may create).
+     * Steps 1 and 2 share one search of at most YIELDSEEKER_WALLET_MATCH_LIMIT
+     * wallet reads. The account report then records the selected wallet; the
+     * server marks it superseded when it differs from the verified wallet.
+     */
+    private chooseAgent;
+    private isAgentMissing;
+    private agentMissing;
+    /**
+     * Fire-and-forget: record which agent serves this slot. Never awaited on the
+     * funds path and never throws; once per agent wallet and deployment state
+     * per session.
+     */
+    private reportAccount;
+    private contextForAgent;
+    private resolveUser;
+    private forgetUser;
+    private ensureAgent;
+    private findAgent;
+    private resolveAgent;
+    /** Create the slot's agent. Only reached when no stored or named agent matched. */
+    private createAgent;
+    /**
+     * The routing create lock refused the create: another tab or app owns or is
+     * creating this slot's agent. Re-read the accounts and the list (bypassing
+     * their caches) and select that agent, once more after 2 s if needed. A
+     * verified account is matched by wallet; otherwise the returned agentId is
+     * used. Never creates again.
+     */
+    private adoptConflictingAgent;
+    private loadPortfolio;
+    private loadActivityPortfolio;
+    private resolvePortfolioContexts;
+    private portfolioVersion;
+    /** Snapshot cache lifetime: the settlement backoff while a movement is being
+     * checked, otherwise the routine non-forced cadence. */
+    private portfolioCacheMs;
+    /** A pending movement inside its ten-minute window. */
+    private settlementWindow;
+    /** A pending movement inside its ten-minute window forces snapshots, unless
+     * every movement being settled is refreshed when ready through the ledger. */
+    private settling;
+    /** Start a new forced-check schedule, or keep the active one. */
+    private beginSettlement;
+    private snapshotMovement;
+    private advancePortfolioVersion;
+    private requestPortfolioSnapshot;
+    private portfolioSnapshot;
+    private loadPortfolioContext;
+    private loadActivityContext;
+    private loadPortfolioParts;
+    private deployAgent;
+    setFundingLedgerAccess(access: AgentFundingLedgerAccess | undefined): void;
+    private historyKey;
+    /** Funding-ledger rows for this slot, cached 15 s. Never throws: null on any failure. */
+    private readLedger;
+    /**
+     * A ledger read within the read budget. On a timeout or failure, the last
+     * successful rows are reused if at most 60 s old (no hold flicker); older
+     * means null, i.e. today's behaviour.
+     */
+    private readLedgerBudgeted;
+    private ledgerMovementsFor;
+    /** Track a movement this instance is settling. With ledger access and a tx
+     * hash it awaits the ledger; otherwise it keeps the timed backoff. */
+    private trackLocalMovement;
+    /** Timed (legacy) entries end with their ten-minute window; ledger ones after the one-hour index window. */
+    private pruneLocalMovements;
+    private hasAwaitingMovement;
+    /** Every movement being settled here is (or may yet be) refreshed when ready through the ledger. */
+    private deferredToLedger;
+    /** A null ledger sends every local movement back to the timed backoff; a
+     * listed tx hash is refreshed when ready; an unlisted one after the grace too. */
+    private resolveLocalMovements;
+    /**
+     * Refresh when ready, before a portfolio read: read the ledger (cached) when
+     * an earnings read asks for it or a movement is being tracked, update each
+     * recent movement's plan, poll the provider's history (non-forced, 15 s
+     * cache) for un-indexed tx hashes, and mark the next snapshot as forced when
+     * a plan is due. Never throws.
+     */
+    private prepareLedgerRefresh;
+    /** Apply one ledger read to local movements and refresh plans. False when the ledger is unavailable. */
+    private applyLedgerRows;
+    private updateRefreshPlans;
+    /** Non-forced provider history read (15 s cache) to learn when a tx hash is indexed. */
+    private pollIndexing;
+    /** The forced snapshot about to be requested counts for every plan that is
+     * due. False (do not force) when none is. */
+    private noteReadyForce;
+    private recordSnapshotHistory;
+    private localHistory;
+    /** After a snapshot: if this SDK's own history shows every recent ledger
+     * movement in net deposits, no plan needs (more) forcing. */
+    private checkLocalBooking;
+    /** The newest server sample observed at or before `cutoff`, cached. Null when none or on failure. */
+    private serverBaseline;
+    /**
+     * Earnings hold (spec B2): while a recent ledger movement is not booked by
+     * the provider, report the last good `cumulativeYieldBase`. The balance is
+     * untouched. Any missing input (no ledger, no baseline) or failure returns
+     * the provider's value. Never throws.
+     */
+    private applyEarningsHold;
+    private refreshSnapshotAfterMovement;
+    private agentPath;
+    private walletRequest;
+    private providerRequest;
+    private mapApiError;
+    private submitTransaction;
+    private waitForReceipt;
+    private assertTransaction;
+    private assertAgent;
+    private isOwneyAgent;
+    private assetForAgent;
+    private isTransactionHash;
+    private assertChain;
+    private assertOptionalChain;
+    private assertAsset;
+    private invalidResponse;
+}
+
 declare class InvalidHistoryCursorError extends Error {
     readonly code: "invalid_cursor";
     constructor(message: string);
@@ -1882,6 +2598,7 @@ declare function createOwneySIWX(config: OwneySIWXConfig): SIWXConfig;
  */
 type StoredOrder = {
     orderHash: string;
+    walletAddress?: string;
     /** Preimages, one per fill. Index matters — fill N needs secret N. */
     secrets: string[];
     /** Chain the funds left from, so a resumed session can report it. */
@@ -1891,13 +2608,56 @@ type StoredOrder = {
     dstSymbol: string;
     dstChainId: number;
     amount: string;
-    /** Epoch ms. Used to drop orders far past any plausible timelock. */
+    /** Epoch ms, for ordering recovery records. */
     createdAt: number;
 };
 /**
- * Every stored order, newest first, dropping anything past MAX_AGE_MS.
+ * Every unresolved stored order, newest first.
  * Used on mount to resume orders the user left in flight.
  */
-declare function listOrders(now?: number): StoredOrder[];
+declare function listOrders(_now?: number): StoredOrder[];
+
+/**
+ * Non-blocking funding ledger reporter.
+ *
+ * Reports each funding operation (deposit / withdraw / swap) to the routing
+ * API's `/api/v1/funding/operations` endpoints so support can reconstruct what
+ * happened. Hard rule: reporting NEVER blocks or fails a funding action.
+ *
+ *   - `start()` / `leg()` / `finish()` are synchronous and never throw.
+ *   - Requests run on a per-operation promise chain, create first.
+ *   - Every error is swallowed (visible only with debug logging on).
+ */
+/** Set by tsup's `define`; "dev" when running from source. */
+declare const SDK_VERSION: string;
+type LedgerLegReport = {
+    legKey: string;
+    legKind: "agent" | "swap" | "approval";
+    agentType?: string;
+    agentWallet?: string;
+    rail?: string;
+    amountRaw?: string;
+    status?: "created" | "submitted" | "unknown" | "failed" | "confirmed";
+    txHash?: string;
+    userOpHash?: string;
+    callsId?: string;
+    orderHash?: string;
+    confirmedAmountRaw?: string;
+    blockNumber?: string;
+    errorCode?: string;
+    swap?: {
+        rail: "swap_classic" | "swap_fusion" | "swap_fusion_plus";
+        srcChainId: number;
+        dstChainId: number;
+        srcToken: string;
+        dstToken: string;
+        srcAmountRaw: string;
+        quotedDstAmountRaw?: string;
+        receivedDstAmountRaw?: string;
+        feeBps?: number;
+        feeBpsSource?: "measured" | "stated";
+        feeToken?: string;
+    };
+};
 
-export { type AccountAgentApy, type AccountApyOptions, type AccountDailyEarnings, type AgentApy, type AgentApyDetails, type AgentBalance, AgentChainIncompatibleError, type AgentEarnings, type AgentHistoryEntry, type AgentHistoryPosition, type AgentId, AgentNotFoundError, type AgentSupportedAsset, type AgentSupportedAssets, type AgentUserProfile, type AgentWithdrawResult, type AgentsApyOptions, type AllocationAgentApy, type AllocationApyOptions, type ApyByChainAndAsset, type ApyCoverage, type ApyHistoryPoint, type Asset, type AssetDailyEarnings, type AvailableAgent, type AvailableAgentsOptions, type AvailablePool, type ConnectionState, type DailyApyDays, type DailyEarningsOptions, type DailyEarningsPoint, type DepositCallback, type DepositOptions, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, type LookbackDays, NotConnectedError, type OrgPoolPolicy, type OrgPoolSelection, type OwneyAccountApy, type OwneyAgentApy, type OwneyAgentHistory, type OwneyAllocationApy, type OwneyBalances, type OwneyDepositResult, type OwneyEarnings, OwneyError, type OwneyErrorCode, type OwneyMultiDepositResult, type OwneyPosition, OwneySDK, type OwneySDKConfig, type OwneySIWXConfig, type OwneySupportedChainId, type OwneySupportedChains, type OwneySupportedTokens, type OwneyToken, type OwneyUserProfile, type OwneyWithdrawAllLeg, type OwneyWithdrawAllResult, type OwneyWithdrawResult, type PendingDeposit, type PoolCatalogProtocol, type PoolSelectionStrategy, type RebalanceLog, type SwapChainTokens, type SwapDirection, type SwapOrderStatus, type SwapQuote, type SwapQuoteParams, type SwapRail, type SwapStage, type SwapTokenInfo, type SwapTokenSearchResult, type UserPoolSelection, type UserPoolSelectionRequest, type WithdrawOptions, type WithdrawSwapRecord, type WithdrawSwapStatus, clearWithdrawSwap, createOwneySIWX, listPendingDeposits, listOrders as listPendingSwaps, listWithdrawSwaps, saveWithdrawSwap, setOwneyDebug, subscribeWithdrawSwaps, updateWithdrawSwap };
+export { type AccountAgentApy, type AccountApyOptions, type AccountDailyEarnings, type AgentApy, type AgentApyDetails, type AgentBalance, AgentChainIncompatibleError, type AgentEarnings, type AgentFundingLedgerAccess, type AgentHistoryEntry, type AgentHistoryPosition, type AgentId, AgentNotFoundError, type AgentSupportedAsset, type AgentSupportedAssets, type AgentUserProfile, type AgentWithdrawResult, type AgentsApyOptions, type AllocationAgentApy, type AllocationApyOptions, type ApyByChainAndAsset, type ApyHistoryPoint, type Asset, type AssetDailyEarnings, type AssetReadMetadata, type AvailableAgent, type AvailableAgentsOptions, type ConnectionState, type DailyApyDays, type DailyEarningsOptions, type DailyEarningsPoint, type DepositAuthorizationReference, type DepositCallback, type DepositOptions, type DepositReplacementValidation, type FundingEvidence, type FundingOperationKind, type FundingOperationLeg, type FundingOperationRow, type FundingProgress, type FundingStage, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, type LedgerLegReport, type LookbackDays, NotConnectedError, type OwneyAccountApy, type OwneyAgentApy, type OwneyAgentHistory, type OwneyAllocationApy, type OwneyBalances, type OwneyDepositResult, type OwneyEarnings, OwneyError, type OwneyErrorCode, type OwneyMultiDepositResult, type OwneyPosition, OwneySDK, type OwneySDKConfig, type OwneySIWXConfig, type OwneySupportedChainId, type OwneySupportedChains, type OwneySupportedTokens, type OwneyToken, type OwneyUserProfile, type OwneyWithdrawResult, type PendingDeposit, type ProviderSnapshotSample, type RebalanceLog, type ReservationAgent, type ReservationReleaseReason, type RpcUrlsConfig, SDK_VERSION, type SwapChainTokens, type SwapDirection, type SwapOrderStatus, type SwapQuote, type SwapQuoteParams, type SwapRail, type SwapStage, type SwapTokenInfo, type SwapTokenSearchResult, type UnsignedUserOperationEvidence, type WithdrawOptions, type WithdrawSwapRecord, type WithdrawSwapStatus, type WithdrawalCompletion, type WithdrawalCompletionContext, type WithdrawalPayoutCandidate, type WithdrawalPayoutScan, type WithdrawalReservationConflict, type WithdrawalReservationMode, type WithdrawalReservationOptions, type WithdrawalSwapRecovery, YieldseekerAgent, type YieldseekerWalletStatus, type ZyfaiRpcUrlsConfig, clearWithdrawSwap, createOwneySIWX, listPendingDeposits, listOrders as listPendingSwaps, listWithdrawSwaps, saveWithdrawSwap, setOwneyDebug, subscribeWithdrawSwaps, updateWithdrawSwap };