Skip to content
LogoLogo

Open payment channels

An app opens a payment channel, and pays for metered use with vouchers of the access key.

Overview

The "Sessions" guides cover payment sessions over payment channels, not the package's sign-in session.

A payment channel pays for metered use with one deposit and many offchain vouchers. The Tempo Account deposits in the chain's TIP-1034 channel reserve, an escrow, and the access key signs a voucher for each unit of use, with no prompt. The payee closes the channel with the highest voucher, and the reserve returns the rest.

This guide opens the channel with Viem and verifies vouchers on the app's server. Pay with sessions leaves both to MPP, a protocol of HTTP 402 payments.

The demo opens a 0.05 OUSD channel on Tempo testnet, pays 0.001 OUSD for each fortune, and after the close shows what the server received and the channel returned.

Open a payment channelDemo

Walkthrough

The steps build the demo's React app and server.

Loading diagram...

Install the packages

The server verifies each voucher with ox, and serves its routes with Hono.

Create the instanceClient

The viem plugin adds Viem's channel actions to the instance, as accounts.channel.

tempo.config.ts
import { Accounts } from 'accounts'
import { viem } from 'accounts/plugins'
import { react } from 'accounts/react'
 
export const accounts = Accounts.create({
  // Each sign-in requests an access key that spends up to 1 OUSD for a day.
  accessKey: () => ({
    expiry: '1d',
    limits: [{ limit: '1', token: 'ousd' }],
  }),
  chain: 'testnet',
  plugins: [react(), viem()], 
})

Without scopes, the access key may open and top up a channel on the reserve, and each deposit counts against its token's limit.

Sign the user inClient

dialog.signIn opens Tempo ID's dialog over the page.

import { accounts } from './tempo.config.js'
 
export function App() {
  const { session } = accounts.useSession()
 
  if (!session)
    return (
      <button onClick={() => accounts.dialog.signIn()} type="button">
        Sign in with Tempo
      </button>
    )
 
  return <p>Signed in as {session.user.email}</p>
}

Open the channelClient

openSync deposits in the reserve, and returns the fields that name the channel in each voucher, top-up, and close. The component keeps them in its state.

import type { Channel } from 'ox/tempo'
import { useState } from 'react'
import { parseUnits } from 'viem'
import { Addresses } from 'viem/tempo'
import { accounts } from './tempo.config.js'
 
export function Open() {
  const { session } = accounts.useSession()
  const [channel, setChannel] = useState<Channel.Resolved>()
 
  if (channel) return <p>The channel is open.</p>
 
  return (
    <button
      onClick={async () => {
        const { channelId, deposit, receipt, ...channel } =
          await accounts.channel.openSync({
            // The access key signs each voucher.
            authorizedSigner: session!.accessKey!.keyAuthorization.keyId,
            deposit: parseUnits('0.05', 6),
            feeToken: Addresses.ousd,
            // The address of the server's account.
            payee: '0x401a632ADBFCc5C8Ce7D2B80D16f7DFc47b642bc',
            token: Addresses.ousd,
          })
        setChannel(channel)
      }}
      type="button"
    >
      Open a channel
    </button>
  )
}
  • authorizedSigner names the access key as the voucher signer, or the reserve refuses its vouchers at the close.
  • feeToken names a token of the access key's limits, since the access key pays fees in no other token. A transfer pays its fee in the token that it sends, but an open sends no token, so it names one.

Pay with a voucherClient

A voucher names the channel's cumulative total, so each voucher replaces the last.

import type { Channel } from 'ox/tempo'
import { useState } from 'react'
import { parseUnits } from 'viem'
import { accounts } from './tempo.config.js'
 
export function Pay(props: Pay.Props) {
  const { channel } = props
  const [fortune, setFortune] = useState<string>()
  // The total of the last voucher that the server accepted, in base units.
  const [spent, setSpent] = useState(0n)
 
  return (
    <>
      <button
        onClick={async () => {
          const cumulativeAmount = spent + parseUnits('0.001', 6)
          const signature = await accounts.channel.signVoucher({
            channel,
            cumulativeAmount,
          })
 
          const response = await fetch('/api/fortune', {
            body: JSON.stringify({
              channel,
              cumulativeAmount: cumulativeAmount.toString(),
              signature,
            }),
            headers: { 'content-type': 'application/json' },
            method: 'POST',
          })
          // A refused voucher keeps the last total.
          if (!response.ok) return
 
          const { fortune } = (await response.json()) as { fortune: string }
          setFortune(fortune)
          setSpent(cumulativeAmount)
        }}
        type="button"
      >
        Pay 0.001 OUSD
      </button>
      <p>{fortune}</p>
    </>
  )
}
 
