@antseed/node 0.2.26 → 0.2.28

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

@@ -1,280 +1,649 @@
 import { randomBytes } from 'node:crypto';
-import { BaseEscrowClient } from './evm/escrow-client.js';
-import { identityToEvmWallet, identityToEvmAddress } from './evm/keypair.js';
-import { buildLockMessageHash, buildSettlementMessageHash, buildExtendLockMessageHash, signMessageEcdsa, buildAckMessage, signMessageEd25519, } 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';
+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 bilateral payment sessions across seller connections.
- *
- * Handles the full lifecycle: lock initiation, receipt acknowledgement,
- * top-up approval, and session settlement.
+ * Manages buyer-side payment sessions using EIP-712 SpendingAuth
+ * with cumulative authorization, bytes/4 cost verification, and overdraft control.
  */
 export class BuyerPaymentManager {
     _identity;
     _signer;
-    _escrowClient;
+    _depositsClient;
     _config;
-    _sessions = new Map();
-    constructor(identity, config) {
+    _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();
+    /** 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._channelStore = channelStore;
+        this._channelsDomain = makeChannelsDomain(config.chainId, config.channelsContractAddress);
+        // Hydrate cumulative maps from persisted active sessions
+        this._hydrateFromStore();
     }
-    get signer() {
-        return this._signer;
+    /** 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.
+        }
     }
-    /** @deprecated Use .signer instead */
-    get wallet() {
+    get signer() {
         return this._signer;
     }
-    /** Replace the signer at runtime (e.g. with a WalletConnect signer). */
     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);
     }
-    /** Get a snapshot of all active sessions. */
-    getActiveSessions() {
-        return [...this._sessions.values()].filter((s) => s.status !== 'ended');
+    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;
     }
-    /** Get the session for a given seller peer, if it exists. */
-    getSession(sellerPeerId) {
-        return this._sessions.get(sellerPeerId);
+    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;
     }
-    // ── Lock initiation ─────────────────────────────────────────────
+    // ── Spending Authorization ────────────────────────────────────
     /**
-     * Generate a session ID, sign a lock authorization, and send it
-     * to the seller via PaymentMux.
+     * 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 initiateLock(sellerPeerId, sellerEvmAddress, paymentMux, lockAmount) {
-        const amount = lockAmount ?? this._config.defaultLockAmountUSDC;
-        const amountBigInt = BigInt(amount);
-        // Generate a 32-byte session ID as 0x-prefixed hex (bytes32)
-        const sessionIdBytes = randomBytes(32);
-        const sessionId = '0x' + sessionIdBytes.toString('hex');
-        debugLog(`[BuyerPayment] Initiating lock: session=${sessionId.slice(0, 18)}... seller=${sellerPeerId.slice(0, 12)}... amount=${amount}`);
-        // Sign the lock message with ECDSA (for on-chain verification)
-        const messageHash = buildLockMessageHash(sessionId, sellerEvmAddress, amountBigInt);
-        const buyerSig = await signMessageEcdsa(this._signer, messageHash);
-        // Store session state
+    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);
+        // 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: 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 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,
-            sellerPeerId,
-            sellerEvmAddress,
-            lockedAmount: amountBigInt,
-            status: 'pending',
-            txSignature: null,
-            lastRunningTotal: 0n,
-            lastRequestCount: 0,
+            sessionId: channelId,
+            peerId: sellerPeerId,
+            role: 'buyer',
+            sellerEvmAddr: peerIdToAddress(sellerPeerId),
+            buyerEvmAddr: this._identity.wallet.address,
+            nonce: 0,
+            authMax: minBudgetPerRequest.toString(),
+            deadline,
+            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._sessions.set(sellerPeerId, session);
-        // Send the lock auth message
-        paymentMux.sendSessionLockAuth({
-            sessionId,
-            lockedAmount: amount,
-            buyerSig,
+        this._channelStore.upsertChannel(session);
+        // Send SpendingAuth via PaymentMux — reserve carries ReserveAuth sig
+        paymentMux.sendSpendingAuth({
+            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;
     }
-    // ── Lock confirmation / rejection handlers ──────────────────────
-    /**
-     * Called when the seller confirms the lock was committed on-chain.
-     */
-    handleLockConfirm(sellerPeerId, payload) {
-        const session = this._sessions.get(sellerPeerId);
+    // ── AuthAck handler ───────────────────────────────────────────
+    handleAuthAck(sellerPeerId, payload) {
+        const session = this.getActiveSession(sellerPeerId);
         if (!session) {
-            debugWarn(`[BuyerPayment] Lock confirm for unknown seller: ${sellerPeerId.slice(0, 12)}...`);
+            debugWarn(`[BuyerPayment] AuthAck for unknown seller: ${sellerPeerId.slice(0, 12)}...`);
             return;
         }
-        if (session.sessionId !== payload.sessionId) {
-            debugWarn(`[BuyerPayment] Lock confirm 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;
         }
-        session.status = 'confirmed';
-        session.txSignature = payload.txSignature;
-        session.updatedAt = Date.now();
-        debugLog(`[BuyerPayment] Lock confirmed: session=${session.sessionId.slice(0, 18)}... tx=${payload.txSignature.slice(0, 12)}...`);
+        this._confirmedPeers.add(sellerPeerId);
+        debugLog(`[BuyerPayment] AuthAck confirmed: channel=${session.sessionId.slice(0, 18)}...`);
     }
+    // ── Buyer-side cost verification ──────────────────────────────
     /**
-     * Called when the seller rejects the lock.
+     * Estimate tokens and cost from response content without updating state.
      */
-    handleLockReject(sellerPeerId, payload) {
-        const session = this._sessions.get(sellerPeerId);
-        if (!session) {
-            debugWarn(`[BuyerPayment] Lock reject for unknown seller: ${sellerPeerId.slice(0, 12)}...`);
-            return;
-        }
-        debugWarn(`[BuyerPayment] Lock rejected: session=${session.sessionId.slice(0, 18)}... reason=${payload.reason}`);
-        this._sessions.delete(sellerPeerId);
+    _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;
     }
-    // ── Receipt handling ────────────────────────────────────────────
     /**
-     * Handle a running-total receipt from the seller.
-     * If autoAck is enabled, automatically counter-sign and send BuyerAck.
+     * Check whether the current cumulative amount is approaching the reserve ceiling
+     * and a top-up should be triggered.
      */
-    async handleSellerReceipt(sellerPeerId, receipt, paymentMux) {
-        const session = this._sessions.get(sellerPeerId);
+    _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) {
-            debugWarn(`[BuyerPayment] Receipt for unknown seller: ${sellerPeerId.slice(0, 12)}...`);
-            return;
+            throw new Error(`[BuyerPayment] No active session for seller ${sellerPeerId.slice(0, 12)}... — call authorizeSpending() first`);
         }
-        if (session.status === 'confirmed') {
-            session.status = 'active';
+        // 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);
         }
-        // Update running total
-        session.lastRunningTotal = BigInt(receipt.runningTotal);
-        session.lastRequestCount = receipt.requestCount;
-        session.updatedAt = Date.now();
-        debugLog(`[BuyerPayment] Receipt: session=${session.sessionId.slice(0, 18)}... total=${receipt.runningTotal} count=${receipt.requestCount}`);
-        const autoAck = this._config.autoAck ?? true;
-        if (autoAck) {
-            // Build ack message and sign with Ed25519
-            const sessionIdBytes = hexToBytes(session.sessionId.startsWith('0x') ? session.sessionId.slice(2) : session.sessionId);
-            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,
-            });
-            debugLog(`[BuyerPayment] Auto-ack sent for session=${session.sessionId.slice(0, 18)}...`);
+        // 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 };
     }
-    // ── Top-up handling ─────────────────────────────────────────────
+    // ── NeedAuth handler ───────────────────────────────────────────
     /**
-     * Handle a top-up request from the seller.
-     * If autoTopUp is enabled and budget allows, sign and send TopUpAuth.
-     * Otherwise, end the session.
+     * Handle seller-initiated NeedAuth messages when the seller's budget runs out mid-session.
+     * Caps the signed amount at verifiedCost + maxPerRequestUsdc (overdraft model).
      */
-    async handleTopUpRequest(sellerPeerId, request, paymentMux) {
-        const session = this._sessions.get(sellerPeerId);
+    async handleNeedAuth(sellerPeerId, payload, paymentMux) {
+        const session = this.getActiveSession(sellerPeerId);
         if (!session) {
-            debugWarn(`[BuyerPayment] Top-up for unknown seller: ${sellerPeerId.slice(0, 12)}...`);
+            debugWarn(`[BuyerPayment] NeedAuth for unknown seller: ${sellerPeerId.slice(0, 12)}...`);
+            return;
+        }
+        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;
         }
-        const additionalAmount = BigInt(request.additionalAmount);
-        const maxBudget = BigInt(this._config.maxSessionBudgetUSDC ?? '10000000');
-        const newTotal = session.lockedAmount + additionalAmount;
-        const autoTopUp = this._config.autoTopUp ?? true;
-        debugLog(`[BuyerPayment] Top-up request: session=${session.sessionId.slice(0, 18)}... additional=${request.additionalAmount} newTotal=${newTotal}`);
-        if (autoTopUp && newTotal <= maxBudget) {
-            // Check on-chain balance
-            const buyerAddr = identityToEvmAddress(this._identity);
-            const account = await this._escrowClient.getBuyerAccount(buyerAddr);
-            if (account.available >= additionalAmount) {
-                // Sign extend-lock authorization
-                const messageHash = buildExtendLockMessageHash(session.sessionId, session.sellerEvmAddress, additionalAmount);
-                const buyerSig = await signMessageEcdsa(this._signer, messageHash);
-                session.lockedAmount = newTotal;
-                session.updatedAt = Date.now();
-                paymentMux.sendTopUpAuth({
-                    sessionId: session.sessionId,
-                    additionalAmount: request.additionalAmount,
-                    buyerSig,
-                });
-                debugLog(`[BuyerPayment] Top-up authorized: session=${session.sessionId.slice(0, 18)}...`);
-                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}`);
             }
-            debugWarn(`[BuyerPayment] Insufficient balance for top-up. Available=${account.available}, requested=${additionalAmount}`);
+            maxSignable = this._maxSignable(sellerPeerId);
+        }
+        if (maxSignable <= currentCumulative) {
+            debugWarn(`[BuyerPayment] NeedAuth: maxSignable=${maxSignable} <= currentCumulative=${currentCumulative} — cannot authorize more (overdraft limit reached)`);
+            return;
+        }
+        // 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(),
+        });
+        // Send via PaymentMux
+        try {
+            paymentMux.sendSpendingAuth({
+                channelId: session.sessionId,
+                cumulativeAmount: effectiveAmount.toString(),
+                metadataHash: metadataHashHex,
+                metadata: encodedMetadata,
+                spendingAuthSig,
+            });
+            debugLog(`[BuyerPayment] NeedAuth responded: new cumulativeAmount=${effectiveAmount}`);
+        }
+        catch {
+            debugLog(`[BuyerPayment] NeedAuth: connection closed before SpendingAuth could be sent`);
         }
