mppx 0.13.5 → 0.14.0

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

@@ -67,15 +67,14 @@ export function resolveSettlementSchedule(schedule, decimals) {
  * 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 function resolveSettlementProgress(channel) {
     if (!ChannelStore.isPrecompileState(channel))
         return undefined;
-    if (!channel.highestVoucher)
-        return undefined;
-    if (channel.highestVoucher.cumulativeAmount <= channel.settledOnChain)
+    // A settlement captures a voucher whole, so only a voucher within spend can be scheduled.
+    if (!ChannelStore.resolveSettleableVoucher(channel))
         return undefined;
     const amountBoundary = channel.lastSettlementSpent ?? channel.settledOnChain;
     const timestampBoundary = Date.parse(channel.lastSettlementAt ?? channel.createdAt);
@@ -171,6 +170,18 @@ export function shouldApplyVerifiedHttpAccounting(parameters) {
         return false;
     return isSessionContentRequest(capturedRequest);
 }
+/**
+ * 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 function shouldChargeVoucherOnAcceptance(parameters) {
+    const { capturedRequest, payloadAction, unitType } = parameters;
+    if (!capturedRequest || payloadAction !== 'voucher' || unitType !== 'request')
+        return false;
+    return isSessionContentRequest(capturedRequest);
+}
 /** Applies the default HTTP content charge after a session credential has been accepted. */
 export async function applyVerifiedHttpAccounting(parameters) {
     const { receipt, sseEnabled } = parameters;
@@ -191,12 +202,18 @@ export async function applyVerifiedHttpAccounting(parameters) {
 }
 /** Atomically deducts spend from a channel and maps store failures to typed session errors. */
 export async function chargeSessionChannel(parameters) {
-    const { store, channelId, amount } = parameters;
+    const { store, channelId, amount, idempotencyKey, retention } = parameters;
+    ChannelStore.assertIdempotencyOptions({ idempotencyKey, retention });
     let result;
     try {
-        result = await ChannelStore.deductFromChannel(store, channelId, amount);
+        result = await ChannelStore.deductFromChannel(store, channelId, amount, {
+            idempotencyKey,
+            retention,
+        });
     }
-    catch {
+    catch (error) {
+        if (error instanceof ChannelStore.IdempotencyKeyConflictError)
+            throw error;
         throw new ChannelClosedError({ reason: 'channel not found' });
     }
     if (!result.ok) {
@@ -286,7 +303,12 @@ export async function maybeSettleScheduled(parameters) {
     await markSettlementComplete({ channelId: channel.channelId, leaseOwner, store }).catch(release);
     return txHash;
 }
-/** 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 async function settle(store_, client, channelId_, options) {
     const store = resolveChannelStore(store_);
     const channelId = ChannelStore.normalizeChannelId(channelId_);
@@ -306,20 +328,72 @@ export async function settle(store_, client, channelId_, options) {
         payee: channel.payee,
         sender: account?.address,
     });
-    const amount = uint96(channel.highestVoucher.cumulativeAmount);
-    const { signature } = channel.highestVoucher;
-    // A replica behind the open or top-up that admitted this voucher rejects the settle while
-    // preparing it (e.g. `ChannelNotFound`); nothing was broadcast, so retry until it catches up.
-    const txHash = await Chain.readbackWithRetry(() => Chain.settleOnChain(client, channel.descriptor, amount, signature, escrow, account
-        ? {
-            account,
-            ...(options?.feePayer ? { feePayer: options.feePayer } : {}),
-            ...(options?.feePayerPolicy ? { feePayerPolicy: options.feePayerPolicy } : {}),
-            ...(options?.feeToken ? { feeToken: options.feeToken } : {}),
-            candidateFeeTokens: options?.candidateFeeTokens ?? [channel.token],
-        }
-        : undefined), { shouldRetry: isExecutionRevert });
-    const receipt = await Chain.waitForSuccessfulReceipt(client, txHash);
+    // Pin the transaction's expiry so the credit floor below can expire once it can no longer land.
+    const validBefore = Math.floor(Date.now() / 1000) + ChannelStore.pendingCloseValiditySeconds;
+    const pending = {
+        amount: 0n,
+        expiresAt: (validBefore + ChannelStore.pendingCloseClockSkewSeconds) * 1000,
+    };
+    const claim = {};
+    // Choosing the voucher and raising the credit floor in one update keeps a concurrent credit from
+    // lowering spent below what this transaction captures.
+    await store.updateChannel(channelId, (current) => {
+        claim.channel = current ?? undefined;
+        claim.voucher = (current && ChannelStore.resolveSettleableVoucher(current)) ?? undefined;
+        if (!current || !claim.voucher)
+            return current;
+        pending.amount = claim.voucher.cumulativeAmount;
+        const live = current.pendingSettlement && current.pendingSettlement.expiresAt > Date.now()
+            ? current.pendingSettlement
+            : undefined;
+        return {
+            ...current,
+            pendingSettlement: {
+                amount: ChannelStore.keepGreater(live?.amount ?? 0n, pending.amount),
+                expiresAt: Math.max(live?.expiresAt ?? 0, pending.expiresAt),
+            },
+        };
+    });
+    const { voucher } = claim;
+    if (!voucher || !claim.channel)
+        throw new VerificationFailedError({
+            reason: 'nothing to settle: no accepted voucher above the settled amount is within spent',
+        });
+    const claimed = claim.channel;
+    const amount = uint96(voucher.cumulativeAmount);
+    const { signature } = voucher;
+    // A revert proves the transaction will not land, so its credit floor can go at once.
+    const release = () => store
+        .updateChannel(channelId, (current) => {
+        if (current?.pendingSettlement?.amount !== pending.amount ||
+            current.pendingSettlement.expiresAt !== pending.expiresAt)
+            return current;
+        const { pendingSettlement: _, ...rest } = current;
+        return rest;
+    })
+        .catch(() => undefined);
+    let txHash;
+    let receipt;
+    try {
+        // A replica behind the open or top-up that admitted this voucher rejects the settle while
+        // preparing it (e.g. `ChannelNotFound`); nothing was broadcast, so retry until it catches up.
+        txHash = await Chain.readbackWithRetry(() => Chain.settleOnChain(client, channel.descriptor, amount, signature, escrow, account
+            ? {
+                account,
+                ...(options?.feePayer ? { feePayer: options.feePayer } : {}),
+                ...(options?.feePayerPolicy ? { feePayerPolicy: options.feePayerPolicy } : {}),
+                ...(options?.feeToken ? { feeToken: options.feeToken } : {}),
+                candidateFeeTokens: options?.candidateFeeTokens ?? [channel.token],
+                validBefore,
+            }
+            : { validBefore }), { shouldRetry: isExecutionRevert });
+        receipt = await Chain.waitForSuccessfulReceipt(client, txHash);
+    }
+    catch (error) {
+        if (isExecutionRevert(error) || error instanceof VerificationFailedError)
+            await release();
+        throw error;
+    }
     const settled = readSettledReceiptFields(Chain.getChannelEvent(receipt, 'Settled', channelId));
     const { deltaPaid, newSettled } = settled;
     if (newSettled < amount)
@@ -332,16 +406,29 @@ export async function settle(store_, client, channelId_, options) {
         });
     let checkpointError;
     await store
-        .updateChannel(channelId, (current) => current
-        ? {
-            ...current,
-            settledOnChain: newSettled > current.settledOnChain ? newSettled : current.settledOnChain,
+        .updateChannel(channelId, (current) => {
+        if (!current)
+            return current;
+        const settledOnChain = ChannelStore.keepGreater(current.settledOnChain, newSettled);
+        const { pendingSettlement, ...rest } = current;
+        return {
+            ...rest,
+            // The recorded settlement now keeps spent at or above what this transaction captured.
+            ...(pendingSettlement && pendingSettlement.amount > settledOnChain
+                ? { pendingSettlement }
+                : {}),
+            ...(current.retainedVouchers
+                ? {
+                    retainedVouchers: current.retainedVouchers.filter((retained) => retained.cumulativeAmount > settledOnChain),
+                }
+                : {}),
+            settledOnChain,
             lastSettlementAt: new Date().toISOString(),
-            // Charges accepted after the voucher was read are not covered by this transaction.
-            lastSettlementSpent: ChannelStore.keepGreater(current.lastSettlementSpent ?? 0n, channel.spent),
-            lastSettlementUnits: Math.max(current.lastSettlementUnits ?? 0, channel.units),
-        }
-        : current)
+            // Charges accepted after the voucher was chosen are not covered by this transaction.
+            lastSettlementSpent: ChannelStore.keepGreater(current.lastSettlementSpent ?? 0n, amount),
+            lastSettlementUnits: Math.max(current.lastSettlementUnits ?? 0, claimed.units),
+        };
+    })
         .catch((cause) => {
         checkpointError = { cause };
     });

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

@@ -0,0 +1,52 @@
+import { Address } from 'ox';
+import type * as Store from '../../../Store.js';
+import type { SessionCredentialPayload } from '../precompile/Protocol.js';
+/**
+ * Sponsored opens, and separately sponsored top-ups, each verified payer may make per UTC day. It is
+ * tempoxyz/mpp-proxy's `DAILY_CHANNEL_OPEN_LIMIT`, the limit its proxy applied to sponsored channel
+ * opens before the limit moved into mppx.
+ */
+export declare const defaultPerDay = 5;
+/** Limits on fee-payer-sponsored channel opens and top-ups. */
+export type Parameters = {
+    /** Atomic store holding one usage record per payer and chain. */
+    store: Store.AtomicStore;
+    /** Sponsored opens, and separately sponsored top-ups, per payer per UTC day. @default 5 */
+    perDay?: number | undefined;
+};
+/** Validates a configured limit. */
+export declare function assertParameters(parameters: Parameters | undefined): void;
+/**
+ * Returns the verified signer of a serialized Tempo transaction, lowercased, or null. A
+ * credential's `source` is client-supplied and unverified at this point, and so are the 0x78
+ * explicit sender slot and a keychain signature's account, so limits key on what the signatures
+ * prove:
+ * - a direct signature: its signer;
+ * - an access key authorized in the same transaction: the account that signed the authorization,
+ *   so fresh keys do not get a fresh quota;
+ * - an access key authorized earlier: the key itself (its account link is only checked on chain).
+ */
+export declare function verifiedPayer(serializedTransaction: string): Address.Address | null;
+/**
+ * Records one sponsored `action` for `payer` on the current UTC day. Returns false, recording
+ * nothing, once the payer has used `perDay` of them.
+ */
+export declare function reserve(store: Store.AtomicStore, parameters: {
+    action: 'open' | 'topUp';
+    chainId: number;
+    payer: string;
+    perDay?: number | undefined;
+    now?: Date | undefined;
+}): Promise<boolean>;
+/**
+ * Returns `feePayer` when the credential's open or top-up may be sponsored, and `undefined` once
+ * its verified payer used the day's sponsored transactions, or when no signature proves a payer.
+ * The transaction is then broadcast as the payer signed it, paying its own fees.
+ */
+export declare function limitFeePayer<feePayer>(parameters: {
+    chainId: number;
+    feePayer: feePayer | undefined;
+    limit: Parameters | undefined;
+    payload: SessionCredentialPayload;
+}): Promise<feePayer | undefined>;
+//# sourceMappingURL=SponsorshipLimit.d.ts.map

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

@@ -0,0 +1,107 @@
+import { Address } from 'ox';
+import { KeyAuthorization, SignatureEnvelope, TxEnvelopeTempo } from 'ox/tempo';
+/**
+ * Sponsored opens, and separately sponsored top-ups, each verified payer may make per UTC day. It is
+ * tempoxyz/mpp-proxy's `DAILY_CHANNEL_OPEN_LIMIT`, the limit its proxy applied to sponsored channel
+ * opens before the limit moved into mppx.
+ */
+export const defaultPerDay = 5;
+/** Validates a configured limit. */
+export function assertParameters(parameters) {
+    const perDay = parameters?.perDay;
+    if (perDay !== undefined && (!Number.isSafeInteger(perDay) || perDay < 0))
+        throw new Error('`sponsorshipLimit.perDay` must be a non-negative integer.');
+}
+/**
+ * The address that provably produced `signature` over `payload`, or null. secp256k1 recovery is
+ * inherently verified; P256 and WebAuthn envelopes carry a public key, so their signature is
+ * checked against it. Multisig has no single signer.
+ */
+function verifiedSigner(payload, signature) {
+    if (signature.type === 'secp256k1')
+        return SignatureEnvelope.extractAddress({ payload, signature });
+    if (signature.type === 'p256' || signature.type === 'webAuthn') {
+        const { publicKey } = signature;
+        return SignatureEnvelope.verify(signature, { payload, publicKey })
+            ? Address.fromPublicKey(publicKey)
+            : null;
+    }
+    return null;
+}
+/**
+ * Returns the verified signer of a serialized Tempo transaction, lowercased, or null. A
+ * credential's `source` is client-supplied and unverified at this point, and so are the 0x78
+ * explicit sender slot and a keychain signature's account, so limits key on what the signatures
+ * prove:
+ * - a direct signature: its signer;
+ * - an access key authorized in the same transaction: the account that signed the authorization,
+ *   so fresh keys do not get a fresh quota;
+ * - an access key authorized earlier: the key itself (its account link is only checked on chain).
+ */
+export function verifiedPayer(serializedTransaction) {
+    if (!/^0x7[68][0-9a-fA-F]+$/.test(serializedTransaction))
+        return null;
+    try {
+        const { from: _claimedSender, ...fields } = TxEnvelopeTempo.deserialize(serializedTransaction);
+        const { signature } = fields;
+        if (!signature)
+            return null;
+        const envelope = TxEnvelopeTempo.from(fields);
+        if (signature.type !== 'keychain')
+            return lower(verifiedSigner(TxEnvelopeTempo.getSignPayload(envelope), signature));
+        // Keychain V2 signs over the account too: keccak256(0x04 || sigHash || userAddress).
+        const accessKey = verifiedSigner(TxEnvelopeTempo.getSignPayload(envelope, signature.version === 'v2' ? { from: signature.userAddress } : {}), signature.inner);
+        if (!accessKey)
+            return null;
+        const authorization = fields.keyAuthorization;
+        if (!authorization)
+            return lower(accessKey);
+        if (!authorization.signature || !Address.isEqual(authorization.address, accessKey))
+            return null;
+        return lower(verifiedSigner(KeyAuthorization.getSignPayload(authorization), authorization.signature));
+    }
+    catch {
+        return null;
+    }
+}
+function lower(address) {
+    return address ? address.toLowerCase() : null;
+}
+/**
+ * Records one sponsored `action` for `payer` on the current UTC day. Returns false, recording
+ * nothing, once the payer has used `perDay` of them.
+ */
+export async function reserve(store, parameters) {
+    const { action, chainId, payer, perDay = defaultPerDay } = parameters;
+    const day = (parameters.now ?? new Date()).toISOString().slice(0, 10);
+    const key = `mppx:session:sponsorship:${chainId}:${payer.toLowerCase()}`;
+    return store.update(key, (current) => {
+        const usage = current?.day === day ? current : { day, open: 0, topUp: 0 };
+        if (usage[action] >= perDay)
+            return { op: 'noop', result: false };
+        return { op: 'set', value: { ...usage, [action]: usage[action] + 1 }, result: true };
+    });
+}
+/**
+ * Returns `feePayer` when the credential's open or top-up may be sponsored, and `undefined` once
+ * its verified payer used the day's sponsored transactions, or when no signature proves a payer.
+ * The transaction is then broadcast as the payer signed it, paying its own fees.
+ */
+export async function limitFeePayer(parameters) {
+    const { chainId, feePayer, limit, payload } = parameters;
+    if (!feePayer || !limit)
+        return feePayer;
+    if (payload.action !== 'open' && payload.action !== 'topUp')
+        return feePayer;
+    const payer = verifiedPayer(payload.transaction);
+    if (!payer)
+        return undefined;
+    const allowed = await reserve(limit.store, {
+        action: payload.action,
+        chainId,
+        payer,
+        perDay: limit.perDay,
+    });
+    return allowed ? feePayer : undefined;
+}
+//# sourceMappingURL=SponsorshipLimit.js.map

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

@@ -27,9 +27,8 @@ export type { SessionController } from './MeteredStream.js';
  * 2. If balance is sufficient, emits `event: message` with the value.
  * 3. If balance is exhausted, emits `event: payment-need-voucher`
  *    and polls store until the client tops up the channel.
- * 4. Commits the reserved charge immediately before the chunk is emitted. If a
- *    manual generator completes after charging without yielding another chunk,
- *    commits that terminal charge on successful completion.
+ * 4. Commits automatic charges before emission and manual charges before
+ *    `stream.charge()` resolves, retaining them on cancellation or failure.
  * 5. On generator completion, emits a final `event: payment-receipt`.
  *
  * Returns a `ReadableStream<Uint8Array>` suitable for use as an HTTP response body.
@@ -43,6 +42,8 @@ export declare namespace serve {
         challengeId: string;
         tickCost: bigint;
         generate: AsyncIterable<string> | ((stream: SessionController) => AsyncIterable<string>);
+        /** Verifies live escrow before charging and delivering stream items. */
+        beforeCharge?: MeteredStreamOptions['beforeCharge'];
         /** Callback invoked after each nonzero stream charge is committed. */
         onChargeCommitted?: MeteredStreamOptions['onChargeCommitted'];
         pollIntervalMs?: number | undefined;

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

@@ -26,9 +26,8 @@ export { extractData, formatMessageEvent, formatNeedVoucherEvent, formatReceiptE
  * 2. If balance is sufficient, emits `event: message` with the value.
  * 3. If balance is exhausted, emits `event: payment-need-voucher`
  *    and polls store until the client tops up the channel.
- * 4. Commits the reserved charge immediately before the chunk is emitted. If a
- *    manual generator completes after charging without yielding another chunk,
- *    commits that terminal charge on successful completion.
+ * 4. Commits automatic charges before emission and manual charges before
+ *    `stream.charge()` resolves, retaining them on cancellation or failure.
  * 5. On generator completion, emits a final `event: payment-receipt`.
  *
  * Returns a `ReadableStream<Uint8Array>` suitable for use as an HTTP response body.
@@ -44,6 +43,7 @@ export function serve(options) {
         channelId,
         tickCost,
         generate,
+        beforeCharge: options.beforeCharge,
         onChargeCommitted: options.onChargeCommitted,
         pollIntervalMs,
         prepaidUnits: options.prepaidUnits,

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

@@ -1,3 +1,4 @@
+import { type SessionCredentialContext } from '../precompile/Protocol.js';
 import * as ChannelStore from './ChannelStore.js';
 import type { MeteredStreamOptions, SessionController } from './MeteredStream.js';
 import type { SettleChargedSessionChannel } from './Settlement.js';
@@ -16,6 +17,11 @@ export type SessionRouteResult = {
 };
 /** HTTP route used to perform a WebSocket payment probe. */
 export type SessionRoute = (request: Request) => Promise<SessionRouteResult>;
+type StreamContext = {
+    challengeId: string;
+    channelId: SessionCredentialContext['channelId'];
+    tickCost: bigint;
+};
 /**
  * Bridge a WebSocket connection to a Tempo session payment flow.
  *
@@ -47,7 +53,9 @@ export declare namespace serve {
         /** Payment route handler. Receives synthetic `POST` requests with only
          *  the `Authorization` header — no cookies, bodies, or upgrade headers. */
         route: SessionRoute;
-        /** Optional low-level hook invoked after each committed stream charge. */
+        /** Verifies live escrow before charging and delivering stream items. */
+        beforeCharge?: ((channelId: StreamContext['channelId']) => void | Promise<void>) | undefined;
+        /** Callback invoked after each nonzero stream charge is committed. */
         onChargeCommitted?: MeteredStreamOptions['onChargeCommitted'];
         /** @deprecated Use `onChargeCommitted`. */
         settleScheduled?: SettleChargedSessionChannel | undefined;

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

@@ -65,6 +65,7 @@ export async function serve(options) {
                 channelId: context.channelId,
                 tickCost: context.tickCost,
                 generate,
+                beforeCharge: () => options.beforeCharge?.(context.channelId),
                 onChargeCommitted: options.onChargeCommitted ?? options.settleScheduled,
                 pollIntervalMs,
                 signal: abortController.signal,

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

@@ -1,4 +1,12 @@
-export { charge, session, settle, settleBatch } from './Session.js';
+export { charge, credit, session, settle, settleBatch } from './Session.js';
+/** Close supervision for payer close requests on idle channels. */
+export { superviseCloses } from './CloseSupervisor.js';
+export type { CloseSupervision, CloseSupervisionOutcome, SuperviseClosesParameters, } from './CloseSupervisor.js';
+/** Idempotent charge and credit options and outcomes, and the voucher a settlement captures. */
+export { IdempotencyKeyConflictError, resolveSettleableVoucher } from './ChannelStore.js';
+export type { ChargeOptions, CreditDeclineReason, CreditOptions, CreditResult, State as ChannelState, } from './ChannelStore.js';
+/** Limits on fee-payer-sponsored channel opens and top-ups. */
+export type { Parameters as SponsorshipLimitParameters } from './SponsorshipLimit.js';
 /** SSE helpers and types for Tempo session streams. */
 export * as Sse from './Sse.js';
 /** Server-side automatic settlement schedule. */

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

@@ -1,4 +1,8 @@
-export { charge, session, settle, settleBatch } from './Session.js';
+export { charge, credit, session, settle, settleBatch } from './Session.js';
+/** Close supervision for payer close requests on idle channels. */
+export { superviseCloses } from './CloseSupervisor.js';
+/** Idempotent charge and credit options and outcomes, and the voucher a settlement captures. */
+export { IdempotencyKeyConflictError, resolveSettleableVoucher } from './ChannelStore.js';
 /** SSE helpers and types for Tempo session streams. */
 export * as Sse from './Sse.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mppx",
   "type": "module",
-  "version": "0.13.5",
+  "version": "0.14.0",
   "main": "./dist/index.js",
   "license": "MIT",
   "homepage": "https://github.com/wevm/mppx#readme",