@geeqdev/geeq-sdk 0.1.0 → 0.1.1

package/src/ledger/decode.ts

@@ -0,0 +1,147 @@
+import { Message } from 'capnp-ts'
+import { ValLayLedger as CapnpValLayLedger } from '../capnp/valLayLedger.capnp'
+
+import { MAX_UINT32 } from '../assert'
+import { fromBase64, toBase64 } from '../encoding/base64'
+import { GeeqError, ledgerUnreadable } from '../errors'
+import type { CoinAccountFacts } from './coin-accounts'
+import { readCoinAccount } from './coin-accounts'
+import { GeeqLedger } from './geeq-ledger'
+import type { GeeqLedgerNode } from './net-actors'
+import { isProcessing, toNodeRole, toNodeStatus } from './net-actors'
+import { readGeeqNorm, readMetadataLimits, readMinimumTransfer } from './params'
+import type { ProxyAccountFacts } from './proxy-accounts'
+import { readProxyAccount } from './proxy-accounts'
+
+export interface DecodeLedgerOptions {
+  /** The node this came from, carried through onto the snapshot. */
+  readonly nodeUrl?: string | undefined
+  /** Overrides the read timestamp. For deterministic tests. */
+  readonly readAt?: number | undefined
+}
+
+/**
+ * Decode a validation layer ledger.
+ *
+ * `source` is what a node's `result` field holds: base64, or the bytes behind it. The
+ * message is Cap'n Proto **packed**, which is what the node writes with
+ * `toPackedArrayBuffer()` — not the flattened form used for signing.
+ *
+ * Everything is read in this one pass and the message is then dropped, so the caller
+ * gets plain values with no traversal budget attached. See {@link GeeqLedger}.
+ */
+export function decodeValidationLedger(
+  source: Uint8Array | ArrayBuffer | string,
+  options: DecodeLedgerOptions = {},
+): GeeqLedger {
+  const bytes =
+    typeof source === 'string'
+      ? fromBase64(source, 'The ledger')
+      : source instanceof ArrayBuffer
+        ? new Uint8Array(source)
+        : source
+
+  if (bytes.length === 0) {
+    throw ledgerUnreadable(
+      'The ledger is empty. A node reports this before it has committed its first ' +
+        'block and while it is resyncing — wait and retry, or read from another node ' +
+        'on the same chain.',
+    )
+  }
+
+  let ledger
+  try {
+    ledger = new Message(bytes, true).getRoot(CapnpValLayLedger)
+  } catch (cause) {
+    throw ledgerUnreadable(
+      `Could not decode ${bytes.length} bytes as a packed Cap'n Proto ValLayLedger. ` +
+        'The node is probably running a schema version this SDK does not know — ' +
+        'upgrade @geeqdev/geeq-sdk, or read the chain state yourself.',
+      cause,
+    )
+  }
+
+  try {
+    const chainNumber = ledger.getChainNum()
+    const blockNumber = ledger.getBlockNum()
+
+    if (blockNumber >= MAX_UINT32) {
+      // Every transaction targets blockNumber + 1, which would overflow the uint32 the
+      // protocol encodes it in. Refuse rather than silently wrap to zero.
+      throw ledgerUnreadable(
+        `The ledger reports block ${blockNumber}, the maximum a uint32 can hold, so no ` +
+          'transaction can target the next block. The ledger is almost certainly corrupt.',
+      )
+    }
+
+    const nodes: GeeqLedgerNode[] = ledger
+      .getNetActorList()
+      .getNetActorRecs()
+      .toArray()
+      .map((record) => {
+        const role = toNodeRole(record.getNetActorType())
+        const status = toNodeStatus(record.getRecStatus())
+        const retiresAtBlock = record.getBlockNumRemove()
+        return Object.freeze({
+          nodeNumber: record.getNodeNumSelf(),
+          host: record.getIpAddr(),
+          port: record.getPortNum(),
+          role,
+          status,
+          processing: isProcessing(role, status),
+          retiresAtBlock,
+          // The node's own guard compares its blockNumRemove against its current block
+          // plus two, and the ledger's block is that current block.
+          retiring: retiresAtBlock < blockNumber + 2,
+        })
+      })
+
+    const params = ledger.getParamAcctList().getParamAcctRecs().toArray()
+
+    // A plausibility gate. Packed capnp can "succeed" on garbage and yield a message of
+    // zeros, which would otherwise surface much later as chain 0, block 0 and a missing
+    // account. A real ledger always carries net actors and parameters.
+    if (nodes.length === 0 || params.length === 0) {
+      throw ledgerUnreadable(
+        `The ledger decoded but does not look like one: chain ${chainNumber}, block ` +
+          `${blockNumber}, ${nodes.length} net actor records, ${params.length} parameter ` +
+          'records. A real ledger always has at least one of each, so this URL is ' +
+          'probably not a Geeq node.',
+      )
+    }
+
+    const accounts = new Map<string, CoinAccountFacts>()
+    const coinAccounts = ledger.getCoinAcctRecs()
+    for (let index = 0; index < coinAccounts.getLength(); index += 1) {
+      const record = coinAccounts.get(index)
+      const accountId = new Uint8Array(record.getAcctNumVal().toArrayBuffer())
+      accounts.set(toBase64(accountId), readCoinAccount(record))
+    }
+
+    const proxies = new Map<string, ProxyAccountFacts>()
+    for (const record of ledger.getProxyAcctRecs().toArray()) {
+      const accountId = new Uint8Array(record.getAcctNumVal().toArrayBuffer())
+      proxies.set(toBase64(accountId), readProxyAccount(record))
+    }
+
+    return new GeeqLedger({
+      chainNumber,
+      blockNumber,
+      nodes,
+      metadataLimits: readMetadataLimits(params),
+      minimumTransfer: readMinimumTransfer(params),
+      geeqNorm: readGeeqNorm(params),
+      accounts,
+      proxies,
+      readAt: options.readAt ?? Date.now(),
+      nodeUrl: options.nodeUrl,
+    })
+  } catch (cause) {
+    if (cause instanceof GeeqError) throw cause
+    throw ledgerUnreadable(
+      'The ledger decoded but its contents could not be read. The node is probably ' +
+        'running a schema version this SDK does not know.',
+      cause,
+    )
+  }
+}

