mppx 0.13.5 → 0.14.0

package/dist/tempo/session/server/MeteredStream.js

@@ -1,38 +1,24 @@
-import { commitReservedCharges, releaseReservedCharges, renewReservedCharges, reserveChargeOrWait, streamReservationLeaseMs, } from './Transports.js';
+import { commitReservedCharges, releaseReservedCharges, reserveChargeOrWait } from './Transports.js';
 /** Applies voucher reservation and spend commits to an async session stream. */
 export async function* meterIterable(options) {
+    const manual = typeof options.generate === 'function';
     let prepaidUnits = options.prepaidUnits ?? 0;
-    const controller = new AbortController();
-    const signal = controller.signal;
+    const signal = options.signal ?? new AbortController().signal;
     const reservation = {
         store: options.store,
         channelId: options.channelId,
         reservationId: globalThis.crypto.randomUUID(),
     };
     let pending = false;
-    let cancelled = false;
-    const onAbort = () => {
-        if (signal.aborted)
-            return;
-        cancelled = true;
-        controller.abort(options.signal?.reason);
-    };
-    options.signal?.addEventListener('abort', onAbort, { once: true });
-    if (options.signal?.aborted)
-        onAbort();
-    const renewal = setInterval(() => {
-        if (pending)
-            void renewReservedCharges(reservation).catch((error) => controller.abort(error));
-    }, streamReservationLeaseMs / 3);
-    renewal.unref?.();
     const releaseOnAbort = () => {
-        clearInterval(renewal);
         void releaseReservedCharges(reservation).catch(() => { });
     };
     signal.addEventListener('abort', releaseOnAbort, { once: true });
     if (signal.aborted)
         releaseOnAbort();
     const charge = async (amount) => {
+        signal.throwIfAborted();
+        await options.beforeCharge?.();
         signal.throwIfAborted();
         if (amount === undefined && prepaidUnits > 0) {
             prepaidUnits -= 1;
@@ -50,9 +36,13 @@ export async function* meterIterable(options) {
             signal,
         });
         pending = true;
+        if (manual)
+            await commit();
         signal.throwIfAborted();
     };
     const commit = async () => {
+        signal.throwIfAborted();
+        await options.beforeCharge?.();
         signal.throwIfAborted();
         if (!pending)
             return;
@@ -63,7 +53,6 @@ export async function* meterIterable(options) {
         await options.onChargeCommitted?.(channel);
     };
     try {
-        const manual = typeof options.generate === 'function';
         const iterable = typeof options.generate === 'function'
             ? options.generate({ charge, signal })
             : options.generate;
@@ -74,7 +63,7 @@ export async function* meterIterable(options) {
                 if (signal.aborted)
                     break;
                 if (done) {
-                    if (manual)
+                    if (manual && pending)
                         await commit();
                     break;
                 }
@@ -83,18 +72,13 @@ export async function* meterIterable(options) {
                 await commit();
                 yield value;
             }
-            if (!cancelled)
-                signal.throwIfAborted();
         }
         finally {
-            clearInterval(renewal);
             await releaseReservedCharges(reservation);
             await iterator.return?.();
         }
     }
     finally {
-        clearInterval(renewal);
-        options.signal?.removeEventListener('abort', onAbort);
         signal.removeEventListener('abort', releaseOnAbort);
         await releaseReservedCharges(reservation);
     }

package/dist/tempo/session/server/Session.d.ts

@@ -18,9 +18,12 @@ import * as Transport from '../../server/internal/transport.js';
 import { deserializeSnapshot as deserializeSessionSnapshot, serializeSnapshot as serializeSessionSnapshot } from '../Snapshot.js';
 import * as ChannelStore from './ChannelStore.js';
 import { type ResolveSessionChannelId } from './RequestState.js';
-import { type SettleChargedSessionChannel } from './Settlement.js';
+import { type SessionStoreInput, type SettleChargedSessionChannel } from './Settlement.js';
 import { type OnSessionSettlement, type OnSessionSettlementFailure, type SettlementSchedule } from './Settlement.js';
+import * as SponsorshipLimit from './SponsorshipLimit.js';
 import * as Ws from './Ws.js';
+/** @internal Reuses a method's escrow verifier when composing shared currency helpers. */
+export declare function verifyStream(method: object, channelId: Hex): Promise<void>;
 /** Server-side automatic settlement schedule. */
 export type { SettlementSchedule } from './Settlement.js';
 /** Server-side settlement event hook types. */
@@ -131,15 +134,27 @@ export declare namespace session {
         serveWebSocket: (options: ServeWebSocketOptions) => Promise<void>;
     };
     /** WebSocket server options supplied after the session binds shared dependencies. */
-    type ServeWebSocketOptions = Omit<Ws.serve.Options, 'onChargeCommitted' | 'settleScheduled' | 'store'>;
+    type ServeWebSocketOptions = Omit<Ws.serve.Options, 'beforeCharge' | 'onChargeCommitted' | 'settleScheduled' | 'store'>;
     /** Request defaults inferred from the Tempo session method schema. */
     type Defaults = LooseOmit<Method.RequestDefaults<typeof Methods.session>, 'escrowContract' | 'feePayer' | 'recipient'>;
     /** Partial fee-sponsor policy used for server-submitted session transactions. */
     type FeePayerPolicy = Partial<FeePayer.Policy>;
     /** Parameters accepted by the TIP-1034 server session payment method. */
     type Parameters = {
-        /** TTL in milliseconds for cached on-chain channel state during non-mutating validation. Voucher acceptance always refreshes on-chain state. @default 5_000 */
+        /** TTL in milliseconds for cached on-chain channel state during non-mutating validation, and before a voucher accepted under `voucherStateMaxAge` starts a fresh read. @default 5_000 */
         channelStateTtl?: number | undefined;
+        /**
+         * Maximum age in milliseconds of verified on-chain channel state that a voucher may be validated
+         * and accepted against without waiting for a fresh read. The fresh read then finishes in the background and
+         * records a pending close, so later vouchers are rejected. `0` reads on-chain state before every
+         * acceptance.
+         *
+         * A payer can withdraw only after the escrow's `CLOSE_GRACE_PERIOD` (900 s on Tempo) following a
+         * close request, so vouchers accepted this way stay settleable as long as the payee settles them
+         * within the grace period minus this age. Keep it well below that bound.
+         * @default 0
+         */
+        voucherStateMaxAge?: number | undefined;
         /** Override the fee-sponsor policy used for sponsored open/topUp transactions and server-driven close transactions. */
         feePayerPolicy?: FeePayerPolicy | undefined;
         /** Minimum voucher delta to accept (numeric string, default: "0"). */
@@ -159,6 +174,19 @@ export declare namespace session {
          * containing the signed highest voucher for client rehydration.
          */
         bootstrap?: boolean | undefined;
+        /**
+         * Lets a session challenge pay for later requests to the same route until it expires. The
+         * challenge is bound to its route, currency, recipient and channel terms but not to the amount
+         * it quoted, and every request is charged its own price from the channel's accepted balance.
+         * A client can then send a voucher with a request instead of waiting for a `402`.
+         */
+        reusableChallenges?: boolean | undefined;
+        /**
+         * Charges request-priced content (`unitType: 'request'`) in the same store update that accepts
+         * its voucher, before the response, instead of in a second update when the response is
+         * delivered. The server must then refund requests it cannot serve.
+         */
+        chargeOnAcceptance?: boolean | undefined;
         /**
          * Atomic store backend for channel state.
          *
@@ -181,6 +209,14 @@ export declare namespace session {
         settlementSchedule?: SettlementSchedule | undefined;
         /** Optional fee token for management and server-driven settle/close transactions. */
         feeToken?: Address | undefined;
+        /**
+         * Limits fee-payer-sponsored channel opens and top-ups to `perDay` of each per payer per UTC
+         * day (default 5), counted in `store`. The payer is the verified signer of the transaction, never
+         * the credential's client-supplied `source`. A transaction over the limit, or one whose
+         * signatures prove no payer, is broadcast unsponsored, so it lands only if the payer pays its
+         * own fees.
+         */
+        sponsorshipLimit?: SponsorshipLimit.Parameters | undefined;
     } & Account.resolve.Parameters & Client.getResolver.Parameters & Defaults & Method.ComposableHooks<typeof Methods.session>;
     /** Defaults derived from `session()` parameters for handler type inference. */
     type DeriveDefaults<parameters extends Parameters> = types.DeriveDefaults<parameters, Defaults, {
@@ -196,6 +232,36 @@ export declare namespace session {
  *
  * Delegates to the shared `deductFromChannel` atomic helper and translates
  * failure modes into typed errors (`InsufficientBalanceError`, `ChannelClosedError`).
+ *
+ * With `options.idempotencyKey` the channel is charged at most once per key: a retry with the same
+ * key and amount returns the channel without charging again, and the same key with a different
+ * amount throws `IdempotencyKeyConflictError`.
+ *
+ * @example
+ * ```ts
+ * // One durable job per voucher, retried under its operation ID.
+ * const channel = await Session.Server.charge(store, channelId, jobCost, {
+ *   idempotencyKey: operationId,
+ * })
+ * ```
+ */
+export declare function charge(store: SessionStoreInput, channelId: Hex, amount: bigint, options?: ChannelStore.ChargeOptions): Promise<ChannelStore.State>;
+/**
+ * Returns an unused amount to a channel's `spent` at most once per idempotency key.
+ *
+ * The first outcome for a key is final. A credit is `declined` when the channel is closing or
+ * finalized, or when it would take `spent` below zero or below what settled, or may still settle,
+ * on-chain, because a close captures `max(spent, settled)`; the caller then refunds another way.
+ * `unknown` reports a store write that failed and may have committed; retrying with the same key
+ * returns the outcome that was recorded.
+ *
+ * @example
+ * ```ts
+ * const result = await Session.Server.credit(store, channelId, unused, {
+ *   idempotencyKey: `refund:${flowId}`,
+ * })
+ * if (result.status === 'declined') await refundAnotherWay()
+ * ```
  */
-export declare function charge(store: ChannelStore.ChannelStore, channelId: Hex, amount: bigint): Promise<ChannelStore.State>;
+export declare function credit(store: SessionStoreInput, channelId: Hex, amount: bigint, options: ChannelStore.CreditOptions): Promise<ChannelStore.CreditResult>;
 //# sourceMappingURL=Session.d.ts.map

package/dist/tempo/session/server/Session.js

@@ -20,17 +20,27 @@ import * as Methods from '../../Methods.js';
 import * as ChargeServer from '../../server/Charge.js';
 import { fallbackStore } from '../../server/internal/fallback-store.js';
 import * as Transport from '../../server/internal/transport.js';
+import * as Chain from '../precompile/Chain.js';
 import { tip20ChannelEscrow } from '../precompile/Protocol.js';
 import { deserializeSnapshot as deserializeSessionSnapshot, serializeSnapshot as serializeSessionSnapshot, } from '../Snapshot.js';
 import * as ChannelStore from './ChannelStore.js';
 import { broadcastCredentialPayload, validateCredentialPayload } from './CredentialVerification.js';
-import { requireSessionCredentialPayload } from './CredentialVerification.js';
+import { requireSessionCredentialPayload, validateChannelState } from './CredentialVerification.js';
 import { resolveCredentialVerificationContext, resolveSessionChannelId, resolveSessionSnapshot, resolveSessionPaymentRequest, } from './RequestState.js';
 import { respondToSessionCredential } from './RequestState.js';
-import { applyVerifiedHttpAccounting, chargeSessionChannel, shouldApplyVerifiedHttpAccounting, } from './Settlement.js';
+import { applyVerifiedHttpAccounting, chargeSessionChannel, resolveChannelStore, shouldApplyVerifiedHttpAccounting, shouldChargeVoucherOnAcceptance, } from './Settlement.js';
 import { ignoreRetryableSettlementFailure, isSettlementDue, maybeSettleScheduled, reportSessionSettlementFailure, } from './Settlement.js';
 import { resolveSettlementSchedule, } from './Settlement.js';
+import * as SponsorshipLimit from './SponsorshipLimit.js';
 import * as Ws from './Ws.js';
+const streamVerifiers = new WeakMap();
+/** @internal Reuses a method's escrow verifier when composing shared currency helpers. */
+export function verifyStream(method, channelId) {
+    const verify = streamVerifiers.get(method);
+    if (!verify)
+        throw new Error('Session stream verifier is not configured');
+    return verify(channelId);
+}
 export { settle, settleBatch } from './Settlement.js';
 function deriveServerDefaults(values) {
     // `Method.toServer()` models defaults from request input fields. Tempo session
@@ -191,11 +201,25 @@ async function handleBootstrapPreflight(parameters) {
     }
     return new Response(null, { status: 204, headers });
 }
+/** Binds a reusable session challenge to its route and channel terms but not to its quoted amount. */
+const reusableSessionBinding = (request) => {
+    const { methodDetails } = request;
+    return {
+        chainId: methodDetails.chainId,
+        currency: request.currency,
+        escrowContract: methodDetails.escrowContract,
+        operator: methodDetails.operator,
+        recipient: request.recipient,
+        sessionProtocol: methodDetails[Constants.MethodDetailKeys.sessionProtocol],
+        unitType: request.unitType,
+    };
+};
 /** Creates a server-side TIP20EscrowChannel precompile session payment method. */
 export function session(p) {
     const parameters = p;
     const { amount, channelStateTtl = 5_000, currency = defaults.resolveCurrency(parameters), decimals = defaults.decimals, operator, store: rawStore = fallbackStore('tempo.session'), suggestedDeposit, unitType, } = parameters;
     const settlementSchedule = resolveSettlementSchedule(parameters.settlementSchedule, decimals);
+    SponsorshipLimit.assertParameters(parameters.sponsorshipLimit);
     const onSessionSettlement = parameters.onSessionSettlement;
     const onSessionSettlementFailure = parameters.onSessionSettlementFailure;
     const store = ChannelStore.fromStore(rawStore);
@@ -236,8 +260,33 @@ export function session(p) {
     // A failed scheduled settlement is reported and retried by the next one; the charged request
     // stays served because the payer's voucher already covers the charge.
     const settleCharged = (channel) => settleScheduled(channel).catch(ignoreRetryableSettlementFailure);
+    // Stream checks have a bounded TTL even when callers disable validation caching.
+    // Cache only successful reads; RPC failures must stop delivery.
+    const beforeStreamCharge = async (channelId) => {
+        channelId = ChannelStore.normalizeChannelId(channelId);
+        const channel = await store.getChannel(channelId);
+        if (!channel || channel.finalized || channel.closeRequestedAt !== 0n)
+            throw new Errors.ChannelClosedError({ reason: 'stream channel is closed' });
+        const now = Date.now();
+        const ttl = Math.min(Math.max(channelStateTtl, 0), 5_000);
+        const lastVerified = lastOnChainVerified.get(channelId);
+        if (lastVerified !== undefined && now >= lastVerified && now - lastVerified < ttl)
+            return;
+        let state;
+        try {
+            const client = await getClient({ chainId: channel.chainId });
+            state = await Chain.getChannelState(client, channelId, channel.escrowContract);
+        }
+        catch {
+            // Transport errors can include private RPC URLs or authentication details.
+            throw new Error('Unable to verify stream escrow');
+        }
+        validateChannelState(state);
+        lastOnChainVerified.set(channelId, now);
+    };
     const serveWebSocket = (options) => Ws.serve({
         ...options,
+        beforeCharge: beforeStreamCharge,
         onChargeCommitted: settleCharged,
         store,
     });
@@ -253,9 +302,11 @@ export function session(p) {
     });
     const transport = parameters.sse
         ? Transport.sse({
+            ...(typeof parameters.sse === 'object' ? parameters.sse : {}),
+            beforeCharge: beforeStreamCharge,
+            reusableChallenges: parameters.reusableChallenges,
             settleCharged,
             store,
-            ...(typeof parameters.sse === 'object' ? parameters.sse : undefined),
         })
         : undefined;
     const validateCredential = async ({ credential, operation, request, }) => {
@@ -267,24 +318,31 @@ export function session(p) {
             minVoucherDelta: parameters.minVoucherDelta,
             request,
         });
-        const details = await validateCredentialPayload({
-            account,
-            allowPendingClose: operation === 'broadcast',
-            challenge: credential.challenge,
-            channelStateTtl,
-            chainId: context.chainId,
-            client: context.client,
-            credentialSource: credential.source,
-            escrow: context.escrow,
-            expectedOperator: context.methodDetails.operator,
-            feePayer: context.feePayer,
-            feePayerPolicy: parameters.feePayerPolicy,
-            feeToken: context.methodDetails.feeToken,
-            lastOnChainVerified,
-            minVoucherDelta: context.minVoucherDelta,
-            payload,
-            store,
-        });
+        // A broadcast voucher is checked against the stored channel by the update that accepts it.
+        const details = operation === 'broadcast' && payload.action === 'voucher'
+            ? {
+                action: payload.action,
+                channelId: ChannelStore.normalizeChannelId(payload.channelId),
+            }
+            : await validateCredentialPayload({
+                account,
+                allowPendingClose: operation === 'broadcast',
+                challenge: credential.challenge,
+                channelStateTtl,
+                chainId: context.chainId,
+                client: context.client,
+                credentialSource: credential.source,
+                escrow: context.escrow,
+                expectedOperator: context.methodDetails.operator,
+                feePayer: context.feePayer,
+                feePayerPolicy: parameters.feePayerPolicy,
+                feeToken: context.methodDetails.feeToken,
+                lastOnChainVerified,
+                minVoucherDelta: context.minVoucherDelta,
+                payload,
+                store,
+                voucherStateMaxAge: parameters.voucherStateMaxAge,
+            });
         return {
             challenge: credential.challenge,
             credential: { ...credential, payload },
@@ -305,16 +363,46 @@ export function session(p) {
             minVoucherDelta: parameters.minVoucherDelta,
             request,
         });
+        const chargeAmount = parameters.chargeOnAcceptance &&
+            shouldChargeVoucherOnAcceptance({
+                capturedRequest: envelope?.capturedRequest,
+                payloadAction: payload.action,
+                unitType: context.request.unitType,
+            })
+            ? BigInt(context.request.amount ?? challenge.request.amount)
+            : undefined;
+        const acceptance = {};
+        const settleAcceptedCharge = (channel) => maybeSettleScheduled({
+            account,
+            client: context.client,
+            ...(context.feePayer ? { feePayer: context.feePayer } : {}),
+            feePayerPolicy: parameters.feePayerPolicy,
+            feeToken: parameters.feeToken,
+            onSessionSettlement,
+            onSessionSettlementFailure,
+            schedule: settlementSchedule,
+            store,
+            channel,
+        }).catch(ignoreRetryableSettlementFailure);
         const sessionReceipt = await broadcastCredentialPayload({
             account,
             challenge,
+            chargeAmount,
+            onCharged: (channel) => {
+                acceptance.charged = channel;
+            },
             channelStateTtl,
             chainId: context.chainId,
             client: context.client,
             credentialSource: credential.source,
             escrow: context.escrow,
             expectedOperator: context.methodDetails.operator,
-            feePayer: context.feePayer,
+            feePayer: await SponsorshipLimit.limitFeePayer({
+                chainId: context.chainId,
+                feePayer: context.feePayer,
+                limit: parameters.sponsorshipLimit,
+                payload,
+            }),
             feePayerPolicy: parameters.feePayerPolicy,
             feeToken: context.methodDetails.feeToken,
             lastOnChainVerified,
@@ -328,7 +416,16 @@ export function session(p) {
                 sseEnabled: Boolean(parameters.sse),
             }),
             store,
+            voucherStateMaxAge: parameters.voucherStateMaxAge,
         });
+        if (acceptance.charged) {
+            const settlementTxHash = await settleAcceptedCharge(acceptance.charged);
+            const receipt = {
+                ...sessionReceipt,
+                ...(settlementTxHash ? { txHash: settlementTxHash } : {}),
+            };
+            return parameters.sse ? Transport.markPrepaidSessionTick(receipt) : receipt;
+        }
         return applyVerifiedHttpAccounting({
             capturedRequest: envelope?.capturedRequest,
             payloadAction: payload.action,
@@ -337,18 +434,7 @@ export function session(p) {
             sseEnabled: Boolean(parameters.sse),
             markPrepaidReceipt: Transport.markPrepaidSessionTick,
             charge: (channelId, requestAmount) => chargeSessionChannel({ store, channelId, amount: requestAmount }),
-            settleCharged: (channel) => maybeSettleScheduled({
-                account,
-                client: context.client,
-                ...(context.feePayer ? { feePayer: context.feePayer } : {}),
-                feePayerPolicy: parameters.feePayerPolicy,
-                feeToken: parameters.feeToken,
-                onSessionSettlement,
-                onSessionSettlementFailure,
-                schedule: settlementSchedule,
-                store,
-                channel,
-            }).catch(ignoreRetryableSettlementFailure),
+            settleCharged: settleAcceptedCharge,
         });
     };
     const method = Method.toServer(Methods.session, {
@@ -364,6 +450,7 @@ export function session(p) {
             unitType,
         }),
         extensions: { serveWebSocket, settleScheduled },
+        ...(parameters.reusableChallenges ? { stableBinding: reusableSessionBinding } : {}),
         transport: deriveTransport(transport),
         preflight: parameters.bootstrap
             ? async ({ capturedRequest, credential, expires, input, options, realm, secretKey }) => {
@@ -430,6 +517,7 @@ export function session(p) {
             });
         },
     });
+    streamVerifiers.set(method, beforeStreamCharge);
     return method;
 }
 (function (session) {
@@ -444,8 +532,40 @@ export function session(p) {
  *
  * Delegates to the shared `deductFromChannel` atomic helper and translates
  * failure modes into typed errors (`InsufficientBalanceError`, `ChannelClosedError`).
+ *
+ * With `options.idempotencyKey` the channel is charged at most once per key: a retry with the same
+ * key and amount returns the channel without charging again, and the same key with a different
+ * amount throws `IdempotencyKeyConflictError`.
+ *
+ * @example
+ * ```ts
+ * // One durable job per voucher, retried under its operation ID.
+ * const channel = await Session.Server.charge(store, channelId, jobCost, {
+ *   idempotencyKey: operationId,
+ * })
+ * ```
+ */
+export async function charge(store, channelId, amount, options) {
+    return chargeSessionChannel({ ...options, store: resolveChannelStore(store), channelId, amount });
+}
+/**
+ * Returns an unused amount to a channel's `spent` at most once per idempotency key.
+ *
+ * The first outcome for a key is final. A credit is `declined` when the channel is closing or
+ * finalized, or when it would take `spent` below zero or below what settled, or may still settle,
+ * on-chain, because a close captures `max(spent, settled)`; the caller then refunds another way.
+ * `unknown` reports a store write that failed and may have committed; retrying with the same key
+ * returns the outcome that was recorded.
+ *
+ * @example
+ * ```ts
+ * const result = await Session.Server.credit(store, channelId, unused, {
+ *   idempotencyKey: `refund:${flowId}`,
+ * })
+ * if (result.status === 'declined') await refundAnotherWay()
+ * ```
  */
-export async function charge(store, channelId, amount) {
-    return chargeSessionChannel({ store, channelId, amount });
+export async function credit(store, channelId, amount, options) {
+    return ChannelStore.creditChannel(resolveChannelStore(store), channelId, amount, options);
 }
 //# sourceMappingURL=Session.js.map

package/dist/tempo/session/server/Settlement.d.ts

@@ -112,8 +112,8 @@ export declare function resolveSettlementSchedule(schedule: SettlementSchedule |
  * Computes the schedule progress for an unsettled precompile-backed channel.
  *
  * Returns `undefined` for channels that cannot be scheduled: non-precompile
- * records, channels without an accepted voucher, or channels with no unsettled
- * voucher amount.
+ * records, or channels without an accepted voucher above the settled amount and
+ * within `spent` (see {@link ChannelStore.resolveSettleableVoucher}).
  */
 export declare function resolveSettlementProgress(channel: ChannelStore.State): SettlementProgress | undefined;
 /** Returns whether the precompile channel has crossed any configured settlement threshold. */
@@ -145,7 +145,7 @@ export type ChargeSessionChannel = (channelId: Hex, amount: bigint) => Promise<C
 /** Callback used by post-verification accounting to run server-owned settlement policy. */
 export type SettleChargedSessionChannel = (channel: ChannelStore.State) => Promise<Hex | undefined>;
 /** Inputs for charging a precompile-backed session channel. */
-export type ChargeParameters = {
+export type ChargeParameters = ChannelStore.ChargeOptions & {
     /** Server-side channel store. */
     store: ChannelStore.ChannelStore;
     /** Channel ID to deduct from. */
@@ -174,6 +174,15 @@ export type ApplyVerifiedHttpAccountingParameters = {
 };
 /** Returns whether an accepted credential will authorize and charge an HTTP content response. */
 export declare function shouldApplyVerifiedHttpAccounting(parameters: Pick<ApplyVerifiedHttpAccountingParameters, 'capturedRequest' | 'payloadAction' | 'sseEnabled'>): boolean;
+/**
+ * Returns whether a voucher pays for its request in the store update that accepts it. A
+ * request-priced content request is charged exactly once, so this is the charge the HTTP
+ * accounting or the streamed response would make, without a second store update; the receipt is
+ * then marked prepaid so an SSE response does not charge again.
+ */
+export declare function shouldChargeVoucherOnAcceptance(parameters: Pick<ApplyVerifiedHttpAccountingParameters, 'capturedRequest' | 'payloadAction'> & {
+    unitType: unknown;
+}): boolean;
 /** Applies the default HTTP content charge after a session credential has been accepted. */
 export declare function applyVerifiedHttpAccounting(parameters: ApplyVerifiedHttpAccountingParameters): Promise<SessionReceipt>;
 /** Atomically deducts spend from a channel and maps store failures to typed session errors. */
@@ -238,7 +247,12 @@ export declare function getClientAccount(client: {
 export declare function assertSettlementSender(parameters: SettlementSenderParameters): void;
 /** Applies automatic settlement when the server-owned schedule is due. */
 export declare function maybeSettleScheduled(parameters: MaybeSettleScheduledParameters): Promise<Hex | undefined>;
-/** Settles the highest accepted voucher for a precompile-backed session channel. */
+/**
+ * Settles the largest accepted voucher within the channel's `spent` for a precompile-backed session
+ * channel (see {@link ChannelStore.resolveSettleableVoucher}). The escrow captures the voucher's
+ * whole cumulative amount, so a voucher above `spent`, such as the highest one after a credit, is
+ * never settled. Until the transaction can no longer land, credits keep `spent` at or above it.
+ */
 export declare function settle(store_: SessionStoreInput, client: Chain.TransactionClient, channelId_: Hex, options?: SettlementTransactionOptions): Promise<Hex>;
 /** Raised when a settlement transaction confirmed but the channel store could not record it. */
 export declare class SettlementCheckpointError extends Error {