@geeqdev/geeq-sdk 0.0.1 → 0.1.1

package/src/tx/transfer.ts

@@ -0,0 +1,162 @@
+import { blake3 } from '@noble/hashes/blake3'
+import { Message } from 'capnp-ts'
+import { UserValTx as CapnpUserValTx } from '../capnp/userValTx.capnp'
+
+import { assertUint32 } from '../assert'
+import { penniesToUint64 } from '../amount'
+import { ACCOUNT_ID_BYTES, PUBLIC_KEY_BYTES, resolveAccountId } from '../crypto/account-id'
+import type { AccountRef } from '../crypto/account-id'
+import { toBase64 } from '../encoding/base64'
+import { invalidArgument } from '../errors'
+import { WasmUserValTx, WasmUserValTxData } from '../runtime/bindings'
+import { assertReady, initGeeq } from '../runtime/init'
+import type { CoinTransferTx, CoinTransferTxInput, GeeqKeypair } from '../types'
+import {
+  REF_HASH_BYTES,
+  assertChainState,
+  assertKeypair,
+  flatten,
+  packed,
+  pinning,
+  resolveChainState,
+} from './encode'
+import { feeFor } from './fee'
+
+/**
+ * Sign a built validation-layer transaction and work out the id the node files it under.
+ * Every validation-layer transaction — a transfer, a proxy creation — ends this way.
+ *
+ * @internal
+ */
+export function signValidationTx(
+  message: Message,
+  tx: CapnpUserValTx,
+  keypair: GeeqKeypair,
+  what: string,
+): { transaction: string; transactionHash: Uint8Array; bytes: number } {
+  // A signature is a union here rather than a plain field, so it has to be told it is
+  // absent before it can be told what it is.
+  tx.initSignature().setNone()
+  tx.initEndorsements(0)
+
+  // Signed over the signature-EXCLUDED flatten, which is what the node verifies against.
+  const flattened = flatten(() => WasmUserValTxData.fromUserValTxCapnp(packed(message)), what)
+  const signature = keypair.sign(flattened)
+  tx.getSignature().initSome(signature.length)
+  tx.getSignature().getSome().copyBuffer(signature)
+
+  // The opposite of an attestation: the node identifies a validation-layer transaction by
+  // the hash of its signature-EXCLUDED flatten (geeq_node_core's UVT wrapper overrides
+  // computeRefHash with the no-signature form), and that is the value its uut_status
+  // events carry. Taken from the finished message rather than reusing the preimage, so
+  // it is computed exactly as the node computes it on receipt.
+  const transactionHash = blake3(
+    flatten(() => WasmUserValTxData.fromUserValTxCapnp(packed(message)), `signed ${what}`),
+    { dkLen: REF_HASH_BYTES },
+  )
+
+  // The fee, though, charges for the flatten WITH the signature: the node's data fee asks
+  // for that form whatever the transaction is identified by.
+  const signed = flatten(() => WasmUserValTx.fromUserValTxCapnp(packed(message)), `signed ${what}`)
+
+  return { transaction: toBase64(packed(message)), transactionHash, bytes: signed.length }
+}
+
+/**
+ * Build and sign a coin transfer. Synchronous; requires a loaded engine.
+ *
+ * Unlike an attestation this is a **validation layer** transaction: it carries no
+ * separate payload, so there is one base64 blob to submit rather than two, and it is
+ * posted as type `uvt`.
+ *
+ * NFTs ride along in the same transaction, with coin: the chain's minimum transfer
+ * applies even when the point is the NFTs.
+ *
+ * Offline — it opens no sockets and reads no ledger. It cannot check that the sender can
+ * afford the transfer, that the amount clears the chain's minimum, or that it holds the
+ * NFTs; all three need a ledger. {@link GeeqChain.createTransfer} does check them.
+ */
+export function createCoinTransferTxSync(input: CoinTransferTxInput): CoinTransferTx {
+  assertReady('createCoinTransferTxSync')
+
+  const { keypair } = input
+  assertKeypair(keypair)
+
+  const chainState = resolveChainState(input)
+  const { chainNumber, blockNumber, nodeNumber, nonce } = chainState
+  assertChainState(chainState)
+
+  const receiver = resolveAccountId(input.to as AccountRef)
+  if (toBase64(receiver) === toBase64(keypair.accountId)) {
+    throw invalidArgument(
+      'to is the sending account. A transfer to yourself moves nothing and still spends ' +
+        'a nonce and a fee.',
+    )
+  }
+
+  const pennies = input.amount
+  if (typeof pennies !== 'bigint') {
+    throw invalidArgument('amount must already be resolved to pennies as a bigint.')
+  }
+  if (pennies <= 0n) {
+    throw invalidArgument(`amount must be greater than zero, received ${pennies} pennies.`)
+  }
+
+  const nfts = input.nfts ?? []
+  for (const nft of nfts) {
+    if (!(nft.id instanceof Uint8Array) || nft.id.length !== ACCOUNT_ID_BYTES) {
+      throw invalidArgument(`An NFT id must be ${ACCOUNT_ID_BYTES} bytes.`)
+    }
+    assertUint32(nft.position, 'An NFT position')
+  }
+  if (new Set(nfts.map((nft) => toBase64(nft.id))).size !== nfts.length) {
+    throw invalidArgument('The same NFT is listed twice, and the chain refuses a transfer that does that.')
+  }
+
+  const message = new Message()
+  const tx = message.initRoot(CapnpUserValTx)
+
+  const data = tx.initData()
+  data.setChainNum(chainNumber)
+  data.setBlockNum(blockNumber)
+  data.setNodeNum(nodeNumber)
+
+  const asset = data.initTx().initCoin().initTxType().initAsset()
+  asset.setNonce(nonce)
+  asset.initAmtCoin().setSome(penniesToUint64(pennies))
+  // Both lists must exist even when empty, or the message is not well formed.
+  asset.initTokenAssetSubgroups(0)
+  const nftList = asset.initNftAssetSubgroups(nfts.length)
+  nfts.forEach((nft, index) => {
+    const entry = nftList.get(index)
+    entry.setPosition(nft.position)
+    const item = entry.initItem()
+    item.initAcctNumApp(ACCOUNT_ID_BYTES)
+    item.getAcctNumApp().copyBuffer(nft.id)
+  })
+  asset.initAcctNumRcv(ACCOUNT_ID_BYTES)
+  asset.getAcctNumRcv().copyBuffer(receiver)
+  asset.initPubKey(PUBLIC_KEY_BYTES)
+  asset.getPubKey().copyBuffer(keypair.publicKey)
+
+  const { transaction, transactionHash, bytes } = signValidationTx(message, tx, keypair, 'transfer')
+
+  return Object.freeze({
+    transaction,
+    transactionHash,
+    publicKey: keypair.publicKey,
+    amount: pennies,
+    nfts: Object.freeze(nfts.map((nft) => nft.id)),
+    to: receiver,
+    fee: feeFor(bytes, pennies, chainState.geeqNorm),
+    ...pinning(chainState),
+  })
+}
+
+/** Build and sign a coin transfer, loading the engine if needed. */
+export async function createCoinTransferTx(
+  input: CoinTransferTxInput,
+): Promise<CoinTransferTx> {
+  await initGeeq()
+  return createCoinTransferTxSync(input)
+}