export declare namespace Pay {
  type Props = {
    /** The channel, as its open returns it. */
    channel: Channel.Resolved
  }
}

Verify the voucher on the serverServer

The server accepts a voucher only if it passes every check below, and keeps each channel's highest voucher in a store for the close. The later server steps import this module.

vouchers.ts
import { Store } from 'accounts'
import { Address } from 'ox'
import { Channel, SignatureEnvelope } from 'ox/tempo'
import { createClient, type Hex, http, parseUnits } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { tempoModerato } from 'viem/chains'
import { Actions, Addresses } from 'viem/tempo'
 
export const client = createClient({
  account: privateKeyToAccount(process.env.PAYEE_PRIVATE_KEY as Hex),
  chain: tempoModerato.extend({ feeToken: Addresses.ousd }),
  transport: http(),
})
 
// The highest voucher of each channel.
export const store = Store.memory()
 
export type Voucher = {
  channel: Channel.Resolved
  cumulativeAmount: bigint
  signature: Hex
}
 
export async function accept(voucher: Voucher) {
  const { channel, cumulativeAmount, signature } = voucher
  const chainId = client.chain.id
  const channelId = Channel.computeId(channel, { chainId })
 
  if (!Address.isEqual(channel.payee, client.account.address)) return false
  if (!Address.isEqual(channel.token, Addresses.ousd)) return false
 
  const signed = SignatureEnvelope.verify(SignatureEnvelope.from(signature), {
    address: channel.authorizedSigner,
    payload: Channel.getVoucherSignPayload({
      chainId,
      channelId,
      cumulativeAmount,
    }),
  })
  if (!signed) return false
 
  const last = (await store.getItem(channelId)) as Voucher | undefined
  const paid = last?.cumulativeAmount ?? 0n
  if (cumulativeAmount < paid + parseUnits('0.001', 6)) return false
 
  const state = await Actions.channel.getStates(client, { channel: channelId })
  if (state.closeRequestedAt !== 0) return false
  if (cumulativeAmount > state.deposit) return false
 
  await store.setItem(channelId, voucher)
  return true
}
CheckRefuses
Payee and tokenA channel that pays another account, or another token
SignatureA voucher that the access key did not sign
AmountA voucher that pays less than the price of the unit
Close requestA channel whose payer requested a close
DepositA voucher that the deposit does not cover

Serve the paid routeServer

The route answers 402 for a refused voucher. Channel.from throws for a malformed channel.

import { Hono } from 'hono'
import { Channel } from 'ox/tempo'
import { accept } from './vouchers.js'
 
const app = new Hono()
 
app.post('/api/fortune', async (c) => {
  const body = await c.req.json()
  const paid = await accept({
    channel: Channel.from(body.channel),
    cumulativeAmount: BigInt(body.cumulativeAmount),
    signature: body.signature,
  })
 
  if (!paid) return c.json({ error: 'The voucher is refused.' }, 402)
  return c.json({ fortune: 'Pay for what you use.' })
})
 
export default app

Close the channel on the serverServer

closeSync sends the highest voucher to the reserve, which pays the payee its amount and returns the rest to the Tempo Account. The payee pays the fee, so its address holds OUSD.

import { Hono } from 'hono'
import { Channel } from 'ox/tempo'
import { Actions } from 'viem/tempo'
import { accept, client, store, type Voucher } from './vouchers.js'
 
const app = new Hono()
 
app.post('/api/fortune', async (c) => {
  const body = await c.req.json()
  const paid = await accept({
    channel: Channel.from(body.channel),
    cumulativeAmount: BigInt(body.cumulativeAmount),
    signature: body.signature,
  })
 
  if (!paid) return c.json({ error: 'The voucher is refused.' }, 402)
  return c.json({ fortune: 'Pay for what you use.' })
})
 
app.post('/api/close', async (c) => {
  const body = await c.req.json()
  const channelId = Channel.computeId(Channel.from(body.channel), {
    chainId: client.chain.id,
  })
 
  const voucher = (await store.getItem(channelId)) as Voucher | undefined
  if (!voucher) return c.json({ error: 'The channel holds no voucher.' }, 404)
 
  const { refundedToPayer, settledToPayee } = await Actions.channel.closeSync(
    client,
    { ...voucher, captureAmount: voucher.cumulativeAmount },
  )
  await store.removeItem(channelId)
 
  return c.json({
    refundedToPayer: refundedToPayer.toString(),
    settledToPayee: settledToPayee.toString(),
  })
})
 
