@geeqdev/geeq-sdk 0.1.0 → 0.2.0

package/src/chain/geeq-node.ts

@@ -0,0 +1,105 @@
+import type { GeeqLedger } from '../ledger/geeq-ledger'
+import type { GeeqNodeRole, GeeqNodeStatus } from '../ledger/net-actors'
+import { readLedger } from '../net/read-ledger'
+import { submitRoute } from '../net/routes'
+import type { GeeqTransport } from '../net/transport'
+
+/** @internal */
+export interface NodeRequestConfig {
+  readonly transport: GeeqTransport
+  readonly timeoutMs: number
+  readonly retries: number
+  readonly headers: Readonly<Record<string, string>> | undefined
+}
+
+/** @internal */
+export interface GeeqNodeInit extends NodeRequestConfig {
+  readonly url: string
+  readonly nodeNumber: number
+  readonly host: string
+  readonly port: number
+  readonly role: GeeqNodeRole
+  readonly status: GeeqNodeStatus
+  readonly processing: boolean
+}
+
+/**
+ * One node, identified in its own chain's ledger.
+ *
+ * A node is only meaningful once a ledger has confirmed which actor it is: the number a
+ * transaction must carry is the node's own `nodeNumSelf`, checked with strict equality,
+ * and nothing outside the ledger reports it.
+ */
+export class GeeqNode {
+  /** Absolute origin, no trailing slash. */
+  readonly url: string
+  /** `nodeNumSelf` — what a transaction targeting this node must name. */
+  readonly nodeNumber: number
+  /** The bare IP the ledger records for it. */
+  readonly host: string
+  /** Its own listen port from the ledger, which is not necessarily {@link url}'s. */
+  readonly port: number
+  readonly role: GeeqNodeRole
+  readonly status: GeeqNodeStatus
+  /** Whether it accepts transactions at all. */
+  readonly processing: boolean
+
+  // A TypeScript `private`, never a `#private`: a `#private` field is unreachable
+  // through a Proxy, which breaks Vue's ref() — the trap already documented on Keypair.
+  private readonly request!: NodeRequestConfig
+
+  /** @internal */
+  constructor(init: GeeqNodeInit) {
+    this.url = init.url
+    this.nodeNumber = init.nodeNumber
+    this.host = init.host
+    this.port = init.port
+    this.role = init.role
+    this.status = init.status
+    this.processing = init.processing
+    Object.defineProperty(this, 'request', {
+      value: Object.freeze({
+        transport: init.transport,
+        timeoutMs: init.timeoutMs,
+        retries: init.retries,
+        headers: init.headers,
+      }),
+      enumerable: false,
+      writable: false,
+    })
+  }
+
+  /**
+   * Where a transaction built for this node must be POSTed.
+   *
+   * The SDK does not submit. This exists so an application posts to the node the SDK
+   * actually read from, instead of keeping a second copy of the URL that can drift.
+   */
+  get submitUrl(): string {
+    return submitRoute(this.url)
+  }
+
+  /** Read this node's current ledger. No caching — {@link GeeqChain} owns that. */
+  async readLedger(options: { readonly signal?: AbortSignal } = {}): Promise<GeeqLedger> {
+    return readLedger(this.url, {
+      ...this.request,
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    })
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      url: this.url,
+      nodeNumber: this.nodeNumber,
+      host: this.host,
+      port: this.port,
+      role: this.role,
+      status: this.status,
+      processing: this.processing,
+    }
+  }
+
+  toString(): string {
+    return `GeeqNode(${this.nodeNumber} at ${this.url}, ${this.role}/${this.status})`
+  }
+}

package/src/chain/nonce-guard.ts

