@owney/sdk 0.7.27-beta.1 → 0.7.27-beta.2

package/dist/index.d.cts

@@ -224,7 +224,7 @@ type SwapOrderStatus = "pending" | "executed" | "expired" | "cancelled" | "refun
  */
 type SwapStage = "withdrawing" | "withdrawn"
 /** Withdrawal incomplete or unconfirmed; no swap was submitted. */
- | "withdrawal-incomplete" | "quoting" | "wrapping" | "wrapped" | "approving" | "building" | "signing" | "swapping" | "swapped" | "depositing" | "refunding" | "refunded";
+ | "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.
  *
@@ -386,7 +386,9 @@ interface IAgent {
      */
     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): Promise<AgentWithdrawResult>;
+    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. */
@@ -500,6 +502,9 @@ type HistoryOptions = {
     filters?: HistoryFilters;
 };
 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. */
@@ -575,6 +580,18 @@ type DepositOptions = {
 };
 
 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;
+};
+type WithdrawalCompletion = {
+    status: "complete" | "remaining" | "unavailable";
+    reason?: string;
+    checkedVaults?: number;
+};
 /** Hash-bound v0.6 recovery metadata. Deliberately excludes the owner signature. */
 type UnsignedUserOperationEvidence = {
     sender: string;
@@ -595,6 +612,8 @@ interface FundingEvidence {
     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. */
@@ -980,41 +999,30 @@ 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;
+    recovery?: WithdrawalSwapRecovery;
+    spent?: string;
+    dismissed?: boolean;
     status: WithdrawSwapStatus;
     /**
      * What actually left the agent, smallest unit of the SOURCE asset.
@@ -1051,7 +1059,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.
  *
@@ -1065,8 +1073,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.
@@ -1251,10 +1259,10 @@ declare class OwneySDK {
      * Invokes `agent.deposit` with the resolved sponsored callback, composing
      * two independent auto-recovery mechanisms:
      *
-     * 1. Missing Permit2 allowance outside the atomic Base-USDC path: when the
+     * 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. Base USDC bundles a gasless ERC-2612 approval inside
+     *    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
@@ -1378,29 +1386,11 @@ declare class OwneySDK {
     /** 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;
@@ -1473,11 +1463,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";
@@ -1609,6 +1600,20 @@ declare class OwneySDK {
          */
         deposited: 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;
+        };
+    }>;
     /**
      * Withdraw from an agent and swap the proceeds into whatever the user wants
      * to hold, delivered to their own wallet.
@@ -1643,6 +1648,7 @@ declare class OwneySDK {
         to: {
             chainId: number;
             symbol: string;
+            decimals?: number;
         };
         /** Human units ("10.5"). Omit to withdraw the full agent balance. */
         amount?: string;
@@ -1677,15 +1683,22 @@ 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;
     }): 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;
         };
@@ -1889,6 +1902,7 @@ declare class YieldseekerAgent implements IAgent {
     private readonly pendingReads;
     private readGeneration;
     private readonly portfolioVersions;
+    private readonly liquidityVersions;
     private readonly snapshotFailures;
     private readonly standardReadFailures;
     private readonly reconcileUntil;
@@ -1896,8 +1910,8 @@ declare class YieldseekerAgent implements IAgent {
     private readonly activityRefreshUntil;
     private readonly snapshotMovements;
     private readonly movementEpochs;
-    private readonly yieldOptions;
-    private readonly pendingYieldOptions;
+    private readonly vaultOptions;
+    private readonly pendingVaultOptions;
     constructor(owneyApiKey: string, options?: YieldseekerAgentOptions);
     private getReceiptClient;
     /** Reads the actual proxy implementation; Yieldseeker's API walletType is not a version check. */
@@ -1911,10 +1925,12 @@ declare class YieldseekerAgent implements IAgent {
     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): Promise<AgentWithdrawResult>;
+    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>;
+    /** Recheck MAX without re-unwinding, paying out, or requesting a signature. */
+    verifyWithdrawalCompletion(state: ConnectionState, evidence: FundingEvidence): Promise<WithdrawalCompletion>;
     private readVaultShares;
     private validateWithdrawalPositions;
     private withdrawalVaultHints;
@@ -1933,7 +1949,7 @@ declare class YieldseekerAgent implements IAgent {
     getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
     getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
     getAgentApy(days: DailyApyDays, options?: AgentApyOptions): Promise<AgentApy>;
-    private loadYieldOptions;
+    private loadVaultOptions;
     private userKey;
     private contextKey;
     private assertSession;
@@ -2036,6 +2052,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. */
@@ -2045,13 +2062,13 @@ 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[];
 
-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 ApyHistoryPoint, type Asset, type AssetDailyEarnings, type AssetReadMetadata, type AvailableAgent, type AvailableAgentsOptions, type ConnectionState, type DailyApyDays, type DailyEarningsOptions, type DailyEarningsPoint, type DepositCallback, type DepositOptions, type FundingEvidence, type FundingProgress, type FundingStage, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, 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 RebalanceLog, type RpcUrlsConfig, 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, YieldseekerAgent, type YieldseekerWalletStatus, type ZyfaiRpcUrlsConfig, 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 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 DepositCallback, type DepositOptions, type FundingEvidence, type FundingProgress, type FundingStage, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, 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 RebalanceLog, type RpcUrlsConfig, 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 WithdrawalSwapRecovery, YieldseekerAgent, type YieldseekerWalletStatus, type ZyfaiRpcUrlsConfig, clearWithdrawSwap, createOwneySIWX, listPendingDeposits, listOrders as listPendingSwaps, listWithdrawSwaps, saveWithdrawSwap, setOwneyDebug, subscribeWithdrawSwaps, updateWithdrawSwap };