mppx 0.8.7 → 0.8.9

package/src/cli/validate.test.ts

@@ -677,3 +677,97 @@ describe('validate: multi-challenge', () => {
     expect(output).toContain('Amount is valid integer string (Got: 1.50)')
   })
 })
+
+describe('validate: payment methods coverage', () => {
+  test(
+    'every method in Constants.Methods produces a payment result',
+    { timeout: 15_000 },
+    async () => {
+      const methods = Object.values(Constants.Methods)
+      const challenges = methods.map((method) => ({
+        id: `${method}-id`,
+        realm: 'localhost',
+        method,
+        intent: 'charge',
+        request: { amount: '100', currency: 'usd', methodDetails: {} },
+        expires: new Date(Date.now() + 300_000).toISOString(),
+      })) as Challenge.Challenge[]
+
+      const header = challenges.map((c) => Challenge.serialize(c)).join(', ')
+      const server = await testServer((req, res) => {
+        const url = new URL(req.url!, 'http://localhost')
+        if (url.pathname === '/openapi.json') {
+          res.setHeader('Content-Type', 'application/json')
+          res.end(
+            JSON.stringify({
+              openapi: '3.1.0',
+              info: { title: 'T', version: '1' },
+              paths: {
+                '/api/test': {
+                  post: { 'x-payment-info': { amount: '100' }, responses: { '402': {} } },
+                },
+              },
+            }),
+          )
+          return
+        }
+        res.writeHead(402, { [Constants.Headers.wwwAuthenticate]: header })
+        res.end()
+      })
+      const { output } = await serve(['validate', server.url, '--outputJson', '--yes'])
+      const jsonStart = output.indexOf('{')
+      const jsonEnd = output.lastIndexOf('}')
+      const result = JSON.parse(output.slice(jsonStart, jsonEnd + 1))
+      const paymentLabels = result.endpoints[0].payment.map((r: { label: string }) => r.label)
+      for (const method of methods) {
+        expect(paymentLabels.some((l: string) => l.includes(`[${method}]`))).toBe(true)
+      }
+    },
+  )
+})
+
+describe('validate: JSON mode', () => {
+  function mainnetChallenge() {
+    return makeChallenge({
+      request: {
+        amount: '10000',
+        currency: '0x20c0000000000000000000000000000000000000',
+        recipient: '0x1234567890123456789012345678901234567890',
+        methodDetails: { chainId: 4217 },
+      },
+    } as Partial<Challenge.Challenge>)
+  }
+
+  function parseJson(output: string) {
+    const jsonStart = output.indexOf('{')
+    const jsonEnd = output.lastIndexOf('}')
+    return JSON.parse(output.slice(jsonStart, jsonEnd + 1))
+  }
+
+  test('does not prompt (non-interactive)', { timeout: 15_000 }, async () => {
+    const server = await mppServer(mainnetChallenge())
+    const { output } = await serve(['validate', server.url, '--outputJson'])
+    const result = parseJson(output)
+    const allPayment = result.endpoints.flatMap((ep: { payment: unknown[] }) => ep.payment)
+    expect(allPayment.length).toBeGreaterThan(0)
+    expect(allPayment.every((r: { severity: string }) => r.severity === 'skip')).toBe(true)
+  })
+
+  test('no console leaks before JSON', { timeout: 15_000 }, async () => {
+    const server = await mppServer(mainnetChallenge())
+    const { output } = await serve(['validate', server.url, '--outputJson', '--yes'])
+    const jsonStart = output.indexOf('{')
+    expect(jsonStart).toBeGreaterThanOrEqual(0)
+    const beforeJson = output.slice(0, jsonStart)
+    expect(beforeJson).not.toContain('Using wallet')
+    expect(beforeJson).not.toContain('Auto-approved')
+    expect(beforeJson).not.toContain('Attempting')
+  })
+
+  test('includes suggestions', { timeout: 15_000 }, async () => {
+    const server = await mppServer(mainnetChallenge())
+    const { output } = await serve(['validate', server.url, '--outputJson', '--yes'])
+    const result = parseJson(output)
+    expect(Array.isArray(result.suggestions)).toBe(true)
+  })
+})

package/src/tempo/internal/fee-payer.test.ts

