@owney/sdk 0.7.25-beta.7 → 0.7.25-beta.9

package/dist/index.cjs

@@ -2905,10 +2905,11 @@ var YieldseekerApiClient = class {
       const payload = await response.json().catch(() => null);
       if (!response.ok) {
         const error = providerError(payload, `HTTP_${response.status}`);
+        const retryAfter = response.headers.get("Retry-After");
         throw new YieldseekerApiError(
           response.status,
           error.code,
-          error.fields
+          retryAfter ? { ...error.fields, headers: { "Retry-After": retryAfter } } : error.fields
         );
       }
       if (payload && typeof payload === "object" && payload.success === true && "data" in payload) {
@@ -3039,13 +3040,14 @@ function position(value, asset, baseAssetDecimals) {
     // differ from the underlying asset. Yieldseeker already converts it to
     // underlying base-asset units in `assetsBase`; pair that value with the
     // snapshot's corresponding `baseAssetDecimals` for display. Keep the raw
-    // share quantity separately because withdraw-from-position expects it.
+    // share quantity separate from the withdrawable underlying asset amount.
     amount: decimal(
       value.assetsBase,
       baseAssetDecimals,
       "yield positions"
     ),
     amountRaw: String(value.assetsRaw),
+    withdrawableAmountRaw: String(value.withdrawableAssetsRaw),
     apy: percent(option.riskAdjustedApy),
     tvl: Number(option.totalDepositsUsd),
     liquidity: Number(option.withdrawableDepositsUsd)
@@ -3374,8 +3376,12 @@ var YIELDSEEKER_USERNAME_PREFIX = "owney_";
 var YIELDSEEKER_USERNAME_RANDOM_LENGTH = 14;
 var YIELDSEEKER_USERNAME_CREATE_ATTEMPTS = 3;
 var YIELDSEEKER_YIELD_OPTIONS_CACHE_MS = 6e4;
-var YIELDSEEKER_AGENT_LIST_CACHE_MS = 6e4;
-var YIELDSEEKER_PORTFOLIO_CACHE_MS = 3e4;
+var YIELDSEEKER_AGENT_LIST_CACHE_MS = 12e4;
+var YIELDSEEKER_PORTFOLIO_CACHE_MS = 12e4;
+var YIELDSEEKER_SETTLEMENT_CACHE_MS = 5e3;
+var YIELDSEEKER_SETTLEMENT_ACTIVITY_CACHE_MS = 15e3;
+var YIELDSEEKER_READ_FAILURE_COOLDOWN_MS = 6e4;
+var YIELDSEEKER_SETTLEMENT_WINDOW_MS = 5 * 6e4;
 var YIELDSEEKER_ACTIVITY_CACHE_MS = 6e4;
 function generateYieldseekerUsername() {
   const suffix = globalThis.crypto.randomUUID().replaceAll("-", "").slice(0, YIELDSEEKER_USERNAME_RANDOM_LENGTH).toLowerCase();
@@ -3445,6 +3451,15 @@ var YieldseekerAgent = class {
   readCache = /* @__PURE__ */ new Map();
   pendingReads = /* @__PURE__ */ new Map();
   readGeneration = 0;
+  portfolioVersions = /* @__PURE__ */ new Map();
+  snapshotFailures = /* @__PURE__ */ new Map();
+  standardReadFailures = /* @__PURE__ */ new Map();
+  reconcileUntil = /* @__PURE__ */ new Map();
+  activityRefreshUntil = /* @__PURE__ */ new Map();
+  // null means a confirmed movement has no reliable baseline. Do not guess
+  // settlement; keep slow reconciliation after the fast window expires.
+  snapshotMovements = /* @__PURE__ */ new Map();
+  movementEpochs = /* @__PURE__ */ new Map();
   yieldOptions = /* @__PURE__ */ new Map();
   pendingYieldOptions = /* @__PURE__ */ new Map();
   constructor(owneyApiKey, options = {}) {
@@ -3475,6 +3490,13 @@ var YieldseekerAgent = class {
     this.pendingWalletContexts.clear();
     this.readCache.clear();
     this.pendingReads.clear();
+    this.portfolioVersions.clear();
+    this.snapshotFailures.clear();
+    this.standardReadFailures.clear();
+    this.reconcileUntil.clear();
+    this.activityRefreshUntil.clear();
+    this.snapshotMovements.clear();
+    this.movementEpochs.clear();
   }
   async activateAgent(state, chainId, asset) {
     this.assertChain(chainId);
@@ -3494,41 +3516,37 @@ var YieldseekerAgent = class {
       );
     }
     const context = await this.ensureAgent(state, chainId, asset);
+    const generation = this.readGeneration;
+    const movement = this.snapshotMovement(state, chainId, context, BigInt(amount));
     let txHash;
-    try {
-      if (depositCallback) {
-        provideDepositVerificationContext(depositCallback, {
-          agentId: "yieldseeker",
-          signature: await this.auth.getToken(state, chainId),
-          userId: context.user.userId,
-          yieldseekerAgentId: context.agent.agentId
-        });
-        txHash = await depositCallback(
-          context.wallet.walletAddress,
-          chainId,
-          amount
-        );
-        await this.waitForReceipt(state, chainId, txHash);
-      } else {
-        txHash = await this.submitTransaction(state, chainId, {
-          from: (0, import_viem7.getAddress)(state.walletAddress),
-          to: YIELDSEEKER_ASSET_METADATA[asset].address,
-          data: (0, import_viem7.encodeFunctionData)({
-            abi: import_viem7.erc20Abi,
-            functionName: "transfer",
-            args: [(0, import_viem7.getAddress)(context.wallet.walletAddress), BigInt(amount)]
-          }),
-          value: "0",
-          chainId
-        });
-      }
-    } finally {
-      await this.refreshSnapshotAfterMovement(
-        state,
+    if (depositCallback) {
+      provideDepositVerificationContext(depositCallback, {
+        agentId: "yieldseeker",
+        signature: await this.auth.getToken(state, chainId),
+        userId: context.user.userId,
+        yieldseekerAgentId: context.agent.agentId
+      });
+      txHash = await depositCallback(
+        context.wallet.walletAddress,
         chainId,
-        context,
-        "deposit"
+        amount
       );
+      await this.waitForReceipt(state, chainId, txHash);
+    } else {
+      txHash = await this.submitTransaction(state, chainId, {
+        from: (0, import_viem7.getAddress)(state.walletAddress),
+        to: YIELDSEEKER_ASSET_METADATA[asset].address,
+        data: (0, import_viem7.encodeFunctionData)({
+          abi: import_viem7.erc20Abi,
+          functionName: "transfer",
+          args: [(0, import_viem7.getAddress)(context.wallet.walletAddress), BigInt(amount)]
+        }),
+        value: "0",
+        chainId
+      });
+    }
+    if (this.readGeneration === generation) {
+      await this.refreshSnapshotAfterMovement(state, chainId, context, "deposit", movement);
     }
     return {
       txHash,
@@ -3556,6 +3574,9 @@ var YieldseekerAgent = class {
         this.id
       );
     }
+    const generation = this.readGeneration;
+    let confirmedMovement = false;
+    let settlement = null;
     try {
       const portfolio = await this.loadPortfolioContext(
         state,
@@ -3573,6 +3594,7 @@ var YieldseekerAgent = class {
       );
       const totalAvailable = idle + deployed;
       const requested = amount === void 0 ? totalAvailable : BigInt(amount);
+      const plannedMovement = this.snapshotMovement(state, chainId, context, -requested);
       if (requested > totalAvailable) {
         throw new OwneyError(
           "WITHDRAW_INSUFFICIENT_BALANCE",
@@ -3608,6 +3630,7 @@ var YieldseekerAgent = class {
           throw this.invalidResponse("position withdrawal");
         }
         await this.waitForReceipt(state, chainId, response.transactionHash);
+        confirmedMovement = true;
         remaining -= assetsRaw;
       }
       if (remaining > 0n) {
@@ -3632,18 +3655,23 @@ var YieldseekerAgent = class {
         value: "0",
         chainId
       });
+      confirmedMovement = true;
+      settlement = plannedMovement;
       return {
         txHash,
         type: amount === void 0 ? "full" : "partial",
         amount: requested.toString()
       };
     } finally {
-      await this.refreshSnapshotAfterMovement(
-        state,
-        chainId,
-        context,
-        "withdrawal"
-      );
+      if (confirmedMovement && this.readGeneration === generation) {
+        await this.refreshSnapshotAfterMovement(
+          state,
+          chainId,
+          context,
+          "withdrawal",
+          settlement
+        );
+      }
     }
   }
   async getBalances(state, chainId) {
@@ -3737,6 +3765,16 @@ var YieldseekerAgent = class {
   contextKey(state, chainId, asset) {
     return `${this.userKey(state, chainId)}:${asset}`;
   }
+  assertSession(generation, chainId, asset) {
+    if (this.readGeneration !== generation) {
+      throw new OwneyError(
+        "NOT_CONNECTED",
+        "Wallet session changed during the Yieldseeker request.",
+        { rpcSource: "agent-api", chainId, ...asset ? { asset } : {} },
+        this.id
+      );
+    }
+  }
   cachedRead(key2, ttlMs, read2) {
     const cached = this.readCache.get(key2);
     if (cached && cached.expiresAt > Date.now()) {
@@ -3746,7 +3784,7 @@ var YieldseekerAgent = class {
     if (pending) return pending;
     const generation = this.readGeneration;
     const request = Promise.resolve().then(read2).then((value) => {
-      if (this.readGeneration === generation) {
+      if (this.readGeneration === generation && this.pendingReads.get(key2) === request) {
         this.readCache.set(key2, {
           expiresAt: Date.now() + ttlMs,
           value
@@ -3794,6 +3832,7 @@ var YieldseekerAgent = class {
       chainId,
       `/users/${user.userId}/agents/${agent.agentId}/wallet`
     ).then((walletResponse) => {
+      this.assertSession(generation, chainId, asset);
       if (!walletResponse?.agentWallet || !(0, import_viem7.isAddress)(walletResponse.agentWallet.walletAddress)) {
         throw this.invalidResponse("agent wallet");
       }
@@ -3803,9 +3842,7 @@ var YieldseekerAgent = class {
         wallet: walletResponse.agentWallet,
         asset
       };
-      if (this.readGeneration === generation) {
-        this.agentContexts.set(key2, context);
-      }
+      this.agentContexts.set(key2, context);
       return context;
     });
     this.pendingWalletContexts.set(key2, request);
@@ -3827,6 +3864,7 @@ var YieldseekerAgent = class {
       return persisted;
     }
     const walletAddress = (0, import_viem7.getAddress)(state.walletAddress);
+    const generation = this.readGeneration;
     let user = null;
     try {
       const login = await this.providerRequest(
@@ -3873,6 +3911,7 @@ var YieldseekerAgent = class {
     if (!user || !/^[a-zA-Z0-9_-]{1,128}$/.test(user.userId)) {
       throw this.invalidResponse("wallet identity");
     }
+    this.assertSession(generation, chainId);
     const resolved = { userId: user.userId };
     this.users.set(key2, resolved);
     writeYieldseekerIdentity(state.walletAddress, chainId, resolved.userId);
@@ -3888,10 +3927,13 @@ var YieldseekerAgent = class {
     if (cached) return cached;
     const pending = this.pendingAgents.get(key2);
     if (pending) return pending;
+    const generation = this.readGeneration;
     const request = this.resolveAgent(state, chainId, asset, true).then(
       async (context) => {
+        this.assertSession(generation, chainId, asset);
         if (!context) throw this.invalidResponse("agent creation");
         await this.deployAgent(state, chainId, context);
+        this.assertSession(generation, chainId, asset);
         this.agentContexts.set(key2, context);
         return context;
       }
@@ -3900,20 +3942,25 @@ var YieldseekerAgent = class {
     try {
       return await request;
     } finally {
-      this.pendingAgents.delete(key2);
+      if (this.pendingAgents.get(key2) === request) this.pendingAgents.delete(key2);
     }
   }
   async findAgent(state, chainId, asset) {
     const key2 = this.contextKey(state, chainId, asset);
     const cached = this.agentContexts.get(key2);
     if (cached) return cached;
+    const generation = this.readGeneration;
     const context = await this.resolveAgent(state, chainId, asset, false);
+    this.assertSession(generation, chainId, asset);
     if (context) this.agentContexts.set(key2, context);
     return context;
   }
   async resolveAgent(state, chainId, asset, createIfMissing) {
+    const generation = this.readGeneration;
     const user = await this.resolveUser(state, chainId);
+    this.assertSession(generation, chainId, asset);
     const agents = await this.listAgents(state, chainId, user);
+    this.assertSession(generation, chainId, asset);
     const metadata = YIELDSEEKER_ASSET_METADATA[asset];
     let agent = agents.find(
       (candidate) => this.isOwneyAgent(candidate) && candidate.chainId === chainId && candidate.type === "vault" && candidate.assetAddress.toLowerCase() === metadata.address.toLowerCase()
@@ -3935,6 +3982,7 @@ var YieldseekerAgent = class {
           }
         }
       );
+      this.assertSession(generation, chainId, asset);
       agent = created?.agent;
       if (agent) {
         this.readCache.set(this.agentListKey(state, chainId), {
@@ -3950,8 +3998,11 @@ var YieldseekerAgent = class {
     return this.contextForAgent(state, chainId, user, agent, asset);
   }
   async loadPortfolio(state, chainId, options) {
+    const generation = this.readGeneration;
     const user = await this.resolveUser(state, chainId);
+    this.assertSession(generation, chainId);
     const agents = await this.listAgents(state, chainId, user);
+    this.assertSession(generation, chainId);
     const contexts = [];
     for (const agent of agents) {
       const asset = this.assetForAgent(agent);
@@ -3962,81 +4013,188 @@ var YieldseekerAgent = class {
       contexts.push(this.contextForAgent(state, chainId, user, agent, asset));
     }
     const resolvedContexts = await Promise.all(contexts);
+    this.assertSession(generation, chainId);
     return Promise.all(
       resolvedContexts.map(
         (context) => this.loadPortfolioContext(state, chainId, context, options)
       )
     );
   }
-  async loadPortfolioContext(state, chainId, context, options = {}) {
-    const contextKey = this.contextKey(state, chainId, context.asset);
-    const [snapshot, positions, historic, actions] = await Promise.all([
-      this.cachedRead(
-        `snapshot:${contextKey}`,
-        YIELDSEEKER_PORTFOLIO_CACHE_MS,
-        async () => {
-          const response = await this.walletRequest(
-            state,
-            chainId,
-            `${this.agentPath(context, "snapshot")}${query({
-              shouldOnlyUseRecentValue: true,
-              shouldAllowStaleOnError: true
-            })}`
-          );
-          if (!response?.agentSnapshot) {
-            throw this.invalidResponse("agent snapshot");
-          }
-          return response;
-        }
-      ),
-      this.cachedRead(
-        `positions:${contextKey}`,
-        YIELDSEEKER_PORTFOLIO_CACHE_MS,
-        async () => {
-          const response = await this.walletRequest(
-            state,
-            chainId,
-            this.agentPath(context, "yield-positions")
-          );
-          if (!Array.isArray(response?.yieldPositions)) {
-            throw this.invalidResponse("yield positions");
+  portfolioVersion(contextKey) {
+    return this.portfolioVersions.get(contextKey) ?? 0;
+  }
+  portfolioCacheMs(contextKey) {
+    return (this.reconcileUntil.get(contextKey) ?? 0) > Date.now() ? YIELDSEEKER_SETTLEMENT_CACHE_MS : YIELDSEEKER_PORTFOLIO_CACHE_MS;
+  }
+  snapshotMovement(state, chainId, context, delta) {
+    const key2 = this.contextKey(state, chainId, context.asset);
+    const previous = this.snapshotMovements.get(key2);
+    if (this.snapshotMovements.has(key2)) {
+      if (!previous || previous.delta > 0n !== delta > 0n) return null;
+      return {
+        ...previous,
+        epoch: this.movementEpochs.get(key2) ?? 0,
+        delta: previous.delta + delta,
+        expectedBalance: previous.expectedBalance + delta,
+        expectedNetDeposits: previous.expectedNetDeposits + delta
+      };
+    }
+    const cached = this.readCache.get(`snapshot:${key2}`);
+    if (!cached || cached.expiresAt <= Date.now()) return null;
+    const snapshot = cached.value.agentSnapshot;
+    if (snapshot.baseAssetDecimals !== YIELDSEEKER_ASSET_METADATA[context.asset].decimals) return null;
+    if (!/^-?\d+$/.test(snapshot.netDepositsBase) || !/^\d+$/.test(snapshot.totalValueBase)) return null;
+    return {
+      epoch: this.movementEpochs.get(key2) ?? 0,
+      delta,
+      decimals: snapshot.baseAssetDecimals,
+      expectedBalance: BigInt(snapshot.totalValueBase) + delta,
+      expectedNetDeposits: BigInt(snapshot.netDepositsBase) + delta
+    };
+  }
+  advancePortfolioVersion(contextKey) {
+    const version = this.portfolioVersion(contextKey) + 1;
+    this.portfolioVersions.set(contextKey, version);
+    this.snapshotFailures.delete(contextKey);
+    for (const kind of ["snapshot", "positions", "historic", "actions"]) {
+      const key2 = `${kind}:${contextKey}`;
+      this.readCache.delete(key2);
+      this.pendingReads.delete(key2);
+    }
+    return version;
+  }
+  requestPortfolioSnapshot(state, chainId, context, contextKey, version, generation, forceRefresh = false) {
+    return this.walletRequest(
+      state,
+      chainId,
+      `${this.agentPath(context, "snapshot")}${query(forceRefresh ? { shouldForceRefresh: true } : { shouldOnlyUseRecentValue: true, shouldAllowStaleOnError: true })}`
+    ).then((response) => {
+      if (!response?.agentSnapshot) {
+        throw this.invalidResponse("agent snapshot");
+      }
+      if (this.readGeneration === generation && this.portfolioVersion(contextKey) === version) {
+        this.snapshotFailures.delete(contextKey);
+        const movement = this.snapshotMovements.get(contextKey);
+        const snapshot = response.agentSnapshot;
+        if (movement && snapshot.baseAssetDecimals === movement.decimals && /^-?\d+$/.test(snapshot.netDepositsBase) && /^\d+$/.test(snapshot.totalValueBase)) {
+          const balance = BigInt(snapshot.totalValueBase);
+          const netDeposits = BigInt(snapshot.netDepositsBase);
+          const reconciled = movement.delta > 0n ? balance >= movement.expectedBalance && netDeposits >= movement.expectedNetDeposits : balance <= movement.expectedBalance && netDeposits <= movement.expectedNetDeposits;
+          if (reconciled) {
+            this.snapshotMovements.delete(contextKey);
+            this.reconcileUntil.delete(contextKey);
           }
-          return response;
         }
-      ),
-      options.historic ? this.cachedRead(
-        `historic:${contextKey}`,
-        YIELDSEEKER_ACTIVITY_CACHE_MS,
-        () => this.walletRequest(
-          state,
-          chainId,
-          this.agentPath(context, "wallet/historic-position")
-        )
-      ) : Promise.resolve(void 0),
-      options.actions ? this.cachedRead(
-        `actions:${contextKey}`,
-        YIELDSEEKER_ACTIVITY_CACHE_MS,
-        () => this.walletRequest(
+      }
+      return response;
+    }).catch((error) => {
+      if (this.readGeneration === generation && this.portfolioVersion(contextKey) === version) {
+        this.snapshotFailures.set(contextKey, {
+          retryAt: Date.now() + Math.max(YIELDSEEKER_READ_FAILURE_COOLDOWN_MS, rateLimitDelay(error) ?? 0),
+          error
+        });
+      }
+      throw error;
+    });
+  }
+  portfolioSnapshot(state, chainId, context, contextKey) {
+    const key2 = `snapshot:${contextKey}`;
+    const cached = this.readCache.get(key2);
+    if ((!cached || cached.expiresAt <= Date.now()) && !this.pendingReads.has(key2)) {
+      const failure = this.snapshotFailures.get(contextKey);
+      if (failure && failure.retryAt > Date.now()) throw failure.error;
+      this.advancePortfolioVersion(contextKey);
+    }
+    const version = this.portfolioVersion(contextKey);
+    const generation = this.readGeneration;
+    return {
+      version,
+      read: this.cachedRead(key2, this.portfolioCacheMs(contextKey), () => (
+        // Force only during the bounded post-transaction window. Keep unknown
+        // or unreconciled movements for verification, but do not let them turn
+        // routine polling into forced refreshes indefinitely.
+        this.requestPortfolioSnapshot(
           state,
           chainId,
-          this.agentPath(context, "actions")
+          context,
+          contextKey,
+          version,
+          generation,
+          this.snapshotMovements.has(contextKey) && (this.reconcileUntil.get(contextKey) ?? 0) > Date.now()
         )
-      ) : Promise.resolve(void 0)
-    ]);
-    if (!snapshot?.agentSnapshot) {
-      throw this.invalidResponse("agent snapshot");
-    }
-    if (!Array.isArray(positions?.yieldPositions)) {
-      throw this.invalidResponse("yield positions");
-    }
-    return {
-      ...context,
-      snapshot: snapshot.agentSnapshot,
-      positions: positions.yieldPositions,
-      ...historic?.position ? { historic: historic.position } : {},
-      ...actions?.actions ? { actions: actions.actions } : {}
+      ))
     };
   }
+  async loadPortfolioContext(state, chainId, context, options = {}) {
+    const contextKey = this.contextKey(state, chainId, context.asset);
+    const generation = this.readGeneration;
+    const assertSession = () => this.assertSession(generation, chainId, context.asset);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const { version, read: read2 } = this.portfolioSnapshot(state, chainId, context, contextKey);
+      try {
+        const snapshot = await read2;
+        assertSession();
+        if (this.portfolioVersion(contextKey) !== version) continue;
+        const [positions, historic, actions] = await Promise.all([
+          this.cachedRead(
+            `positions:${contextKey}`,
+            this.portfolioCacheMs(contextKey),
+            async () => {
+              const response = await this.walletRequest(
+                state,
+                chainId,
+                this.agentPath(context, "yield-positions")
+              );
+              if (!Array.isArray(response?.yieldPositions)) {
+                throw this.invalidResponse("yield positions");
+              }
+              return response;
+            }
+          ),
+          options.historic ? this.cachedRead(
+            `historic:${contextKey}`,
+            (this.activityRefreshUntil.get(contextKey) ?? 0) > Date.now() ? YIELDSEEKER_SETTLEMENT_ACTIVITY_CACHE_MS : YIELDSEEKER_ACTIVITY_CACHE_MS,
+            () => this.walletRequest(
+              state,
+              chainId,
+              this.agentPath(context, "wallet/historic-position")
+            )
+          ) : Promise.resolve(void 0),
+          options.actions ? this.cachedRead(
+            `actions:${contextKey}`,
+            (this.activityRefreshUntil.get(contextKey) ?? 0) > Date.now() ? YIELDSEEKER_SETTLEMENT_ACTIVITY_CACHE_MS : YIELDSEEKER_ACTIVITY_CACHE_MS,
+            () => this.walletRequest(
+              state,
+              chainId,
+              this.agentPath(context, "actions")
+            )
+          ) : Promise.resolve(void 0)
+        ]);
+        assertSession();
+        if (this.portfolioVersion(contextKey) !== version) continue;
+        if (!Array.isArray(positions?.yieldPositions)) {
+          throw this.invalidResponse("yield positions");
+        }
+        return {
+          ...context,
+          snapshot: snapshot.agentSnapshot,
+          positions: positions.yieldPositions,
+          ...historic?.position ? { historic: historic.position } : {},
+          ...actions?.actions ? { actions: actions.actions } : {}
+        };
+      } catch (error) {
+        assertSession();
+        if (this.portfolioVersion(contextKey) !== version) continue;
+        throw error;
+      }
+    }
+    throw new OwneyError(
+      "AGENT_API_ERROR",
+      "Yieldseeker portfolio changed during the read. Please retry.",
+      { rpcSource: "agent-api", chainId, asset: context.asset },
+      this.id
+    );
+  }
   async deployAgent(state, chainId, context) {
     if (context.wallet.initializedDate != null) return;
     const walletAddress = context.wallet.walletAddress.toLowerCase();
@@ -4053,42 +4211,52 @@ var YieldseekerAgent = class {
     }
     context.wallet = deployed.agentWallet;
   }
-  async refreshSnapshotAfterMovement(state, chainId, context, movement) {
+  async refreshSnapshotAfterMovement(state, chainId, context, movement, settlement) {
     const contextKey = this.contextKey(state, chainId, context.asset);
-    const invalidatePortfolio = () => {
-      for (const kind of ["snapshot", "positions", "historic", "actions"]) {
-        this.readCache.delete(`${kind}:${contextKey}`);
-      }
-    };
-    invalidatePortfolio();
+    this.reconcileUntil.set(contextKey, Date.now() + YIELDSEEKER_SETTLEMENT_WINDOW_MS);
+    this.activityRefreshUntil.set(contextKey, Date.now() + YIELDSEEKER_SETTLEMENT_WINDOW_MS);
+    const epoch = this.movementEpochs.get(contextKey) ?? 0;
+    this.snapshotMovements.set(contextKey, settlement?.epoch === epoch ? settlement : null);
+    this.movementEpochs.set(contextKey, epoch + 1);
+    const version = this.advancePortfolioVersion(contextKey);
+    const generation = this.readGeneration;
     try {
-      const response = await this.walletRequest(
-        state,
-        chainId,
-        `${this.agentPath(context, "snapshot")}${query({
-          shouldForceRefresh: true
-        })}`
+      await this.cachedRead(
+        `snapshot:${contextKey}`,
+        YIELDSEEKER_SETTLEMENT_CACHE_MS,
+        () => this.requestPortfolioSnapshot(state, chainId, context, contextKey, version, generation, true)
       );
-      if (!response?.agentSnapshot) {
-        throw this.invalidResponse("agent snapshot refresh");
-      }
     } catch (error) {
       console.warn(
         `[owney-sdk] Yieldseeker ${movement} snapshot refresh failed:`,
         error
       );
-    } finally {
-      invalidatePortfolio();
     }
   }
   agentPath(context, suffix) {
     return `/users/${context.user.userId}/agents/${context.agent.agentId}/${suffix}`;
   }
   async walletRequest(state, chainId, path, options = {}) {
+    const read2 = (options.method ?? "GET") === "GET";
+    const userKey = this.userKey(state, chainId);
+    if (read2) {
+      const failure = this.standardReadFailures.get(userKey);
+      if (failure && failure.retryAt > Date.now()) throw failure.error;
+      if (failure) this.standardReadFailures.delete(userKey);
+    }
+    const generation = this.readGeneration;
     try {
       return await this.providerRequest(state, chainId, path, options);
     } catch (error) {
-      throw this.mapApiError(error);
+      const mapped = this.mapApiError(error);
+      const delay = read2 ? rateLimitDelay(mapped) : void 0;
+      if (delay !== void 0 && this.readGeneration === generation) {
+        this.standardReadFailures.set(userKey, {
+          retryAt: Date.now() + Math.max(YIELDSEEKER_READ_FAILURE_COOLDOWN_MS, delay),
+          error: mapped
+        });
+      }
+      throw mapped;
     }
   }
   async providerRequest(state, chainId, path, options = {}) {
@@ -4385,16 +4553,16 @@ function projectAgentBalancesForAsset(agents, aggregated, chainId, asset, decima
         const positionChain = position2.chain.trim().toUpperCase();
         const matchesChain = positionChain === String(chainId) || targetChain !== void 0 && positionChain === targetChain;
         if (!matchesChain || position2.asset.toUpperCase() !== target) continue;
-        if (position2.amountRaw !== void 0) {
-          try {
-            balance += BigInt(position2.amountRaw);
-            continue;
-          } catch {
-          }
-        }
-        balance += (0, import_viem8.parseUnits)(position2.amount, decimals);
+        balance += position2.withdrawableAmountRaw !== void 0 ? BigInt(position2.withdrawableAmountRaw) : (0, import_viem8.parseUnits)(position2.amount, decimals);
       }
     }
+    const assetTotal = agentBalance?.assetBalances?.find(
+      (t) => t.chainId === chainId && t.asset.toUpperCase() === target
+    );
+    if (assetTotal) {
+      const total = (0, import_viem8.parseUnits)(assetTotal.amount, decimals);
+      if (total < balance) balance = total > 0n ? total : 0n;
+    }
     return { agent, balance };
   });
 }
@@ -6015,7 +6183,14 @@ var OwneySDK = class {
    * @returns {AgentWithdrawResult} for a single agent, or {OwneyWithdrawResult} with per-agent results
    */
   async withdraw(options) {
-    const { asset, amount, agentId } = options;
+    const { asset, amount, agentId, onAgentResult } = options;
+    const notifyAgentResult = (id, result) => {
+      try {
+        onAgentResult?.(id, result);
+      } catch (error) {
+        console.warn("Withdrawal result observer failed:", error);
+      }
+    };
     const state = this.requireState();
     const chainId = this.requireChainId();
     const token = asset;
@@ -6031,12 +6206,14 @@ var OwneySDK = class {
     if (agentId) {
       const agent = this.getAgent(agentId);
       this.validateAssetSupport(agent, chainId, asset);
-      return withFailureReporting(
+      const result = await withFailureReporting(
         this.apiKey,
         agent.id,
         () => agent.withdraw(state, chainId, token, amount),
         this.routingApiBaseUrl
       );
+      notifyAgentResult(agent.id, result);
+      return result;
     }
     const eligibleAgents = this.getEligibleAgents(chainId, asset);
     const withdrawalAgents = this.orderAgentsForWithdrawal(eligibleAgents);
@@ -6046,6 +6223,7 @@ var OwneySDK = class {
       for (const agent of withdrawalAgents) {
         try {
           results2[agent.id] = await agent.withdraw(state, chainId, token);
+          notifyAgentResult(agent.id, results2[agent.id]);
         } catch (err) {
           if (this.isUserRejectedWithdrawal(err)) throw err;
           console.error(`withdraw failed for agent "${agent.id}":`, err);
@@ -6143,6 +6321,7 @@ var OwneySDK = class {
           token,
           p.planned.toString()
         );
+        notifyAgentResult(p.agent.id, results[p.agent.id]);
       } catch (err) {
         if (this.isUserRejectedWithdrawal(err)) throw err;
         console.error(`withdraw failed for agent "${p.agent.id}":`, err);