@geeqdev/geeq-sdk 0.1.0 → 0.1.1

package/src/crypto/mnemonic.ts

@@ -0,0 +1,69 @@
+import { generateMnemonic as scureGenerate, validateMnemonic as scureValidate } from '@scure/bip39'
+import { wordlist } from '@scure/bip39/wordlists/english'
+import { invalidArgument } from '../errors'
+
+/** Supported mnemonic lengths. 12 words is the common default; 24 is the strongest. */
+export type MnemonicWordCount = 12 | 15 | 18 | 21 | 24
+
+const ENTROPY_BITS: Readonly<Record<MnemonicWordCount, number>> = {
+  12: 128,
+  15: 160,
+  18: 192,
+  21: 224,
+  24: 256,
+}
+
+export const MNEMONIC_WORD_COUNTS = Object.freeze([12, 15, 18, 21, 24] as const)
+
+export interface GenerateMnemonicOptions {
+  /** How many words to generate. Defaults to 12. */
+  readonly words?: MnemonicWordCount
+}
+
+/**
+ * Generate a fresh BIP-39 recovery phrase, using the platform's cryptographically
+ * secure random source.
+ *
+ * Pure JavaScript — no engine needed, so this works before {@link initGeeq}
+ * resolves. Phrases are generated from the English wordlist, which is what
+ * {@link keypairFromMnemonic} expects.
+ *
+ * The phrase is the *only* way to recover the wallet. Show it to the user once,
+ * let them write it down, and never transmit or persist it in plaintext.
+ *
+ * ```ts
+ * const mnemonic = generateMnemonic()            // 12 words
+ * const long = generateMnemonic({ words: 24 })   // 24 words
+ * ```
+ */
+export function generateMnemonic(options: GenerateMnemonicOptions = {}): string {
+  const words = options.words ?? 12
+  const bits = ENTROPY_BITS[words]
+  if (bits === undefined) {
+    throw invalidArgument(
+      `words must be one of ${MNEMONIC_WORD_COUNTS.join(', ')}, received ${String(words)}.`,
+    )
+  }
+  return scureGenerate(wordlist, bits)
+}
+
+/**
+ * Check a recovery phrase for the right word count, known words, and a valid
+ * checksum. Use it to give immediate feedback on a restore form rather than
+ * waiting for {@link keypairFromMnemonic} to throw.
+ *
+ * Pure JavaScript — no engine needed.
+ */
+export function validateMnemonic(mnemonic: string): boolean {
+  if (typeof mnemonic !== 'string') return false
+  try {
+    return scureValidate(normalizeMnemonic(mnemonic), wordlist)
+  } catch {
+    return false
+  }
+}
+
+/** Trim and collapse whitespace so pasted phrases validate as typed ones do. */
+export function normalizeMnemonic(mnemonic: string): string {
+  return mnemonic.trim().replace(/\s+/gu, ' ').toLowerCase()
+}

package/src/encoding/base64.ts

@@ -0,0 +1,58 @@
+import { invalidArgument } from '../errors'
+
+/**
+ * Base64 in both directions, with one behaviour on every runtime.
+ *
+ * The platform primitives disagree on bad input: `Buffer.from(s, 'base64')` silently
+ * drops characters it does not recognise and returns a short buffer, while `atob`
+ * throws. Decoding a ledger through the first would turn "this URL is not a Geeq node"
+ * into "this ledger is corrupt" — so the input is validated here and both paths take
+ * the same branch.
+ */
+
+/** Standard alphabet, correct padding, whole 4-character groups. */
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+
+export function toBase64(bytes: Uint8Array): string {
+  if (typeof btoa === 'function') {
+    let binary = ''
+    for (const byte of bytes) binary += String.fromCharCode(byte)
+    return btoa(binary)
+  }
+  return Buffer.from(bytes).toString('base64')
+}
+
+/**
+ * Decode base64, rejecting anything the alphabet does not cover.
+ *
+ * `label` names the thing being decoded so the message points at the caller's data
+ * rather than at this function.
+ */
+export function fromBase64(value: string, label = 'value'): Uint8Array {
+  if (typeof value !== 'string') {
+    throw invalidArgument(`${label} must be a base64 string, received ${typeof value}.`)
+  }
+  if (value === '') return new Uint8Array(0)
+
+  if (!BASE64.test(value)) {
+    // Naming the offending character and its index is the difference between "this is
+    // not base64" and "your proxy returned an HTML login page".
+    const index = value.search(/[^A-Za-z0-9+/=]/u)
+    const detail =
+      index === -1
+        ? `its length (${value.length}) is not a multiple of 4, or its padding is misplaced`
+        : `it contains ${JSON.stringify(value[index])} at index ${index}`
+    throw invalidArgument(
+      `${label} is not valid base64: ${detail}. ` +
+        'A value that looks like markup or JSON usually means the URL is not a Geeq node.',
+    )
+  }
+
+  if (typeof atob === 'function') {
+    const binary = atob(value)
+    const bytes = new Uint8Array(binary.length)
+    for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i)
+    return bytes
+  }
+  return new Uint8Array(Buffer.from(value, 'base64'))
+}

