@antseed/node 0.2.157 → 0.2.158

package/dist/payments/seller-payment-manager.js

@@ -1,4 +1,5 @@
 import { keccak256, verifyTypedData } from 'ethers';
+import { DEFAULT_TOP_UP_SETTLED_THRESHOLD_BPS } from '../types/protocol.js';
 import { ChannelsClient } from './evm/channels-client.js';
 import { SPENDING_AUTH_TYPES, RESERVE_AUTH_TYPES, makeChannelsDomain, encodeMetadata, ZERO_METADATA, } from './evm/signatures.js';
 import { debugLog, debugWarn } from '../utils/debug.js';
@@ -20,6 +21,10 @@ const DEFAULT_MIN_SETTLE_DELTA = BigInt(DEFAULT_MIN_SETTLE_DELTA_STR);
  * the wire when the close request arrives.
  */
 const CLOSE_CATCH_UP_WAIT_MS = 5_000;
+/** How long an auth only a mining top-up covers waits for it (outside the buyer lock). */
+const OVER_CEILING_AUTH_WAIT_MS = 30_000;
+/** Minimum gap between on-chain reads of one channel's deposit. */
+const RESERVE_REFRESH_MIN_INTERVAL_MS = 10_000;
 /** `retryAfterMs` hint returned with 'busy' / 'pending_auth' rejections. */
 const CLOSE_RETRY_AFTER_MS = 2_000;
 const TOP_UP_THRESHOLD_NOT_MET_SELECTOR = '0x1ea4506b';
