@geeqdev/geeq-sdk 0.1.0 → 0.1.1

package/src/net/discovery.ts

@@ -0,0 +1,231 @@
+import { invalidArgument, nodeUnusable } from '../errors'
+import { GEEQ_NODE_PORT } from '../chain/select'
+import { chainsRoute, nodesRoute } from './routes'
+import type { RequestOptions } from './transport'
+import { requestText } from './transport'
+
+/** How the directory classifies a node. Only `'active'` processes transactions. */
+export type GeeqNodeKind = 'active' | 'relay' | 'listener' | 'chain-admin' | 'none' | 'unknown'
+
+/** One chain the directory knows about. */
+export interface GeeqDiscoveredChain {
+  /** The directory's own row id, which every other directory route calls `systemId`. */
+  readonly systemId: number
+  /** The protocol chain number — what a transaction carries and a node checks. */
+  readonly chainNumber: number
+  readonly name: string | undefined
+}
+
+/**
+ * One node the directory knows about.
+ *
+ * Note what is **missing**: a node number. The directory can say where a node is but
+ * not who it is in the chain's own net actor list, so the ledger read is still the only
+ * way to learn the number a transaction must carry.
+ */
+export interface GeeqDiscoveredNode {
+  readonly host: string
+  readonly kind: GeeqNodeKind
+  /** The directory's own lifecycle state — `new`, `ready`, `stopped`. */
+  readonly status: string
+  /** Where to reach it. Always the client port; the directory's own port is internal. */
+  readonly url: string
+}
+
+const KINDS: ReadonlySet<string> = new Set([
+  'active',
+  'relay',
+  'listener',
+  'chain-admin',
+  'none',
+])
+
+function resultOf(body: string, url: string): unknown[] {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(body)
+  } catch (cause) {
+    throw nodeUnusable(
+      `The directory at ${url} did not answer with JSON. A proxy or login page in front ` +
+        'of it is the usual reason.',
+      cause,
+    )
+  }
+  const result = (parsed as { result?: unknown })?.result
+  if (!Array.isArray(result)) {
+    throw nodeUnusable(
+      `The directory at ${url} answered without a "result" array, so it does not look ` +
+        'like a Geeq node directory.',
+    )
+  }
+  return result
+}
+
+/** Every chain the directory knows about. */
+export async function listChains(
+  origin: string,
+  request: RequestOptions,
+): Promise<GeeqDiscoveredChain[]> {
+  const url = chainsRoute(origin)
+  const rows = resultOf(await requestText(url, request), url)
+
+  return rows
+    .map((row) => row as { id?: unknown; chainNumber?: unknown; name?: unknown })
+    .filter((row) => typeof row.id === 'number' && typeof row.chainNumber === 'number')
+    .map((row) =>
+      Object.freeze({
+        systemId: row.id as number,
+        chainNumber: row.chainNumber as number,
+        name: typeof row.name === 'string' ? row.name : undefined,
+      }),
+    )
+}
+
+export interface NodeAddressing {
+  /** Scheme for the node URLs. Defaults to the directory's own. */
+  readonly protocol?: string | undefined
+  /** Client port. Defaults to {@link GEEQ_NODE_PORT}; override only for local setups. */
+  readonly port?: number | undefined
+}
+
+/** Every node the directory lists for one chain. */
+export async function listNodes(
+  origin: string,
+  systemId: number,
+  request: RequestOptions,
+  addressing: NodeAddressing = {},
+): Promise<GeeqDiscoveredNode[]> {
+  const protocol = addressing.protocol ?? new URL(origin).protocol
+  const port = addressing.port ?? GEEQ_NODE_PORT
+  const url = nodesRoute(origin, systemId)
+  const rows = resultOf(await requestText(url, request), url)
+
+  return rows
+    .map((row) => row as { ip?: unknown; type?: unknown; status?: unknown })
+    .filter((row) => typeof row.ip === 'string' && row.ip !== '')
+    .map((row) => {
+      const kind = typeof row.type === 'string' && KINDS.has(row.type) ? row.type : 'unknown'
+      return Object.freeze({
+        host: row.ip as string,
+        kind: kind as GeeqNodeKind,
+        status: typeof row.status === 'string' ? row.status : 'unknown',
+        // The directory reports the node's own internal listener, which is not where
+        // clients connect, so its port field is deliberately ignored in favour of the
+        // one port every node answers on.
+        url: `${protocol}//${row.ip as string}:${port}`,
+      })
+    })
+}
+
+export interface DiscoverOptions extends NodeAddressing {
+  readonly origin: string
+  /** Select the chain by the name the directory gives it. Matched case-insensitively. */
+  readonly chainName?: string | undefined
+  /** Select by protocol chain number, or — alongside `chainName` — assert it. */
+  readonly chainNumber?: number | undefined
+  readonly request: RequestOptions
+}
+
+export interface Discovery {
+  readonly chain: GeeqDiscoveredChain
+  /** Every node listed for the chain, in directory order. */
+  readonly nodes: readonly GeeqDiscoveredNode[]
+  /** Those that will actually take a transaction. */
+  readonly usable: readonly GeeqDiscoveredNode[]
+}
+
+/** True when the directory says this node is an active one that has not been stopped. */
+export function isUsable(node: GeeqDiscoveredNode): boolean {
+  return node.kind === 'active' && node.status !== 'stopped'
+}
+
+/**
+ * Find a chain in the directory and list its nodes.
+ *
+ * This reads two routes and nothing else. The directory is a deployment control plane:
+ * it has no authentication, and its other routes create and destroy machines and serve
+ * private keys. Treat every value it returns as a hint about *where* to look, never as
+ * authority about the chain itself — that comes from the ledger.
+ */
+export async function discover(options: DiscoverOptions): Promise<Discovery> {
+  const chains = await listChains(options.origin, options.request)
+
+  if (chains.length === 0) {
+    throw nodeUnusable(`The directory at ${options.origin} lists no chains.`)
+  }
+
+  const listed = chains
+    .map((c) => `${c.name ?? '(unnamed)'} (chain ${c.chainNumber})`)
+    .join(', ')
+
+  let chain: GeeqDiscoveredChain | undefined
+
+  if (options.chainName !== undefined) {
+    // Names are what a person types, so match them the way a person means them.
+    const wanted = options.chainName.trim().toLowerCase()
+    const matches = chains.filter((c) => c.name?.trim().toLowerCase() === wanted)
+
+    if (matches.length === 0) {
+      throw invalidArgument(
+        `The directory at ${options.origin} has no chain named ` +
+          `${JSON.stringify(options.chainName)}. Available: ${listed}.`,
+      )
+    }
+    if (matches.length > 1) {
+      throw invalidArgument(
+        `The directory at ${options.origin} lists ${matches.length} chains named ` +
+          `${JSON.stringify(options.chainName)} (numbers ` +
+          `${matches.map((c) => c.chainNumber).join(', ')}), so the name does not identify ` +
+          'one. Select it by chainNumber instead.',
+      )
+    }
+    chain = matches[0]
+  } else if (options.chainNumber !== undefined) {
+    chain = chains.find((c) => c.chainNumber === options.chainNumber)
+    if (chain === undefined) {
+      throw invalidArgument(
+        `The directory at ${options.origin} does not list chain ${options.chainNumber}. ` +
+          `Available: ${listed}.`,
+      )
+    }
+  } else {
+    if (chains.length > 1) {
+      throw invalidArgument(
+        `The directory at ${options.origin} lists ${chains.length} chains, so chainName ` +
+          `or chainNumber is required to choose one. Available: ${listed}.`,
+      )
+    }
+    chain = chains[0]
+  }
+
+  const resolved = chain as GeeqDiscoveredChain
+
+  // A name and a number together are an assertion, not two ways of choosing.
+  if (
+    options.chainName !== undefined &&
+    options.chainNumber !== undefined &&
+    resolved.chainNumber !== options.chainNumber
+  ) {
+    throw invalidArgument(
+      `The directory at ${options.origin} says ${JSON.stringify(options.chainName)} is ` +
+        `chain ${resolved.chainNumber}, but chainNumber was given as ` +
+        `${options.chainNumber}. Drop one of the two.`,
+    )
+  }
+  const nodes = await listNodes(options.origin, resolved.systemId, options.request, {
+    ...(options.protocol === undefined ? {} : { protocol: options.protocol }),
+    ...(options.port === undefined ? {} : { port: options.port }),
+  })
+  const usable = nodes.filter(isUsable)
+
+  if (usable.length === 0) {
+    const seen = nodes.map((n) => `${n.host} (${n.kind}/${n.status})`).join(', ')
+    throw nodeUnusable(
+      `The directory at ${options.origin} lists no node for chain ${resolved.chainNumber} ` +
+        'that is active and running. Only an active node processes transactions. ' +
+        (seen === '' ? 'It listed none at all.' : `It listed: ${seen}.`),
+    )
+  }
+
+  return Object.freeze({ chain: resolved, nodes: Object.freeze([...nodes]), usable: Object.freeze(usable) })
+}

