mppx 0.8.15 → 0.8.18

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(),
-  }
-}

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

@@ -1,111 +0,0 @@
-import type { Address } from 'viem'
-
-import type { MaybePromise } from '../../../internal/types.js'
-import type { ChannelEntry } from './ChannelOps.js'
-
-/** Store of reusable payer session channels keyed by payment scope. */
-export type ChannelStore = {
-  /** Returns the channel cached for `key`, when present. */
-  get(key: string): MaybePromise<ChannelEntry | undefined>
-  /** Inserts or replaces a channel entry. */
-  set(entry: ChannelEntry): MaybePromise<void>
-  /** Removes the channel cached for `key`. */
-  delete(key: string): MaybePromise<void>
-}
-
-/** Channel persistence and update notification for credential results. */
-export type ChannelSink = {
-  store: ChannelStore
-  notifyUpdate: (entry: ChannelEntry) => void
-}
-
-/** Returns the scope key for a reusable payer session channel. */
-export function channelKey(scope: {
-  payee: Address
-  token: Address
-  escrow: Address
-  chainId: number
-}): string {
-  const { payee, token, escrow, chainId } = scope
-  return `${payee.toLowerCase()}:${token.toLowerCase()}:${escrow.toLowerCase()}:${chainId}`
-}
-
-/** Returns the scope key for a stored channel entry. */
-export function entryKey(entry: ChannelEntry): string {
-  return channelKey({
-    payee: entry.descriptor.payee,
-    token: entry.descriptor.token,
-    escrow: entry.escrow,
-    chainId: entry.chainId,
-  })
-}
-
-/** Creates the default in-memory {@link ChannelStore}. */
-export function createChannelStore(): ChannelStore {
-  const channels = new Map<string, ChannelEntry>()
-  return {
-    get: (key) => channels.get(key),
-    set(entry) {
-      channels.set(entryKey(entry), entry)
-    },
-    delete(key) {
-      channels.delete(key)
-    },
-  } satisfies ChannelStore
-}
-
-/** JSON-safe projection of a {@link ChannelEntry}, with bigint amounts as decimal strings. */
-export type StoredChannel = Omit<ChannelEntry, 'cumulativeAmount' | 'deposit'> & {
-  /** Cumulative voucher authorization in raw token units, as a decimal string. */
-  cumulativeAmount: string
-  /** Channel deposit in raw token units, as a decimal string. */
-  deposit: string
-}
-
-/** Converts a channel entry into its JSON-safe stored form. */
-export function serializeEntry(entry: ChannelEntry): StoredChannel {
-  return {
-    ...entry,
-    cumulativeAmount: entry.cumulativeAmount.toString(),
-    deposit: entry.deposit.toString(),
-  }
-}
-
-/** Restores a channel entry from its JSON-safe stored form. */
-export function deserializeEntry(stored: StoredChannel): ChannelEntry {
-  return {
-    ...stored,
-    cumulativeAmount: BigInt(stored.cumulativeAmount),
-    deposit: BigInt(stored.deposit),
-  }
-}
-
-/** Prefix for serialized channel entries persisted by {@link createJsonChannelStore}. */
-const channelPrefix = 'chan:'
-
-/** Plain string key-value backend a {@link createJsonChannelStore} persists into. */
-export type JsonChannelKv = {
-  /** Returns the value stored at `key`, when present. */
-  get(key: string): MaybePromise<string | undefined>
-  /** Persists a `value` at `key`. */
-  set(key: string, value: string): MaybePromise<void>
-  /** Removes the value stored at `key`. */
-  delete(key: string): MaybePromise<void>
-}
-
-/** Wraps a string KV backend as a bigint-safe channel store. */
-export function createJsonChannelStore(kv: JsonChannelKv): ChannelStore {
-  return {
-    async get(key) {
-      const value = await kv.get(channelPrefix + key)
-      if (value === undefined) return undefined
-      return deserializeEntry(JSON.parse(value) as StoredChannel)
-    },
-    async set(entry) {
-      await kv.set(channelPrefix + entryKey(entry), JSON.stringify(serializeEntry(entry)))
-    },
-    async delete(key) {
-      await kv.delete(channelPrefix + key)
-    },
-  } satisfies ChannelStore
-}