package/src/ledger/geeq-ledger.ts

@@ -0,0 +1,184 @@
+import { resolveAccountId } from '../crypto/account-id'
+import type { AccountRef } from '../crypto/account-id'
+import { fromBase64, toBase64 } from '../encoding/base64'
+import type { GeeqMetadataLimits } from '../types'
+import type { CoinAccountFacts, GeeqCoinAccount } from './coin-accounts'
+import type { GeeqLedgerNode } from './net-actors'
+import type { GeeqProxyAccount, ProxyAccountFacts } from './proxy-accounts'
+
+/** @internal — built by {@link decodeValidationLedger}, never by hand. */
+export interface GeeqLedgerInit {
+  readonly chainNumber: number
+  readonly blockNumber: number
+  readonly nodes: readonly GeeqLedgerNode[]
+  readonly metadataLimits: GeeqMetadataLimits | undefined
+  readonly minimumTransfer: bigint | undefined
+  readonly geeqNorm: bigint | undefined
+  readonly accounts: ReadonlyMap<string, CoinAccountFacts>
+  readonly proxies: ReadonlyMap<string, ProxyAccountFacts>
+  readonly readAt: number
+  readonly nodeUrl: string | undefined
+}
+
+/**
+ * One validation layer ledger, decoded into plain values.
+ *
+ * This is a snapshot, not a view: the Cap'n Proto `Message` it came from is released
+ * the moment decoding finishes. That is deliberate and load-bearing. capnp-ts counts a
+ * traversal budget per `Message` and never resets it, so a retained handle rescanned on
+ * every transaction eventually throws `PTR_TRAVERSAL_LIMIT_EXCEEDED`; and reading a
+ * malformed union arm mutates the message in place. Neither can happen to a snapshot.
+ *
+ * It holds no WebAssembly handle, so unlike a keypair it needs no `dispose()`.
+ */
+export class GeeqLedger {
+  /** The ledger's own chain number. A transaction must name exactly this. */
+  readonly chainNumber: number
+  /** N — the last block committed to this ledger. */
+  readonly blockNumber: number
+  /** N + 1 — the block a transaction built now should ask for. */
+  readonly targetBlockNumber: number
+  /** Every net actor, in ledger order. */
+  readonly nodes: readonly GeeqLedgerNode[]
+  /** Undefined when this chain publishes no metadata parameters. */
+  readonly metadataLimits: GeeqMetadataLimits | undefined
+  /**
+   * The smallest transfer this chain accepts, in pennies.
+   *
+   * Undefined when the chain does not publish the parameters it is derived from.
+   */
+  readonly minimumTransfer: bigint | undefined
+  /**
+   * The chain's `geeqNorm` parameter, which the minimum transfer and every fee are
+   * multiples of. Undefined when the chain does not publish it.
+   */
+  readonly geeqNorm: bigint | undefined
+  /** `Date.now()` when this was read, so callers can judge staleness. */
+  readonly readAt: number
+  /** The node it was read from, when it came from one. */
+  readonly nodeUrl: string | undefined
+
+  // Deliberately a TypeScript `private`, not a `#private` field. A `#private` is
+  // unreachable through a Proxy, which breaks Vue's ref() — the same trap documented
+  // on Keypair in src/crypto/keypair.ts. Non-enumerable so it stays out of logs and
+  // structured clones, since on a busy chain it is the largest thing here.
+  private readonly accounts!: ReadonlyMap<string, CoinAccountFacts>
+  private readonly proxies!: ReadonlyMap<string, ProxyAccountFacts>
+
+  /** @internal */
+  constructor(init: GeeqLedgerInit) {
+    this.chainNumber = init.chainNumber
+    this.blockNumber = init.blockNumber
+    this.targetBlockNumber = init.blockNumber + 1
+    this.nodes = Object.freeze([...init.nodes])
+    this.metadataLimits = init.metadataLimits
+    this.minimumTransfer = init.minimumTransfer
+    this.geeqNorm = init.geeqNorm
+    this.readAt = init.readAt
+    this.nodeUrl = init.nodeUrl
+    Object.defineProperty(this, 'accounts', {
+      value: init.accounts,
+      enumerable: false,
+      writable: false,
+    })
+    Object.defineProperty(this, 'proxies', {
+      value: init.proxies,
+      enumerable: false,
+      writable: false,
+    })
+  }
+
+  /** The nodes that will actually accept a transaction. */
+  get processingNodes(): readonly GeeqLedgerNode[] {
+    return this.nodes.filter((node) => node.processing)
+  }
+
+  /**
+   * Find a net actor record.
+   *
+   * By `host` this matches the bare IP and nothing else — every first-party client does
+   * the same, because a record's `port` is the node's internal listen port while clients
+   * connect through a proxy on another one. Matching on both finds nothing.
+   */
+  findNode(match: { readonly host: string } | { readonly nodeNumber: number }): GeeqLedgerNode | undefined {
+    if ('nodeNumber' in match) {
+      return this.nodes.find((node) => node.nodeNumber === match.nodeNumber)
+    }
+    return this.nodes.find((node) => node.host === match.host)
+  }
+
+  /** Every net actor record at one host. More than one is possible, and ambiguous. */
+  findNodes(host: string): readonly GeeqLedgerNode[] {
+    return this.nodes.filter((node) => node.host === host)
+  }
+
+  /**
+   * The signing account's coin record, or `undefined` when this chain has none for it.
+   *
+   * Absence is the ordinary state of a freshly generated keypair: an account appears in
+   * the ledger only once it has been funded.
+   */
+  findCoinAccount(account: AccountRef): GeeqCoinAccount | undefined {
+    const accountId = resolveAccountId(account)
+    const facts = this.accounts.get(toBase64(accountId))
+    if (facts === undefined) return undefined
+    return Object.freeze({
+      accountId,
+      kind: facts.kind,
+      nonce: facts.nonce,
+      balance: facts.balance,
+      nfts: facts.nfts,
+    })
+  }
+
+  /** A proxy record, or `undefined` when this chain has none with that id. */
+  findProxyAccount(account: AccountRef): GeeqProxyAccount | undefined {
+    const accountId = resolveAccountId(account)
+    const facts = this.proxies.get(toBase64(accountId))
+    if (facts === undefined) return undefined
+    return Object.freeze({ accountId, ...facts })
+  }
+
+  /**
+   * Every NFT mint proxy an account administers — the ones it can mint through.
+   *
+   * Found by the admin each record names, so it needs nothing remembered from when they
+   * were created.
+   */
+  findProxyAccounts(match: { readonly admin: AccountRef }): readonly GeeqProxyAccount[] {
+    const admin = toBase64(resolveAccountId(match.admin))
+    const found: GeeqProxyAccount[] = []
+    for (const [key, facts] of this.proxies) {
+      if (facts.admin !== undefined && toBase64(facts.admin) === admin) {
+        found.push(Object.freeze({ accountId: fromBase64(key), ...facts }))
+      }
+    }
+    return found
+  }
+
+  /** How many coin accounts this ledger carries. Mostly useful for diagnostics. */
+  get coinAccountCount(): number {
+    return this.accounts.size
+  }
+
+  /** Summary only — the account table is far too large to serialise. */
+  toJSON(): Record<string, unknown> {
+    return {
+      chainNumber: this.chainNumber,
+      blockNumber: this.blockNumber,
+      targetBlockNumber: this.targetBlockNumber,
+      nodes: this.nodes,
+      metadataLimits: this.metadataLimits,
+      minimumTransfer: this.minimumTransfer?.toString(),
+      geeqNorm: this.geeqNorm?.toString(),
+      coinAccountCount: this.coinAccountCount,
+      proxyAccountCount: this.proxies.size,
+      readAt: this.readAt,
+      nodeUrl: this.nodeUrl,
+    }
+  }
+
+  toString(): string {
+    return `GeeqLedger(chain ${this.chainNumber}, block ${this.blockNumber}, ${this.nodes.length} nodes)`
+  }
+}

