@owney/sdk 0.7.32-beta.4 → 0.7.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,5 +1,3 @@
1
- import * as viem from 'viem';
2
- import { Hex, Address } from 'viem';
3
1
  import { SIWXConfig } from '@reown/appkit-controllers';
4
2
 
5
3
  /**
@@ -222,9 +220,7 @@ type SwapOrderStatus = "pending" | "executed" | "expired" | "cancelled" | "refun
222
220
  * of the flow and the one place a user would otherwise think nothing is
223
221
  * happening.
224
222
  */
225
- type SwapStage = "withdrawing" | "withdrawn"
226
- /** Withdrawal incomplete or unconfirmed; no swap was submitted. */
227
- | "withdrawal-incomplete" | "swap-unknown" | "swap-partial" | "swap-not-started" | "quoting" | "wrapping" | "wrapped" | "approving" | "building" | "signing" | "swapping" | "swapped" | "depositing" | "refunding" | "refunded";
223
+ type SwapStage = "withdrawing" | "withdrawn" | "quoting" | "wrapping" | "wrapped" | "approving" | "building" | "signing" | "swapping" | "swapped" | "depositing" | "refunding" | "refunded";
228
224
  /**
229
225
  * Which way the funds travel, which decides what each side may be.
230
226
  *
@@ -250,95 +246,19 @@ type SwapQuoteParams = {
250
246
  direction?: SwapDirection;
251
247
  };
252
248
 
253
- type FundingOperationKind = "deposit" | "withdraw" | "swap_deposit" | "withdraw_swap";
254
- /** One leg of a ledger operation, as the API returns it. */
255
- type FundingOperationLeg = {
256
- /** e.g. `agent:zyfai`, `swap`, `approval`. */
257
- legKey: string;
258
- agentType: string | null;
259
- /** created | submitted | unknown | failed | confirmed */
260
- status: string;
261
- /** uint256 decimal string. */
262
- confirmedAmountRaw: string | null;
263
- /** bigint decimal string. */
264
- blockNumber: string | null;
265
- txHash: string | null;
266
- /** ISO. Kept as stored: a confirmed -> failed leg keeps its value, so key off `status`. */
267
- confirmedAt: string | null;
268
- /** Lowercase agent wallet the leg moved funds to or from; null when unknown. */
269
- agentWallet: string | null;
270
- /** ISO. First time the provider's proxied history listed this leg's tx hash (Yieldseeker). Never cleared. */
271
- providerIndexedAt: string | null;
272
- /**
273
- * ISO. When a proxied provider snapshot first showed this leg in net deposits
274
- * (Yieldseeker). Never cleared. Null means "not booked or undecidable", never
275
- * "definitely not booked".
276
- */
277
- providerBookedAt: string | null;
278
- /** The provider's own id for this leg (e.g. a withdrawal or deposit id), as stored; null when none. */
279
- providerRef: string | null;
280
- /**
281
- * The server stopped checking this in-flight leg (no outcome was proven).
282
- * Present only when true; a new fact reported for the leg reopens it.
283
- */
284
- closed?: true;
285
- };
286
- /** One ledger operation, as the API returns it. */
287
- type FundingOperationRow = {
288
- /** First 8 hex chars of the client operation id, lowercase. */
289
- reference: string;
290
- /** Present only for operations whose id the caller passed in `ids`. */
291
- clientOperationId?: string;
292
- kind: FundingOperationKind;
293
- /** created | submitted | unknown | failed | confirmed | partial */
294
- status: string;
295
- /** ISO. */
296
- createdAt: string;
297
- /** ISO. */
298
- settledAt: string | null;
299
- stuck: boolean;
300
- legs: FundingOperationLeg[];
301
- };
302
- /** The newest server-side provider snapshot sample at or before a time. */
303
- type ProviderSnapshotSample = {
304
- /** Signed decimal strings in the asset's base units, or null. */
305
- netDepositsRaw: string | null;
306
- cumulativeYieldRaw: string | null;
307
- totalValueRaw: string | null;
308
- /** ISO or null. */
309
- providerUpdatedAt: string | null;
310
- /** ISO. */
311
- observedAt: string;
312
- };
313
-
314
- type RpcUrlsConfig = Partial<Record<(typeof SUPPORTED_CHAIN_IDS)[number], string>>;
315
- /** @deprecated Use RpcUrlsConfig. */
316
- type ZyfaiRpcUrlsConfig = RpcUrlsConfig;
249
+ type ZyfaiRpcUrlsConfig = Partial<Record<(typeof SUPPORTED_CHAIN_IDS)[number], string>>;
317
250
  interface OwneySDKConfig {
318
251
  apiKey: string;
319
- /**
320
- * Optional per-chain RPC overrides used for application-owned reads and
321
- * transaction receipt polling. Missing chains use the Owney routing API's
322
- * read-only RPC proxy. No upstream RPC credentials are included in the SDK.
323
- * Wallet providers remain responsible for account access, chain switching,
324
- * signatures, and transaction submission.
325
- */
326
- rpcUrls?: RpcUrlsConfig;
327
252
  /**
328
253
  * Optional per-chain RPC overrides for Zyfai SDK network calls.
329
254
  * Example: { 8453: "https://...", 42161: "https://..." }
330
- * @deprecated Use rpcUrls so every agent shares the same read transport.
331
255
  */
332
256
  zyfaiRpcUrls?: ZyfaiRpcUrlsConfig;
333
- /** Optional Owney Yieldseeker proxy base URL override for integration tests. */
334
- yieldseekerApiBaseUrl?: string;
335
- /** Optional SIWE origin override. Defaults to the requesting browser origin. */
336
- yieldseekerSiweOrigin?: string;
337
257
  /**
338
258
  * Optional override for the Owney routing API base URL used by all routing
339
- * calls. RPC proxy requests use OWNEY_ROUTING_API_BASE_URL when this is
340
- * omitted; without either value, all rpcUrls must be configured.
341
- * Set this to a local/staging routing API when testing sponsor changes.
259
+ * calls (defaults to the OWNEY_ROUTING_API_BASE_URL env var, then the
260
+ * production URL). Set this to point at a local/staging routing API,
261
+ * e.g. "http://localhost:3000", when testing sponsor changes.
342
262
  */
343
263
  routingApiBaseUrl?: string;
344
264
  /**
@@ -347,13 +267,6 @@ interface OwneySDKConfig {
347
267
  * for apps that don't use the AppKit SIWX modal.
348
268
  */
349
269
  referralSource?: string;
350
- /**
351
- * Mini-app identifier (`web`, `base`, `ellipal` …) recorded on funding ledger
352
- * operations. Not `referralSource`, which is a Zyfai attribution tag. The
353
- * ledger records `unknown` when this is omitted. Lowercased before sending;
354
- * a value that is not 1-32 of `a-z 0-9 _ -` after that is left out.
355
- */
356
- appName?: string;
357
270
  /**
358
271
  * Turn on the SDK's debug logging (default false). Traces the decisions that
359
272
  * are otherwise invisible — notably how the organization's agent policy is
@@ -363,6 +276,15 @@ interface OwneySDKConfig {
363
276
  * already-deployed app: set `globalThis.__OWNEY_DEBUG__ = true` in devtools.
364
277
  */
365
278
  debug?: boolean;
279
+ /**
280
+ * When true, the organization's pool policy is NOT applied on connect, so a
281
+ * user's own deposit-time pool selection (ROUT-569) is never overwritten by
282
+ * the org-level one on their next reconnect. Splitting and the rest of the
283
+ * org policy still apply. Turn this on in apps that expose the deposit-time
284
+ * Pools step (the spread flow); leave it off where the partner dashboard's
285
+ * pool customization is the source of truth.
286
+ */
287
+ userPoolCustomization?: boolean;
366
288
  /**
367
289
  * Absolute URL of an ERC-7677 paymaster service. When set, deposits go out as
368
290
  * an EIP-5792 `wallet_sendCalls` with `capabilities.paymasterService`, so a
@@ -374,45 +296,6 @@ interface OwneySDKConfig {
374
296
  * unresolvable. Omit it and every rail behaves exactly as before.
375
297
  */
376
298
  paymasterServiceUrl?: string;
377
- /**
378
- * Cross-device withdrawal reservation (default `"fail-open"`). `withdraw()`
379
- * claims a hold on the owner's funds before any provider call; a hold held by
380
- * another device or app rejects with `WITHDRAW_IN_PROGRESS` /
381
- * `details.reason === "RESERVED_ELSEWHERE"`.
382
- * - `"fail-open"`: when the reservation API cannot answer (network error,
383
- * timeout, 5xx, 404, 429, ...) the withdrawal proceeds as before.
384
- * - `"fail-closed"`: it rejects with `WITHDRAW_RESERVATION_UNAVAILABLE`
385
- * before anything is submitted.
386
- * - `"off"`: never calls the reservation API.
387
- * `OWNEY_WITHDRAWAL_RESERVATION_DISABLED=1` in the environment acts as `"off"`.
388
- */
389
- withdrawalReservation?: "fail-open" | "fail-closed" | "off";
390
- /**
391
- * Hand Zyfai withdrawals and deposit registrations, with the user's Zyfai
392
- * session, to the Owney routing API, which then sends them itself (default
393
- * off). Only `true`, or a function that returns `true`, opts in.
394
- *
395
- * A function is called for each operation, at the moment it would first
396
- * hand a withdrawal or a registration off, so an app can turn the handoff on
397
- * or off in open tabs without a reload. A function that throws counts as
398
- * off.
399
- *
400
- * Off, the SDK hands no new operation off, never sends the Zyfai session to
401
- * Owney for it, and behaves as before. Turning it off never makes the
402
- * browser send what the server may already hold: an operation this SDK
403
- * instance already handed off keeps going through the server (its nudges,
404
- * re-runs, retries and registration recovery). Recovery of a deposit handed
405
- * off by an earlier page waits until it is on again.
406
- */
407
- zyfaiServerTasks?: boolean | (() => boolean);
408
- /**
409
- * Hand each signed cross-chain (Fusion+) order's secrets to the Owney
410
- * routing API, which publishes them once 1inch is ready, so the swap
411
- * completes even if the tab closes (default false). Only `true` opts in.
412
- * Off, the secrets never leave the browser and swaps behave as before. On,
413
- * the browser still publishes them too.
414
- */
415
- fusionSecretHandoff?: boolean;
416
299
  }
417
300
  interface ConnectionState {
418
301
  provider: any;
@@ -426,246 +309,7 @@ type OwneySupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number];
426
309
  type OwneySupportedChains = (typeof SUPPORTED_CHAINS)[number];
427
310
  type OwneySupportedTokens = (typeof SUPPORTED_TOKENS)[number];
428
311
 
429
- /**
430
- * One protocol's pool selection on one chain. `pools` holds Zyfai pool NAMES
431
- * verbatim — matched case-sensitively by customizeBatch, and an unrecognised
432
- * name makes Zyfai's rebalance engine skip the whole protocol, so these strings
433
- * must not be normalised anywhere.
434
- *
435
- * An empty array means "no usable pools on this chain".
436
- */
437
- type OrgPoolSelection = {
438
- protocolId: string;
439
- chainId: number;
440
- pools: string[];
441
- };
442
- /**
443
- * The partner's protocol/pool policy (ROUT-224). Sparse — only protocols they
444
- * narrowed appear. Optional so an older routing API, which does not return the
445
- * field, still parses; undefined and null both mean "change nothing".
446
- */
447
- type OrgPoolPolicy = {
448
- autoApproveProtocols: boolean;
449
- autoApprovePools: boolean;
450
- selections: OrgPoolSelection[];
451
- };
452
- /**
453
- * The organization's agent execution policy, or null when the partner has never
454
- * configured one — in which case the agents leave the user's profile alone.
455
- */
456
- type OrgAgentConfig = {
457
- splittingMode: "none" | "automatic" | "force";
458
- minSplits: number | null;
459
- poolPolicy?: OrgPoolPolicy | null;
460
- };
461
-
462
- /** Capability flag: this SDK can hand Zyfai withdrawals and deposit
463
- * registrations to the server, and marks such legs with evidence `serverTask`.
464
- * Older builds do not export this. */
465
- declare const ZYFAI_SERVER_TASKS: 1;
466
- /** A `zyfai_withdrawal` task that failed with one of these codes never sent
467
- * the withdrawal to Zyfai. */
468
- declare const ZYFAI_WITHDRAWAL_NOT_SENT_CODES: ReadonlySet<string>;
469
- /** A `zyfai_deposit_registration` task that failed with one of these codes
470
- * never registered the deposit with Zyfai, so the browser may register it. */
471
- declare const ZYFAI_REGISTRATION_NOT_SENT_CODES: ReadonlySet<string>;
472
- type ZyfaiTaskResult = {
473
- providerWithdrawalId?: string;
474
- providerDepositId?: string;
475
- txHash?: string;
476
- asyncPending?: true;
477
- handedOff?: "reconciler";
478
- lifecycle?: "failed";
479
- };
480
- /**
481
- * - accepted: the server has a task for this leg (its state and code);
482
- * - declined: the server proved no task was created (a 200 decline, or a 400,
483
- * 401, 403, 404, 409 or 429; or `ZYFAI_SERVER_TASKS_OFF_CODE` without the
484
- * opt-in);
485
- * - unknown: anything else. The server may have a task.
486
- */
487
- type ZyfaiHandoffAnswer = {
488
- type: "accepted";
489
- taskId: string;
490
- state: string;
491
- code?: string;
492
- result: ZyfaiTaskResult;
493
- } | {
494
- type: "declined";
495
- code: string;
496
- } | {
497
- type: "unknown";
498
- };
499
-
500
- type DepositCallback = (smartWalletAddress: string, chainId: number, amount: string) => Promise<`0x${string}`> | `0x${string}`;
501
- /**
502
- * Read access to the funding ledger, given to agents by the client so they can
503
- * hold earnings while a provider lags (spec B2). Both reads never throw:
504
- * null means "no ledger information", and callers then behave as before.
505
- */
506
- type AgentFundingLedgerAccess = {
507
- /** `sdk.listFundingOperations` for this owner; null when the owner is not the connected one or on failure. */
508
- listOperations(input: {
509
- owner: string;
510
- chainId: number;
511
- asset: string;
512
- since?: Date;
513
- }): Promise<FundingOperationRow[] | null>;
514
- /** The newest server provider-snapshot sample at or before `before`; null when none or on failure. */
515
- providerSnapshot?(input: {
516
- owner: string;
517
- chainId: number;
518
- asset: string;
519
- agentWallet: string;
520
- before: Date;
521
- }): Promise<ProviderSnapshotSample | null>;
522
- };
523
- interface IAgent {
524
- readonly id: string;
525
- readonly supportedChainIds: readonly OwneySupportedChainId[];
526
- readonly supportedAssets: readonly AgentSupportedAssets[];
527
- /**
528
- * Describes how `AgentBalance.tokens` relates to `positions`.
529
- * Most adapters expose token totals that already include deployed positions.
530
- * Providers such as Yieldseeker expose idle wallet tokens separately, so
531
- * withdrawal planning must add matching position amounts.
532
- */
533
- readonly balanceComposition?: "tokens-include-positions" | "tokens-plus-positions";
534
- /**
535
- * Whether a withdrawal requires an owner-approved wallet transaction.
536
- * Aggregate withdrawals run these agents before relayer-only agents so a
537
- * rejected wallet request cannot happen after another leg has committed.
538
- */
539
- readonly withdrawalRequiresWalletApproval?: boolean;
540
- /**
541
- * Settles this agent's own wallet prompts (a login, a session key) so that a
542
- * following `withdraw` needs none. A multi-agent withdrawal calls it before a
543
- * wallet-approval agent's owner signature, so two prompts never overlap and
544
- * this agent can start as soon as that signature was accepted. Never submits
545
- * a withdrawal. A rejected prompt throws; other failures are left to `withdraw`.
546
- */
547
- prepareWithdrawal?(state: ConnectionState, chainId: number, token: OwneySupportedTokens): Promise<void>;
548
- /**
549
- * The adapter can hand its withdrawal to our server (part 4, Zyfai). Only
550
- * such agents get the plan-time handoff and a `planned` withdraw context;
551
- * every other agent keeps today's calls.
552
- */
553
- readonly supportsServerTasks?: true;
554
- /**
555
- * Hands a planned withdrawal leg to our server before an earlier
556
- * wallet-approval leg is signed (`after`: those legs' keys). The server sends
557
- * it once those legs are accepted. Never throws; never withdraws locally.
558
- * `amount` is the leg's planned share, or "MAX". `beforeRequest` runs right
559
- * before the request leaves (never when none is sent), so the caller can
560
- * save the leg's server mark first.
561
- */
562
- handOffPlannedWithdrawal?(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount: string, ctx: {
563
- operationId: string;
564
- after: string[];
565
- beforeRequest?: () => void;
566
- }): Promise<ZyfaiHandoffAnswer>;
567
- disconnect(): Promise<void>;
568
- activateAgent(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<void>;
569
- /**
570
- * Apply the organization's agent policy to this user's account.
571
- *
572
- * Optional: an agent that has no equivalent knob simply omits it, which is why
573
- * this is not part of `activateAgent`'s signature. Declared on the interface
574
- * rather than only on ZyfaiAgent so the contract stays agent-neutral — the
575
- * ticket asks for a design that can also cover Surf, which has no adapter yet.
576
- *
577
- * Implementations must be **non-fatal**: this runs during activation as a side
578
- * effect, so a failure has to leave the user connected and their profile
579
- * unchanged rather than break the connect.
580
- */
581
- applyOrgPolicy?(state: ConnectionState, chainId: number, policy: OrgAgentConfig): Promise<void>;
582
- deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback, onProgress?: FundingProgress, onBeforeSubmission?: (evidence: FundingEvidence) => void | Promise<void>,
583
- /** `operationId`: the funding ledger operation. Zyfai hands the deposit's
584
- * registration to the server with it (only agents with
585
- * `supportsServerTasks` get it; every other agent keeps today's call). */
586
- context?: {
587
- operationId?: string;
588
- }): Promise<OwneyDepositResult>;
589
- withdraw(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount?: string, onProgress?: FundingProgress, gasMode?: "auto" | "sponsored" | "paid", onBeforeSubmission?: FundingProgress, assertCurrent?: () => void,
590
- /** `operationId`: the funding ledger operation (Yieldseeker opts in to the
591
- * server-owned send of its sponsored userOp with it; Zyfai hands its
592
- * withdrawal to the server with it). `planned`: the leg was handed to the
593
- * server at plan time, so this call nudges that task (only for agents with
594
- * `supportsServerTasks`). */
595
- context?: {
596
- operationId?: string;
597
- planned?: true;
598
- }): Promise<AgentWithdrawResult>;
599
- /** Read-only MAX proof at the owner payout block; never sends another withdrawal. */
600
- verifyWithdrawalCompletion?(state: ConnectionState, evidence: FundingEvidence): Promise<WithdrawalCompletion>;
601
- /** A newly observed pool allocation invalidates this asset's portfolio cache only. */
602
- invalidateAllocationRead?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): void;
603
- /** Invalidate only the confirmed asset. This hook must not sign or submit transactions. */
604
- invalidateFundingRead?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number, txHash?: string): void;
605
- /** End accelerated balance reads only for the exact snapshot the caller displayed. */
606
- endFundingBalanceRefresh?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
607
- getFundingHistory?(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
608
- getFundingWallet?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;
609
- /** Verify the displayed remaining balance after a receipt-confirmed payout.
610
- * Undefined means unknown; never substitute a failed read with zero. */
611
- verifyWithdrawalBalance?(state: ConnectionState, evidence: FundingEvidence, balance: AgentBalance): Promise<AssetReadMetadata | undefined>;
612
- /** Read-only chain proof when indexed withdrawal components are incomplete.
613
- * Returns raw owner-withdrawable units; unavailable proof must throw.
614
- * minimumAmount is the raw liquidity required from this agent for a typed
615
- * plan, so adapters can expand discovery when known positions fall short. */
616
- getWithdrawableBalance?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, minimumAmount?: bigint): Promise<bigint>;
617
- /** Optional positive proof for a repeat deposit; unknown must fall back to portfolio validation. */
618
- hasExistingDepositFunds?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
619
- getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
620
- getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
621
- /** Funding-ledger read access for earnings holds. Optional; without it an agent behaves as before. */
622
- setFundingLedgerAccess?(access: AgentFundingLedgerAccess | undefined): void;
623
- /**
624
- * A small, never-prompting read of the provider's earnings bookkeeping for a
625
- * `provider.sample` ledger event (Zyfai). Null when unavailable; never throws.
626
- */
627
- providerEarningsSample?(state: ConnectionState, chainId: number): Promise<Record<string, unknown> | null>;
628
- /**
629
- * Refresh the agent's earnings snapshot when its backend supports doing so.
630
- * Implementations own freshness and request-deduplication policy.
631
- */
632
- refreshEarnings?(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
633
- getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays,
634
- /**
635
- * Optional asset symbol ("USDC" / "WETH") scoping the daily series to a
636
- * single asset on the chain. Agents without per-asset positions ignore it.
637
- */
638
- tokenSymbol?: string): Promise<AccountAgentApy>;
639
- /**
640
- * Daily cumulative earnings in token units, scoped to a chain/asset, using
641
- * the provider's earnings basis. Include an opening snapshot when available
642
- * so the "recent earnings" subline can difference the endpoints. (ROUT-452)
643
- */
644
- getDailyEarnings?(state: ConnectionState, chainId: number, days: LookbackDays, tokenSymbol?: string): Promise<AccountDailyEarnings>;
645
- getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
646
- getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
647
- /**
648
- * Ensure the given asset uses backend protocol auto-selection
649
- * (`autoSelectProtocols: true`). Optional capability — only agents whose
650
- * backend models per-asset protocol selection implement it. Returns whether
651
- * a write occurred (`false` = already enabled / not supported).
652
- */
653
- ensureAutoSelectProtocols?(state: ConnectionState, chainId: number, asset: "USDC" | "WETH"): Promise<boolean>;
654
- supportsAgentApyPeriod?(days: DailyApyDays): boolean;
655
- getAgentApy(days: DailyApyDays, options?: AgentApyOptions): Promise<AgentApy>;
656
- }
657
- /**
658
- * Optional filters for per-agent APY lookups.
659
- * - `tokenSymbol` / `chainId` scope the APY to a specific asset+chain when
660
- * the underlying provider supports it (Zyfai). Agents whose backends do
661
- * not yet support per-asset APY will ignore these options.
662
- */
663
- type AgentApyOptions = {
664
- tokenSymbol?: string;
665
- chainId?: number;
666
- };
667
-
668
- type AgentId = "zyfai" | "yieldseeker";
312
+ type AgentId = "zyfai";
669
313
  type Asset = string;