package/src/encoding/hex.ts

@@ -0,0 +1,42 @@
+import { invalidArgument } from '../errors'
+
+/**
+ * Hex in both directions.
+ *
+ * Every hash this SDK returns is bytes, and almost every application immediately turns
+ * them into hex to show or log. Doing that by hand is three lines everyone writes
+ * slightly differently — and `toString(16)` without padding silently drops a leading
+ * zero, producing a 63-character "32-byte" hash that compares unequal to itself.
+ */
+
+const HEX = /^[0-9a-fA-F]*$/
+
+export function toHex(bytes: Uint8Array): string {
+  let hex = ''
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, '0')
+  return hex
+}
+
+export function fromHex(value: string, label = 'value'): Uint8Array {
+  if (typeof value !== 'string') {
+    throw invalidArgument(`${label} must be a hex string, received ${typeof value}.`)
+  }
+  const text = value.startsWith('0x') || value.startsWith('0X') ? value.slice(2) : value
+  if (text.length % 2 !== 0) {
+    throw invalidArgument(
+      `${label} must have an even number of hex digits, received ${text.length}.`,
+    )
+  }
+  if (!HEX.test(text)) {
+    const index = text.search(/[^0-9a-fA-F]/u)
+    throw invalidArgument(
+      `${label} is not valid hex: it contains ${JSON.stringify(text[index])} at index ${index}.`,
+    )
+  }
+
+  const bytes = new Uint8Array(text.length / 2)
+  for (let i = 0; i < bytes.length; i += 1) {
+    bytes[i] = Number.parseInt(text.slice(i * 2, i * 2 + 2), 16)
+  }
+  return bytes
+}

package/src/errors.ts