@@ -89,6 +94,10 @@ export class SellerPaymentManager {
     _spent = new Map();
     /** channelId -> on-chain reserveMaxAmount (budget ceiling from ReserveAuth) */
     _reserveMax = new Map();
+    /** When each channel's ceiling was last checked against the chain (see refreshReserveMaxFromChain). */
+    _reserveRefreshedAt = new Map();
+    /** channelId -> on-chain ceiling read in progress, shared by concurrent callers */
+    _reserveRefreshes = new Map();
     /** channelId -> latest buyer-signed auth (both sigs + cumulative values + metadata) for settle/close */
     _latestAuth = new Map();
     /**
@@ -115,6 +124,13 @@ export class SellerPaymentManager {
      *  before a retry succeeds, we keep the most recent higher ceiling because it
      *  subsumes the older request. */
     _pendingTopUp = new Map();
+    /** Channels with a background topUp() running, and those asked for another meanwhile. */
+    _topUpsRunning = new Map();
+    _topUpsWanted = new Set();
+    /** channelId -> ceiling of the topUp() being submitted now. */
+    _topUpInFlight = new Map();
+    /** AntseedChannels TOP_UP_SETTLED_THRESHOLD_BPS, read once. */
+    _topUpThreshold = null;
     /** Channels that must not serve more paid work until closed/renegotiated. */
     _blockedChannels = new Set();
     /** channelId -> close waiting for in-flight requests (closeSessionWhenIdle). */
@@ -441,23 +457,34 @@ export class SellerPaymentManager {
         // delays the buyer's session-channel auths.
         const isOneOff = payload.oneOffRequestId != null || this._oneOffChannelIds.has(payload.channelId);
         const lockKey = isOneOff ? `${buyerPeerId}\n${payload.channelId.toLowerCase()}` : buyerPeerId;
-        const existing = this._buyerLocks.get(lockKey);
-        let result = 'rejected';
-        const lock = (existing ?? Promise.resolve()).then(async () => {
-            result = isOneOff
-                ? await this._handleOneOffSpendingAuth(buyerPeerId, payload, paymentMux)
-                : await this._handleSpendingAuthInner(buyerPeerId, payload, paymentMux, disconnectMarker);
-        });
-        const tail = lock.catch(() => { });
-        this._buyerLocks.set(lockKey, tail);
-        try {
-            await lock;
-        }
-        finally {
-            if (isOneOff && this._buyerLocks.get(lockKey) === tail)
-                this._buyerLocks.delete(lockKey);
+        const runLocked = async (allowTopUpWait) => {
+            const existing = this._buyerLocks.get(lockKey);
+            let outcome = 'rejected';
+            const lock = (existing ?? Promise.resolve()).then(async () => {
+                outcome = isOneOff
+                    ? await this._handleOneOffSpendingAuth(buyerPeerId, payload, paymentMux)
+                    : await this._handleSpendingAuthInner(buyerPeerId, payload, paymentMux, disconnectMarker, allowTopUpWait);
+            });
+            const tail = lock.catch(() => { });
+            this._buyerLocks.set(lockKey, tail);
+            try {
+                await lock;
+            }
+            finally {
+                if (isOneOff && this._buyerLocks.get(lockKey) === tail)
+                    this._buyerLocks.delete(lockKey);
+            }
+            return outcome;
+        };
+        let result = await runLocked(true);
+        if (result === 'awaiting-top-up') {
+            // Only a top-up that is mining covers this auth: wait for it with the
+            // lock released, so this buyer's other auths and requests keep moving,
+            // then judge the auth again against the new ceiling.
+            await this.waitForTopUp(payload.channelId, OVER_CEILING_AUTH_WAIT_MS);
+            result = await runLocked(false);
         }
-        return result;
+        return result === 'awaiting-top-up' ? 'rejected' : result;
     }
     /**
      * Wait for any in-flight SpendingAuth processing for this buyer to complete.
@@ -470,7 +497,7 @@ export class SellerPaymentManager {
             await pending;
         }
     }
-    async _handleSpendingAuthInner(buyerPeerId, payload, paymentMux, disconnectMarker) {
+    async _handleSpendingAuthInner(buyerPeerId, payload, paymentMux, disconnectMarker, allowTopUpWait = false) {
         const buyerEvmAddr = peerIdToAddress(buyerPeerId);
         try {
             const channelId = payload.channelId;
@@ -481,9 +508,26 @@ export class SellerPaymentManager {
                     `channel=${channelId.slice(0, 18)}...`);
                 return 'rejected';
             }
+            // The signature check below only proves the sender signed the auth, not
+            // that the channel is theirs. An auth from one buyer must never move
+            // another buyer's channel: it would raise what that buyer may spend
+            // with an authorization the contract cannot settle.
+            const owner = existingCumulative !== undefined ? this._channelStore.getChannel(channelId)?.peerId : undefined;
+            if (owner !== undefined && owner !== buyerPeerId) {
+                debugWarn(`[SellerPayment] Rejecting SpendingAuth for a channel another buyer owns: ` +
+                    `channel=${channelId.slice(0, 18)}... sender=${buyerPeerId.slice(0, 12)}...`);
+                return 'rejected';
+            }
             const { channels: channelsAddr } = await this._resolvedAddresses;
             const channelsDomain = makeChannelsDomain(this._config.chainId, channelsAddr);
             if (existingCumulative === undefined) {
+                // A channel this seller already closed stays closed: a lagging RPC
+                // node can still report it active, and recovering it would block the
+                // buyer's replacement channel. No chain read is needed to say so.
+                if (this._channelStore.getChannel(channelId)?.status === CHANNEL_STATUS.SETTLED) {
+                    debugLog(`[SellerPayment] SpendingAuth for closed channel ${channelId.slice(0, 18)}... — rejected`);
+                    return 'rejected';
+                }
                 const hasReserveFields = payload.reserveSalt != null
                     || payload.reserveMaxAmount != null
                     || payload.reserveDeadline != null;
@@ -585,48 +629,20 @@ export class SellerPaymentManager {
                     debugWarn(`[SellerPayment] Invalid top-up ReserveAuth signature: recovered=${recovered} expected=${buyerEvmAddr}`);
                     return 'rejected';
                 }
-                // Call topUp() on-chain — includes settle of current cumulative spend
-                const { amount: settleAmount, metadata: settleMetadata, sig: settleSig } = this._getSettleParams(channelId);
-                debugLog(`[SellerPayment] Top-up verified: channel=${channelId.slice(0, 18)}... ceiling ${currentReserveMax} → ${newMaxAmount} (settling cumulative=${settleAmount})`);
-                try {
-                    await this._channelsClient.topUp(this._signer, channelId, settleAmount, settleMetadata, settleSig, newMaxAmount, BigInt(topUpDeadline), payload.spendingAuthSig);
-                    // Update tracking
-                    this._hydratedChannelIds.delete(channelId);
-                    this._reserveMax.set(channelId, newMaxAmount);
-                    const session = this._channelStore.getChannel(channelId);
-                    if (session) {
-                        session.previousConsumption = newMaxAmount.toString(); // repurposed: stores reserveMax
-                        session.deadline = topUpDeadline;
-                        session.updatedAt = Date.now();
-                        this._channelStore.upsertChannel(session);
-                    }
-                    debugLog(`[SellerPayment] Top-up completed: channel=${channelId.slice(0, 18)}... new ceiling=${newMaxAmount}`);
-                }
-                catch (topUpErr) {
-                    const failureKind = this._classifyTopUpFailure(topUpErr);
-                    if (failureKind === 'retryable-threshold' || failureKind === 'retryable-tx-backpressure') {
-                        // TopUpThresholdNotMet is a timing/settlement race; tx backpressure
-                        // means the RPC/delegated-account queue is saturated. In both cases
-                        // keep the ReserveAuth pending and retry after a later SpendingAuth
-                        // instead of treating the active channel as permanently broken.
-                        const reason = failureKind === 'retryable-threshold' ? 'threshold not met' : 'transaction backpressure';
-                        debugWarn(`[SellerPayment] Top-up ${reason}: channel=${channelId.slice(0, 18)}... ` +
-                            `error=${this._formatError(topUpErr)} — ` +
-                            `deferring topUp (will retry after next SpendingAuth)`);
-                        this._storePendingTopUp(channelId, {
-                            newMaxAmount,
-                            deadline: topUpDeadline,
-                            reserveAuthSig: payload.spendingAuthSig,
-                        });
-                        return 'accepted';
-                    }
-                    debugWarn(`[SellerPayment] Top-up on-chain failed permanently: channel=${channelId.slice(0, 18)}... ` +
-                        `kind=${failureKind} error=${this._formatError(topUpErr)} — closing latest auth and rejecting topUp`);
-                    this._pendingTopUp.delete(channelId);
-                    this._blockedChannels.add(channelId);
-                    await this.settleSession(buyerPeerId);
-                    return 'rejected';
-                }
+                // The on-chain topUp() runs outside this per-buyer lock, once the
+                // contract will accept it: with Base's block time and RPC latency a
+                // topUp() takes seconds, and every auth and request for this buyer
+                // waits on the lock. Until it lands, serving uses the current ceiling.
+                debugLog(`[SellerPayment] Top-up verified: channel=${channelId.slice(0, 18)}... ceiling ${currentReserveMax} → ${newMaxAmount}`);
+                // A replay of the top-up being submitted right now adds nothing.
+                if (newMaxAmount <= (this._topUpInFlight.get(channelId) ?? 0n))
+                    return 'accepted';
+                this._storePendingTopUp(channelId, {
+                    newMaxAmount,
+                    deadline: topUpDeadline,
+                    reserveAuthSig: payload.spendingAuthSig,
+                });
+                this._scheduleTopUp(buyerPeerId, channelId);
                 return 'accepted';
             }
             else {
@@ -657,19 +673,32 @@ export class SellerPaymentManager {
                     this._acknowledgeRetainedChannel(buyerPeerId, channelId, paymentMux, disconnectMarker);
                     return 'accepted';
                 }
-                // Reject if buyer's cumulative doesn't cover what the seller has already spent
+                // An auth below what the seller has spent is still accepted: it only
+                // raises what the seller can claim. With requests in parallel, another
+                // one often finishes between a NeedAuth and the buyer's answer, so the
+                // answer is behind by then; rejecting it left the accepted amount stuck
+                // and parked every later request. Serving stays gated on spent <=
+                // accepted (see the request handler), so this never serves more.
                 const spent = this._spent.get(channelId) ?? 0n;
                 if (cumulativeAmount < spent) {
-                    debugWarn(`[SellerPayment] Rejecting underfunded SpendingAuth: ` +
+                    debugLog(`[SellerPayment] SpendingAuth behind spend, accepted: ` +
                         `cumulative=${cumulativeAmount} < spent=${spent} channel=${channelId.slice(0, 18)}...`);
-                    return 'rejected';
                 }
                 // Reject if cumulative exceeds the on-chain deposit. Pending topUps do
                 // not count here: until topUp() succeeds, the extra funds are not
                 // locked, and accepting an over-reserve SpendingAuth would leave the
                 // seller with an auth the contract cannot settle.
-                const currentReserveMax = this._reserveMax.get(channelId) ?? 0n;
+                let currentReserveMax = this._reserveMax.get(channelId) ?? 0n;
                 const pendingTopUpForCheck = this._pendingTopUp.get(channelId);
+                // The buyer signs up to a top-up it sent: while that topUp() is mining,
+                // ask the caller to wait for it (with the lock released) instead of
+                // rejecting an auth only the new ceiling covers.
+                if (allowTopUpWait && currentReserveMax > 0n && cumulativeAmount > currentReserveMax && this._topUpsRunning.has(channelId)) {
+                    return 'awaiting-top-up';
+                }
+                if (currentReserveMax > 0n && cumulativeAmount > currentReserveMax) {
+                    currentReserveMax = await this.refreshReserveMaxFromChain(channelId);
+                }
                 if (currentReserveMax > 0n && cumulativeAmount > currentReserveMax) {
                     debugWarn(`[SellerPayment] Rejecting SpendingAuth exceeding deposit ceiling: ` +
                         `cumulative=${cumulativeAmount} > reserveMax=${currentReserveMax}` +
@@ -696,12 +725,9 @@ export class SellerPaymentManager {
                     this._channelStore.upsertChannel(session);
                 }
                 debugLog(`[SellerPayment] Budget updated: channel=${channelId.slice(0, 18)}... cumulative=${cumulativeAmount}`);
-                // Retry any deferred topUp now that we have a higher settle amount.
-                const pendingTopUp = this._pendingTopUp.get(channelId);
-                if (pendingTopUp) {
-                    const { amount: retrySettleAmount, metadata: retryMetadata, sig: retrySig } = this._getSettleParams(channelId);
-                    await this._retryPendingTopUp(buyerPeerId, channelId, pendingTopUp, retrySettleAmount, retryMetadata, retrySig);
-                }
+                // A deferred topUp may be accepted now that more is authorized.
+                if (this._pendingTopUp.has(channelId))
+                    this._scheduleTopUp(buyerPeerId, channelId);
                 if (requiresReactivation
                     && await this._validateRetainedChannel(buyerPeerId, channelId, cumulativeAmount, disconnectMarker)) {
                     this._acknowledgeRetainedChannel(buyerPeerId, channelId, paymentMux, disconnectMarker);
@@ -1271,19 +1297,122 @@ export class SellerPaymentManager {
             debugWarn(`[SellerPayment] Failed to settle channel after ${reason}: ${err instanceof Error ? err.message : err}`);
         }
     }
+    /**
+     * Submit the channel's pending topUp in the background, one at a time per
+     * channel, and only once the authorized amount reaches the contract's
+     * settled threshold: anything earlier reverts TopUpThresholdNotMet after a
+     * full chain round trip. A request made while one is running is picked up
+     * when it finishes.
+     */
+    _scheduleTopUp(buyerPeerId, channelId) {
+        if (this._topUpsRunning.has(channelId)) {
+            this._topUpsWanted.add(channelId);
+            return;
+        }
+        // Starts after it is registered below, so every exit path finds itself there.
+        const run = Promise.resolve().then(async () => {
+            try {
+                for (;;) {
+                    this._topUpsWanted.delete(channelId);
+                    const pending = this._pendingTopUp.get(channelId);
+                    if (!pending)
+                        break;
+                    // A replay of a top-up that already landed: the contract would
+                    // reject it (TopUpAmountTooLow) and that would close the channel.
+                    if (pending.newMaxAmount <= (this._reserveMax.get(channelId) ?? 0n)) {
+                        this._pendingTopUp.delete(channelId);
+                        break;
+                    }
+                    if (!await this._topUpEligible(channelId, this._getSettleParams(channelId).amount)) {
+                        // A higher auth may have arrived during the threshold read.
+                        if (this._topUpsWanted.has(channelId))
+                            continue;
+                        break;
+                    }
+                    // Submit what is pending now: a higher ReserveAuth may have replaced
+                    // it during the read, and settle with the latest authorization.
+                    const latest = this._pendingTopUp.get(channelId);
+                    if (!latest)
+                        break;
+                    const { amount, metadata, sig } = this._getSettleParams(channelId);
+                    this._topUpInFlight.set(channelId, latest.newMaxAmount);
+                    let outcome;
+                    try {
+                        outcome = await this._retryPendingTopUp(buyerPeerId, channelId, latest, amount, metadata, sig);
+                    }
+                    finally {
+                        this._topUpInFlight.delete(channelId);
+                    }
+                    if (outcome === 'permanent-failure')
+                        break;
+                    // After a success, a higher top-up queued meanwhile goes next; after
+                    // a retryable failure, only a newer request retries it.
+                    if (outcome === 'succeeded' ? !this._pendingTopUp.has(channelId) : !this._topUpsWanted.has(channelId))
+                        break;
+                }
+            }
+            catch (err) {
+                debugWarn(`[SellerPayment] Background topUp failed: channel=${channelId.slice(0, 18)}... error=${this._formatError(err)}`);
+            }
+            finally {
+                if (this._topUpsRunning.get(channelId) === run)
+                    this._topUpsRunning.delete(channelId);
+                this._topUpsWanted.delete(channelId);
+            }
+        });
+        this._topUpsRunning.set(channelId, run);
+    }
+    /** Resolves once no background topUp() is running for the channel. */
+    async waitForTopUp(channelId, timeoutMs = Infinity) {
+        const deadline = Date.now() + timeoutMs;
+        while (this._topUpsRunning.has(channelId)) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return false;
+            let timer;
+            const timedOut = new Promise((resolve) => {
+                if (Number.isFinite(remaining))
+                    timer = setTimeout(resolve, remaining);
+            });
+            try {
+                await Promise.race([this._topUpsRunning.get(channelId), timedOut]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        return true;
+    }
+    /** Whether a background topUp() is being submitted for the channel now. */
+    isTopUpRunning(channelId) {
+        return this._topUpsRunning.has(channelId);
+    }
+    /** Whether topUp() settling `settleAmount` would pass the contract's settled threshold. */
+    async _topUpEligible(channelId, settleAmount) {
+        const deposit = this._reserveMax.get(channelId) ?? 0n;
+        if (deposit <= 0n)
+            return true;
+        const thresholdBps = await this._topUpThresholdBps();
+        return settleAmount * 10000n >= deposit * thresholdBps;
+    }
+    _topUpThresholdBps() {
+        this._topUpThreshold ??= this._channelsClient.getTopUpSettledThresholdBps()
+            .then((bps) => (bps > 0n && bps <= 10000n ? bps : DEFAULT_TOP_UP_SETTLED_THRESHOLD_BPS))
+            .catch((err) => {
+            debugWarn(`[SellerPayment] Failed to read the top-up threshold; using ${DEFAULT_TOP_UP_SETTLED_THRESHOLD_BPS}: ${this._formatError(err)}`);
+            this._topUpThreshold = null;
+            return DEFAULT_TOP_UP_SETTLED_THRESHOLD_BPS;
+        });
+        return this._topUpThreshold;
+    }
     async _retryPendingTopUp(buyerPeerId, channelId, pendingTopUp, settleAmount, settleMetadata, settleSig) {
-        this._pendingTopUp.delete(channelId);
+        // A higher ReserveAuth queued meanwhile stays pending for the next round.
+        if (this._pendingTopUp.get(channelId) === pendingTopUp)
+            this._pendingTopUp.delete(channelId);
         debugLog(`[SellerPayment] Retrying deferred topUp: channel=${channelId.slice(0, 18)}... settling=${settleAmount} newMax=${pendingTopUp.newMaxAmount}`);
         try {
             await this._channelsClient.topUp(this._signer, channelId, settleAmount, settleMetadata, settleSig, pendingTopUp.newMaxAmount, BigInt(pendingTopUp.deadline), pendingTopUp.reserveAuthSig);
-            this._reserveMax.set(channelId, pendingTopUp.newMaxAmount);
-            const topUpSession = this._channelStore.getChannel(channelId);
-            if (topUpSession) {
-                topUpSession.previousConsumption = pendingTopUp.newMaxAmount.toString();
-                topUpSession.deadline = pendingTopUp.deadline;
-                topUpSession.updatedAt = Date.now();
-                this._channelStore.upsertChannel(topUpSession);
-            }
+            this._updateReserveCeiling(channelId, pendingTopUp.newMaxAmount, pendingTopUp.deadline);
             debugLog(`[SellerPayment] Deferred topUp succeeded: channel=${channelId.slice(0, 18)}... new ceiling=${pendingTopUp.newMaxAmount}`);
             return 'succeeded';
         }
@@ -1298,8 +1427,12 @@ export class SellerPaymentManager {
             }
             debugWarn(`[SellerPayment] Deferred topUp failed permanently: channel=${channelId.slice(0, 18)}... ` +
                 `kind=${failureKind} error=${this._formatError(retryErr)} — closing latest auth and dropping pending topUp`);
+            // Stop admitting work at once, but close only after the requests already
+            // running on this channel have recorded their spend and been signed for.
             this._blockedChannels.add(channelId);
-            await this.settleSession(buyerPeerId);
+            if (this._channelStore.getActiveChannelByPeer(buyerPeerId, CHANNEL_ROLE.SELLER)?.sessionId === channelId) {
+                await this.closeSessionWhenIdle(buyerPeerId);
+            }
             return 'permanent-failure';
         }
     }
@@ -1524,6 +1657,24 @@ export class SellerPaymentManager {
         const session = this._channelStore.getActiveChannelByPeer(buyerPeerId, CHANNEL_ROLE.SELLER);
         return session != null && this._closingChannels.has(session.sessionId);
     }
+    /**
+     * Wait (up to `timeoutMs`) for the close in flight on the buyer's active
+     * channel. Returns whether it finished in time.
+     */
+    async waitForClosingChannel(buyerPeerId, timeoutMs) {
+        const session = this._channelStore.getActiveChannelByPeer(buyerPeerId, CHANNEL_ROLE.SELLER);
+        const closing = session ? this._closingChannels.get(session.sessionId) : undefined;
+        if (!closing)
+            return true;
+        let timer;
+        const timedOut = new Promise((resolve) => { timer = setTimeout(() => resolve(false), timeoutMs); });
+        try {
+            return await Promise.race([closing.then(() => true, () => true), timedOut]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     // ── Disconnect handling ───────────────────────────────────────
     onBuyerDisconnect(buyerPeerId) {
         const session = this._channelStore.getActiveChannelByPeer(buyerPeerId, CHANNEL_ROLE.SELLER);
@@ -1788,6 +1939,16 @@ export class SellerPaymentManager {
             while (this.hasInFlightRequests(buyerPeerId) && Date.now() < drainDeadline) {
                 await new Promise((resolve) => setTimeout(resolve, IDLE_CLOSE_POLL_MS));
             }
+            // The buyer's auths for the work just finished are still on the wire or
+            // queued behind the lock: close at them, not at what was accepted before.
+            await this.waitForPendingAuths(buyerPeerId);
+            const spent = this._spent.get(channelId) ?? 0n;
+            const ceiling = this._reserveMax.get(channelId) ?? 0n;
+            const claimable = ceiling > 0n && spent > ceiling ? ceiling : spent;
+            if ((this._acceptedCumulative.get(channelId) ?? 0n) < claimable) {
+                await this.awaitAcceptedAtLeast(channelId, claimable, CLOSE_CATCH_UP_WAIT_MS);
+                await this.waitForPendingAuths(buyerPeerId);
+            }
             if (this._channelStore.getActiveChannelByPeer(buyerPeerId, CHANNEL_ROLE.SELLER)?.sessionId !== channelId)
                 return;
             if ((this._acceptedCumulative.get(channelId) ?? 0n) > 0n || !this._blockedChannels.has(channelId)) {
@@ -1830,6 +1991,70 @@ export class SellerPaymentManager {
     getEffectiveReserveMax(sessionId) {
         return this.getReserveMax(sessionId);
     }
+    /**
+     * Raise the local reserve ceiling to the channel's on-chain deposit when it
+     * is behind: a top-up that confirmed while the seller stopped is not in the
+     * store. Checked before treating a channel as exhausted or rejecting an
+     * auth above the ceiling, so a stale ceiling never closes a channel early.
+     * Never lowers the ceiling. Concurrent callers share one read, and a channel
+     * is read at most once per interval. Returns the effective ceiling.
+     */
+    async refreshReserveMaxFromChain(channelId) {
+        return (await this._refreshReserveCeiling(channelId)).ceiling;
+    }
+    /**
+     * The effective ceiling, and whether it reflects a successful chain read
+     * (now or within the interval). A failed read returns the stored ceiling,
+     * unverified, and is retried on the next call.
+     */
+    _refreshReserveCeiling(channelId) {
+        const pending = this._reserveRefreshes.get(channelId);
+        if (pending)
+            return pending;
+        if (Date.now() - (this._reserveRefreshedAt.get(channelId) ?? 0) < RESERVE_REFRESH_MIN_INTERVAL_MS) {
+            return Promise.resolve({ ceiling: this.getEffectiveReserveMax(channelId), verified: true });
+        }
+        const refresh = this._readReserveMaxFromChain(channelId).then((verified) => {
+            if (verified) {
+                this._reserveRefreshedAt.set(channelId, Date.now());
+                if (this._reserveRefreshedAt.size > 1_024)
+                    this._reserveRefreshedAt.delete(this._reserveRefreshedAt.keys().next().value);
+            }
+            return { ceiling: this.getEffectiveReserveMax(channelId), verified };
+        }).finally(() => {
+            this._reserveRefreshes.delete(channelId);
+        });
+        this._reserveRefreshes.set(channelId, refresh);
+        return refresh;
+    }
+    /** Raise the ceiling to the on-chain deposit when it is behind. Returns whether the read succeeded. */
+    async _readReserveMaxFromChain(channelId) {
+        try {
+            const state = classifyOnChainChannel(await this._channelsClient.getSession(channelId));
+            const current = this._reserveMax.get(channelId) ?? 0n;
+            if (state.exists && state.status === 'active' && state.channel.deposit > current) {
+                this._updateReserveCeiling(channelId, state.channel.deposit);
+                debugLog(`[SellerPayment] Reserve ceiling ${current} behind on-chain deposit ${state.channel.deposit}: channel=${channelId.slice(0, 18)}...`);
+            }
+            return true;
+        }
+        catch (err) {
+            debugWarn(`[SellerPayment] Reserve ceiling refresh failed: channel=${channelId.slice(0, 18)}... error=${this._formatError(err)}`);
+            return false;
+        }
+    }
+    /** Set a channel's reserve ceiling in memory and in the store (and its deadline, after a top-up). */
+    _updateReserveCeiling(channelId, reserveMax, deadline) {
+        this._reserveMax.set(channelId, reserveMax);
+        const session = this._channelStore.getChannel(channelId);
+        if (!session)
+            return;
+        session.previousConsumption = reserveMax.toString(); // repurposed: stores reserveMax
+        if (deadline !== undefined)
+            session.deadline = deadline;
+        session.updatedAt = Date.now();
+        this._channelStore.upsertChannel(session);
+    }
     /** Whether this channel is blocked from serving more paid work. */
     isChannelBlocked(sessionId) {
         return this._blockedChannels.has(sessionId);
@@ -1914,7 +2139,22 @@ export class SellerPaymentManager {
             return reject('invalid_auth', err instanceof Error ? err.message : String(err));
         }
         if (buyerAuth) {
-            this._adoptBuyerCloseAuth(channelId, buyerAuth);
+            // An auth above the deposit cannot be settled: close() would revert and
+            // the channel would stay open. Keep the settleable auth instead.
+            const { ceiling, verified } = await this._refreshReserveCeiling(channelId);
+            if (ceiling > 0n && buyerAuth.cumulativeAmount > ceiling && !verified) {
+                // The stored ceiling may just be stale: never drop the buyer's auth on it.
+                return reject('close_failed', 'could not read the on-chain deposit to check the close authorization', {
+                    retryAfterMs: CLOSE_RETRY_AFTER_MS,
+                });
+            }
+            if (ceiling > 0n && buyerAuth.cumulativeAmount > ceiling) {
+                debugWarn(`[SellerPayment] Ignoring close auth above the deposit: cumulative=${buyerAuth.cumulativeAmount} ` +
+                    `> reserveMax=${ceiling} channel=${channelId.slice(0, 18)}...`);
+            }
+            else {
+                this._adoptBuyerCloseAuth(channelId, buyerAuth);
+            }
         }
         // Anything served but not yet signed for is unclaimable — ask for the
         // catch-up auth rather than closing at a loss.