670
314
  type AgentSupportedAsset = {
671
315
  readonly symbol: string;
@@ -682,6 +326,15 @@ type AvailableAgent = {
682
326
  supportedChainIds: readonly number[];
683
327
  supportedAssets: readonly AgentSupportedAssets[];
684
328
  };
329
+ type ActivateAgentOptions = {
330
+ /**
331
+ * Called once the chain and agents are registered, before any agent signs in
332
+ * or runs its setup. From then on reads such as `getBalances` are safe to
333
+ * start: each agent's reads wait on that agent's own sign-in, so they share
334
+ * the activation's one wallet prompt instead of waiting for all of setup.
335
+ */
336
+ onAgentsSelected?: () => void;
337
+ };
685
338
  type AvailableAgentsOptions = {
686
339
  chainId?: number;
687
340
  asset?: Asset;
@@ -714,51 +367,43 @@ type HistoryFilters = {
714
367
  tokenSymbol?: string;
715
368
  };
716
369
  type HistoryOptions = {
717
- chainId?: number;
718
370
  agentId?: AgentId;
719
371
  filters?: HistoryFilters;
372
+ /**
373
+ * Chains to read, instead of the one `activateAgent` last set (ROUT-479).
374
+ *
375
+ * Each chain pages independently and the results merge into one
376
+ * chronological list, with every entry stamped with the chain it came from.
377
+ * Omit for the single-chain behaviour, which stays the default: fanning out
378
+ * by default would multiply every existing caller's request count.
379
+ */
380
+ chainIds?: OwneySupportedChainId[];
720
381
  };
721
382
  type WithdrawOptions = {
722
- /** Internal orchestration observation deadline; never retries a send. */
723
- observationDeadline?: number;
724
- assertCurrent?: () => void;
725
- /** Yieldseeker V2 only. "auto" requests sponsorship for a verified V2 wallet. */
726
- gasMode?: "auto" | "sponsored" | "paid";
727
- /** Exclude unresolved providers from aggregate withdrawals; direct agent requests are unchanged. */
728
- excludeAgentIds?: AgentId[];
729
- onProgress?: FundingProgress;
730
- /**
731
- * Durable pre-dispatch checkpoint for adapters with a recoverable operation ID.
732
- * Rejection prevents submission; progress observers remain non-fatal.
733
- */
734
- onBeforeSubmission?: FundingProgress;
735
383
  asset: Asset;
736
384
  amount?: string;
737
385
  agentId?: AgentId;
738
- /** Called after each agent returns; callback failures never change a financial result. */
739
- onAgentResult?: (agentId: AgentId, result: AgentWithdrawResult) => void;
740
- /** Funding ledger reference (a UUID). Defaults to a new random UUID; apps pass
741
- * their own so the app record and the ledger share one reference. It is also
742
- * the withdrawal reservation's operationId. */
743
- operationId?: string;
744
- /**
745
- * Cross-device withdrawal reservation options.
746
- * - `override`: the `reference` from an overridable `RESERVED_ELSEWHERE`
747
- * error, sent after the user chose "Withdraw anyway".
748
- * - `supersedesOperationId`: an earlier operation of this SDK (for example
749
- * the sponsored attempt a paid retry replaces). Its hold is released when
750
- * this SDK still has that operation's holder token; otherwise ignored.
751
- */
752
- reservation?: WithdrawalReservationOptions;
753
- };
754
- /** `WithdrawOptions.reservation`: see there. */
755
- type WithdrawalReservationOptions = {
756
- override?: string;
757
- supersedesOperationId?: string;
386
+ /**
387
+ * Chain to withdraw from. Defaults to the chain `activateAgent` last set.
388
+ * See `DepositOptions.chainId` — the same rules apply.
389
+ */
390
+ chainId?: number;
758
391
  };
759
392
  type AccountApyOptions = {
760
393
  agentId?: AgentId;
761
394
  days: LookbackDays;
395
+ /**
396
+ * Chain to scope the daily series to, instead of the one `activateAgent`
397
+ * last set (ROUT-479).
398
+ *
399
+ * `"all"` blends every chain the wallet held that day, which is what the
400
+ * chart's "All chains" filter asks for. Unlike the history and earnings
401
+ * reads this needs no fan-out: the provider's daily-APY payload is already
402
+ * wallet-wide and names each position's chain, so the scope is a filter over
403
+ * one response rather than several calls. Omit for the active chain, which
404
+ * stays the default.
405
+ */
406
+ chainId?: OwneySupportedChainId | "all";
762
407
  /**
763
408
  * Optional asset symbol (e.g. "USDC", "WETH") to scope the daily APY series
764
409
  * to a specific asset on the active chain. Without it the series blends every
@@ -776,6 +421,14 @@ type AccountApyOptions = {
776
421
  type DailyEarningsOptions = {
777
422
  agentId?: AgentId;
778
423
  days: LookbackDays;
424
+ /**
425
+ * Chains to read, instead of the one `activateAgent` last set (ROUT-479).
426
+ *
427
+ * The same asset is summed across them — USDC on Base and USDC on Arbitrum
428
+ * are the same unit. Different assets stay apart, as they already do within
429
+ * one chain. Omit for the single-chain behaviour, which stays the default.
430
+ */
431
+ chainIds?: OwneySupportedChainId[];
779
432
  /**
780
433
  * Optional asset symbol (e.g. "USDC", "WETH") scoping the series to one
781
434
  * asset on the active chain.
@@ -801,258 +454,170 @@ type AgentsApyOptions = {
801
454
  chainId?: number;
802
455
  };
803
456
  type DepositOptions = {
804
- /** Optional synchronous foreground ownership fence for the default Permit2 rail.
805
- * Throw to stop preparation/dispatch and late journal writes after lease/session loss. */
806
- assertSubmissionCurrent?: () => void;
807
- /** Resume only these already signed relayer bytes; never create a new authorization. */
808
- resumeTxHash?: `0x${string}`;
809
- /** Resume only the saved signed batch of a deposit the server may be sending
810
- * (its prepare got no answer, so no transaction hash is known); never create
811
- * a new authorization. Check it first with `canResumePendingDeposit`. */
812
- resumeSavedBatch?: true;
813
- onProgress?: FundingProgress;
814
- /** Awaited immediately before dispatch. Throwing prevents submission.
815
- * All legs of an atomic batch are checkpointed together. */
816
- onBeforeSubmission?: (evidence: FundingEvidence[]) => void | Promise<void>;
817
457
  amount: string;
818
458
  asset: Asset;
819
459
  depositCallback?: DepositCallback;
820
460
  agentId?: AgentId;
821
461
  onApproved?: () => void;
822
- /** Funding ledger reference (a UUID). Defaults to a new random UUID; apps pass
823
- * their own so the app record and the ledger share one reference. */
824
- operationId?: string;
462
+ /**
463
+ * Chain to deposit on. Defaults to the chain `activateAgent` last set, so
464
+ * omitting it behaves exactly as before.
465
+ *
466
+ * Pass it to fund several chains in a row without re-activating between
467
+ * them (ROUT-245's spread strategies). It selects the target; it does not
468
+ * replace activation, which is what populates `activeAgents`, and it does
469
+ * not remove the wallet's network switch — the default deposit callbacks
470
+ * still put the wallet on this chain before signing, since a deposit
471
+ * signature is EIP-712 with the chain in its domain.
472
+ */
473
+ chainId?: number;
825
474
  };
826
475
 
827
- type FundingStage = "pending" | "confirmed" | "unknown" | "failed" | "not-applicable";
828
- /** Vault inventory retained before the MAX payout. No signatures or secrets. */
829
- type WithdrawalCompletionContext = {
830
- vaults: string[];
831
- userId: string;
832
- agentId: string;
833
- inventoryComplete: boolean;
834
- };
835
- type WithdrawalCompletion = {
836
- status: "complete" | "remaining" | "unavailable";
837
- reason?: string;
838
- checkedVaults?: number;
476
+ /**
477
+ * One protocol's pool selection on one chain. `pools` holds Zyfai pool NAMES
478
+ * verbatim — matched case-sensitively by customizeBatch, and an unrecognised
479
+ * name makes Zyfai's rebalance engine skip the whole protocol, so these strings
480
+ * must not be normalised anywhere.
481
+ *
482
+ * An empty array means "no usable pools on this chain".
483
+ */
484
+ type OrgPoolSelection = {
485
+ protocolId: string;
486
+ chainId: number;
487
+ pools: string[];
839
488
  };
840
- /** Hash-bound v0.6 recovery metadata. Deliberately excludes the owner signature. */
841
- type UnsignedUserOperationEvidence = {
842
- sender: string;
843
- nonce: string;
844
- initCode: string;
845
- callData: string;
846
- callGasLimit: string;
847
- verificationGasLimit: string;
848
- preVerificationGas: string;
849
- maxFeePerGas: string;
850
- maxPriorityFeePerGas: string;
851
- paymasterAndData: string;
489
+ /**
490
+ * The partner's protocol/pool policy (ROUT-224). Sparse — only protocols they
491
+ * narrowed appear. Optional so an older routing API, which does not return the
492
+ * field, still parses; undefined and null both mean "change nothing".
493
+ */
494
+ type OrgPoolPolicy = {
495
+ autoApproveProtocols: boolean;
496
+ autoApprovePools: boolean;
497
+ selections: OrgPoolSelection[];
852
498
  };
853
- type DepositAuthorizationReference = {
854
- authorizationId: `0x${string}`;
855
- predecessorTxHash?: `0x${string}`;
499
+ /**
500
+ * The organization's agent execution policy, or null when the partner has never
501
+ * configured one — in which case the agents leave the user's profile alone.
502
+ */
503
+ type OrgAgentConfig = {
504
+ splittingMode: "none" | "automatic" | "force";
505
+ minSplits: number | null;
506
+ poolPolicy?: OrgPoolPolicy | null;
856
507
  };
857
- type DepositReplacementValidation = {
858
- authorizationId: `0x${string}`;
859
- predecessorTxHash: `0x${string}`;
860
- replacementTxHash: `0x${string}`;
508
+
509
+ /**
510
+ * Pool policy: Owney's org-level protocol/pool policy -> Zyfai's two mismatched
511
+ * write shapes.
512
+ *
513
+ * Zyfai splits "which protocols and pools may this user's funds sit in" across
514
+ * two calls that do not share an axis:
515
+ *
516
+ * updateUserProfile({ protocols }) per ASSET, chain-agnostic
517
+ * customizeBatch([{ protocolId, per (PROTOCOL, CHAIN), asset-agnostic
518
+ * chainId, pools, autoselect }])
519
+ *
520
+ * `protocols` is an explicit ALLOW-LIST: a protocol left out of it is disabled
521
+ * for that asset, on every chain, immediately. `customizeBatch` is the opposite
522
+ * shape — one record per (protocol, chain) pair, asset-agnostic, and per
523
+ * docs.zyf.ai it "creates or updates a record for the (user, protocol, chain)
524
+ * combination"; "previous customizations for the same combination are
525
+ * overwritten".
526
+ *
527
+ * That second property is the reason this file exists rather than a single
528
+ * flat translation: customizeBatch overwrites only the combinations it is
529
+ * GIVEN. The partner's stored policy (`OrgPoolPolicy.selections`) is sparse —
530
+ * only the protocols they actually narrowed appear — but the payload we send
531
+ * must be EXHAUSTIVE over every (protocol, chain) pair Zyfai offers this user.
532
+ * If we only sent the narrowed pairs, a partner who restricts Morpho, saves,
533
+ * then later re-ticks every pool box would never be able to undo it: nothing
534
+ * in the (sparse) policy would tell us to send a record clearing it, and the
535
+ * old restrictive record would stay live on the user's profile forever.
536
+ *
537
+ * Pure functions, kept out of the agent so the mapping is testable without a
538
+ * Zyfai client. See splitting.ts for the same pattern on the other lever.
539
+ */
540
+
541
+ /** One selectable pool, with the figures the deposit-time Pools step shows. */
542
+ type AvailablePool = {
543
+ chainId: number;
544
+ token: string;
545
+ name: string;
546
+ /** combined_apy (pool + rewards), already a percent. null when absent. */
547
+ apy: number | null;
548
+ /** TVL in USD. null when absent. See ZyfCustomizationPoolInfo: `tvl` is in
549
+ * the pool's own token, `tvlUsd` is the dollar figure — only the latter is
550
+ * safe to show with a currency symbol. */
551
+ tvlUsd: number | null;
552
+ /** Per-pool deep link (e.g. the Morpho vault page). null when absent. */
553
+ link: string | null;
861
554
  };
862
- /** Evidence about one provider leg. Amounts are token base units, never USD. */
863
- interface FundingEvidence {
864
- agentId: AgentId;
555
+ /** Public Zyfai strategies used by deposit-time pool customization. */
556
+ type PoolSelectionStrategy = "aggressive" | "yieldmaxxing";
557
+ /** One asset's explicit choice for a protocol on one chain. */
558
+ type UserPoolSelection = {
559
+ asset: "USDC" | "WETH";
560
+ protocolId: string;
865
561
  chainId: number;
866
- token: OwneySupportedTokens;
867
- walletAddress: string;
868
- agentWallet?: string;
869
- maxCompletion?: WithdrawalCompletionContext;
870
- maxCompletionCheck?: WithdrawalCompletion;
871
- intendedAmount: string;
872
- /** A multi-agent withdrawal recorded this leg's planned amount (`intendedAmount`:
873
- * the leg's share, or "MAX") before any agent was dispatched. A plan, not a
874
- * submission: it never says the leg was sent. */
875
- planned?: true;
876
- /** The owner-authorized call of a wallet-approval withdrawal was accepted: the
877
- * bundler accepted the signed userOp (`userOpHash`), the wallet returned a
878
- * calls ID (`callsId`), or `eth_sendTransaction` returned a hash (`txHash`).
879
- * Not confirmation: the call can still revert. */
880
- ownerAuthorization?: "accepted";
881
- confirmedAmount?: string;
882
- /** Receipt delivery and fulfillment of a typed requested amount are separate facts. */
883
- amountCompletion?: "complete" | "shortfall";
884
- /** Verified difference between the typed request and the actual owner payout. */
885
- shortfallAmount?: string;
886
- txHash?: string;
887
- /** Zyfai's id for this deposit, from its registration (1-128 chars); reads its placement status. */
888
- providerDepositId?: string;
889
- /** Persisted before a sponsored EOA operation is sent. */
890
- userOpHash?: string;
891
- /** Lets recovery verify a consumed nonce even if a bundler forgets the operation. */
892
- userOperation?: UnsignedUserOperationEvidence;
893
- /** Base Account calls ID used to recover an uncertain wallet submission. */
894
- callsId?: string;
895
- /** The server owns this sponsored Yieldseeker userOp's send (true), or may
896
- * own it ("unknown": the opted-in send got no definitive answer). Either way
897
- * the leg is never "not sent". Not acceptance, not confirmation. Never sent
898
- * to the ledger. */
899
- serverSubmit?: true | "unknown";
900
- /** Zyfai server tasks. On a withdrawal leg: the server sends this withdrawal
901
- * (true), or may send it ("unknown": the handoff got no definitive answer),
902
- * so the browser never sends it. `false`: the server proved it has no task
903
- * for this leg, so the browser sends it; it clears an earlier mark (a
904
- * handoff checkpoint), and a merge must let it win over true and "unknown".
905
- * On a deposit leg: the server registers this deposit. Not acceptance, not
906
- * confirmation. Never sent to the ledger. */
907
- serverTask?: true | "unknown" | false;
908
- /** With `serverTask` on a Zyfai deposit leg: the client operation id of the
909
- * server's registration task, so registration recovery can nudge that task
910
- * after a reload. Not a secret. Never sent to the ledger. */
911
- serverTaskOperationId?: string;
912
- /** With `serverTask: "unknown"` on a Zyfai deposit leg: what the server
913
- * answered to the registration handoff. "lost": no answer (the server may
914
- * or may not have a task), so a later proof of no task lets the browser
915
- * register it. "declined": the server declined it with a code that does not
916
- * prove no task (e.g. ALREADY_REGISTERED), so the browser never registers
917
- * it. Local only: never sent to the ledger. */
918
- serverTaskCreate?: "declined" | "lost";
919
- /** Deposit execution was attempted, rather than only prepared. Not confirmation. */
920
- depositSubmission?: "started";
921
- depositAuthorization?: DepositAuthorizationReference;
922
- /** The server accepted this sponsored deposit and sends it itself if the
923
- * browser does not (true), or may have accepted it ("unknown": the prepare
924
- * got no definitive answer, no hash is known yet). Either way it is never
925
- * "not sent". Not confirmation. */
926
- serverBroadcast?: true | "unknown";
927
- /** With `serverBroadcast: "unknown"`: the deposit authorization's Permit2
928
- * deadline (unix seconds). After it no deposit of that authorization can
929
- * execute. */
930
- authorizationDeadline?: number;
931
- /** With `serverBroadcast`: the deposit authorization's Permit2 nonce
932
- * (decimal); see `checkDepositAuthorization`. */
933
- permit2Nonce?: string;
934
- blockNumber?: string;
935
- logIndexes?: number[];
936
- transferLogs?: {
937
- logIndex: number;
938
- amountRaw: string;
939
- }[];
940
- /** Sanitized execution-request evidence. Attempted does not prove server acceptance. */
941
- withdrawalRequest?: {
942
- attempted: boolean;
943
- method?: "GET" | "POST";
944
- /** The route that answered. v1 paths appear only in evidence saved before @zyfai/sdk 0.10.0. */
945
- path?: "/users/withdraw" | "/users/partial-withdraw" | "/users/withdraw/v2" | "/users/partial-withdraw/v2";
946
- elapsedMs?: number;
947
- /** Actual response status captured before the vendor replaces the HTTP error. */
948
- httpStatus?: number;
949
- failure?: "network" | "unauthorized" | "forbidden" | "rate-limited" | "insufficient-balance" | "session-key-missing" | "withdrawal-in-progress" | "other";
950
- /** When the provider accepted the request without a hash (ms since epoch). */
951
- acceptedAt?: number;
952
- /** Zyfai's v2 withdrawal id, for the lifecycle lookup (1-128 chars). */
953
- providerWithdrawalId?: string;
954
- };
955
- /** Where an on-chain payout search may start, for a hashless acceptance.
956
- * `fromBlock` is the chain head read just before the request (decimal string). */
957
- payoutSearch?: {
958
- fromBlock?: string;
959
- };
960
- transfer: FundingStage;
961
- registration: FundingStage;
962
- delivery: FundingStage;
963
- }
964
- type FundingProgress = (evidence: FundingEvidence) => void;
965
- /** The part of Zyfai's withdrawal lifecycle (`GET /users/withdrawals/{id}`) that Owney acts on. */
966
- type ZyfaiWithdrawalLifecycle = {
967
- status: string;
968
- /** The synchronous payout leg has settled. */
969
- syncSettled: boolean;
970
- /** Hash of the synchronous payout transaction; present only when well formed. */
971
- syncTxHash?: `0x${string}`;
972
- /** Delayed (protocol-cooldown) redemption legs; empty when none or unreadable. */
973
- asyncLegs: {
974
- id: string;
975
- status: string;
976
- estimatedClaimAt?: string;
977
- claimTxHash?: `0x${string}`;
978
- }[];
979
- /** Ids of delayed legs Zyfai reports as failed. */
980
- failedAsyncIds: string[];
981
- /** When the delayed part is expected to arrive; present only when a valid date. */
982
- estimatedClaimAt?: string;
983
- /** Zyfai recorded an error for this withdrawal. Its text is never carried. */
984
- hasError: boolean;
562
+ /** Names enabled by the user for this asset/protocol/chain. */
563
+ pools: string[];
564
+ /** Every name shown for this asset/protocol/chain in the superset catalog. */
565
+ availablePools: string[];
985
566
  };
986
- /** The part of Zyfai's deposit status (`GET /users/deposits/{id}/v2`) that Owney acts on. */
987
- type ZyfaiDepositPlacement = {
988
- /** `handover_pending | credited | position_pending | positioned | recovered_to_eoa`. */
989
- status: string;
990
- /** `pending | positioned | skipped | failed`. */
991
- positionOutcome?: string;
567
+ /** The complete saved draft for the asset/chain legs selected in the deposit. */
568
+ type UserPoolSelectionRequest = {
569
+ strategies: Array<{
570
+ asset: "USDC" | "WETH";
571
+ strategy: PoolSelectionStrategy;
572
+ }>;
573
+ selections: UserPoolSelection[];
992
574
  };
993
- interface AssetReadMetadata {
994
- chainId: number;
995
- asset: string;
996
- fetchedAt?: number;
997
- /** When the underlying provider request started; preserved on cached reads. */
998
- requestedAt?: number;
999
- /** SDK cache generation, not an onchain block or provider timestamp. */
1000
- readVersion?: number;
1001
- providerUpdatedAt?: string;
1002
- snapshotId?: string;
1003
- blockNumber?: string;
1004
- netDepositsRaw?: string;
1005
- /** Display-only agreement with a post-payout read. Does not prove that
1006
- * provider accounting, history or allocations include the transaction. */
1007
- withdrawalCheck?: {
1008
- txHash: string;
1009
- blockNumber: string;
1010
- };
1011
- positionsStatus: "available" | "unavailable";
1012
- }
575
+ /**
576
+ * What a user's account currently has saved (ROUT-650): each asset's strategy,
577
+ * plus the pool list of every protocol/chain pair frozen by an earlier Save.
578
+ * Pairs Zyfai still autoselects are left out, so "no entry" means "default".
579
+ */
580
+ type SavedPoolSelection = {
581
+ strategies: Array<{
582
+ asset: "USDC" | "WETH";
583
+ strategy: string;
584
+ }>;
585
+ pairs: Array<{
586
+ protocolId: string;
587
+ chainId: number;
588
+ pools: string[];
589
+ }>;
590
+ };
591
+ /** One protocol with its pools for the deposit asset — what the Pools step
592
+ * renders: a protocol row that opens to a list of selectable pools. */
593
+ type PoolCatalogProtocol = {
594
+ protocolId: string;
595
+ name: string;
596
+ logo: string | null;
597
+ pools: AvailablePool[];
598
+ };
599
+
1013
600
  interface OwneyDepositResult {
1014
- evidence?: FundingEvidence;
1015
601
  txHash: string;
1016
602
  smartWallet: string;
1017
603
  amount: string;
1018
- /** Funding ledger reference for this deposit (quote it in support tickets). */
1019
- operationId?: string;
1020
604
  }
1021
605
  interface OwneyMultiDepositResult {
1022
606
  agentResults: Record<string, OwneyDepositResult>;
1023
- /** Funding ledger reference for this deposit (quote it in support tickets). */
1024
- operationId?: string;
1025
607
  }
1026
608
  interface AgentWithdrawResult {
1027
- evidence?: FundingEvidence;
1028
609
  txHash?: string;
1029
610
  type: "full" | "partial";
1030
- /** Owner payout or clearing all MAX positions still needs verification. */
1031
- completion?: "unverified";
1032
- /** Confirmed smallest-unit amount; "0" when no owner payout is verified.
1033
- * Legacy providers may return a sentinel such as "all" for a full request. */
611
+ /** Smallest-unit amount, or a provider sentinel such as "all" for a full request. */
1034
612
  amount: string;
1035
- /** Yieldseeker typed withdrawal fulfilled after an exactly verified fee
1036
- * deduction. Amount remains the confirmed net owner payout, and the gross
1037
- * amount must equal that payout plus the fee, all in token base units. */
1038
- feeAdjustment?: {
1039
- grossAmount: string;
1040
- feeAmount: string;
1041
- };
1042
- /** Funding ledger reference for this withdrawal (quote it in support tickets).
1043
- * Set on the result of a single-agent `withdraw()`, not on per-agent entries. */
1044
- operationId?: string;
1045
613
  }
1046
614
  interface OwneyWithdrawResult {
1047
615
  agentResult: Record<AgentId, AgentWithdrawResult>;
1048
616
  /**
1049
- * Sum of confirmed smallest-unit amounts; null while any returned leg's
1050
- * payout is not yet known, including typed requests accepted asynchronously.
1051
- * Evidence-less custom adapters retain their confirmed-amount contract.
617
+ * Sum of reported smallest-unit amounts; null when a full withdrawal's
618
+ * amount is not yet known. An accepted request is not proof of settlement.
1052
619
  */
1053
620
  totalWithdrawn: string | null;
1054
- /** Funding ledger reference for this withdrawal (quote it in support tickets). */
1055
- operationId?: string;
1056
621
  }
1057
622
  interface OwneyToken {
1058
623
  chain: OwneySupportedChains;
@@ -1068,10 +633,6 @@ interface OwneyPosition {
1068
633
  pool?: string;
1069
634
  asset: string;
1070
635
  amount: string;
1071
- /** Provider-native raw quantity; may represent vault shares, not the underlying asset. */
1072
- amountRaw?: string;
1073
- /** Withdrawable underlying asset amount in that asset's smallest units. */
1074
- withdrawableAmountRaw?: string;
1075
636
  apy?: number;
1076
637
  tvl?: number;
1077
638
  /** Pool liquidity. Prepared slot — Zyfai will add this to its portfolio
@@ -1101,34 +662,11 @@ interface OwneyPendingAllocation {
1101
662
  /** ISO timestamp from Zyfai's `updatedAt`, when the payload carries one. */
1102
663
  since?: string;
1103
664
  }
1104
- /**
1105
- * A Zyfai delayed redemption in flight (`REQUESTED` or `CLAIMABLE`). Its funds
1106
- * are in neither `positions` nor `tokens`; display-only, never added to a total.
1107
- */
1108
- interface OwneyPendingWithdrawal {
1109
- id: string;
1110
- status: string;
1111
- chainId: number;
1112
- /** Token symbol as Zyfai reports it. */
1113
- asset: string;
1114
- /** Redeemed amount in least units, as a decimal string. */
1115
- amountRaw: string;
1116
- }
1117
665
  interface AgentBalance {
1118
- readMetadata?: AssetReadMetadata[];
1119
- /** Authoritative native balances per asset/network, including idle and invested funds. */
1120
- assetBalances?: OwneyToken[];
1121
666
  smartWallet?: `0x${string}`;
1122
667
  totalBalance: string;
1123
668
  /** Asset that `totalBalance` is denominated in. Currently always `"usdc"`. */
1124
669
  totalBalanceAsset: string;
1125
- /**
1126
- * Describes whether `tokens` already includes deployed `positions`.
1127
- * Consumers must add matching positions only for `tokens-plus-positions`;
1128
- * doing so for Zyfai would double-count, while omitting it for Yieldseeker
1129
- * makes its balance disappear as soon as idle funds enter a vault.
1130
- */
1131
- balanceComposition?: "tokens-include-positions" | "tokens-plus-positions";
1132
670
  tokens: OwneyToken[];
1133
671
  /**
1134
672
  * Per-protocol/pool positions when the agent's portfolio payload includes
@@ -1137,36 +675,35 @@ interface AgentBalance {
1137
675
  positions?: OwneyPosition[];
1138
676
  /** Funds received but not yet deployed. Omitted when nothing is pending. */
1139
677
  pendingAllocations?: OwneyPendingAllocation[];
1140
- /** Zyfai only: delayed redemptions still in flight. Omitted when none. Never part of a total. */
1141
- pendingWithdrawals?: OwneyPendingWithdrawal[];
1142
- /**
1143
- * Zyfai only: every delayed redemption Zyfai lists except FAILED, recently
1144
- * CLAIMED ones included (Zyfai keeps them about a day). Present, possibly
1145
- * empty, whenever Zyfai sent the list; absent when it did not. Empty means no
1146
- * older delayed payout can be landing now. Never part of a total.
1147
- */
1148
- recentAsyncWithdrawals?: OwneyRecentAsyncWithdrawal[];
1149
678
  }
1150
- /** A delayed Zyfai redemption by status, for telling a new payout from an older remainder. */
1151
- type OwneyRecentAsyncWithdrawal = {
1152
- id: string;
1153
- status: string;
1154
- chainId: number;
1155
- asset: string;
1156
- };
679
+ /**
680
+ * One position drained by `withdrawAll()` — a chain and asset pair.
681
+ *
682
+ * Carries either a result or an error, never both: a leg that failed while
683
+ * others succeeded is the normal case, not an exception, and the caller needs
684
+ * to name the ones that did not arrive.
685
+ */
686
+ interface OwneyWithdrawAllLeg {
687
+ chainId: OwneySupportedChainId;
688
+ asset: OwneySupportedTokens;
689
+ /** What the position held when the sweep started. */
690
+ amount: string;
691
+ result?: OwneyWithdrawResult | AgentWithdrawResult;
692
+ error?: string;
693
+ }
694
+ interface OwneyWithdrawAllResult {
695
+ /** Every position attempted, in the order it was attempted. */
696
+ legs: OwneyWithdrawAllLeg[];
697
+ }
1157
698
  interface OwneyBalances {
1158
699
  totalBalance: string;
1159
700
  /** Asset that `totalBalance` is denominated in. Currently always `"usdc"`. */
1160
701
  totalBalanceAsset: string;
1161
702
  agentBalances: Record<AgentId, AgentBalance>;
1162
- /**
1163
- * Per-agent read failures when an aggregate balance request returned only a
1164
- * partial result. Callers may display the successful balances, but funding
1165
- * operations must not interpret a missing agent as having a zero balance.
1166
- */
1167
- agentErrors?: Partial<Record<AgentId, string>>;
703
+ /** Omitted agents failed to load; they must not be interpreted as zero. */
704
+ agentErrors?: Record<AgentId, string>;
1168
705
  /** Absolute provider cooldown deadlines (Unix milliseconds). */
1169
- agentRetryAt?: Partial<Record<AgentId, number>>;
706
+ agentRetryAt?: Record<AgentId, number>;
1170
707
  }
1171
708
  interface AgentEarnings {
1172
709
  smartWallet: `0x${string}`;
@@ -1176,10 +713,6 @@ interface AgentEarnings {
1176
713
  interface OwneyEarnings {
1177
714
  totalEarnings: string;
1178
715
  agentEarnings: Record<AgentId, AgentEarnings>;
1179
- /** Per-agent failures when an aggregate read returned a partial result. */
1180
- agentErrors?: Partial<Record<AgentId, string>>;
1181
- /** Absolute provider cooldown deadlines (Unix milliseconds). */
1182
- agentRetryAt?: Partial<Record<AgentId, number>>;
1183
716
  }
1184
717
  type ApyByChainAndAsset = Partial<Record<OwneySupportedChainId, Partial<Record<OwneySupportedTokens, number>>>>;
1185
718
  /** A single day's net APY for the connected account, as a percentage number. */
@@ -1194,6 +727,36 @@ interface ApyHistoryPoint {
1194
727
  unit: string;
1195
728
  };
1196
729
  }
730
+ /**
731
+ * What the APY chart's chain/asset menus are allowed to offer, and how far
732
+ * back each option reaches (ROUT-479).
733
+ *
734
+ * An option only earns a place if some day in the window held a real position
735
+ * on it — a balance and a rate. Listing anything else would offer a filter
736
+ * that draws a blank chart. `days` is what the menu prints beside each row,
737
+ * and the legs genuinely differ: a wallet can hold USDC for a fortnight and
738
+ * WETH for three days.
739
+ */
740
+ interface ApyCoverage {
741
+ chains: {
742
+ chainId: number;
743
+ days: number;
744
+ }[];
745
+ /** Legs whose `tokenSymbol` the provider left unset are absent — they cannot
746
+ * be named, so they cannot be picked. Their chain still counts. */
747
+ assets: {
748
+ asset: string;
749
+ days: number;
750
+ }[];
751
+ /** Each asset on each chain, for a menu that offers the two together
752
+ * (ROUT-647). The lists above cannot say this: USDC on Base and WETH on
753
+ * Arbitrum put both chains and both assets in them, and no WETH on Base. */
754
+ pairs: {
755
+ chainId: number;
756
+ asset: string;
757
+ days: number;
758
+ }[];
759
+ }
1197
760
  interface AccountAgentApy {
1198
761
  walletAddress: string;
1199
762
  weightedApyAfterFee?: number;
@@ -1204,6 +767,8 @@ interface AccountAgentApy {
1204
767
  * date. Empty when the provider returns no daily history.
1205
768
  */
1206
769
  history?: ApyHistoryPoint[];
770
+ /** Which chains/assets this history can be filtered down to. */
771
+ coverage?: ApyCoverage;
1207
772
  }
1208
773
  interface OwneyAccountApy {
1209
774
  totalApy: string;
@@ -1225,15 +790,6 @@ interface OwneyAllocationApy {
1225
790
  }
1226
791
  type HistoryAction = "Rebalance" | "Deposit" | "Top up" | "Withdraw" | "Earned";
1227
792
  interface HistoryTransaction {
1228
- tokenAddress?: string;
1229
- agentWallet?: string;
1230
- logIndexes?: number[];
1231
- transferLogs?: {
1232
- logIndex: number;
1233
- amountRaw: string;
1234
- }[];
1235
- amountRaw?: string;
1236
- blockNumber?: string;
1237
793
  txHashes: string[];
1238
794
  chainId?: number;
1239
795
  tokenSymbol?: string;
@@ -1254,39 +810,40 @@ interface RebalanceLog {
1254
810
  tokenSymbol: string;
1255
811
  amount: string;
1256
812
  status: "success" | "failed";
1257
- /** Fee-net APY at execution time for the source leg, in percentage points. */
1258
- fromApy?: string;
1259
- /** Fee-net APY at execution time for the destination leg, in percentage points. */
1260
- toApy?: string;
1261
813
  }
1262
814
  interface AgentHistoryPosition {
1263
815
  protocol: string;
1264
816
  pool?: string;
1265
817
  tokenSymbol?: string;
1266
- /** The position balance after the action (decimal string, token units). */
1267
818
  amount?: string;
1268
- /**
1269
- * The amount the action actually moved (decimal string, token units), as
1270
- * opposed to `amount`, the resulting position balance. Present only when the
1271
- * provider reports it; withheld on withdrawals.
1272
- */
1273
- deltaAmount?: string;
1274
819
  }
1275
820
  interface AgentHistoryEntry {
1276
- /** Stable provider/transfer identity, independent of row order. */
1277
- id?: string;
1278
821
  agent: AgentId;
1279
822
  action: HistoryAction;
823
+ /**
824
+ * Chain this entry came from, stamped by the history fan-out (ROUT-479).
825
+ *
826
+ * Absent on a single-chain read, where the caller already knows the chain.
827
+ * The entry has no chain of its own otherwise: `transactions[].chainId` is
828
+ * optional and missing whenever the indexer has not attached the transfer,
829
+ * so a row cannot be labelled from it reliably.
830
+ */
831
+ chainId?: OwneySupportedChainId;
1280
832
  date: string;
1281
833
  oldApy: string | null;
1282
834
  newApy: string | null;
1283
835
  transactions: HistoryTransaction[];
1284
836
  rebalanceLog: RebalanceLog[];
1285
837
  positions?: AgentHistoryPosition[];
838
+ /**
839
+ * Set on a `Withdraw` that was only requested from an async vault
840
+ * (ROUT-624). The vault pays out in batches later, so the funds have not
841
+ * reached the wallet yet and `transactions[0].amount` is the amount
842
+ * requested.
843
+ */
844
+ asyncRequest?: true;
1286
845
  }
1287
846
  interface OwneyAgentHistory {
1288
- agentErrors?: Partial<Record<AgentId, string>>;
1289
- agentRetryAt?: Partial<Record<AgentId, number>>;
1290
847
  data: AgentHistoryEntry[];
1291
848
  /** True iff a subsequent page exists; pair with `nextCursor`. */
1292
849
  hasMore: boolean;
@@ -1325,18 +882,17 @@ interface AgentApy {
1325
882
  detailedApys?: AgentApyDetails;
1326
883
  }
1327
884
  interface OwneyAgentApy {
1328
- /** Agents without data for the requested period are omitted. */
1329
- agentApy: Partial<Record<AgentId, AgentApy>>;
885
+ agentApy: Record<AgentId, AgentApy>;
1330
886
  }
1331
- /** One day's cumulative earnings for a single asset. */
887
+ /** One day's cumulative NET earnings for a single asset. */
1332
888
  interface DailyEarningsPoint {
1333
889
  /** ISO date string for the day, e.g. "2026-09-01". */
1334
890
  date: string;
1335
891
  /**
1336
- * Cumulative earnings in the asset's own units, using the provider's earnings
1337
- * basis. A provider may return lifetime totals or a running window total;
1338
- * difference the last and opening points to measure earnings over the window.
1339
- * Aggregate series normalize each component's opening value before summing.
892
+ * Earnings accumulated from the start of the returned series up to and
893
+ * including this day, net of the agent's performance fee, denominated in the
894
+ * asset's own units. A running total of daily deltas, so it measures the
895
+ * window — not the wallet's lifetime.
1340
896
  */
1341
897
  amount: number;
1342
898
  }
@@ -1345,9 +901,8 @@ interface AssetDailyEarnings {
1345
901
  /** Asset symbol, e.g. "USDC" / "WETH". */
1346
902
  asset: string;
1347
903
  /**
1348
- * Ascending by date, including an opening snapshot before the requested
1349
- * window when available. Provider gaps remain absent; aggregates carry the
1350
- * most recent cumulative value across dates reported by other providers.
904
+ * Ascending by date. Days the wallet held nothing of this asset are absent
905
+ * rather than zero — a zero would read as "earned nothing that day".
1351
906
  */
1352
907
  points: DailyEarningsPoint[];
1353
908
  }
@@ -1364,53 +919,107 @@ interface AccountDailyEarnings {
1364
919
  assets: AssetDailyEarnings[];
1365
920
  }
1366
921
 
1367
- type ReservationAgent = "zyfai" | "surfliquid" | "yieldseeker";
1368
- type WithdrawalReservationMode = "fail-open" | "fail-closed" | "off";
1369
- type ReservationReleaseReason = "confirmed" | "failed" | "not_submitted";
1370
- /** What the 409 tells the app. The holding operation's id and token are never returned. */
1371
- type WithdrawalReservationConflict = {
1372
- /** First 8 hex characters of the holding operation's id. */
1373
- reference: string;
1374
- ageSec: number;
1375
- expiresInSec: number;
1376
- agents: ReservationAgent[];
1377
- state: "preparing" | "dispatched";
1378
- /** True for an unproven hold: the app may resend with `override: reference`. */
1379
- overridable: boolean;
1380
- };
1381
-
922
+ type DepositCallback = (smartWalletAddress: string, chainId: number, amount: string) => Promise<`0x${string}`> | `0x${string}`;
923
+ interface IAgent {
924
+ readonly id: string;
925
+ readonly supportedChainIds: readonly OwneySupportedChainId[];
926
+ readonly supportedAssets: readonly AgentSupportedAssets[];
927
+ disconnect(): Promise<void>;
928
+ activateAgent(state: ConnectionState, chainId: number): Promise<void>;
929
+ /**
930
+ * Apply the organization's agent policy to this user's account.
931
+ *
932
+ * Optional: an agent that has no equivalent knob simply omits it, which is why
933
+ * this is not part of `activateAgent`'s signature. Declared on the interface
934
+ * rather than only on ZyfaiAgent so the contract stays agent-neutral — the
935
+ * ticket asks for a design that can also cover Surf, which has no adapter yet.
936
+ *
937
+ * Implementations must be **non-fatal**: this runs during activation as a side
938
+ * effect, so a failure has to leave the user connected and their profile
939
+ * unchanged rather than break the connect.
940
+ */
941
+ applyOrgPolicy?(state: ConnectionState, chainId: number, policy: OrgAgentConfig): Promise<void>;
942
+ /**
943
+ * The deposit-time pool catalogue for one asset and strategy: protocols with
944
+ * their selectable pools and figures. Optional — an agent with no pool
945
+ * customization omits it. (ROUT-569)
946
+ */
947
+ getPoolCatalog?(params: {
948
+ asset: string;
949
+ strategy: "conservative" | "aggressive" | "yieldmaxxing";
950
+ }): Promise<PoolCatalogProtocol[]>;
951
+ /**
952
+ * Apply a user's own pool selection to their account, driven by the
953
+ * deposit-time Pools step. Optional, and non-fatal like `applyOrgPolicy`.
954
+ * (ROUT-569)
955
+ */
956
+ setPoolSelection?(selection: UserPoolSelectionRequest): Promise<void>;
957
+ /**
958
+ * Read back what `setPoolSelection` saved, for the pairs and assets given,
959
+ * so the Pools step can open on the user's own choices. Optional. (ROUT-650)
960
+ */
961
+ getPoolSelection?(state: ConnectionState, chainId: number, params: {
962
+ pairs: Array<{
963
+ protocolId: string;
964
+ chainId: number;
965
+ }>;
966
+ assets: Array<"USDC" | "WETH">;
967
+ }): Promise<SavedPoolSelection>;
968
+ deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback): Promise<OwneyDepositResult>;
969
+ withdraw(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount?: string): Promise<AgentWithdrawResult>;
970
+ getBalances(state: ConnectionState, chainId: number): Promise<AgentBalance>;
971
+ getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
972
+ /**
973
+ * Refresh the agent's earnings snapshot when its backend supports doing so.
974
+ * Implementations own freshness and request-deduplication policy.
975
+ */
976
+ refreshEarnings?(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
977
+ getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays,
978
+ /**
979
+ * Optional asset symbol ("USDC" / "WETH") scoping the daily series to a
980
+ * single asset on the chain. Agents without per-asset positions ignore it.
981
+ */
982
+ tokenSymbol?: string,
983
+ /**
984
+ * Chain the series is scoped to, when that differs from the chain the
985
+ * connection is on. `null` spans every chain the wallet held (ROUT-479);
986
+ * omitted means `chainId`. Kept apart from `chainId` because that one
987
+ * still resolves the wallet and must stay a real, connected chain.
988
+ */
989
+ scopeChainId?: number | null): Promise<AccountAgentApy>;
990
+ /**
991
+ * Daily cumulative NET earnings for the window, scoped to a chain/asset.
992
+ * Backs the "recent earnings" subline, whose figure must reconcile with the
993
+ * balance headline directly above it. (ROUT-452)
994
+ */
995
+ getDailyEarnings?(state: ConnectionState, chainId: number, days: LookbackDays, tokenSymbol?: string): Promise<AccountDailyEarnings>;
996
+ getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
997
+ getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
998
+ /**
999
+ * Ensure the given asset uses backend protocol auto-selection
1000
+ * (`autoSelectProtocols: true`). Optional capability — only agents whose
1001
+ * backend models per-asset protocol selection implement it. Returns whether
1002
+ * a write occurred (`false` = already enabled / not supported).
1003
+ */
1004
+ ensureAutoSelectProtocols?(state: ConnectionState, chainId: number, asset: "USDC" | "WETH"): Promise<boolean>;
1005
+ getAgentApy(days: DailyApyDays, options?: AgentApyOptions): Promise<AgentApy>;
1006
+ }
1382
1007
  /**
1383
- * On-chain discovery of a hashless withdrawal's payout.
1384
- *
1385
- * Lists ERC-20 `Transfer` logs on the operation's token that reach the owner.
1386
- * The sender is never filtered: routed payouts hop through intermediaries.
1387
- * This only finds candidates; each one must still be proven with the receipt
1388
- * inspection (`inspectFunding(candidate, "withdraw", { requireAmountMatch: true })`).
1008
+ * Optional filters for per-agent APY lookups.
1009
+ * - `tokenSymbol` / `chainId` scope the APY to a specific asset+chain when
1010
+ * the underlying provider supports it (Zyfai). Agents whose backends do
1011
+ * not yet support per-asset APY will ignore these options.
1389
1012
  */
1390
- type WithdrawalPayoutCandidate = {
1391
- txHash: string;
1392
- /** Decimal block number. */
1393
- blockNumber: string;
1394
- logIndex: number;
1395
- /** Transferred amount in token base units. */
1396
- amountRaw: string;
1397
- };
1398
- type WithdrawalPayoutScan = {
1399
- candidates: WithdrawalPayoutCandidate[];
1400
- /** Last block scanned (inclusive, decimal). Pass it back as the next `cursor`. */
1401
- scannedTo: string;
1402
- /** False when the call stopped at its request limit before the scan end (the
1403
- * head minus the reorg margin), so more blocks are already waiting. */
1404
- caughtUp: boolean;
1013
+ type AgentApyOptions = {
1014
+ tokenSymbol?: string;
1015
+ chainId?: number;
1405
1016
  };
1406
1017
 
1407
- 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";
1018
+ 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" | "SWAP_ORDER_NOT_FOUND" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "POOL_CATALOG_UNSUPPORTED" | "POOL_SELECTION_UNSUPPORTED" | "VALIDATION_INVALID_DAYS";
1408
1019
  declare class OwneyError extends Error {
1409
1020
  readonly code: OwneyErrorCode;
1410
1021
  readonly details?: Record<string, unknown>;
1411
1022
  readonly agentId?: string;
1412
- /** Funding ledger reference, set when a funding operation fails. */
1413
- operationId?: string;
1414
1023
  constructor(code: OwneyErrorCode, message: string, details?: Record<string, unknown>, agentId?: string);
1415
1024
  }
1416
1025
  declare class AgentNotFoundError extends OwneyError {
@@ -1431,35 +1040,41 @@ declare class AgentChainIncompatibleError extends OwneyError {
1431
1040
  }>, connectedChainId: number);
1432
1041
  }
1433
1042
 
1434
- /** Durable intent and evidence, including the gap before an order exists. */
1435
- type WithdrawalSwapRecovery = {
1436
- attemptId: string;
1437
- phase: "withdrawing" | "verifying" | "ready" | "submitted" | "incomplete";
1438
- baseline: string;
1439
- baselineBlock: string;
1440
- submittedAt: number;
1441
- deadline: number;
1442
- requested?: string;
1443
- agentId?: AgentId;
1444
- results?: Record<string, AgentWithdrawResult>;
1445
- evidence: Record<string, FundingEvidence>;
1446
- reason?: string;
1447
- };
1448
- /** Unknown and partial outcomes remain recoverable until settlement is verified. */
1449
- type WithdrawSwapStatus = "swapping" | "landed" | "refunded" | "unknown" | "refund-pending" | "partially-filled" | "withdrawal-pending" | "withdrawal-incomplete" | "ready" | "not-swapped";
1043
+ /**
1044
+ * Withdrawal swaps the user has walked away from, and how they ended.
1045
+ *
1046
+ * The deposit side has `swap.pending-deposit.ts` for the same shape of
1047
+ * problem, but the two are not symmetrical. A pending deposit is a JOB: the
1048
+ * money is in the wallet and an ordinary deposit finishes it. This is a
1049
+ * WATCH — the funds are in escrow, nothing the user does moves them along,
1050
+ * and the only question is where they ended up.
1051
+ *
1052
+ * That is the whole reason this exists. `withdrawAndSwap` used to hold the
1053
+ * screen for the entire escrow lifecycle, which on a slow mainnet fill is
1054
+ * minutes of a modal the user cannot leave (ROUT-242). Backgrounding it means
1055
+ * the outcome arrives after the UI that started it has gone, so the outcome
1056
+ * has to be written down somewhere the next render can find it.
1057
+ *
1058
+ * Only cross-chain swaps are recorded. A same-chain classic swap is one
1059
+ * transaction and resolves in seconds; a same-chain fusion order has no stored
1060
+ * preimages, so there would be nothing for a reloaded session to resume and
1061
+ * the record would sit at `swapping` for ever.
1062
+ *
1063
+ * Kept deliberately separate from the secret store. Secrets are retired the
1064
+ * moment an order reaches a verdict — that is a safety property, not a display
1065
+ * one — and the record has to outlive them so the user can still be told what
1066
+ * happened after they come back.
1067
+ */
1068
+ /**
1069
+ * `swapping` is the only non-terminal state. `unknown` is what a watch that
1070
+ * gave up looks like: we stopped polling before the order spoke, so the order
1071
+ * may well have filled. It is not a failure, and it must never be shown as
1072
+ * one.
1073
+ */
1074
+ type WithdrawSwapStatus = "swapping" | "landed" | "refunded" | "unknown";
1450
1075
  type WithdrawSwapRecord = {
1451
1076
  /** Identity. One record per Fusion+ order. */
1452
1077
  orderHash: string;
1453
- walletAddress?: string;
1454
- txHash?: string;
1455
- /**
1456
- * The funding-ledger operation of this withdrawal and swap, reused when it
1457
- * is continued or rechecked. Absent on records written by an older SDK.
1458
- */
1459
- operationId?: string;
1460
- recovery?: WithdrawalSwapRecovery;
1461
- spent?: string;
1462
- dismissed?: boolean;
1463
1078
  status: WithdrawSwapStatus;
1464
1079
  /**
1465
1080
  * What actually left the agent, smallest unit of the SOURCE asset.
@@ -1496,7 +1111,7 @@ declare function subscribeWithdrawSwaps(listener: () => void): () => void;
1496
1111
  * Not after the swap resolves: the point is to survive the gap between submit
1497
1112
  * and settle, which is exactly when the user closes the tab.
1498
1113
  */
1499
- declare function saveWithdrawSwap(record: WithdrawSwapRecord): boolean;
1114
+ declare function saveWithdrawSwap(record: WithdrawSwapRecord): void;
1500
1115
  /**
1501
1116
  * Move a record to its outcome.
1502
1117
  *
@@ -1510,8 +1125,8 @@ declare function saveWithdrawSwap(record: WithdrawSwapRecord): boolean;
1510
1125
  declare function updateWithdrawSwap(orderHash: string, patch: Partial<Omit<WithdrawSwapRecord, "orderHash">>): void;
1511
1126
  /** The user has read the outcome. Only they do this. */
1512
1127
  declare function clearWithdrawSwap(orderHash: string): void;
1513
- /** Visible records, newest first. Only verified terminal records expire by age. */
1514
- declare function listWithdrawSwaps(now?: number, includeDismissed?: boolean): WithdrawSwapRecord[];
1128
+ /** Every record, newest first, sweeping anything past MAX_AGE_MS. */
1129
+ declare function listWithdrawSwaps(now?: number): WithdrawSwapRecord[];
1515
1130
 
1516
1131
  /**
1517
1132
  * Swaps that landed but were never deposited.
@@ -1546,11 +1161,6 @@ type PendingDeposit = {
1546
1161
  agentId?: string;
1547
1162
  /** Epoch ms, for the sweep. */
1548
1163
  createdAt: number;
1549
- /**
1550
- * The swap's funding-ledger operation, so finishing the deposit reports into
1551
- * it. Absent on records written by an older SDK.
1552
- */
1553
- operationId?: string;
1554
1164
  };
1555
1165
  /** Every record, dismissed ones included, newest first. Sweeps as it goes. */
1556
1166
  declare function listPendingDeposits(now?: number): PendingDeposit[];
@@ -1565,96 +1175,22 @@ declare class OwneySDK {
1565
1175
  */
1566
1176
  private disabledAgents;
1567
1177
  private state;
1568
- private connectionRevision;
1569
- private disconnectingAgents;
1570
1178
  private apiKey;
1571
1179
  private orgAgentConfig;
1572
1180
  private orgAgentConfigPromise;
1573
- private rpcUrls?;
1574
1181
  private zyfaiRpcUrls?;
1575
- private yieldseekerApiBaseUrl?;
1576
- private yieldseekerSiweOrigin?;
1182
+ private userPoolCustomization;
1577
1183
  private routingApiBaseUrl?;
1578
1184
  private referralSource?;
1579
- private readonly ledger;
1580
- private readonly reservationMode;
1581
- private readonly reservationTransport;
1582
- /** The caller's Zyfai server tasks opt-in: `true`, a function read each
1583
- * time a handoff would start (F-I2(iii)), or undefined (off). */
1584
- private readonly zyfaiServerTasks;
1585
- /** The caller opted in to the Fusion+ secret handoff (`fusionSecretHandoff: true`). */
1586
- private readonly fusionSecretHandoff;
1587
1185
  private cachedSponsoredCallback;
1588
1186
  private cachedWethSponsoredCallback;
1589
1187
  private paymasterServiceUrl?;
1590
1188
  private cachedSponsoredCallsCallbacks;
1591
1189
  private readonly agentReads;
1592
- private readonly depositFamilyReads;
1593
- /** Movements (owner, chain, agent, token, tx hash) whose balance refresh this
1594
- * session started: true when it armed the refresh, false when its deadline
1595
- * had passed (it only dropped the cache and forced one snapshot read). */
1596
- private readonly recoveredFundingReads;
1597
- private fundingBalanceChecks;
1598
1190
  private readonly activationChecks;
1599
- private readonly withdrawalSubmissions;
1600
- private readonly withdrawalSwapSubmissions;
1601
1191
  private readAgent;
1602
1192
  private initializingAgentsPromise;
1603
1193
  constructor(config: OwneySDKConfig);
1604
- /** Finishes a funding-ledger operation on success and adds its reference to
1605
- * the result. The result object is copied, never mutated or replaced.
1606
- * `OK` replaces any failure code an earlier attempt of the same operation
1607
- * recorded (a resumed pending deposit, a continuation). */
1608
- private ledgerSucceeded;
1609
- /** Tags a failure with its funding-ledger reference and finishes the
1610
- * operation. The error is never wrapped or replaced. */
1611
- private ledgerFailed;
1612
- /**
1613
- * Swap operations running right now, by operationId. A deposit or withdrawal
1614
- * started with one of these ids is the inner half of that swap and joins its
1615
- * operation instead of starting its own (see `startLedger`).
1616
- */
1617
- private readonly openSwapLedgers;
1618
- /**
1619
- * Starts a funding-ledger operation, or joins the open swap operation with
1620
- * the same id. A joined call reports its legs into the swap's operation and
1621
- * leaves finishing to the swap, so the operation gets one outcome, sent on
1622
- * one ordered request chain.
1623
- */
1624
- private startLedger;
1625
- /** Starts a swap's operation and opens it to the swap's inner deposit or
1626
- * withdrawal. Never throws: reporting never blocks a swap. */
1627
- private openSwapLedger;
1628
- /**
1629
- * Part 5: the swap's ledger identity, for the executor's Fusion+ secret
1630
- * handoff. Only with the `fusionSecretHandoff` opt-in and an open operation;
1631
- * otherwise undefined, and the executor sends nothing. Owner and token are
1632
- * lowercased, as the ledger reports them.
1633
- */
1634
- private secretHandoffFor;
1635
- private closeSwapLedger;
1636
- /** Reports one agent's withdrawal evidence as its leg (with `errorCode`, when
1637
- * given). Never throws. */
1638
- private ledgerWithdrawalLeg;
1639
- /** Operation/leg/tx keys whose provider samples are already scheduled. */
1640
- private readonly providerSampleKeys;
1641
- /**
1642
- * For a confirmed leg of an operation this SDK reported, records the agent's
1643
- * own earnings bookkeeping as `provider.sample` events at confirmation, +5
1644
- * and +30 min (Zyfai; evidence for provider lag). Only agents that expose a
1645
- * never-prompting sample read take part. Fire-and-forget, never throws;
1646
- * a later sample is skipped once the wallet disconnects or changes.
1647
- */
1648
- private ledgerProviderSamples;
1649
- /**
1650
- * Funding-ledger read access handed to agents for earnings holds. Reads only
1651
- * for the connected owner; null otherwise and on any failure.
1652
- */
1653
- private agentLedgerAccess;
1654
- /** Reports the swap leg. Never throws: reporting never affects a swap. */
1655
- private ledgerSwap;
1656
- /** Reports the swap leg of a swap that threw, with any identifier it carried. */
1657
- private ledgerSwapFailed;
1658
1194
  /**
1659
1195
  * Establish connection state for all subsequent SDK calls.
1660
1196
  * Must be called once before any agent operation that requires a wallet.
@@ -1666,8 +1202,6 @@ declare class OwneySDK {
1666
1202
  * After calling this, `connect()` must be called again before using agent methods.
1667
1203
  */
1668
1204
  disconnect(): Promise<void>;
1669
- private clearConnectionState;
1670
- private disconnectAgents;
1671
1205
  private isAgentDisabled;
1672
1206
  /**
1673
1207
  * Check if the SDK has an active connection state.
@@ -1679,39 +1213,31 @@ declare class OwneySDK {
1679
1213
  * @returns The active chain ID, or `null` if `activateAgent` has not been called
1680
1214
  */
1681
1215
  getActiveChainId(): number | null;
1682
- /**
1683
- * The funding-ledger operations this app has for the connected wallet and
1684
- * `asset` (default chain: the active one). Never throws: resolves `null` when
1685
- * not connected, with no chain, when ledger reporting is disabled, or on any
1686
- * failure, which callers treat as "no ledger information".
1687
- *
1688
- * Full `clientOperationId`s come back only for ids passed in `ids`. The ids
1689
- * are trimmed and lowercased, non-uuid strings are dropped, and the first 50
1690
- * distinct ids (caller order) are sent; the rest are ignored.
1691
- */
1692
- listFundingOperations(opts: {
1693
- chainId?: number;
1694
- asset: string;
1695
- ids?: string[];
1696
- since?: Date;
1697
- }): Promise<FundingOperationRow[] | null>;
1698
1216
  private requireState;
1699
1217
  private requireChainId;
1700
1218
  private requireConnectedProvider;
1701
- private getPaidRpcClient;
1702
- /** Builds the default USDC batch callback for the connected wallet. */
1219
+ /**
1220
+ * Lazily builds (and caches) the default EIP-3009 sponsored deposit callback
1221
+ * used when the caller omits `depositCallback`. Wraps the connected EIP-1193
1222
+ * provider with viem `custom(provider)` to read token meta and sign the
1223
+ * `TransferWithAuthorization`, then POSTs to the sponsor API.
1224
+ */
1703
1225
  private getDefaultSponsoredCallback;
1704
- /** Builds the wallet-native sponsored calls callback for compatible paymasters. */
1226
+ /**
1227
+ * Lazily builds (and caches) the default Permit2 sponsored WETH deposit
1228
+ * callback used when the caller omits `depositCallback` for a WETH
1229
+ * deposit. Mirrors `getDefaultSponsoredCallback()` but signs a Permit2
1230
+ * `PermitTransferFrom` instead of an EIP-3009 authorization.
1231
+ */
1705
1232
  private getDefaultSponsoredCallsCallback;
1706
1233
  /**
1707
1234
  * Lazily builds (and caches) the default Permit2 sponsored WETH deposit
1708
1235
  * callback used when the caller omits `depositCallback` for a WETH deposit.
1709
1236
  * Mirrors `getDefaultSponsoredCallback()` but signs a Permit2
1710
- * single-use batch authorization instead of an EIP-3009 authorization.
1237
+ * `PermitTransferFrom` instead of an EIP-3009 authorization.
1711
1238
  */
1712
1239
  private getDefaultWethSponsoredCallback;
1713
1240
  private getAgent;
1714
- getActiveAgentIds(): AgentId[];
1715
1241
  private getActiveAgents;
1716
1242
  /**
1717
1243
  * Read the org's agent policy once and reuse it. fetchOrgAgentConfig never
@@ -1743,9 +1269,9 @@ declare class OwneySDK {
1743
1269
  * that support the given chainId (incompatible agents are silently skipped).
1744
1270
  * If provided, ALL specified agents must support the chainId or the call
1745
1271
  * throws before activating any agent.
1272
+ * @param options - Optional. `onAgentsSelected` fires once reads can start.
1746
1273
  */
1747
- activateAgent(chainId: number, agentId?: AgentId[], asset?: OwneySupportedTokens): Promise<void>;
1748
- private assertActivationSession;
1274
+ activateAgent(chainId: number, agentId?: AgentId[], options?: ActivateAgentOptions): Promise<void>;
1749
1275
  /**
1750
1276
  * Activate agents ONE AT A TIME, each followed by its org policy.
1751
1277
  *
@@ -1759,9 +1285,10 @@ declare class OwneySDK {
1759
1285
  * Serializing costs no real wall-clock: the user can only approve one prompt
1760
1286
  * at a time anyway.
1761
1287
  *
1762
- * Stop at the first failure so a canceled sign-in does not open another
1763
- * agent's wallet prompt. Report any earlier successes for diagnostics; the
1764
- * app discards the session when the complete sign-in does not succeed.
1288
+ * Every agent is attempted even if an earlier one fails, so one declined
1289
+ * signature can't deny the remaining agents their turn. The first failure is
1290
+ * rethrown (matching the previous `Promise.all` rejection) once all agents
1291
+ * have had a chance to activate.
1765
1292
  */
1766
1293
  private activateAgentsInTurn;
1767
1294
  /**
@@ -1772,8 +1299,7 @@ declare class OwneySDK {
1772
1299
  * @param options.asset - Asset symbol to deposit (e.g. "USDC")
1773
1300
  * @param options.depositCallback - Callback that performs the token transfer and returns a tx hash.
1774
1301
  * When agentId is omitted, this callback is invoked once per eligible agent with that agent's
1775
- * split amount and smart wallet address. Default sponsored deposits batch
1776
- * all shares into one signature; custom callbacks still run once per agent.
1302
+ * split amount and smart wallet address — expect multiple wallet prompts.
1777
1303
  * @param options.agentId - Optional explicit target. Otherwise split equally,
1778
1304
  * or fund remaining agents when a recovery deposit cannot meet every minimum.
1779
1305
  * @returns {OwneyDepositResult} for a single agent, or {OwneyMultiDepositResult} with per-agent results
@@ -1783,12 +1309,10 @@ declare class OwneySDK {
1783
1309
  * Invokes `agent.deposit` with the resolved sponsored callback, composing
1784
1310
  * two independent auto-recovery mechanisms:
1785
1311
  *
1786
- * 1. Missing Permit2 allowance outside the sponsored ERC-2612 path: when the
1787
- * app did not supply its own callback and the attempt fails with
1788
- * `PERMIT2_APPROVAL_REQUIRED`, this is the wallet's first Permit2 deposit
1789
- * for that token. Native Base/Arbitrum USDC uses gasless ERC-2612 approval in
1790
- * its sponsored deposit and never reaches this branch. Other tokens send
1791
- * the one-time user-paid Permit2 approval via `approvePermit2()` and
1312
+ * 1. Missing Permit2 allowance: when the app did not supply its own
1313
+ * callback and the attempt fails with `PERMIT2_APPROVAL_REQUIRED` on a
1314
+ * WETH deposit, this is the wallet's first gasless WETH deposit. We send
1315
+ * the one-time (user-paid) Permit2 approval via `approvePermit2()` and
1792
1316
  * retry the SAME sponsored attempt once. Bounded to one approval attempt
1793
1317
  * per call so a wallet/agent that keeps reporting the allowance as
1794
1318
  * missing can't loop forever. If `approvePermit2()` itself throws (e.g.
@@ -1809,7 +1333,6 @@ declare class OwneySDK {
1809
1333
  private depositWithFallback;
1810
1334
  private getMinDepositAmount;
1811
1335
  private splitDepositAmount;
1812
- private formatAgentName;
1813
1336
  private validateMinDepositAmount;
1814
1337
  /**
1815
1338
  * Whether the user already holds a non-zero balance with `agent` for the
@@ -1818,114 +1341,25 @@ declare class OwneySDK {
1818
1341
  * false, so the minimum is enforced as today.
1819
1342
  */
1820
1343
  private hasExistingBalance;
1344
+ /**
1345
+ * Guard an explicitly requested chain against one agent's own list.
1346
+ *
1347
+ * Only reachable when the caller passes `chainId` — the activated chain has
1348
+ * already been checked by `activateAgent`. Kept separate from
1349
+ * `validateAssetSupport` so "this agent is not on Ethereum" does not arrive
1350
+ * worded as "this agent does not support USDC".
1351
+ */
1352
+ private validateChainSupport;
1353
+ /**
1354
+ * Guard an explicitly requested chain before a fan-out.
1355
+ *
1356
+ * Without this the split simply produces no agents, and the caller is told
1357
+ * their amount "cannot activate every eligible agent" against a combined
1358
+ * minimum of 0 — an error about the amount when the chain is at fault.
1359
+ */
1360
+ private validateChainHasAgents;
1821
1361
  private validateAssetSupport;
1822
1362
  private getEligibleAgents;
1823
- /**
1824
- * Run owner-approved withdrawals before relayer-only withdrawals. Wallet
1825
- * approval is the only point at which the user can cancel the aggregate
1826
- * operation, so no relayer leg should commit before it has completed.
1827
- */
1828
- private orderAgentsForWithdrawal;
1829
- private isUserRejectedWithdrawal;
1830
- private captureReadScope;
1831
- /** Revalidate a saved transfer against the authenticated account and actual receipt. */
1832
- inspectFunding(evidence: FundingEvidence, direction: "deposit" | "withdraw", options?: {
1833
- balanceRefreshUntil?: number;
1834
- refreshBalance?: boolean;
1835
- requireAmountMatch?: boolean;
1836
- }): Promise<FundingEvidence>;
1837
- private noteFundingRefresh;
1838
- /**
1839
- * Re-arms an agent's balance refresh after a confirmed deposit or withdrawal
1840
- * the caller already verified (e.g. after a page reload, which loses the
1841
- * refresh the SDK started in memory). Same refresh as receipt recovery
1842
- * (`inspectFunding`), without a receipt read, and shared with it: once per
1843
- * movement (`txHash`) in this SDK session, unless that recovery came after
1844
- * its own deadline and so armed nothing. `until` bounds it (the agent caps
1845
- * it further). Returns false when the agent has no such refresh or `until`
1846
- * has passed; throws when not connected or on another chain. Never prompts.
1847
- */
1848
- refreshAgentBalanceAfterMovement(input: {
1849
- agentId: AgentId;
1850
- chainId: number;
1851
- token: OwneySupportedTokens;
1852
- txHash?: string;
1853
- until: number;
1854
- }): boolean;
1855
- /**
1856
- * Lists on-chain payout candidates for a withdrawal the provider accepted
1857
- * without a hash: ERC-20 `Transfer` logs on the evidence's token that reach
1858
- * the owner, from `max(fromBlock, cursor − 20)` to `latest − 3`, chunked.
1859
- * Discovery only: prove each candidate with
1860
- * `inspectFunding({ ...evidence, txHash }, "withdraw", { requireAmountMatch: true })`.
1861
- *
1862
- * `fromBlock` defaults to `evidence.payoutSearch.fromBlock`; without either
1863
- * (legacy records) the start is estimated from
1864
- * `withdrawalRequest.acceptedAt ?? submittedAt` minus 5 minutes. Pass the
1865
- * returned `scannedTo` back as `cursor` to scan only new blocks.
1866
- * Never prompts and never throws: null on any failure or scope mismatch.
1867
- */
1868
- findWithdrawalPayoutCandidates(evidence: FundingEvidence, opts?: {
1869
- fromBlock?: string;
1870
- cursor?: string;
1871
- submittedAt?: number;
1872
- }): Promise<WithdrawalPayoutScan | null>;
1873
- /** Resolve a saved sponsored-withdrawal ID without opening a wallet prompt. */
1874
- resolveSponsoredWithdrawalEvidence(evidence: FundingEvidence, options?: {
1875
- submittedAt?: number;
1876
- }): Promise<FundingEvidence>;
1877
- /** Recover an EIP-5792 deposit or payout using this account's exact batch ID. */
1878
- resolveWalletCallsFundingEvidence(evidence: FundingEvidence, direction: "deposit" | "withdraw"): Promise<FundingEvidence>;
1879
- /** Whether a foreground deposit can resume the same signed batch, never a
1880
- * fresh authorization. The batch rail independently rechecks the exact plan. */
1881
- canResumePendingDeposit(evidences: FundingEvidence[], amount: string): Promise<boolean>;
1882
- /** Whether a Permit2 deposit authorization can still execute and whether it
1883
- * did: `expired` when the finalized block is more than 300 s past
1884
- * `deadline` (chain time), `used` when the owner's Permit2 nonce bit is set
1885
- * at that block. Null when anything cannot be read. Never throws. */
1886
- checkDepositAuthorization(input: {
1887
- chainId: number;
1888
- owner: string;
1889
- token?: string;
1890
- permit2Nonce: string;
1891
- deadline: number;
1892
- }): Promise<{
1893
- expired: boolean;
1894
- used: boolean;
1895
- } | null>;
1896
- /** Drops the saved signed body of a hashless deposit the server may have
1897
- * been sending (`serverBroadcast` 'unknown'/true, no hash) once the app has
1898
- * settled it another way: by the ledger's hash or its expired deadline.
1899
- * Only the body with this Permit2 deadline and these exact shares is
1900
- * dropped, so it never resumes or blocks a different deposit. Never throws. */
1901
- discardSavedDepositBatch(evidences: FundingEvidence[]): Promise<boolean>;
1902
- /** Validate signed journal membership, never just a caller-supplied family ID. */
1903
- validateDepositReplacement(previous: FundingEvidence[], next: FundingEvidence[]): Promise<DepositReplacementValidation | undefined>;
1904
- /** Optional post-payout display proof; receipt verification and the provider
1905
- * adapter must agree before attaching it to this exact balance object. */
1906
- verifyWithdrawalBalance(evidence: FundingEvidence, balance: AgentBalance): Promise<AgentBalance>;
1907
- /** A display acknowledgement controls polling only; it never confirms a financial outcome. */
1908
- endFundingBalanceRefresh(evidence: FundingEvidence, read: AssetReadMetadata): boolean;
1909
- /** History lookup for receipt recovery; adapters may not authenticate or sign here. */
1910
- getFundingHistory(evidence: FundingEvidence, fromDate: string, options?: Pick<HistoryFilters, "cursor" | "toDate">): Promise<OwneyAgentHistory>;
1911
- recoverDepositRegistration(evidence: FundingEvidence): Promise<FundingEvidence>;
1912
- /** A Zyfai withdrawal's lifecycle by the id recorded on its evidence. Never signs,
1913
- * prompts or authenticates; `null` when unavailable or not this wallet's Zyfai withdrawal. */
1914
- getZyfaiWithdrawal(evidence: FundingEvidence): Promise<ZyfaiWithdrawalLifecycle | null>;
1915
- /** A Zyfai deposit's placement status by the id recorded on its evidence. Never signs,
1916
- * prompts or authenticates; `null` when unavailable or not this wallet's Zyfai deposit. */
1917
- getZyfaiDeposit(evidence: FundingEvidence): Promise<ZyfaiDepositPlacement | null>;
1918
- /** On-chain version and ownership status for this owner's Yieldseeker agent. */
1919
- getYieldseekerWalletStatus(asset: OwneySupportedTokens): Promise<YieldseekerWalletStatus | null>;
1920
- /** Deployment gate; an unavailable response keeps the current paid path. */
1921
- isYieldseekerWithdrawalSponsorshipAvailable(): Promise<boolean>;
1922
- isYieldseekerUpgradeSponsorshipAvailable(): Promise<boolean>;
1923
- private isYieldseekerSponsorshipAvailable;
1924
- /** Explicit V1-to-V2 upgrade, confirmed on chain before returning. */
1925
- upgradeYieldseekerWallet(asset: OwneySupportedTokens, gasMode?: "paid" | "sponsored"): Promise<{
1926
- txHash: viem.Hex;
1927
- status: YieldseekerWalletStatus;
1928
- }>;
1929
1363
  /** Lazily built so an app that never swaps pays nothing for it. */
1930
1364
  private swapApiClient?;
1931
1365
  private swapApi;
@@ -1970,23 +1404,77 @@ declare class OwneySDK {
1970
1404
  * would strand funds we might have been able to move.
1971
1405
  */
1972
1406
  /** ERC20 balance of the connected wallet, read through the wallet's own node. */
1407
+ /**
1408
+ * A read client pinned to `chainId`, over HTTP rather than the wallet.
1409
+ *
1410
+ * The swap rail has read this way from the start, and the reason is written
1411
+ * out at `buildSwapDeps`: a provider-backed client reads from whatever chain
1412
+ * the WALLET is on, which after a cross-chain swap is the source chain, not
1413
+ * the one the funds landed on. The deposit's own reads did not, so a Permit2
1414
+ * check for WETH on Arbitrum went to Base — where that address is not a
1415
+ * contract at all, so viem got "0x" back and threw "The contract function
1416
+ * 'allowance' returned no data".
1417
+ */
1418
+ private chainReader;
1973
1419
  private readTokenBalance;
1974
1420
  /** How much of `token` the wallet has already approved Permit2 to move. */
1975
1421
  private readTokenPermit2Allowance;
1976
1422
  /**
1977
- * Finish any user-paid Permit2 approval before measuring the deposit.
1978
- * Wallets can charge approval gas in the received token (ROUT-242/544).
1979
- * Cap the result at the swap arrival to preserve pre-existing wallet funds.
1980
- * Native Base/Arbitrum USDC uses sponsored ERC-2612; configured paymaster
1981
- * wallet calls also cover approval without spending the received tokens.
1423
+ * How much of a landed swap to actually deposit.
1424
+ *
1425
+ * The swap reports what ARRIVED, and the deposit used to be handed that
1426
+ * figure directly. It is the entire arrival, so there is no slack: anything
1427
+ * that spends the target asset between the two fails the deposit outright.
1428
+ *
1429
+ * Something does. A first WETH deposit needs a one-time Permit2 approval,
1430
+ * and that approval is a transaction. A wallet holding no native gas token -
1431
+ * the normal state of someone who just swapped everything INTO WETH - pays
1432
+ * for it out of the WETH. The deposit then asked for ~2e12 wei more than was
1433
+ * left and refused with DEPOSIT_INSUFFICIENT_BALANCE, under a wrapper saying
1434
+ * the funds were safe but unadded (ROUT-242).
1435
+ *
1436
+ * So the approval happens here, before the amount is settled, and the amount
1437
+ * comes from a read taken after it. Two things this deliberately is not:
1438
+ *
1439
+ * - It is not a balance sweep. `received` is a DELTA over the pre-swap
1440
+ * balance, so a wallet already holding WETH reads far above it; depositing
1441
+ * the balance would move funds the user never offered. The arrival is the
1442
+ * ceiling and the balance is only ever allowed to lower it.
1443
+ * - It does not touch USDC, which moves on signed typed data and so spends
1444
+ * nothing of the user's in between, nor a paymaster-configured client,
1445
+ * where the sponsor covers the transfer and Permit2 never applies.
1982
1446
  */
1983
1447
  private settleSwapDepositAmount;
1448
+ /**
1449
+ * Deposit a swap's output, retrying once at the balance the deposit saw.
1450
+ *
1451
+ * `settleSwapDepositAmount` approves and THEN reads, but the read and the
1452
+ * deposit's own pre-check can disagree: the approval is confirmed through
1453
+ * the wallet's node, the read goes to a pinned RPC, and gas paid in WETH
1454
+ * (MetaMask offers this to a wallet with no ETH) can land after either.
1455
+ * ROUT-618 failed that way with the settle step in place.
1456
+ *
1457
+ * The pre-check reports the balance it saw, and that is the authority, so
1458
+ * a shortfall is retried once at that figure. Only a small one: a node that
1459
+ * has not caught up can read near zero, and depositing that would leave the
1460
+ * rest of the swap stranded behind a "success".
1461
+ */
1462
+ private depositSwapOutput;
1984
1463
  private walletSeesBalance;
1985
1464
  /**
1986
1465
  * Runs a quoted swap. A named seam rather than an inline `executeSwap` call
1987
1466
  * so the deposit half of `swapAndDeposit` can be exercised on its own.
1988
1467
  */
1989
1468
  private runSwap;
1469
+ /**
1470
+ * Throws SWAP_INSUFFICIENT_GAS when the wallet cannot pay for this swap.
1471
+ *
1472
+ * Only the classic rail is ever refused: it is the one where the user sends
1473
+ * the transactions. Call it on a preview quote to warn BEFORE a withdrawal
1474
+ * moves anything — `withdrawAndSwap` repeats it on its own quote, but by
1475
+ * then the funds have already left the agent (ROUT-622).
1476
+ */
1477
+ checkSwapGas(quote: SwapQuote): Promise<void>;
1990
1478
  /**
1991
1479
  * The half of the swap deps that only ever talks to the routing API.
1992
1480
  *
@@ -2051,12 +1539,11 @@ declare class OwneySDK {
2051
1539
  * Every order is attempted even if an earlier one throws: they are unrelated
2052
1540
  * escrows, and one ending badly must not abandon the next one's secrets.
2053
1541
  * `unfinished` is not a verdict — the order may still settle, so unless the
2054
- * provider has confirmed full settlement or refund, its preimages are kept.
1542
+ * chain has said refunded or cancelled its preimages are kept.
2055
1543
  */
2056
1544
  resumePendingSwaps(options?: {
2057
1545
  onStage?: (orderHash: string, stage: SwapStage) => void;
2058
1546
  timeoutMs?: number;
2059
- orderHash?: string;
2060
1547
  }): Promise<{
2061
1548
  orderHash: string;
2062
1549
  status: "completed" | "unfinished";
@@ -2174,14 +1661,6 @@ declare class OwneySDK {
2174
1661
  /** Percent, classic rail only. Fusion+ prices through its auction. */
2175
1662
  slippage?: number;
2176
1663
  onSwapProgress?: (stage: SwapStage) => void;
2177
- /** Destination balance baseline, read after the swap and before deposit preparation. */
2178
- onBeforeDeposit?: () => Promise<void>;
2179
- onDepositProgress?: FundingProgress;
2180
- onBeforeDepositSubmission?: DepositOptions["onBeforeSubmission"];
2181
- /** Stop a stale foreground attempt before it prepares or sends another transaction. */
2182
- assertCurrent?: () => void;
2183
- /** Funding-ledger reference for this swap and its deposit. Generated when omitted. */
2184
- operationId?: string;
2185
1664
  }): Promise<{
2186
1665
  swap: {
2187
1666
  received: string;
@@ -2195,24 +1674,6 @@ declare class OwneySDK {
2195
1674
  * want this one; `swap.received` stays what it says it is.
2196
1675
  */
2197
1676
  deposited: string;
2198
- /** Funding-ledger reference shared by the swap and its deposit. */
2199
- operationId?: string;
2200
- }>;
2201
- /** Read-only confirmation of a saved pre-swap withdrawal. Never withdraws or swaps. */
2202
- recheckWithdrawalSwap(id: string): Promise<WithdrawSwapRecord>;
2203
- /** Explicit foreground continuation: spends verified payouts, never withdraws again. */
2204
- continueWithdrawalSwap(id: string, callbacks?: Pick<Parameters<OwneySDK["withdrawAndSwap"]>[0], "onSwapProgress" | "onOrderSubmitted" | "onWithdrawalProgress" | "assertCurrent">): Promise<{
2205
- withdraw: OwneyWithdrawResult | AgentWithdrawResult;
2206
- /** What actually arrived in the wallet, smallest unit of the agent's asset. */
2207
- withdrawn: string;
2208
- swap: {
2209
- received: string;
2210
- spent?: string;
2211
- orderHash?: string;
2212
- txHash?: string;
2213
- };
2214
- /** Funding-ledger reference shared by the withdrawal and the swap. */
2215
- operationId?: string;
2216
1677
  }>;
2217
1678
  /**
2218
1679
  * Withdraw from an agent and swap the proceeds into whatever the user wants
@@ -2226,9 +1687,10 @@ declare class OwneySDK {
2226
1687
  * Quoting before the tokens land would size the swap against a balance that
2227
1688
  * is not there yet.
2228
1689
  *
2229
- * Wait for each participating agent's owner payout and size one swap from
2230
- * their confirmed net amounts. A first wallet increase cannot establish
2231
- * that every payout arrived. Failed or incomplete withdrawals stop here.
1690
+ * The swap is therefore sized from the MEASURED arrival, exactly as the
1691
+ * deposit path sizes its deposit from the measured swap output. On a full
1692
+ * withdrawal there is no other number available — "MAX" has no figure until
1693
+ * the agent picks one.
2232
1694
  *
2233
1695
  * **Failure here is not symmetrical with the deposit path.** A failed
2234
1696
  * deposit-swap leaves the user holding what they started with. A failed
@@ -2248,7 +1710,6 @@ declare class OwneySDK {
2248
1710
  to: {
2249
1711
  chainId: number;
2250
1712
  symbol: string;
2251
- decimals?: number;
2252
1713
  };
2253
1714
  /** Human units ("10.5"). Omit to withdraw the full agent balance. */
2254
1715
  amount?: string;
@@ -2256,8 +1717,6 @@ declare class OwneySDK {
2256
1717
  /** Percent, classic rail only. Fusion+ prices through its auction. */
2257
1718
  slippage?: number;
2258
1719
  onSwapProgress?: (stage: SwapStage) => void;
2259
- /** Receipt evidence for the existing funding/recovery tracker. */
2260
- onWithdrawalProgress?: FundingProgress;
2261
1720
  /**
2262
1721
  * Fires once the order is with the relayer, before the watch.
2263
1722
  *
@@ -2283,32 +1742,18 @@ declare class OwneySDK {
2283
1742
  withdrawn: string;
2284
1743
  /** Smallest unit of the destination — the auction's start, not its floor. */
2285
1744
  expected: string;
2286
- spent?: string;
2287
- durable?: boolean;
2288
1745
  }) => void;
2289
1746
  /** How long to wait for the withdrawal to land before giving up on the swap. */
2290
1747
  arrivalTimeoutMs?: number;
2291
- /** UI ownership fence, checked before each financial continuation. */
2292
- assertCurrent?: () => void;
2293
- /** Used only by explicit continueWithdrawalSwap; it never sends another withdrawal. */
2294
- recoveryId?: string;
2295
- /**
2296
- * Funding-ledger reference for this withdrawal and swap. Generated when
2297
- * omitted; a continuation reuses the one saved on its record.
2298
- */
2299
- operationId?: string;
2300
1748
  }): Promise<{
2301
1749
  withdraw: OwneyWithdrawResult | AgentWithdrawResult;
2302
1750
  /** What actually arrived in the wallet, smallest unit of the agent's asset. */
2303
1751
  withdrawn: string;
2304
1752
  swap: {
2305
1753
  received: string;
2306
- spent?: string;
2307
1754
  orderHash?: string;
2308
1755
  txHash?: string;
2309
1756
  };
2310
- /** Funding-ledger reference shared by the withdrawal and the swap. */
2311
- operationId?: string;
2312
1757
  }>;
2313
1758
  /**
2314
1759
  * Withdraw funds from a specific agent, or all agents that support the active chain+asset if agentId is omitted.
@@ -2320,78 +1765,25 @@ declare class OwneySDK {
2320
1765
  * @returns {AgentWithdrawResult} for a single agent, or {OwneyWithdrawResult} with per-agent results
2321
1766
  */
2322
1767
  withdraw(options: WithdrawOptions): Promise<OwneyWithdrawResult | AgentWithdrawResult>;
2323
- /**
2324
- * Claims the cross-device hold for every agent in the plan. Returns the hold,
2325
- * or undefined when the reservation is off or the API is unavailable and the
2326
- * mode is fail-open. Throws only before anything is submitted:
2327
- * - `WITHDRAW_IN_PROGRESS` / `RESERVED_ELSEWHERE` on a 409;
2328
- * - `WITHDRAW_RESERVATION_UNAVAILABLE` when unavailable and fail-closed.
2329
- */
2330
- private reserveWithdrawal;
2331
- /**
2332
- * The cached Yieldseeker SIWE proof, when Yieldseeker is active for this
2333
- * SDK. Cache only: never prompts. Yieldseeker signs on Base, so a claim on
2334
- * another chain falls back to the Base proof (the server checks the
2335
- * signature, the address and its age, not the chain).
2336
- */
2337
- private peekReservationProof;
2338
- /**
2339
- * Releases or keeps each agent's hold when `withdraw()` ends. Never throws.
2340
- * - unattempted agents: `not_submitted`;
2341
- * - `confirmed` / definitively `failed` legs: released;
2342
- * - pending/unknown legs (Zyfai's hashless acknowledgement): kept;
2343
- * - a throw without submission evidence: `not_submitted`;
2344
- * - Zyfai "withdrawal already in progress": kept, dispatch `provider_in_progress`.
2345
- */
2346
- private settleWithdrawalReservation;
2347
- /**
2348
- * Releases a withdrawal reservation this browser still holds (the holder
2349
- * token is kept per operationId). Use it when the app learns the outcome of a
2350
- * kept hold, for example a Zyfai payout that arrived later. Never throws; a
2351
- * hold this SDK does not know about is left to the server's expiry.
2352
- */
2353
- releaseWithdrawalReservation(operationId: string, reason: ReservationReleaseReason, agents?: ReservationAgent[]): Promise<void>;
2354
- /**
2355
- * Reports a withdrawal step the app closed as never sent (a reload before its
2356
- * request was saved) as a failed ledger leg with `NOT_SUBMITTED`, so other
2357
- * devices and later recovery stop treating it as in flight. Refuses any step
2358
- * with a hash or a saved request. Never touches the hold; never throws.
2359
- */
2360
- reportWithdrawalNotSubmitted(operationId: string, evidence: FundingEvidence): Promise<void>;
2361
- /**
2362
- * Reports a withdrawal leg that was proven after its call ended (a hashless
2363
- * Zyfai payout found on chain or in history) to the funding ledger, then
2364
- * releases the withdrawal reservation this browser holds, as a fallback to
2365
- * the server's own release. Only evidence with a hash whose transfer and
2366
- * delivery are both confirmed is reported; anything else is ignored.
2367
- * The ledger PATCHes the existing operation (creating it only on a 404) and
2368
- * the server re-verifies the hash. Never throws.
2369
- */
2370
- reportWithdrawalRecovery(operationId: string, evidence: FundingEvidence): Promise<void>;
2371
- /**
2372
- * Reports a deposit leg that the app's recovery verified on chain after its
2373
- * call ended to the funding ledger. Only evidence whose transfer is confirmed
2374
- * with a transaction hash is reported; anything else is ignored. The ledger
2375
- * PATCHes the existing operation (creating it only on a 404) and the server
2376
- * re-verifies the hash. Deposits hold no reservation, so nothing is released.
2377
- * Never throws.
2378
- */
2379
- reportDepositRecovery(operationId: string, evidence: FundingEvidence): Promise<void>;
2380
- private withdrawFromAgents;
2381
- /** Read-only invalidation after new pool-deposit activity. Does not restart
2382
- * funding reconciliation, bypass cooldowns, or authorize a transaction. */
2383
- invalidateAllocationRead(scope: Pick<FundingEvidence, "agentId" | "walletAddress" | "chainId" | "token">): boolean;
2384
1768
  /**
2385
1769
  * Get the user's balances for a specific agent, or aggregated across all agents.
2386
1770
  * @param agentId - Optional. Agent to query. Omit for aggregated balances.
2387
1771
  * @returns {AgentBalance} for a single agent, or {OwneyBalances} with totalBalance and per-agent breakdown
2388
1772
  */
2389
- getBalances(agentId?: AgentId, options?: {
2390
- chainId?: number;
2391
- asset?: OwneySupportedTokens;
2392
- }): Promise<OwneyBalances | AgentBalance>;
2393
- /** Preserve failure objects for withdrawal recovery without changing public balance results. */
2394
- private readAggregatedBalances;
1773
+ /**
1774
+ * Withdraw every position the wallet holds, across chains and assets.
1775
+ *
1776
+ * `withdraw()` drains one asset on one chain, so this is N of those. It
1777
+ * deliberately does not stop at the first failure: the funds in the other
1778
+ * positions are just as withdrawable, and someone who asked for everything
1779
+ * is better served by three of four than by none. Each leg reports its own
1780
+ * outcome so the caller can name the ones that did not arrive; only a total
1781
+ * failure throws.
1782
+ *
1783
+ * @returns {OwneyWithdrawAllResult} one leg per position attempted.
1784
+ */
1785
+ withdrawAll(): Promise<OwneyWithdrawAllResult>;
1786
+ getBalances(agentId?: AgentId): Promise<OwneyBalances | AgentBalance>;
2395
1787
  /**
2396
1788
  * Get the user's on-chain earnings for a specific agent, or aggregated across all agents.
2397
1789
  * @param agentId - Optional. Agent to query. Omit for aggregated earnings.
@@ -2403,7 +1795,6 @@ declare class OwneySDK {
2403
1795
  * Agents without a refresh capability fall back to their current snapshot.
2404
1796
  */
2405
1797
  refreshEarnings(agentId?: AgentId): Promise<OwneyEarnings | AgentEarnings>;
2406
- private aggregateEarnings;
2407
1798
  /**
2408
1799
  * Get the weighted APY for the user's account over a time period.
2409
1800
  * When querying all agents, the total APY is a balance-weighted average.
@@ -2413,16 +1804,50 @@ declare class OwneySDK {
2413
1804
  * @returns {AccountAgentApy} for a single agent, or {OwneyAccountApy} with totalApy and per-agent breakdown
2414
1805
  */
2415
1806
  /**
2416
- * Daily cumulative earnings in the selected asset's units, backing the
2417
- * "recent earnings" subline. Each adapter uses its provider's earnings basis.
1807
+ * Daily cumulative NET earnings for the selected chain/asset, backing the
1808
+ * "recent earnings" subline. Net is computed as Zyfai's own
1809
+ * `lifetime + unrealized + current x 0.9`, so the figure reconciles with the
1810
+ * balance headline rather than reading ~11% high. (ROUT-452)
2418
1811
  *
2419
1812
  * Unlike getAccountApy this does NOT blend across agents: earnings are
2420
1813
  * summed, not weighted, and an agent that fails to report must not silently
2421
1814
  * subtract from the total. Without an agentId the series is the sum of the
2422
1815
  * agents that answered.
2423
1816
  */
2424
- getDailyEarnings({ agentId, days, tokenSymbol, }: DailyEarningsOptions): Promise<AccountDailyEarnings>;
2425
- getAccountApy({ agentId, days, tokenSymbol, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
1817
+ getDailyEarnings({ agentId, days, tokenSymbol, chainIds, }: DailyEarningsOptions): Promise<AccountDailyEarnings>;
1818
+ /**
1819
+ * The deposit-time pool catalogue (ROUT-569): every protocol with its
1820
+ * selectable pools (name, APY, TVL, link) for `asset` under `strategy`.
1821
+ * Defaults to the zyfai agent, the only one with pool customization today.
1822
+ */
1823
+ getPoolCatalog(params: {
1824
+ asset: OwneySupportedTokens;
1825
+ strategy: "conservative" | "aggressive" | "yieldmaxxing";
1826
+ agentId?: AgentId;
1827
+ }): Promise<PoolCatalogProtocol[]>;
1828
+ /**
1829
+ * Apply a user's deposit-time pool selection to their account (ROUT-569).
1830
+ * The request carries explicit pool choices plus the resulting strategy for
1831
+ * each asset reviewed in the deposit flow.
1832
+ */
1833
+ setPoolSelection(params: {
1834
+ selection: UserPoolSelectionRequest;
1835
+ agentId?: AgentId;
1836
+ }): Promise<void>;
1837
+ /**
1838
+ * The pool selection saved on the user's account (ROUT-650), so the Pools
1839
+ * step can show what applies now rather than the defaults. `pairs` and
1840
+ * `assets` say which protocol/chain lists and strategies to read.
1841
+ */
1842
+ getPoolSelection(params: {
1843
+ pairs: Array<{
1844
+ protocolId: string;
1845
+ chainId: number;
1846
+ }>;
1847
+ assets: Array<"USDC" | "WETH">;
1848
+ agentId?: AgentId;
1849
+ }): Promise<SavedPoolSelection>;
1850
+ getAccountApy({ agentId, days, tokenSymbol, chainId: scope, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
2426
1851
  /**
2427
1852
  * Get transaction history for a specific agent, or all agents.
2428
1853
  *
@@ -2456,17 +1881,14 @@ declare class OwneySDK {
2456
1881
  */
2457
1882
  ensureAutoSelectProtocols(asset: "USDC" | "WETH", agentId?: AgentId): Promise<boolean>;
2458
1883
  /**
2459
- * User-paid approval of Permit2 on the selected token for the active chain.
2460
- * Grants the maximum ERC20 allowance so later deposits do not require another
2461
- * approval. Resolves after one confirmation so the subsequent deposit attempt
2462
- * sees the new allowance. Deposit retries pass their captured chain id so a
2463
- * concurrent activation cannot redirect the approval to another network.
2464
- *
2465
- * @param requiredAmount Raw base-unit amount the pending deposit must cover.
2466
- * @param expectedChainId Chain captured by the deposit that requested approval.
1884
+ * One-time, user-paid approval of Permit2 on the sponsored WETH token for
1885
+ * the active chain. Required once per wallet per chain before gasless WETH
1886
+ * deposits; afterwards deposit() is signature-only. Resolves only after the
1887
+ * approval transaction is mined (1 confirmation), so a subsequent deposit()
1888
+ * will see the new allowance; throws if the transaction reverted.
2467
1889
  * @returns the approval transaction hash.
2468
1890
  */
2469
- approvePermit2(asset?: OwneySupportedTokens, requiredAmount?: bigint, expectedChainId?: OwneySupportedChainId, assertCurrent?: () => void): Promise<`0x${string}`>;
1891
+ approvePermit2(asset?: "WETH"): Promise<`0x${string}`>;
2470
1892
  /**
2471
1893
  * Get the agent's average APY performance over a time period. Does not require a wallet connection.
2472
1894
  * @param options - Contains agentId (optional) and days ("7D", "14D", or "30D")
@@ -2490,374 +1912,6 @@ declare class OwneySDK {
2490
1912
  getAllocationApy({ agentId, }?: AllocationApyOptions): Promise<OwneyAllocationApy>;
2491
1913
  }
2492
1914
 
2493
- type YieldseekerAuthToken = {
2494
- message: string;
2495
- signature: Hex;
2496
- };
2497
- type YieldseekerAuthDependencies = {
2498
- origin?: string;
2499
- now?: () => Date;
2500
- nonce?: () => string;
2501
- };
2502
-
2503
- type YieldseekerFetch = typeof fetch;
2504
-
2505
- type YieldseekerTransaction = {
2506
- from: `0x${string}`;
2507
- to: `0x${string}`;
2508
- data: `0x${string}`;
2509
- value: string;
2510
- chainId: number;
2511
- };
2512
-
2513
- type YieldseekerWalletStatus = {
2514
- agentWallet: Address;
2515
- owner: Address;
2516
- ownerPath: "eoa" | "smart";
2517
- asset: Address;
2518
- implementation: Address;
2519
- version: "v1" | "v2" | "unknown";
2520
- upgradeAvailable: boolean;
2521
- /** The factory, owner, base asset, and provider wallet mapping all agree. */
2522
- verified: boolean;
2523
- };
2524
-
2525
- type YieldseekerAgentOptions = {
2526
- baseUrl?: string;
2527
- routingApiBaseUrl?: string;
2528
- fetchFn?: YieldseekerFetch;
2529
- auth?: YieldseekerAuthDependencies;
2530
- /** Dedicated read transport; Base is used for receipt polling. */
2531
- rpcUrls?: RpcUrlsConfig;
2532
- /** Test seam for the wallet-submission/receipt boundary. */
2533
- transactionExecutor?: (state: ConnectionState, chainId: number, transaction: YieldseekerTransaction, onReceipt?: (receipt: viem.TransactionReceipt) => void) => Promise<Hex>;
2534
- /** Test seam for transactions submitted outside transactionExecutor. */
2535
- unwindReceiptWaiter?: (state: ConnectionState, chainId: number, transactionHash: Hex) => Promise<void>;
2536
- };
2537
- declare class YieldseekerAgent implements IAgent {
2538
- readonly id = "yieldseeker";
2539
- readonly balanceComposition: "tokens-plus-positions";
2540
- readonly withdrawalRequiresWalletApproval = true;
2541
- readonly supportedChainIds: readonly [8453];
2542
- readonly supportedAssets: readonly [{
2543
- readonly chainId: 8453;
2544
- readonly chain: "BASE";
2545
- readonly assets: readonly [{
2546
- readonly symbol: "USDC";
2547
- readonly minDepositAmount: "10000000";
2548
- }, {
2549
- readonly symbol: "WETH";
2550
- readonly minDepositAmount: "1";
2551
- }];
2552
- }];
2553
- private readonly api;
2554
- private readonly auth;
2555
- private readonly rpcUrls?;
2556
- private readonly owneyApiKey;
2557
- private readonly routingApiBaseUrl?;
2558
- private receiptClient?;
2559
- private readonly withdrawalVersionCache;
2560
- private readonly pendingWalletStatus;
2561
- /** Lowercase Agent Wallet -> when this instance's deploy request succeeded. */
2562
- private readonly recentDeployments;
2563
- private readonly pendingUpgrades;
2564
- private readonly transactionExecutor?;
2565
- private readonly unwindReceiptWaiter?;
2566
- private readonly agentContexts;
2567
- private readonly walletContexts;
2568
- private readonly agentAccountReads;
2569
- private readonly reportedAccounts;
2570
- private readonly missingSlots;
2571
- private readonly freshListReads;
2572
- private readonly knownContextKeys;
2573
- private readonly pendingSlotInvalidations;
2574
- private readonly balanceContexts;
2575
- private readonly balanceVaults;
2576
- private readonly users;
2577
- private readonly pendingAgents;
2578
- private readonly pendingWalletContexts;
2579
- private readonly readCache;
2580
- private readonly pendingReads;
2581
- private readGeneration;
2582
- private readonly portfolioVersions;
2583
- private readonly liquidityVersions;
2584
- private readonly snapshotFailures;
2585
- private readonly standardReadFailures;
2586
- private readonly endpointReadFailures;
2587
- private readonly reconcileUntil;
2588
- private readonly allocationRefresh;
2589
- /** Contexts whose next permitted snapshot read is forced once: a funding
2590
- * invalidation with a tx hash (receipt recovery, a re-armed refresh). */
2591
- private readonly forceNextSnapshot;
2592
- private readonly activityRefreshUntil;
2593
- private readonly snapshotMovements;
2594
- private readonly movementEpochs;
2595
- private readonly settlementChecks;
2596
- private ledgerAccess?;
2597
- private readonly ledgerReads;
2598
- /** contextKey -> movements this instance started settling (by tx hash) and how they refresh:
2599
- * awaiting the ledger, refreshed when ready (ledger), or on the timed backoff (legacy). */
2600
- private readonly localMovements;
2601
- /** contextKey -> tx hash -> refresh-when-ready state of a ledger movement. */
2602
- private readonly refreshPlans;
2603
- /** contextKey -> the agent's ledger movements from the latest ledger read. */
2604
- private readonly ledgerMovementCache;
2605
- /** Contexts whose next snapshot request is a refresh-when-ready force. */
2606
- private readonly readyForces;
2607
- private readonly serverBaselines;
2608
- private readonly snapshotHistory;
2609
- /** contextKey -> the history key its refresh plans persist forced times under. */
2610
- private readonly planHistoryKeys;
2611
- /** A ledger read slower than this counts as "no ledger information" for that read. */
2612
- private ledgerBudgetMs;
2613
- /** slotKey -> the last successful ledger rows and when they arrived. */
2614
- private readonly lastLedgerRows;
2615
- private readonly vaultOptions;
2616
- private readonly pendingVaultOptions;
2617
- private readonly assetApyStats;
2618
- private readonly pendingAssetApyStats;
2619
- constructor(owneyApiKey: string, options?: YieldseekerAgentOptions);
2620
- private getReceiptClient;
2621
- /** Reads the actual proxy implementation; Yieldseeker's API walletType is not a version check. */
2622
- getWalletStatus(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, useCachedV2?: boolean): Promise<YieldseekerWalletStatus | null>;
2623
- /** Reads (or reuses the 15-minute verified V2 hint for) this exact context's wallet. */
2624
- private readWalletStatus;
2625
- /**
2626
- * Deposits go only to a wallet whose identity is verified on chain (factory
2627
- * mapping, owner, base asset, FACTORY). The API key is public, so the wallet
2628
- * the provider API returned is not trusted on its own. V1 wallets still
2629
- * accept deposits: only identity is required, not the V2 implementation.
2630
- * A failed read fails closed (reason UNAVAILABLE): an unverified wallet never
2631
- * receives funds. Session changes keep their own NOT_CONNECTED error.
2632
- */
2633
- private assertDepositWalletVerified;
2634
- private rememberWalletStatus;
2635
- /** Explicit owner action. This never runs as a side effect of withdrawal. */
2636
- upgradeWallet(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, gasMode?: "paid" | "sponsored"): Promise<{
2637
- txHash: Hex;
2638
- status: YieldseekerWalletStatus;
2639
- }>;
2640
- disconnect(): Promise<void>;
2641
- activateAgent(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<void>;
2642
- deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback, onProgress?: FundingProgress, onBeforeSubmission?: (evidence: FundingEvidence) => void | Promise<void>): Promise<OwneyDepositResult>;
2643
- withdraw(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, amount?: string, onProgress?: FundingProgress, gasMode?: "auto" | "sponsored" | "paid", onBeforeSubmission?: FundingProgress, assertOperation?: () => void, submission?: {
2644
- operationId?: string;
2645
- }): Promise<AgentWithdrawResult>;
2646
- private withdrawInternal;
2647
- /** Fresh position amounts for withdrawal planning, net of reserved fees. */
2648
- getWithdrawableBalance(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, minimumAmount?: bigint): Promise<bigint>;
2649
- /**
2650
- * The cached SIWE proof, decoded, for the withdrawal reservation claim's
2651
- * owner proof. Only a proof already in the cache: this never prompts the
2652
- * wallet and never throws. Never log the result.
2653
- */
2654
- peekReservationProof(state: ConnectionState, chainId: number): YieldseekerAuthToken | undefined;
2655
- /** Recheck MAX without re-unwinding, paying out, or requesting a signature. */
2656
- verifyWithdrawalCompletion(state: ConnectionState, evidence: FundingEvidence): Promise<WithdrawalCompletion>;
2657
- private readVaultShares;
2658
- private validateWithdrawalPositions;
2659
- private withdrawalVaultHints;
2660
- private readWithdrawalPositions;
2661
- private resolveWithdrawalLiquidity;
2662
- getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
2663
- verifyWithdrawalBalance(state: ConnectionState, evidence: FundingEvidence, balance: AgentBalance): Promise<AssetReadMetadata | undefined>;
2664
- invalidateAllocationRead(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): void;
2665
- invalidateFundingRead(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number, txHash?: string): void;
2666
- endFundingBalanceRefresh(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
2667
- getFundingWallet(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;
2668
- hasExistingDepositFunds(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
2669
- getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
2670
- getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays, tokenSymbol?: string): Promise<AccountAgentApy>;
2671
- getDailyEarnings(state: ConnectionState, chainId: number, days: LookbackDays, tokenSymbol?: string): Promise<AccountDailyEarnings>;
2672
- getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
2673
- getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
2674
- getAgentApy(days: DailyApyDays, options?: AgentApyOptions): Promise<AgentApy>;
2675
- supportsAgentApyPeriod(days: DailyApyDays): boolean;
2676
- private loadAssetApyStats;
2677
- private loadVaultOptions;
2678
- private userKey;
2679
- /** One deposit/withdraw slot: owner, chain and asset. */
2680
- private slotKey;
2681
- /**
2682
- * One agent's portfolio state. Includes the agentId so duplicate or renamed
2683
- * agents for the same asset never share caches, versions or settlement.
2684
- */
2685
- private contextKey;
2686
- /**
2687
- * Context keys an asset-only call applies to: the selected agent when known,
2688
- * else every agent of the slot seen this session.
2689
- */
2690
- private slotContextKeys;
2691
- /**
2692
- * Apply an asset-only invalidation. Before any agent of the slot resolves,
2693
- * queue it so the first resolved agents still see it (as the slot-keyed
2694
- * state did before contexts were keyed by agentId).
2695
- */
2696
- private invalidateSlot;
2697
- /** Record the selected agent for a slot; queued invalidations are now settled. */
2698
- private selectContext;
2699
- private assertSession;
2700
- private cachedRead;
2701
- private agentListKey;
2702
- private listAgents;
2703
- /**
2704
- * The routing API's stored accounts for owner+chain, read once per session.
2705
- * Resolves null when unavailable (callers keep name matching) and never
2706
- * rejects. A failure is retried after a short window.
2707
- */
2708
- private agentAccounts;
2709
- /** Yieldseeker accounts for one slot (returned addresses are compared lowercase). */
2710
- private slotAccounts;
2711
- private agentFits;
2712
- /**
2713
- * The listed agent of the slot whose resolved wallet is in the
2714
- * highest-priority set of `priorities` (index 0 first). Hinted agentIds are
2715
- * resolved first and a hinted top-priority match ends the search; then other
2716
- * listed agents, at most YIELDSEEKER_WALLET_MATCH_LIMIT wallets in total.
2717
- */
2718
- private agentWithWallet;
2719
- /**
2720
- * chooseAgent, re-reading a cached list once (bypassing its cache) when the
2721
- * verified agent is missing. A slot still missing after that re-read is
2722
- * remembered for the list cache window, so later reads fail from the cached
2723
- * list without another re-read.
2724
- */
2725
- private chooseAgentRefreshing;
2726
- private isSlotMissing;
2727
- /**
2728
- * The agent that serves deposits and withdrawals for a slot (Ruling 23):
2729
- * 1. the listed fitting agent whose wallet is the verified account's wallet,
2730
- * whatever its name; the stored agentId is only a hint;
2731
- * 2. else a listed fitting agent whose wallet is a superseded account's wallet;
2732
- * 3. else the fitting agent named "owney" (first use, migration, or a
2733
- * verified wallet that is not a fitting listed agent);
2734
- * 4. else, with a verified account, throw YIELDSEEKER_AGENT_MISSING (never
2735
- * create); without one, undefined (the caller may create).
2736
- * Steps 1 and 2 share one search of at most YIELDSEEKER_WALLET_MATCH_LIMIT
2737
- * wallet reads. The account report then records the selected wallet; the
2738
- * server marks it superseded when it differs from the verified wallet.
2739
- */
2740
- private chooseAgent;
2741
- private isAgentMissing;
2742
- private agentMissing;
2743
- /**
2744
- * Fire-and-forget: record which agent serves this slot. Never awaited on the
2745
- * funds path and never throws; once per agent wallet and deployment state
2746
- * per session.
2747
- */
2748
- private reportAccount;
2749
- private contextForAgent;
2750
- private resolveUser;
2751
- private forgetUser;
2752
- private ensureAgent;
2753
- private findAgent;
2754
- private resolveAgent;
2755
- /** Create the slot's agent. Only reached when no stored or named agent matched. */
2756
- private createAgent;
2757
- /**
2758
- * The routing create lock refused the create: another tab or app owns or is
2759
- * creating this slot's agent. Re-read the accounts and the list (bypassing
2760
- * their caches) and select that agent, once more after 2 s if needed. A
2761
- * verified account is matched by wallet; otherwise the returned agentId is
2762
- * used. Never creates again.
2763
- */
2764
- private adoptConflictingAgent;
2765
- private loadPortfolio;
2766
- private loadActivityPortfolio;
2767
- private resolvePortfolioContexts;
2768
- private portfolioVersion;
2769
- /** Snapshot cache lifetime: the settlement backoff while a movement is being
2770
- * checked, otherwise the routine non-forced cadence. */
2771
- private portfolioCacheMs;
2772
- /** A pending movement inside its ten-minute window. */
2773
- private settlementWindow;
2774
- /** A pending movement inside its ten-minute window forces snapshots, unless
2775
- * every movement being settled is refreshed when ready through the ledger. */
2776
- private settling;
2777
- /** Start a new forced-check schedule, or keep the active one. */
2778
- private beginSettlement;
2779
- private snapshotMovement;
2780
- private advancePortfolioVersion;
2781
- private requestPortfolioSnapshot;
2782
- private snapshotPath;
2783
- /** True while `walletRequest` would refuse a read of `path`: this user's
2784
- * rate-limit cooldown or that endpoint's outage cooldown. */
2785
- private readCoolingDown;
2786
- private portfolioSnapshot;
2787
- private loadPortfolioContext;
2788
- private loadActivityContext;
2789
- private loadPortfolioParts;
2790
- private deployAgent;
2791
- setFundingLedgerAccess(access: AgentFundingLedgerAccess | undefined): void;
2792
- private historyKey;
2793
- /** Funding-ledger rows for this slot, cached 15 s. Never throws: null on any failure. */
2794
- private readLedger;
2795
- /**
2796
- * A ledger read within the read budget. On a timeout or failure, the last
2797
- * successful rows are reused if at most 60 s old (no hold flicker); older
2798
- * means null, i.e. today's behaviour.
2799
- */
2800
- private readLedgerBudgeted;
2801
- private ledgerMovementsFor;
2802
- /** Track a movement this instance is settling. With ledger access and a tx
2803
- * hash it awaits the ledger; otherwise it keeps the timed backoff. */
2804
- private trackLocalMovement;
2805
- /** Timed (legacy) entries end with their ten-minute window; ledger ones after the one-hour index window. */
2806
- private pruneLocalMovements;
2807
- private hasAwaitingMovement;
2808
- /** Every movement being settled here is (or may yet be) refreshed when ready through the ledger. */
2809
- private deferredToLedger;
2810
- /** A null ledger sends every local movement back to the timed backoff; a
2811
- * listed tx hash is refreshed when ready; an unlisted one after the grace too. */
2812
- private resolveLocalMovements;
2813
- /**
2814
- * Refresh when ready, before a portfolio read: read the ledger (cached) when
2815
- * an earnings read asks for it or a movement is being tracked, update each
2816
- * recent movement's plan, poll the provider's history (non-forced, 15 s
2817
- * cache) for un-indexed tx hashes, and mark the next snapshot as forced when
2818
- * a plan is due. Never throws.
2819
- */
2820
- private prepareLedgerRefresh;
2821
- /** Apply one ledger read to local movements and refresh plans. False when the ledger is unavailable. */
2822
- private applyLedgerRows;
2823
- private updateRefreshPlans;
2824
- /** Non-forced provider history read (15 s cache) to learn when a tx hash is indexed. */
2825
- private pollIndexing;
2826
- /** The forced snapshot about to be requested counts for every plan that is
2827
- * due. False (do not force) when none is. */
2828
- private noteReadyForce;
2829
- private recordSnapshotHistory;
2830
- private localHistory;
2831
- /** After a snapshot: if this SDK's own history shows every recent ledger
2832
- * movement in net deposits, no plan needs (more) forcing. */
2833
- private checkLocalBooking;
2834
- /** The newest server sample observed at or before `cutoff`, cached. Null when none or on failure. */
2835
- private serverBaseline;
2836
- /**
2837
- * Earnings hold (spec B2): while a recent ledger movement is not booked by
2838
- * the provider, report the last good `cumulativeYieldBase`. The balance is
2839
- * untouched. Any missing input (no ledger, no baseline) or failure returns
2840
- * the provider's value. Never throws.
2841
- */
2842
- private applyEarningsHold;
2843
- private refreshSnapshotAfterMovement;
2844
- private agentPath;
2845
- private walletRequest;
2846
- private providerRequest;
2847
- private mapApiError;
2848
- private submitTransaction;
2849
- private waitForReceipt;
2850
- private assertTransaction;
2851
- private assertAgent;
2852
- private isOwneyAgent;
2853
- private assetForAgent;
2854
- private isTransactionHash;
2855
- private assertChain;
2856
- private assertOptionalChain;
2857
- private assertAsset;
2858
- private invalidResponse;
2859
- }
2860
-
2861
1915
  declare class InvalidHistoryCursorError extends Error {
2862
1916
  readonly code: "invalid_cursor";
2863
1917
  constructor(message: string);
@@ -2899,6 +1953,23 @@ type OwneySIWXConfig = {
2899
1953
  */
2900
1954
  declare function createOwneySIWX(config: OwneySIWXConfig): SIWXConfig;
2901
1955
 
1956
+ /**
1957
+ * Ask the wallet ITSELF to switch networks, over WalletConnect.
1958
+ *
1959
+ * WalletConnect's provider answers `wallet_switchEthereumChain` locally when
1960
+ * the chain was approved at connect time: it moves its own default chain and
1961
+ * reports success without telling the wallet. MetaMask mobile then stays on
1962
+ * its network, keeps reporting it, and every guard downstream fails with
1963
+ * CHAIN_MISMATCH — after a swap, with the user's funds already moved (ROUT-727).
1964
+ * Sending the request through the session client reaches the wallet, which
1965
+ * shows a real "switch network" prompt; the client also deep-links the wallet
1966
+ * app open on mobile.
1967
+ *
1968
+ * Returns false when `provider` is not a WalletConnect session, so the caller
1969
+ * can fall back to an ordinary switch.
1970
+ */
1971
+ declare function switchWalletConnectChain(provider: unknown, chainId: number, timeoutMs?: number): Promise<boolean>;
1972
+
2902
1973
  /**
2903
1974
  * Persists cross-chain swap secrets so an in-flight order survives a reload.
2904
1975
  *
@@ -2917,7 +1988,6 @@ declare function createOwneySIWX(config: OwneySIWXConfig): SIWXConfig;
2917
1988
  */
2918
1989
  type StoredOrder = {
2919
1990
  orderHash: string;
2920
- walletAddress?: string;
2921
1991
  /** Preimages, one per fill. Index matters — fill N needs secret N. */
2922
1992
  secrets: string[];
2923
1993
  /** Chain the funds left from, so a resumed session can report it. */
@@ -2927,105 +1997,13 @@ type StoredOrder = {
2927
1997
  dstSymbol: string;
2928
1998
  dstChainId: number;
2929
1999
  amount: string;
2930
- /** Epoch ms, for ordering recovery records. */
2000
+ /** Epoch ms. Used to drop orders far past any plausible timelock. */
2931
2001
  createdAt: number;
2932
- /**
2933
- * A swap-deposit's deposit half, so a resume that finishes the swap can
2934
- * record it (ROUT-625). `received` is the quote's guaranteed minimum. Absent
2935
- * on plain swaps and on records written by an older SDK.
2936
- */
2937
- pendingDeposit?: {
2938
- received: string;
2939
- symbol: string;
2940
- chainId: number;
2941
- agentId?: string;
2942
- operationId?: string;
2943
- };
2944
- /**
2945
- * Our routing API accepted these secrets (part 5's opt-in handoff) and
2946
- * publishes them itself once 1inch is ready. Informational: this browser
2947
- * still publishes and resumes as before. Absent when no handoff was accepted.
2948
- */
2949
- serverSecrets?: true;
2950
2002
  };
2951
2003
  /**
2952
- * Every unresolved stored order, newest first.
2004
+ * Every stored order, newest first, dropping anything past MAX_AGE_MS.
2953
2005
  * Used on mount to resume orders the user left in flight.
2954
2006
  */
2955
- declare function listOrders(_now?: number): StoredOrder[];
2956
-
2957
- /**
2958
- * Capability flag (part 5): this SDK can hand a signed Fusion+ order's secrets
2959
- * to the routing API (`handoffSecrets`), which then publishes each one when
2960
- * 1inch is ready, even if this tab is gone. Older builds do not export this.
2961
- */
2962
- declare const FUSION_SECRET_SERVER_PUBLISH: 1;
2963
-
2964
- /**
2965
- * Non-blocking funding ledger reporter.
2966
- *
2967
- * Reports each funding operation (deposit / withdraw / swap) to the routing
2968
- * API's `/api/v1/funding/operations` endpoints so support can reconstruct what
2969
- * happened. Hard rule: reporting NEVER blocks or fails a funding action.
2970
- *
2971
- * - `start()` / `leg()` / `finish()` are synchronous and never throw.
2972
- * - Requests run on a per-operation promise chain, create first.
2973
- * - Every error is swallowed (visible only with debug logging on).
2974
- */
2975
- /** Set by tsup's `define`; "dev" when running from source. */
2976
- declare const SDK_VERSION: string;
2977
- type LedgerLegReport = {
2978
- legKey: string;
2979
- legKind: "agent" | "swap" | "approval";
2980
- agentType?: string;
2981
- agentWallet?: string;
2982
- rail?: string;
2983
- amountRaw?: string;
2984
- status?: "created" | "submitted" | "unknown" | "failed" | "confirmed";
2985
- txHash?: string;
2986
- userOpHash?: string;
2987
- callsId?: string;
2988
- orderHash?: string;
2989
- /** The provider's own id for this leg's request (Zyfai's v2 withdrawal id). */
2990
- providerRef?: string;
2991
- confirmedAmountRaw?: string;
2992
- blockNumber?: string;
2993
- errorCode?: string;
2994
- swap?: {
2995
- rail: "swap_classic" | "swap_fusion" | "swap_fusion_plus";
2996
- srcChainId: number;
2997
- dstChainId: number;
2998
- srcToken: string;
2999
- dstToken: string;
3000
- srcAmountRaw: string;
3001
- quotedDstAmountRaw?: string;
3002
- receivedDstAmountRaw?: string;
3003
- feeBps?: number;
3004
- feeBpsSource?: "measured" | "stated";
3005
- feeToken?: string;
3006
- };
3007
- };
3008
-
3009
- /** This SDK hands every Zyfai withdrawal request to the caller's
3010
- * `onBeforeSubmission` before sending it, and a failed checkpoint stops it.
3011
- * A caller that persisted nothing for a dead run can therefore conclude the
3012
- * request was never sent. Older builds do not export this. */
3013
- declare const ZYFAI_WITHDRAW_DISPATCH_CHECKPOINT: 1;
3014
-
3015
- /** Capability flag: this SDK opts in to the server sending an accepted
3016
- * sponsored deposit itself (prepare `serverBroadcast: true`) and reports such a
3017
- * deposit as pending, never "not sent". Older builds do not export this. */
3018
- declare const SPONSORED_DEPOSIT_SERVER_BROADCAST: 1;
3019
-
3020
- /** Capability flag: this SDK opts in to the server sending its signed sponsored
3021
- * Yieldseeker withdrawal userOp itself (`serverSubmit=1` on its own
3022
- * `eth_sendUserOperation`) and reports such a leg as pending, never "not sent".
3023
- * Older builds do not export this. */
3024
- declare const YIELDSEEKER_WITHDRAW_SERVER_SUBMIT: 1;
3025
-
3026
- /** Capability flag: this SDK has `reportDepositRecovery`, which reports a
3027
- * deposit leg the app's recovery verified on chain to the funding ledger.
3028
- * Older builds do not export this. */
3029
- declare const FUNDING_DEPOSIT_RECOVERY_REPORT: 1;
2007
+ declare function listOrders(now?: number): StoredOrder[];
3030
2008
 
3031
- 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, FUNDING_DEPOSIT_RECOVERY_REPORT, FUSION_SECRET_SERVER_PUBLISH, 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, SPONSORED_DEPOSIT_SERVER_BROADCAST, 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, YIELDSEEKER_WITHDRAW_SERVER_SUBMIT, YieldseekerAgent, type YieldseekerWalletStatus, ZYFAI_REGISTRATION_NOT_SENT_CODES, ZYFAI_SERVER_TASKS, ZYFAI_WITHDRAWAL_NOT_SENT_CODES, ZYFAI_WITHDRAW_DISPATCH_CHECKPOINT, type ZyfaiDepositPlacement, type ZyfaiRpcUrlsConfig, type ZyfaiWithdrawalLifecycle, clearWithdrawSwap, createOwneySIWX, listPendingDeposits, listOrders as listPendingSwaps, listWithdrawSwaps, saveWithdrawSwap, setOwneyDebug, subscribeWithdrawSwaps, updateWithdrawSwap };
2009
+ export { type AccountAgentApy, type AccountApyOptions, type AccountDailyEarnings, type ActivateAgentOptions, 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 SavedPoolSelection, 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, switchWalletConnectChain, updateWithdrawSwap };