mppx 0.8.15 → 0.8.18

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

@@ -54,6 +54,8 @@ export type HighestVoucherParameters = {
     cumulativeAmount: bigint;
     /** Candidate voucher signature. */
     signature: Hex;
+    /** Optional router-domain authorization retained for machine-token settlement. */
+    authorizationSignature?: Hex | undefined;
 };
 /** Highest accepted voucher amount plus signed voucher payload. */
 export type HighestVoucher = {
@@ -93,6 +95,8 @@ export type OpenChannelStateParameters = {
     cumulativeAmount: bigint;
     /** Voucher signature for `cumulativeAmount`. */
     signature: Hex;
+    /** Optional router-domain authorization for the initial machine-token voucher. */
+    authorizationSignature?: Hex | undefined;
     /** Latest on-chain channel state read after open. */
     state: Chain.ChannelState;
 };
@@ -134,6 +138,8 @@ export type PendingCloseUpdate = {
 };
 /** Inputs for finalizing local state after a successful close transaction. */
 export type FinalizeClosedChannelParameters = {
+    /** Router authorization paired with the close voucher on machine channels. */
+    authorizationSignature?: Hex | undefined;
     /** Amount captured to payee during close. */
     captureAmount: bigint;
     /** Normalized channel ID. */
@@ -194,6 +200,13 @@ export type VerifyAndAcceptVoucherParameters = {
     /** Signed cumulative voucher to verify and accept. */
     voucher: SignedVoucher;
 };
+/** Inputs for validating a cumulative voucher without recording it. */
+export type ValidateVoucherParameters = Omit<VerifyAndAcceptVoucherParameters, 'challenge' | 'store'>;
+/** Result of validating a cumulative voucher against persisted channel state. */
+export type VoucherValidation = {
+    /** Whether the voucher was already accepted at the same cumulative amount. */
+    alreadyAccepted: boolean;
+};
 /** Channel backend-specific fields. */
 export type BackendState = CompatibilityBackendState | PrecompileBackendState;
 /** State for records owned by a backend outside the TIP-1034 precompile path. */
@@ -284,6 +297,8 @@ export declare function markPendingClose(parameters: MarkPendingCloseParameters)
 export declare function finalizeClosedChannelState(parameters: FinalizeClosedChannelParameters): State | null;
 /** Loads a precompile-backed channel or throws a verification error. */
 export declare function loadPrecompileChannel(parameters: LoadPrecompileChannelParameters): Promise<StoredPrecompileChannel>;
+/** Verifies a cumulative voucher without changing persisted channel state. */
+export declare function validateVoucher(parameters: ValidateVoucherParameters): Promise<VoucherValidation>;
 /** Verifies a cumulative voucher and returns a session receipt after store reconciliation. */
 export declare function verifyAndAcceptVoucher(parameters: VerifyAndAcceptVoucherParameters): Promise<SessionReceipt>;
 /**

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

@@ -25,7 +25,7 @@ export function mergeActiveOnChainState(current, state) {
 }
 /** Keeps the existing higher voucher, otherwise stores the supplied candidate voucher. */
 export function resolveHighestVoucher(parameters) {
-    const { channelId, current, cumulativeAmount, signature } = parameters;
+    const { authorizationSignature, channelId, current, cumulativeAmount, signature } = parameters;
     if (current?.highestVoucherAmount && current.highestVoucherAmount > cumulativeAmount) {
         return {
             highestVoucherAmount: current.highestVoucherAmount,
@@ -34,7 +34,12 @@ export function resolveHighestVoucher(parameters) {
     }
     return {
         highestVoucherAmount: cumulativeAmount,
-        highestVoucher: { channelId, cumulativeAmount, signature },
+        highestVoucher: {
+            channelId,
+            cumulativeAmount,
+            signature,
+            ...(authorizationSignature ? { authorizationSignature } : {}),
+        },
     };
 }
 /** Derives persisted identity fields from a verified precompile channel descriptor. */
@@ -59,8 +64,9 @@ export function resolvePrecompileChannelIdentity(parameters) {
 export function openChannelState(parameters) {
     const { authorizedSigner, chainId, channelId, current, descriptor, escrow, expiringNonceHash } = parameters;
     const { state } = parameters;
-    const { cumulativeAmount, signature } = parameters;
+    const { authorizationSignature, cumulativeAmount, signature } = parameters;
     const highestVoucher = resolveHighestVoucher({
+        authorizationSignature,
         channelId,
         current,
         cumulativeAmount,
@@ -164,10 +170,11 @@ export function markPendingClose(parameters) {
 }
 /** Finalizes local channel state after a successful close transaction. */
 export function finalizeClosedChannelState(parameters) {
-    const { captureAmount, channelId, cumulativeAmount, current, signature } = parameters;
+    const { authorizationSignature, captureAmount, channelId, cumulativeAmount, current, signature } = parameters;
     if (!current)
         return current;
     const highestVoucher = resolveHighestVoucher({
+        authorizationSignature,
         channelId,
         current,
         cumulativeAmount,
@@ -196,9 +203,9 @@ export async function loadPrecompileChannel(parameters) {
         validateChannelDescriptor(descriptor, channelId, chainId, escrow, channel.payee, channel.token);
     return channel;
 }
-/** Verifies a cumulative voucher and returns a session receipt after store reconciliation. */
-export async function verifyAndAcceptVoucher(parameters) {
-    const { store, minVoucherDelta, challenge, channel, voucher, channelState, methodDetails } = parameters;
+/** Verifies a cumulative voucher without changing persisted channel state. */
+export async function validateVoucher(parameters) {
+    const { minVoucherDelta, channel, voucher, channelState, methodDetails } = parameters;
     validateChannelState(channelState);
     if (voucher.cumulativeAmount > channelState.deposit)
         throw new AmountExceedsDepositError({ reason: 'voucher amount exceeds on-chain deposit' });
@@ -214,6 +221,19 @@ export async function verifyAndAcceptVoucher(parameters) {
             reason: 'voucher cumulativeAmount is below on-chain settled amount',
         });
     if (voucher.cumulativeAmount === channel.highestVoucherAmount)
+        return { alreadyAccepted: true };
+    const delta = voucher.cumulativeAmount - channel.highestVoucherAmount;
+    if (delta < minVoucherDelta)
+        throw new DeltaTooSmallError({
+            reason: `voucher delta ${delta} below minimum ${minVoucherDelta}`,
+        });
+    return { alreadyAccepted: false };
+}
+/** Verifies a cumulative voucher and returns a session receipt after store reconciliation. */
+export async function verifyAndAcceptVoucher(parameters) {
+    const { store, challenge, channel, voucher, channelState } = parameters;
+    const validation = await validateVoucher(parameters);
+    if (validation.alreadyAccepted)
         return createSessionReceipt({
             challengeId: challenge.id,
             channelId: voucher.channelId,
@@ -221,11 +241,6 @@ export async function verifyAndAcceptVoucher(parameters) {
             spent: channel.spent,
             units: channel.units,
         });
-    const delta = voucher.cumulativeAmount - channel.highestVoucherAmount;
-    if (delta < minVoucherDelta)
-        throw new DeltaTooSmallError({
-            reason: `voucher delta ${delta} below minimum ${minVoucherDelta}`,
-        });
     const updated = await store.updateChannel(voucher.channelId, (current) => acceptVoucherStateUpdate({ channelState, current, voucher }));
     if (!updated)
         throw new ChannelNotFoundError({ reason: 'channel not found' });

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

@@ -5,21 +5,22 @@ import * as Chain from '../precompile/Chain.js';
 import * as Channel from '../precompile/Channel.js';
 import { type SessionCredentialPayload, type SessionReceipt } from '../precompile/Protocol.js';
 import * as ChannelStore from './ChannelStore.js';
+import { type ChallengePaymentFields } from './RequestState.js';
 import { type OnSessionSettlement } from './Settlement.js';
 /** Returns the effective voucher signer for a TIP-1034 descriptor. */
 export declare function authorizedSigner(descriptor: Channel.ChannelDescriptor): Address;
-/** Asserts that a credential payload includes a TIP-1034 descriptor. */
-export declare function assertDescriptor(payload: {
-    descriptor?: Channel.ChannelDescriptor | undefined;
-}): asserts payload is {
-    descriptor: Channel.ChannelDescriptor;
-};
 /** Asserts that two TIP-1034 descriptors identify the same channel. */
 export declare function assertSameDescriptor(a: Channel.ChannelDescriptor, b: Channel.ChannelDescriptor): void;
 /**
  * Validates a TIP-1034 descriptor against channel ID, server destination, and token.
  */
 export declare function validateChannelDescriptor(descriptor: Channel.ChannelDescriptor, channelId: Address | `0x${string}`, chainId: number, escrow: Address, recipient: Address, currency: Address, expectedOperator?: Address | undefined): void;
+type ResolvedCredentialRoute = {
+    allowedFeeTokens: readonly Address[];
+    expectedOperator: Address;
+    machineRouter?: Address | undefined;
+    payment: ChallengePaymentFields;
+};
 /** Validates on-chain channel state before accepting or charging a credential. */
 export declare function validateChannelState(state: Chain.ChannelState, amount?: bigint): void;
 /** Asserts that an opening channel covers the route's requested payment. */
@@ -47,8 +48,8 @@ export declare function requireSessionCredentialAction(payload: unknown): Sessio
 export declare function requireSessionCredentialPayloadHeader(payload: unknown): SessionCredentialPayloadHeader;
 /** Validates action-specific fields for a TIP-1034 session credential payload. */
 export declare function requireSessionCredentialPayload(payload: unknown): SessionCredentialPayload;
-/** Shared inputs required to verify a single precompile session credential payload. */
-export type VerifyCredentialPayloadParameters = {
+/** Shared inputs required to broadcast a verified precompile session credential payload. */
+export type BroadcastCredentialPayloadParameters = {
     /** Optional account override used for payee-side close settlement. */
     account?: viem_Account | undefined;
     /** Challenge echoed by the credential. */
@@ -69,7 +70,7 @@ export type VerifyCredentialPayloadParameters = {
     feePayer?: viem_Account | true | undefined;
     /** Optional policy for fee-sponsored close/open/top-up transactions. */
     feePayerPolicy?: Partial<FeePayer.Policy> | undefined;
-    /** Optional fee token override for close transactions. */
+    /** Optional fee token override for sponsored management and settlement transactions. */
     feeToken?: Address | undefined;
     /** Last successful on-chain refresh timestamp per channel ID. */
     lastOnChainVerified: Map<Hex, number>;
@@ -82,21 +83,39 @@ export type VerifyCredentialPayloadParameters = {
     /** Server-side channel store. */
     store: ChannelStore.ChannelStore;
 };
-/** Narrows shared credential verification inputs to one payload action. */
-export type VerifyCredentialActionParameters<action extends SessionCredentialPayload['action']> = Omit<VerifyCredentialPayloadParameters, 'payload'> & {
+/** @deprecated Use {@link BroadcastCredentialPayloadParameters}. */
+export type VerifyCredentialPayloadParameters = BroadcastCredentialPayloadParameters;
+/** Narrows shared credential broadcast inputs to one payload action. */
+export type BroadcastCredentialActionParameters<action extends SessionCredentialPayload['action']> = Omit<BroadcastCredentialPayloadParameters, 'payload'> & ResolvedCredentialRoute & {
     /** Credential payload for the selected action. */
     payload: Extract<SessionCredentialPayload, {
         action: action;
     }>;
 };
-/** Inputs for verifying an open transaction credential and initial voucher. */
-export type OpenCredentialActionParameters = VerifyCredentialActionParameters<'open'>;
-/** Inputs for verifying a top-up transaction credential. */
-export type TopUpCredentialActionParameters = VerifyCredentialActionParameters<'topUp'>;
-/** Inputs for verifying and accepting an incremental voucher credential. */
-export type VoucherCredentialActionParameters = VerifyCredentialActionParameters<'voucher'>;
-/** Inputs for verifying and settling a cooperative close credential. */
-export type CloseCredentialActionParameters = VerifyCredentialActionParameters<'close'>;
-/** Verifies a session credential payload and applies the action-specific state transition. */
+/** @deprecated Use {@link BroadcastCredentialActionParameters}. */
+export type VerifyCredentialActionParameters<action extends SessionCredentialPayload['action']> = BroadcastCredentialActionParameters<action>;
+/** Inputs for broadcasting an open transaction credential and initial voucher. */
+export type OpenCredentialActionParameters = BroadcastCredentialActionParameters<'open'>;
+/** Inputs for broadcasting a top-up transaction credential. */
+export type TopUpCredentialActionParameters = BroadcastCredentialActionParameters<'topUp'>;
+/** Inputs for broadcasting and accepting an incremental voucher credential. */
+export type VoucherCredentialActionParameters = BroadcastCredentialActionParameters<'voucher'>;
+/** Inputs for broadcasting and settling a cooperative close credential. */
+export type CloseCredentialActionParameters = BroadcastCredentialActionParameters<'close'>;
+/** Inputs for validating a session credential without applying its state transition. */
+export type ValidateCredentialPayloadParameters = Pick<BroadcastCredentialPayloadParameters, 'account' | 'channelStateTtl' | 'chainId' | 'client' | 'credentialSource' | 'escrow' | 'expectedOperator' | 'feePayer' | 'feePayerPolicy' | 'feeToken' | 'lastOnChainVerified' | 'minVoucherDelta' | 'payload' | 'store' | 'challenge'>;
+/** Non-mutating result produced by session credential validation. */
+export type CredentialPayloadValidation = {
+    /** Session action validated from the credential. */
+    action: SessionCredentialPayload['action'];
+    /** Normalized channel ID targeted by the credential. */
+    channelId: Hex;
+};
+/** Validates all action-specific session credential invariants without changing payment state. */
+export declare function validateCredentialPayload(parameters: ValidateCredentialPayloadParameters): Promise<CredentialPayloadValidation>;
+/** Broadcasts a validated session credential payload and applies its state transition. */
+export declare function broadcastCredentialPayload(context: BroadcastCredentialPayloadParameters): Promise<SessionReceipt>;
+/** @deprecated Use {@link broadcastCredentialPayload}. */
 export declare function verifyCredentialPayload(context: VerifyCredentialPayloadParameters): Promise<SessionReceipt>;
+export {};
 //# sourceMappingURL=CredentialVerification.d.ts.map