@@ -0,0 +1,122 @@
+/**
+ * Every error thrown by this SDK is a {@link GeeqError} carrying a stable
+ * {@link GeeqErrorCode}. Branch on `code`, never on the message text.
+ */
+export type GeeqErrorCode =
+  /** An SDK function was called before the engine finished loading. */
+  | 'not-initialized'
+  /** The WebAssembly engine could not be loaded. */
+  | 'init-failed'
+  /** A public or private key was the wrong length, or the pair did not match. */
+  | 'invalid-key'
+  /** A wallet address was malformed, or encoded a record type we do not know. */
+  | 'invalid-address'
+  /** A caller-supplied argument was outside its allowed range. */
+  | 'invalid-argument'
+  /** A node could not be reached at all — no HTTP response arrived. */
+  | 'network-unreachable'
+  /** A node, simulator or explorer answered with an error status. See `status` and `nodeDetails`. */
+  | 'node-error'
+  /** A node answered, but its ledger could not be decoded. */
+  | 'ledger-unreadable'
+  /** The node's chain is not the one the caller said to expect. */
+  | 'chain-mismatch'
+  /** The signing account has no record on this chain yet — it needs funding. */
+  | 'account-not-found'
+  /** The account exists but its record type cannot sign this transaction. */
+  | 'account-not-attestable'
+  /**
+   * The node being targeted cannot be identified, or cannot process transactions. Also
+   * thrown when a simulator or explorer answers with something it should not serve.
+   */
+  | 'node-unusable'
+  /** Metadata exceeds a limit this chain publishes in its ledger. */
+  | 'metadata-too-large'
+  /** A second transaction was built for one account against one block. */
+  | 'nonce-collision'
+  /** The sending account does not hold enough coin. */
+  | 'insufficient-funds'
+  /** The amount is below the smallest transfer this chain accepts. */
+  | 'amount-below-minimum'
+  /** The sending account does not hold an NFT it was asked to send. */
+  | 'nft-not-owned'
+  /** A node's WebSocket could not be opened, or this runtime has no WebSocket at all. */
+  | 'socket-unreachable'
+  /** The {@link GeeqSocket} was disposed, so it will not send or receive again. */
+  | 'socket-closed'
+
+export interface GeeqErrorOptions {
+  readonly cause?: unknown
+  /** HTTP status, when a server answered. */
+  readonly status?: number
+  /**
+   * The server's own `details`, verbatim; a list of them is joined with `; `. Never parse
+   * it — branch on `code`.
+   */
+  readonly nodeDetails?: string
+}
+
+export class GeeqError extends Error {
+  readonly code: GeeqErrorCode
+  readonly status?: number | undefined
+  readonly nodeDetails?: string | undefined
+
+  constructor(code: GeeqErrorCode, message: string, options?: GeeqErrorOptions) {
+    // Only `cause` belongs to Error; the rest are ours. exactOptionalPropertyTypes
+    // forbids handing it an explicit undefined, hence the ternary.
+    super(message, options?.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'GeeqError'
+    this.code = code
+    this.status = options?.status
+    this.nodeDetails = options?.nodeDetails
+  }
+}
+
+function make(code: GeeqErrorCode) {
+  return (message: string, cause?: unknown): GeeqError =>
+    new GeeqError(code, message, cause === undefined ? undefined : { cause })
+}
+
+export function notInitialized(what: string): GeeqError {
+  return new GeeqError(
+    'not-initialized',
+    `${what} was called before the Geeq engine finished loading. ` +
+      'Await initGeeq() once at startup, or use the async helpers (generateKeypair, ' +
+      'importKeypair, createWalletAddress) which load it for you.',
+  )
+}
+
+/** The default chain was used before one was installed. */
+export function noChain(what: string): GeeqError {
+  return new GeeqError(
+    'not-initialized',
+    `${what} was called before a chain was initialised. ` +
+      'Await GeeqChain.init({ endpoint }) once at startup, or pass an explicit chain ' +
+      'from GeeqChain.connect({ endpoint }).',
+  )
+}
+
+export const invalidKey = make('invalid-key')
+export const invalidAddress = make('invalid-address')
+export const invalidArgument = make('invalid-argument')
+export const ledgerUnreadable = make('ledger-unreadable')
+export const chainMismatch = make('chain-mismatch')
+export const accountNotFound = make('account-not-found')
+export const accountNotAttestable = make('account-not-attestable')
+export const nodeUnusable = make('node-unusable')
+export const metadataTooLarge = make('metadata-too-large')
+export const nonceCollision = make('nonce-collision')
+export const insufficientFunds = make('insufficient-funds')
+export const amountBelowMinimum = make('amount-below-minimum')
+export const nftNotOwned = make('nft-not-owned')
+export const socketUnreachable = make('socket-unreachable')
+export const socketClosed = make('socket-closed')
+export const networkUnreachable = make('network-unreachable')
+
+/** A node answered with an error status. `details` is the node's own message. */
+export function nodeError(message: string, status: number, details?: string): GeeqError {
+  return new GeeqError('node-error', message, {
+    status,
+    ...(details === undefined ? {} : { nodeDetails: details }),
+  })
+}

package/src/index.ts

@@ -0,0 +1,195 @@
+/**
+ * Geeq SDK — browser-first TypeScript access to the Geeq blockchain.
+ *
+ * ```ts
+ * import { generateKeypair } from '@geeqdev/geeq-sdk'
+ *
+ * const keypair = await generateKeypair()
+ * const address = keypair.getAddress({ chainNumber: 1 })
+ * ```
+ */
+
+// Engine lifecycle
+export { initGeeq, isGeeqReady } from './runtime/init'
+
+// Keypairs
+export {
+  generateKeypair,
+  generateKeypairSync,
+  importKeypair,
+  importKeypairSync,
+  keypairFromSecretKey,
+  keypairFromSecretKeySync,
+  keypairFromMnemonic,
+  keypairFromMnemonicSync,
+  verifySignature,
+} from './crypto/keypair'
+
+export { accountIdFromPublicKey, ACCOUNT_ID_BYTES, PUBLIC_KEY_BYTES } from './crypto/account-id'
+export type { AccountRef } from './crypto/account-id'
+
+// Recovery phrases
+export {
+  generateMnemonic,
+  validateMnemonic,
+  normalizeMnemonic,
+  MNEMONIC_WORD_COUNTS,
+} from './crypto/mnemonic'
+export type { GenerateMnemonicOptions, MnemonicWordCount } from './crypto/mnemonic'
+
+// Wallet addresses
+export {
+  createWalletAddress,
+  createWalletAddressSync,
+  decodeWalletAddress,
+  decodeWalletAddressSync,
+  isValidWalletAddress,
+} from './address/wallet-address'
+
+export { GEEQ_RECORD_TYPES, DEFAULT_RECORD_TYPE } from './address/record-type'
+
+// Chains and nodes
+export { GeeqChain, attest, initChain, transfer } from './chain/geeq-chain'
+export { GeeqNode } from './chain/geeq-node'
+export { GEEQ_NODE_PORT, selectNode } from './chain/select'
+export { discover, listChains, listNodes } from './net/discovery'
+export { defaultTransport } from './net/transport'
+export {
+  attestationSubmitBody,
+  coinTransferSubmitBody,
+  ledgerRoute,
+  socketRoute,
+  submitRoute,
+} from './net/routes'
+export type {
+  AttestationRequest,
+  ChainStateRequest,
+  CoinTransferRequest,
+  GeeqChainOptions,
+  NftMintRequest,
+  NftMintProxiesRequest,
+  NftMintProxyRequest,
+  NftsRequest,
+} from './chain/geeq-chain'
+export type {
+  Discovery,
+  GeeqDiscoveredChain,
+  GeeqDiscoveredNode,
+  GeeqNodeKind,
+} from './net/discovery'
+export type {
+  GeeqHttpResponse,
+  GeeqRequestInit,
+  GeeqTransport,
+} from './net/transport'
+
+// Block explorer — look a transaction up after a block has decided it
+export { getExplorerTransaction } from './net/explorer'
+export type { ExplorerTransactionRequest, GeeqExplorerTransaction } from './net/explorer'
+
+// Sockets — what happened to the transactions you sent, and anything else a node pushes
+export { GeeqSocket } from './socket/geeq-socket'
+export { GeeqTrackedTx } from './socket/tracked-tx'
+export { transactionIdOf } from './socket/tx-status'
+export { defaultWebSocketFactory } from './net/websocket'
+export type {
+  GeeqListenOptions,
+  GeeqSendOptions,
+  GeeqSocketMessage,
+  GeeqSocketOptions,
+  GeeqSocketState,
+  GeeqTrackable,
+  GeeqTrackOptions,
+} from './socket/geeq-socket'
+export type {
+  GeeqTxConfirmed,
+  GeeqTxOutcome,
+  GeeqTxRefusal,
+  GeeqTxRejected,
+  GeeqTxRejectionReason,
+  GeeqTxState,
+  GeeqTxUnknown,
+  GeeqTxUnknownReason,
+} from './socket/tracked-tx'
+export type { GeeqTxStatusEvent, GeeqTxVerdict } from './socket/tx-status'
+export type {
+  GeeqWebSocketFactory,
+  GeeqWebSocketLike,
+  GeeqWebSocketMessageEvent,
+} from './net/websocket'
+
+// Content, encoding and metadata — everything an application would otherwise
+// hand-roll around a transaction
+export {
+  ATTEST_HASH_BYTES,
+  assertAttestHash,
+  attestHashOf,
+  attestHashOfSync,
+  readContent,
+} from './tx/content'
+export type { GeeqContent } from './tx/content'
+export { inspectMetadata } from './tx/metadata'
+export type { MetadataEntryReport, MetadataReport } from './tx/metadata'
+export { fromBase64, toBase64 } from './encoding/base64'
+export { fromHex, toHex } from './encoding/hex'
+
+// Ledgers
+export { decodeValidationLedger } from './ledger/decode'
+export { GeeqLedger } from './ledger/geeq-ledger'
+export type { DecodeLedgerOptions } from './ledger/decode'
+export type { GeeqCoinAccount, GeeqCoinRecordKind, GeeqHeldNft } from './ledger/coin-accounts'
+export type { GeeqLedgerNode, GeeqNodeRole, GeeqNodeStatus } from './ledger/net-actors'
+export type { GeeqProxyAccount, GeeqProxyKind } from './ledger/proxy-accounts'
+
+// Transactions
+export { createAttestationTx, createAttestationTxSync } from './tx/attestation'
+export { createCoinTransferTx, createCoinTransferTxSync } from './tx/transfer'
+export { createNftMintProxyTx, createNftMintProxyTxSync } from './tx/proxy'
+export { createNftMintTx, createNftMintTxSync } from './tx/nft'
+
+// Amounts — the protocol counts pennies; how many make a Geeq is the app's to say
+export { formatGeeq, toPennies } from './amount'
+export type { GeeqAmount } from './amount'
+
+// Errors
+export { GeeqError } from './errors'
+export type { GeeqErrorCode } from './errors'
+
+// Types
+export type {
+  AttestationContent,
+  AttestationTx,
+  AttestationTxFlatInput,
+  AttestationTxInput,
+  AttestationTxStateInput,
+  ChainStateInput,
+  CoinTransferContent,
+  CoinTransferTx,
+  CoinTransferTxFlatInput,
+  CoinTransferTxInput,
+  CoinTransferTxStateInput,
+  GeeqChainState,
+  GeeqFee,
+  GeeqMetadataLimits,
+  DecodedWalletAddress,
+  GeeqCoinType,
+  GeeqKeypair,
+  GeeqRecordType,
+  InitOptions,
+  MnemonicOptions,
+  GeeqNft,
+  GeeqNftMintProxies,
+  GeeqNftMintProxy,
+  NftMintProxyTx,
+  NftMintProxyTxInput,
+  NftMintTx,
+  NftMintTxInput,
+  NftTransferEntry,
+  WalletAddressOptions,
+  WasmSource,
+} from './types'
+
+export type {
+  AccountIdentifier,
+  CreateWalletAddressInput,
+} from './address/wallet-address'

package/src/ledger/coin-accounts.ts

@@ -0,0 +1,73 @@
+import type { CoinAcctRec } from '../capnp/coinAcctRec.capnp'
+
+import { uint64ToPennies } from '../amount'
+
+/** Which coin record subtype an account is. Only `'asset'` may sign an attestation. */
+export type GeeqCoinRecordKind = 'asset' | 'hl' | 'micro' | 'unknown'
+
+/** One coin account record, as plain values. */
+export interface GeeqCoinAccount {
+  readonly accountId: Uint8Array
+  readonly kind: GeeqCoinRecordKind
+  /**
+   * `undefined` for a hash-lock record, which carries no nonce field at all, and for a
+   * record whose subtype could not be read.
+   */
+  readonly nonce: number | undefined
+  /** Balance in pennies. Use `formatGeeq` to show it. */
+  readonly balance: bigint
+  /** The NFTs it holds, in the order its record lists them. Read for coin-asset records only. */
+  readonly nfts: readonly GeeqHeldNft[]
+}
+
+/** One NFT an account holds, as its record lists it. */
+export interface GeeqHeldNft {
+  /** The NFT's 32-byte id. */
+  readonly id: Uint8Array
+  /** A counterparty NFT moves only with a counterparty transaction, never a plain transfer. */
+  readonly counterparty: boolean
+}
+
+/** What we keep per account. The id is the map key, so it is not repeated here. */
+export interface CoinAccountFacts {
+  readonly kind: GeeqCoinRecordKind
+  readonly nonce: number | undefined
+  readonly balance: bigint
+  readonly nfts: readonly GeeqHeldNft[]
+}
+
+/**
+ * Read a coin account's subtype and nonce without tripping the union's zero value.
+ *
+ * `getAsset()` throws on a record of another subtype, and — worse — `ASSET` is the
+ * union's zero value, so a record whose tag is unset and whose pointer is null passes
+ * capnp-ts's `testWhich`. `getStruct` then calls `initStruct`, MUTATING the decoded
+ * message and handing back a zeroed struct whose `getNonce()` is `0`. A silent nonce of
+ * zero is the worst possible failure here, so every arm is guarded by both `isX()` and
+ * `hasX()` and an unreadable record reports `'unknown'` instead of a number.
+ */
+export function readCoinAccount(record: CoinAcctRec): CoinAccountFacts {
+  const recType = record.getRecType()
+  // The balance lives on the outer record, so every subtype has one.
+  const balance = uint64ToPennies(record.getAmtCoin())
+
+  if (recType.isAsset()) {
+    if (!recType.hasAsset()) return { kind: 'unknown', nonce: undefined, balance, nfts: [] }
+    const asset = recType.getAsset()
+    const nfts = asset.getNftAssetSubgroups().toArray().map((nft) => ({
+      id: new Uint8Array(nft.getAcctNumApp().toArrayBuffer()),
+      counterparty: nft.getFlagCounterpartyNft(),
+    }))
+    return { kind: 'asset', nonce: asset.getNonce(), balance, nfts }
+  }
+  if (recType.isHl()) {
+    // Hash-lock records have no nonce field in the schema at all.
+    return { kind: 'hl', nonce: undefined, balance, nfts: [] }
+  }
+  if (recType.isMicro()) {
+    return recType.hasMicro()
+      ? { kind: 'micro', nonce: recType.getMicro().getNonce(), balance, nfts: [] }
+      : { kind: 'unknown', nonce: undefined, balance, nfts: [] }
+  }
+  return { kind: 'unknown', nonce: undefined, balance, nfts: [] }
+}