@antseed/node 0.2.27 → 0.2.28

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

@@ -1,38 +1,77 @@
 import { randomBytes } from 'node:crypto';
-import { encodeBytes32String } from 'ethers';
-import { BaseEscrowClient } from './evm/escrow-client.js';
-import { identityToEvmWallet, identityToEvmAddress } from './evm/keypair.js';
-import { signSpendingAuth, makeEscrowDomain, buildAckMessage, signMessageEd25519, verifyMessageEd25519, buildReceiptMessage, } from './evm/signatures.js';
-import { bytesToHex, hexToBytes } from '../utils/hex.js';
+import { DepositsClient } from './evm/deposits-client.js';
+import { signSpendingAuth, signReserveAuth, makeChannelsDomain, computeMetadataHash, encodeMetadata, ZERO_METADATA, ZERO_METADATA_HASH, computeChannelId, } from './evm/signatures.js';
 import { debugLog, debugWarn } from '../utils/debug.js';
-const ZERO_SESSION_ID = '0x' + '0'.repeat(64);
+import { peerIdToAddress } from '../types/peer.js';
+import { estimateCostFromBytes } from './pricing.js';
+// ── Response cost header constants ───────────────────────────────
+const HEADER_COST = 'x-antseed-cost';
+const HEADER_INPUT_TOKENS = 'x-antseed-input-tokens';
+const HEADER_OUTPUT_TOKENS = 'x-antseed-output-tokens';
+/** Default tolerance: accept seller claims up to 1.4x buyer's bytes/4 estimate. */
+const DEFAULT_COST_TOLERANCE = 1.4;
+/** Fraction of reserve ceiling at which to signal a top-up is needed. */
+/** Must match or exceed contract's TOP_UP_SETTLED_THRESHOLD_BPS (85%). */
+const DEFAULT_TOPUP_THRESHOLD = 0.85;
 /**
  * Manages buyer-side payment sessions using EIP-712 SpendingAuth
- * with persistent session storage.
+ * with cumulative authorization, bytes/4 cost verification, and overdraft control.
  */
 export class BuyerPaymentManager {
     _identity;
     _signer;
-    _escrowClient;
+    _depositsClient;
     _config;
-    _sessionStore;
+    _channelStore;
     /** In-memory map of active confirmed sessions by seller peerId for fast lookups. */
     _confirmedPeers = new Set();
     /** Peers that explicitly rejected our spending auth. */
     _rejectedPeers = new Set();
-    _nonceCounter;
-    constructor(identity, config, sessionStore) {
+    /** sellerPeerId -> cumulative USDC amount in the latest SpendingAuth */
+    _cumulativeAmount = new Map();
+    /** sellerPeerId -> cumulative metadata for SpendingAuth */
+    _metadata = new Map();
+    /** sellerPeerId -> buyer-verified cumulative cost from bytes/4 */
+    _verifiedCost = new Map();
+    /** sellerPeerId -> pricing learned from 402 / peer metadata at session start */
+    _sessionPricing = new Map();
+    /** Cumulative response token totals per seller, tracked independently of signing metadata. */
+    _responseTokenTotals = new Map();
+    /** sellerPeerId -> current on-chain reserve ceiling (can grow with top-ups) */
+    _currentReserveCeiling = new Map();
+    /** sellerPeerId -> salt used in the current reserve */
+    _reserveSalt = new Map();
+    /** Cached EIP-712 domain — static for the lifetime of this manager. */
+    _channelsDomain;
+    constructor(identity, config, channelStore) {
         this._identity = identity;
         this._config = config;
-        this._signer = identityToEvmWallet(identity);
-        this._escrowClient = new BaseEscrowClient({
+        this._signer = identity.wallet;
+        this._depositsClient = new DepositsClient({
             rpcUrl: config.rpcUrl,
-            contractAddress: config.contractAddress,
+            contractAddress: config.depositsContractAddress,
             usdcAddress: config.usdcAddress,
         });
-        this._sessionStore = sessionStore;
-        // Restore nonce counter from persisted sessions to avoid duplicates across restarts
-        this._nonceCounter = sessionStore.getMaxNonce('buyer');
+        this._channelStore = channelStore;
+        this._channelsDomain = makeChannelsDomain(config.chainId, config.channelsContractAddress);
+        // Hydrate cumulative maps from persisted active sessions
+        this._hydrateFromStore();
+    }
+    /** Hydrate cumulative tracking maps from persisted active buyer sessions. */
+    _hydrateFromStore() {
+        const activeChannels = this._channelStore.getActiveChannelsByBuyer('buyer', this._identity.wallet.address);
+        for (const channel of activeChannels) {
+            const peerId = channel.peerId;
+            this._cumulativeAmount.set(peerId, BigInt(channel.authMax));
+            this._metadata.set(peerId, {
+                cumulativeInputTokens: BigInt(channel.tokensDelivered),
+                cumulativeOutputTokens: BigInt(channel.previousConsumption),
+                cumulativeLatencyMs: 0n,
+                cumulativeRequestCount: BigInt(channel.requestCount),
+            });
+            // verifiedCost and pricing are not persisted — start from 0 on hydration.
+            // This is conservative: the buyer treats all previously-signed amounts as unverified.
+        }
     }
     get signer() {
         return this._signer;
@@ -40,184 +79,519 @@ export class BuyerPaymentManager {
     setSigner(signer) {
         this._signer = signer;
     }
-    get escrowClient() {
-        return this._escrowClient;
+    get depositsClient() {
+        return this._depositsClient;
+    }
+    get _costTolerance() {
+        return this._config.costToleranceMultiplier ?? DEFAULT_COST_TOLERANCE;
+    }
+    _getCeiling(sellerPeerId) {
+        return this._currentReserveCeiling.get(sellerPeerId) ?? this._config.maxReserveAmountUsdc;
+    }
+    /** Clean up all in-memory state for a seller when the session ends. */
+    cleanupSession(sellerPeerId) {
+        this._cumulativeAmount.delete(sellerPeerId);
+        this._metadata.delete(sellerPeerId);
+        this._verifiedCost.delete(sellerPeerId);
+        this._sessionPricing.delete(sellerPeerId);
+        this._currentReserveCeiling.delete(sellerPeerId);
+        this._reserveSalt.delete(sellerPeerId);
+        this._confirmedPeers.delete(sellerPeerId);
+        this._rejectedPeers.delete(sellerPeerId);
+        this._responseTokenTotals.delete(sellerPeerId);
+    }
+    getActiveSession(sellerPeerId) {
+        return this._channelStore.getActiveChannelByPeerAndBuyer(sellerPeerId, 'buyer', this._identity.wallet.address);
+    }
+    retireSession(sellerPeerId, status, settledAmount) {
+        const session = this.getActiveSession(sellerPeerId);
+        if (session) {
+            this._channelStore.updateChannelStatus(session.sessionId, status, settledAmount !== undefined ? settledAmount.toString() : undefined);
+        }
+        this.cleanupSession(sellerPeerId);
+    }
+    canReplayReserveAuth(sellerPeerId) {
+        return this._reserveSalt.has(sellerPeerId);
+    }
+    async resendCurrentSpendingAuth(sellerPeerId, paymentMux) {
+        const session = this.getActiveSession(sellerPeerId);
+        if (!session) {
+            throw new Error(`[BuyerPayment] No active session for seller ${sellerPeerId.slice(0, 12)}...`);
+        }
+        const cumulativeAmount = this._cumulativeAmount.get(sellerPeerId) ?? BigInt(session.authMax);
+        const currentMeta = this._metadata.get(sellerPeerId) ?? ZERO_METADATA;
+        const metadataHashHex = computeMetadataHash(currentMeta);
+        const encodedMetadata = encodeMetadata(currentMeta);
+        const metadataMsg = {
+            channelId: session.sessionId,
+            cumulativeAmount,
+            metadataHash: metadataHashHex,
+        };
+        const spendingAuthSig = await signSpendingAuth(this._signer, this._channelsDomain, metadataMsg);
+        paymentMux.sendSpendingAuth({
+            channelId: session.sessionId,
+            cumulativeAmount: cumulativeAmount.toString(),
+            metadataHash: metadataHashHex,
+            metadata: encodedMetadata,
+            spendingAuthSig,
+        });
+        return session.sessionId;
+    }
+    async resendReserveAuth(sellerPeerId, paymentMux) {
+        const session = this.getActiveSession(sellerPeerId);
+        const salt = this._reserveSalt.get(sellerPeerId);
+        if (!session || !salt) {
+            throw new Error(`[BuyerPayment] No replayable reserve for seller ${sellerPeerId.slice(0, 12)}...`);
+        }
+        // Force a fresh AuthAck after replaying the reserve path.
+        this._confirmedPeers.delete(sellerPeerId);
+        const maxAmount = this._currentReserveCeiling.get(sellerPeerId) ?? this._config.maxReserveAmountUsdc;
+        const deadline = Math.floor(Date.now() / 1000) + this._config.defaultAuthDurationSecs;
+        const reserveMsg = {
+            channelId: session.sessionId,
+            maxAmount,
+            deadline: BigInt(deadline),
+        };
+        const reserveAuthSig = await signReserveAuth(this._signer, this._channelsDomain, reserveMsg);
+        paymentMux.sendSpendingAuth({
+            channelId: session.sessionId,
+            cumulativeAmount: session.authMax,
+            metadataHash: ZERO_METADATA_HASH,
+            metadata: encodeMetadata(this._metadata.get(sellerPeerId) ?? ZERO_METADATA),
+            spendingAuthSig: reserveAuthSig,
+            reserveSalt: salt,
+            reserveMaxAmount: maxAmount.toString(),
+            reserveDeadline: deadline,
+        });
+        return session.sessionId;
     }
     // ── Spending Authorization ────────────────────────────────────
     /**
-     * Sign and send an EIP-712 SpendingAuth to a seller.
-     * Loads the latest session to build the proof chain.
+     * Sign and send an initial EIP-712 SpendingAuth to a seller.
+     * The initial cumulativeAmount is set to the seller's minBudgetPerRequest.
+     *
+     * @param pricing Token pricing from the seller's 402 / peer metadata.
      */
-    async authorizeSpending(sellerPeerId, sellerEvmAddr, paymentMux, maxAmount) {
-        const amount = maxAmount ?? this._config.defaultMaxAmountUsdc;
+    async authorizeSpending(sellerPeerId, paymentMux, minBudgetPerRequest, reserveAmountOrPricing, pricingArg) {
+        const sellerEvmAddr = peerIdToAddress(sellerPeerId);
+        const reserveAmount = typeof reserveAmountOrPricing === 'bigint'
+            ? reserveAmountOrPricing
+            : this._config.maxReserveAmountUsdc;
+        const pricing = typeof reserveAmountOrPricing === 'bigint'
+            ? pricingArg
+            : reserveAmountOrPricing;
+        // Budget validation: reject if seller demands more than buyer's overdraft limit
+        if (minBudgetPerRequest > this._config.maxPerRequestUsdc) {
+            debugWarn(`[BuyerPayment] Seller ${sellerPeerId.slice(0, 12)}... minBudgetPerRequest=${minBudgetPerRequest} exceeds maxPerRequestUsdc=${this._config.maxPerRequestUsdc} — not authorizing`);
+            return '';
+        }
         // Clear confirmation state so we wait for a fresh AuthAck on the new session
         this._confirmedPeers.delete(sellerPeerId);
-        // Load latest session to build proof chain.
-        // Only chain if the session is settled or active-with-delivery (the seller
-        // will settle it on-chain before reserving the new one).
-        // Fall back to first-sign for timed-out/ghost sessions.
-        const latestSession = this._sessionStore.getLatestSession(sellerPeerId, 'buyer');
-        const canChain = latestSession
-            && latestSession.status !== 'timeout'
-            && latestSession.status !== 'ghost'
-            && BigInt(latestSession.tokensDelivered) > 0n;
-        const previousConsumption = canChain
-            ? BigInt(latestSession.tokensDelivered)
-            : 0n;
-        const previousSessionId = canChain
-            ? latestSession.sessionId
-            : ZERO_SESSION_ID;
-        // Generate a 32-byte session ID
-        const sessionIdBytes = randomBytes(32);
-        const sessionId = '0x' + sessionIdBytes.toString('hex');
-        const nonce = ++this._nonceCounter;
+        // Store pricing for this session
+        if (pricing) {
+            this._sessionPricing.set(sellerPeerId, pricing);
+        }
+        // Generate random salt and compute deterministic channelId
+        const salt = '0x' + randomBytes(32).toString('hex');
+        const buyerEvmAddr = this._identity.wallet.address;
+        const channelId = computeChannelId(buyerEvmAddr, sellerEvmAddr, salt);
         const deadline = Math.floor(Date.now() / 1000) + this._config.defaultAuthDurationSecs;
-        debugLog(`[BuyerPayment] authorizeSpending: session=${sessionId.slice(0, 18)}... seller=${sellerPeerId.slice(0, 12)}... amount=${amount}`);
-        // Sign EIP-712 SpendingAuth
-        const domain = makeEscrowDomain(this._config.chainId, this._config.contractAddress);
-        const msg = {
-            seller: sellerEvmAddr,
-            sessionId,
-            maxAmount: amount,
-            nonce,
-            deadline,
-            previousConsumption,
-            previousSessionId,
+        debugLog(`[BuyerPayment] authorizeSpending: channel=${channelId.slice(0, 18)}... seller=${sellerPeerId.slice(0, 12)}... amount=${minBudgetPerRequest}`);
+        // Sign ReserveAuth — binds channelId, maxAmount, deadline on-chain
+        const channelsDomain = this._channelsDomain;
+        const maxAmount = reserveAmount;
+        const reserveMsg = {
+            channelId,
+            maxAmount,
+            deadline: BigInt(deadline),
         };
-        const buyerSig = await signSpendingAuth(this._signer, domain, msg);
-        const buyerEvmAddr = identityToEvmAddress(this._identity);
+        const reserveAuthSig = await signReserveAuth(this._signer, channelsDomain, reserveMsg);
+        // Initialize state for this session
+        this._cumulativeAmount.set(sellerPeerId, minBudgetPerRequest);
+        this._metadata.set(sellerPeerId, { ...ZERO_METADATA });
+        this._verifiedCost.set(sellerPeerId, 0n);
+        this._currentReserveCeiling.set(sellerPeerId, maxAmount);
+        this._reserveSalt.set(sellerPeerId, salt);
         // Store session
         const now = Date.now();
         const session = {
-            sessionId,
+            sessionId: channelId,
             peerId: sellerPeerId,
             role: 'buyer',
-            sellerEvmAddr,
-            buyerEvmAddr,
-            nonce,
-            authMax: amount.toString(),
+            sellerEvmAddr: peerIdToAddress(sellerPeerId),
+            buyerEvmAddr: this._identity.wallet.address,
+            nonce: 0,
+            authMax: minBudgetPerRequest.toString(),
             deadline,
-            previousSessionId,
-            previousConsumption: previousConsumption.toString(),
+            previousSessionId: '0x' + '0'.repeat(64),
+            previousConsumption: '0',
             tokensDelivered: '0',
             requestCount: 0,
             reservedAt: now,
             settledAt: null,
             settledAmount: null,
             status: 'active',
+            latestBuyerSig: null,
+            latestSpendingAuthSig: null,
+            latestMetadata: null,
             createdAt: now,
             updatedAt: now,
         };
-        this._sessionStore.upsertSession(session);
-        // Send SpendingAuth via PaymentMux
+        this._channelStore.upsertChannel(session);
+        // Send SpendingAuth via PaymentMux — reserve carries ReserveAuth sig
         paymentMux.sendSpendingAuth({
-            sessionId,
-            maxAmountUsdc: amount.toString(),
-            nonce,
-            deadline,
-            buyerSig,
-            buyerEvmAddr,
-            previousConsumption: previousConsumption.toString(),
-            previousSessionId,
+            channelId,
+            cumulativeAmount: minBudgetPerRequest.toString(),
+            metadataHash: ZERO_METADATA_HASH,
+            metadata: encodeMetadata(ZERO_METADATA),
+            spendingAuthSig: reserveAuthSig,
+            reserveSalt: salt,
+            reserveMaxAmount: maxAmount.toString(),
+            reserveDeadline: deadline,
         });
-        return sessionId;
+        return channelId;
     }
     // ── AuthAck handler ───────────────────────────────────────────
     handleAuthAck(sellerPeerId, payload) {
-        const session = this._sessionStore.getActiveSessionByPeer(sellerPeerId, 'buyer');
+        const session = this.getActiveSession(sellerPeerId);
         if (!session) {
             debugWarn(`[BuyerPayment] AuthAck for unknown seller: ${sellerPeerId.slice(0, 12)}...`);
             return;
         }
-        if (session.sessionId !== payload.sessionId) {
-            debugWarn(`[BuyerPayment] AuthAck session mismatch: expected=${session.sessionId.slice(0, 18)}... got=${payload.sessionId.slice(0, 18)}...`);
+        if (session.sessionId !== payload.channelId) {
+            debugWarn(`[BuyerPayment] AuthAck channel mismatch: expected=${session.sessionId.slice(0, 18)}... got=${payload.channelId.slice(0, 18)}...`);
             return;
         }
         this._confirmedPeers.add(sellerPeerId);
-        debugLog(`[BuyerPayment] AuthAck confirmed: session=${session.sessionId.slice(0, 18)}...`);
+        debugLog(`[BuyerPayment] AuthAck confirmed: channel=${session.sessionId.slice(0, 18)}...`);
+    }
+    // ── Buyer-side cost verification ──────────────────────────────
+    /**
+     * Estimate tokens and cost from response content without updating state.
+     */
+    _estimateResponseCost(sellerPeerId, inputBytes, outputBytes) {
+        const pricing = this._sessionPricing.get(sellerPeerId);
+        if (!pricing)
+            return null;
+        return estimateCostFromBytes(inputBytes, outputBytes, pricing);
+    }
+    /**
+     * Accumulate a cost estimate into verifiedCost.
+     */
+    _accumulateVerifiedCost(sellerPeerId, estimate) {
+        const prev = this._verifiedCost.get(sellerPeerId) ?? 0n;
+        const newVerified = prev + estimate.cost;
+        this._verifiedCost.set(sellerPeerId, newVerified);
+        return newVerified;
+    }
+    /**
+     * Record response content and update the buyer's verified cost.
+     * Call this after receiving each response from the seller.
+     *
+     * NOTE: Do not call this AND signPerRequestAuth for the same response —
+     * signPerRequestAuth already updates verifiedCost internally.
+     *
+     * @returns The updated verified cost and estimated tokens, or null if no pricing is available.
+     */
+    recordResponseBytes(sellerPeerId, inputBytes, outputBytes) {
+        const estimate = this._estimateResponseCost(sellerPeerId, inputBytes, outputBytes);
+        if (!estimate)
+            return null;
+        const newVerified = this._accumulateVerifiedCost(sellerPeerId, estimate);
+        const inSize = inputBytes.length;
+        const outSize = outputBytes.length;
+        debugLog(`[BuyerPayment] recordResponseBytes: seller=${sellerPeerId.slice(0, 12)}... ` +
+            `in=${inSize}B→${estimate.inputTokens}tok out=${outSize}B→${estimate.outputTokens}tok ` +
+            `requestCost=${estimate.cost} verifiedCost=${newVerified}`);
+        return { verifiedCost: newVerified, inputTokens: estimate.inputTokens, outputTokens: estimate.outputTokens };
+    }
+    // ── Per-request authorization (overdraft model) ─────────────
+    /**
+     * Compute the max signable cumulative amount based on the overdraft model:
+     * maxSignable = verifiedCost + maxPerRequestUsdc, capped at reserve ceiling.
+     */
+    _maxSignable(sellerPeerId) {
+        const verified = this._verifiedCost.get(sellerPeerId) ?? 0n;
+        const ceiling = this._getCeiling(sellerPeerId);
+        const maxSignable = verified + this._config.maxPerRequestUsdc;
+        return maxSignable < ceiling ? maxSignable : ceiling;
+    }
+    /**
+     * Check whether the current cumulative amount is approaching the reserve ceiling
+     * and a top-up should be triggered.
+     */
+    _needsTopUp(sellerPeerId) {
+        const ceiling = this._getCeiling(sellerPeerId);
+        const current = this._cumulativeAmount.get(sellerPeerId) ?? 0n;
+        const threshold = BigInt(Math.floor(Number(ceiling) * DEFAULT_TOPUP_THRESHOLD));
+        return current >= threshold;
+    }
+    /**
+     * Sign an updated SpendingAuth after receiving a response.
+     *
+     * The buyer uses the seller's claimed cost to advance the cumulative amount,
+     * but validates it against the buyer's bytes/4 estimate. If the seller's claim
+     * exceeds the buyer's estimate by more than the configured tolerance, the buyer
+     * caps at tolerance * buyerEstimate. The cumulative is also capped at the
+     * overdraft limit (verifiedCost + maxPerRequestUsdc) and the reserve ceiling.
+     *
+     * @param sellerPeerId Seller peer ID.
+     * @param responseStats Byte counts from the last response and seller's claimed cost.
+     * @param addedLatencyMs Optional latency for metadata.
+     * @returns The signed payload and whether a reserve top-up is needed.
+     */
+    async signPerRequestAuth(sellerPeerId, responseStats, addedLatencyMs) {
+        const session = this.getActiveSession(sellerPeerId);
+        if (!session) {
+            throw new Error(`[BuyerPayment] No active session for seller ${sellerPeerId.slice(0, 12)}... — call authorizeSpending() first`);
+        }
+        // Estimate cost from response bytes (buyer's independent estimate) and accumulate
+        const estimate = this._estimateResponseCost(sellerPeerId, responseStats.inputBytes, responseStats.outputBytes);
+        const estimatedInputTokens = estimate ? BigInt(estimate.inputTokens) : 0n;
+        const estimatedOutputTokens = estimate ? BigInt(estimate.outputTokens) : 0n;
+        const buyerEstimatedRequestCost = estimate ? estimate.cost : 0n;
+        if (estimate) {
+            this._accumulateVerifiedCost(sellerPeerId, estimate);
+        }
+        // Determine the accepted cost for this request:
+        // Use seller's claim, but cap at tolerance * buyer estimate if buyer has pricing.
+        let acceptedCost = responseStats.sellerClaimedCost ?? buyerEstimatedRequestCost;
+        if (responseStats.sellerClaimedCost != null && buyerEstimatedRequestCost > 0n) {
+            const maxAcceptable = BigInt(Math.ceil(Number(buyerEstimatedRequestCost) * this._costTolerance));
+            if (responseStats.sellerClaimedCost > maxAcceptable) {
+                debugWarn(`[BuyerPayment] Seller claimed ${responseStats.sellerClaimedCost} exceeds ${this._costTolerance}x buyer estimate ${buyerEstimatedRequestCost} — capping at ${maxAcceptable}`);
+                acceptedCost = maxAcceptable;
+            }
+        }
+        // Minimum 1 base unit for monotonicity
+        if (acceptedCost === 0n)
+            acceptedCost = 1n;
+        // Update cumulative metadata
+        const prev = this._metadata.get(sellerPeerId) ?? ZERO_METADATA;
+        const newMeta = {
+            cumulativeInputTokens: prev.cumulativeInputTokens + estimatedInputTokens,
+            cumulativeOutputTokens: prev.cumulativeOutputTokens + estimatedOutputTokens,
+            cumulativeLatencyMs: prev.cumulativeLatencyMs + (addedLatencyMs ?? 0n),
+            cumulativeRequestCount: prev.cumulativeRequestCount + 1n,
+        };
+        this._metadata.set(sellerPeerId, newMeta);
+        // Advance cumulative amount by the accepted cost, then add overdraft headroom
+        // for the next request (so the seller has budget to serve it).
+        // maxSignable already caps at reserve ceiling, so one cap is sufficient
+        const prevAmount = this._cumulativeAmount.get(sellerPeerId) ?? 0n;
+        const maxSignable = this._maxSignable(sellerPeerId);
+        let newAmount = prevAmount + acceptedCost;
+        if (newAmount > maxSignable)
+            newAmount = maxSignable;
+        // Ensure monotonic increase (at least +1 per request)
+        if (newAmount <= prevAmount)
+            newAmount = prevAmount + 1n;
+        if (newAmount > maxSignable)
+            newAmount = maxSignable;
+        this._cumulativeAmount.set(sellerPeerId, newAmount);
+        // Compute metadata hash and encode metadata
+        const metadataHashHex = computeMetadataHash(newMeta);
+        const encodedMetadata = encodeMetadata(newMeta);
+        // Sign EIP-712 SpendingAuth
+        const channelsDomain = this._channelsDomain;
+        const metadataMsg = {
+            channelId: session.sessionId,
+            cumulativeAmount: newAmount,
+            metadataHash: metadataHashHex,
+        };
+        const spendingAuthSig = await signSpendingAuth(this._signer, channelsDomain, metadataMsg);
+        // Persist updated cumulative values to ChannelStore
+        this._channelStore.upsertChannel({
+            ...session,
+            authMax: newAmount.toString(),
+            requestCount: Number(newMeta.cumulativeRequestCount),
+            updatedAt: Date.now(),
+        });
+        const payload = {
+            channelId: session.sessionId,
+            cumulativeAmount: newAmount.toString(),
+            metadataHash: metadataHashHex,
+            metadata: encodedMetadata,
+            spendingAuthSig,
+        };
+        const topUpNeeded = this._needsTopUp(sellerPeerId);
+        return { payload, topUpNeeded };
     }
-    // ── Seller Receipt handler ────────────────────────────────────
-    async handleSellerReceipt(sellerPeerId, receipt, paymentMux) {
-        const session = this._sessionStore.getActiveSessionByPeer(sellerPeerId, 'buyer');
+    // ── NeedAuth handler ───────────────────────────────────────────
+    /**
+     * Handle seller-initiated NeedAuth messages when the seller's budget runs out mid-session.
+     * Caps the signed amount at verifiedCost + maxPerRequestUsdc (overdraft model).
+     */
+    async handleNeedAuth(sellerPeerId, payload, paymentMux) {
+        const session = this.getActiveSession(sellerPeerId);
         if (!session) {
-            debugWarn(`[BuyerPayment] Receipt for unknown seller: ${sellerPeerId.slice(0, 12)}...`);
+            debugWarn(`[BuyerPayment] NeedAuth for unknown seller: ${sellerPeerId.slice(0, 12)}...`);
             return;
         }
-        if (session.sessionId !== receipt.sessionId) {
-            debugWarn(`[BuyerPayment] Receipt session ID mismatch: active=${session.sessionId.slice(0, 18)}... receipt=${receipt.sessionId.slice(0, 18)}... — discarding stale receipt`);
+        const requiredCumulativeAmount = BigInt(payload.requiredCumulativeAmount);
+        const currentCumulative = this._cumulativeAmount.get(sellerPeerId) ?? 0n;
+        // Reject stale/lower NeedAuth (monotonicity guard)
+        if (requiredCumulativeAmount <= currentCumulative) {
+            debugLog(`[BuyerPayment] NeedAuth stale: required=${requiredCumulativeAmount} <= current=${currentCumulative} — ignoring`);
             return;
         }
-        // Verify seller's Ed25519 signature
-        try {
-            const sellerPublicKey = hexToBytes(sellerPeerId);
-            const sessionIdBytes = hexToBytes(receipt.sessionId.replace(/^0x/, ''));
-            const responseHashBytes = hexToBytes(receipt.responseHash);
-            const receiptMsg = buildReceiptMessage(sessionIdBytes, BigInt(receipt.runningTotal), receipt.requestCount, responseHashBytes);
-            const sigBytes = hexToBytes(receipt.sellerSig);
-            const valid = await verifyMessageEd25519(sellerPublicKey, sigBytes, receiptMsg);
-            if (!valid) {
-                debugWarn(`[BuyerPayment] Invalid seller receipt signature from ${sellerPeerId.slice(0, 12)}...`);
-                return;
+        // Cap at overdraft limit: verifiedCost + maxPerRequestUsdc
+        let maxSignable = this._maxSignable(sellerPeerId);
+        const reserveCeiling = this._getCeiling(sellerPeerId);
+        if (requiredCumulativeAmount > maxSignable && maxSignable >= reserveCeiling) {
+            try {
+                await this.topUpReserve(sellerPeerId, paymentMux);
             }
+            catch (err) {
+                debugWarn(`[BuyerPayment] NeedAuth: topUpReserve failed: ${err instanceof Error ? err.message : err}`);
+            }
+            maxSignable = this._maxSignable(sellerPeerId);
         }
-        catch (err) {
-            debugWarn(`[BuyerPayment] Failed to verify receipt: ${err instanceof Error ? err.message : err}`);
-            return;
-        }
-        // Validate monotonic increase: runningTotal must exceed previous
-        const newTotal = BigInt(receipt.runningTotal);
-        const prevTotal = BigInt(session.tokensDelivered);
-        if (newTotal <= prevTotal) {
-            debugWarn(`[BuyerPayment] Receipt runningTotal not monotonic: new=${newTotal} prev=${prevTotal}`);
+        if (maxSignable <= currentCumulative) {
+            debugWarn(`[BuyerPayment] NeedAuth: maxSignable=${maxSignable} <= currentCumulative=${currentCumulative} — cannot authorize more (overdraft limit reached)`);
             return;
         }
-        // Note: we don't compare token count against authMax (USDC) here because
-        // they're in different units (tokens vs USDC base units). The on-chain
-        // settle() caps chargeAmount = min(tokenCount * tokenRate, maxAmount),
-        // so the buyer's EIP-712 signature is the real USDC protection.
-        debugLog(`[BuyerPayment] Receipt: session=${session.sessionId.slice(0, 18)}... total=${receipt.runningTotal} count=${receipt.requestCount}`);
-        // Atomically update tokens delivered and store receipt
-        this._sessionStore.updateDeliveredAndInsertReceipt(session.sessionId, receipt.runningTotal, receipt.requestCount, {
-            sessionId: session.sessionId,
-            runningTotal: receipt.runningTotal,
-            requestCount: receipt.requestCount,
-            responseHash: receipt.responseHash,
-            sellerSig: receipt.sellerSig,
-            buyerAckSig: null,
-            createdAt: Date.now(),
+        // Sign up to the lesser of what the seller asks and what we allow
+        const effectiveAmount = requiredCumulativeAmount < maxSignable ? requiredCumulativeAmount : maxSignable;
+        debugLog(`[BuyerPayment] NeedAuth: channel=${session.sessionId.slice(0, 18)}... required=${requiredCumulativeAmount} effective=${effectiveAmount}`);
+        // Update cumulative amount
+        this._cumulativeAmount.set(sellerPeerId, effectiveAmount);
+        // Sign SpendingAuth with the effective amount and current metadata
+        const currentMeta = this._metadata.get(sellerPeerId) ?? ZERO_METADATA;
+        const metadataHashHex = computeMetadataHash(currentMeta);
+        const encodedMetadata = encodeMetadata(currentMeta);
+        const channelsDomain = this._channelsDomain;
+        const metadataMsg = {
+            channelId: session.sessionId,
+            cumulativeAmount: effectiveAmount,
+            metadataHash: metadataHashHex,
+        };
+        const spendingAuthSig = await signSpendingAuth(this._signer, channelsDomain, metadataMsg);
+        // Persist updated values
+        this._channelStore.upsertChannel({
+            ...session,
+            authMax: effectiveAmount.toString(),
+            updatedAt: Date.now(),
         });
-        // Auto-ack if configured
-        if (this._config.autoAck) {
-            const sessionIdBytes = hexToBytes(session.sessionId.replace(/^0x/, ''));
-            const ackMsg = buildAckMessage(sessionIdBytes, BigInt(receipt.runningTotal), receipt.requestCount);
-            const sigBytes = await signMessageEd25519(this._identity, ackMsg);
-            const buyerSig = bytesToHex(sigBytes);
-            paymentMux.sendBuyerAck({
-                sessionId: session.sessionId,
-                runningTotal: receipt.runningTotal,
-                requestCount: receipt.requestCount,
-                buyerSig,
+        // Send via PaymentMux
+        try {
+            paymentMux.sendSpendingAuth({
+                channelId: session.sessionId,
+                cumulativeAmount: effectiveAmount.toString(),
+                metadataHash: metadataHashHex,
+                metadata: encodedMetadata,
+                spendingAuthSig,
             });
-            debugLog(`[BuyerPayment] Auto-ack sent for session=${session.sessionId.slice(0, 18)}...`);
+            debugLog(`[BuyerPayment] NeedAuth responded: new cumulativeAmount=${effectiveAmount}`);
+        }
+        catch {
+            debugLog(`[BuyerPayment] NeedAuth: connection closed before SpendingAuth could be sent`);
         }
     }
-    // ── TopUp handler ─────────────────────────────────────────────
-    async handleTopUpRequest(sellerPeerId, request, paymentMux) {
-        const session = this._sessionStore.getActiveSessionByPeer(sellerPeerId, 'buyer');
+    // ── Reserve top-up ─────────────────────────────────────────────
+    /**
+     * Sign a new ReserveAuth with a higher maxAmount to extend the session's reserve ceiling.
+     * The seller must call reserve() on-chain again with the new signature.
+     * Note: requires contract support for top-up (increaseDeposit on existing channelId).
+     */
+    async topUpReserve(sellerPeerId, paymentMux) {
+        const session = this.getActiveSession(sellerPeerId);
         if (!session) {
-            debugWarn(`[BuyerPayment] Top-up for unknown seller: ${sellerPeerId.slice(0, 12)}...`);
+            debugWarn(`[BuyerPayment] topUpReserve: no active session for ${sellerPeerId.slice(0, 12)}...`);
             return;
         }
-        debugLog(`[BuyerPayment] TopUp request: session=${session.sessionId.slice(0, 18)}... currentUsed=${request.currentUsed} currentMax=${request.currentMax}`);
-        // Sign a new SpendingAuth with increased cap
-        const currentMax = BigInt(session.authMax);
-        const additionalAmount = BigInt(request.requestedAdditional);
-        const newMax = currentMax + additionalAmount;
-        // The new auth embeds the current consumption as previousConsumption
-        await this.authorizeSpending(sellerPeerId, session.sellerEvmAddr, paymentMux, newMax);
-        debugLog(`[BuyerPayment] TopUp authorized: new auth sent with max=${newMax}`);
+        const prevCeiling = this._getCeiling(sellerPeerId);
+        const newCeiling = prevCeiling + this._config.maxReserveAmountUsdc;
+        const deadline = Math.floor(Date.now() / 1000) + this._config.defaultAuthDurationSecs;
+        debugLog(`[BuyerPayment] topUpReserve: channel=${session.sessionId.slice(0, 18)}... ceiling ${prevCeiling} → ${newCeiling}`);
+        // Sign ReserveAuth with new maxAmount
+        const channelsDomain = this._channelsDomain;
+        const reserveMsg = {
+            channelId: session.sessionId,
+            maxAmount: newCeiling,
+            deadline: BigInt(deadline),
+        };
+        const reserveAuthSig = await signReserveAuth(this._signer, channelsDomain, reserveMsg);
+        const currentCumulative = this._cumulativeAmount.get(sellerPeerId) ?? 0n;
+        const currentMeta = this._metadata.get(sellerPeerId) ?? ZERO_METADATA;
+        const metadataHashHex = computeMetadataHash(currentMeta);
+        const encodedMetadata = encodeMetadata(currentMeta);
+        const salt = this._reserveSalt.get(sellerPeerId) ?? '0x' + '00'.repeat(32);
+        // Send ReserveAuth sig with reserve fields (same pattern as initial authorizeSpending).
+        // The seller uses this to call topUp() on-chain with the new maxAmount.
+        try {
+            paymentMux.sendSpendingAuth({
+                channelId: session.sessionId,
+                cumulativeAmount: currentCumulative.toString(),
+                metadataHash: metadataHashHex,
+                metadata: encodedMetadata,
+                spendingAuthSig: reserveAuthSig,
+                reserveSalt: salt,
+                reserveMaxAmount: newCeiling.toString(),
+                reserveDeadline: deadline,
+            });
+            // Only commit the new ceiling after the message is delivered
+            this._currentReserveCeiling.set(sellerPeerId, newCeiling);
+            debugLog(`[BuyerPayment] topUpReserve sent: newCeiling=${newCeiling}`);
+        }
+        catch {
+            debugLog(`[BuyerPayment] topUpReserve: connection closed before ReserveAuth could be sent`);
+        }
     }
     // ── Queries ───────────────────────────────────────────────────
+    /** Max USDC overdraft (unverified exposure) from buyer config. */
+    get maxPerRequestUsdc() {
+        return this._config.maxPerRequestUsdc;
+    }
+    /** Max USDC per ReserveAuth signature from buyer config. */
+    get maxReserveAmountUsdc() {
+        return this._config.maxReserveAmountUsdc;
+    }
+    /** Current buyer-verified cost for a seller. */
+    getVerifiedCost(sellerPeerId) {
+        return this._verifiedCost.get(sellerPeerId) ?? 0n;
+    }
+    /** Current reserve ceiling for a seller (may be higher than initial after top-ups). */
+    getReserveCeiling(sellerPeerId) {
+        return this._currentReserveCeiling.get(sellerPeerId) ?? this._config.maxReserveAmountUsdc;
+    }
+    /** Current cumulative signed amount for a seller. */
+    getCumulativeAmount(sellerPeerId) {
+        return this._cumulativeAmount.get(sellerPeerId) ?? 0n;
+    }
+    /** Live cumulative token counts for a seller (in-memory, always up-to-date). */
+    getCumulativeTokens(sellerPeerId) {
+        const meta = this._metadata.get(sellerPeerId) ?? ZERO_METADATA;
+        return { inputTokens: meta.cumulativeInputTokens, outputTokens: meta.cumulativeOutputTokens };
+    }
+    /**
+     * Accumulate response token counts and persist to the channel store.
+     * Tracks its own running totals independently of signPerRequestAuth metadata,
+     * so the persisted data is always up-to-date after each response.
+     */
+    recordAndPersistTokens(sellerPeerId, inputTokens, outputTokens) {
+        const session = this.getActiveSession(sellerPeerId);
+        if (!session)
+            return;
+        const prev = this._responseTokenTotals.get(sellerPeerId) ?? { input: 0, output: 0, requests: 0 };
+        const totals = {
+            input: prev.input + inputTokens,
+            output: prev.output + outputTokens,
+            requests: prev.requests + 1,
+        };
+        this._responseTokenTotals.set(sellerPeerId, totals);
+        this._channelStore.upsertChannel({
+            ...session,
+            tokensDelivered: String(totals.input),
+            previousConsumption: String(totals.output),
+            requestCount: totals.requests,
+            updatedAt: Date.now(),
+        });
+    }
+    /** Get the live response token totals for a seller, or null if none recorded this session. */
+    getResponseTokenTotals(sellerPeerId) {
+        return this._responseTokenTotals.get(sellerPeerId) ?? null;
+    }
     /** Check if a session has been confirmed via AuthAck. */
     isAuthorized(sellerPeerId) {
         return this._confirmedPeers.has(sellerPeerId);
@@ -236,40 +610,40 @@ export class BuyerPaymentManager {
         debugLog(`[BuyerPayment] Peer ${sellerPeerId.slice(0, 12)}... marked as rejected`);
     }
     getSessionHistory(sellerPeerId) {
-        const sessions = [];
-        const seen = new Set();
-        let session = this._sessionStore.getLatestSession(sellerPeerId, 'buyer');
-        while (session && !seen.has(session.sessionId)) {
-            seen.add(session.sessionId);
-            sessions.unshift(session);
-            if (session.previousSessionId === ZERO_SESSION_ID)
-                break;
-            session = this._sessionStore.getSession(session.previousSessionId);
-        }
-        return sessions;
+        const session = this._channelStore.getLatestChannelByPeerAndBuyer(sellerPeerId, 'buyer', this._identity.wallet.address);
+        return session ? [session] : [];
     }
-    // ── Escrow operations ─────────────────────────────────────────
+    // ── Deposit operations ──────────────────────────────────────────
     async deposit(amount) {
-        debugLog(`[BuyerPayment] Depositing ${amount} to escrow`);
-        return this._escrowClient.deposit(this._signer, amount);
+        debugLog(`[BuyerPayment] Depositing ${amount} to deposits`);
+        const buyer = this._identity.wallet.address;
+        return this._depositsClient.deposit(this._signer, buyer, amount);
     }
     async withdraw(amount) {
-        debugLog(`[BuyerPayment] Requesting withdrawal of ${amount} from escrow`);
-        return this._escrowClient.requestWithdrawal(this._signer, amount);
+        debugLog(`[BuyerPayment] Withdrawing ${amount} from deposits`);
+        return this._depositsClient.withdraw(this._signer, this._identity.wallet.address, amount);
     }
     async getBalance() {
-        const buyerAddr = identityToEvmAddress(this._identity);
-        const info = await this._escrowClient.getBuyerBalance(buyerAddr);
+        const buyerAddr = this._identity.wallet.address;
+        const info = await this._depositsClient.getBuyerBalance(buyerAddr);
         return { available: info.available, reserved: info.reserved };
     }
-    // ── Feedback (Task 6) ─────────────────────────────────────────
-    async submitFeedback(sellerPeerId, qualityScore, identityClient) {
-        const session = this._sessionStore.getLatestSession(sellerPeerId, 'buyer');
-        if (!session || session.status !== 'settled')
+    // ── Response cost parsing ──────────────────────────────────────
+    static parseResponseCost(headers) {
+        const costStr = headers[HEADER_COST];
+        if (costStr === undefined || costStr === '')
             return null;
-        const tokenId = await identityClient.getTokenId(session.sellerEvmAddr);
-        const tag = encodeBytes32String('quality');
-        return identityClient.submitFeedback(this._signer, tokenId, qualityScore, tag);
+        try {
+            const cost = BigInt(costStr);
+            const inputStr = headers[HEADER_INPUT_TOKENS];
+            const inputTokens = inputStr !== undefined && inputStr !== '' ? BigInt(inputStr) : 0n;
+            const outputStr = headers[HEADER_OUTPUT_TOKENS];
+            const outputTokens = outputStr !== undefined && outputStr !== '' ? BigInt(outputStr) : 0n;
+            return { cost, inputTokens, outputTokens };
+        }
+        catch {
+            return null;
+        }
     }
 }
 //# sourceMappingURL=buyer-payment-manager.js.map