package/src/ledger/net-actors.ts

@@ -0,0 +1,129 @@
+import {
+  NetActorStatus as CapnpNetActorStatus,
+  NetActorType as CapnpNetActorType,
+} from '../capnp/netActorRec.capnp'
+
+/** What kind of actor a net actor record describes. */
+export type GeeqNodeRole =
+  | 'anchor-node'
+  | 'anon-node'
+  | 'cert-node'
+  | 'cert-authority'
+  | 'chain-admin'
+  | 'relay'
+  | 'treasury-agent'
+  | 'unknown'
+
+/** What that actor is currently doing. */
+export type GeeqNodeStatus =
+  | 'chain-admin'
+  | 'hub'
+  | 'leaving'
+  | 'listening'
+  | 'node'
+  | 'ready'
+  | 'relay'
+  | 'suspended'
+  | 'unknown'
+
+const ROLES: Readonly<Record<number, GeeqNodeRole>> = Object.freeze({
+  [CapnpNetActorType.NET_ACTOR_TYPE_ANCHOR_NODE]: 'anchor-node',
+  [CapnpNetActorType.NET_ACTOR_TYPE_ANON_NODE]: 'anon-node',
+  [CapnpNetActorType.NET_ACTOR_TYPE_CERT_NODE]: 'cert-node',
+  [CapnpNetActorType.NET_ACTOR_TYPE_CERT_AUTH]: 'cert-authority',
+  [CapnpNetActorType.NET_ACTOR_TYPE_CHAIN_ADMIN]: 'chain-admin',
+  [CapnpNetActorType.NET_ACTOR_TYPE_RELAY]: 'relay',
+  [CapnpNetActorType.NET_ACTOR_TYPE_TREASURY_AGENT]: 'treasury-agent',
+})
+
+const STATUSES: Readonly<Record<number, GeeqNodeStatus>> = Object.freeze({
+  [CapnpNetActorStatus.NET_ACTOR_STATUS_CHAIN_ADMIN]: 'chain-admin',
+  [CapnpNetActorStatus.NET_ACTOR_STATUS_HUB]: 'hub',
+  [CapnpNetActorStatus.NET_ACTOR_STATUS_LEAVING]: 'leaving',
+  [CapnpNetActorStatus.NET_ACTOR_STATUS_LISTENING]: 'listening',
+  [CapnpNetActorStatus.NET_ACTOR_STATUS_NODE]: 'node',
+  [CapnpNetActorStatus.NET_ACTOR_STATUS_READY]: 'ready',
+  [CapnpNetActorStatus.NET_ACTOR_STATUS_RELAY]: 'relay',
+  [CapnpNetActorStatus.NET_ACTOR_STATUS_SUSPENDED]: 'suspended',
+})
+
+/**
+ * Unknown values map to `'unknown'` rather than throwing.
+ *
+ * This deliberately differs from `fromWasmRecordType`, which throws: a bad record type
+ * means a corrupt address, but a new actor kind on a newer chain must not make an
+ * otherwise-valid ledger undecodable. An `'unknown'` actor is never `processing`, so
+ * the safe outcome is the default.
+ */
+export function toNodeRole(value: number): GeeqNodeRole {
+  return ROLES[value] ?? 'unknown'
+}
+
+export function toNodeStatus(value: number): GeeqNodeStatus {
+  return STATUSES[value] ?? 'unknown'
+}
+
+/** Roles that run the transaction handler at all. */
+const PROCESSING_ROLES: ReadonlySet<GeeqNodeRole> = new Set<GeeqNodeRole>([
+  'anon-node',
+  'anchor-node',
+  'cert-node',
+])
+
+/** Statuses in which such a role actually accepts transactions. */
+const PROCESSING_STATUSES: ReadonlySet<GeeqNodeStatus> = new Set<GeeqNodeStatus>(['node', 'hub'])
+
+/**
+ * Whether this actor will accept a transaction.
+ *
+ * Mirrors `isActive()` in the node itself
+ * (geeq_node_core/src/wrappers/network-actor-record/index.ts). Anything else answers
+ * HTTP 400 `'not processing'`, or — for a relay — registers no handler at all.
+ */
+export function isProcessing(role: GeeqNodeRole, status: GeeqNodeStatus): boolean {
+  return PROCESSING_ROLES.has(role) && PROCESSING_STATUSES.has(status)
+}
+
+/** One net actor record, as plain values. */
+export interface GeeqLedgerNode {
+  /** `nodeNumSelf` — what a transaction must name, checked with strict equality. */
+  readonly nodeNumber: number
+  /** The bare IP the ledger records. Nodes are matched on this and nothing else. */
+  readonly host: string
+  /**
+   * The port recorded against this node in the ledger.
+   *
+   * **Not the port you connect to.** Clients always reach a node on 2082, where TLS is
+   * terminated; every first-party client ignores this field and rebuilds the URL from
+   * its own configuration. Exposed for diagnostics, and used only to break a tie when
+   * one address carries several records.
+   */
+  readonly port: number
+  readonly role: GeeqNodeRole
+  readonly status: GeeqNodeStatus
+  /**
+   * True when the protocol permits this node to accept transactions.
+   *
+   * **Not a liveness signal.** Nothing in the protocol evicts a crashed node from the
+   * net actor list, and `blockNumLiveness` is rewritten for every actor on every commit
+   * rather than per node, so it carries no health information at all. A node that died
+   * an hour ago still reads as processing here. The only way to learn a node is up is
+   * to talk to it.
+   */
+  readonly processing: boolean
+  /**
+   * `blockNumRemove` — the block at which this node's turn in the active set ends.
+   *
+   * Reset 100–355 blocks ahead each time the node is promoted, so it is a rotation
+   * deadline rather than a departure flag.
+   */
+  readonly retiresAtBlock: number
+  /**
+   * True when this node is inside its own shutdown window and will refuse work.
+   *
+   * The node's submit handler answers HTTP 503 `'Block chain is stopped'` once its
+   * `blockNumRemove` is less than its current block plus two, so this is knowable from
+   * the ledger before a transaction is ever built.
+   */
+  readonly retiring: boolean
+}