@@ -0,0 +1,73 @@
+import { nonceCollision } from '../errors'
+
+/**
+ * Stops one account producing two transactions against one block.
+ *
+ * The ledger only reflects committed blocks, so building twice inside a block interval
+ * derives the same nonce twice — and the node invalidates **every** transaction in a
+ * duplicate-nonce group rather than keeping the first
+ * (geeq_node_core/src/validations/workers/joint/checks/9.nonce.ts). The user would see
+ * one success and lose both.
+ *
+ * Auto-incrementing instead was considered and rejected. The node's full check requires
+ * nonces consecutive from the ledger's, so handing out n+1 and then submitting only that
+ * one leaves a permanent gap. Since this SDK does not submit, it never learns which
+ * transactions actually went out, so it cannot safely keep a counter. Refusing turns a
+ * silent double loss into an error naming the ways forward — and an application that
+ * knows a build was never sent hands its nonce back with {@link release}.
+ */
+export class NonceGuard {
+  /** Per account: the ledger block its last build was against, and that build's id. */
+  private readonly issued = new Map<string, { block: number; transaction: string }>()
+
+  /**
+   * Whether claiming now would collide, without recording anything.
+   *
+   * Lets a caller tell "this account already built against this block" apart from
+   * "the ledger we are looking at is simply out of date", which are the same thing from
+   * a cached read and very different from a fresh one.
+   */
+  wouldCollide(accountKey: string, ledgerBlock: number): boolean {
+    const previous = this.issued.get(accountKey)
+    return previous !== undefined && previous.block >= ledgerBlock
+  }
+
+  /**
+   * Record that `accountKey` is taking a nonce at `ledgerBlock`, for the transaction
+   * identified by `transaction`.
+   *
+   * @throws a `nonce-collision` GeeqError if it already took one at that block.
+   */
+  claim(accountKey: string, ledgerBlock: number, nonce: number, transaction: string): void {
+    const previous = this.issued.get(accountKey)
+
+    if (previous !== undefined && previous.block >= ledgerBlock) {
+      throw nonceCollision(
+        `This account already has a transaction built with nonce ${nonce} against ` +
+          `block ${previous.block}, and the ledger has not advanced past it. Two ` +
+          'transactions from one account sharing a nonce are both rejected, not just the ' +
+          'second. If the first was never sent, discard(tx) it and build again. Otherwise ' +
+          'submit it and wait for the next block, pass nonce: ' +
+          `${nonce + 1} explicitly if you mean to submit both together, or call ` +
+          'refresh() once the chain has moved on.',
+      )
+    }
+
+    this.issued.set(accountKey, { block: ledgerBlock, transaction })
+  }
+
+  /**
+   * Give back the nonce a transaction claimed, because it will never be sent. Nothing
+   * happens unless it is still its account's latest claim.
+   */
+  release(transaction: string): void {
+    for (const [accountKey, claim] of this.issued) {
+      if (claim.transaction === transaction) this.issued.delete(accountKey)
+    }
+  }
+
+  /** Forget every claim. For a key change, or after abandoning a built transaction. */
+  clear(): void {
+    this.issued.clear()
+  }
+}

package/src/chain/select.ts