package/src/net/explorer.ts

@@ -0,0 +1,123 @@
+import { GeeqError, invalidArgument, nodeUnusable } from '../errors'
+import { fromBase64 } from '../encoding/base64'
+import { toHex } from '../encoding/hex'
+import { explorerTransactionRoute } from './routes'
+import { defaultTransport, requestText } from './transport'
+import type { GeeqTransport } from './transport'
+
+const DEFAULT_TIMEOUT_MS = 10_000
+const HASH_BYTES = 32
+/** What the explorer answers, with HTTP 500, for a refHash it does not have. */
+const NOT_FOUND = 'Transaction does not exist'
+
+/** A transaction as a block explorer reports it, field for field. */
+export interface GeeqExplorerTransaction {
+  /** Hex — the form the explorer files transactions under. */
+  readonly refHash: string
+  /** The transaction's kind, such as `coin`. */
+  readonly type: string
+  /** The explorer's verdict on it. */
+  readonly status: string
+  readonly block: number
+  readonly chainName: string
+  readonly chainNumber: number
+  /** The sender's wallet address. */
+  readonly from: string
+  readonly senderType: string
+  /** The receiver's wallet address, or empty when it has none. */
+  readonly to: string
+  readonly receiverType: string
+  readonly publicKey: string
+  readonly signature: string
+  readonly createdAt: string
+  readonly fee: string
+  readonly acctNumApp?: string
+  /** What it moved — coin, tokens, NFTs — with amounts as decimal strings. */
+  readonly values: readonly {
+    readonly type: string
+    readonly value: string
+    readonly name?: string
+  }[]
+  /** An attestation's hash and metadata. */
+  readonly payload?: {
+    readonly attestationHash: string
+    readonly metadata: readonly string[]
+  }
+}
+
+export interface ExplorerTransactionRequest {
+  /** The explorer's base URL, such as `https://blkexp.geeq-test.io`. */
+  readonly explorerUrl: string | URL
+  /**
+   * The transaction's refHash in base64 — what `transactionIdOf(tx)` returns and socket
+   * status events carry. It is sent to the explorer as hex.
+   */
+  readonly refHash: string
+  /** Defaults to `globalThis.fetch`. */
+  readonly transport?: GeeqTransport
+  /** Defaults to 10000. */
+  readonly timeoutMs?: number
+  readonly signal?: AbortSignal
+}
+
+function explorerBase(explorerUrl: string | URL): string {
+  let url: URL | undefined
+  try {
+    url = new URL(String(explorerUrl))
+  } catch {
+    url = undefined
+  }
+  if (url === undefined || (url.protocol !== 'https:' && url.protocol !== 'http:')) {
+    throw invalidArgument(
+      'explorerUrl must be an absolute http(s) URL, such as https://blkexp.geeq-test.io, ' +
+        `received ${JSON.stringify(String(explorerUrl))}.`,
+    )
+  }
+  return `${url.origin}${url.pathname.replace(/\/+$/u, '')}`
+}
+
+/**
+ * Look a transaction up in a block explorer by its refHash.
+ *
+ * Resolves `null` when the explorer does not have it — not indexed yet, or never put in a
+ * block. The explorer only knows a transaction once a block has decided it, so for one
+ * you have just sent, the node socket answers first.
+ */
+export async function getExplorerTransaction(
+  request: ExplorerTransactionRequest,
+): Promise<GeeqExplorerTransaction | null> {
+  const hash = fromBase64(request.refHash, 'refHash')
+  if (hash.length !== HASH_BYTES) {
+    throw invalidArgument(
+      `refHash must be the base64 of a ${HASH_BYTES}-byte hash, received ${hash.length} bytes.`,
+    )
+  }
+  const url = explorerTransactionRoute(explorerBase(request.explorerUrl), toHex(hash))
+
+  let body: string
+  try {
+    body = await requestText(url, {
+      transport: request.transport ?? defaultTransport,
+      timeoutMs: request.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      retries: 1,
+      signal: request.signal,
+    })
+  } catch (error) {
+    if (error instanceof GeeqError && error.nodeDetails === NOT_FOUND) return null
+    throw error
+  }
+
+  let result: unknown
+  try {
+    result = (JSON.parse(body) as { result?: unknown })?.result
+  } catch {
+    result = undefined
+  }
+  if (result === null || typeof result !== 'object' || !('refHash' in result)) {
+    throw nodeUnusable(
+      `${url} did not answer with a transaction, so it does not look like a Geeq block ` +
+        'explorer.',
+    )
+  }
+  return result as GeeqExplorerTransaction
+}

