mppx 0.8.17 → 0.8.19

package/src/tempo/session/Snapshot.ts

@@ -1,95 +0,0 @@
-import { isAddress, type Address, type Hex } from 'viem'
-
-import * as HeaderCodec from '../../internal/HeaderCodec.js'
-import * as z from '../../zod.js'
-import type { ChannelDescriptor, RawAmountString } from './precompile/Protocol.js'
-
-/** Server-provided reusable channel state used to bootstrap a client session. */
-export type SessionSnapshot = {
-  /** Highest cumulative voucher amount the server has accepted for this channel. */
-  acceptedCumulative: RawAmountString
-  /** Tempo chain ID used to derive the channel ID and voucher domain. */
-  chainId: number
-  /** TIP-1034 channel ID derived from descriptor, escrow address, and chain ID. */
-  channelId: Hex
-  /** Timestamp when unilateral close was requested, when the channel is closing. */
-  closeRequestedAt?: RawAmountString | undefined
-  /** Current on-chain deposit ceiling for cumulative voucher authorization. */
-  deposit: RawAmountString
-  /** Full descriptor needed to recover the channel without client-side persistence. */
-  descriptor: ChannelDescriptor
-  /** Escrow precompile address used to derive the channel ID. */
-  escrow: Address
-  /** Minimum cumulative authorization needed for the challenged request or stream continuation. */
-  requiredCumulative: RawAmountString
-  /** Highest client-signed voucher accepted by the server. */
-  highestVoucher?:
-    | {
-        /** Channel identifier bound into the voucher signature. */
-        channelId: Hex
-        /** Cumulative authorization bound into the voucher signature. */
-        cumulativeAmount: RawAmountString
-        /** Original client signature proving the accepted cumulative authorization. */
-        signature: Hex
-      }
-    | undefined
-  /** Amount already settled on-chain. */
-  settled: RawAmountString
-  /** Amount consumed by delivered content according to server accounting. */
-  spent: RawAmountString
-  /** Paid units delivered by the server, when the transport reports them. */
-  units?: number | undefined
-}
-
-const addressSchema = z.custom<Address>(
-  (value) => typeof value === 'string' && isAddress(value, { strict: false }),
-)
-const hashSchema = z.custom<Hex>(
-  (value) => typeof value === 'string' && /^0x[0-9a-fA-F]{64}$/.test(value),
-)
-const hexSchema = z.custom<Hex>(
-  (value) => typeof value === 'string' && /^0x[0-9a-fA-F]+$/.test(value),
-)
-
-const channelDescriptorSchema = z.object({
-  authorizedSigner: addressSchema,
-  expiringNonceHash: hashSchema,
-  operator: addressSchema,
-  payee: addressSchema,
-  payer: addressSchema,
-  salt: hashSchema,
-  token: addressSchema,
-})
-
-const sessionSnapshotSchema = z.object({
-  acceptedCumulative: z.string(),
-  chainId: z.number(),
-  channelId: hashSchema,
-  closeRequestedAt: z.optional(z.string()),
-  deposit: z.string(),
-  descriptor: channelDescriptorSchema,
-  escrow: addressSchema,
-  highestVoucher: z.optional(
-    z.object({
-      channelId: hashSchema,
-      cumulativeAmount: z.string(),
-      signature: hexSchema,
-    }),
-  ),
-  requiredCumulative: z.string(),
-  settled: z.string(),
-  spent: z.string(),
-  units: z.optional(z.number()),
-})
-
-const sessionSnapshotHeader = HeaderCodec.createJson(sessionSnapshotSchema)
-
-/** Serializes a session snapshot for the `Payment-Session-Snapshot` header. */
-export function serializeSnapshot(snapshot: SessionSnapshot): string {
-  return sessionSnapshotHeader.encode(snapshot)
-}
-
-/** Deserializes a session snapshot from the `Payment-Session-Snapshot` header. */
-export function deserializeSnapshot(value: string): SessionSnapshot {
-  return sessionSnapshotHeader.decode(value) as SessionSnapshot
-}

package/src/tempo/session/client/ChannelOps.test.ts