@@ -0,0 +1,149 @@
+import { invalidArgument, nodeUnusable } from '../errors'
+import type { GeeqLedger } from '../ledger/geeq-ledger'
+import type { GeeqLedgerNode } from '../ledger/net-actors'
+
+/**
+ * The port every Geeq node answers client traffic on.
+ *
+ * Nodes terminate TLS on 2082 and that is the only client-facing port; an endpoint
+ * given without one is resolved to it rather than to the scheme's default, because a
+ * request to 443 would fail opaquely in a browser with no way to tell why.
+ */
+export const GEEQ_NODE_PORT = 2082
+
+/** The host part of a node URL, which is what the net actor list records. */
+export function hostOf(url: string | URL): string {
+  try {
+    return new URL(String(url)).hostname
+  } catch (cause) {
+    throw invalidArgument(
+      `endpoint must be an absolute URL such as https://1.2.3.4:2082, received ${JSON.stringify(String(url))}.`,
+      cause,
+    )
+  }
+}
+
+/** Normalise a node URL to an origin with no trailing slash, so it is safe to append to. */
+export function originOf(url: string | URL): string {
+  hostOf(url) // same validation, same message
+  const parsed = new URL(String(url))
+  const port = parsed.port === '' ? String(GEEQ_NODE_PORT) : parsed.port
+  return `${parsed.protocol}//${parsed.hostname}:${port}${parsed.pathname.replace(/\/+$/u, '')}`
+}
+
+/**
+ * Normalise an ordinary service URL, leaving its port exactly as given.
+ *
+ * Distinct from {@link originOf} on purpose: a node directory is a normal web service
+ * on whatever port it was deployed on, so filling in the Geeq node port would send
+ * every request to the wrong place.
+ */
+export function serviceOriginOf(url: string | URL): string {
+  hostOf(url)
+  const parsed = new URL(String(url))
+  return `${parsed.protocol}//${parsed.host}${parsed.pathname.replace(/\/+$/u, '')}`
+}
+
+function listAlternatives(ledger: GeeqLedger): string {
+  const processing = ledger.processingNodes.filter((node) => !node.retiring)
+  if (processing.length === 0) {
+    return 'This ledger lists no node that is currently processing transactions.'
+  }
+  const listed = processing
+    .map((node) => `${node.host} (node ${node.nodeNumber})`)
+    .join(', ')
+  return `Nodes in this ledger that are processing: ${listed}.`
+}
+
+function assertUsable(node: GeeqLedgerNode, ledger: GeeqLedger): GeeqLedgerNode {
+  if (!node.processing) {
+    // Name the role and status verbatim: they are what the operator sees too, and the
+    // node's own rejection ('not processing') says nothing about which is wrong.
+    const detail =
+      node.role === 'relay'
+        ? 'a relay registers no transaction handler at all'
+        : 'only anon-node, anchor-node or cert-node with status node or hub processes transactions'
+    throw nodeUnusable(
+      `Node ${node.nodeNumber} at ${node.host} is a ${node.role} with status ` +
+        `"${node.status}", so it will not accept this transaction — ${detail}. ` +
+        listAlternatives(ledger),
+    )
+  }
+
+  if (node.retiring) {
+    // The node checks its own rotation deadline before accepting anything and answers
+    // 503 'Block chain is stopped' once it is within two blocks of it. That is knowable
+    // here, and a 503 naming a stopped chain is a badly misleading thing to hand someone
+    // whose chain is running perfectly well.
+    throw nodeUnusable(
+      `Node ${node.nodeNumber} at ${node.host} leaves the active set at block ` +
+        `${node.retiresAtBlock} and the ledger is already at ${ledger.blockNumber}, so it ` +
+        'will answer 503 "Block chain is stopped" rather than accept a transaction. This ' +
+        `is the node rotating out, not the chain halting. ${listAlternatives(ledger)}`,
+    )
+  }
+
+  return node
+}
+
+export interface SelectNodeOptions {
+  /** Skip host matching entirely. Required behind a gateway or a DNS name. */
+  readonly nodeNumber?: number | undefined
+}
+
+/**
+ * Choose the net actor record that a transaction should name.
+ *
+ * Matching is on **host only**. A record's `port` is the node's own listen port, while
+ * a client reaches it through a proxy on another one, so requiring both to agree finds
+ * nothing on a correctly deployed chain. Port is used solely to disambiguate when one
+ * address carries several records.
+ *
+ * This never silently retargets. A different node means a different address, a
+ * different certificate, a different CORS origin and a different operator seeing the
+ * transaction, so an unusable node is reported with its alternatives and the caller
+ * decides.
+ */
+export function selectNode(
+  ledger: GeeqLedger,
+  endpoint: string | URL,
+  options: SelectNodeOptions = {},
+): GeeqLedgerNode {
+  if (options.nodeNumber !== undefined) {
+    const named = ledger.findNode({ nodeNumber: options.nodeNumber })
+    if (named === undefined) {
+      throw nodeUnusable(
+        `nodeNumber ${options.nodeNumber} is not in the net actor list of the ledger ` +
+          `served by ${String(endpoint)}, which lists ${ledger.nodes.length} records. ` +
+          listAlternatives(ledger),
+      )
+    }
+    return assertUsable(named, ledger)
+  }
+
+  const host = hostOf(endpoint)
+  const candidates = ledger.findNodes(host)
+
+  if (candidates.length === 0) {
+    // Almost always a hostname or a gateway: the list holds bare IPs and a browser
+    // cannot resolve a name to one, so there is nothing the SDK can infer here.
+    throw nodeUnusable(
+      `${host} is not in the net actor list of the ledger it served ` +
+        `(${ledger.nodes.length} records, none at that address). A node is matched by ` +
+        'its IP address, so a DNS name, a gateway or a proxy cannot be matched at all — ' +
+        `pass nodeNumber explicitly for those. ${listAlternatives(ledger)}`,
+    )
+  }
+
+  if (candidates.length === 1) return assertUsable(candidates[0] as GeeqLedgerNode, ledger)
+
+  const processing = candidates.filter((node) => node.processing && !node.retiring)
+  if (processing.length === 1) return processing[0] as GeeqLedgerNode
+
+  const numbers = candidates.map((node) => node.nodeNumber).join(', ')
+  throw nodeUnusable(
+    `${host} matches ${candidates.length} net actor records (node numbers ${numbers}) ` +
+      `and ${processing.length} of them are processing, so the SDK cannot choose. ` +
+      'Pass nodeNumber explicitly.',
+  )
+}

