@geeqdev/geeq-sdk 0.1.0 → 0.1.1

package/src/socket/tracked-tx.ts

@@ -0,0 +1,319 @@
+import type { GeeqTxStatusEvent } from './tx-status'
+
+/** The node committed it. */
+export interface GeeqTxConfirmed {
+  readonly status: 'confirmed'
+  readonly id: string
+  /** The `valid` event that settled it. */
+  readonly event: GeeqTxStatusEvent
+  readonly at: Date
+}
+
+/**
+ * Why a transaction was rejected. Branch on this, never on {@link GeeqTxRejected.message}.
+ *
+ * - `invalid` — found wrong at commit, usually the nonce or the balance. The fee is still
+ *   charged.
+ * - `incorrectly-included` — carried by a node the chain judged dishonest. Not your fault.
+ * - `nonsane` — the receiving node refused it and dropped it.
+ * - `refused` — the node answered the submission with an error status. It never entered
+ *   a block and will produce no status event.
+ */
+export type GeeqTxRejectionReason = 'invalid' | 'incorrectly-included' | 'nonsane' | 'refused'
+
+export interface GeeqTxRejected {
+  readonly status: 'rejected'
+  readonly id: string
+  readonly reason: GeeqTxRejectionReason
+  /** The node's own words when it gave any. For display and support — never parse it. */
+  readonly message: string
+  /** The event that settled it. Undefined for a `refused` submission the socket never saw. */
+  readonly event: GeeqTxStatusEvent | undefined
+  /** The HTTP status of a `refused` submission, when the caller reported one. */
+  readonly httpStatus: number | undefined
+  readonly at: Date
+}
+
+/**
+ * No verdict, and none is coming to this handle.
+ *
+ * - `timeout` — nothing final arrived in time. **This is not a rejection**: statuses sent
+ *   while the socket was reconnecting are lost, so it may well have settled. Read the
+ *   ledger (has the account's nonce moved on?) before sending it again.
+ * - `closed` — the socket was disposed while it was pending.
+ * - `released` — the caller stopped tracking it.
+ */
+export type GeeqTxUnknownReason = 'timeout' | 'closed' | 'released'
+
+export interface GeeqTxUnknown {
+  readonly status: 'unknown'
+  readonly id: string
+  readonly reason: GeeqTxUnknownReason
+  readonly message: string
+  readonly at: Date
+}
+
+export type GeeqTxOutcome = GeeqTxConfirmed | GeeqTxRejected | GeeqTxUnknown
+
+/** `pending` until an outcome, then the outcome's own status. Never goes back. */
+export type GeeqTxState = 'pending' | GeeqTxOutcome['status']
+
+/** What a submission refusal looked like, for {@link GeeqTrackedTx.refused}. */
+export interface GeeqTxRefusal {
+  /** The HTTP status the node answered with. */
+  readonly status?: number
+  /** The node's `details`, or the body — whatever it said. */
+  readonly message?: string
+}
+
+/**
+ * Hand an error thrown by application code to the platform, without letting it stop the
+ * SDK delivering the same event to everyone else.
+ *
+ * @internal
+ */
+export function reportListenerError(error: unknown): void {
+  const report = (globalThis as { reportError?: (error: unknown) => void }).reportError
+  if (typeof report === 'function') report(error)
+  else console.error(error)
+}
+
+/** @internal */
+export interface TrackedTxInit {
+  readonly id: string
+  readonly timeoutMs: number
+  readonly nonsaneGraceMs: number
+  /** Called once, when it settles — the socket drops it from its table. */
+  readonly detach: () => void
+}
+
+/**
+ * One submitted transaction, followed to its verdict.
+ *
+ * Returned by {@link GeeqSocket.track}. It collapses the node's four verdicts, some of
+ * which arrive more than once and one of which is only usually final, into one of three
+ * outcomes an application can branch on — and it never rejects, because a rejected
+ * transaction is an answer, not a failure:
+ *
+ * ```ts
+ * const outcome = await tracked.settled()
+ * if (outcome.status === 'confirmed') …
+ * else if (outcome.status === 'rejected') show(outcome.reason, outcome.message)
+ * else checkLedgerBeforeRetrying()          // 'unknown'
+ * ```
+ *
+ * In a reactive framework, keep it raw (Vue's `markRaw`) and re-read `status` and
+ * `events` from {@link onChange}.
+ */
+export class GeeqTrackedTx {
+  /** The transaction's refHash, base64 — the same string status events carry. */
+  readonly id: string
+
+  // TS-private and non-enumerable, never `#private` — see GeeqNode for why.
+  private readonly received!: GeeqTxStatusEvent[]
+  private readonly listeners!: Set<(tx: GeeqTrackedTx) => void>
+  private readonly nonsaneGraceMs!: number
+  private readonly detach!: () => void
+  private readonly promise!: Promise<GeeqTxOutcome>
+  private readonly resolve!: (outcome: GeeqTxOutcome) => void
+  private current!: GeeqTxOutcome | undefined
+  private deadline!: ReturnType<typeof setTimeout> | null
+  private grace!: ReturnType<typeof setTimeout> | null
+
+  /** @internal */
+  constructor(init: TrackedTxInit) {
+    this.id = init.id
+
+    const hidden = (key: string, value: unknown, writable = false): void => {
+      Object.defineProperty(this, key, { value, enumerable: false, writable })
+    }
+    let resolve!: (outcome: GeeqTxOutcome) => void
+    const promise = new Promise<GeeqTxOutcome>((settle) => {
+      resolve = settle
+    })
+    hidden('received', [])
+    hidden('listeners', new Set())
+    hidden('nonsaneGraceMs', init.nonsaneGraceMs)
+    hidden('detach', init.detach)
+    hidden('promise', promise)
+    hidden('resolve', resolve)
+    hidden('current', undefined, true)
+    hidden('grace', null, true)
+    hidden(
+      'deadline',
+      init.timeoutMs > 0
+        ? setTimeout(() => {
+            this.finish({
+              status: 'unknown',
+              id: this.id,
+              reason: 'timeout',
+              message:
+                `No final status for transaction ${this.id} within ${init.timeoutMs}ms. ` +
+                'That is not a rejection: statuses sent while the socket was reconnecting ' +
+                'are lost. Check the ledger — whether the account nonce has moved on — ' +
+                'before sending it again.',
+              at: new Date(),
+            })
+          }, init.timeoutMs)
+        : null,
+      true,
+    )
+  }
+
+  /** `pending`, then `confirmed`, `rejected` or `unknown` — once, and for good. */
+  get status(): GeeqTxState {
+    return this.current?.status ?? 'pending'
+  }
+
+  /** The outcome, once there is one. */
+  get outcome(): GeeqTxOutcome | undefined {
+    return this.current
+  }
+
+  /** Every status event received for this transaction, oldest first. */
+  get events(): readonly GeeqTxStatusEvent[] {
+    return [...this.received]
+  }
+
+  /** Resolves with the outcome. Never rejects — see the class notes. */
+  settled(): Promise<GeeqTxOutcome> {
+    return this.promise
+  }
+
+  /**
+   * Call `listener` whenever an event arrives for this transaction or it settles.
+   *
+   * Returns the function that removes it. Read {@link status}, {@link events} and
+   * {@link outcome} inside; they are already up to date.
+   */
+  onChange(listener: (tx: GeeqTrackedTx) => void): () => void {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  /**
+   * Report that the node refused the submission — answered it with an error status.
+   *
+   * Settles it `rejected` at once. A refused transaction never reaches a block, so no
+   * status event would ever arrive to settle it, and waiting would only turn a clear
+   * answer into a timeout. Do **not** call this when the POST failed to arrive at all
+   * (a network error): the node may have it, so leave it tracked.
+   */
+  refused(refusal: GeeqTxRefusal = {}): void {
+    if (this.current !== undefined) return
+    const nonsane = this.received.find((event) => event.verdict === 'nonsane')
+    const said = refusal.message ?? nonsane?.error
+    this.finish({
+      status: 'rejected',
+      id: this.id,
+      reason: 'refused',
+      message:
+        said === undefined || said === ''
+          ? `The node refused transaction ${this.id}` +
+            (refusal.status === undefined ? '.' : ` with HTTP ${refusal.status}.`)
+          : said,
+      event: nonsane,
+      httpStatus: refusal.status,
+      at: new Date(),
+    })
+  }
+
+  /** Stop tracking. Settles `unknown` with reason `released` if it was still pending. */
+  release(): void {
+    this.abandon('released', `Tracking of transaction ${this.id} was released.`)
+  }
+
+  /** @internal Settle as unknown because the socket is going away, or on release. */
+  abandon(reason: 'closed' | 'released', message: string): void {
+    this.finish({ status: 'unknown', id: this.id, reason, message, at: new Date() })
+  }
+
+  /**
+   * @internal Take one status event for this transaction.
+   *
+   * The only place the protocol's rules live. First-event-wins would report false
+   * failures: a `nonsane` can be followed by a real verdict when a node carries its buffer
+   * over a restart, so it only settles if nothing final follows within the grace window.
+   * Everything after the outcome — a second node's copy, a duplicate — is ignored.
+   */
+  receive(event: GeeqTxStatusEvent): void {
+    if (this.current !== undefined) return
+    this.received.push(event)
+
+    if (event.verdict === 'nonsane') {
+      if (this.grace === null) {
+        this.grace = setTimeout(() => {
+          this.finish({
+            status: 'rejected',
+            id: this.id,
+            reason: 'nonsane',
+            message: event.error ?? 'The node refused this transaction.',
+            event,
+            httpStatus: undefined,
+            at: new Date(),
+          })
+        }, this.nonsaneGraceMs)
+      }
+      this.notify()
+      return
+    }
+
+    if (event.verdict === 'valid') {
+      this.finish({ status: 'confirmed', id: this.id, event, at: new Date() })
+      return
+    }
+
+    this.finish({
+      status: 'rejected',
+      id: this.id,
+      reason: event.verdict === 'invalid' ? 'invalid' : 'incorrectly-included',
+      message:
+        event.error ??
+        (event.verdict === 'invalid'
+          ? 'The chain found this transaction invalid when committing the block.'
+          : 'This transaction was carried by a node the chain judged dishonest.'),
+      event,
+      httpStatus: undefined,
+      at: new Date(),
+    })
+  }
+
+  private finish(outcome: GeeqTxOutcome): void {
+    if (this.current !== undefined) return
+    this.current = Object.freeze(outcome)
+    if (this.deadline !== null) clearTimeout(this.deadline)
+    if (this.grace !== null) clearTimeout(this.grace)
+    this.deadline = null
+    this.grace = null
+    this.detach()
+    this.resolve(this.current)
+    this.notify()
+  }
+
+  private notify(): void {
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(this)
+      } catch (error) {
+        reportListenerError(error)
+      }
+    }
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      id: this.id,
+      status: this.status,
+      events: this.received.map((event) => event.verdict),
+      ...(this.current?.status === 'rejected' || this.current?.status === 'unknown'
+        ? { reason: this.current.reason }
+        : {}),
+    }
+  }
+
+  toString(): string {
+    return `GeeqTrackedTx(${this.id}, ${this.status})`
+  }
+}