-        // Cannot or will not top up — end the session
-        debugLog(`[BuyerPayment] Declining top-up, ending session=${session.sessionId.slice(0, 18)}...`);
-        await this.endSession(sellerPeerId, paymentMux, 80);
     }
-    // ── Session end ─────────────────────────────────────────────────
+    // ── Reserve top-up ─────────────────────────────────────────────
     /**
-     * End a session with the given seller. Signs a settlement message
-     * with ECDSA and sends SessionEnd.
+     * 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 endSession(sellerPeerId, paymentMux, score = 80) {
-        const session = this._sessions.get(sellerPeerId);
+    async topUpReserve(sellerPeerId, paymentMux) {
+        const session = this.getActiveSession(sellerPeerId);
         if (!session) {
-            debugWarn(`[BuyerPayment] Cannot end session for unknown seller: ${sellerPeerId.slice(0, 12)}...`);
+            debugWarn(`[BuyerPayment] topUpReserve: no active session for ${sellerPeerId.slice(0, 12)}...`);
             return;
         }
-        if (session.status === 'ending' || session.status === 'ended') {
-            return;
+        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`);
         }
-        session.status = 'ending';
-        session.updatedAt = Date.now();
-        debugLog(`[BuyerPayment] Ending session=${session.sessionId.slice(0, 18)}... total=${session.lastRunningTotal} score=${score}`);
-        // Sign settlement message with ECDSA
-        const messageHash = buildSettlementMessageHash(session.sessionId, session.lastRunningTotal, score);
-        const buyerSig = await signMessageEcdsa(this._signer, messageHash);
-        paymentMux.sendSessionEnd({
-            sessionId: session.sessionId,
-            runningTotal: session.lastRunningTotal.toString(),
-            requestCount: session.lastRequestCount,
-            score,
-            buyerSig,
-        });
-        session.status = 'ended';
-        session.updatedAt = Date.now();
-        debugLog(`[BuyerPayment] Session ended: ${session.sessionId.slice(0, 18)}...`);
     }
-    // ── Escrow operations ───────────────────────────────────────────
-    /**
-     * Deposit USDC into the escrow contract.
-     * @param amount Amount in USDC base units (6 decimals).
-     */
-    async deposit(amount) {
-        debugLog(`[BuyerPayment] Depositing ${amount} to escrow`);
-        return this._escrowClient.deposit(this._signer, amount);
+    // ── Queries ───────────────────────────────────────────────────
+    /** Max USDC overdraft (unverified exposure) from buyer config. */
+    get maxPerRequestUsdc() {
+        return this._config.maxPerRequestUsdc;
     }
-    /**
-     * Withdraw USDC from the escrow contract.
-     * @param amount Amount in USDC base units (6 decimals).
-     */
-    async withdraw(amount) {
-        debugLog(`[BuyerPayment] Withdrawing ${amount} from escrow`);
-        return this._escrowClient.withdraw(this._signer, amount);
+    /** Max USDC per ReserveAuth signature from buyer config. */
+    get maxReserveAmountUsdc() {
+        return this._config.maxReserveAmountUsdc;
     }
-    /**
-     * Get the buyer's on-chain escrow balance.
-     */
-    async getBalance() {
-        const buyerAddr = identityToEvmAddress(this._identity);
-        return this._escrowClient.getBuyerAccount(buyerAddr);
+    /** Current buyer-verified cost for a seller. */
+    getVerifiedCost(sellerPeerId) {
+        return this._verifiedCost.get(sellerPeerId) ?? 0n;
     }
-    // ── Dispute helpers ─────────────────────────────────────────────
-    /**
-     * Release an expired lock (buyer reclaims funds).
-     */
-    async releaseExpiredLock(sessionId) {
-        debugLog(`[BuyerPayment] Releasing expired lock: session=${sessionId.slice(0, 18)}...`);
-        return this._escrowClient.releaseExpiredLock(this._signer, sessionId);
+    /** Current reserve ceiling for a seller (may be higher than initial after top-ups). */
+    getReserveCeiling(sellerPeerId) {
+        return this._currentReserveCeiling.get(sellerPeerId) ?? this._config.maxReserveAmountUsdc;
     }
-    /**
-     * Respond to a dispute opened by the seller.
-     */
-    async respondToDispute(sessionId) {
-        debugLog(`[BuyerPayment] Responding to dispute: session=${sessionId.slice(0, 18)}...`);
-        return this._escrowClient.respondDispute(this._signer, sessionId);
+    /** 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 };
     }
     /**
-     * Check if a session lock has been confirmed (for polling).
+     * 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);
+    }
+    /** Alias for isAuthorized (used by polling loop). */
     isLockConfirmed(sellerPeerId) {
-        const session = this._sessions.get(sellerPeerId);
-        return session?.status === 'confirmed' || session?.status === 'active';
+        return this.isAuthorized(sellerPeerId);
     }
-    /**
-     * Check if a session lock has been rejected (for polling).
-     */
+    /** Check if the lock was explicitly rejected (not just never-contacted). */
     isLockRejected(sellerPeerId) {
-        return !this._sessions.has(sellerPeerId);
+        return this._rejectedPeers.has(sellerPeerId);
+    }
+    /** Mark a peer as having rejected our spending auth. */
+    markRejected(sellerPeerId) {
+        this._rejectedPeers.add(sellerPeerId);
+        debugLog(`[BuyerPayment] Peer ${sellerPeerId.slice(0, 12)}... marked as rejected`);
+    }
+    getSessionHistory(sellerPeerId) {
+        const session = this._channelStore.getLatestChannelByPeerAndBuyer(sellerPeerId, 'buyer', this._identity.wallet.address);
+        return session ? [session] : [];
+    }
+    // ── Deposit operations ──────────────────────────────────────────
+    async deposit(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] Withdrawing ${amount} from deposits`);
+        return this._depositsClient.withdraw(this._signer, this._identity.wallet.address, amount);
+    }
+    async getBalance() {
+        const buyerAddr = this._identity.wallet.address;
+        const info = await this._depositsClient.getBuyerBalance(buyerAddr);
+        return { available: info.available, reserved: info.reserved };
+    }
+    // ── Response cost parsing ──────────────────────────────────────
+    static parseResponseCost(headers) {
+        const costStr = headers[HEADER_COST];
+        if (costStr === undefined || costStr === '')
+            return null;
+        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