@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/internal/ConfigurableAccount.ts

@@ -0,0 +1,1315 @@
+/**
+ * Configurable accounts (TIP-1107) on the chains that `CONFIGURABLE_ACCOUNTS` names: the
+ * configurations that Tempo ID stores for those chains, the owners' view of each configurable
+ * account, and the transactions that change the owners. On such a chain, a key that Tempo ID created
+ * owns the account that its initial configuration derives, and a linked wallet.tempo passkey owns its
+ * own address until an upgrade in place (TIP-1113) makes it configurable. A configuration update adds
+ * an owner to an account that is already configurable. Every configuration has threshold 1, so each
+ * owner signs alone.
+ * @module
+ */
+import { and, eq, gt, sql } from 'drizzle-orm'
+import { Address, Hex, PublicKey, Secp256k1 } from 'ox'
+import {
+  AccountConfig,
+  type KeyAuthorization,
+  SignatureEnvelope,
+} from 'ox/tempo'
+import {
+  type Client as Client_,
+  createClient,
+  http,
+  type HttpTransport,
+  type LocalAccount,
+} from 'viem'
+import {
+  prepareTransactionRequest,
+  sendRawTransactionSync,
+  signTransaction,
+} from 'viem/actions'
+import { Authentication } from 'ox/webauthn'
+import {
+  Account,
+  Actions,
+  Transaction,
+  type Transport,
+  withRelay,
+} from 'viem/tempo'
+import { z } from 'zod'
+import * as Schema from '../app/db/schema.js'
+import * as Chain from './Chain.js'
+import * as ChainList from './ChainList.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import { tip20 } from './KeyAuthorization.js'
+import * as Owner from './Owner.js'
+import type * as Passkey from './Passkey.js'
+import type * as Realm from './Realm.js'
+
+/**
+ * The chain's configuration of the account differs from the stored one, such as after a change that
+ * Tempo ID did not send, or an upgrade on the chain that Tempo ID did not record.
+ */
+export class ConflictError extends ErrorResponse.define('config_conflict') {
+  override readonly name = 'ConfigurableAccount.ConflictError'
+
+  constructor(options: ConflictError.Options) {
+    super({
+      error_description: `Configuration conflict: the chain's configuration of ${options.account} differs from the stored one. Reload the account, and try again.`,
+      field: 'account',
+      meta: { account: options.account },
+    })
+  }
+}
+
+export declare namespace ConflictError {
+  type Options = {
+    /** The account's address. */
+    account: string
+  }
+}
+
+/** The deployment has no configurable accounts, or the request names a chain whose accounts are not. */
+export class DisabledError extends ErrorResponse.define(
+  'configurable_accounts_disabled',
+) {
+  override readonly name = 'ConfigurableAccount.DisabledError'
+
+  constructor(options: DisabledError.Options = {}) {
+    const { chain, configured = [] } = options
+    super(
+      chain && configured.length > 0
+        ? {
+            error_description: `Configurable accounts are not available on the chain \`${chain}\`. Select ${configured.map((name) => `\`${name}\``).join(' or ')}.`,
+            field: 'chain',
+            meta: { chain, configured: configured.join(',') },
+          }
+        : {
+            error_description:
+              'Configurable accounts are not available on this deployment. Use the account as it is.',
+            field: 'chain',
+          },
+    )
+  }
+}
+
+export declare namespace DisabledError {
+  type Options = {
+    /** The chain that the request names. */
+    chain?: string | undefined
+    /** The chains whose accounts are configurable, by name. */
+    configured?: readonly string[] | undefined
+  }
+}
+
+/**
+ * The account is not configurable on the chain: an owner joins only a configurable account, and only
+ * an account that a passkey owns upgrades in place.
+ */
+export class NotConfigurableError extends ErrorResponse.define(
+  'not_configurable',
+) {
+  override readonly name = 'ConfigurableAccount.NotConfigurableError'
+
+  constructor(options: NotConfigurableError.Options) {
+    const { account } = options
+    super({
+      error_description:
+        options.reason === 'cloud'
+          ? `Not configurable: a cloud wallet owns ${account}, and only an account that a passkey owns upgrades in place. Use an account that is configurable from its creation.`
+          : `Not configurable: ${account} is not a configurable account yet. Upgrade it with its passkey, then add the owner.`,
+      field: 'account',
+      meta: { account, reason: options.reason },
+    })
+  }
+}
+
+export declare namespace NotConfigurableError {
+  type Options = {
+    /** The account's address. */
+    account: string
+    /**
+     * Why: a cloud wallet's account, which no upgrade covers (`cloud`), or an account that must
+     * upgrade before an owner joins (`upgrade`).
+     */
+    reason: 'cloud' | 'upgrade'
+  }
+}
+
+/** The account already holds the owner that the request adds, or is already configurable. */
+export class OwnerExistsError extends ErrorResponse.define('owner_exists') {
+  override readonly name = 'ConfigurableAccount.OwnerExistsError'
+
+  constructor(options: OwnerExistsError.Options) {
+    super({
+      error_description: {
+        configurable: `Owner exists: ${options.account} is already a configurable account. Add an owner to it instead.`,
+        passkey: `Owner exists: a passkey already owns ${options.account}. Use the account as it is.`,
+      }[options.owner],
+      field: options.owner === 'passkey' ? 'account' : 'wallet',
+      meta: { account: options.account, owner: options.owner },
+    })
+  }
+}
+
+export declare namespace OwnerExistsError {
+  type Options = {
+    /** The account's address. */
+    account: string
+    /** What the account already holds: a passkey, or a configuration. */
+    owner: 'configurable' | 'passkey'
+  }
+}
+
+/**
+ * A wallet.tempo passkey's account is a root account on a chain whose accounts are configurable, so
+ * no key signs for it there until its upgrade.
+ */
+export class UpgradeRequiredError extends ErrorResponse.define(
+  'upgrade_required',
+) {
+  override readonly name = 'ConfigurableAccount.UpgradeRequiredError'
+
+  constructor(options: UpgradeRequiredError.Options) {
+    super({
+      error_description: `Upgrade required: Tempo Account ${options.account} is not a configurable account on this chain yet. Upgrade it on the account page, then authorize again.`,
+      field: 'key_authorization.account',
+      meta: { account: options.account },
+    })
+  }
+}
+
+export declare namespace UpgradeRequiredError {
+  type Options = {
+    /** The account's address. */
+    account: string
+  }
+}
+
+/**
+ * The client ID that a passkey's signature challenge of a configuration change names, in place of an
+ * app's. No app's client ID has this form.
+ */
+export const clientId = 'tempo-id:account-config'
+
+/** How long a prepared transaction stays valid, in seconds, as long as a passkey challenge. */
+export const lifetime = 5 * 60
+
+/** The threshold of every configuration that Tempo ID installs, so each owner signs alone. */
+export const threshold = 1
+
+/** pathUSD, the TIP-20 token of every Tempo chain's genesis. */
+const pathUsd = '0x20c0000000000000000000000000000000000000'
+
+/** A private key whose public key fills a signer that never signs with it. */
+const placeholder = `0x${'0'.repeat(63)}1` as const
+
+/**
+ * The selectors of the TIP-20 calls of 0 that register a key. An approval of 0 would replace an
+ * allowance that the account gave, so none registers a key.
+ */
+const selectors = {
+  transfer: '0xa9059cbb',
+  transferWithMemo: '0x95777d59',
+} as const
+
+/** The prefix of the `verification` identifier of a change that waits for a passkey's signature. */
+const pendingPrefix = 'account-config:'
+
+/**
+ * A client that {@link client} returns: a plain HTTP transport, or a sponsor relay in front of one.
+ * The type names the transports explicitly, since declaration emit cannot name the relay transport
+ * that `withRelay` infers.
+ */
+export type Client = Client_<
+  HttpTransport | Transport.Relay,
+  Entry['definition']
+>
+
+/** A configurable account's configuration on one chain, as Tempo ID stores it. */
+export type Config = {
+  /**
+   * The account's address: the key's own, which an upgrade kept, or the one that the initial
+   * configuration derives for an account that is configurable from its creation.
+   */
+  address: Address.Address
+  /** The ID of the chain where the configuration is live. */
+  chainId: number
+  /**
+   * The address of the key whose account this is: `address` for an upgrade, or the key that created
+   * the account, which is its first owner.
+   */
+  key: Address.Address
+  /** The owners, in the configuration's canonical order. */
+  owners: readonly Owner.Configurable.Owner[]
+  /** The 32-byte salt, hex. */
+  salt: Hex.Hex
+  /** The total owner weight that a signature needs. */
+  threshold: number
+  /** The configuration version. A creation installs version 0, and an upgrade version 1. */
+  version: bigint
+}
+
+/** Zod schemas for stored configurations and pending changes. */
+namespace schema {
+  const address = z.templateLiteral([
+    '0x',
+    z.string().regex(/^[0-9a-fA-F]{40}$/),
+  ])
+  const hex = z.templateLiteral(['0x', z.string().regex(/^[0-9a-fA-F]*$/)])
+
+  /** The `owners` column. */
+  export const owners = z.array(
+    z.object({
+      address,
+      type: z.string(),
+      weight: z.number().int().positive(),
+    }),
+  )
+
+  /** A configuration as a pending change stores it, with the version as a decimal string. */
+  const config = z.object({
+    address,
+    chainId: z.number().int(),
+    key: address,
+    owners,
+    salt: hex,
+    threshold: z.number().int(),
+    version: z.string().regex(/^[0-9]+$/),
+  })
+
+  /** A change that waits for a passkey's signature, as the `verification` table stores it. */
+  export const pending = z.object({
+    current: config.optional(),
+    registration: z.object({ digest: hex, transaction: hex }).optional(),
+    target: config,
+    transaction: hex,
+  })
+}
+
+/**
+ * Returns `owners` as they act on the chain `chainId`, which `CONFIGURABLE_ACCOUNTS` names. Each
+ * stored configuration applies, and a key that Tempo ID created without one carries the initial
+ * configuration that it owns alone, from {@link created}. A linked key without one, such as a
+ * wallet.tempo passkey, stays a root key until its upgrade. A key that co-owns another account is no
+ * account of its own. The view's passkey and server signer come from the user's keys among the
+ * configuration's owners.
+ */
+export function apply<const type extends string>(
+  owners: readonly Owner.Owner<type>[],
+  options: apply.Options,
+): readonly Owner.Owner<type>[] {
+  const { chainId } = options
+  // Each key is read by its own address, since a configuration already applied names another.
+  const find = (address: Address.Address) =>
+    owners.find((entry) => Address.isEqual(Owner.key(entry), address))
+  const configs = [
+    ...options.configs,
+    ...owners.flatMap((entry) =>
+      entry.linked ||
+      options.configs.some((config) =>
+        Address.isEqual(config.key, Owner.key(entry)),
+      )
+        ? []
+        : [created({ chainId, key: Owner.key(entry), type: entry.type })],
+    ),
+  ]
+
+  // A key that the configuration of another account lists co-owns that account, so it acts as no
+  // account of its own.
+  const cosigners = new Set(
+    configs.flatMap((config) =>
+      config.owners
+        .filter((entry) => !Address.isEqual(entry.address, config.key))
+        .map((entry) => entry.address.toLowerCase()),
+    ),
+  )
+
+  return owners
+    .filter((entry) => !cosigners.has(Owner.key(entry).toLowerCase()))
+    .map((entry) => {
+      const config = configs.find((candidate) =>
+        Address.isEqual(candidate.key, Owner.key(entry)),
+      )
+      if (!config) return entry
+
+      const members = config.owners.flatMap((member) => {
+        const found = find(member.address)
+        return found ? [found] : []
+      })
+      const passkey = members.find((member) => member.credential)
+      const server = members.find((member) => member.signer)
+      const owner = Owner.from({
+        account: toAccount(config),
+        createdAt: entry.createdAt,
+        credential: passkey?.credential,
+        linked: entry.linked,
+        realm: entry.realm,
+        signer: server?.signer
+          ? async (c, options) =>
+              toAccount(config, {
+                signers: [await server.signer!(c, options)],
+              })
+          : undefined,
+        type: entry.type,
+      })
+      const configurable = {
+        chainId: config.chainId,
+        owner,
+        owners: config.owners,
+      }
+      // The view names itself, so `Owner.on` returns it again, and `Owner.configured` tells it apart.
+      owner.configurable = configurable
+      return { ...entry, configurable }
+    })
+}
+
+export declare namespace apply {
+  type Options = {
+    /** The ID of the chain, which `CONFIGURABLE_ACCOUNTS` names. */
+    chainId: number
+    /** The user's stored configurations on that chain. */
+    configs: readonly Config[]
+  }
+}
+
+/**
+ * Returns the chains whose accounts are configurable: those that `CONFIGURABLE_ACCOUNTS` names, in
+ * its order, each with its ID, its RPC URL, and Viem's definition of it. A name that is neither built
+ * in nor listed, or a chain that is no Tempo chain, is left out, since `App.create` refuses both when
+ * the Worker starts.
+ */
+export function chains(options: chains.Options): readonly Entry[] {
+  // Every chain that the list resolves is one of `Chain.known`, whose IDs `ChainList.known` holds.
+  return ChainList.configurable(options).flatMap((entry) => {
+    const definition = Chain.known.find((chain) => chain.id === entry.chainId)
+    return definition ? [{ ...entry, definition }] : []
+  })
+}
+
+export declare namespace chains {
+  type Options = ChainList.configurable.Options
+}
+
+/** A chain whose accounts are configurable, as {@link chains} returns it. */
+export type Entry = {
+  /** The chain's ID. */
+  chainId: number
+  /** Viem's definition of the chain. */
+  definition: (typeof Chain.known)[number]
+  /** The chain's name, which the `chain` parameter carries. */
+  name: string
+  /** The RPC URL that serves the chain, or `undefined` for the chain's own. */
+  rpcUrl: string | undefined
+}
+
+/**
+ * Returns the chain `chainId` when `CONFIGURABLE_ACCOUNTS` names it, or `undefined` without a chain
+ * or for another chain.
+ */
+export function on(options: on.Options): Entry | undefined {
+  const { chainId, env } = options
+  if (chainId === undefined) return undefined
+  return chains({
+    rpcUrl: env.TEMPO_RPC_URL,
+    rpcUrls: env.RPC_URLS,
+    value: env.CONFIGURABLE_ACCOUNTS,
+  }).find((entry) => entry.chainId === chainId)
+}
+
+export declare namespace on {
+  type Options = {
+    /** The chain's ID, if any. */
+    chainId?: number | undefined
+    /** The deployment variables that name the chains. */
+    env: Owner.Env
+  }
+}
+
+/**
+ * Creates a client of `chain` that sends configurable-account transactions. When `apiUrl`, the
+ * chain's Tempo API, holds a key, its sponsor relay at `/rpc/sponsor/<chainId>` fills and co-signs
+ * each transaction, so the account pays no fee. Without a key, each account pays its own fees.
+ */
+export function client(options: client.Options): Client {
+  const { apiUrl, chain } = options
+  const sponsor = (() => {
+    if (!apiUrl) return undefined
+    // The URL holds the key in its user name and password, such as `tempo:sk:…`, which the URL
+    // splits at the first colon. The API reads the key from a header.
+    const url = new URL(apiUrl)
+    const key = [url.username, url.password]
+      .filter(Boolean)
+      .map(decodeURIComponent)
+      .join(':')
+    if (!key) return undefined
+    url.username = ''
+    url.password = ''
+    // The API can sit under a path, such as behind a gateway, which a root-relative URL would drop.
+    url.pathname = `${url.pathname.replace(/\/$/, '')}/rpc/sponsor/${chain.chainId}`
+    return { key, url: url.href }
+  })()
+  const transport = http(chain.rpcUrl, { retryCount: 0 })
+  return createClient({
+    chain: chain.definition,
+    transport: sponsor
+      ? withRelay(
+          transport,
+          http(sponsor.url, {
+            fetchOptions: { headers: { 'tempo-api-key': sponsor.key } },
+            retryCount: 0,
+          }),
+        )
+      : transport,
+  })
+}
+
+export declare namespace client {
+  type Options = {
+    /** The chain's Tempo API URL, as `Chain.apiUrl` returns it, with its key as user information. */
+    apiUrl: string | undefined
+    /** The chain, as {@link chains} returns it. */
+    chain: Entry
+  }
+}
+
+/**
+ * Returns the initial configuration of the account that `key`, a key that Tempo ID created, owns
+ * alone: version 0 at threshold 1, with the zero salt. The configuration derives the account's
+ * address from the key alone, so no row stores it and no transaction installs it. The account's first
+ * transaction carries it.
+ */
+export function created(options: created.Options): Config {
+  const { chainId, key, type } = options
+  const initial = from({
+    // `toAccount` derives the address of a version 0 configuration, which replaces this one.
+    address: key,
+    chainId,
+    key,
+    owners: [{ address: key, type, weight: 1 }],
+    salt: `0x${'0'.repeat(64)}`,
+    threshold,
+    version: 0n,
+  })
+  return from({ ...initial, address: toAccount(initial).address })
+}
+
+export declare namespace created {
+  type Options = {
+    /** The ID of the chain, which `CONFIGURABLE_ACCOUNTS` names. */
+    chainId: number
+    /** The address of the key, such as a Privy wallet or a registered passkey. */
+    key: Address.Address
+    /** The kind of the key, such as `privy` or `webAuthn`. */
+    type: string
+  }
+}
+
+/**
+ * Instantiates a {@link Config}.
+ *
+ * @example
+ * ```ts
+ * const config = ConfigurableAccount.from({
+ *   address: '0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c',
+ *   chainId: 31318,
+ *   owners: [{ address: '0x8c3b…', type: 'privy', weight: 1 }],
+ *   salt: '0x…',
+ *   threshold: 1,
+ *   version: 1n,
+ * })
+ * ```
+ */
+export function from(value: Config): Config {
+  return value
+}
+
+/** Returns the stored configurations of the user's accounts on the chain `chainId`. */
+export async function list(
+  db: Realm.Database,
+  options: list.Options,
+): Promise<readonly Config[]> {
+  const rows = await db
+    .select()
+    .from(Schema.accountConfigs)
+    .where(
+      and(
+        eq(Schema.accountConfigs.chainId, options.chainId),
+        eq(Schema.accountConfigs.userId, options.userId),
+      ),
+    )
+  return rows.map((row) =>
+    from({
+      address: Address.checksum(row.address as Address.Address),
+      chainId: row.chainId,
+      key: Address.checksum(row.key as Address.Address),
+      owners: schema.owners.parse(row.owners).map((owner) => ({
+        ...owner,
+        address: Address.checksum(owner.address),
+      })),
+      salt: row.salt as Hex.Hex,
+      threshold: row.threshold,
+      version: BigInt(row.version),
+    }),
+  )
+}
+
+export declare namespace list {
+  type Options = {
+    /** The chain's ID. */
+    chainId: number
+    /** The user's ID. */
+    userId: string
+  }
+}
+
+/**
+ * Returns the configuration that adds `add` to the account at `address`, in one change: an upgrade
+ * that keeps the account's key as an owner when `current` is absent, or an update of `current`
+ * otherwise.
+ */
+export function next(options: next.Options): Config {
+  const { add = [], address, chainId, current } = options
+  const owners = [
+    ...(current?.owners ?? [{ address, type: options.type, weight: 1 }]),
+    ...add,
+  ]
+  const input = owners.map((entry) => ({
+    owner: entry.address,
+    weight: entry.weight,
+  }))
+  const config = current
+    ? AccountConfig.update(toOx(current), { owners: input, threshold })
+    : AccountConfig.fromUpgrade(address, { owners: input, threshold })
+  return from({
+    address,
+    chainId,
+    key: current?.key ?? address,
+    // The configuration sorts its owners, so each keeps its kind by address.
+    owners: config.owners.map((entry) => ({
+      address: Address.checksum(entry.owner),
+      type: owners.find((candidate) =>
+        Address.isEqual(candidate.address, entry.owner),
+      )!.type,
+      weight: Number(entry.weight),
+    })),
+    salt: config.salt,
+    threshold: Number(config.threshold),
+    version: BigInt(config.version),
+  })
+}
+
+export declare namespace next {
+  type Options = {
+    /** The owners that the configuration adds. Absent for an upgrade that adds none. */
+    add?: readonly Owner.Configurable.Owner[] | undefined
+    /** The account's address. */
+    address: Address.Address
+    /** The ID of the chain where the configuration is live. */
+    chainId: number
+    /** The account's configuration. Absent for an account that is not yet configurable. */
+    current: Config | undefined
+    /** The kind of the account's key, which an upgrade keeps as an owner. */
+    type: string
+  }
+}
+
+/** Returns the configuration of the account that `owner` owns, or `undefined` when it is not configurable. */
+export function of(owner: Owner.Owner): Config | undefined {
+  const { configurable } = owner
+  if (!configurable) return undefined
+  const { config } = configurable.owner.account
+  return from({
+    address: configurable.owner.account.address,
+    chainId: configurable.chainId,
+    key: Owner.key(owner),
+    owners: configurable.owners,
+    salt: config.salt,
+    threshold: Number(config.threshold),
+    version: BigInt(config.version),
+  })
+}
+
+/**
+ * Prepares the transaction that installs `target`, for a passkey to sign in the browser. Returns the
+ * digest that the passkey signs as its challenge, and the unsigned transaction that {@link sendSigned}
+ * signs with the assertion. Without `current`, the passkey is the account's key, which signs the
+ * upgrade. With it, the passkey is one of `current`'s owners.
+ *
+ * @throws {ConflictError} When the chain's configuration differs from `current`.
+ */
+export async function request(
+  options: request.Options,
+): Promise<request.ReturnType> {
+  const { client, current, publicKey, target } = options
+  await check({ client, current, target })
+
+  const captured: { digest?: Hex.Hex | undefined } = {}
+  const passkey = Account.from({
+    keyType: 'webAuthn',
+    publicKey: PublicKey.fromHex(publicKey),
+    sign(parameters) {
+      captured.digest = parameters.hash
+      return Promise.reject(new Error('The digest is captured.'))
+    },
+  })
+  const account = current ? toAccount(current, { signers: [passkey] }) : passkey
+  const prepared = await prepare({ account, client, current, target })
+  const transaction = await Transaction.serialize(prepared as never)
+  // The passkey signs nothing here: its `sign` records the digest of the transaction, then refuses.
+  await signTransaction(client, { ...prepared, account } as never).catch(
+    () => undefined,
+  )
+  if (!captured.digest)
+    throw new Error('The transaction asked the passkey to sign no digest.')
+  return { digest: captured.digest, transaction }
+}
+
+export declare namespace request {
+  type Options = {
+    /** The client, from {@link client}. */
+    client: Client
+    /** The account's stored configuration. Absent for an account that is not yet configurable. */
+    current: Config | undefined
+    /** The passkey's uncompressed P256 public key, hex. */
+    publicKey: Hex.Hex
+    /** The configuration to install, from {@link next}. */
+    target: Config
+  }
+
+  type ReturnType = {
+    /** The digest that the passkey signs, as hex. */
+    digest: Hex.Hex
+    /** The unsigned transaction, serialized. */
+    transaction: Hex.Hex
+  }
+
+  type ErrorType = ConflictError
+}
+
+/**
+ * Stores `config` for the user with `userId`. A stored configuration of a later version stays, so
+ * two concurrent changes keep the newer one.
+ */
+export async function save(db: Realm.Database, options: save.Options) {
+  const { config, userId } = options
+  const values = {
+    address: config.address.toLowerCase(),
+    chainId: config.chainId,
+    key: config.key.toLowerCase(),
+    owners: config.owners.map((owner) => ({
+      address: owner.address.toLowerCase(),
+      type: owner.type,
+      weight: owner.weight,
+    })),
+    salt: config.salt,
+    threshold: config.threshold,
+    userId,
+    version: config.version.toString(),
+  }
+  await db
+    .insert(Schema.accountConfigs)
+    .values(values)
+    .onConflictDoUpdate({
+      set: {
+        owners: values.owners,
+        salt: values.salt,
+        threshold: values.threshold,
+        updatedAt: sql`now()`,
+        version: values.version,
+      },
+      // A row of a later version, or of another user, stays as it is.
+      setWhere: sql`${Schema.accountConfigs.version}::numeric < excluded.version::numeric and ${Schema.accountConfigs.userId} = excluded.user_id`,
+      target: [Schema.accountConfigs.chainId, Schema.accountConfigs.address],
+    })
+}
+
+export declare namespace save {
+  type Options = {
+    /** The configuration that the chain installed. */
+    config: Config
+    /** The user who holds the account. */
+    userId: string
+  }
+}
+
+/**
+ * Sends the transaction that installs `target` from `account`, and returns the installed
+ * configuration. Without `current`, `account` is the account's key, which signs the upgrade. With
+ * it, `account` is the configurable account with an owner that signs, from {@link toAccount}. The
+ * chain's configuration must match `current`.
+ *
+ * @throws {ConflictError} When the chain's configuration differs from `current`.
+ */
+export async function send(options: send.Options): Promise<Config> {
+  const { account, client, current, target } = options
+  await check({ client, current, target })
+
+  const request = await prepare({ account, client, current, target })
+  const signed = await signTransaction(client, { ...request, account } as never)
+  await submit({ client, serialized: signed })
+  return target
+}
+
+export declare namespace send {
+  type Options = {
+    /** The account that sends: its key for an upgrade, or the configurable account of `current`. */
+    account: LocalAccount
+    /** The client, from {@link client}. */
+    client: Client
+    /** The account's stored configuration. Absent for an account that is not yet configurable. */
+    current: Config | undefined
+    /** The configuration to install, from {@link next}. */
+    target: Config
+  }
+
+  type ErrorType = ConflictError
+}
+
+/**
+ * Signs the transaction that {@link request} prepared with `assertion`, the passkey's signature over
+ * its digest, sends it, and returns the installed configuration. The chain must still hold `current`.
+ *
+ * @throws {ConflictError} When the chain's configuration differs from `current`.
+ */
+export async function sendSigned(options: sendSigned.Options): Promise<Config> {
+  const { assertion, client, current, digest, publicKey, target } = options
+  await check({ client, current, target })
+
+  const { metadata, signature } = Authentication.deserializeResponse(assertion)
+  const envelope = SignatureEnvelope.serialize({
+    metadata: {
+      authenticatorData: metadata.authenticatorData,
+      clientDataJSON: metadata.clientDataJSON,
+    },
+    publicKey: PublicKey.fromHex(publicKey),
+    signature,
+    type: 'webAuthn',
+  })
+
+  // The passkey already signed the digest, so this owner returns its envelope, and nothing else.
+  const passkey = Account.from({
+    keyType: 'webAuthn',
+    publicKey: PublicKey.fromHex(publicKey),
+    sign(parameters) {
+      if (parameters.hash !== digest)
+        return Promise.reject(
+          new Error('The assertion signs another transaction.'),
+        )
+      return Promise.resolve(envelope)
+    },
+  })
+  const account = current ? toAccount(current, { signers: [passkey] }) : passkey
+  const fields: object = Transaction.deserialize(options.transaction as never)
+  const signed = await signTransaction(client, { ...fields, account } as never)
+  await submit({ client, serialized: signed })
+  return target
+}
+
+export declare namespace sendSigned {
+  type Options = request.Options & {
+    /** The passkey's assertion over `digest`, which `Passkey.verify` accepted. */
+    assertion: Passkey.Assertion
+    /** The digest that {@link request} returned, which the passkey signed. */
+    digest: Hex.Hex
+    /** The unsigned transaction that {@link request} returned. */
+    transaction: Hex.Hex
+  }
+
+  type ErrorType = ConflictError
+}
+
+/**
+ * Prepares the transaction that registers `key`, an access key that the account's own key signed,
+ * so the key keeps working after the upgrade retires that signature (TIP-1112). The access key signs
+ * the transaction in the app, so its one call is a TIP-20 transfer of 0 that the key's scopes allow.
+ * Returns the digest that the access key signs raw, and the unsigned transaction, or `undefined` when
+ * no scope allows such a call.
+ */
+export async function requestRegistration(
+  options: requestRegistration.Options,
+): Promise<requestRegistration.ReturnType | undefined> {
+  const { account, client, key } = options
+  const call = registration(key, { account })
+  if (!call) return undefined
+
+  const captured: { digest?: Hex.Hex | undefined } = {}
+  const signer = accessKey({
+    account,
+    key,
+    sign(hash) {
+      captured.digest = hash
+      return Promise.reject(new Error('The digest is captured.'))
+    },
+  })
+  const prepared = await prepareTransactionRequest(client, {
+    account: signer,
+    calls: [call],
+    feePayer: client.transport.key === 'relay' ? true : undefined,
+    keyAuthorization: key,
+    nonceKey: Hex.toBigInt(Hex.random(24)),
+    type: 'tempo',
+    validBefore: Math.floor(Date.now() / 1000) + lifetime,
+  } as never)
+  const transaction = await Transaction.serialize(prepared as never)
+  await signTransaction(client, {
+    ...prepared,
+    account: signer,
+  } as never).catch(() => undefined)
+  if (!captured.digest)
+    throw new Error('The transaction asked the access key to sign no digest.')
+  return { digest: captured.digest, transaction }
+}
+
+export declare namespace requestRegistration {
+  type Options = {
+    /** The account that the key acts for. */
+    account: Address.Address
+    /** The client, from {@link client}. */
+    client: Client
+    /** The signed key authorization, whose access key signs the registration. */
+    key: KeyAuthorization.Signed
+  }
+
+  type ReturnType = {
+    /** The digest that the access key signs raw, as hex. */
+    digest: Hex.Hex
+    /** The unsigned transaction, serialized. */
+    transaction: Hex.Hex
+  }
+}
+
+/**
+ * Returns whether the chain holds `key`, an access key, for `account`: `active`, `revoked`, or
+ * `missing`. A revoked key stays on the chain, so no registration replaces it.
+ */
+export async function keyStatus(
+  options: keyStatus.Options,
+): Promise<'active' | 'missing' | 'revoked'> {
+  const { account, client, key } = options
+  const metadata = await Actions.accessKey.getMetadata(client, {
+    account,
+    accessKey: key,
+  })
+  // The chain reads a revoked key with the zero address, so the flag decides first.
+  if (metadata.isRevoked) return 'revoked'
+  return Address.isEqual(metadata.address, key) ? 'active' : 'missing'
+}
+
+export declare namespace keyStatus {
+  type Options = {
+    /** The account that the key acts for. */
+    account: Address.Address
+    /** The client, from {@link client}. */
+    client: Client
+    /** The access key's address. */
+    key: Address.Address
+  }
+}
+
+/**
+ * Signs the transaction that {@link requestRegistration} prepared with `signature`, the access key's
+ * raw signature over `digest`, and sends it. Resolves once the chain registered the key.
+ */
+export async function sendRegistration(options: sendRegistration.Options) {
+  const { account, client, digest, signature } = options
+  const fields = Transaction.deserialize(options.transaction as never) as {
+    keyAuthorization: KeyAuthorization.Signed
+  }
+  const signer = accessKey({
+    account,
+    key: fields.keyAuthorization,
+    sign(hash) {
+      if (hash !== digest)
+        return Promise.reject(
+          new Error('The signature signs another transaction.'),
+        )
+      return Promise.resolve(signature)
+    },
+  })
+  const signed = await signTransaction(client, {
+    ...fields,
+    account: signer,
+  } as never)
+  await submit({ client, serialized: signed })
+}
+
+export declare namespace sendRegistration {
+  type Options = {
+    /** The account that the key acts for. */
+    account: Address.Address
+    /** The client, from {@link client}. */
+    client: Client
+    /** The digest that {@link requestRegistration} returned. */
+    digest: Hex.Hex
+    /** The access key's raw signature over `digest`, as a serialized signature envelope. */
+    signature: Hex.Hex
+    /** The unsigned transaction that {@link requestRegistration} returned. */
+    transaction: Hex.Hex
+  }
+}
+
+/**
+ * Stores a change that waits for the passkey's signature over `digest`, for the user with `userId`,
+ * for {@link lifetime}. {@link takePending} reads it once.
+ */
+export async function storePending(
+  db: Realm.Database,
+  options: storePending.Options,
+) {
+  const { current, digest, registration, target, transaction, userId } = options
+  const encode = (config: Config) => ({
+    ...config,
+    version: config.version.toString(),
+  })
+  await db.insert(Schema.verification).values({
+    expiresAt: new Date(Date.now() + lifetime * 1000),
+    id: crypto.randomUUID(),
+    identifier: pendingIdentifier({ digest, userId }),
+    value: JSON.stringify(
+      schema.pending.parse({
+        ...(current ? { current: encode(current) } : {}),
+        ...(registration ? { registration } : {}),
+        target: encode(target),
+        transaction,
+      }),
+    ),
+  })
+}
+
+export declare namespace storePending {
+  type Options = {
+    /** The account's stored configuration. Absent for an account that is not yet configurable. */
+    current: Config | undefined
+    /** The digest that the passkey signs. */
+    digest: Hex.Hex
+    /** The key's registration, which the chain receives before the change. Absent without one. */
+    registration?: requestRegistration.ReturnType | undefined
+    /** The configuration to install. */
+    target: Config
+    /** The unsigned transaction. */
+    transaction: Hex.Hex
+    /** The signed-in user's ID. */
+    userId: string
+  }
+}
+
+/**
+ * Deletes and returns the change that waits for the passkey's signature over `digest`, for the user
+ * with `userId`, or `undefined` when none is stored or it expired.
+ */
+export async function takePending(
+  db: Realm.Database,
+  options: takePending.Options,
+): Promise<takePending.ReturnType> {
+  const [row] = await db
+    .delete(Schema.verification)
+    .where(
+      and(
+        eq(Schema.verification.identifier, pendingIdentifier(options)),
+        gt(Schema.verification.expiresAt, new Date()),
+      ),
+    )
+    .returning({ value: Schema.verification.value })
+  if (!row) return undefined
+
+  const value = schema.pending.parse(JSON.parse(row.value))
+  const decode = (config: z.output<typeof schema.pending>['target']) =>
+    from({
+      ...config,
+      address: Address.checksum(config.address),
+      key: Address.checksum(config.key),
+      owners: config.owners.map((owner) => ({
+        ...owner,
+        address: Address.checksum(owner.address),
+      })),
+      version: BigInt(config.version),
+    })
+  return {
+    current: value.current ? decode(value.current) : undefined,
+    registration: value.registration,
+    target: decode(value.target),
+    transaction: value.transaction,
+  }
+}
+
+export declare namespace takePending {
+  type Options = {
+    /** The digest that the passkey signed. */
+    digest: Hex.Hex
+    /** The signed-in user's ID. */
+    userId: string
+  }
+
+  type ReturnType =
+    | {
+        /** The account's configuration when the change was prepared, if any. */
+        current: Config | undefined
+        /** The key's registration, which the chain receives before the change, if any. */
+        registration: requestRegistration.ReturnType | undefined
+        /** The configuration to install. */
+        target: Config
+        /** The unsigned transaction. */
+        transaction: Hex.Hex
+      }
+    | undefined
+}
+
+/**
+ * Returns the configurable account of `config` as Viem signs for it. Each of `signers` signs as the
+ * owner at its address, and every other owner is an address alone.
+ */
+export function toAccount(config: Config, options: toAccount.Options = {}) {
+  const { signers = [] } = options
+  const owners = config.owners.map((entry) => ({
+    owner:
+      signers.find((signer) =>
+        Address.isEqual(signer.address, entry.address),
+      ) ?? entry.address,
+    weight: entry.weight,
+  }))
+  // Viem derives the address of an initial configuration, and takes it for any later version.
+  if (config.version === 0n)
+    return Account.fromConfig({
+      owners,
+      salt: config.salt,
+      threshold: config.threshold,
+    })
+  return Account.fromConfig({
+    address: config.address,
+    owners,
+    salt: config.salt,
+    threshold: config.threshold,
+    version: config.version,
+  })
+}
+
+export declare namespace toAccount {
+  type Options = {
+    /** The owners that sign on the server, as Viem accounts. */
+    signers?: readonly LocalAccount[] | undefined
+  }
+}
+
+/**
+ * Returns `key`'s access key as the signer of `account`, which Viem signs for through a keychain
+ * envelope. `sign` receives the digest that the access key signs raw. Tempo ID holds no public key
+ * of the access key, so the address comes from the key authorization.
+ */
+function accessKey(options: accessKey.Options) {
+  const { account, key } = options
+  const signer = Account.from({
+    access: account,
+    keyType: key.type as 'secp256k1',
+    // The keychain envelope names the parent account, and the key authorization names the access
+    // key, so the public key signs nothing. Any valid point fills it.
+    publicKey: Secp256k1.getPublicKey({ privateKey: placeholder }),
+    sign: (parameters) => options.sign(parameters.hash),
+  })
+  return { ...signer, accessKeyAddress: Address.checksum(key.address) }
+}
+
+declare namespace accessKey {
+  type Options = {
+    /** The account that the key acts for. */
+    account: Address.Address
+    /** The signed key authorization. */
+    key: KeyAuthorization.Signed
+    /** Returns the access key's raw signature over `hash`. */
+    sign: (hash: Hex.Hex) => Promise<Hex.Hex>
+  }
+}
+
+/**
+ * Checks that the chain still holds `current`, or no configuration for an account that is not yet
+ * configurable.
+ *
+ * @throws {ConflictError} When it does not.
+ */
+async function check(options: check.Options) {
+  const { client, current, target } = options
+  const commitment = await Actions.accounts.getConfigCommitment(client, {
+    account: target.address,
+  })
+  const expected = current
+    ? AccountConfig.getCommitment(toOx(current))
+    : undefined
+  const empty = /^0x0*$/.test(commitment)
+  // An account that is configurable from its creation holds no commitment until it first sends.
+  const matches = expected
+    ? Hex.isEqual(commitment, expected) || (current!.version === 0n && empty)
+    : empty
+  if (!matches) throw new ConflictError({ account: target.address })
+}
+
+declare namespace check {
+  type Options = {
+    /** The client, from {@link client}. */
+    client: Client
+    /** The account's stored configuration, if any. */
+    current: Config | undefined
+    /** The configuration to install. */
+    target: Config
+  }
+}
+
+/**
+ * Returns whether the chain already holds `target`'s commitment for its account, such as after an
+ * upgrade that the chain accepted and whose save failed.
+ */
+export async function installed(options: installed.Options) {
+  const { client, target } = options
+  const commitment = await Actions.accounts.getConfigCommitment(client, {
+    account: target.address,
+  })
+  return Hex.isEqual(commitment, AccountConfig.getCommitment(toOx(target)))
+}
+
+export declare namespace installed {
+  type Options = {
+    /** The client, from {@link client}. */
+    client: Client
+    /** The configuration that a change installs. */
+    target: Config
+  }
+}
+
+/** Returns the `verification` identifier of a pending change. JSON keeps each value apart. */
+function pendingIdentifier(options: takePending.Options) {
+  return (
+    pendingPrefix +
+    JSON.stringify([options.userId, options.digest.toLowerCase()])
+  )
+}
+
+/**
+ * Prepares the transaction that installs `target` for `account`: the upgrade's only call, or the
+ * configuration update. A random nonce key gives the transaction a nonce lane of its own, which no
+ * other transaction of the account spends while the passkey signs. It is valid for {@link lifetime}.
+ */
+async function prepare(options: prepare.Options) {
+  const { account, client, current, target } = options
+  const owners = target.owners.map((entry) => ({
+    owner: entry.address,
+    weight: entry.weight,
+  }))
+  const calls = current
+    ? [
+        Actions.accounts.updateConfig.call({
+          currentConfig: toOx(current),
+          nextConfig: { owners, threshold: target.threshold },
+        }),
+      ]
+    : [
+        Actions.accounts.upgrade.call({
+          owners,
+          threshold: target.threshold,
+        }),
+      ]
+  return await prepareTransactionRequest(client, {
+    account,
+    calls,
+    // Only the Tempo API's sponsor relay fills and co-signs a sponsored transaction.
+    feePayer: client.transport.key === 'relay' ? true : undefined,
+    nonceKey: Hex.toBigInt(Hex.random(24)),
+    type: 'tempo',
+    validBefore: Math.floor(Date.now() / 1000) + lifetime,
+  } as never)
+}
+
+declare namespace prepare {
+  type Options = {
+    /** The account that sends: the key itself for an upgrade, or the configurable account. */
+    account: LocalAccount
+    /** The client, from {@link client}. */
+    client: Client
+    /** The account's stored configuration, if any. */
+    current: Config | undefined
+    /** The configuration to install. */
+    target: Config
+  }
+}
+
+/**
+ * Returns the call that registers `key` for `account`: a TIP-20 `transfer` or `transferWithMemo` of 0
+ * that a scope allows, to the account or the first recipient that the scope names. A key without
+ * scopes transfers 0 pathUSD. Returns `undefined` when no scope allows such a call.
+ */
+function registration(
+  key: KeyAuthorization.Signed,
+  options: registration.Options,
+) {
+  const { account } = options
+  if (!key.scopes) return transfer({ to: account, token: pathUsd })
+
+  for (const scope of key.scopes) {
+    if (!tip20(scope.address)) continue
+    const to = scope.recipients?.[0] ?? account
+    const selector = scope.selector?.toLowerCase()
+    if (selector === selectors.transfer)
+      return transfer({ to, token: scope.address })
+    if (selector === selectors.transferWithMemo)
+      return Actions.token.transfer.call({
+        amount: 0n,
+        memo: Hex.padLeft('0x', 32),
+        to,
+        token: scope.address,
+      })
+  }
+  return undefined
+}
+
+declare namespace registration {
+  type Options = {
+    /** The account that the key acts for, which receives a transfer of 0 without a named recipient. */
+    account: Address.Address
+  }
+}
+
+/**
+ * Sends a signed transaction and waits for its receipt.
+ *
+ * @throws When the node refuses it or the transaction reverts.
+ */
+async function submit(options: submit.Options) {
+  const receipt = await sendRawTransactionSync(options.client, {
+    serializedTransaction: options.serialized as never,
+  })
+  if (receipt.status !== 'success')
+    throw new Error(`The transaction ${receipt.transactionHash} reverted.`)
+}
+
+declare namespace submit {
+  type Options = {
+    /** The client, from {@link client}. */
+    client: Client
+    /** The signed transaction, serialized. */
+    serialized: Hex.Hex
+  }
+}
+
+/** Returns `config` as ox reads a configuration. */
+function toOx(config: Config) {
+  return AccountConfig.from({
+    owners: config.owners.map((entry) => ({
+      owner: entry.address,
+      weight: entry.weight,
+    })),
+    salt: config.salt,
+    threshold: config.threshold,
+    version: config.version,
+  })
+}
+
+/** Returns a TIP-20 transfer of 0 of `token` to `to`. */
+function transfer(options: transfer.Options) {
+  return Actions.token.transfer.call({ amount: 0n, ...options })
+}
+
+declare namespace transfer {
+  type Options = {
+    /** The recipient of the transfer of 0. */
+    to: Address.Address
+    /** The TIP-20 token that transfers. */
+    token: Address.Address
+  }
+}