package/src/socket/tx-status.ts

@@ -0,0 +1,131 @@
+import { toBase64 } from '../encoding/base64'
+
+/**
+ * The four verdicts a node reports for a transaction, by their protocol names.
+ *
+ * - `valid` — committed in a block. Final.
+ * - `invalid` — placed in a block's invalid list, typically a nonce or solvency failure
+ *   found at commit. Final, and **the sender is still charged the fee**.
+ * - `incorrectlyIncluded` — carried by a node the chain judged dishonest. Final; not the
+ *   sender's fault.
+ * - `nonsane` — refused by the receiving node, at intake (alongside an HTTP 400) or at block
+ *   selection (after a 200). The node drops it, so it is final in practice — but a node
+ *   restarting can carry its buffer forward, and then a later verdict follows.
+ *
+ * From geeq_node_core `UutStatuses` (actors/interfaces.ts).
+ */
+export type GeeqTxVerdict = 'nonsane' | 'incorrectlyIncluded' | 'invalid' | 'valid'
+
+/** The wire carries names, but the node's own enum is numbered; accept either. */
+const VERDICTS: readonly GeeqTxVerdict[] = [
+  'nonsane',
+  'incorrectlyIncluded',
+  'invalid',
+  'valid',
+]
+
+/**
+ * One `uut_status` event, normalised.
+ *
+ * Every field is what the node sent, renamed only where the wire name misleads. Nothing
+ * is inferred: in particular `vlbBlock` is passed through as reported and not treated as
+ * the inclusion block, because on current nodes it is one ahead of it for `valid` and
+ * `invalid` events.
+ */
+export interface GeeqTxStatusEvent {
+  /**
+   * The transaction's refHash, standard base64 — compare it with `transactionIdOf(tx)`.
+   * Always the transaction hash, never the payload hash.
+   */
+  readonly id: string
+  readonly verdict: GeeqTxVerdict
+  /** The node's own boolean: true exactly when `verdict` is `valid`. */
+  readonly isValid: boolean
+  /** The node's reason, verbatim. Empty when valid. Show it; never parse it. */
+  readonly error: string | undefined
+  /** The transaction's own target block, as the node reports it. */
+  readonly blockNumber: number | undefined
+  /** The node's `vlbBlock`, as reported. See the note above before relying on it. */
+  readonly vlbBlock: number | undefined
+  /**
+   * `outgoing` on the sender's copy, `incoming` on the receiver's, when the node says —
+   * older nodes do not. Do not use it to tell your own transactions apart: match on
+   * {@link id} instead.
+   */
+  readonly direction: 'incoming' | 'outgoing' | undefined
+  /** The signer's base64 public key. */
+  readonly signer: string | undefined
+  /** When the node stamped it. Second precision. */
+  readonly createdAt: Date | undefined
+  /** The event's payload exactly as it arrived, for logging and support. */
+  readonly raw: unknown
+}
+
+function optionalNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+function verdictOf(value: unknown): GeeqTxVerdict | undefined {
+  if (typeof value === 'number') return VERDICTS[value]
+  if (typeof value === 'string') {
+    return VERDICTS.find((verdict) => verdict === value)
+  }
+  return undefined
+}
+
+/** The node renders timestamps as `Date:<Date#toString()>`. */
+function dateOf(value: unknown): Date | undefined {
+  if (typeof value !== 'string') return undefined
+  const parsed = Date.parse(value.replace(/^Date:/u, ''))
+  return Number.isNaN(parsed) ? undefined : new Date(parsed)
+}
+
+/**
+ * Read a `uut_status` payload, or `undefined` when it is not one this SDK understands.
+ *
+ * Tolerant of the shapes nodes have actually sent: `publicKeys` as an array or the older
+ * single `publicKey`, the verdict as a name or as the node's enum number.
+ *
+ * @internal
+ */
+export function parseTxStatus(payload: unknown): GeeqTxStatusEvent | undefined {
+  if (payload === null || typeof payload !== 'object') return undefined
+  const fields = payload as Record<string, unknown>
+
+  const id = fields.refHash
+  const verdict = verdictOf(fields.status)
+  if (typeof id !== 'string' || id === '' || verdict === undefined) return undefined
+
+  const keys = fields.publicKeys
+  const signer = Array.isArray(keys)
+    ? keys.find((key): key is string => typeof key === 'string')
+    : typeof fields.publicKey === 'string'
+      ? fields.publicKey
+      : undefined
+
+  const direction =
+    fields.type === 'incoming' || fields.type === 'outgoing' ? fields.type : undefined
+
+  return Object.freeze({
+    id,
+    verdict,
+    isValid: typeof fields.isValid === 'boolean' ? fields.isValid : verdict === 'valid',
+    error: typeof fields.error === 'string' && fields.error !== '' ? fields.error : undefined,
+    blockNumber: optionalNumber(fields.blockNumber),
+    vlbBlock: optionalNumber(fields.vlbBlock),
+    direction,
+    signer,
+    createdAt: dateOf(fields.createdAt),
+    raw: payload,
+  })
+}
+
+/**
+ * A transaction's id as status events name it: its `transactionHash`, in base64.
+ *
+ * Works on anything the SDK builds — an attestation or a transfer — because each already
+ * carries the hash its kind is identified by, and the two kinds are hashed differently.
+ */
+export function transactionIdOf(tx: { readonly transactionHash: Uint8Array }): string {
+  return toBase64(tx.transactionHash)
+}