package/src/types.ts

@@ -0,0 +1,503 @@
+import type { AccountRef } from './crypto/account-id'
+import type { GeeqHeldNft } from './ledger/coin-accounts'
+import type { GeeqProxyAccount } from './ledger/proxy-accounts'
+
+/**
+ * Where the WebAssembly engine should be loaded from. Leave it unset and the SDK
+ * uses the copy shipped beside its own bundle, which every common bundler emits
+ * as a hashed asset automatically.
+ */
+export type WasmSource =
+  | string
+  | URL
+  | Request
+  | Response
+  | ArrayBuffer
+  | Uint8Array
+  | WebAssembly.Module
+
+export interface InitOptions {
+  /** Override where `geeq_core_bg.wasm` is fetched from. */
+  readonly wasm?: WasmSource
+}
+
+/**
+ * The kind of ledger record an address points at. Most applications only ever
+ * need `'coin-asset'`, which is the default and is what a normal user account is.
+ */
+export type GeeqRecordType =
+  | 'coin-asset'
+  | 'coin-hl'
+  | 'coin-micro'
+  | 'app-counterparty'
+  | 'app-dce'
+  | 'app-nft'
+  | 'app-stackable'
+  | 'proxy-nft-mint'
+  | 'proxy-funding'
+  | 'proxy-multisig'
+  | 'proxy-dce'
+  | 'proxy-token-mint'
+  | 'gt-nwa'
+  | 'param-boolean'
+  | 'param-count-2'
+  | 'param-count-8'
+  | 'sys'
+
+/** Which coin family a derivation path belongs to. */
+export type GeeqCoinType = 'mainnet' | 'testnet'
+
+export interface WalletAddressOptions {
+  /** The chain this address belongs to. Addresses are not portable across chains. */
+  readonly chainNumber: number
+  /** Defaults to `'coin-asset'` — an ordinary user account. */
+  readonly recordType?: GeeqRecordType
+}
+
+export interface DecodedWalletAddress {
+  /** The address that was decoded, unchanged. */
+  readonly address: string
+  readonly chainNumber: number
+  readonly recordType: GeeqRecordType
+  /** The 32-byte account id this address points at. */
+  readonly accountId: Uint8Array
+}
+
+/** Options for deriving a keypair from a BIP-39 mnemonic along the Geeq path. */
+export interface MnemonicOptions {
+  /** Optional BIP-39 passphrase. Defaults to an empty string. */
+  readonly passphrase?: string
+  /** Defaults to `'coin-asset'`. */
+  readonly recordType?: GeeqRecordType
+  /** Defaults to `'mainnet'`. */
+  readonly coinType?: GeeqCoinType
+  /** Defaults to 0. */
+  readonly account?: number
+  /** Defaults to 0. */
+  readonly addressIndex?: number
+}
+
+/**
+ * An Ed25519 keypair plus the identifiers derived from it.
+ *
+ * `privateKey` is raw secret material. Never log it, never put it in an error
+ * message, and never send it anywhere. Call {@link GeeqKeypair.dispose} when done
+ * to release the engine-side copy.
+ */
+export interface GeeqKeypair {
+  /** 32-byte Ed25519 public key. */
+  readonly publicKey: Uint8Array
+  /** 32-byte Ed25519 secret key. Secret material. */
+  readonly privateKey: Uint8Array
+  /** 32-byte account id derived from the public key. */
+  readonly accountId: Uint8Array
+
+  /** The base58 wallet address for this keypair on a given chain. */
+  getAddress(options: WalletAddressOptions): string
+  /** Sign a message. Throws once {@link GeeqKeypair.dispose} has been called. */
+  sign(message: Uint8Array): Uint8Array
+  /** Release the engine-side keypair. The byte fields stay readable afterwards. */
+  dispose(): void
+}
+
+/** The metadata limits this chain publishes in its own ledger. */
+export interface GeeqMetadataLimits {
+  /** Maximum NUMBER of metadata entries. From the `metadataVarNum` parameter. */
+  readonly maxEntries: number
+  /** Maximum bytes in ONE entry. There is no aggregate cap. From `metadataVarBytes`. */
+  readonly maxBytesPerEntry: number
+}
+
+/**
+ * The live chain values a transaction is pinned to.
+ *
+ * `blockNumber` is the block being *asked for*, which is the ledger's last committed
+ * block plus one. Read it from a node with {@link GeeqChain}, or supply it yourself for
+ * replay and offline signing.
+ */
+export interface ChainStateInput {
+  /** The chain this transaction targets — the ledger's own chain number. */
+  readonly chainNumber: number
+  /** The block it asks to be included in: the ledger's block **+ 1**. */
+  readonly blockNumber: number
+  /** The receiving node's own number, from the net actor list in the ledger. */
+  readonly nodeNumber: number
+  /** The signing account's current nonce, from its coin account record. */
+  readonly nonce: number
+  /** When present, metadata is checked against it before anything is signed. */
+  readonly metadataLimits?: GeeqMetadataLimits | undefined
+  /**
+   * The chain's `geeqNorm` parameter, which every fee is a multiple of. When present, the
+   * built transaction carries its {@link GeeqFee}.
+   */
+  readonly geeqNorm?: bigint | undefined
+  /**
+   * The node this state describes, and therefore the only node that will accept a
+   * transaction built from it — `nodeNumber` is checked with strict equality.
+   */
+  readonly nodeUrl?: string | undefined
+  /**
+   * N, the ledger block this was read from. Present only when a chain produced it —
+   * there is nothing to report when the caller supplied the numbers.
+   */
+  readonly ledgerBlockNumber?: number | undefined
+  /** `Date.now()` at the read. Present only when a chain produced it. */
+  readonly readAt?: number | undefined
+}
+
+/**
+ * Chain state read from a node, carrying where and when it came from.
+ *
+ * The same fields as {@link ChainStateInput}, with the provenance ones narrowed from
+ * optional to always present — a chain can always say which ledger block and which node
+ * it read.
+ */
+export interface GeeqChainState extends ChainStateInput {
+  /** N — the ledger's last committed block. {@link blockNumber} is this plus one. */
+  readonly ledgerBlockNumber: number
+  /** `Date.now()` when the ledger was read, so callers can see how stale this is. */
+  readonly readAt: number
+  /** The node it was read from, and therefore the node it must be submitted to. */
+  readonly nodeUrl: string
+  /** The signing account's balance, in pennies, as at this read. */
+  readonly balance: bigint
+  /** The smallest transfer this chain accepts, in pennies, if it publishes one. */
+  readonly minimumTransfer: bigint | undefined
+  /** The chain's `geeqNorm` parameter, if it publishes one. */
+  readonly geeqNorm: bigint | undefined
+}
+
+/**
+ * What the chain charges for a transaction, in pennies, on top of any amount it sends.
+ *
+ * Worked out by the SDK the way the node works it out, from the signed bytes, so it is
+ * the exact figure rather than an estimate.
+ */
+export interface GeeqFee {
+  /** The whole fee: {@link data} plus {@link coin}. */
+  readonly total: bigint
+  /** `geeqNorm` per byte of the signed transaction, and of its payload when it has one. */
+  readonly data: bigint
+  /**
+   * A quarter of a percent of the amount sent, rounded down and capped at
+   * `geeqNorm × 10⁷`. Zero for an attestation, which sends no amount.
+   */
+  readonly coin: bigint
+  /** How many bytes {@link data} charges for. */
+  readonly bytes: number
+}
+
+/** What is being attested, independent of any chain state. */
+export interface AttestationContent {
+  /** The account that signs both the attestation and the transaction. */
+  readonly keypair: GeeqKeypair
+  /** 32-byte hash of the content. The content itself never leaves the device. */
+  readonly attestHash: Uint8Array
+  /**
+   * Optional labels stored alongside the hash, in the order given. Strings are encoded
+   * as UTF-8. Anything here is public once submitted.
+   */
+  readonly metadata?: readonly (string | Uint8Array)[]
+}
+
+/**
+ * The four chain values supplied explicitly.
+ *
+ * Kept for replay, deterministic tests and air-gapped signing, where there is no node
+ * to ask. Most callers should let {@link GeeqChain} read them instead — none of them can
+ * be derived offline, and a wrong one is rejected by the chain.
+ */
+export type AttestationTxFlatInput = AttestationContent & {
+  readonly chainNumber: number
+  readonly blockNumber: number
+  readonly nodeNumber: number
+  readonly nonce: number
+  readonly chainState?: never
+}
+
+/** The same four values as one object, which is what a chain read produces. */
+export type AttestationTxStateInput = AttestationContent & {
+  readonly chainState: ChainStateInput
+  readonly chainNumber?: never
+  readonly blockNumber?: never
+  readonly nodeNumber?: never
+  readonly nonce?: never
+}
+
+export type AttestationTxInput = AttestationTxFlatInput | AttestationTxStateInput
+
+/**
+ * A signed attestation transaction, ready to submit. The SDK does not submit it — post
+ * {@link AttestationTx.transaction} and {@link AttestationTx.payload} to the node named
+ * by {@link AttestationTx.nodeUrl}, after handing it to `GeeqSocket.track` to hear the
+ * verdict.
+ */
+export interface AttestationTx {
+  /** base64 packed `UserAppTx`. Submit as the `transaction` field. */
+  readonly transaction: string
+  /** base64 packed `Payload`. Submit as the `payload` field. */
+  readonly payload: string
+  /** 32-byte BLAKE3 of the flattened payload, as embedded in the transaction. */
+  readonly refHashPayload: Uint8Array
+  /**
+   * 32-byte BLAKE3 of the signed, flattened transaction — how a node identifies it, and
+   * the `refHash` its status events carry. `transactionIdOf(tx)` gives it as the base64
+   * string a {@link GeeqSocket} matches on.
+   */
+  readonly transactionHash: Uint8Array
+  /** The signer's 32-byte public key — whose status events to subscribe to. */
+  readonly publicKey: Uint8Array
+  /**
+   * What the chain charges the signing account for it. Undefined when the chain state
+   * carried no `geeqNorm`.
+   */
+  readonly fee: GeeqFee | undefined
+  /** Exactly what this transaction is pinned to. Frozen. */
+  readonly chainState: ChainStateInput
+  /**
+   * The last block a node takes it at: its target block plus 8. Once the chain's latest
+   * block is past this, every node refuses it as too old, and it has to be built and
+   * signed again. `GeeqChain.isExpired` checks.
+   */
+  readonly validUntilBlock: number
+  /**
+   * Where this must be submitted, when a chain read chose the node.
+   *
+   * Not a convenience: the node checks that `nodeNumber` is its own, with strict
+   * equality, so posting to any other node is a guaranteed rejection. Undefined only
+   * when the caller supplied the four values themselves and the SDK never saw a node.
+   */
+  readonly nodeUrl?: string | undefined
+}
+
+/** What is being transferred, independent of any chain state. */
+export interface CoinTransferContent {
+  /** The account paying. Must be a coin-asset account on this chain. */
+  readonly keypair: GeeqKeypair
+  /** Who receives it. Resolved to a 32-byte account id. */
+  readonly to: AccountRef
+  /**
+   * How much, in pennies. Use `toPennies` to get here from a figure. Never
+   * zero: the node reads a zero amount as the sender's whole balance.
+   */
+  readonly amount: bigint
+  /** NFTs sent with it. Each must be one the sender holds, named once. */
+  readonly nfts?: readonly NftTransferEntry[]
+}
+
+/** One NFT a transfer moves. */
+export interface NftTransferEntry {
+  /** The NFT's 32-byte id. */
+  readonly id: Uint8Array
+  /** Where it sits in the sender's list of NFTs, from 0 — as `GeeqCoinAccount.nfts` orders them. */
+  readonly position: number
+}
+
+/** The four chain values supplied explicitly. For replay and air-gapped signing. */
+export type CoinTransferTxFlatInput = CoinTransferContent & {
+  readonly chainNumber: number
+  readonly blockNumber: number
+  readonly nodeNumber: number
+  readonly nonce: number
+  readonly chainState?: never
+}
+
+/** The same four as one object, which is what a chain read produces. */
+export type CoinTransferTxStateInput = CoinTransferContent & {
+  readonly chainState: ChainStateInput
+  readonly chainNumber?: never
+  readonly blockNumber?: never
+  readonly nodeNumber?: never
+  readonly nonce?: never
+}
+
+export type CoinTransferTxInput = CoinTransferTxFlatInput | CoinTransferTxStateInput
+
+/**
+ * A signed coin transfer, ready to submit.
+ *
+ * Note there is no `payload`: a validation-layer transaction is self-contained, unlike an
+ * attestation. Post it with `coinTransferSubmitBody`, which sends it as type `uvt`, after
+ * handing it to `GeeqSocket.track` to hear the verdict.
+ */
+export interface CoinTransferTx {
+  /** base64 packed `UserValTx`. Submit as the `transaction` field. */
+  readonly transaction: string
+  /**
+   * 32-byte BLAKE3 of the flattened transaction **without** its signature — how the chain
+   * identifies a validation-layer transaction, and the `refHash` its status events carry.
+   * Note this is the opposite of an attestation, whose hash includes the signature.
+   */
+  readonly transactionHash: Uint8Array
+  /** The sender's 32-byte public key — whose status events to subscribe to. */
+  readonly publicKey: Uint8Array
+  /** What was sent, in pennies. */
+  readonly amount: bigint
+  /** The ids of the NFTs sent with it, if any. */
+  readonly nfts: readonly Uint8Array[]
+  /**
+   * What the chain charges the sender, on top of {@link amount}. Undefined when the chain
+   * state carried no `geeqNorm`.
+   */
+  readonly fee: GeeqFee | undefined
+  /** The 32-byte account id it was sent to. */
+  readonly to: Uint8Array
+  /** Exactly what this transaction is pinned to. Frozen. */
+  readonly chainState: ChainStateInput
+  /**
+   * The last block a node takes it at: its target block plus 8. Once the chain's latest
+   * block is past this, every node refuses it as too old, and it has to be built and
+   * signed again. `GeeqChain.isExpired` checks.
+   */
+  readonly validUntilBlock: number
+  /** Where it must be submitted, when a chain read chose the node. */
+  readonly nodeUrl?: string | undefined
+}
+
+/**
+ * What a proxy creation needs. The chain values come as one object only — there is no
+ * flat form, since a proxy is always built against a ledger read.
+ */
+export interface NftMintProxyTxInput {
+  /**
+   * The account paying for the proxy, which also becomes its admin: the only key that
+   * can later mint through it. Must be a coin-asset account on this chain.
+   */
+  readonly keypair: GeeqKeypair
+  /**
+   * Which of the admin's proxies this is, from 1. The proxy's id is derived from the
+   * admin's public key and this index, as the Geeq wallet derives it, so it must be one
+   * the admin has not used — `GeeqChain.findNftMintProxies` gives the next one.
+   */
+  readonly index: number
+  /** Coin moved onto the proxy, in pennies. It pays for the mints made through it. */
+  readonly amount: bigint
+  readonly chainState: ChainStateInput
+}
+
+/**
+ * A signed transaction creating an NFT mint proxy, ready to submit.
+ *
+ * A validation-layer transaction, like a transfer: post it with `coinTransferSubmitBody`,
+ * after handing it to `GeeqSocket.track` to hear the verdict.
+ */
+export interface NftMintProxyTx {
+  /** base64 packed `UserValTx`. Submit as the `transaction` field. */
+  readonly transaction: string
+  /** 32-byte BLAKE3 of the signature-excluded flatten — the `refHash` its status events carry. */
+  readonly transactionHash: Uint8Array
+  /** The admin's 32-byte public key — whose status events to subscribe to. */
+  readonly publicKey: Uint8Array
+  /** The coin moved onto the proxy, in pennies. */
+  readonly amount: bigint
+  /** Which of the admin's proxies this is, from 1. */
+  readonly index: number
+  /** The new proxy's 32-byte account id, derived from the admin's key and {@link index}. */
+  readonly proxyAccountId: Uint8Array
+  /** The new proxy's wallet address on this chain, record type `proxy-nft-mint`. */
+  readonly proxyAddress: string
+  /**
+   * What the chain charges the admin, on top of {@link amount}. Undefined when the chain
+   * state carried no `geeqNorm`.
+   */
+  readonly fee: GeeqFee | undefined
+  /** Exactly what this transaction is pinned to. Frozen. */
+  readonly chainState: ChainStateInput
+  /**
+   * The last block a node takes it at: its target block plus 8. Once the chain's latest
+   * block is past this, every node refuses it as too old, and it has to be built and
+   * signed again. `GeeqChain.isExpired` checks.
+   */
+  readonly validUntilBlock: number
+  /** Where it must be submitted, when a chain read chose the node. */
+  readonly nodeUrl?: string | undefined
+}
+
+/**
+ * What an NFT mint needs. The chain values come as one object only, as for a proxy.
+ */
+export interface NftMintTxInput {
+  /** The proxy's admin. It signs both the NFT and the transaction. */
+  readonly keypair: GeeqKeypair
+  /** The 32-byte account id of the proxy minting it, which pays for it. */
+  readonly proxyAccountId: Uint8Array
+  /** 32-byte hash of what the NFT stands for. The content itself never leaves the device. */
+  readonly attestHash: Uint8Array
+  /** Optional public labels stored with the NFT, in the order given. */
+  readonly metadata?: readonly (string | Uint8Array)[]
+  /** Who receives the NFT. Resolved to a 32-byte account id. */
+  readonly to: AccountRef
+  /** Coin the proxy sends to the receiver along with the NFT, in pennies. */
+  readonly amount: bigint
+  /** Its `nonce` is the proxy's own, not the admin's. */
+  readonly chainState: ChainStateInput
+}
+
+/**
+ * A signed NFT mint, ready to submit.
+ *
+ * An application-layer transaction, like an attestation: post `transaction` and `payload`
+ * with `attestationSubmitBody`, after handing it to `GeeqSocket.track` to hear the verdict.
+ */
+export interface NftMintTx {
+  /** base64 packed `UserAppTx`. Submit as the `transaction` field. */
+  readonly transaction: string
+  /** base64 packed `Payload`. Submit as the `payload` field. */
+  readonly payload: string
+  /** 32-byte BLAKE3 of the flattened payload, as embedded in the transaction. */
+  readonly refHashPayload: Uint8Array
+  /** 32-byte BLAKE3 of the signed, flattened transaction — the `refHash` its status events carry. */
+  readonly transactionHash: Uint8Array
+  /** The admin's 32-byte public key — whose status events to subscribe to. */
+  readonly publicKey: Uint8Array
+  /** The new NFT's 32-byte id: the hash of its attestation subgroup, as the wallet derives it. */
+  readonly nftId: Uint8Array
+  /** The proxy minting it. */
+  readonly proxyAccountId: Uint8Array
+  /** The 32-byte account id receiving it. */
+  readonly to: Uint8Array
+  /** The coin sent along with it, in pennies. */
+  readonly amount: bigint
+  /**
+   * What the chain charges the proxy — not the admin — on top of {@link amount}. Undefined
+   * when the chain state carried no `geeqNorm`.
+   */
+  readonly fee: GeeqFee | undefined
+  /** Exactly what this transaction is pinned to. Frozen. */
+  readonly chainState: ChainStateInput
+  /**
+   * The last block a node takes it at: its target block plus 8. Once the chain's latest
+   * block is past this, every node refuses it as too old, and it has to be built and
+   * signed again. `GeeqChain.isExpired` checks.
+   */
+  readonly validUntilBlock: number
+  /** Where it must be submitted, when a chain read chose the node. */
+  readonly nodeUrl?: string | undefined
+}
+
+/** One of an admin's NFT mint proxies, as the ledger holds it. */
+export interface GeeqNftMintProxy extends GeeqProxyAccount {
+  /**
+   * Which of the admin's proxies it is, from 1. Undefined for a proxy whose id was not
+   * derived from the admin's key — one made with an id of its own.
+   */
+  readonly index: number | undefined
+  /** Its wallet address on this chain, record type `proxy-nft-mint`. */
+  readonly address: string
+}
+
+/** The NFT mint proxies one admin has, and the index its next one takes. */
+export interface GeeqNftMintProxies {
+  /** In index order; any without an index come last. */
+  readonly proxies: readonly GeeqNftMintProxy[]
+  /** One past the highest index in use, or 1 when there is none. */
+  readonly nextIndex: number
+}
+
+/** An NFT an account holds, with the hash and labels it was minted with. */
+export interface GeeqNft extends GeeqHeldNft {
+  /** The hash of what it stands for. Undefined when the application layer ledger has no record of it. */
+  readonly attestHash: Uint8Array | undefined
+  /** Its public labels as text, in order. */
+  readonly metadata: readonly string[]
+}

