mppx 0.0.1 → 0.1.0

package/src/tempo/client/ChannelOps.ts

@@ -0,0 +1,233 @@
+/**
+ * Shared client-side channel operations.
+ *
+ * Provides the low-level helpers that both `session()` (MethodIntent plugin)
+ * and `sessionManager()` (orchestrator) rely on: escrow resolution, channel
+ * ID computation, on-chain open/voucher/close payload construction, channel
+ * recovery from on-chain state, and credential serialization.
+ */
+import { Hex } from 'ox'
+import {
+  type Address,
+  encodeFunctionData,
+  type Account as viem_Account,
+  type Client as viem_Client,
+} from 'viem'
+import { prepareTransactionRequest, signTransaction } from 'viem/actions'
+import { Abis } from 'viem/tempo'
+import type { Challenge } from '../../Challenge.js'
+import * as Credential from '../../Credential.js'
+import * as defaults from '../internal/defaults.js'
+import { escrowAbi, getOnChainChannel } from '../stream/Chain.js'
+import * as Channel from '../stream/Channel.js'
+import type { StreamCredentialPayload } from '../stream/Types.js'
+import { signVoucher } from '../stream/Voucher.js'
+
+export type ChannelEntry = {
+  channelId: Hex.Hex
+  salt: Hex.Hex
+  cumulativeAmount: bigint
+  escrowContract: Address
+  chainId: number
+  opened: boolean
+}
+
+export function resolveChainId(challenge: Challenge): number {
+  const md = challenge.request.methodDetails as { chainId?: number } | undefined
+  return md?.chainId ?? 0
+}
+
+export function resolveEscrow(
+  challenge: { request: { methodDetails?: unknown } },
+  chainId: number,
+  escrowContractOverride?: Address,
+): Address {
+  const challengeEscrow = (challenge.request.methodDetails as { escrowContract?: string })
+    ?.escrowContract as Address | undefined
+  const escrow =
+    challengeEscrow ??
+    escrowContractOverride ??
+    ((defaults.escrowContract as Record<number, string>)[chainId] as Address | undefined)
+  if (!escrow)
+    throw new Error(
+      'No `escrowContract` available. Provide it in parameters or ensure the server challenge includes it.',
+    )
+  return escrow
+}
+
+export function serializeCredential(
+  challenge: Challenge,
+  payload: StreamCredentialPayload,
+  chainId: number,
+  account: viem_Account,
+): string {
+  return Credential.serialize({
+    challenge,
+    payload,
+    source: `did:pkh:eip155:${chainId}:${account.address}`,
+  })
+}
+
+export async function createVoucherPayload(
+  client: viem_Client,
+  account: viem_Account,
+  channelId: Hex.Hex,
+  cumulativeAmount: bigint,
+  escrowContract: Address,
+  chainId: number,
+  authorizedSigner?: Address | undefined,
+): Promise<StreamCredentialPayload> {
+  const signature = await signVoucher(
+    client,
+    account,
+    { channelId, cumulativeAmount },
+    escrowContract,
+    chainId,
+    authorizedSigner,
+  )
+  return {
+    action: 'voucher',
+    channelId,
+    cumulativeAmount: cumulativeAmount.toString(),
+    signature,
+  }
+}
+
+export async function createClosePayload(
+  client: viem_Client,
+  account: viem_Account,
+  channelId: Hex.Hex,
+  cumulativeAmount: bigint,
+  escrowContract: Address,
+  chainId: number,
+  authorizedSigner?: Address | undefined,
+): Promise<StreamCredentialPayload> {
+  const signature = await signVoucher(
+    client,
+    account,
+    { channelId, cumulativeAmount },
+    escrowContract,
+    chainId,
+    authorizedSigner,
+  )
+  return {
+    action: 'close',
+    channelId,
+    cumulativeAmount: cumulativeAmount.toString(),
+    signature,
+  }
+}
+
+export async function createOpenPayload(
+  client: viem_Client,
+  account: viem_Account,
+  options: {
+    authorizedSigner?: Address | undefined
+    escrowContract: Address
+    payee: Address
+    currency: Address
+    deposit: bigint
+    initialAmount: bigint
+    chainId: number
+    feePayer?: boolean | undefined
+  },
+): Promise<{ entry: ChannelEntry; payload: StreamCredentialPayload }> {
+  const { escrowContract, payee, currency, deposit, initialAmount, chainId, feePayer } = options
+  const authorizedSigner = options.authorizedSigner ?? account.address
+
+  const salt = Hex.random(32)
+  const channelId = Channel.computeId({
+    authorizedSigner,
+    chainId,
+    escrowContract,
+    payee,
+    payer: account.address,
+    salt,
+    token: currency,
+  })
+
+  const approveData = encodeFunctionData({
+    abi: Abis.tip20,
+    functionName: 'approve',
+    args: [escrowContract, deposit],
+  })
+  const openData = encodeFunctionData({
+    abi: escrowAbi,
+    functionName: 'open',
+    args: [payee, currency, deposit, salt, authorizedSigner],
+  })
+
+  const prepared = await prepareTransactionRequest(client, {
+    account,
+    calls: [
+      { to: currency, data: approveData },
+      { to: escrowContract, data: openData },
+    ],
+    ...(feePayer && { feePayer: true }),
+  } as never)
+  prepared.gas = prepared.gas! + 5_000n
+  const transaction = (await signTransaction(client, prepared as never)) as Hex.Hex
+
+  const signature = await signVoucher(
+    client,
+    account,
+    { channelId, cumulativeAmount: initialAmount },
+    escrowContract,
+    chainId,
+    options.authorizedSigner,
+  )
+
+  return {
+    entry: {
+      channelId,
+      salt,
+      cumulativeAmount: initialAmount,
+      escrowContract,
+      chainId,
+      opened: true,
+    },
+    payload: {
+      action: 'open',
+      type: 'transaction',
+      channelId,
+      transaction,
+      authorizedSigner,
+      cumulativeAmount: initialAmount.toString(),
+      signature,
+    },
+  }
+}
+
+/**
+ * Attempt to recover an existing on-chain channel by reading its state.
+ *
+ * If the channel has a positive deposit and is not finalized, returns a
+ * {@link ChannelEntry} with `cumulativeAmount` set to the on-chain settled
+ * amount (the safe starting point for new vouchers).
+ *
+ * Returns `undefined` if the channel doesn't exist, has zero deposit,
+ * or is already finalized.
+ */
+export async function tryRecoverChannel(
+  client: viem_Client,
+  escrowContract: Address,
+  channelId: Hex.Hex,
+  chainId: number,
+): Promise<ChannelEntry | undefined> {
+  try {
+    const onChain = await getOnChainChannel(client, escrowContract, channelId)
+
+    if (onChain.deposit > 0n && !onChain.finalized) {
+      return {
+        channelId,
+        salt: '0x' as Hex.Hex,
+        cumulativeAmount: onChain.settled,
+        escrowContract,
+        chainId,
+        opened: true,
+      }
+    }
+  } catch {}
+
+  return undefined
+}