package/src/crypto/account-id.ts

@@ -0,0 +1,83 @@
+import { blake3 } from '@noble/hashes/blake3'
+import { invalidArgument, invalidKey } from '../errors'
+
+/** Account ids and public keys are both 32 bytes. */
+export const ACCOUNT_ID_BYTES = 32
+export const PUBLIC_KEY_BYTES = 32
+
+/**
+ * Any way of naming an account that does not need the engine.
+ *
+ * Structural on purpose: a {@link GeeqKeypair} already carries `accountId`, so it
+ * satisfies this without the crypto layer importing the keypair type and without the
+ * caller unwrapping anything.
+ */
+export type AccountRef =
+  | Uint8Array
+  | { readonly accountId: Uint8Array }
+  | { readonly publicKey: Uint8Array }
+
+/**
+ * Derive the 32-byte account id for a public key.
+ *
+ * This is a pure hash — it needs no engine and no network, so it works before
+ * {@link initGeeq} has resolved.
+ */
+export function accountIdFromPublicKey(publicKey: Uint8Array): Uint8Array {
+  if (publicKey.length !== PUBLIC_KEY_BYTES) {
+    throw invalidKey(
+      `A public key must be ${PUBLIC_KEY_BYTES} bytes, received ${publicKey.length}.`,
+    )
+  }
+  return blake3(publicKey, { dkLen: ACCOUNT_ID_BYTES })
+}
+
+/**
+ * Resolve any {@link AccountRef} to a 32-byte account id.
+ *
+ * Shared by the address layer and the ledger layer: both need to turn "whatever the
+ * caller had to hand" into the one value records are keyed by, and two copies of this
+ * would drift. Pure — no engine, no network.
+ *
+ * `accountId` is checked before `publicKey` so that a keypair, which carries both,
+ * takes the cheap path instead of re-hashing its own public key.
+ *
+ * @internal
+ */
+export function resolveAccountId(account: AccountRef): Uint8Array {
+  if (account instanceof Uint8Array) {
+    if (account.length !== ACCOUNT_ID_BYTES) {
+      throw invalidKey(
+        `An account id must be ${ACCOUNT_ID_BYTES} bytes, received ${account.length}.`,
+      )
+    }
+    return account
+  }
+
+  if (account !== null && typeof account === 'object') {
+    const { accountId } = account as { accountId?: unknown }
+    if (accountId !== undefined) {
+      if (!(accountId instanceof Uint8Array)) {
+        throw invalidKey('accountId must be a Uint8Array.')
+      }
+      if (accountId.length !== ACCOUNT_ID_BYTES) {
+        throw invalidKey(
+          `An account id must be ${ACCOUNT_ID_BYTES} bytes, received ${accountId.length}.`,
+        )
+      }
+      return accountId
+    }
+
+    const { publicKey } = account as { publicKey?: unknown }
+    if (publicKey !== undefined) {
+      if (!(publicKey instanceof Uint8Array)) {
+        throw invalidKey('publicKey must be a Uint8Array.')
+      }
+      return accountIdFromPublicKey(publicKey)
+    }
+  }
+
+  throw invalidArgument(
+    `Provide a keypair, a ${ACCOUNT_ID_BYTES}-byte accountId, or a ${PUBLIC_KEY_BYTES}-byte publicKey.`,
+  )
+}

package/src/crypto/keypair.ts