package/src/wasm/README.md

@@ -0,0 +1,22 @@
+# Geeq WASM engine (vendored)
+
+The compiled Geeq core engine and its wasm-bindgen glue, copied verbatim from the `lib/`
+directory of the private `geeq_wasm_lib` repository so the SDK builds and publishes
+without Bitbucket access.
+
+| | |
+|---|---|
+| Source | `bitbucket.org/bigkraken5/geeq_wasm_lib`, branch `app15` |
+| Commit | `89159feeaee30affd2d23fdd9998086c94e14c74` |
+
+- `browser/` is the build the SDK ships. tsup bundles `geeq_core.js` into both the
+  browser and Node outputs, and `scripts/copy-wasm.mjs` puts `geeq_core_bg.wasm` beside them.
+- `nodejs/` is used only by tooling: Jest, which runs as CommonJS and cannot load the ESM
+  browser build (see `jest.config.js`), and `example/scripts/browser-check.mjs`. Its
+  `package.json` is ours, not upstream's: it marks the folder CommonJS, since the SDK's
+  own `package.json` declares `"type": "module"` and Node would otherwise refuse to load it.
+
+Do not edit these files by hand. To update, copy `lib/browser` and `lib/nodejs` from the
+new commit over these directories, update the commit above, and run `npm run typecheck`,
+`npm test` and `npm run build && npm run smoke`. The engine must match the protocol
+version of the Cap'n Proto schemas in `src/capnp`.