@@ -1,218 +0,0 @@
-import { Hex } from 'ox'
-import { type Address, createClient, custom, zeroAddress } from 'viem'
-import { privateKeyToAccount } from 'viem/accounts'
-import { describe, expect, test } from 'vp/test'
-
-import * as Channel from '../precompile/Channel.js'
-import { tip20ChannelEscrow } from '../precompile/Protocol.js'
-import * as Types from '../precompile/Protocol.js'
-import * as Voucher from '../precompile/Voucher.js'
-import * as ChannelOps from './ChannelOps.js'
-
-const mocks = vi.hoisted(() => ({
-  prepareTransactionRequest: vi.fn(async (_client: unknown, request: unknown) => request),
-  signTransaction: vi.fn(async () => '0x1234'),
-}))
-
-vi.mock('viem/actions', async (importOriginal) => ({
-  ...(await importOriginal<typeof import('viem/actions')>()),
-  prepareTransactionRequest: mocks.prepareTransactionRequest,
-  signTransaction: mocks.signTransaction,
-}))
-
-const account = privateKeyToAccount(
-  '0xac0974bec39a17e36ba6a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
-)
-const client = createClient({
-  account,
-  transport: custom({
-    async request() {
-      throw new Error('unexpected rpc request')
-    },
-  }),
-})
-const chainId = 42431
-
-const descriptor = {
-  payer: account.address,
-  payee: '0x0000000000000000000000000000000000000002' as Address,
-  operator: '0x0000000000000000000000000000000000000000' as Address,
-  token: '0x0000000000000000000000000000000000000003' as Address,
-  salt: `0x${'11'.repeat(32)}` as Hex.Hex,
-  authorizedSigner: account.address,
-  expiringNonceHash: `0x${'22'.repeat(32)}` as Hex.Hex,
-} satisfies Channel.ChannelDescriptor
-
-const channelId = Channel.computeId({ ...descriptor, chainId, escrow: tip20ChannelEscrow })
-
-describe('precompile client ChannelOps credential builders', () => {
-  test('resolves escrow from override, challenge hint, or canonical default', () => {
-    const override = '0x0000000000000000000000000000000000000005' as Address
-    const hinted = '0x0000000000000000000000000000000000000006' as Address
-
-    expect(
-      ChannelOps.resolveEscrow(
-        { request: { methodDetails: { escrowContract: hinted } } },
-        override,
-      ),
-    ).toBe(override)
-    expect(
-      ChannelOps.resolveEscrow({ request: { methodDetails: { escrowContract: hinted } } }),
-    ).toBe(hinted)
-    expect(ChannelOps.resolveEscrow({ request: { methodDetails: { escrow: hinted } } })).toBe(
-      hinted,
-    )
-    expect(
-      ChannelOps.resolveEscrow({
-        request: { methodDetails: { escrowContract: 'not-an-address' } },
-      }),
-    ).toBe(tip20ChannelEscrow)
-    expect(ChannelOps.resolveEscrow({ request: { methodDetails: {} } })).toBe(tip20ChannelEscrow)
-  })
-
-  test('creates a verifiable voucher credential for an existing precompile channel', async () => {
-    const cumulativeAmount = Types.uint96(250n)
-    const payload = await ChannelOps.createVoucherPayload(
-      client,
-      account,
-      descriptor,
-      cumulativeAmount,
-      chainId,
-    )
-    if (payload.action !== 'voucher') throw new Error('expected voucher payload')
-
-    expect(payload.channelId).toBe(channelId)
-    expect(payload.descriptor).toEqual(descriptor)
-    expect(payload.cumulativeAmount).toBe('250')
-    expect(
-      Voucher.verifyVoucher(
-        tip20ChannelEscrow,
-        chainId,
-        { channelId, cumulativeAmount, signature: payload.signature },
-        descriptor.authorizedSigner,
-      ),
-    ).toBe(true)
-  })
-
-  test('binds voucher channel ID and signature domain to the provided escrow', async () => {
-    const escrow = '0x0000000000000000000000000000000000000005' as Address
-    const cumulativeAmount = Types.uint96(260n)
-    const expectedChannelId = Channel.computeId({ ...descriptor, chainId, escrow })
-    const payload = await ChannelOps.createVoucherPayload(
-      client,
-      account,
-      descriptor,
-      cumulativeAmount,
-      chainId,
-      escrow,
-    )
-
-    expect(payload.channelId).toBe(expectedChannelId)
-    expect(
-      Voucher.verifyVoucher(
-        escrow,
-        chainId,
-        { channelId: expectedChannelId, cumulativeAmount, signature: payload.signature },
-        descriptor.authorizedSigner,
-      ),
-    ).toBe(true)
-  })
-
-  test('uses the payer as voucher signer when descriptor authorizedSigner is zero', async () => {
-    const zeroSignerDescriptor = {
-      ...descriptor,
-      authorizedSigner: zeroAddress,
-    }
-    const zeroSignerChannelId = Channel.computeId({
-      ...zeroSignerDescriptor,
-      chainId,
-      escrow: tip20ChannelEscrow,
-    })
-    const cumulativeAmount = Types.uint96(275n)
-    const payload = await ChannelOps.createVoucherPayload(
-      client,
-      account,
-      zeroSignerDescriptor,
-      cumulativeAmount,
-      chainId,
-    )
-    if (payload.action !== 'voucher') throw new Error('expected voucher payload')
-
-    expect(payload.channelId).toBe(zeroSignerChannelId)
-    expect(
-      Voucher.verifyVoucher(
-        tip20ChannelEscrow,
-        chainId,
-        { channelId: zeroSignerChannelId, cumulativeAmount, signature: payload.signature },
-        descriptor.payer,
-      ),
-    ).toBe(true)
-  })
-
-  test('creates a close credential with a verifiable voucher signature', async () => {
-    const cumulativeAmount = Types.uint96(300n)
-    const payload = await ChannelOps.createClosePayload(
-      client,
-      account,
-      descriptor,
-      cumulativeAmount,
-      chainId,
-    )
-    if (payload.action !== 'close') throw new Error('expected close payload')
-
-    expect(payload.channelId).toBe(channelId)
-    expect(payload.cumulativeAmount).toBe('300')
-    expect(
-      Voucher.verifyVoucher(
-        tip20ChannelEscrow,
-        chainId,
-        { channelId, cumulativeAmount, signature: payload.signature },
-        descriptor.authorizedSigner,
-      ),
-    ).toBe(true)
-  })
-
-  test('distinguishes otherwise-identical fee-sponsored management transactions', async () => {
-    mocks.prepareTransactionRequest.mockClear()
-    let randomValue = 1
-    const random = vi.spyOn(globalThis.crypto, 'getRandomValues').mockImplementation((array) => {
-      if (!array) return array
-      new Uint8Array(array.buffer, array.byteOffset, array.byteLength).fill(randomValue++)
-      return array
-    })
-    try {
-      await ChannelOps.createTopUpPayload(client, account, descriptor, 10n, chainId, true)
-      await ChannelOps.createTopUpPayload(client, account, descriptor, 10n, chainId, true)
-    } finally {
-      random.mockRestore()
-    }
-
-    const requests = mocks.prepareTransactionRequest.mock.calls.map(([, request]) => request)
-    const validAfter = requests.map((request) =>
-      Number((request as { validAfter?: number }).validAfter),
-    )
-    const now = Math.floor(Date.now() / 1_000)
-
-    expect(requests).toMatchObject([
-      { feePayer: true, nonceKey: 'expiring', validAfter: expect.any(Number) },
-      { feePayer: true, nonceKey: 'expiring', validAfter: expect.any(Number) },
-    ])
-    expect(new Set(validAfter).size).toBe(2)
-    expect(validAfter.every((value) => value >= 0 && value < now)).toBe(true)
-  })
-
-  test('uses expiring nonces and entropy for unsponsored management transactions', async () => {
-    mocks.prepareTransactionRequest.mockClear()
-
-    await ChannelOps.createTopUpPayload(client, account, descriptor, 10n, chainId, false)
-
-    expect(mocks.prepareTransactionRequest).toHaveBeenCalledWith(
-      client,
-      expect.objectContaining({
-        nonceKey: 'expiring',
-        validAfter: expect.any(Number),
-      }),
-    )
-    expect(mocks.prepareTransactionRequest.mock.calls[0]?.[1]).not.toHaveProperty('feePayer')
-  })
-})

