mppx 0.6.31 → 0.8.0

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

@@ -0,0 +1,330 @@
+/**
+ * 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'
+
+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)
+}
+
+/** 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
+  },
+) {
+  const { account, calls, feePayer, feeToken } = parameters
+  // 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,
+    ...(feePayer ? { feePayer: true } : {}),
+    feeToken,
+  } 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
+    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: [{ 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,
+): Promise<TopUpCredentialPayload> {
+  const channelId = Channel.computeId({
+    ...descriptor,
+    chainId,
+    escrow,
+  })
+  const deposit = uint96(additionalDeposit)
+  const prepared = await prepareTempoChannelTransaction(client, {
+    account,
+    calls: [
+      {
+        to: escrow,
+        data: encodeFunctionData({
+          abi: escrowAbi,
+          functionName: 'topUp',
+          args: [descriptor, deposit],
+        }),
+      },
+    ],
+    feePayer,
+    feeToken: descriptor.token,
+  })
+  const transaction = await signPreparedTempoTransaction(client, prepared)
+
+  return {
+    action: 'topUp',
+    type: 'transaction',
+    channelId,
+    transaction,
+    descriptor,
+    additionalDeposit: deposit.toString(),
+  }
+}

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

@@ -0,0 +1,111 @@
+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
+}