package/src/net/read-ledger.ts

@@ -0,0 +1,58 @@
+import { ledgerUnreadable } from '../errors'
+import { decodeValidationLedger } from '../ledger/decode'
+import type { GeeqLedger } from '../ledger/geeq-ledger'
+import { decodeNftRecords } from '../ledger/nft-records'
+import type { NftRecordFacts } from '../ledger/nft-records'
+import { appLedgerRoute, ledgerRoute } from './routes'
+import type { RequestOptions } from './transport'
+import { requestText } from './transport'
+
+/** Pull `result` out of a node's response envelope. */
+function resultOf(body: string, url: string): string {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(body)
+  } catch (cause) {
+    throw ledgerUnreadable(
+      `The node at ${url} did not answer with JSON. A login page or a proxy error is ` +
+        `the usual reason. First 120 characters: ${JSON.stringify(body.slice(0, 120))}.`,
+      cause,
+    )
+  }
+
+  if (parsed === null || typeof parsed !== 'object' || !('result' in parsed)) {
+    throw ledgerUnreadable(
+      `The node at ${url} answered JSON with no "result" field, so this is probably ` +
+        'not a Geeq node.',
+    )
+  }
+
+  const { result } = parsed as { result: unknown }
+  if (typeof result !== 'string') {
+    throw ledgerUnreadable(
+      `The node at ${url} answered with a "result" of type ${typeof result}, expected a ` +
+        'base64 string.',
+    )
+  }
+  return result
+}
+
+/** Read and decode the validation layer ledger from one node. */
+export async function readLedger(
+  origin: string,
+  options: RequestOptions,
+): Promise<GeeqLedger> {
+  const url = ledgerRoute(origin)
+  const body = await requestText(url, options)
+  return decodeValidationLedger(resultOf(body, url), { nodeUrl: origin })
+}
+
+/** Read the NFT records in the application layer ledger from one node. */
+export async function readNftRecords(
+  origin: string,
+  options: RequestOptions,
+): Promise<Map<string, NftRecordFacts>> {
+  const url = appLedgerRoute(origin)
+  const body = await requestText(url, options)
+  return decodeNftRecords(resultOf(body, url))
+}