package/src/tempo/session/client/ChannelOps.ts

@@ -1,348 +0,0 @@
-/**
- * Shared client-side TIP-1034 channel operations.
- *
- * Provides the low-level helpers that both `tempo.session()` and
- * `tempo.session.manager()` rely on: channel ID computation,
- * transaction-bound descriptor construction, on-chain open/top-up payload
- * construction, voucher/close payload serialization, and transaction signing.
- *
- * @see https://tips.sh/1034-1
- */
-import { Hex } from 'ox'
-import { encodeFunctionData, isAddress, type Account, type Address, type Client } from 'viem'
-import { prepareTransactionRequest, signTransaction } from 'viem/actions'
-import { Transaction } from 'viem/tempo'
-
-import type { Challenge } from '../../../Challenge.js'
-import * as Credential from '../../../Credential.js'
-import * as Channel from '../precompile/Channel.js'
-import { escrowAbi } from '../precompile/escrow.abi.js'
-import { tip20ChannelEscrow } from '../precompile/Protocol.js'
-import type {
-  CloseCredentialPayload,
-  OpenCredentialPayload,
-  SessionCredentialPayload,
-  TopUpCredentialPayload,
-  VoucherCredentialPayload,
-} from '../precompile/Protocol.js'
-import { uint96 } from '../precompile/Protocol.js'
-import * as Voucher from '../precompile/Voucher.js'
-
-export type TempoChannelCall = {
-  to: Address
-  data: Hex.Hex
-}
-
-type AccountWithAccessKey = Account & {
-  accessKeyAddress?: unknown
-}
-
-/** Client-side cached channel metadata used for automatic voucher management. */
-export type ChannelEntry = {
-  /** TIP-1034 channel ID derived from descriptor, escrow, and chain ID. */
-  channelId: Hex.Hex
-  /** Highest cumulative amount this client has locally authorized. */
-  cumulativeAmount: bigint
-  /** Latest channel deposit known by the client. */
-  deposit: bigint
-  /** TIP-1034 descriptor required for vouchers, top-ups, and close credentials. */
-  descriptor: Channel.ChannelDescriptor
-  /** Escrow contract address used to derive `channelId`. */
-  escrow: Address
-  /** EVM chain ID used for channel ID and voucher domain separation. */
-  chainId: number
-  /** Whether the client considers the channel reusable for new vouchers. */
-  opened: boolean
-}
-
-function isObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null
-}
-
-function readOptionalAddress(value: unknown): Address | undefined {
-  return typeof value === 'string' && isAddress(value, { strict: false }) ? value : undefined
-}
-
-function readAccessKeyAddress(account: Account): Address | undefined {
-  return readOptionalAddress((account as AccountWithAccessKey).accessKeyAddress)
-}
-
-/** Returns random past seconds to distinguish otherwise-identical expiring transactions. */
-function randomValidAfter(): number {
-  const now = BigInt(Math.floor(Date.now() / 1_000))
-  const latest = now - 60n
-  if (latest <= 0n) return 0
-  return Number(BigInt(Hex.random(8)) % latest)
-}
-
-/** Resolves the voucher authority address for a client account. */
-export function resolveAuthorizedSigner(account: Account): Address {
-  return readAccessKeyAddress(account) ?? account.address
-}
-
-async function prepareTempoChannelTransaction(
-  client: Client,
-  parameters: {
-    account: Account
-    calls: readonly TempoChannelCall[]
-    feePayer?: boolean | undefined
-    feeToken: Address
-    validAfter?: number | undefined
-  },
-) {
-  const { account, calls, feePayer, feeToken, validAfter } = parameters
-  // Session management transactions are independent and short-lived, so they
-  // always use TIP-1009 expiring nonces. `feePayer` controls sponsorship only.
-  // viem's stable transaction request type does not yet expose Tempo's
-  // `calls`, `feePayer`, and `feeToken` fields together. Keep the cast at
-  // this boundary so session credential builders stay typed.
-  return prepareTransactionRequest(client, {
-    account,
-    calls,
-    nonceKey: 'expiring',
-    ...(feePayer ? { feePayer: true } : {}),
-    feeToken,
-    ...(validAfter !== undefined ? { validAfter } : {}),
-  } as never)
-}
-
-async function signPreparedTempoTransaction(client: Client, prepared: unknown): Promise<Hex.Hex> {
-  return (await signTransaction(client, prepared as never)) as Hex.Hex
-}
-
-/** Resolves the escrow precompile from local override, challenge hints, or canonical default. */
-export function resolveEscrow(
-  challenge: {
-    request: {
-      methodDetails?: unknown
-    }
-  },
-  escrowOverride?: Address | undefined,
-): Address {
-  const methodDetails = challenge.request.methodDetails
-  const challengeEscrow = isObject(methodDetails)
-    ? (readOptionalAddress(methodDetails.escrowContract) ??
-      readOptionalAddress(methodDetails.escrow))
-    : undefined
-  return escrowOverride ?? challengeEscrow ?? tip20ChannelEscrow
-}
-
-/** Serializes a session credential with a DID source bound to the payer account. */
-export function serializeCredential(
-  challenge: Challenge,
-  payload: SessionCredentialPayload,
-  chainId: number,
-  account: Account,
-): string {
-  return Credential.serialize({
-    challenge,
-    payload,
-    source: `did:pkh:eip155:${chainId}:${account.address}`,
-  })
-}
-
-/** Case-insensitive EVM address equality. */
-export function isSameAddress(a: Address, b: Address): boolean {
-  return a.toLowerCase() === b.toLowerCase()
-}
-
-/**
- * Signs and creates a TIP-1034 voucher credential payload for an existing channel.
- *
- * @see https://tips.sh/1034-1#execution-semantics
- */
-export async function createVoucherPayload(
-  client: Client,
-  account: Account,
-  descriptor: Channel.ChannelDescriptor,
-  cumulativeAmount: bigint,
-  chainId: number,
-  escrow: Address = tip20ChannelEscrow,
-): Promise<VoucherCredentialPayload> {
-  const channelId = Channel.computeId({
-    ...descriptor,
-    chainId,
-    escrow,
-  })
-  const amount = uint96(cumulativeAmount)
-  const signature = await Voucher.signVoucher(
-    client,
-    account,
-    { channelId, cumulativeAmount: amount },
-    escrow,
-    chainId,
-  )
-
-  return {
-    action: 'voucher',
-    channelId,
-    descriptor,
-    cumulativeAmount: amount.toString(),
-    signature,
-  }
-}
-
-/**
- * Signs and creates a TIP-1034 close credential payload for an existing channel.
- *
- * @see https://tips.sh/1034-1#execution-semantics
- */
-export async function createClosePayload(
-  client: Client,
-  account: Account,
-  descriptor: Channel.ChannelDescriptor,
-  cumulativeAmount: bigint,
-  chainId: number,
-  escrow: Address = tip20ChannelEscrow,
-): Promise<CloseCredentialPayload> {
-  const voucher = await createVoucherPayload(
-    client,
-    account,
-    descriptor,
-    cumulativeAmount,
-    chainId,
-    escrow,
-  )
-  return {
-    action: 'close',
-    channelId: voucher.channelId,
-    descriptor,
-    cumulativeAmount: voucher.cumulativeAmount,
-    signature: voucher.signature,
-  }
-}
-
-/**
- * Prepares, signs, and creates a TIP-1034 open credential payload.
- *
- * The channel descriptor uses the signed transaction's expiring nonce hash
- * because TIP-1034 binds each opened channel to that transaction context.
- *
- * @see https://tips.sh/1034-1#channel-identity-and-packed-state
- */
-export async function createOpenPayload(
-  client: Client,
-  account: Account,
-  parameters: {
-    chainId: number
-    deposit: bigint
-    escrow?: Address | undefined
-    feePayer?: boolean | undefined
-    initialAmount: bigint
-    operator?: Address | undefined
-    payee: Address
-    /** Calls executed atomically before the channel is opened. */
-    prefixCalls?: readonly TempoChannelCall[] | undefined
-    token: Address
-  },
-): Promise<OpenCredentialPayload> {
-  const authorizedSigner = resolveAuthorizedSigner(account)
-  const escrow = parameters.escrow ?? tip20ChannelEscrow
-  const operator = parameters.operator ?? '0x0000000000000000000000000000000000000000'
-  const salt = Hex.random(32)
-
-  const deposit = uint96(parameters.deposit)
-  const initialAmount = uint96(parameters.initialAmount)
-  const openData = encodeFunctionData({
-    abi: escrowAbi,
-    functionName: 'open',
-    args: [parameters.payee, operator, parameters.token, deposit, salt, authorizedSigner],
-  })
-  const prepared = await prepareTempoChannelTransaction(client, {
-    account,
-    calls: [...(parameters.prefixCalls ?? []), { to: escrow, data: openData }],
-    feePayer: parameters.feePayer,
-    feeToken: parameters.token,
-  })
-  const transaction = await signPreparedTempoTransaction(client, prepared)
-  const signed = Transaction.deserialize(transaction as Transaction.TransactionSerializedTempo)
-
-  const expiringNonceHash = Channel.computeExpiringNonceHash(
-    Channel.transactionForExpiringNonceHash({
-      ...(parameters.feePayer ? { feePayer: true } : {}),
-      transaction: signed,
-    }),
-    { sender: account.address },
-  )
-  const descriptor = {
-    authorizedSigner,
-    expiringNonceHash,
-    operator,
-    payee: parameters.payee,
-    payer: account.address,
-    salt,
-    token: parameters.token,
-  } satisfies Channel.ChannelDescriptor
-  const channelId = Channel.computeId({
-    ...descriptor,
-    chainId: parameters.chainId,
-    escrow,
-  })
-  const signature = await Voucher.signVoucher(
-    client,
-    account,
-    { channelId, cumulativeAmount: initialAmount },
-    escrow,
-    parameters.chainId,
-  )
-  return {
-    action: 'open',
-    type: 'transaction',
-    channelId,
-    transaction,
-    signature,
-    descriptor,
-    cumulativeAmount: initialAmount.toString(),
-    authorizedSigner: descriptor.authorizedSigner,
-  }
-}
-
-/**
- * Prepares, signs, and creates a TIP-1034 top-up credential payload.
- *
- * @see https://tips.sh/1034-1#execution-semantics
- */
-export async function createTopUpPayload(
-  client: Client,
-  account: Account,
-  descriptor: Channel.ChannelDescriptor,
-  additionalDeposit: bigint,
-  chainId: number,
-  feePayer?: boolean | undefined,
-  escrow: Address = tip20ChannelEscrow,
-  prefixCalls: readonly TempoChannelCall[] = [],
-): Promise<TopUpCredentialPayload> {
-  const channelId = Channel.computeId({
-    ...descriptor,
-    chainId,
-    escrow,
-  })
-  const deposit = uint96(additionalDeposit)
-  const prepared = await prepareTempoChannelTransaction(client, {
-    account,
-    calls: [
-      ...prefixCalls,
-      {
-        to: escrow,
-        data: encodeFunctionData({
-          abi: escrowAbi,
-          functionName: 'topUp',
-          args: [descriptor, deposit],
-        }),
-      },
-    ],
-    feePayer,
-    feeToken: descriptor.token,
-    validAfter: randomValidAfter(),
-  })
-  const transaction = await signPreparedTempoTransaction(client, prepared)
-
-  return {
-    action: 'topUp',
-    type: 'transaction',
-    channelId,
-    transaction,
-    descriptor,
-    additionalDeposit: deposit.toString(),
-  }
-}