@@ -565,7 +565,10 @@ describe('fillHostedFeePayerTransaction', () => {
               },
             },
           },
-          (_key, value) => (typeof value === 'bigint' ? toHex(value) : value),
+          (key, value) => {
+            if (key === 'yParity') return toHex(value)
+            return typeof value === 'bigint' ? toHex(value) : value
+          },
         ),
       )
     })

package/src/tempo/internal/fee-payer.ts

@@ -224,7 +224,10 @@ export async function fillHostedFeePayerTransaction(parameters: {
 
   assertAllowedFeeToken({ feeToken: filled.feeToken }, allowedFeeTokens)
 
-  const feePayerSignature = filled.feePayerSignature
+  const feePayerSignature = {
+    ...(filled.feePayerSignature as Record<string, unknown>),
+    yParity: Number((filled.feePayerSignature as { yParity?: unknown }).yParity),
+  }
   const feeToken = filled.feeToken
 
   // Recover the concrete sponsor address so the simulation can use a concrete

package/src/tempo/session/precompile/Chain.test.ts

@@ -613,6 +613,48 @@ describe('precompile broadcastOpenTransaction', () => {
     expect(simulationIndex).toBeLessThan(broadcastIndex)
   })
 
+  test('hosted fee-payer relays a sender-signed open without local co-signing', async () => {
+    const rpcMethods: string[] = []
+    const serializedTransaction = await createOpenTransaction({ signed: true })
+    const transaction = Transaction.deserialize(
+      serializedTransaction as Transaction.TransactionSerializedTempo,
+    )
+    const payer = transaction.from!
+    const expiringNonceHash = Channel.computeExpiringNonceHash(
+      Channel.transactionForExpiringNonceHash({ feePayer: true, transaction }),
+      { sender: payer },
+    )
+    const expectedDescriptor = { ...descriptor, payer, expiringNonceHash }
+    const channelId = Channel.computeId({
+      ...expectedDescriptor,
+      chainId,
+      escrow: tip20ChannelEscrow,
+    })
+    const state = { settled: 0n, deposit, closeRequestedAt: 0 }
+
+    await Chain.broadcastOpenTransaction({
+      chainId,
+      client: createMockClient({
+        channel: { descriptor: expectedDescriptor, state },
+        receipt: receipt([openedLog({ channelId, expiringNonceHash })]),
+        rpcMethods,
+      }),
+      escrowContract: tip20ChannelEscrow,
+      expectedAuthorizedSigner: descriptor.authorizedSigner,
+      expectedChannelId: channelId,
+      expectedCurrency: descriptor.token,
+      expectedExpiringNonceHash: expiringNonceHash,
+      expectedOperator: descriptor.operator,
+      expectedPayee: descriptor.payee,
+      expectedPayer: payer,
+      feePayer: true,
+      serializedTransaction,
+    })
+
+    expect(rpcMethods).toContain('eth_sendRawTransaction')
+    expect(rpcMethods).not.toContain('eth_sendRawTransactionSync')
+  })
+
   test('rejects expiring nonce hash mismatches before broadcasting', async () => {
     const serializedTransaction = await createOpenTransaction()
 

package/src/tempo/session/precompile/Chain.ts

@@ -406,7 +406,7 @@ type ParsedPrecompileCredentialTransaction = {
 
 function parsePrecompileCredentialTransaction(parameters: {
   escrowContract: Address
-  feePayer?: Account | undefined
+  feePayer?: Account | true | undefined
   label: 'open' | 'topUp'
   serializedTransaction: Hex
 }): ParsedPrecompileCredentialTransaction {
@@ -668,8 +668,8 @@ export type SendCredentialTransactionParameters = {
   allowedFeeTokens?: readonly Address[] | undefined
   /** Human-readable transaction details used by fee-payer policy hooks. */
   details: Record<string, string>
-  /** Fee-payer account used to co-sign Tempo transactions. */
-  feePayer?: Account | undefined
+  /** Fee-payer account, or `true` when the client transport delegates co-signing to a hosted relay. */
+  feePayer?: Account | true | undefined
   /** Optional fee-payer policy enforced before co-signing. */
   feePayerPolicy?: Partial<FeePayer.Policy> | undefined
   /** Management transaction kind, used for validation errors. */
@@ -704,6 +704,11 @@ export async function sendCredentialTransaction(parameters: SendCredentialTransa
     throw new BadRequestError({ reason: 'Only Tempo (0x76/0x78) transactions are supported' })
   assertSenderSigned(transaction)
 
+  if (feePayer === true) {
+    const txHash = await sendTransaction(client, serializedTransaction)
+    return waitForSuccessfulReceipt(client, txHash)
+  }
+
   await simulateTempoTransaction(client, transaction)
 
   const sponsored = FeePayer.prepareSponsoredTransaction({
@@ -771,8 +776,8 @@ export type BroadcastOpenTransactionParameters = {
   expectedPayee: Address
   /** Payer expected to have signed the open transaction. */
   expectedPayer: Address
-  /** Fee-payer account used to co-sign sponsored open transactions. */
-  feePayer?: Account | undefined
+  /** Fee-payer account, or `true` when the client transport delegates co-signing to a hosted relay. */
+  feePayer?: Account | true | undefined
   /** Optional fee-payer policy enforced before co-signing. */
   feePayerPolicy?: Partial<FeePayer.Policy> | undefined
   /** Client-signed serialized open transaction. */
@@ -895,8 +900,8 @@ export type BroadcastTopUpTransactionParameters = {
   expectedChannelId: Hex
   /** Payment token expected for sponsored transaction fee token checks. */
   expectedCurrency: Address
-  /** Fee-payer account used to co-sign sponsored top-up transactions. */
-  feePayer?: Account | undefined
+  /** Fee-payer account, or `true` when the client transport delegates co-signing to a hosted relay. */
+  feePayer?: Account | true | undefined
   /** Optional fee-payer policy enforced before co-signing. */
   feePayerPolicy?: Partial<FeePayer.Policy> | undefined
   /** Client-signed serialized top-up transaction. */

package/src/tempo/session/server/CredentialVerification.ts

@@ -334,8 +334,8 @@ export type VerifyCredentialPayloadParameters = {
   escrow: Address
   /** Operator address advertised in the HMAC-bound challenge details. */
   expectedOperator?: Address | undefined
-  /** Optional fee-payer account for fee-sponsored management transactions. */
-  feePayer?: viem_Account | undefined
+  /** Fee-payer account, or `true` when the client transport delegates co-signing to a hosted relay. */
+  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. */
@@ -714,7 +714,7 @@ async function handleCloseCredential(
       account
         ? {
             account,
-            ...(parameters.feePayer ? { feePayer: parameters.feePayer } : {}),
+            ...(typeof parameters.feePayer === 'object' ? { feePayer: parameters.feePayer } : {}),
             ...(parameters.feePayerPolicy ? { feePayerPolicy: parameters.feePayerPolicy } : {}),
             ...(parameters.feeToken ? { feeToken: parameters.feeToken } : {}),
             candidateFeeTokens: [channel.token],

package/src/tempo/session/server/RequestState.ts

@@ -27,6 +27,7 @@ import {
   resolveCredentialFeePayer,
   resolveRequestFeePayer,
   type ParameterFeePayer,
+  type ResolvedFeePayer,
 } from './Settlement.js'
 
 /** Inputs used to build server bootstrap hints for a reusable session channel. */
@@ -267,8 +268,8 @@ export type ResolveSessionPaymentRequestParameters = {
 
 /** Inputs used to resolve shared context for credential verification. */
 export type ResolveCredentialVerificationContextParameters = {
-  /** Default configured fee-payer account, when enabled. */
-  feePayer?: viem_Account | undefined
+  /** Configured local fee payer, hosted relay URL, or sponsorship flag. */
+  feePayer?: ParameterFeePayer
   /** Resolves a viem client for the challenge chain ID. */
   getClient(parameters: {
     chainId: number
@@ -294,7 +295,7 @@ export type CredentialVerificationContext = {
   /** Client for precompile reads and transaction broadcasts. */
   client: PrecompileChain.TransactionClient
   /** Fee payer authorized for this credential, when allowed. */
-  feePayer?: viem_Account | undefined
+  feePayer?: ResolvedFeePayer
   /** Minimum allowed voucher delta in raw token units. */
   minVoucherDelta: bigint
 }

package/src/tempo/session/server/Session.ts

@@ -315,9 +315,11 @@ export function session<const parameters extends session.Parameters>(
 
   const store = ChannelStore.fromStore(rawStore)
   const lastOnChainVerified = new Map<Hex, number>()
-  const { account, feePayer, recipient } = Account.resolve(parameters)
+  const { account, feePayer, feePayerUrl, recipient } = Account.resolve(parameters)
+  const configuredFeePayer = feePayer ?? feePayerUrl
   const getClient = Client.getResolver({
     chain: tempo_chain,
+    feePayerUrl,
     getClient: parameters.getClient,
     rpcUrl: defaults.rpcUrl,
   })
@@ -326,6 +328,7 @@ export function session<const parameters extends session.Parameters>(
     chainId: parameters.chainId,
     currency,
     decimals,
+    feePayer: parameters.feePayer,
     getClient: parameters.getClient,
     recipient,
     store: rawStore,
@@ -401,7 +404,7 @@ export function session<const parameters extends session.Parameters>(
       const payload = requireSessionCredentialPayload(credential.payload)
       const context = await resolveCredentialVerificationContext({
         decimals,
-        feePayer,
+        feePayer: configuredFeePayer,
         getClient,
         minVoucherDelta: parameters.minVoucherDelta,
         request,
@@ -438,7 +441,7 @@ export function session<const parameters extends session.Parameters>(
           maybeSettleScheduled({
             account,
             client: context.client,
-            feePayer: context.feePayer,
+            ...(typeof context.feePayer === 'object' ? { feePayer: context.feePayer } : {}),
             feePayerPolicy: parameters.feePayerPolicy,
             feeToken: parameters.feeToken,
             schedule: settlementSchedule,

package/src/tempo/session/server/Settlement.test.ts

@@ -23,6 +23,7 @@ describe('FeePayerResolution', () => {
   const requestFeePayer = privateKeyToAccount(
     '0x5de4111a56d1f1ad3c74c8a3be6fba32114d0f9f8e9e4b0d4d4f5a7833f1b6c9',
   )
+  const feePayerUrl = 'https://fee-payer.example/relay'
 
   function credential(): Credential.Credential {
     return {
@@ -60,6 +61,13 @@ describe('FeePayerResolution', () => {
           parameterFeePayer: true,
         }),
       ).toBe(true)
+
+      expect(
+        resolveRequestFeePayer({
+          credential: null,
+          parameterFeePayer: feePayerUrl,
+        }),
+      ).toBe(true)
     })
 
     test('does not advertise fee-payer support when request disables it', () => {
@@ -106,6 +114,14 @@ describe('FeePayerResolution', () => {
         }),
       ).toBe(defaultFeePayer)
 
+      expect(
+        resolveCredentialFeePayer({
+          feePayer: feePayerUrl,
+          methodDetails: { feePayer: true },
+          request: { feePayer: true },
+        }),
+      ).toBe(true)
+
       expect(
         resolveCredentialFeePayer({
           feePayer: defaultFeePayer,

package/src/tempo/session/server/Settlement.ts

@@ -32,6 +32,9 @@ import * as ChannelStore from './ChannelStore.js'
 /** Fee-payer parameter accepted by the server session method. */
 export type ParameterFeePayer = viem_Account | string | true | undefined
 
+/** Resolved fee-payer mode for credential-time transaction submission. */
+export type ResolvedFeePayer = viem_Account | true | undefined
+
 /** Minimum method details needed to decide credential-time fee sponsorship. */
 export type CredentialFeePayerMethodDetails = {
   /** Whether the challenge advertised fee-payer support. */
@@ -56,8 +59,8 @@ export type ResolveCredentialFeePayerParameters = {
   request: unknown
   /** Challenge method details echoed by the credential. */
   methodDetails: CredentialFeePayerMethodDetails
-  /** Default fee-payer account resolved from server parameters. */
-  feePayer?: viem_Account | undefined
+  /** Configured local fee payer, hosted relay URL, or sponsorship flag. */
+  feePayer?: ParameterFeePayer
 }
 
 /** Fee-payer value read from an untrusted credential challenge request. */
@@ -89,20 +92,28 @@ export function resolveRequestFeePayer(
 
   const account = typeof requestFeePayer === 'object' ? requestFeePayer : defaultFeePayer
   if (credential) return account ?? undefined
-  if (account || defaultFeePayer || parameterFeePayer === true) return true
+  if (
+    account ||
+    defaultFeePayer ||
+    parameterFeePayer === true ||
+    typeof parameterFeePayer === 'string'
+  )
+    return true
   return undefined
 }
 
 /** Resolves the fee-payer account allowed for an incoming credential. */
 export function resolveCredentialFeePayer(
   parameters: ResolveCredentialFeePayerParameters,
-): viem_Account | undefined {
+): ResolvedFeePayer {
   const { feePayer, methodDetails, request } = parameters
   const requestFeePayer = readRequestFeePayer(request)
   const requestAllowsFeePayer =
     requestFeePayer === undefined || requestFeePayer === true || typeof requestFeePayer === 'object'
   if (methodDetails.feePayer !== true || !requestAllowsFeePayer) return undefined
-  return typeof requestFeePayer === 'object' ? requestFeePayer : feePayer
+  if (typeof requestFeePayer === 'object') return requestFeePayer
+  if (typeof feePayer === 'object') return feePayer
+  return typeof feePayer === 'string' ? true : undefined
 }
 
 /** Declarative server-side settlement cadence for automatic session settlement. */

package/src/validation/core.ts

@@ -1,3 +1,6 @@
+import type { Chain } from 'viem'
+import * as viemChains from 'viem/chains'
+
 import { validateChallenge, validateErrorHandling } from '../cli/validate/challenge.js'
 import {
   buildUrl,
@@ -25,6 +28,7 @@ export type ValidateOptions = {
   verbose?: boolean | undefined
   yes?: boolean | undefined
   skipPayment?: boolean | undefined
+  interactive?: boolean | undefined
   discoveryPath?: string | undefined
   onPaymentResults?: (results: CheckResult[]) => void
 }
@@ -50,14 +54,7 @@ export type ValidateResult = {
   discovery: DiscoveryResult
   endpoints: EndpointValidationResult[]
   summary: { passed: number; failed: number; warnings: number; skipped: number }
-  flags: {
-    sawMppEndpoint: boolean
-    sawNonMppPaymentEndpoint: boolean
-    sawMalformedChallenge: boolean
-    sawTestnet: boolean
-    sawMainnet: boolean
-    paymentSucceeded: boolean
-  }
+  suggestions: string[]
 }
 
 export type ValidateEvent =
@@ -69,8 +66,10 @@ export type ValidateEvent =
       results: CheckResult[]
       isMpp: boolean
       isTestnet: boolean
+      isMainnet: boolean
       isNonMppPayment: boolean
       isMalformedChallenge: boolean
+      methods: string[]
     }
   | { phase: 'errorHandling'; endpoint: EndpointSpec; results: CheckResult[] }
   | {
@@ -102,26 +101,25 @@ export async function* validateStream(options: ValidateOptions): AsyncGenerator<
       }
     }
 
-    const { results: challengeResults, resolvedBody } = await validateChallenge(
-      baseUrl,
-      endpoint,
-      verbose,
-      {
-        body,
-        query: options.query,
-        discoveryDoc: discovery.doc ?? undefined,
-      },
-    )
+    const {
+      results: challengeResults,
+      resolvedBody,
+      challenges: parsedChallenges,
+    } = await validateChallenge(baseUrl, endpoint, verbose, {
+      body,
+      query: options.query,
+      discoveryDoc: discovery.doc ?? undefined,
+    })
     const effectiveBody = resolvedBody ?? body
     const isMpp = challengeResults.some(
       (r) => r.severity === 'pass' && r.label === 'Challenge parseable',
     )
-    const isTestnet = challengeResults.some(
-      (r) =>
-        r.severity === 'pass' &&
-        r.label.endsWith('Valid currency address') &&
-        r.detail === 'testnet',
-    )
+    const chainIds = (parsedChallenges ?? [])
+      .filter((ch) => ch.method !== 'stripe')
+      .map((ch) => ((ch.request as Record<string, unknown>).methodDetails as any)?.chainId)
+      .filter((id): id is number => typeof id === 'number')
+    const isTestnet = chainIds.some(chainIsTestnet)
+    const isMainnet = chainIds.some((id) => !chainIsTestnet(id))
     const isNonMppPayment =
       !isMpp && challengeResults.some((r) => r.label === 'Not an MPP endpoint')
     const hasPaymentScheme = challengeResults.some(
@@ -132,14 +130,18 @@ export async function* validateStream(options: ValidateOptions): AsyncGenerator<
     )
     const isMalformedChallenge = !isMpp && hasPaymentScheme && challengeFailed
 
+    const methods = parsedChallenges?.map((c) => c.method) ?? []
+
     yield {
       phase: 'challenge',
       endpoint,
       results: challengeResults,
       isMpp,
       isTestnet,
+      isMainnet,
       isNonMppPayment,
       isMalformedChallenge,
+      methods,
     }
 
     if (isMpp) {
@@ -155,6 +157,8 @@ export async function* validateStream(options: ValidateOptions): AsyncGenerator<
           body: effectiveBody,
           query: options.query,
           yes: options.yes,
+          silent: !onResults,
+          interactive: options.interactive,
           ...(onResults && { onResults }),
         })
         const succeeded = paymentResults.some(
@@ -175,10 +179,6 @@ export async function validate(options: ValidateOptions): Promise<ValidateResult
 
   let sawTestnet = false
   let sawMainnet = false
-  let paymentSucceeded = false
-  let sawMppEndpoint = false
-  let sawNonMppPaymentEndpoint = false
-  let sawMalformedChallenge = false
 
   for await (const event of validateStream(options)) {
     switch (event.phase) {
@@ -198,19 +198,15 @@ export async function validate(options: ValidateOptions): Promise<ValidateResult
       case 'challenge':
         if (current) current.challenge = event.results
         if (event.isMpp) {
-          sawMppEndpoint = true
           if (event.isTestnet) sawTestnet = true
-          else sawMainnet = true
+          if (event.isMainnet) sawMainnet = true
         }
-        if (event.isNonMppPayment) sawNonMppPaymentEndpoint = true
-        if (event.isMalformedChallenge) sawMalformedChallenge = true
         break
       case 'errorHandling':
         if (current) current.errorHandling = event.results
         break
       case 'payment':
         if (current) current.payment = event.results
-        if (event.succeeded) paymentSucceeded = true
         break
     }
   }
@@ -235,20 +231,50 @@ export async function validate(options: ValidateOptions): Promise<ValidateResult
 
   if (!discovery) throw new Error('Discovery phase did not complete')
 
+  const suggestions = computeSuggestions(endpointResults, { sawTestnet, sawMainnet })
+
   return {
     url: baseUrl,
     discovery,
     endpoints: endpointResults,
     summary,
-    flags: {
-      sawMppEndpoint,
-      sawNonMppPaymentEndpoint,
-      sawMalformedChallenge,
-      sawTestnet,
-      sawMainnet,
-      paymentSucceeded,
-    },
+    suggestions,
+  }
+}
+
+function computeSuggestions(
+  endpoints: EndpointValidationResult[],
+  flags: { sawTestnet: boolean; sawMainnet: boolean },
+): string[] {
+  const steps: string[] = []
+  const allResults = endpoints.flatMap((ep) => [...ep.challenge, ...ep.payment])
+
+  const sawCryptoMainnet = flags.sawMainnet
+  const sawCryptoTestnet = flags.sawTestnet
+  const sawStripeLive = allResults.some(
+    (r) => r.label.includes('[stripe]') && r.label.includes('livemode'),
+  )
+
+  if (sawCryptoMainnet && !sawCryptoTestnet) {
+    steps.push(
+      'Validate your testnet server to test without real funds (Tempo wallets are automatically provisioned).',
+    )
+  } else if (sawCryptoTestnet && !sawCryptoMainnet) {
+    steps.push('Validate your mainnet server to confirm real payments work end-to-end.')
   }
+  if (sawStripeLive) {
+    steps.push(
+      'Validate your testmode Stripe server to test card payments end-to-end (auto-pays with test card).',
+    )
+  }
+
+  return steps
+}
+
+const allChains = Object.values(viemChains) as Chain[]
+
+function chainIsTestnet(chainId: number): boolean {
+  return allChains.find((c) => c.id === chainId)?.testnet === true
 }
 
 async function runDiscovery(baseUrl: string, options: ValidateOptions): Promise<DiscoveryResult> {