package/src/tx/attestation.ts

@@ -0,0 +1,222 @@
+import { blake3 } from '@noble/hashes/blake3'
+import { Message } from 'capnp-ts'
+import {
+  AttestationSubgroup as CapnpAttestationSubgroup,
+  Payload as CapnpPayload,
+} from '../capnp/payload.capnp'
+import { UserAppTx as CapnpUserAppTx } from '../capnp/userAppTx.capnp'
+
+import { toBase64 } from '../encoding/base64'
+import { assertMetadataWithinLimits, encodeMetadata } from './metadata'
+import { ATTEST_HASH_BYTES, assertAttestHash } from './content'
+import {
+  REF_HASH_BYTES,
+  assertChainState,
+  assertKeypair,
+  flatten,
+  packed,
+  pinning,
+  resolveChainState,
+} from './encode'
+import { feeFor } from './fee'
+import {
+  WasmAttestationSubgroupData,
+  WasmPayload,
+  WasmUserAppTx,
+  WasmUserAppTxData,
+} from '../runtime/bindings'
+import { assertReady, initGeeq } from '../runtime/init'
+import { ACCOUNT_ID_BYTES, PUBLIC_KEY_BYTES } from '../crypto/account-id'
+import type { AttestationTx, AttestationTxInput, GeeqKeypair } from '../types'
+
+/**
+ * Build and sign an attestation subgroup: a hash, its labels, and the account vouching
+ * for them. An attestation and an NFT mint carry the same subgroup; it names the signer's
+ * own account in one and the minting proxy in the other.
+ *
+ * Also returns the signature-excluded flatten — what was signed, and what an NFT's id is
+ * the hash of.
+ *
+ * @internal
+ */
+export function signAttestationSubgroup(input: {
+  readonly keypair: GeeqKeypair
+  readonly attestHash: Uint8Array
+  readonly metadata: readonly Uint8Array[]
+  readonly chainNumber: number
+  readonly accountId: Uint8Array
+}): { subgroup: CapnpAttestationSubgroup; flattened: Uint8Array } {
+  const { keypair, attestHash, metadata } = input
+
+  const message = new Message()
+  const subgroup = message.initRoot(CapnpAttestationSubgroup)
+  const data = subgroup.initData()
+  data.setChainNum(input.chainNumber)
+  data.initAttestHash(ATTEST_HASH_BYTES)
+  data.getAttestHash().copyBuffer(attestHash)
+  data.initAcctNumVal(ACCOUNT_ID_BYTES)
+  data.getAcctNumVal().copyBuffer(input.accountId)
+  data.initPubKey(PUBLIC_KEY_BYTES)
+  data.getPubKey().copyBuffer(keypair.publicKey)
+
+  data.initMetadata(metadata.length)
+  const metadataList = data.getMetadata()
+  metadata.forEach((item, index) => {
+    const entry = metadataList.get(index)
+    // Subgroup positions are 1-based throughout the protocol, so the first label is
+    // position 1. The node sorts by this field on read, which is what preserves the
+    // order the caller gave.
+    entry.setPosition(index + 1)
+    entry.initItem(item.length)
+    entry.getItem().copyBuffer(item)
+  })
+
+  // The subgroup is signed over its data alone, before the signature field exists.
+  const flattened = flatten(
+    () => WasmAttestationSubgroupData.fromAttestationSubgroupCapnp(packed(message)),
+    'attestation subgroup',
+  )
+  const signature = keypair.sign(flattened)
+  subgroup.initSignature(signature.length)
+  subgroup.getSignature().copyBuffer(signature)
+
+  return { subgroup, flattened }
+}
+
+/**
+ * A payload as it is submitted, the hash its transaction references it by, and its
+ * flattened size, which the fee charges for.
+ *
+ * @internal
+ */
+export function packPayload(message: Message): {
+  payload: string
+  refHashPayload: Uint8Array
+  bytes: number
+} {
+  const flattened = flatten(() => WasmPayload.fromPayloadCapnp(packed(message)), 'payload')
+  return {
+    payload: toBase64(packed(message)),
+    refHashPayload: blake3(flattened, { dkLen: REF_HASH_BYTES }),
+    bytes: flattened.length,
+  }
+}
+
+/**
+ * Sign a built application-layer transaction and work out the id the node files it under.
+ * Every application-layer transaction — an attestation, an NFT mint — ends this way.
+ *
+ * @internal
+ */
+export function signAppTx(
+  message: Message,
+  tx: CapnpUserAppTx,
+  keypair: GeeqKeypair,
+): { transaction: string; transactionHash: Uint8Array; bytes: number } {
+  // Signed over the signature-EXCLUDED flatten. The node verifies against exactly this
+  // form: its flatten worker swaps in the `…Data` class whenever the signature is left
+  // out, and its signature check asks for the flatten without one.
+  const flattened = flatten(
+    () => WasmUserAppTxData.fromUserAppTxCapnp(packed(message)),
+    'transaction',
+  )
+  const signature = keypair.sign(flattened)
+  tx.initSignature(signature.length)
+  tx.getSignature().copyBuffer(signature)
+
+  // The chain identifies a transaction by the hash of its signature-INCLUDED flatten —
+  // that is the value its status events carry. Hashing the signing preimage instead
+  // yields a plausible-looking 32 bytes that no node has ever heard of, so this has to
+  // happen after the signature is attached, and through the non-Data class. The same
+  // flatten is what the fee charges for.
+  const signed = flatten(
+    () => WasmUserAppTx.fromUserAppTxCapnp(packed(message)),
+    'signed transaction',
+  )
+
+  return {
+    transaction: toBase64(packed(message)),
+    transactionHash: blake3(signed, { dkLen: REF_HASH_BYTES }),
+    bytes: signed.length,
+  }
+}
+
+/**
+ * Build and sign an attestation transaction. Synchronous; requires a loaded engine.
+ *
+ * This function is offline: it opens no sockets and reads no ledger. It needs chain
+ * state that only a node can supply, so either pass the four values yourself or let
+ * {@link GeeqChain} read them and hand you a `chainState`.
+ *
+ * The transaction is signed but **not submitted**. Post
+ * {@link AttestationTx.transaction} and {@link AttestationTx.payload} to the node named
+ * by {@link AttestationTx.nodeUrl}.
+ */
+export function createAttestationTxSync(input: AttestationTxInput): AttestationTx {
+  assertReady('createAttestationTxSync')
+
+  const { keypair, attestHash } = input
+  const chainState = resolveChainState(input)
+  const { chainNumber, blockNumber, nodeNumber, nonce } = chainState
+
+  assertKeypair(keypair)
+  assertAttestHash(attestHash)
+  assertChainState(chainState)
+
+  const metadata = encodeMetadata(input.metadata)
+  assertMetadataWithinLimits(metadata, chainState.metadataLimits, { chainNumber, blockNumber })
+
+  // 1. The attestation subgroup: what is being attested, and by whom. The account's
+  //    identifying record number is the BLAKE3 of its public key, which is exactly the
+  //    account id the keypair already carries.
+  const { subgroup } = signAttestationSubgroup({
+    keypair,
+    attestHash,
+    metadata,
+    chainNumber,
+    accountId: keypair.accountId,
+  })
+
+  // 2. The payload carries the signed subgroup.
+  const payloadMessage = new Message()
+  const payloadRoot = payloadMessage.initRoot(CapnpPayload)
+  payloadRoot.initTxType().initAttestCommit()
+  payloadRoot.getTxType().getAttestCommit().setAttestationSubgroup(subgroup)
+  const { payload, refHashPayload, bytes: payloadBytes } = packPayload(payloadMessage)
+
+  // 3. The transaction references the payload by hash rather than carrying it, and
+  //    names the block and node that should process it.
+  const txMessage = new Message()
+  const tx = txMessage.initRoot(CapnpUserAppTx)
+  const txData = tx.getData()
+  txData.initTxType().initAttestCommit()
+  txData.getTxType().getAttestCommit().initAcctNumVal().setNone()
+  txData.setChainNum(chainNumber)
+  txData.setBlockNum(blockNumber)
+  txData.setNodeNum(nodeNumber)
+  txData.setNonce(nonce)
+  txData.initRefHashPayload(refHashPayload.length)
+  txData.getRefHashPayload().copyBuffer(refHashPayload)
+  txData.initPubKey(PUBLIC_KEY_BYTES)
+  txData.getPubKey().copyBuffer(keypair.publicKey)
+
+  const { transaction, transactionHash, bytes } = signAppTx(txMessage, tx, keypair)
+
+  return Object.freeze({
+    transaction,
+    payload,
+    refHashPayload,
+    transactionHash,
+    publicKey: keypair.publicKey,
+    // An attestation sends no coin, so it pays only for its bytes: the transaction's and
+    // the payload's.
+    fee: feeFor(bytes + payloadBytes, 0n, chainState.geeqNorm),
+    ...pinning(chainState),
+  })
+}
+
+/** Build and sign an attestation transaction, loading the engine if needed. */
+export async function createAttestationTx(input: AttestationTxInput): Promise<AttestationTx> {
+  await initGeeq()
+  return createAttestationTxSync(input)
+}