mppx 0.13.6 → 0.14.0

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

@@ -18,8 +18,9 @@ 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>;
@@ -208,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, {
@@ -223,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

@@ -28,9 +28,10 @@ import { broadcastCredentialPayload, validateCredentialPayload } from './Credent
 import { requireSessionCredentialPayload, validateChannelState } from './CredentialVerification.js';
 import { resolveCredentialVerificationContext, resolveSessionChannelId, resolveSessionSnapshot, resolveSessionPaymentRequest, } from './RequestState.js';
 import { respondToSessionCredential } from './RequestState.js';
-import { applyVerifiedHttpAccounting, chargeSessionChannel, shouldApplyVerifiedHttpAccounting, shouldChargeVoucherOnAcceptance, } 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. */
@@ -218,6 +219,7 @@ 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);
@@ -395,7 +397,12 @@ export function session(p) {
             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,
@@ -525,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. */
@@ -247,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 {

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);
@@ -203,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) {
@@ -298,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_);
@@ -318,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)
@@ -344,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/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.6",
+  "version": "0.14.0",
   "main": "./dist/index.js",
   "license": "MIT",
   "homepage": "https://github.com/wevm/mppx#readme",