package/src/ledger/nft-records.ts

@@ -0,0 +1,49 @@
+import { Message } from 'capnp-ts'
+import { AppLayLedger as CapnpAppLayLedger } from '../capnp/appLayLedger.capnp'
+
+import { fromBase64, toBase64 } from '../encoding/base64'
+import { ledgerUnreadable } from '../errors'
+
+/** What the application layer ledger says one NFT stands for. */
+export interface NftRecordFacts {
+  readonly attestHash: Uint8Array
+  readonly metadata: readonly string[]
+}
+
+/**
+ * The NFT records in an application layer ledger, keyed by the NFT's base64 id.
+ *
+ * `source` is what a node's `result` holds for `type=all`: base64 packed Cap'n Proto, the
+ * same form as the validation layer ledger. Other application records are skipped. As
+ * with that ledger, the message is dropped once read.
+ */
+export function decodeNftRecords(source: string): Map<string, NftRecordFacts> {
+  const bytes = fromBase64(source, 'The application layer ledger')
+  const records = new Map<string, NftRecordFacts>()
+  const decoder = new TextDecoder()
+  try {
+    const ledger = new Message(bytes, true).getRoot(CapnpAppLayLedger)
+    for (const record of ledger.getAppLayRecs().toArray()) {
+      // `counterparty` is the union's zero value, so the arm is checked before it is read.
+      const recType = record.getRecType()
+      if (!recType.isNft() || !recType.hasNft()) continue
+      const data = recType.getNft().getAttestationSubgroup().getData()
+      const metadata = data
+        .getMetadata()
+        .toArray()
+        .sort((a, b) => a.getPosition() - b.getPosition())
+        .map((entry) => decoder.decode(new Uint8Array(entry.getItem().toArrayBuffer())))
+      records.set(toBase64(new Uint8Array(record.getAcctNumApp().toArrayBuffer())), {
+        attestHash: new Uint8Array(data.getAttestHash().toArrayBuffer()),
+        metadata,
+      })
+    }
+  } catch (cause) {
+    throw ledgerUnreadable(
+      'The application layer ledger could not be read. The node is probably running a ' +
+        'schema version this SDK does not know.',
+      cause,
+    )
+  }
+  return records
+}