package/src/net/routes.ts

@@ -0,0 +1,79 @@
+/**
+ * Every node route the SDK knows, in one place.
+ *
+ * `origin` is an absolute node URL with no trailing slash — see `originOf`.
+ */
+
+/** `GET` the current validation layer ledger, base64 packed capnp under `result`. */
+export function ledgerRoute(origin: string): string {
+  return `${origin}/api/blocks?type=vll`
+}
+
+/** `GET` the current application layer ledger, where NFT records live. Same envelope. */
+export function appLedgerRoute(origin: string): string {
+  return `${origin}/api/blocks?type=all`
+}
+
+/**
+ * Where a signed transaction is POSTed.
+ *
+ * The SDK does not submit — this is exported so an application builds the same URL the
+ * SDK read from, rather than keeping its own copy of the path.
+ */
+export function submitRoute(origin: string): string {
+  return `${origin}/api/blocks/process`
+}
+
+/**
+ * The node's client WebSocket, where transaction status events arrive.
+ *
+ * Same host and port as the HTTP API — the node's TLS front door routes `/ws/` to the
+ * socket server and `/api/` to the HTTP one — so the only change is the scheme. The
+ * trailing slash is part of the route: the proxy answers `/ws` with a redirect, and a
+ * WebSocket handshake treats a redirect as failure.
+ */
+export function socketRoute(origin: string): string {
+  const url = new URL(origin)
+  const scheme =
+    url.protocol === 'https:' ? 'wss:' : url.protocol === 'http:' ? 'ws:' : url.protocol
+  return `${scheme}//${url.host}${url.pathname.replace(/\/+$/u, '')}/ws/`
+}
+
+/**
+ * The body a node expects for an application-layer transaction: an attestation or an NFT
+ * mint, each a transaction and its payload.
+ */
+export function attestationSubmitBody(transaction: string, payload: string): string {
+  return JSON.stringify({ type: 'uat', data: { transaction, payload } })
+}
+
+/**
+ * The body a node expects for a coin transfer.
+ *
+ * A different type and a different shape from an attestation: a validation-layer
+ * transaction carries no separate payload, so there is one blob rather than two.
+ */
+export function coinTransferSubmitBody(transaction: string): string {
+  return JSON.stringify({ type: 'uvt', data: { transaction } })
+}
+
+/**
+ * Discovery routes on the chain's directory service.
+ *
+ * Only these two are ever called. The same service also exposes routes that start and
+ * stop nodes, install a genesis block, and — on `/api/accounts` — hand out plaintext
+ * private keys. None of those belong anywhere near an SDK, so the paths live here and
+ * nowhere else, and nothing constructs a URL against that origin by hand.
+ */
+export function chainsRoute(origin: string): string {
+  return `${origin}/api/admin/simulation/chains`
+}
+
+export function nodesRoute(origin: string, systemId: number): string {
+  return `${origin}/api/nodes?systemId=${encodeURIComponent(String(systemId))}`
+}
+
+/** A block explorer's transaction lookup. The explorer files transactions by hex refHash. */
+export function explorerTransactionRoute(explorer: string, refHashHex: string): string {
+  return `${explorer}/api/transactions/byRefHash?refHash=${refHashHex}`
+}