export default app

Request the closeClient

Close posts the app's channel to the route.

import type { Channel } from 'ox/tempo'
 
export function Close(props: Close.Props) {
  const { channel } = props
 
  return (
    <button
      onClick={() =>
        fetch('/api/close', {
          body: JSON.stringify({ channel }),
          headers: { 'content-type': 'application/json' },
          method: 'POST',
        })
      }
      type="button"
    >
      Close the channel
    </button>
  )
}
 
export declare namespace Close {
  type Props = {
    /** The channel, as its open returns it. */
    channel: Channel.Resolved
  }
}

Use cases

Each use case calls one more channel action: on the page, through the client of the viem plugin, or on the server, through the payee's client.

Top up the channel

topUpSync adds to the deposit, and the server reads the new deposit from getStates. Render TopUp beside Pay.

import type { Channel } from 'ox/tempo'
import { parseUnits } from 'viem'
import { Addresses } from 'viem/tempo'
import { accounts } from './tempo.config.js'
 
export function TopUp(props: TopUp.Props) {
  const { channel } = props
 
  return (
    <button
      onClick={() =>
        accounts.channel.topUpSync({
          additionalDeposit: parseUnits('0.05', 6),
          channel,
          feeToken: Addresses.ousd,
        })
      }
      type="button"
    >
      Add 0.05 OUSD
    </button>
  )
}
 
export declare namespace TopUp {
  type Props = {
    /** The channel, as its open returns it. */
    channel: Channel.Resolved
  }
}

Settle before the close

settleSync collects up to a voucher from a long-lived channel, and keeps it open. Add settle to the server of the close step.

import { Hono } from 'hono'
import { Channel } from 'ox/tempo'
import type { Hex } from 'viem'
import { Actions } from 'viem/tempo'
import { accept, client, store, type Voucher } from './vouchers.js'
 
const app = new Hono()
 
app.post('/api/fortune', async (c) => {
  const body = await c.req.json()
  const paid = await accept({
    channel: Channel.from(body.channel),
    cumulativeAmount: BigInt(body.cumulativeAmount),
    signature: body.signature,
  })
 
  if (!paid) return c.json({ error: 'The voucher is refused.' }, 402)
  return c.json({ fortune: 'Pay for what you use.' })
})
 
app.post('/api/close', async (c) => {
  const body = await c.req.json()
  const channelId = Channel.computeId(Channel.from(body.channel), {
    chainId: client.chain.id,
  })
 
  const voucher = (await store.getItem(channelId)) as Voucher | undefined
  if (!voucher) return c.json({ error: 'The channel holds no voucher.' }, 404)
 
  const { refundedToPayer, settledToPayee } = await Actions.channel.closeSync(
    client,
    { ...voucher, captureAmount: voucher.cumulativeAmount },
  )
  await store.removeItem(channelId)
 
  return c.json({
    refundedToPayer: refundedToPayer.toString(),
    settledToPayee: settledToPayee.toString(),
  })
})
 
async function settle(channelId: Hex) {
  const voucher = (await store.getItem(channelId)) as Voucher | undefined
  if (!voucher) return undefined
 
  const { deltaPaid } = await Actions.channel.settleSync(client, voucher)
  return deltaPaid
}
 
export default app

The reserve refuses a voucher that is not above the settled amount.

Withdraw without the payee

If the server never closes the channel, the app takes the deposit back itself. requestCloseSync starts the reserve's timer, and the server then accepts no voucher. After 15 minutes, withdrawSync returns the deposit that no voucher settled.

The filled scopes allow neither call. Named scopes replace them, so the access key names each call of the reserve that it makes.

import type { Channel } from 'ox/tempo'
import { Addresses } from 'viem/tempo'
import { accounts } from './tempo.config.js'
 
export function Withdraw(props: Withdraw.Props) {
  const { channel } = props
 
  return (
    <>
      <button
        onClick={() =>
          accounts.channel.requestCloseSync({ channel, feeToken: Addresses.ousd }) 
        }
        type="button"
      >
        Request the close
      </button>
      {/* The reserve allows the withdrawal 15 minutes after the request. */}
      <button
        onClick={() =>
          accounts.channel.withdrawSync({ channel, feeToken: Addresses.ousd }) 
        }
        type="button"
      >
        Withdraw the deposit
      </button>
    </>
  )
}
 
export declare namespace Withdraw {
  type Props = {
    /** The channel, as its open returns it. */
    channel: Channel.Resolved
  }
}

Next steps