mppx 0.8.15 → 0.8.18

package/src/tempo/server/Subscription.ts

@@ -1,1333 +0,0 @@
-import { Base64 } from 'ox'
-import { KeyAuthorization } from 'ox/tempo'
-import {
-  encodeFunctionData,
-  isAddressEqual,
-  parseEventLogs,
-  type Address,
-  type Client as ViemClient,
-  type TransactionReceipt,
-} from 'viem'
-import {
-  call as viem_call,
-  prepareTransactionRequest,
-  sendRawTransaction,
-  sendRawTransactionSync,
-  signTransaction,
-} from 'viem/actions'
-import { Abis, Account as TempoAccount, Transaction } from 'viem/tempo'
-import { tempo as tempo_chain } from 'viem/tempo/chains'
-
-import { VerificationFailedError } from '../../Errors.js'
-import type { LooseOmit, MaybePromise, NoExtraKeys } from '../../internal/types.js'
-import * as Method from '../../Method.js'
-import * as Store from '../../Store.js'
-import type * as Client from '../../viem/Client.js'
-import * as ClientResolver from '../../viem/Client.js'
-import * as Attribution from '../Attribution.js'
-import * as Account from '../internal/account.js'
-import * as defaults from '../internal/defaults.js'
-import * as FeePayer from '../internal/fee-payer.js'
-import * as Proof from '../internal/proof.js'
-import type * as types from '../internal/types.js'
-import * as Methods from '../Methods.js'
-import {
-  assertSubscriptionTiming,
-  toSubscriptionPeriodSeconds,
-  verifySubscriptionKeyAuthorization,
-} from '../subscription/KeyAuthorization.js'
-import * as SubscriptionReceipt from '../subscription/Receipt.js'
-import * as SubscriptionStore from '../subscription/Store.js'
-import type {
-  SubscriptionAccessKey,
-  SubscriptionCredentialPayload,
-  SubscriptionLookup,
-  SubscriptionPeriodUnit,
-  SubscriptionRecord,
-  SubscriptionReceipt as SubscriptionReceiptValue,
-} from '../subscription/Types.js'
-
-type SubscriptionRequest = ReturnType<typeof Methods.subscription.schema.request.parse>
-type RenewalHandler = NonNullable<subscription.Parameters['renew']>
-
-/**
- * Creates a Tempo subscription method for recurring TIP-20 token payments.
- *
- * The method handles activation, request-path reuse, and optional lazy renewals.
- */
-export function subscription<const parameters extends subscription.Parameters>(
-  p: NoExtraKeys<parameters, subscription.Parameters>,
-) {
-  const parameters = p as parameters
-  const rawStore = (parameters.store ?? Store.memory()) as Store.AtomicStore<
-    Record<string, unknown>
-  >
-  if (typeof rawStore.update !== 'function') {
-    throw new Error('tempo.subscription() requires an atomic store with `update`.')
-  }
-  const defaultChainId = parameters.chainId ?? defaults.chainId.testnet
-  const {
-    amount,
-    currency = defaults.resolveCurrency({ chainId: defaultChainId }),
-    decimals = defaults.decimals,
-    description,
-    externalId,
-    periodCount,
-    periodUnit,
-    subscriptionExpires,
-  } = parameters
-
-  const { recipient } = Account.resolve(parameters)
-  const context = createContext(parameters, {
-    store: Store.from(rawStore, { keyPrefix: parameters.storeKeyPrefix }),
-    options: {
-      activationTimeoutMs: parameters.activationTimeoutMs,
-      renewalTimeoutMs: parameters.renewalTimeoutMs,
-    },
-  })
-  const { feePayer, feePayerPolicy, getClient, store, waitForConfirmation } = context
-
-  type Defaults = subscription.DeriveDefaults<parameters>
-  const method = Method.toServer<
-    typeof Methods.subscription,
-    Defaults,
-    undefined,
-    subscription.Extensions
-  >(Methods.subscription, {
-    defaults: {
-      amount,
-      currency,
-      decimals,
-      description,
-      externalId,
-      periodCount,
-      periodUnit,
-      recipient,
-      subscriptionExpires,
-    } as unknown as Defaults,
-    extensions: {
-      renew: (parameters) =>
-        renewWithContext({
-          context: {
-            ...context,
-            feePayerPolicy: parameters.feePayerPolicy
-              ? resolveFeePayerPolicy(context.feePayerPolicy, parameters.feePayerPolicy)
-              : context.feePayerPolicy,
-            waitForConfirmation: parameters.waitForConfirmation ?? context.waitForConfirmation,
-          },
-          subscriptionId: parameters.subscriptionId,
-        }),
-    },
-
-    async authorize({ input, request }) {
-      if (parameters.requireCredential) return undefined
-
-      const resolved = await parameters.resolve({ input, request })
-      if (!resolved) return undefined
-
-      const subscription = await store.getByKey(resolved.key)
-      if (!subscription || !isActive(subscription)) return undefined
-      if (!subscriptionMatchesRequest(subscription, request)) return undefined
-
-      const periodIndex = getPeriodIndex(subscription)
-      if (periodIndex > subscription.lastChargedPeriod) {
-        const renew = resolveRenewalHandler({
-          feePayer,
-          feePayerPolicy,
-          getClient,
-          parameters,
-          store,
-          subscription,
-          waitForConfirmation,
-        })
-        if (!renew) return undefined
-
-        const renewal = await settleRenewal({
-          expectedLookupKey: resolved.key,
-          periodIndex,
-          renew,
-          request,
-          store,
-          subscription,
-        })
-        if (!renewal) return undefined
-        if (renewal.status === 'charged') return { receipt: renewal.receipt }
-        if (renewal.status === 'inFlight') {
-          return {
-            receipt: renewal.receipt,
-            response: new Response(null, {
-              headers: { 'Retry-After': '1' },
-              status: 409,
-            }),
-          }
-        }
-
-        await parameters.hooks?.renewed?.({
-          periodIndex,
-          receipt: renewal.result.receipt,
-          subscription: renewal.result.subscription,
-        })
-        return {
-          receipt: renewal.result.receipt,
-        }
-      }
-
-      return {
-        receipt: SubscriptionReceipt.fromRecord(subscription),
-      }
-    },
-
-    async request({ capturedRequest, credential, request }) {
-      const credentialRequest = credential?.challenge.request as SubscriptionRequest | undefined
-      const chainId =
-        request.chainId ??
-        parameters.chainId ??
-        credentialRequest?.methodDetails?.chainId ??
-        defaults.chainId.testnet
-      const parsedRequest = Methods.subscription.schema.request.parse({
-        ...request,
-        chainId,
-      })
-      const input = requestFromCaptured(capturedRequest)
-      const resolved = await parameters.resolve({ input, request: parsedRequest })
-      const existing = resolved ? await store.getByKey(resolved.key) : null
-      const accessKey = !credential
-        ? resolved
-          ? await resolveChallengeAccessKey({
-              existing,
-              input,
-              parameters,
-              request: parsedRequest,
-              resolved,
-              store,
-            })
-          : parameters.requireCredential && !parameters.activate
-            ? await createUnboundChallengeAccessKey({ store })
-            : undefined
-        : (credentialRequest?.methodDetails?.accessKey ?? parsedRequest.methodDetails?.accessKey)
-      if (!accessKey) {
-        throw new VerificationFailedError({ reason: 'subscription accessKey is missing' })
-      }
-
-      // Challenges carry the server-generated key in methodDetails so the shared request shape stays spec-compatible.
-      return {
-        ...request,
-        methodDetails: {
-          ...request.methodDetails,
-          accessKey,
-        },
-        chainId,
-      }
-    },
-
-    stableBinding: subscriptionBinding,
-
-    async verify({ credential, envelope, request }) {
-      const input = requestFromCaptured(envelope?.capturedRequest)
-      const parsed = Methods.subscription.schema.request.safeParse(request)
-      const parsedRequest = parsed.success ? parsed.data : (request as SubscriptionRequest)
-      assertSubscriptionTiming({
-        challengeExpires: credential.challenge.expires,
-        request: parsedRequest,
-      })
-      const challengeRequest = credential.challenge.request as SubscriptionRequest
-      let resolved: subscription.ResolvedSubscription | null = null
-      let accessKey =
-        challengeRequest.methodDetails?.accessKey ?? parsedRequest.methodDetails?.accessKey
-      if (!accessKey) {
-        resolved = await parameters.resolve({ input, request: parsedRequest })
-        if (!resolved) {
-          throw new VerificationFailedError({ reason: 'subscription could not be resolved' })
-        }
-        accessKey = await resolveAccessKey({ input, parameters, request: parsedRequest, resolved })
-      }
-      if (!accessKey) {
-        throw new VerificationFailedError({ reason: 'subscription accessKey is missing' })
-      }
-      const verified = verifySubscriptionKeyAuthorization({
-        accessKey,
-        chainId: parsedRequest.methodDetails?.chainId ?? defaults.chainId.testnet,
-        payload: credential.payload as SubscriptionCredentialPayload,
-        request: parsedRequest,
-      })
-      const declaredSource = credential.source ? Proof.parsePkhSource(credential.source) : null
-      if (
-        declaredSource &&
-        (declaredSource.chainId !== verified.source.chainId ||
-          !isAddressEqual(declaredSource.address, verified.source.address))
-      ) {
-        throw new VerificationFailedError({
-          reason: 'credential source does not match signature',
-        })
-      }
-      resolved =
-        (await parameters.resolve({ input, request: parsedRequest, source: verified.source })) ??
-        resolved
-
-      if (!resolved) {
-        throw new VerificationFailedError({ reason: 'subscription could not be resolved' })
-      }
-
-      const activation = await store.activate({
-        challengeId: credential.challenge.id,
-        isReusable: (subscription) =>
-          parameters.requireCredential
-            ? isActiveSubscriptionForRequest(subscription, parsedRequest)
-            : isReusableSubscription(subscription, parsedRequest),
-        lookupKey: resolved.key,
-        async create() {
-          const activation = withSubscriptionAccessKey(
-            await activateSubscription({
-              accessKey,
-              auto: {
-                challengeId: credential.challenge.id,
-                feePayer,
-                feePayerPolicy,
-                getClient,
-                keyAuthorization: (credential.payload as SubscriptionCredentialPayload).signature,
-                realm: credential.challenge.realm,
-                store,
-                waitForConfirmation,
-              },
-              credential: credential as typeof credential & {
-                payload: SubscriptionCredentialPayload
-              },
-              input,
-              parameters,
-              request: parsedRequest,
-              resolved,
-              source: verified.source,
-            }),
-            accessKey,
-          )
-          validateSubscriptionSettlement(activation, {
-            expectedLookupKey: resolved.key,
-            expectedPeriodIndex: 0,
-            request: parsedRequest,
-          })
-          return activation
-        },
-      })
-      if (activation.status === 'replayed') {
-        throw new VerificationFailedError({
-          reason: 'subscription credential has already been used',
-        })
-      }
-      if (activation.status === 'inFlight') {
-        throw new VerificationFailedError({
-          reason: 'subscription activation is already in flight',
-        })
-      }
-      if (activation.status === 'claimMismatch') {
-        throw new VerificationFailedError({ reason: 'subscription activation claim mismatch' })
-      }
-      if (activation.status === 'existing') {
-        const subscription = activation.subscription
-        assertSubscriptionPayer(subscription, verified.source, {
-          required: parameters.requireCredential,
-        })
-
-        const periodIndex = getPeriodIndex(subscription)
-        if (periodIndex > subscription.lastChargedPeriod) {
-          const renew = resolveRenewalHandler({
-            feePayer,
-            feePayerPolicy,
-            getClient,
-            parameters,
-            store,
-            subscription,
-            waitForConfirmation,
-          })
-          if (!renew) {
-            throw new VerificationFailedError({ reason: 'subscription renewal is required' })
-          }
-
-          const renewal = await settleRenewal({
-            expectedLookupKey: resolved.key,
-            periodIndex,
-            renew,
-            request: parsedRequest,
-            store,
-            subscription,
-          })
-          if (!renewal) {
-            throw new VerificationFailedError({ reason: 'subscription renewal failed' })
-          }
-          if (renewal.status === 'charged' || renewal.status === 'inFlight') {
-            return renewal.receipt
-          }
-
-          await parameters.hooks?.renewed?.({
-            periodIndex,
-            receipt: renewal.result.receipt,
-            subscription: renewal.result.subscription,
-          })
-          return renewal.result.receipt
-        }
-
-        return SubscriptionReceipt.fromRecord(subscription)
-      }
-
-      await parameters.hooks?.activated?.({
-        receipt: activation.result.receipt,
-        subscription: activation.result.subscription,
-      })
-      return activation.result.receipt
-    },
-  })
-  return method
-}
-
-// Access-key provisioning can cost around 4M gas.
-const defaultFeePayerPolicy = {
-  maxGas: 5_000_000n,
-  maxTotalFee: 200_000_000_000_000_000n,
-} satisfies Partial<FeePayer.Policy>
-
-function resolveFeePayerPolicy(
-  ...policies: (Partial<FeePayer.Policy> | undefined)[]
-): Partial<FeePayer.Policy> {
-  return Object.assign({}, defaultFeePayerPolicy, ...policies)
-}
-
-function requestFromCaptured(capturedRequest: Method.CapturedRequest | undefined): Request {
-  if (!capturedRequest) return new Request('https://subscription.invalid')
-  return new Request(capturedRequest.url, {
-    headers: capturedRequest.headers,
-    method: capturedRequest.method,
-  })
-}
-
-async function resolveAccessKey(parameters: {
-  input: Request
-  parameters: subscription.Parameters
-  request: SubscriptionRequest
-  resolved: subscription.ResolvedSubscription
-}) {
-  const { input, parameters: subscriptionParameters, request, resolved } = parameters
-  return (
-    resolved.accessKey ??
-    (subscriptionParameters.accessKey
-      ? await subscriptionParameters.accessKey({ input, request, resolved })
-      : undefined)
-  )
-}
-
-async function resolveChallengeAccessKey(parameters: {
-  existing: SubscriptionRecord | null
-  input: Request
-  parameters: subscription.Parameters
-  request: SubscriptionRequest
-  resolved: subscription.ResolvedSubscription
-  store: SubscriptionStore.SubscriptionStore
-}) {
-  const {
-    existing,
-    input,
-    parameters: subscriptionParameters,
-    request,
-    resolved,
-    store,
-  } = parameters
-  if (!subscriptionParameters.activate) {
-    // In automatic mode, the SDK owns the server access key so apps can issue
-    // challenges from only their resolved subscription lookup key.
-    const accessKey = await store.getOrCreateAccessKey(resolved.key)
-    return {
-      accessKeyAddress: accessKey.accessKeyAddress,
-      keyType: accessKey.keyType,
-    } satisfies SubscriptionAccessKey
-  }
-  // Manual activation keeps the lower-level API: callers can provide the
-  // access key for new challenges, while active subscriptions reuse the stored key.
-  return (
-    (await resolveAccessKey({ input, parameters: subscriptionParameters, request, resolved })) ??
-    (existing && isActive(existing) ? existing.accessKey : undefined)
-  )
-}
-
-async function createUnboundChallengeAccessKey(parameters: {
-  store: SubscriptionStore.SubscriptionStore
-}) {
-  const accessKey = await parameters.store.getOrCreateAccessKey(
-    `challenge:${createSubscriptionId()}`,
-  )
-  return {
-    accessKeyAddress: accessKey.accessKeyAddress,
-    keyType: accessKey.keyType,
-  } satisfies SubscriptionAccessKey
-}
-
-async function activateSubscription(parameters: {
-  accessKey: SubscriptionAccessKey
-  auto: {
-    challengeId: string
-    feePayer?: ReturnType<typeof Account.resolve>['feePayer'] | undefined
-    feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-    getClient: (parameters: { chainId?: number | undefined }) => MaybePromise<ViemClient>
-    keyAuthorization: `0x${string}`
-    realm: string
-    store: SubscriptionStore.SubscriptionStore
-    waitForConfirmation: boolean
-  }
-  credential: {
-    payload: SubscriptionCredentialPayload
-    source?: string | undefined
-  }
-  input: Request
-  parameters: subscription.Parameters
-  request: SubscriptionRequest
-  resolved: subscription.ResolvedSubscription
-  source: { address: Address; chainId: number } | null
-}) {
-  const {
-    accessKey,
-    auto,
-    credential,
-    input,
-    parameters: subscriptionParameters,
-    request,
-    resolved,
-    source,
-  } = parameters
-  if (subscriptionParameters.activate) {
-    // A custom activate hook owns settlement and record creation.
-    return subscriptionParameters.activate({
-      accessKey,
-      credential,
-      input,
-      request,
-      resolved,
-      source,
-    })
-  }
-  if (!source) {
-    throw new VerificationFailedError({ reason: 'subscription payer is missing' })
-  }
-
-  // Automatic activation bills the first period and persists the recurring
-  // billing authority needed for request-path and background renewals.
-  const reference = await submitSubscriptionPayment({
-    accessKey,
-    feePayer: auto.feePayer,
-    feePayerPolicy: auto.feePayerPolicy,
-    getClient: auto.getClient,
-    keyAuthorization: auto.keyAuthorization,
-    lookupKey: resolved.key,
-    request,
-    settlementReference: auto.challengeId,
-    source,
-    store: auto.store,
-    waitForConfirmation: auto.waitForConfirmation,
-  })
-  const timestamp = new Date().toISOString()
-  const subscription = {
-    accessKey,
-    amount: request.amount,
-    billingAnchor: timestamp,
-    chainId: request.methodDetails?.chainId,
-    currency: request.currency,
-    externalId: request.externalId,
-    keyAuthorization: auto.keyAuthorization,
-    lastChargedPeriod: 0,
-    lookupKey: resolved.key,
-    payer: source,
-    periodCount: request.periodCount,
-    periodUnit: request.periodUnit,
-    recipient: request.recipient,
-    reference,
-    subscriptionExpires: request.subscriptionExpires,
-    subscriptionId: createSubscriptionId(),
-    timestamp,
-  } satisfies SubscriptionRecord
-
-  return {
-    receipt: SubscriptionReceipt.createSubscriptionReceipt(subscription),
-    subscription,
-  }
-}
-
-async function settleRenewal(parameters: {
-  expectedLookupKey: string
-  periodIndex: number
-  renew: (parameters: {
-    inFlightReference: string
-    periodIndex: number
-    subscription: SubscriptionRecord
-  }) => Promise<subscription.RenewalResult>
-  request?: SubscriptionRequest | undefined
-  store: SubscriptionStore.SubscriptionStore
-  subscription: SubscriptionRecord
-}): Promise<
-  | { status: 'charged'; receipt: SubscriptionReceiptValue }
-  | { status: 'inFlight'; receipt: SubscriptionReceiptValue }
-  | { status: 'renewed'; result: subscription.RenewalResult }
-  | null
-> {
-  const { expectedLookupKey, periodIndex, renew, request, store, subscription } = parameters
-  const inFlightReference = renewalReference(subscription.subscriptionId, periodIndex)
-  const renewal = await store.renew({
-    inFlightReference,
-    periodIndex,
-    async renew({ inFlightReference, periodIndex, subscription: started }) {
-      const renewed = withSubscriptionAccessKey(
-        await renew({
-          inFlightReference,
-          periodIndex,
-          subscription: started,
-        }),
-        started.accessKey,
-      )
-      validateSubscriptionSettlement(renewed, {
-        expectedLookupKey,
-        expectedPeriodIndex: periodIndex,
-        expectedSubscriptionId: subscription.subscriptionId,
-        previous: started,
-        request,
-      })
-      return renewed
-    },
-    subscriptionId: subscription.subscriptionId,
-  })
-
-  if (renewal.status === 'charged') {
-    return { receipt: SubscriptionReceipt.fromRecord(renewal.subscription), status: 'charged' }
-  }
-  if (renewal.status === 'inFlight') {
-    return { receipt: SubscriptionReceipt.fromRecord(renewal.subscription), status: 'inFlight' }
-  }
-  if (renewal.status === 'renewed') return { result: renewal.result, status: 'renewed' }
-  if (renewal.status === 'claimMismatch') {
-    throw new VerificationFailedError({ reason: 'subscription renewal claim mismatch' })
-  }
-  return null
-}
-
-function renewalReference(subscriptionId: string, periodIndex: number): string {
-  // This stable identifier is persisted before the billing hook runs so apps can
-  // use it as an idempotency/reconciliation key if a renewal crashes mid-flight.
-  return `renewal:${subscriptionId}:${periodIndex}`
-}
-
-function withSubscriptionAccessKey<
-  result extends subscription.ActivationResult | subscription.RenewalResult,
->(result: result, accessKey: SubscriptionAccessKey | undefined): result {
-  if (!accessKey || result.subscription.accessKey) return result
-  return {
-    ...result,
-    subscription: {
-      ...result.subscription,
-      accessKey,
-    },
-  }
-}
-
-function getPeriodIndex(subscription: SubscriptionRecord): number {
-  const anchor = new Date(subscription.billingAnchor).getTime()
-  const expires = new Date(subscription.subscriptionExpires).getTime()
-  const now = Date.now()
-  if (!Number.isFinite(anchor) || !Number.isFinite(expires) || now >= expires) {
-    return Number.POSITIVE_INFINITY
-  }
-
-  let periodSeconds: number
-  try {
-    periodSeconds = toSubscriptionPeriodSeconds(subscription)
-  } catch {
-    return Number.POSITIVE_INFINITY
-  }
-
-  return Math.max(0, Math.floor((now - anchor) / (periodSeconds * 1_000)))
-}
-
-function isActive(subscription: SubscriptionRecord): boolean {
-  if (subscription.canceledAt || subscription.revokedAt) return false
-  return new Date(subscription.subscriptionExpires).getTime() > Date.now()
-}
-
-function isActiveSubscriptionForRequest(
-  subscription: SubscriptionRecord,
-  request: SubscriptionRequest,
-): boolean {
-  return isActive(subscription) && subscriptionMatchesRequest(subscription, request)
-}
-
-function isReusableSubscription(
-  subscription: SubscriptionRecord,
-  request: SubscriptionRequest,
-): boolean {
-  return (
-    isActiveSubscriptionForRequest(subscription, request) &&
-    getPeriodIndex(subscription) <= subscription.lastChargedPeriod
-  )
-}
-
-function subscriptionMatchesRequest(
-  subscription: SubscriptionRecord,
-  request: SubscriptionRequest | SubscriptionRecord,
-): boolean {
-  const actual = comparableSubscriptionBinding(subscription)
-  const expected = comparableSubscriptionBinding(request)
-  return (Object.keys(expected) as (keyof typeof expected)[]).every(
-    (key) => actual[key] === expected[key],
-  )
-}
-
-function assertSubscriptionPayer(
-  subscription: SubscriptionRecord,
-  source: { address: Address; chainId: number },
-  options?: { required?: boolean | undefined },
-) {
-  if (!subscription.payer) {
-    if (options?.required) {
-      throw new VerificationFailedError({ reason: 'subscription payer is missing' })
-    }
-    return
-  }
-  if (
-    subscription.payer.chainId !== source.chainId ||
-    !isAddressEqual(subscription.payer.address, source.address)
-  ) {
-    throw new VerificationFailedError({ reason: 'subscription payer mismatch' })
-  }
-}
-
-function comparableSubscriptionBinding(value: SubscriptionRecord | SubscriptionRequest) {
-  const chainId =
-    'chainId' in value ? value.chainId : (value as SubscriptionRequest).methodDetails?.chainId
-  return {
-    amount: value.amount,
-    chainId,
-    currency: value.currency.toLowerCase(),
-    externalId: value.externalId,
-    periodCount: value.periodCount,
-    periodUnit: value.periodUnit,
-    recipient: value.recipient.toLowerCase(),
-    subscriptionExpires: value.subscriptionExpires,
-  }
-}
-
-function validateSubscriptionSettlement(
-  result: subscription.ActivationResult | subscription.RenewalResult,
-  options: {
-    expectedLookupKey: string
-    expectedPeriodIndex: number
-    expectedSubscriptionId?: string | undefined
-    previous?: SubscriptionRecord | undefined
-    request?: SubscriptionRequest | undefined
-  },
-) {
-  const { receipt, subscription } = result
-  assertSubscriptionReceipt(receipt, subscription)
-  assertSubscriptionRecord(subscription, options)
-
-  if (options.request) {
-    assertSubscriptionRequestMatch(subscription, options.request)
-  } else if (options.previous) {
-    assertSubscriptionRequestMatch(subscription, options.previous)
-  }
-}
-
-function assertSubscriptionReceipt(
-  receipt: SubscriptionReceiptValue,
-  subscription: SubscriptionRecord,
-) {
-  if (receipt.method !== 'tempo' || receipt.status !== 'success') {
-    throw new VerificationFailedError({ reason: 'subscription receipt is invalid' })
-  }
-  if (receipt.subscriptionId !== subscription.subscriptionId) {
-    throw new VerificationFailedError({ reason: 'subscription receipt id mismatch' })
-  }
-  if (receipt.reference !== subscription.reference) {
-    throw new VerificationFailedError({ reason: 'subscription receipt reference mismatch' })
-  }
-  if (receipt.timestamp !== subscription.timestamp) {
-    throw new VerificationFailedError({ reason: 'subscription receipt timestamp mismatch' })
-  }
-  assertTransactionHash(receipt.reference, 'subscription reference must be a transaction hash')
-  assertValidDate(receipt.timestamp, 'subscription receipt timestamp is invalid')
-}
-
-function assertSubscriptionRecord(
-  subscription: SubscriptionRecord,
-  options: {
-    expectedLookupKey: string
-    expectedPeriodIndex: number
-    expectedSubscriptionId?: string | undefined
-  },
-) {
-  assertBase64Url(subscription.subscriptionId, 'subscriptionId must be base64url')
-  assertTransactionHash(subscription.reference, 'subscription reference must be a transaction hash')
-  const billingAnchor = assertValidDate(
-    subscription.billingAnchor,
-    'subscription billingAnchor is invalid',
-  )
-  const subscriptionExpires = assertValidDate(
-    subscription.subscriptionExpires,
-    'subscriptionExpires is invalid',
-  )
-
-  assertEqual(subscription.lookupKey, options.expectedLookupKey, {
-    reason: 'subscription lookupKey does not match the resolved key',
-  })
-  assertEqual(subscription.lastChargedPeriod, options.expectedPeriodIndex, {
-    reason: 'subscription lastChargedPeriod does not match the settled period',
-  })
-  if (options.expectedSubscriptionId) {
-    assertEqual(subscription.subscriptionId, options.expectedSubscriptionId, {
-      reason: 'subscriptionId does not match the active subscription',
-    })
-  }
-  if (billingAnchor >= subscriptionExpires) {
-    throw new VerificationFailedError({
-      reason: 'subscription billingAnchor must be before subscriptionExpires',
-    })
-  }
-}
-
-function assertSubscriptionRequestMatch(
-  subscription: SubscriptionRecord,
-  request: SubscriptionRequest | SubscriptionRecord,
-) {
-  if (!subscriptionMatchesRequest(subscription, request)) {
-    throw new VerificationFailedError({ reason: 'subscription record does not match request' })
-  }
-}
-
-function assertBase64Url(value: string, reason: string) {
-  if (!/^[A-Za-z0-9_-]+$/.test(value)) {
-    throw new VerificationFailedError({ reason })
-  }
-}
-
-function assertTransactionHash(value: string, reason: string) {
-  if (!/^0x[0-9a-fA-F]{64}$/.test(value)) {
-    throw new VerificationFailedError({ reason })
-  }
-}
-
-function assertValidDate(value: string, reason: string) {
-  const milliseconds = new Date(value).getTime()
-  if (!Number.isFinite(milliseconds)) {
-    throw new VerificationFailedError({ reason })
-  }
-  return milliseconds
-}
-
-function assertEqual<value>(actual: value, expected: value, options: { reason: string }) {
-  if (actual !== expected) {
-    throw new VerificationFailedError(options)
-  }
-}
-
-function subscriptionBinding(request: SubscriptionRequest) {
-  return {
-    amount: request.amount,
-    chainId: request.methodDetails?.chainId,
-    currency: request.currency,
-    externalId: request.externalId,
-    periodCount: request.periodCount,
-    periodUnit: request.periodUnit,
-    recipient: request.recipient,
-    subscriptionExpires: request.subscriptionExpires,
-  }
-}
-
-function resolveRenewalHandler(parameters: {
-  feePayer?: ReturnType<typeof Account.resolve>['feePayer'] | undefined
-  feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-  getClient: (parameters: { chainId?: number | undefined }) => MaybePromise<ViemClient>
-  parameters: Pick<createContext.Parameters, 'renew'>
-  store: SubscriptionStore.SubscriptionStore
-  subscription: SubscriptionRecord
-  waitForConfirmation: boolean
-}): RenewalHandler | undefined {
-  const {
-    feePayer,
-    feePayerPolicy,
-    getClient,
-    parameters: subscriptionParameters,
-    store,
-    subscription,
-    waitForConfirmation,
-  } = parameters
-  if (subscriptionParameters.renew) return subscriptionParameters.renew
-  if (!subscription.accessKey || !subscription.payer) return undefined
-  return async ({ inFlightReference, periodIndex, subscription }) => {
-    const reference = await submitSubscriptionPayment({
-      accessKey: subscription.accessKey!,
-      feePayer,
-      feePayerPolicy,
-      getClient,
-      lookupKey: subscription.lookupKey,
-      request: subscription,
-      settlementReference: inFlightReference,
-      source: subscription.payer!,
-      store,
-      waitForConfirmation,
-    })
-    const record = {
-      ...subscription,
-      lastChargedPeriod: periodIndex,
-      reference,
-      timestamp: new Date().toISOString(),
-    } satisfies SubscriptionRecord
-    return {
-      receipt: SubscriptionReceipt.createSubscriptionReceipt(record),
-      subscription: record,
-    }
-  }
-}
-
-async function submitSubscriptionPayment(parameters: {
-  accessKey: SubscriptionAccessKey
-  feePayer?: ReturnType<typeof Account.resolve>['feePayer'] | undefined
-  feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-  getClient: (parameters: { chainId?: number | undefined }) => MaybePromise<ViemClient>
-  keyAuthorization?: `0x${string}` | undefined
-  lookupKey: string
-  request: Pick<SubscriptionRequest, 'amount'> & {
-    methodDetails?: { chainId?: number | undefined } | undefined
-  } & { currency: Address | string; recipient: Address | string }
-  settlementReference: string
-  source: { address: Address; chainId: number }
-  store: SubscriptionStore.SubscriptionStore
-  waitForConfirmation: boolean
-}) {
-  const {
-    accessKey,
-    feePayer,
-    feePayerPolicy,
-    getClient,
-    keyAuthorization,
-    lookupKey,
-    request,
-    settlementReference,
-    source,
-    store,
-    waitForConfirmation,
-  } = parameters
-  const stored =
-    (await store.getAccessKey(lookupKey)) ??
-    (await store.getAccessKeyByAddress(accessKey.accessKeyAddress))
-  if (!stored) {
-    throw new VerificationFailedError({ reason: 'subscription access key is missing' })
-  }
-  const rawAccessAccount = TempoAccount.fromSecp256k1(stored.privateKey)
-  if (!isAddressEqual(rawAccessAccount.address, accessKey.accessKeyAddress)) {
-    throw new VerificationFailedError({
-      reason: 'subscription access key does not match stored key',
-    })
-  }
-
-  const chainId = request.methodDetails?.chainId ?? source.chainId
-  const client = await getClient({ chainId })
-  const account = TempoAccount.fromSecp256k1(stored.privateKey, {
-    access: source.address,
-  })
-  const memo = Attribution.encode({
-    challengeId: settlementReference,
-    serverId: lookupKey,
-  })
-  const baseTransaction = {
-    account,
-    calls: [
-      {
-        data: encodeFunctionData({
-          abi: Abis.tip20,
-          functionName: 'transferWithMemo',
-          args: [request.recipient as Address, BigInt(request.amount), memo],
-        }),
-        to: request.currency as Address,
-      },
-    ],
-    chainId,
-    ...(keyAuthorization
-      ? { keyAuthorization: KeyAuthorization.deserialize(keyAuthorization) }
-      : {}),
-  }
-  const serializedTransaction = await (async () => {
-    if (!feePayer) return await signTransaction(client, baseTransaction as never)
-    // For sponsored payments, prepare the tx via `prepareTransactionRequest`
-    // (without `feePayer: true`) so viem returns the chain's full
-    // proof-inclusive gas estimate. With `feePayer: true` viem sets a
-    // dummy sig + null feePayerSignature, dropping signature and key
-    // authorization verification costs -- see chainConfig.js FIXME. We add
-    // a small buffer for fee-payer overhead, then flip `feePayer = true`
-    // and re-sign with the fee-payer-sponsored envelope.
-    const prepared = await prepareTransactionRequest(client, {
-      ...baseTransaction,
-      nonceKey: 'expiring',
-    } as never)
-    prepared.gas = (prepared.gas ?? 0n) + 5_000n
-    ;(prepared as Record<string, unknown>).feePayer = true
-    const userSerialized = await signTransaction(client, prepared as never)
-    const userTransaction = Transaction.deserialize(
-      userSerialized as Transaction.TransactionSerializedTempo,
-    )
-    const completed = await FeePayer.preflightSponsorship({
-      transaction: userTransaction,
-      simulate: (request) => viem_call(client, request as never),
-      async complete() {
-        const sponsored = FeePayer.prepareSponsoredTransaction({
-          account: feePayer,
-          chainId: chainId ?? client.chain!.id,
-          details: {
-            amount: String(request.amount),
-            currency: String(request.currency),
-            recipient: String(request.recipient),
-          },
-          ...(feePayerPolicy ? { policy: feePayerPolicy } : {}),
-          transaction: userTransaction as never,
-        })
-        return { feePayer: feePayer.address, transaction: sponsored }
-      },
-    })
-    return await signTransaction(client, completed.transaction as never)
-  })()
-  const transaction = Transaction.deserialize(
-    serializedTransaction as Transaction.TransactionSerializedTempo,
-  )
-  if (!feePayer)
-    await viem_call(client, {
-      ...transaction,
-      account: transaction.from,
-      calls: transaction.calls,
-      feePayerSignature: undefined,
-    } as never)
-
-  if (!waitForConfirmation) {
-    // Optimistic mode has no receipt to inspect, so it cannot detect a T6
-    // (TIP-1028) held transfer. Use `waitForConfirmation: true` for T6-safe proof.
-    return sendRawTransaction(client, {
-      serializedTransaction: serializedTransaction as Transaction.TransactionSerializedTempo,
-    })
-  }
-
-  const receipt = await sendRawTransactionSync(client, {
-    serializedTransaction: serializedTransaction as Transaction.TransactionSerializedTempo,
-  })
-  if (receipt.status !== 'success') {
-    throw new VerificationFailedError({
-      reason: `subscription transaction reverted: ${receipt.transactionHash}`,
-    })
-  }
-  assertSubscriptionTransfer(receipt, {
-    amount: BigInt(request.amount),
-    currency: request.currency as Address,
-    memo,
-    recipient: request.recipient as Address,
-  })
-  return receipt.transactionHash
-}
-
-/**
- * Asserts a confirmed subscription payment credited the recipient.
- *
- * Transaction success alone is not proof: under Tempo T6 (TIP-1028) a recipient
- * receive policy can hold the funds in `ReceivePolicyGuard` while the tx still
- * succeeds. Settlement always emits one `transferWithMemo(recipient, amount,
- * memo)`, so this requires a matching `TransferWithMemo` log on the expected
- * token. A held transfer fails because its `to` is the guard, and the memo
- * binding excludes unrelated transfer effects in the same receipt.
- */
-function assertSubscriptionTransfer(
-  receipt: TransactionReceipt,
-  parameters: { amount: bigint; currency: Address; memo: `0x${string}`; recipient: Address },
-): void {
-  const { amount, currency, memo, recipient } = parameters
-  const credited = parseEventLogs({
-    abi: Abis.tip20,
-    eventName: 'TransferWithMemo',
-    logs: receipt.logs,
-  }).some(
-    (log) =>
-      isAddressEqual(log.address, currency) &&
-      isAddressEqual(log.args.to, recipient) &&
-      log.args.amount === amount &&
-      log.args.memo.toLowerCase() === memo.toLowerCase(),
-  )
-  if (!credited) {
-    throw new VerificationFailedError({
-      reason:
-        `subscription transfer was not credited to the recipient ` +
-        `(funds may have been held by a receive policy): ${receipt.transactionHash}`,
-    })
-  }
-}
-
-function createSubscriptionId() {
-  const bytes = new Uint8Array(18)
-  globalThis.crypto.getRandomValues(bytes)
-  return Base64.fromBytes(bytes, { url: true }).replace(/=+$/, '')
-}
-
-/**
- * Renews an overdue subscription outside of the HTTP request path.
- * Intended for cron jobs or background workers that bill subscriptions on a schedule.
- *
- * Returns the renewal result if the subscription was overdue, or `null` if already current.
- */
-export async function renew(parameters: renew.Parameters): Promise<renew.Result | null> {
-  const context = createContext(parameters, {
-    store: parameters.store,
-    options: {
-      renewalTimeoutMs: parameters.renewalTimeoutMs,
-    },
-  })
-
-  return renewWithContext({
-    context,
-    subscriptionId: parameters.subscriptionId,
-  })
-}
-
-async function renewWithContext(parameters: {
-  context: createContext.Return
-  subscriptionId: string
-}): Promise<renew.Result | null> {
-  const { context, subscriptionId } = parameters
-  const record = await context.store.get(subscriptionId)
-  if (!record) return null
-  if (!isActive(record)) return null
-  const active = await context.store.getByKey(record.lookupKey)
-  if (active?.subscriptionId !== record.subscriptionId) return null
-
-  const periodIndex = getPeriodIndex(record)
-  if (periodIndex <= record.lastChargedPeriod) return null
-
-  const renew = resolveRenewalHandler({
-    feePayer: context.feePayer,
-    feePayerPolicy: context.feePayerPolicy,
-    getClient: context.getClient,
-    parameters: context.parameters,
-    store: context.store,
-    subscription: record,
-    waitForConfirmation: context.waitForConfirmation,
-  })
-  if (!renew) return null
-
-  const renewal = await settleRenewal({
-    expectedLookupKey: record.lookupKey,
-    periodIndex,
-    renew,
-    store: context.store,
-    subscription: record,
-  })
-  if (renewal?.status !== 'renewed') return null
-
-  await context.parameters.hooks?.renewed?.({
-    periodIndex,
-    receipt: renewal.result.receipt,
-    subscription: renewal.result.subscription,
-  })
-  return renewal.result
-}
-
-export declare namespace renew {
-  /** Parameters for renewing an overdue subscription outside the request path. */
-  type Parameters = Account.resolve.Parameters &
-    Client.getResolver.Parameters & {
-      /** The subscription to renew. */
-      subscriptionId: string
-      /** Billing callback -- same signature as the `renew` hook on {@link subscription}. */
-      renew?: subscription.Parameters['renew']
-      /** Store containing subscription records. */
-      store: Store.AtomicStore<Record<string, unknown>>
-      /**
-       * Milliseconds before an in-flight renewal lock can be replaced.
-       * Keeps concurrent renewal safe while allowing recovery from abandoned attempts.
-       */
-      renewalTimeoutMs?: number | undefined
-      /**
-       * Override the fee-payer policy for sponsored subscription payments.
-       * Useful when the access key renewal tx requires more gas than the default policy allows.
-       */
-      feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-      waitForConfirmation?: boolean | undefined
-    }
-
-  /** Renewal result returned by {@link renew}. */
-  type Result = subscription.RenewalResult
-}
-
-export declare namespace subscription {
-  /** Request-scoped lookup key used to find the active subscription. */
-  type ResolvedSubscription = SubscriptionLookup
-
-  /** Activation result returned after the initial credential is verified. */
-  type ActivationResult = {
-    receipt: SubscriptionReceiptValue
-    subscription: SubscriptionRecord
-  }
-
-  /** Renewal result returned when an overdue subscription is charged. */
-  type RenewalResult = {
-    receipt: SubscriptionReceiptValue
-    subscription: SubscriptionRecord
-  }
-
-  /** Parameters for renewing through a configured `mppx.tempo.subscription` handler. */
-  type RenewParameters = {
-    /** The subscription to renew. */
-    subscriptionId: string
-    /**
-     * Override the fee-payer policy for sponsored subscription payments.
-     * Useful when the access key renewal tx requires more gas than the default policy allows.
-     */
-    feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-    waitForConfirmation?: boolean | undefined
-  }
-
-  /** Handler extensions attached to `mppx.tempo.subscription`. */
-  type Extensions = {
-    renew: (parameters: RenewParameters) => Promise<renew.Result | null>
-  }
-
-  /** Request defaults supported by the subscription method. */
-  type Defaults = LooseOmit<
-    Method.RequestDefaults<typeof Methods.subscription>,
-    'accessKey' | 'recipient'
-  >
-
-  /** Parameters for configuring a Tempo subscription method. */
-  type Parameters = Account.resolve.Parameters &
-    Client.getResolver.Parameters & {
-      accessKey?:
-        | ((parameters: {
-            input: Request
-            request: SubscriptionRequest
-            resolved: ResolvedSubscription
-          }) => MaybePromise<SubscriptionAccessKey>)
-        | undefined
-      /**
-       * Milliseconds before an in-flight activation lock can be replaced.
-       * Keeps concurrent activation safe while allowing recovery from abandoned attempts.
-       */
-      activationTimeoutMs?: number | undefined
-      /**
-       * Milliseconds before an in-flight renewal lock can be replaced.
-       * Keeps concurrent renewal safe while allowing recovery from abandoned attempts.
-       */
-      renewalTimeoutMs?: number | undefined
-      /**
-       * Requires a fresh subscription Credential even when a subscription is active.
-       * This binds access reuse to the stored payer instead of trusting request metadata alone.
-       */
-      requireCredential?: boolean | undefined
-      /**
-       * Override the fee-payer policy for sponsored subscription payments.
-       * Useful when the access key + key authorization tx requires more gas
-       * than the default policy allows.
-       */
-      feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-      activate?:
-        | ((parameters: {
-            /** Custom activation must verify this access key matches the resolved subscription. */
-            accessKey: SubscriptionAccessKey
-            credential: {
-              payload: SubscriptionCredentialPayload
-              source?: string | undefined
-            }
-            input: Request
-            request: SubscriptionRequest
-            resolved: ResolvedSubscription
-            source: { address: Address; chainId: number } | null
-          }) => Promise<ActivationResult>)
-        | undefined
-      hooks?:
-        | {
-            activated?:
-              | ((parameters: {
-                  receipt: SubscriptionReceiptValue
-                  subscription: SubscriptionRecord
-                }) => MaybePromise<void>)
-              | undefined
-            renewed?:
-              | ((parameters: {
-                  periodIndex: number
-                  receipt: SubscriptionReceiptValue
-                  subscription: SubscriptionRecord
-                }) => MaybePromise<void>)
-              | undefined
-          }
-        | undefined
-      periodCount?: Methods.SubscriptionPeriodCountInput | undefined
-      periodUnit?: SubscriptionPeriodUnit | undefined
-      /**
-       * Resolves the request identity. This callback must authenticate and
-       * authorize the caller before returning a key; automatic mode may create
-       * a server-owned access key for that key while issuing a challenge.
-       */
-      resolve: (parameters: {
-        input: Request
-        request: SubscriptionRequest
-        /** Verified payer identity recovered from a signed subscription credential. */
-        source?: { address: Address; chainId: number } | undefined
-      }) => MaybePromise<ResolvedSubscription | null>
-      renew?: (parameters: {
-        /** Stable idempotency/reconciliation reference persisted before the renewal hook runs. */
-        inFlightReference: string
-        periodIndex: number
-        /** Custom renewal hooks must preserve amount, currency, recipient, period, expiry, and lookup key. */
-        subscription: SubscriptionRecord
-      }) => Promise<RenewalResult>
-      store?: Store.AtomicStore<Record<string, unknown>> | undefined
-      /**
-       * Prefix prepended to all subscription store keys.
-       *
-       * By default, no prefix is applied.
-       */
-      storeKeyPrefix?: string | undefined
-      testnet?: boolean | undefined
-      waitForConfirmation?: boolean | undefined
-    } & Defaults
-
-  /** Derived defaults after account and chain configuration are applied. */
-  type DeriveDefaults<parameters extends Parameters> = types.DeriveDefaults<
-    parameters,
-    Defaults,
-    {
-      currency: string
-      decimals: number
-    }
-  >
-}
-
-function createContext<const parameters extends createContext.Parameters>(
-  parameters: parameters,
-  options: createContext.Options,
-) {
-  const { feePayer } = Account.resolve(parameters)
-  const store = SubscriptionStore.fromStore(options.store, options.options)
-  const getClient = ClientResolver.getResolver({
-    chain: tempo_chain,
-    getClient: parameters.getClient,
-    rpcUrl: defaults.rpcUrl,
-  })
-  return {
-    feePayer,
-    feePayerPolicy: resolveFeePayerPolicy(parameters.feePayerPolicy),
-    getClient,
-    parameters,
-    store,
-    waitForConfirmation: parameters.waitForConfirmation ?? true,
-  }
-}
-
-declare namespace createContext {
-  type Parameters = Account.resolve.Parameters &
-    Client.getResolver.Parameters & {
-      feePayerPolicy?: Partial<FeePayer.Policy> | undefined
-      hooks?: subscription.Parameters['hooks']
-      renew?: subscription.Parameters['renew']
-      waitForConfirmation?: boolean | undefined
-    }
-
-  type Options = {
-    store: Store.AtomicStore<Record<string, unknown>>
-    options?: SubscriptionStore.fromStore.Options | undefined
-  }
-
-  type Return = ReturnType<typeof createContext>
-}