@geeqdev/geeq-sdk 0.1.0 → 0.2.0

package/src/chain/geeq-chain.ts

@@ -0,0 +1,1094 @@
+import { assertDuration, assertUint32 } from '../assert'
+import { resolveAccountId } from '../crypto/account-id'
+import type { AccountRef } from '../crypto/account-id'
+import { toBase64 } from '../encoding/base64'
+import {
+  accountNotAttestable,
+  accountNotFound,
+  amountBelowMinimum,
+  chainMismatch,
+  insufficientFunds,
+  invalidArgument,
+  nftNotOwned,
+  noChain,
+} from '../errors'
+import { decimalsOf, formatGeeq, toPennies } from '../amount'
+import type { GeeqAmount } from '../amount'
+import { decodeWalletAddressSync } from '../address/wallet-address'
+import { createCoinTransferTxSync } from '../tx/transfer'
+import { createNftMintProxyTxSync, nftMintProxiesIn, nftMintProxyId } from '../tx/proxy'
+import { createNftMintTxSync } from '../tx/nft'
+import type {
+  AttestationTx,
+  CoinTransferTx,
+  GeeqChainState,
+  GeeqFee,
+  GeeqKeypair,
+  GeeqNft,
+  GeeqNftMintProxies,
+  NftMintProxyTx,
+  NftMintTx,
+} from '../types'
+import { discover } from '../net/discovery'
+import type { Discovery, GeeqDiscoveredNode } from '../net/discovery'
+import type { GeeqLedger } from '../ledger/geeq-ledger'
+import type { GeeqLedgerNode } from '../ledger/net-actors'
+import { readLedger, readNftRecords } from '../net/read-ledger'
+import { defaultTransport, raceAbort } from '../net/transport'
+import type { GeeqTransport } from '../net/transport'
+import { initGeeq } from '../runtime/init'
+import { createAttestationTxSync } from '../tx/attestation'
+import { ATTEST_HASH_BYTES, attestHashOf } from '../tx/content'
+import type { GeeqContent } from '../tx/content'
+import { GeeqNode } from './geeq-node'
+import type { NodeRequestConfig } from './geeq-node'
+import { NonceGuard } from './nonce-guard'
+import { GEEQ_NODE_PORT, originOf, selectNode, serviceOriginOf } from './select'
+
+const DEFAULT_TIMEOUT_MS = 10_000
+const DEFAULT_LEDGER_MAX_AGE_MS = 5_000
+const DEFAULT_RETRIES = 1
+
+export interface GeeqChainOptions {
+  /**
+   * How many pennies make one Geeq: a power of ten, as a bigint.
+   *
+   * The chain counts only pennies and does not publish this, so the app says — use the
+   * divisor its wallet and explorer show amounts with. {@link GeeqChain.toPennies} reads
+   * `{ geeq }` figures with it, and {@link GeeqChain.formatGeeq} and the chain's own
+   * messages show amounts with it.
+   */
+  readonly penniesPerGeeq: bigint
+  /**
+   * The chain's node directory — the simulator URL for your environment — which the SDK
+   * asks for an active node. Works for every chain and environment.
+   *
+   * Supply this or {@link endpoint}, not both. The directory is the only thing that
+   * knows which nodes exist and which are running; the ledger then says which actor the
+   * chosen one is. Note the directory is a deployment control plane with no
+   * authentication — the SDK reads two of its routes and never touches the rest.
+   */
+  readonly discovery?: string | URL
+  /**
+   * A specific node, when you already know one.
+   *
+   * Supply this or {@link discovery}, not both.
+   */
+  readonly endpoint?: string | URL
+  /**
+   * Which chain to use, by the name its directory gives it.
+   *
+   * Only meaningful with {@link discovery} — a name exists nowhere but the directory.
+   * Matched case-insensitively.
+   */
+  readonly chainName?: string
+  /**
+   * Which chain to use, by protocol number.
+   *
+   * With {@link discovery} this selects the chain when no {@link chainName} is given,
+   * and asserts it when one is. With {@link endpoint} it asserts the node serves the
+   * chain you expect, and a mismatch throws `chain-mismatch` on the first ledger read.
+   */
+  readonly chainNumber?: number
+  /** Defaults to a call through `globalThis.fetch`. */
+  readonly transport?: GeeqTransport
+  /** Per request. Defaults to 10000. */
+  readonly timeoutMs?: number
+  /** Extra headers on every request — a proxy token, a trace id. */
+  readonly headers?: Readonly<Record<string, string>>
+  /** How long a read ledger may be reused. Defaults to 5000. 0 disables the cache. */
+  readonly ledgerMaxAgeMs?: number
+  /** Skip host matching. Required behind a gateway or when using a DNS name. */
+  readonly nodeNumber?: number
+  /**
+   * The port discovered nodes are reached on. Defaults to 2082.
+   *
+   * Deployment configuration, not node selection — override it only when running
+   * against nodes that are not behind the standard TLS front door, such as a local
+   * test harness.
+   */
+  readonly nodePort?: number
+  /** Retries on transport failure only, never on a response. Defaults to 1. */
+  readonly retries?: number
+  readonly signal?: AbortSignal
+}
+
+export interface AttestationRequest {
+  /** The account that signs. Must be a coin-asset account on this chain. */
+  readonly keypair: GeeqKeypair
+  /**
+   * What to attest. Hashed here with BLAKE3-32; the content never leaves the device.
+   *
+   * A `File` straight from a file input works, as does a string or raw bytes.
+   */
+  readonly content?: GeeqContent
+  /** Or supply the digest yourself. Exactly one of `content` and `attestHash`. */
+  readonly attestHash?: Uint8Array
+  /** Public labels, checked against this chain's limits before anything is signed. */
+  readonly metadata?: readonly (string | Uint8Array)[]
+  /** Override the derived nonce. See {@link NonceGuard} for when that is needed. */
+  readonly nonce?: number
+  readonly signal?: AbortSignal
+}
+
+export interface CoinTransferRequest {
+  /** The account paying. Must be a coin-asset account on this chain. */
+  readonly from: GeeqKeypair
+  /**
+   * Who receives it.
+   *
+   * A base58 wallet address is the usual thing — it is what a person pastes — and the
+   * chain it encodes is checked against this one. A raw account id or public key works
+   * too, but carries no chain to check.
+   */
+  readonly to: string | AccountRef
+  /**
+   * How much. State the unit: `{ geeq: "1.5" }`, read at {@link GeeqChainOptions.penniesPerGeeq},
+   * or `{ pennies }` as the chain counts them. May be left out
+   * when sending NFTs, which then go with the chain's minimum transfer.
+   */
+  readonly amount?: GeeqAmount
+  /** NFTs to send, by id — see {@link GeeqChain.findNfts}. The sender must hold each one. */
+  readonly nfts?: readonly Uint8Array[]
+  /** Override the derived nonce. See {@link NonceGuard}. */
+  readonly nonce?: number
+  readonly signal?: AbortSignal
+}
+
+export interface ChainStateRequest {
+  readonly account: AccountRef
+  readonly maxAgeMs?: number
+  readonly signal?: AbortSignal
+}
+
+export interface NftMintProxyRequest {
+  /**
+   * The account paying for the proxy, which also becomes its admin: the only key that
+   * can later mint NFTs through it. Must be a coin-asset account on this chain.
+   */
+  readonly admin: GeeqKeypair
+  /**
+   * Coin moved onto the proxy, `{ geeq }` or `{ pennies }` like any amount. It pays for the
+   * mints made through it, so fund it for more than one.
+   */
+  readonly amount: GeeqAmount
+  /**
+   * Which of the admin's proxies this is, from 1. Leave it out to take the next one —
+   * one past the highest the ledger holds for this admin, see
+   * {@link GeeqChain.findNftMintProxies}. An index already in use is refused.
+   */
+  readonly index?: number
+  /** Override the derived nonce. See {@link NonceGuard}. */
+  readonly nonce?: number
+  readonly signal?: AbortSignal
+}
+
+export interface NftMintProxiesRequest {
+  /**
+   * The admin whose proxies to find. A keypair will do; so will a bare public key, since
+   * listing needs no signature. Not an account id: an index is derived from the key.
+   */
+  readonly admin: { readonly publicKey: Uint8Array }
+  /** How old a cached ledger may be. 0 reads afresh — a new proxy shows only once confirmed. */
+  readonly maxAgeMs?: number
+  readonly signal?: AbortSignal
+}
+
+export interface NftsRequest {
+  /** Whose NFTs. A keypair will do, as will an account id or a public key. */
+  readonly owner: AccountRef
+  /** How old a cached ledger may be. 0 reads afresh — a new NFT shows only once confirmed. */
+  readonly maxAgeMs?: number
+  readonly signal?: AbortSignal
+}
+
+export interface NftMintRequest {
+  /** The proxy's admin: the only key that can mint through it. It signs the mint. */
+  readonly admin: GeeqKeypair
+  /**
+   * Which of the admin's proxies mints it, by index — see
+   * {@link GeeqChain.findNftMintProxies}. The proxy pays the fee and {@link amount}, and
+   * spends its own nonce, not the admin's.
+   */
+  readonly index: number
+  /**
+   * What the NFT stands for. Hashed here with BLAKE3-32; the content never leaves the
+   * device. A `File` straight from a file input works, as does a string or raw bytes.
+   */
+  readonly content?: GeeqContent
+  /** Or supply the digest yourself. Exactly one of `content` and `attestHash`. */
+  readonly attestHash?: Uint8Array
+  /** Public labels stored with the NFT, checked against this chain's limits before signing. */
+  readonly metadata?: readonly (string | Uint8Array)[]
+  /** Who receives the NFT. Defaults to the admin. An address is checked against this chain. */
+  readonly to?: string | AccountRef
+  /** Coin the proxy sends to the receiver with it. Defaults to the chain's minimum transfer. */
+  readonly amount?: GeeqAmount
+  /** Override the proxy's derived nonce. See {@link NonceGuard}. */
+  readonly nonce?: number
+  readonly signal?: AbortSignal
+}
+
+/** The process-wide default, installed by {@link GeeqChain.init}. */
+let defaultChain: GeeqChain | null = null
+
+/**
+ * Refuse a nonsense option before anything is read. Left to the network layer, a negative
+ * `retries` sends no request at all and a zero `timeoutMs` times every request out — both
+ * reported as an unreachable node, which is the one thing they are not.
+ */
+function assertChainOptions(options: GeeqChainOptions): void {
+  assertDuration(options.timeoutMs, 'timeoutMs')
+  if (options.timeoutMs === 0) {
+    throw invalidArgument('timeoutMs must be more than 0, or every request times out at once.')
+  }
+  assertDuration(options.ledgerMaxAgeMs, 'ledgerMaxAgeMs')
+  const { retries, nodePort } = options
+  if (retries !== undefined && (!Number.isInteger(retries) || retries < 0)) {
+    throw invalidArgument(`retries must be a whole number, 0 or more, received ${String(retries)}.`)
+  }
+  if (nodePort !== undefined && (!Number.isInteger(nodePort) || nodePort < 1 || nodePort > 65_535)) {
+    throw invalidArgument(`nodePort must be a port from 1 to 65535, received ${JSON.stringify(nodePort)}.`)
+  }
+  if (options.chainNumber !== undefined) assertUint32(options.chainNumber, 'chainNumber')
+  if (options.nodeNumber !== undefined) assertUint32(options.nodeNumber, 'nodeNumber')
+}
+
+/**
+ * Refuse a transaction its payer cannot cover. The node checks the balance against the
+ * amount plus the fee, so this does too — after building, because the fee is charged on
+ * the signed bytes.
+ */
+function assertAffordable(
+  penniesPerGeeq: bigint,
+  payer: string,
+  balance: bigint,
+  amount: bigint,
+  fee: GeeqFee | undefined,
+  block: number,
+): void {
+  const cost = amount + (fee?.total ?? 0n)
+  if (balance >= cost) return
+
+  const geeq = (pennies: bigint) => formatGeeq(pennies, penniesPerGeeq)
+  const needed =
+    fee === undefined
+      ? geeq(amount)
+      : amount === 0n
+        ? `a fee of ${geeq(fee.total)}`
+        : `${geeq(amount)} plus a fee of ${geeq(fee.total)}`
+  throw insufficientFunds(
+    `${payer} holds ${geeq(balance)} geeq at block ${block}, and this needs ${needed} geeq.`,
+  )
+}
+
+/**
+ * A chain, reached through one node.
+ *
+ * Holds the node directory, the metadata limits and a short-lived ledger cache, so an
+ * attestation needs only a keypair and something to attest. Everything a transaction is
+ * pinned to — chain number, target block, node number, nonce — is read from the ledger
+ * rather than asked of the caller, because none of it can be known offline and a wrong
+ * value is rejected by the chain.
+ *
+ * A chain is bound to the endpoint it was connected to. To use a different node, connect
+ * another one: a different node means a different address, certificate and CORS origin,
+ * which is not something to switch silently.
+ *
+ * In a reactive framework, mark an instance raw (Vue's `markRaw`) rather than letting it
+ * be proxied.
+ */
+export class GeeqChain {
+  /** The node this chain reads from and builds transactions for. */
+  readonly endpoint: string
+  /** What the directory said about the nodes on this chain, when one was used. */
+  readonly candidates: readonly GeeqDiscoveredNode[]
+  /** The chain's name, when a directory supplied one. Display only — chains are numbered. */
+  readonly chainName: string | undefined
+  /** How many pennies make one Geeq, as given to {@link GeeqChain.connect}. */
+  readonly penniesPerGeeq: bigint
+
+  private readonly request!: NodeRequestConfig
+  private readonly ledgerMaxAgeMs!: number
+  private readonly nonces!: NonceGuard
+  private readonly declaredChainNumber!: number | undefined
+  private readonly nodeNumberOverride!: number | undefined
+  private cached!: GeeqLedger | null
+  private resolved!: GeeqNode | null
+  private inflight!: Promise<GeeqLedger> | null
+
+  /** @internal */
+  constructor(init: {
+    endpoint: string
+    candidates: readonly GeeqDiscoveredNode[]
+    chainName: string | undefined
+    chainNumber: number | undefined
+    nodeNumber: number | undefined
+    penniesPerGeeq: bigint
+    request: NodeRequestConfig
+    ledgerMaxAgeMs: number
+  }) {
+    this.endpoint = init.endpoint
+    this.candidates = Object.freeze([...init.candidates])
+    this.chainName = init.chainName
+    this.penniesPerGeeq = init.penniesPerGeeq
+
+    // Non-enumerable and TS-private, never `#private` — see GeeqNode for why.
+    const hidden = (key: string, value: unknown, writable = false): void => {
+      Object.defineProperty(this, key, { value, enumerable: false, writable })
+    }
+    hidden('request', init.request)
+    hidden('ledgerMaxAgeMs', init.ledgerMaxAgeMs)
+    hidden('declaredChainNumber', init.chainNumber)
+    hidden('nodeNumberOverride', init.nodeNumber)
+    hidden('nonces', new NonceGuard())
+    hidden('cached', null, true)
+    hidden('resolved', null, true)
+    hidden('inflight', null, true)
+  }
+
+  /**
+   * Choose a chain and a node, without reading anything from the chain itself.
+   *
+   * With `discovery`, the directory is asked which nodes exist and one of the active
+   * ones is taken. With `endpoint`, that node is used as given. Either way **no ledger
+   * is fetched here** — a ledger read is only valid for a few blocks, so it happens when
+   * a transaction is actually being built rather than when the app starts.
+   */
+  static async connect(options: GeeqChainOptions): Promise<GeeqChain> {
+    const hasDiscovery = options.discovery !== undefined
+    const hasEndpoint = options.endpoint !== undefined
+    if (hasDiscovery === hasEndpoint) {
+      throw invalidArgument(
+        'Provide exactly one of discovery (a node directory to pick an active node ' +
+          'from) or endpoint (a node you already know).',
+      )
+    }
+    decimalsOf(options.penniesPerGeeq)
+    assertChainOptions(options)
+
+    const request: NodeRequestConfig = Object.freeze({
+      transport: options.transport ?? defaultTransport,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      retries: options.retries ?? DEFAULT_RETRIES,
+      headers: options.headers,
+    })
+
+    let endpoint: string
+    let candidates: readonly GeeqDiscoveredNode[] = []
+    let chainName: string | undefined = options.chainName
+    let chainNumber = options.chainNumber
+
+    if (hasDiscovery) {
+      const found: Discovery = await discover({
+        origin: serviceOriginOf(options.discovery as string | URL),
+        ...(options.chainName === undefined ? {} : { chainName: options.chainName }),
+        chainNumber: options.chainNumber,
+        ...(options.nodePort === undefined ? {} : { port: options.nodePort }),
+        request: {
+          ...request,
+          ...(options.signal === undefined ? {} : { signal: options.signal }),
+        },
+      })
+      candidates = found.nodes
+      chainName = found.chain.name
+      chainNumber = found.chain.chainNumber
+      // Spread across the usable nodes rather than everyone hammering the first one.
+      // The directory's order is stable, so picking [0] would concentrate every client
+      // of every app on one machine.
+      endpoint = (found.usable[Math.floor(Math.random() * found.usable.length)] as GeeqDiscoveredNode).url
+    } else {
+      endpoint = originOf(options.endpoint as string | URL)
+    }
+
+    return new GeeqChain({
+      endpoint,
+      candidates,
+      chainName,
+      chainNumber,
+      nodeNumber: options.nodeNumber,
+      penniesPerGeeq: options.penniesPerGeeq,
+      request,
+      ledgerMaxAgeMs: options.ledgerMaxAgeMs ?? DEFAULT_LEDGER_MAX_AGE_MS,
+    })
+  }
+
+  /** {@link GeeqChain.connect}, and install the result as the process-wide default. */
+  static async init(options: GeeqChainOptions): Promise<GeeqChain> {
+    const chain = await GeeqChain.connect(options)
+    defaultChain = chain
+    return chain
+  }
+
+  /** The default chain. Throws `not-initialized` when there is none. */
+  static current(): GeeqChain {
+    if (defaultChain === null) throw noChain('GeeqChain.current()')
+    return defaultChain
+  }
+
+  /** Whether a default chain has been installed. */
+  static get initialized(): boolean {
+    return defaultChain !== null
+  }
+
+  /** Clear the default. Call this from `afterEach` so tests do not leak into each other. */
+  static reset(): void {
+    defaultChain = null
+  }
+
+  /** Resolve an amount to pennies, reading a `{ geeq }` figure at {@link penniesPerGeeq}. */
+  toPennies(amount: GeeqAmount): bigint {
+    return toPennies(amount, this.penniesPerGeeq)
+  }
+
+  /** Show pennies as a Geeq figure at {@link penniesPerGeeq}, as the Geeq wallet does. */
+  formatGeeq(pennies: bigint): string {
+    return formatGeeq(pennies, this.penniesPerGeeq)
+  }
+
+  /**
+   * This chain's number.
+   *
+   * Known immediately when a directory named the chain, or once a ledger has been read.
+   * `undefined` in between — with a bare endpoint and no declared number, only the node
+   * can say.
+   */
+  get chainNumber(): number | undefined {
+    return this.cached?.chainNumber ?? this.declaredChainNumber
+  }
+
+  /**
+   * The node, once a ledger read has identified it in the net actor list.
+   *
+   * `undefined` until then: a node's number is the one thing the directory cannot say,
+   * so it is not known before the first read.
+   */
+  get node(): GeeqNode | undefined {
+    return this.resolved ?? undefined
+  }
+
+  /** The net actor directory from the last ledger read, if there has been one. */
+  get nodes(): readonly GeeqLedgerNode[] {
+    return this.cached?.nodes ?? []
+  }
+
+  /** Those of them that accept transactions. */
+  get processingNodes(): readonly GeeqLedgerNode[] {
+    return this.cached?.processingNodes ?? []
+  }
+
+  /** The ledger from the last read, if it is still cached. */
+  get ledger(): GeeqLedger | undefined {
+    return this.cached ?? undefined
+  }
+
+  /**
+   * A URL for another node in this chain.
+   *
+   * Every node answers client traffic on {@link GEEQ_NODE_PORT}, so only the scheme is
+   * carried over from the endpoint in use. The port recorded against a node in the
+   * ledger is its own internal listener and is never what you connect to.
+   */
+  endpointFor(host: string): string {
+    return `${new URL(this.endpoint).protocol}//${host}:${GEEQ_NODE_PORT}`
+  }
+
+  /**
+   * The current ledger, from cache when it is fresh enough.
+   *
+   * Staleness is safe in exactly one direction. The node accepts a target block within
+   * `[N-8, N+1]` of its own head, and a cached ledger can only be *behind*, so the
+   * target it yields is never in the future — the only rejected direction. The default
+   * five seconds is set by the node list and metadata limits, which have no such
+   * tolerance, not by the block window.
+   */
+  async getLedger(
+    options: { readonly maxAgeMs?: number; readonly signal?: AbortSignal } = {},
+  ): Promise<GeeqLedger> {
+    const maxAge = options.maxAgeMs ?? this.ledgerMaxAgeMs
+    const cached = this.cached
+    if (cached !== null && maxAge > 0 && Date.now() - cached.readAt < maxAge) return cached
+    return this.read(options.signal)
+  }
+
+  /** Discard the cached ledger and read again. */
+  async refresh(options: { readonly signal?: AbortSignal } = {}): Promise<GeeqLedger> {
+    this.cached = null
+    return this.read(options.signal)
+  }
+
+  /**
+   * One read at a time.
+   *
+   * Same single-flight shape as `initGeeq`, including clearing the promise on failure so
+   * a later call can retry rather than being stuck with the first error. Without it, a
+   * page that builds several transactions at once pulls the whole ledger several times
+   * from an endpoint with no rate limiting of any kind.
+   *
+   * The read is shared, so it carries no caller's signal: one caller aborting must not
+   * fail the others waiting on it. Each caller stops waiting on its own signal instead,
+   * and the read runs on, bounded by `timeoutMs`, to fill the cache for whoever is next.
+   */
+  private read(signal?: AbortSignal): Promise<GeeqLedger> {
+    if (signal?.aborted === true) return Promise.reject(signal.reason)
+    if (this.inflight !== null) return raceAbort(this.inflight, signal)
+
+    const pending = readLedger(this.endpoint, this.request)
+      .then((ledger) => {
+        const declared = this.declaredChainNumber
+        if (declared !== undefined && ledger.chainNumber !== declared) {
+          throw chainMismatch(
+            `This chain was opened as chain ${declared} but the node at ${this.endpoint} ` +
+              `serves chain ${ledger.chainNumber}. A transaction signed for the wrong ` +
+              'chain is rejected, so either drop chainNumber to accept the node\'s, or ' +
+              `use a node on chain ${declared}.`,
+          )
+        }
+
+        // The node's own number lives only in the ledger, so this is the first moment it
+        // can be known — and the first moment the node can be checked for being able to
+        // take work at all.
+        const selected = selectNode(ledger, this.endpoint, {
+          ...(this.nodeNumberOverride === undefined ? {} : { nodeNumber: this.nodeNumberOverride }),
+        })
+        this.resolved = new GeeqNode({ ...this.request, ...selected, url: this.endpoint })
+        this.cached = ledger
+        return ledger
+      })
+      .finally(() => {
+        this.inflight = null
+      })
+
+    this.inflight = pending
+    return raceAbort(pending, signal)
+  }
+
+  /**
+   * Everything a transaction must be pinned to, read from this chain.
+   *
+   * Throws rather than guessing when the account cannot sign: absent from the ledger
+   * (the ordinary state of an unfunded keypair), or present as a record type the
+   * protocol will not accept.
+   */
+  async getChainState(request: ChainStateRequest): Promise<GeeqChainState> {
+    const ledger = await this.getLedger({
+      ...(request.maxAgeMs === undefined ? {} : { maxAgeMs: request.maxAgeMs }),
+      ...(request.signal === undefined ? {} : { signal: request.signal }),
+    })
+    return this.stateIn(ledger, request.account)
+  }
+
+  /**
+   * What every transaction built from `ledger` is pinned to, bar the signer's nonce: the
+   * same for a signer's own transaction and for a proxy's.
+   */
+  private pinnedTo(
+    ledger: GeeqLedger,
+  ): Omit<GeeqChainState, 'nonce' | 'balance' | 'minimumTransfer'> {
+    return {
+      chainNumber: ledger.chainNumber,
+      blockNumber: ledger.targetBlockNumber,
+      nodeNumber: (this.resolved as GeeqNode).nodeNumber,
+      metadataLimits: ledger.metadataLimits,
+      geeqNorm: ledger.geeqNorm,
+      ledgerBlockNumber: ledger.blockNumber,
+      readAt: ledger.readAt,
+      nodeUrl: this.endpoint,
+    }
+  }
+
+  /** {@link getChainState} against a ledger already in hand, so a build reads only one. */
+  private stateIn(ledger: GeeqLedger, ref: AccountRef): GeeqChainState {
+    const accountId = resolveAccountId(ref)
+    const account = ledger.findCoinAccount(accountId)
+    const shown = toBase64(accountId)
+
+    if (account === undefined) {
+      throw accountNotFound(
+        `Account ${shown} is not in the ledger of chain ${ledger.chainNumber} at block ` +
+          `${ledger.blockNumber}. An account exists on a Geeq chain only once it has ` +
+          'received coins, so a freshly generated keypair will not be there. Fund it, ' +
+          'then try again.',
+      )
+    }
+
+    if (account.kind !== 'asset' || account.nonce === undefined) {
+      const described =
+        account.kind === 'hl'
+          ? 'a hash-lock record, which carries no nonce at all'
+          : account.kind === 'micro'
+            ? 'a micro-coin record'
+            : 'a record whose subtype could not be read'
+      throw accountNotAttestable(
+        `Account ${shown} is in the ledger at block ${ledger.blockNumber} as ${described}, ` +
+          'but an attestation must be signed by a coin-asset account. Sign with a ' +
+          'coin-asset key on this chain instead.',
+      )
+    }
+
+    return Object.freeze({
+      ...this.pinnedTo(ledger),
+      nonce: account.nonce,
+      balance: account.balance,
+      minimumTransfer: ledger.minimumTransfer,
+    })
+  }
+
+  /**
+   * The ledger a build is made from, and the state of `signer` in it.
+   *
+   * A cached ledger is up to a few seconds old, so "this account already built against
+   * this block" may only mean "we are looking at an old block". Look again once before
+   * letting the nonce guard refuse — otherwise a caller who waited out the block interval
+   * is told to wait for a block that has already passed. An explicit nonce is the caller
+   * taking responsibility, so it skips the check.
+   *
+   * Everything the build then needs — what the sender holds, which proxies exist — comes
+   * from this same ledger, so it all describes one block.
+   */
+  private async readForBuild(
+    signer: GeeqKeypair,
+    explicitNonce: number | undefined,
+    signal: AbortSignal | undefined,
+  ): Promise<{ readonly ledger: GeeqLedger; readonly chainState: GeeqChainState }> {
+    const options = signal === undefined ? {} : { signal }
+    const [cached] = await Promise.all([this.getLedger(options), initGeeq()])
+    const ledger = await this.recheckIfClaimed(
+      cached,
+      explicitNonce === undefined ? toBase64(signer.accountId) : undefined,
+      options,
+    )
+    const chainState = this.stateIn(ledger, signer)
+    return {
+      ledger,
+      chainState:
+        explicitNonce === undefined ? chainState : { ...chainState, nonce: explicitNonce },
+    }
+  }
+
+  /** Read afresh if `guardKey` already built against `ledger`'s block. See {@link readForBuild}. */
+  private async recheckIfClaimed(
+    ledger: GeeqLedger,
+    guardKey: string | undefined,
+    options: { readonly signal?: AbortSignal },
+  ): Promise<GeeqLedger> {
+    if (guardKey === undefined || !this.nonces.wouldCollide(guardKey, ledger.blockNumber)) {
+      return ledger
+    }
+    return this.refresh(options)
+  }
+
+  /**
+   * Build and sign an attestation, deriving everything the chain decides.
+   *
+   * This is where the ledger is read, because this is the first moment the values it
+   * carries are actually needed — and they go stale within a handful of blocks, so
+   * reading them any earlier would only mean reading them twice.
+   *
+   * The result is **not submitted**. Hand it to {@link GeeqSocket.track} first, so its
+   * verdict has somewhere to arrive, then POST `transaction` and `payload` to
+   * {@link AttestationTx.nodeUrl}; any other node rejects it, because the node number is
+   * checked with strict equality.
+   */
+  async createAttestation(input: AttestationRequest): Promise<AttestationTx> {
+    if ((input.content === undefined) === (input.attestHash === undefined)) {
+      throw invalidArgument(
+        'Provide exactly one of content (hashed here with BLAKE3) or attestHash (a ' +
+          `${ATTEST_HASH_BYTES}-byte digest you produced yourself).`,
+      )
+    }
+
+    const attestHash = input.attestHash ?? (await attestHashOf(input.content as GeeqContent))
+    const { chainState } = await this.readForBuild(input.keypair, input.nonce, input.signal)
+
+    const tx = createAttestationTxSync({
+      keypair: input.keypair,
+      attestHash,
+      ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+      chainState,
+    })
+    assertAffordable(this.penniesPerGeeq, 'This account', chainState.balance, 0n, tx.fee, chainState.ledgerBlockNumber)
+    this.claimNonce(input.keypair, input.nonce, chainState, tx)
+    return tx
+  }
+
+  /**
+   * Record the nonce a finished build took, so a second build against the same block is
+   * refused rather than sent to share it.
+   *
+   * Claimed only once a transaction really exists, so a build that failed validation does
+   * not consume the account's one nonce for this block. An explicit nonce is the caller
+   * taking responsibility, so it bypasses the guard entirely.
+   */
+  private claimNonce(
+    signer: GeeqKeypair,
+    explicitNonce: number | undefined,
+    chainState: GeeqChainState,
+    tx: { readonly transactionHash: Uint8Array },
+  ): void {
+    if (explicitNonce !== undefined) return
+    this.nonces.claim(
+      toBase64(signer.accountId),
+      chainState.ledgerBlockNumber,
+      chainState.nonce,
+      toBase64(tx.transactionHash),
+    )
+  }
+
+  /**
+   * Resolve a recipient, checking the chain it belongs to when one is stated.
+   *
+   * An address carries a chain number, and an address from another chain is almost
+   * always a paste from the wrong place. The account id inside it would still be
+   * technically usable here, which is exactly why this is worth refusing rather than
+   * quietly sending.
+   */
+  private resolveRecipient(to: string | AccountRef, chainNumber: number): Uint8Array {
+    if (typeof to !== 'string') return resolveAccountId(to)
+
+    const decoded = decodeWalletAddressSync(to)
+    if (decoded.chainNumber !== chainNumber) {
+      throw chainMismatch(
+        `The recipient address is for chain ${decoded.chainNumber} but this is chain ` +
+          `${chainNumber}. An address encodes its chain, so this one was almost certainly ` +
+          'copied from somewhere else — check it before sending.',
+      )
+    }
+    return decoded.accountId
+  }
+
+  /**
+   * Send coin to another account, and NFTs with it if you name them.
+   *
+   * Reads the ledger, so it also knows what the sender holds and what the chain's minimum
+   * transfer is. The amount is checked against the minimum, and the sender's NFTs against
+   * the ones named, before anything is signed; the balance against the amount plus the
+   * fee once the signed transaction gives the fee. NFTs always travel with coin: leave
+   * `amount` out and they go with the chain's minimum transfer.
+   *
+   * The result is **not submitted**. Hand it to {@link GeeqSocket.track} first, then POST
+   * `transaction` to {@link CoinTransferTx.nodeUrl} using `coinTransferSubmitBody`, which
+   * sends it as type `uvt` — a different shape from an attestation, and with no separate
+   * payload.
+   */
+  async createTransfer(input: CoinTransferRequest): Promise<CoinTransferTx> {
+    const nfts = input.nfts ?? []
+    if (input.amount === undefined && nfts.length === 0) {
+      throw invalidArgument('Say what to send: an amount, NFTs, or both.')
+    }
+    const asked = input.amount === undefined ? undefined : this.toPennies(input.amount)
+    const { ledger, chainState } = await this.readForBuild(input.from, input.nonce, input.signal)
+
+    const to = this.resolveRecipient(input.to, chainState.chainNumber)
+
+    const minimum = chainState.minimumTransfer
+    const pennies = asked ?? minimum
+    if (pennies === undefined) {
+      throw invalidArgument(
+        'This chain publishes no minimum transfer to send with the NFTs by default, so pass amount.',
+      )
+    }
+    if (minimum !== undefined && pennies < minimum) {
+      throw amountBelowMinimum(
+        `This chain will not accept a transfer below ${this.formatGeeq(minimum)} geeq, and ` +
+          `${this.formatGeeq(pennies)} is smaller. The minimum comes from the chain's own ` +
+          'minTxAmt and geeqNorm parameters, read at block ' +
+          `${chainState.ledgerBlockNumber}.`,
+      )
+    }
+
+    // The transaction names each NFT by id and by its place in the sender's list, read
+    // from the same ledger as the nonce, so both describe one block.
+    const held = ledger.findCoinAccount(input.from)?.nfts ?? []
+    const entries = nfts.map((id) => {
+      const position = held.findIndex((nft) => toBase64(nft.id) === toBase64(id))
+      if (position === -1) {
+        throw nftNotOwned(
+          `This account does not hold NFT ${toBase64(id)} at block ${ledger.blockNumber}. ` +
+            'findNfts lists the ones it does; one just sent away is gone once a block confirms it.',
+        )
+      }
+      if (held[position]?.counterparty === true) {
+        throw invalidArgument(`NFT ${toBase64(id)} is a counterparty NFT, which a plain transfer cannot move.`)
+      }
+      return { id, position }
+    })
+
+    // The chain gives an NFT only to a wallet account (or a multisig proxy). A proxy's
+    // address is the likely paste here.
+    if (entries.length > 0) {
+      const proxy = ledger.findProxyAccount(to)
+      const account = ledger.findCoinAccount(to)
+      if ((proxy !== undefined && proxy.kind !== 'multisig') || (account !== undefined && account.kind !== 'asset')) {
+        throw invalidArgument(
+          `The recipient is a ${proxy?.kind ?? account?.kind} record, and the chain gives NFTs ` +
+            'only to a wallet account. Send them to a wallet address instead.',
+        )
+      }
+    }
+
+    const tx = createCoinTransferTxSync({
+      keypair: input.from,
+      to,
+      amount: pennies,
+      nfts: entries,
+      chainState,
+    })
+    assertAffordable(this.penniesPerGeeq, 'This account', chainState.balance, pennies, tx.fee, chainState.ledgerBlockNumber)
+    this.claimNonce(input.from, input.nonce, chainState, tx)
+    return tx
+  }
+
+  /**
+   * The NFTs an account holds on this chain, in the order its record lists them, each with
+   * the hash and labels it was minted with.
+   *
+   * Which NFTs it holds comes from the validation layer ledger; what each stands for, from
+   * the application layer ledger, which is read afresh every time. An account the chain
+   * does not know holds none. A new NFT shows once a block has confirmed it, so pass
+   * `maxAgeMs: 0` to look straight after one was minted or sent.
+   */
+  async findNfts(request: NftsRequest): Promise<readonly GeeqNft[]> {
+    const signal = request.signal === undefined ? {} : { signal: request.signal }
+    const [ledger, records] = await Promise.all([
+      this.getLedger({
+        ...(request.maxAgeMs === undefined ? {} : { maxAgeMs: request.maxAgeMs }),
+        ...signal,
+      }),
+      readNftRecords(this.endpoint, { ...this.request, ...signal }),
+    ])
+    const held = ledger.findCoinAccount(request.owner)?.nfts ?? []
+    return Object.freeze(
+      held.map((nft) => {
+        const record = records.get(toBase64(nft.id))
+        return Object.freeze({ ...nft, attestHash: record?.attestHash, metadata: record?.metadata ?? [] })
+      }),
+    )
+  }
+
+  /**
+   * The NFT mint proxies an admin has on this chain, each with its index, and the index
+   * its next proxy takes: one past the highest in use, or 1 for an admin with none.
+   *
+   * A proxy appears once a block has confirmed it, so pass `maxAgeMs: 0` to look
+   * straight after one was submitted.
+   */
+  async findNftMintProxies(request: NftMintProxiesRequest): Promise<GeeqNftMintProxies> {
+    const [ledger] = await Promise.all([
+      this.getLedger({
+        ...(request.maxAgeMs === undefined ? {} : { maxAgeMs: request.maxAgeMs }),
+        ...(request.signal === undefined ? {} : { signal: request.signal }),
+      }),
+      initGeeq(),
+    ])
+    return nftMintProxiesIn(ledger, request.admin)
+  }
+
+  /**
+   * Create a proxy to mint NFTs through.
+   *
+   * A proxy is a record of its own: it holds coin, carries its own nonce, and names one
+   * admin — `admin` here — who signs every mint made through it. Its id is derived from
+   * the admin's key and an index, as the Geeq wallet derives it: by default the next
+   * index {@link findNftMintProxies} reports, so it is found again from the key alone.
+   *
+   * Checks the funding against the chain's minimum, and the admin's balance against the
+   * funding plus the fee. The result is **not submitted** — track it, then post it with
+   * `coinTransferSubmitBody`, exactly as a transfer. The proxy exists once a block
+   * confirms it.
+   */
+  async createNftMintProxy(input: NftMintProxyRequest): Promise<NftMintProxyTx> {
+    const pennies = this.toPennies(input.amount)
+    const { ledger, chainState } = await this.readForBuild(input.admin, input.nonce, input.signal)
+
+    // The node holds proxy funding to the same minimum as any transfer.
+    const minimum = chainState.minimumTransfer
+    if (minimum !== undefined && pennies < minimum) {
+      throw amountBelowMinimum(
+        `A proxy must be funded with at least ${this.formatGeeq(minimum)} geeq, and ` +
+          `${this.formatGeeq(pennies)} is smaller. It is the same minimum as a transfer, from ` +
+          "the chain's minTxAmt and geeqNorm parameters, read at block " +
+          `${chainState.ledgerBlockNumber}.`,
+      )
+    }
+
+    const existing = nftMintProxiesIn(ledger, input.admin)
+    const index = input.index ?? existing.nextIndex
+    if (existing.proxies.some((proxy) => proxy.index === index)) {
+      throw invalidArgument(
+        `This admin already has a proxy at index ${index}. Leave index out to take the ` +
+          `next one, ${existing.nextIndex}.`,
+      )
+    }
+
+    const tx = createNftMintProxyTxSync({
+      keypair: input.admin,
+      index,
+      amount: pennies,
+      chainState,
+    })
+    assertAffordable(this.penniesPerGeeq, 'This account', chainState.balance, pennies, tx.fee, chainState.ledgerBlockNumber)
+    this.claimNonce(input.admin, input.nonce, chainState, tx)
+    return tx
+  }
+
+  /**
+   * Mint an NFT through one of the admin's proxies.
+   *
+   * The proxy is the sender: it pays the fee and the coin sent with the NFT, and spends
+   * its own nonce, not the admin's. The admin signs. The NFT itself is the content's hash
+   * and labels, as an attestation is, and its id is derived from them — so the same
+   * content with the same labels through the same proxy cannot be minted twice.
+   *
+   * Reads the ledger to find the proxy and check what it holds. The result is **not
+   * submitted** — track it, then post it with `attestationSubmitBody`, exactly as an
+   * attestation: two fields, as `uat`.
+   */
+  async mintNft(input: NftMintRequest): Promise<NftMintTx> {
+    if ((input.content === undefined) === (input.attestHash === undefined)) {
+      throw invalidArgument(
+        'Provide exactly one of content (hashed here with BLAKE3) or attestHash (a ' +
+          `${ATTEST_HASH_BYTES}-byte digest you produced yourself).`,
+      )
+    }
+    assertUint32(input.index, 'index')
+
+    const attestHash = input.attestHash ?? (await attestHashOf(input.content as GeeqContent))
+    const signal = input.signal === undefined ? {} : { signal: input.signal }
+
+    const [cached] = await Promise.all([this.getLedger(signal), initGeeq()])
+    const proxyKey = toBase64(nftMintProxyId(input.admin.publicKey, input.index))
+
+    // The proxy spends its own nonce, so the guard is keyed on the proxy, not the admin.
+    const ledger = await this.recheckIfClaimed(
+      cached,
+      input.nonce === undefined ? proxyKey : undefined,
+      signal,
+    )
+
+    const proxy = ledger
+      .findProxyAccounts({ admin: input.admin })
+      .find((found) => toBase64(found.accountId) === proxyKey)
+    if (proxy === undefined) {
+      throw accountNotFound(
+        `This admin has no NFT mint proxy at index ${input.index} in the ledger of chain ` +
+          `${ledger.chainNumber} at block ${ledger.blockNumber}. A new proxy appears once a ` +
+          'block has confirmed it; findNftMintProxies lists the ones there are.',
+      )
+    }
+
+    const minimum = ledger.minimumTransfer
+    const pennies = input.amount === undefined ? minimum : this.toPennies(input.amount)
+    if (pennies === undefined) {
+      throw invalidArgument(
+        'This chain publishes no minimum transfer to send with the NFT by default, so pass amount.',
+      )
+    }
+    if (minimum !== undefined && pennies < minimum) {
+      throw amountBelowMinimum(
+        `A mint must send at least ${this.formatGeeq(minimum)} geeq with the NFT, and ` +
+          `${this.formatGeeq(pennies)} is smaller. It is the same minimum as a transfer, from ` +
+          "the chain's minTxAmt and geeqNorm parameters, read at block " +
+          `${ledger.blockNumber}.`,
+      )
+    }
+    const tx = createNftMintTxSync({
+      keypair: input.admin,
+      proxyAccountId: proxy.accountId,
+      attestHash,
+      ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+      to:
+        input.to === undefined
+          ? input.admin.accountId
+          : this.resolveRecipient(input.to, ledger.chainNumber),
+      amount: pennies,
+      chainState: { ...this.pinnedTo(ledger), nonce: input.nonce ?? proxy.nonce },
+    })
+    // The proxy pays, not the admin. Topping it up is a plain transfer to its address.
+    assertAffordable(this.penniesPerGeeq, `Proxy ${input.index}`, proxy.balance, pennies, tx.fee, ledger.blockNumber)
+
+    if (input.nonce === undefined) {
+      this.nonces.claim(proxyKey, ledger.blockNumber, proxy.nonce, toBase64(tx.transactionHash))
+    }
+
+    return tx
+  }
+
+  /**
+   * Whether a built transaction is now too old to send: the chain is past its
+   * `validUntilBlock`, and a node would refuse it with an HTTP 400.
+   *
+   * Reads the ledger afresh, because a cached one can only be behind the chain and would
+   * say "not yet" when it already is. Call it before submitting a transaction that may
+   * have waited.
+   */
+  async isExpired(tx: { readonly validUntilBlock: number }): Promise<boolean> {
+    const ledger = await this.getLedger({ maxAgeMs: 0 })
+    return ledger.blockNumber > tx.validUntilBlock
+  }
+
+  /**
+   * Give back the nonce a built transaction took, because it will never be sent — the
+   * user changed something and is building again. The next build may then take the same
+   * nonce in the same block instead of being refused with `nonce-collision`.
+   *
+   * Only for a transaction that was not submitted: if it reaches the node as well as its
+   * rebuild, the two share a nonce and the node rejects both.
+   */
+  discard(tx: { readonly transactionHash: Uint8Array }): void {
+    this.nonces.release(toBase64(tx.transactionHash))
+  }
+
+  /** Forget which accounts have built a transaction against the current block. */
+  forgetNonces(): void {
+    this.nonces.clear()
+  }
+
+  /** Drop cached state, and step down as the default if this chain holds that slot. */
+  dispose(): void {
+    this.cached = null
+    this.resolved = null
+    this.inflight = null
+    this.nonces.clear()
+    if (defaultChain === this) defaultChain = null
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      chainNumber: this.chainNumber,
+      endpoint: this.endpoint,
+      node: this.node,
+      ledgerBlockNumber: this.cached?.blockNumber,
+      candidateCount: this.candidates.length,
+    }
+  }
+
+  toString(): string {
+    return `GeeqChain(chain ${this.chainNumber ?? 'unread'} via ${this.endpoint})`
+  }
+}
+
+/**
+ * Connect to a chain and make it the default.
+ *
+ * Thin alias for {@link GeeqChain.init} — the name most applications reach for, and one
+ * line so there is no second implementation to keep in step.
+ *
+ * ```ts
+ * await initChain({ endpoint: 'https://1.2.3.4:2082' })
+ * const tx = await attest({ keypair, content: fileBytes })
+ * ```
+ */
+export function initChain(options: GeeqChainOptions): Promise<GeeqChain> {
+  return GeeqChain.init(options)
+}
+
+/** Build an attestation on the default chain. See {@link GeeqChain.createAttestation}. */
+export function attest(input: AttestationRequest): Promise<AttestationTx> {
+  return GeeqChain.current().createAttestation(input)
+}
+
+/** Send coin on the default chain. See {@link GeeqChain.createTransfer}. */
+export function transfer(input: CoinTransferRequest): Promise<CoinTransferTx> {
+  return GeeqChain.current().createTransfer(input)
+}