package/src/ledger/params.ts

@@ -0,0 +1,82 @@
+import type { ParamAcctRec } from '../capnp/paramAcctRec.capnp'
+
+import { uint64ToPennies } from '../amount'
+import type { GeeqMetadataLimits } from '../types'
+
+/**
+ * Read the metadata limits a chain publishes in its parameter account list.
+ *
+ * `metadataVarNum` caps the NUMBER of entries and `metadataVarBytes` caps the bytes in
+ * ONE entry; there is no aggregate cap. The node enforces both at submit time, so
+ * having them here is what lets a transaction be rejected before it is signed rather
+ * than after it is sent.
+ *
+ * Returns `undefined` when either parameter is absent. A chain that does not publish
+ * them is a schema difference, not a caller error, so the preflight is skipped and the
+ * node stays the authority.
+ *
+ * `metadataFixedNum` / `metadataFixedBytes` exist in the schema but are read nowhere in
+ * the current node, so they are ignored here too.
+ */
+export function readMetadataLimits(
+  records: readonly ParamAcctRec[],
+): GeeqMetadataLimits | undefined {
+  let maxEntries: number | undefined
+  let maxBytesPerEntry: number | undefined
+
+  for (const record of records) {
+    const param = record.getParamType()
+    if (maxEntries === undefined && param.isMetadataVarNum() && param.hasMetadataVarNum()) {
+      maxEntries = param.getMetadataVarNum().getCurrentValue()
+      continue
+    }
+    if (
+      maxBytesPerEntry === undefined &&
+      param.isMetadataVarBytes() &&
+      param.hasMetadataVarBytes()
+    ) {
+      maxBytesPerEntry = param.getMetadataVarBytes().getCurrentValue()
+    }
+  }
+
+  if (maxEntries === undefined || maxBytesPerEntry === undefined) return undefined
+  return Object.freeze({ maxEntries, maxBytesPerEntry })
+}
+
+/**
+ * The smallest transfer this chain will accept, in pennies: `minTxAmt × geeqNorm + 1`.
+ *
+ * The node rejects anything below `minTxAmt × geeqNorm` (geeq_node_core, Transaction
+ * Amount Conformity); the Geeq wallet asks for one penny more, and so does this. Knowing
+ * it here turns a rejected transaction into a message before it is signed.
+ *
+ * Returns `undefined` when either parameter is missing, in which case nothing is checked
+ * and the node stays the authority.
+ */
+export function readMinimumTransfer(
+  records: readonly ParamAcctRec[],
+): bigint | undefined {
+  const geeqNorm = readGeeqNorm(records)
+  for (const record of records) {
+    const param = record.getParamType()
+    if (param.isMinTxAmt() && param.hasMinTxAmt()) {
+      if (geeqNorm === undefined) return undefined
+      return uint64ToPennies(param.getMinTxAmt().getCurrentValue()) * geeqNorm + 1n
+    }
+  }
+  return undefined
+}
+
+/**
+ * The chain's `geeqNorm` parameter: the multiplier behind its minimum transfer and every
+ * fee. `undefined` when the chain does not publish it.
+ */
+export function readGeeqNorm(records: readonly ParamAcctRec[]): bigint | undefined {
+  for (const record of records) {
+    const param = record.getParamType()
+    if (param.isGeeqNorm() && param.hasGeeqNorm()) {
+      return uint64ToPennies(param.getGeeqNorm().getCurrentValue())
+    }
+  }
+  return undefined
+}