package/src/tempo/client/Charge.ts

@@ -0,0 +1,84 @@
+import type * as Hex from 'ox/Hex'
+import { prepareTransactionRequest, signTransaction } from 'viem/actions'
+import { tempo as tempo_chain } from 'viem/chains'
+import { Actions } from 'viem/tempo'
+import * as Credential from '../../Credential.js'
+import * as MethodIntent from '../../MethodIntent.js'
+import * as Account from '../../viem/Account.js'
+import * as Client from '../../viem/Client.js'
+import * as z from '../../zod.js'
+import * as Attribution from '../Attribution.js'
+import * as Intents from '../Intents.js'
+import * as defaults from '../internal/defaults.js'
+
+/**
+ * Creates a Tempo charge method intent for usage on the client.
+ *
+ * @example
+ * ```ts
+ * import { tempo } from 'mppx/client'
+ * import { privateKeyToAccount } from 'viem/accounts'
+ *
+ * const charge = tempo.charge({
+ *   account: privateKeyToAccount('0x...'),
+ * })
+ * ```
+ */
+export function charge(parameters: charge.Parameters = {}) {
+  const { clientId } = parameters
+  const getClient = Client.getResolver({
+    chain: tempo_chain,
+    getClient: parameters.getClient,
+    rpcUrl: defaults.rpcUrl,
+  })
+  const getAccount = Account.getResolver({ account: parameters.account })
+
+  return MethodIntent.toClient(Intents.charge, {
+    context: z.object({
+      account: z.optional(z.custom<Account.getResolver.Parameters['account']>()),
+    }),
+
+    async createCredential({ challenge, context }) {
+      const chainId = challenge.request.methodDetails?.chainId
+      const client = await getClient({ chainId })
+      const account = getAccount(client, context)
+
+      const { request } = challenge
+      const { amount, currency, recipient, methodDetails } = request
+
+      const memo = methodDetails?.memo
+        ? (methodDetails.memo as Hex.Hex)
+        : Attribution.encode({ serverId: challenge.realm, clientId })
+
+      const prepared = await prepareTransactionRequest(client, {
+        account,
+        calls: [
+          Actions.token.transfer.call({
+            amount: BigInt(amount),
+            memo,
+            to: recipient as Hex.Hex,
+            token: currency as Hex.Hex,
+          }),
+        ],
+        ...(methodDetails?.feePayer && { feePayer: true }),
+      } as never)
+      // FIXME: figure out gas estimation issue for fee payer tx
+      prepared.gas = prepared.gas! + 5_000n
+      const signature = await signTransaction(client, prepared as never)
+
+      return Credential.serialize({
+        challenge,
+        payload: { signature, type: 'transaction' },
+        source: `did:pkh:eip155:${chainId}:${account.address}`,
+      })
+    },
+  })
+}
+
+export declare namespace charge {
+  type Parameters = {
+    /** Client identifier used to derive the client fingerprint in attribution memos. */
+    clientId?: string | undefined
+  } & Account.getResolver.Parameters &
+    Client.getResolver.Parameters
+}

package/src/tempo/client/MethodIntents.ts

@@ -0,0 +1,28 @@
+import { charge as charge_ } from './Charge.js'
+import { session as sessionIntent_ } from './Session.js'
+import { sessionManager as session_ } from './SessionManager.js'
+
+/**
+ * Creates both Tempo `charge` and `session` client method intents from shared parameters.
+ *
+ * @example
+ * ```ts
+ * import { Mppx, tempo } from 'mppx/client'
+ *
+ * const mppx = Mppx.create({
+ *   methods: [tempo({ account })],
+ * })
+ * ```
+ */
+export function tempo(parameters: tempo.Parameters = {}) {
+  return [charge_(parameters), sessionIntent_(parameters)] as const
+}
+
+export namespace tempo {
+  export type Parameters = charge_.Parameters & sessionIntent_.Parameters
+
+  /** Creates a Tempo `charge` client method intent for one-time TIP-20 token transfers. */
+  export const charge = charge_
+  /** Creates a client-side streaming session for managing payment channels. */
+  export const session = session_
+}