@@ -0,0 +1,221 @@
+import { toBase64 } from '../encoding/base64'
+import { invalidArgument, invalidKey } from '../errors'
+import { WasmKeypair, wasmVerify } from '../runtime/bindings'
+import { assertReady, initGeeq } from '../runtime/init'
+import { DEFAULT_RECORD_TYPE, toWasmCoinType, toWasmRecordType } from '../address/record-type'
+import { createWalletAddressSync } from '../address/wallet-address'
+import type {
+  GeeqKeypair,
+  MnemonicOptions,
+  WalletAddressOptions,
+} from '../types'
+import { PUBLIC_KEY_BYTES, accountIdFromPublicKey } from './account-id'
+import { normalizeMnemonic } from './mnemonic'
+
+const SECRET_KEY_BYTES = 32
+const SIGNATURE_BYTES = 64
+
+/**
+ * Wraps an engine-side keypair. The byte fields are copied out once at
+ * construction so the object stays fully readable after {@link dispose}, which
+ * only releases the engine handle used for signing.
+ */
+class Keypair implements GeeqKeypair {
+  readonly publicKey: Uint8Array
+  readonly privateKey: Uint8Array
+  readonly accountId: Uint8Array
+
+  /**
+   * The engine-side handle.
+   *
+   * Deliberately a plain non-enumerable property rather than a `#private` field:
+   * private fields are unreachable through a Proxy, so a keypair placed in
+   * proxy-based reactive state — Vue's `ref`/`reactive`, MobX, Valtio — would
+   * throw `TypeError: Cannot read from private field` on every method call.
+   * Non-enumerable keeps it out of spreads, `Object.keys` and devtools noise.
+   */
+  private handle: WasmKeypair | null
+
+  constructor(inner: WasmKeypair) {
+    this.handle = inner
+    Object.defineProperty(this, 'handle', { enumerable: false })
+    this.publicKey = inner.exportPublicKey()
+    this.privateKey = inner.exportSecretKey()
+    this.accountId = accountIdFromPublicKey(this.publicKey)
+  }
+
+  getAddress(options: WalletAddressOptions): string {
+    return createWalletAddressSync({
+      accountId: this.accountId,
+      chainNumber: options.chainNumber,
+      recordType: options.recordType ?? DEFAULT_RECORD_TYPE,
+    })
+  }
+
+  sign(message: Uint8Array): Uint8Array {
+    if (this.handle === null) {
+      throw invalidKey('This keypair has been disposed and can no longer sign.')
+    }
+    if (!(message instanceof Uint8Array)) {
+      throw invalidArgument('sign() expects a Uint8Array.')
+    }
+    return this.handle.sign(message)
+  }
+
+  dispose(): void {
+    this.handle?.free()
+    this.handle = null
+  }
+
+  /** Keeps secret material out of logs, `console.log` and error breadcrumbs. */
+  toJSON(): { readonly type: 'GeeqKeypair'; readonly publicKey: string } {
+    return { type: 'GeeqKeypair', publicKey: toBase64(this.publicKey) }
+  }
+
+  toString(): string {
+    return '[GeeqKeypair]'
+  }
+}
+
+function assertBytes(value: unknown, expected: number, label: string): Uint8Array {
+  if (!(value instanceof Uint8Array)) {
+    throw invalidKey(`${label} must be a Uint8Array.`)
+  }
+  if (value.length !== expected) {
+    throw invalidKey(`${label} must be ${expected} bytes, received ${value.length}.`)
+  }
+  return value
+}
+
+/** Create a brand new random keypair. Synchronous; requires a loaded engine. */
+export function generateKeypairSync(): GeeqKeypair {
+  assertReady('generateKeypairSync')
+  return new Keypair(WasmKeypair.generate())
+}
+
+/** Create a brand new random keypair, loading the engine if needed. */
+export async function generateKeypair(): Promise<GeeqKeypair> {
+  await initGeeq()
+  return generateKeypairSync()
+}
+
+/** Re-create a keypair from stored public and private key bytes. */
+export function importKeypairSync(publicKey: Uint8Array, privateKey: Uint8Array): GeeqKeypair {
+  assertReady('importKeypairSync')
+  assertBytes(publicKey, PUBLIC_KEY_BYTES, 'publicKey')
+  assertBytes(privateKey, SECRET_KEY_BYTES, 'privateKey')
+
+  let keypair: Keypair
+  try {
+    // Deliberately derived from the secret key rather than via the engine's
+    // import(), which accepts a mismatched pair and stores the given public key
+    // verbatim — yielding a keypair whose signatures the chain would reject.
+    keypair = new Keypair(WasmKeypair.fromSecretKey(privateKey))
+  } catch (cause) {
+    throw invalidKey('Could not import this keypair. Check the private key is correct.', cause)
+  }
+
+  if (!bytesEqual(keypair.publicKey, publicKey)) {
+    keypair.dispose()
+    throw invalidKey(
+      'publicKey does not match privateKey. Check the two halves came from the same keypair.',
+    )
+  }
+  return keypair
+}
+
+/** Re-create a keypair from stored key bytes, loading the engine if needed. */
+export async function importKeypair(
+  publicKey: Uint8Array,
+  privateKey: Uint8Array,
+): Promise<GeeqKeypair> {
+  await initGeeq()
+  return importKeypairSync(publicKey, privateKey)
+}
+
+/** Recover a keypair from its 32-byte secret key alone. */
+export function keypairFromSecretKeySync(privateKey: Uint8Array): GeeqKeypair {
+  assertReady('keypairFromSecretKeySync')
+  assertBytes(privateKey, SECRET_KEY_BYTES, 'privateKey')
+  try {
+    return new Keypair(WasmKeypair.fromSecretKey(privateKey))
+  } catch (cause) {
+    throw invalidKey('Could not derive a keypair from this secret key.', cause)
+  }
+}
+
+/** Recover a keypair from its secret key, loading the engine if needed. */
+export async function keypairFromSecretKey(privateKey: Uint8Array): Promise<GeeqKeypair> {
+  await initGeeq()
+  return keypairFromSecretKeySync(privateKey)
+}
+
+/**
+ * Derive a keypair from a BIP-39 mnemonic along Geeq's standard derivation path.
+ *
+ * The same mnemonic and options always produce the same keypair, so this is how a
+ * wallet is restored on another device.
+ */
+export function keypairFromMnemonicSync(
+  mnemonic: string,
+  options: MnemonicOptions = {},
+): GeeqKeypair {
+  assertReady('keypairFromMnemonicSync')
+
+  if (typeof mnemonic !== 'string' || mnemonic.trim().length === 0) {
+    throw invalidArgument('mnemonic must be a non-empty BIP-39 phrase.')
+  }
+  const account = options.account ?? 0
+  const addressIndex = options.addressIndex ?? 0
+  for (const [label, value] of [['account', account], ['addressIndex', addressIndex]] as const) {
+    if (!Number.isInteger(value) || value < 0 || value > 0x7fffffff) {
+      throw invalidArgument(`${label} must be an integer between 0 and 2147483647.`)
+    }
+  }
+
+  try {
+    return new Keypair(
+      WasmKeypair.tryFromMnemonicGeeqPath(
+        normalizeMnemonic(mnemonic),
+        options.passphrase ?? '',
+        toWasmRecordType(options.recordType ?? DEFAULT_RECORD_TYPE),
+        toWasmCoinType(options.coinType ?? 'mainnet'),
+        account,
+        addressIndex,
+      ),
+    )
+  } catch (cause) {
+    throw invalidKey(
+      'Could not derive a keypair from this mnemonic. Check the words and the passphrase.',
+      cause,
+    )
+  }
+}
+
+/** Derive a keypair from a mnemonic, loading the engine if needed. */
+export async function keypairFromMnemonic(
+  mnemonic: string,
+  options: MnemonicOptions = {},
+): Promise<GeeqKeypair> {
+  await initGeeq()
+  return keypairFromMnemonicSync(mnemonic, options)
+}
+
+/** Verify an Ed25519 signature. Requires a loaded engine. */
+export function verifySignature(
+  publicKey: Uint8Array,
+  signature: Uint8Array,
+  message: Uint8Array,
+): boolean {
+  assertReady('verifySignature')
+  assertBytes(publicKey, PUBLIC_KEY_BYTES, 'publicKey')
+  assertBytes(signature, SIGNATURE_BYTES, 'signature')
+  return wasmVerify(publicKey, signature, message)
+}
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i += 1) diff |= (a[i] as number) ^ (b[i] as number)
+  return diff === 0
+}