package/src/ledger/proxy-accounts.ts

@@ -0,0 +1,51 @@
+import type { ProxyAcctRec } from '../capnp/proxyAcctRec.capnp'
+
+import { uint64ToPennies } from '../amount'
+
+/** Which kind of proxy a record is. Only `'nft-mint'` is read further. */
+export type GeeqProxyKind = 'nft-mint' | 'token-mint' | 'funding' | 'multisig' | 'dce' | 'unknown'
+
+/** One proxy account record, as plain values. */
+export interface GeeqProxyAccount {
+  readonly accountId: Uint8Array
+  readonly kind: GeeqProxyKind
+  /**
+   * The proxy's own nonce. A mint through it spends this one, not the admin's — a proxy
+   * carries its nonce on the record itself.
+   */
+  readonly nonce: number
+  /** Balance in pennies. Use `formatGeeq` to show it. */
+  readonly balance: bigint
+  /** The account id of the only key that can sign for it. Read for NFT mint proxies only. */
+  readonly admin: Uint8Array | undefined
+}
+
+/** What we keep per proxy. The id is the map key, so it is not repeated here. */
+export type ProxyAccountFacts = Omit<GeeqProxyAccount, 'accountId'>
+
+/**
+ * Read a proxy record's kind and admin.
+ *
+ * The same zero-value trap as a coin account: `DCE` is the union's zero value, so every
+ * arm is checked with `isX()` before anything is read from it.
+ */
+export function readProxyAccount(record: ProxyAcctRec): ProxyAccountFacts {
+  const recType = record.getRecType()
+  const nonce = record.getNonce()
+  const balance = uint64ToPennies(record.getAmtCoin())
+
+  if (recType.isNftMint() && recType.hasNftMint()) {
+    const admin = new Uint8Array(recType.getNftMint().getAcctNumAdminUser().toArrayBuffer())
+    return { kind: 'nft-mint', nonce, balance, admin }
+  }
+  const kind = recType.isTokenMint()
+    ? 'token-mint'
+    : recType.isFunding()
+      ? 'funding'
+      : recType.isMultisig()
+        ? 'multisig'
+        : recType.isDce() && recType.hasDce()
+          ? 'dce'
+          : 'unknown'
+  return { kind, nonce, balance, admin: undefined }
+}