@geeqdev/geeq-sdk 0.1.0 → 0.2.0

package/dist/src/net/routes.js

@@ -0,0 +1,70 @@
+/**
+ * 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) {
+    return `${origin}/api/blocks?type=vll`;
+}
+/** `GET` the current application layer ledger, where NFT records live. Same envelope. */
+export function appLedgerRoute(origin) {
+    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) {
+    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) {
+    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, payload) {
+    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) {
+    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) {
+    return `${origin}/api/admin/simulation/chains`;
+}
+export function nodesRoute(origin, systemId) {
+    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, refHashHex) {
+    return `${explorer}/api/transactions/byRefHash?refHash=${refHashHex}`;
+}
+//# sourceMappingURL=routes.js.map

package/dist/src/net/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../../src/net/routes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qFAAqF;AACrF,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,GAAG,MAAM,sBAAsB,CAAA;AACxC,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,GAAG,MAAM,sBAAsB,CAAA;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,GAAG,MAAM,qBAAqB,CAAA;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAA;IAC3B,MAAM,MAAM,GACV,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAA;IACtF,OAAO,GAAG,MAAM,KAAK,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAA;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB,EAAE,OAAe;IACxE,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC,CAAA;AACxE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,WAAW,EAAE,EAAE,CAAC,CAAA;AAC/D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,GAAG,MAAM,8BAA8B,CAAA;AAChD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAc,EAAE,QAAgB;IACzD,OAAO,GAAG,MAAM,uBAAuB,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAA;AAC/E,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,wBAAwB,CAAC,QAAgB,EAAE,UAAkB;IAC3E,OAAO,GAAG,QAAQ,uCAAuC,UAAU,EAAE,CAAA;AACvE,CAAC"}

package/dist/src/net/transport.d.ts

@@ -0,0 +1,55 @@
+/** A response, narrowed to what this SDK reads. A WHATWG `Response` satisfies it. */
+export interface GeeqHttpResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+}
+/** A request, narrowed to what this SDK sends. Assignable to `RequestInit`. */
+export interface GeeqRequestInit {
+    readonly method?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+    readonly signal?: AbortSignal;
+}
+/**
+ * How the SDK reaches a node.
+ *
+ * Deliberately a structural subset of WHATWG `fetch`, so `{ transport: fetch }`
+ * typechecks with no adapter, and so does undici with a custom dispatcher, a relative
+ * URL through a dev proxy, or a scripted array of responses in a test.
+ */
+export type GeeqTransport = (url: string, init?: GeeqRequestInit) => Promise<GeeqHttpResponse>;
+/**
+ * `globalThis.fetch`, resolved at call time.
+ *
+ * Never a stored reference: an unbound `fetch` throws `Illegal invocation` in a
+ * browser, and capturing it would defeat any test that swaps `globalThis.fetch` after
+ * this module is imported.
+ */
+export declare const defaultTransport: GeeqTransport;
+export interface RequestOptions {
+    readonly transport: GeeqTransport;
+    readonly timeoutMs: number;
+    readonly retries: number;
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly method?: string | undefined;
+    readonly body?: string | undefined;
+}
+/**
+ * Make one request and return its body, mapping every failure onto a typed error.
+ *
+ * Retries only a transport failure, and only because reads are idempotent. A response
+ * that arrived is never retried: the node has decided.
+ */
+export declare function requestText(url: string, options: RequestOptions): Promise<string>;
+/**
+ * Wait for `promise`, or stop waiting when `signal` aborts.
+ *
+ * For a request several callers share: aborting one caller's wait must not cancel the
+ * request out from under the others, so the request runs on without any caller's signal
+ * and each caller races its own against it.
+ *
+ * @internal
+ */
+export declare function raceAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;

package/dist/src/net/transport.js

@@ -0,0 +1,168 @@
+import { GeeqError, networkUnreachable, nodeError } from '../errors';
+/**
+ * `globalThis.fetch`, resolved at call time.
+ *
+ * Never a stored reference: an unbound `fetch` throws `Illegal invocation` in a
+ * browser, and capturing it would defeat any test that swaps `globalThis.fetch` after
+ * this module is imported.
+ */
+export const defaultTransport = (url, init) => globalThis.fetch(url, init);
+/**
+ * The one failure a browser can be certain about before making a request.
+ *
+ * An https page may not load an http subresource. The browser blocks it and reports a
+ * generic network failure, so issuing the request would only turn a knowable cause into
+ * an ambiguous one.
+ */
+function assertSchemeReachable(url) {
+    const location = globalThis.location;
+    if (location?.protocol !== 'https:')
+        return;
+    let scheme;
+    try {
+        scheme = new URL(url).protocol;
+    }
+    catch {
+        return;
+    }
+    if (scheme !== 'http:')
+        return;
+    throw networkUnreachable(`This page is served over https and the node URL ${url} is http, so the browser ` +
+        'will block the request as mixed content before it is sent. Use the node\'s https ' +
+        'URL (port 2082 by default), or serve this page over http while developing.');
+}
+/** The four causes a browser cannot tell apart, each with what to do about it. */
+function opaqueFailureMessage(url) {
+    return (`Could not reach the Geeq node at ${url}. A browser reports network failures ` +
+        'opaquely, so this is one of four things: (1) the node does not answer CORS for ' +
+        'this origin — pass your own `transport` routing through a proxy you control; ' +
+        "(2) the node's TLS certificate is not trusted, which is common because nodes are " +
+        'addressed by bare IP — open the URL in a tab to see the interstitial; (3) this ' +
+        'page is https and the node is http, which browsers block; or (4) the node is down ' +
+        'or the URL is wrong.');
+}
+function describeCause(cause) {
+    if (cause !== null && typeof cause === 'object') {
+        const { code } = cause;
+        if (typeof code === 'string')
+            return code;
+    }
+    return undefined;
+}
+/** Pull the node's own `details` out of an error body without trusting its shape. */
+function nodeDetailsOf(body) {
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed !== null && typeof parsed === 'object') {
+            const { details, error } = parsed;
+            if (typeof details === 'string' && details !== '')
+                return details;
+            // A block explorer sends its reasons as a list.
+            if (Array.isArray(details)) {
+                const joined = details.filter((item) => typeof item === 'string').join('; ');
+                if (joined !== '')
+                    return joined;
+            }
+            if (typeof error === 'string' && error !== '')
+                return error;
+        }
+    }
+    catch {
+        // Not JSON. The raw body is still the most useful thing we have.
+    }
+    return body === '' ? undefined : body.slice(0, 400);
+}
+/**
+ * `signal.throwIfAborted()`, written out: a polyfilled `AbortSignal` may not have it.
+ * A call rather than an inline check also keeps TypeScript from narrowing `aborted` to
+ * false for the rest of the function — it can change across an `await`.
+ */
+function throwIfAborted(signal) {
+    if (signal?.aborted === true)
+        throw signal.reason;
+}
+/**
+ * Make one request and return its body, mapping every failure onto a typed error.
+ *
+ * Retries only a transport failure, and only because reads are idempotent. A response
+ * that arrived is never retried: the node has decided.
+ */
+export async function requestText(url, options) {
+    assertSchemeReachable(url);
+    const { signal } = options;
+    let lastCause;
+    for (let attempt = 0; attempt <= options.retries; attempt += 1) {
+        // An 'abort' listener never fires for a signal that is already aborted, so without
+        // this the request would go out anyway — and so would a retry after an abort.
+        throwIfAborted(signal);
+        // Composed by hand rather than with AbortSignal.any, which needs Node 20.3 and
+        // Safari 17.4 — too new for a library that supports Node 20. The caller's reason is
+        // passed on, so a fetch that honours it rejects with exactly what the caller aborted with.
+        const controller = new AbortController();
+        const onAbort = () => controller.abort(signal?.reason);
+        signal?.addEventListener('abort', onAbort);
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, options.timeoutMs);
+        try {
+            const response = await options.transport(url, {
+                signal: controller.signal,
+                ...(options.method === undefined ? {} : { method: options.method }),
+                ...(options.headers === undefined ? {} : { headers: options.headers }),
+                ...(options.body === undefined ? {} : { body: options.body }),
+            });
+            const body = await response.text();
+            if (!response.ok) {
+                const details = nodeDetailsOf(body);
+                throw nodeError(`The node at ${url} answered HTTP ${response.status}` +
+                    (details === undefined ? ' with no detail.' : `: ${JSON.stringify(details)}.`), response.status, details);
+            }
+            return body;
+        }
+        catch (cause) {
+            if (cause instanceof GeeqError)
+                throw cause;
+            // A caller-driven abort is theirs to observe, not ours to relabel.
+            if (signal?.aborted === true)
+                throw signal.reason;
+            if (timedOut) {
+                throw networkUnreachable(`The node at ${url} did not answer within ${options.timeoutMs}ms. Raise ` +
+                    'timeoutMs if the node is simply slow, or try another node.', cause);
+            }
+            lastCause = cause;
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+        }
+    }
+    const code = describeCause(lastCause);
+    throw networkUnreachable(code === undefined
+        ? opaqueFailureMessage(url)
+        : `Could not reach the Geeq node at ${url}: ${code}.`, lastCause);
+}
+/**
+ * Wait for `promise`, or stop waiting when `signal` aborts.
+ *
+ * For a request several callers share: aborting one caller's wait must not cancel the
+ * request out from under the others, so the request runs on without any caller's signal
+ * and each caller races its own against it.
+ *
+ * @internal
+ */
+export function raceAbort(promise, signal) {
+    if (signal === undefined)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise
+            .then(resolve, reject)
+            .finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+//# sourceMappingURL=transport.js.map

package/dist/src/net/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../../src/net/transport.ts"],"names":[],"mappings":"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"}

package/dist/src/net/websocket.d.ts

@@ -0,0 +1,49 @@
+/** `readyState` of an open connection. The same number in browsers and in `ws`. */
+export declare const WEBSOCKET_OPEN = 1;
+/** What a WebSocket hands its `message` listeners, narrowed to the one field read. */
+export interface GeeqWebSocketMessageEvent {
+    readonly data: unknown;
+}
+/**
+ * A WebSocket, narrowed to what this SDK uses.
+ *
+ * Deliberately structural, like {@link GeeqTransport}: a browser `WebSocket`, Node 22's
+ * global one and the `ws` package's class all satisfy it with no adapter, and so does a
+ * scripted fake in a test. Listeners are attached with `addEventListener` rather than
+ * `onmessage` and friends because a method is compared bivariantly, which is what lets
+ * each implementation's own event types through.
+ */
+export interface GeeqWebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open', listener: (event: unknown) => void): void;
+    addEventListener(type: 'message', listener: (event: GeeqWebSocketMessageEvent) => void): void;
+    addEventListener(type: 'close', listener: (event: unknown) => void): void;
+    addEventListener(type: 'error', listener: (event: unknown) => void): void;
+}
+/**
+ * How the SDK opens a socket.
+ *
+ * `(url) => new WebSocket(url)` is the whole contract. Pass one to use the `ws` package on
+ * Node 20, to add headers or a TLS agent there, or to script a connection in a test.
+ */
+export type GeeqWebSocketFactory = (url: string) => GeeqWebSocketLike;
+/**
+ * `new globalThis.WebSocket(url)`, resolved at call time.
+ *
+ * Never a stored reference, for the same reason as `defaultTransport`: a test that swaps
+ * the global after import must still be honoured. Node 20 has no global WebSocket at all,
+ * and a library that supports Node 20 cannot assume one, so its absence is reported with
+ * the one-line fix rather than as a `TypeError`.
+ */
+export declare const defaultWebSocketFactory: GeeqWebSocketFactory;
+/**
+ * The one socket failure a browser can be certain about before trying.
+ *
+ * An https page may not open a `ws://` socket; the browser refuses it outright and reports
+ * nothing useful, so the handshake would only turn a knowable cause into an opaque one.
+ */
+export declare function assertSocketSchemeReachable(url: string): void;
+/** The causes a browser cannot tell apart when a handshake fails, with the fix for each. */
+export declare function opaqueSocketFailureMessage(url: string): string;

package/dist/src/net/websocket.js

@@ -0,0 +1,54 @@
+import { socketUnreachable } from '../errors';
+/** `readyState` of an open connection. The same number in browsers and in `ws`. */
+export const WEBSOCKET_OPEN = 1;
+/**
+ * `new globalThis.WebSocket(url)`, resolved at call time.
+ *
+ * Never a stored reference, for the same reason as `defaultTransport`: a test that swaps
+ * the global after import must still be honoured. Node 20 has no global WebSocket at all,
+ * and a library that supports Node 20 cannot assume one, so its absence is reported with
+ * the one-line fix rather than as a `TypeError`.
+ */
+export const defaultWebSocketFactory = (url) => {
+    const WebSocketClass = globalThis
+        .WebSocket;
+    if (typeof WebSocketClass !== 'function') {
+        throw socketUnreachable('This runtime has no global WebSocket — Node 20 does not, Node 22 and every browser ' +
+            'do. Pass one explicitly: `webSocket: (url) => new WebSocket(url)` with ' +
+            '`import WebSocket from "ws"`.');
+    }
+    return new WebSocketClass(url);
+};
+/**
+ * The one socket failure a browser can be certain about before trying.
+ *
+ * An https page may not open a `ws://` socket; the browser refuses it outright and reports
+ * nothing useful, so the handshake would only turn a knowable cause into an opaque one.
+ */
+export function assertSocketSchemeReachable(url) {
+    const location = globalThis.location;
+    if (location?.protocol !== 'https:')
+        return;
+    let scheme;
+    try {
+        scheme = new URL(url).protocol;
+    }
+    catch {
+        return;
+    }
+    if (scheme !== 'ws:')
+        return;
+    throw socketUnreachable(`This page is served over https and the socket URL ${url} is ws://, so the browser ` +
+        'will block it as mixed content before it connects. Use the node\'s wss:// URL ' +
+        '(port 2082 by default), or serve this page over http while developing.');
+}
+/** The causes a browser cannot tell apart when a handshake fails, with the fix for each. */
+export function opaqueSocketFailureMessage(url) {
+    return (`Could not open the Geeq node socket at ${url}. A browser reports a failed handshake ` +
+        'with no detail, so this is one of four things: (1) the node\'s TLS certificate is ' +
+        'not trusted, which is common because nodes are addressed by bare IP — open the ' +
+        "node's https URL in a tab to see the interstitial; (2) this page is https and the " +
+        'socket is ws://, which browsers block; (3) the URL is wrong — the path is /ws/, with ' +
+        'the trailing slash, on the same port as the HTTP API; or (4) the node is down.');
+}
+//# sourceMappingURL=websocket.js.map

package/dist/src/net/websocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.js","sourceRoot":"","sources":["../../../src/net/websocket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAE7C,mFAAmF;AACnF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAA;AAkC/B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAyB,CAAC,GAAG,EAAE,EAAE;IACnE,MAAM,cAAc,GAAI,UAAqE;SAC1F,SAAS,CAAA;IACZ,IAAI,OAAO,cAAc,KAAK,UAAU,EAAE,CAAC;QACzC,MAAM,iBAAiB,CACrB,qFAAqF;YACnF,yEAAyE;YACzE,+BAA+B,CAClC,CAAA;IACH,CAAC;IACD,OAAO,IAAI,cAAc,CAAC,GAAG,CAAC,CAAA;AAChC,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAAC,GAAW;IACrD,MAAM,QAAQ,GAAI,UAAmD,CAAC,QAAQ,CAAA;IAC9E,IAAI,QAAQ,EAAE,QAAQ,KAAK,QAAQ;QAAE,OAAM;IAE3C,IAAI,MAAc,CAAA;IAClB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAA;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAM;IACR,CAAC;IACD,IAAI,MAAM,KAAK,KAAK;QAAE,OAAM;IAE5B,MAAM,iBAAiB,CACrB,qDAAqD,GAAG,4BAA4B;QAClF,gFAAgF;QAChF,wEAAwE,CAC3E,CAAA;AACH,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,OAAO,CACL,0CAA0C,GAAG,yCAAyC;QACtF,oFAAoF;QACpF,iFAAiF;QACjF,oFAAoF;QACpF,uFAAuF;QACvF,gFAAgF,CACjF,CAAA;AACH,CAAC"}

package/dist/src/runtime/bindings.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The single place the SDK reaches into the WebAssembly engine.
+ *
+ * Every binding is imported by name and re-exported as a real identifier, never
+ * looked up by string. A string-keyed lookup here would break under any consumer
+ * minifier that renames module bindings, and it would fail silently for exactly
+ * one code path — the failure mode this indirection exists to prevent.
+ */
+export { Keypair as WasmKeypair, WalletAddress as WasmWalletAddress, RecordType as WasmRecordType, CoinType as WasmCoinType, verify as wasmVerify, mnemonicToSeed as wasmMnemonicToSeed, generateSeedId as wasmGenerateSeedId, generateIrn as wasmGenerateIrn, IrnRecordType as WasmIrnRecordType, Payload as WasmPayload, UserAppTx as WasmUserAppTx, UserAppTxData as WasmUserAppTxData, UserValTx as WasmUserValTx, UserValTxData as WasmUserValTxData, AttestationSubgroupData as WasmAttestationSubgroupData, } from '../wasm/browser/geeq_core';

package/dist/src/runtime/bindings.js

@@ -0,0 +1,27 @@
+/**
+ * The single place the SDK reaches into the WebAssembly engine.
+ *
+ * Every binding is imported by name and re-exported as a real identifier, never
+ * looked up by string. A string-keyed lookup here would break under any consumer
+ * minifier that renames module bindings, and it would fail silently for exactly
+ * one code path — the failure mode this indirection exists to prevent.
+ */
+export { Keypair as WasmKeypair, WalletAddress as WasmWalletAddress, RecordType as WasmRecordType, CoinType as WasmCoinType, verify as wasmVerify, mnemonicToSeed as wasmMnemonicToSeed, generateSeedId as wasmGenerateSeedId, 
+// A proxy's account id, derived from its admin's public key and an index exactly as the
+// Geeq wallet derives it. See src/tx/proxy.ts.
+generateIrn as wasmGenerateIrn, IrnRecordType as WasmIrnRecordType, 
+// Transaction canonicalisation. The engine cannot *build* a transaction — every
+// transaction class it exposes has a private constructor — but it is the only
+// thing that can turn a Cap'n Proto message into the flattened byte form the
+// chain signs over, so structures are built with capnp and flattened here.
+Payload as WasmPayload, 
+// Both forms of the transaction are needed and they are NOT interchangeable. The
+// engine flattens `UserAppTxData` without the signature — that is the preimage the
+// signature is made over — and `UserAppTx` with it, which is what the chain hashes to
+// identify the transaction. See src/tx/attestation.ts.
+UserAppTx as WasmUserAppTx, UserAppTxData as WasmUserAppTxData, 
+// The validation-layer transaction — coin transfers — has the same two forms, but the
+// node identifies it by the Data (signature-excluded) flatten, not the signed one.
+// See src/tx/transfer.ts.
+UserValTx as WasmUserValTx, UserValTxData as WasmUserValTxData, AttestationSubgroupData as WasmAttestationSubgroupData, } from '../wasm/browser/geeq_core';
+//# sourceMappingURL=bindings.js.map

package/dist/src/runtime/bindings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.js","sourceRoot":"","sources":["../../../src/runtime/bindings.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,OAAO,IAAI,WAAW,EACtB,aAAa,IAAI,iBAAiB,EAClC,UAAU,IAAI,cAAc,EAC5B,QAAQ,IAAI,YAAY,EACxB,MAAM,IAAI,UAAU,EACpB,cAAc,IAAI,kBAAkB,EACpC,cAAc,IAAI,kBAAkB;AACpC,wFAAwF;AACxF,+CAA+C;AAC/C,WAAW,IAAI,eAAe,EAC9B,aAAa,IAAI,iBAAiB;AAClC,gFAAgF;AAChF,8EAA8E;AAC9E,6EAA6E;AAC7E,2EAA2E;AAC3E,OAAO,IAAI,WAAW;AACtB,iFAAiF;AACjF,mFAAmF;AACnF,sFAAsF;AACtF,uDAAuD;AACvD,SAAS,IAAI,aAAa,EAC1B,aAAa,IAAI,iBAAiB;AAClC,sFAAsF;AACtF,mFAAmF;AACnF,0BAA0B;AAC1B,SAAS,IAAI,aAAa,EAC1B,aAAa,IAAI,iBAAiB,EAClC,uBAAuB,IAAI,2BAA2B,GACvD,MAAM,2BAA2B,CAAA"}

package/dist/src/runtime/init.d.ts

@@ -0,0 +1,13 @@
+import type { InitOptions } from '../types';
+/**
+ * Load the Geeq engine. Idempotent and single-flight: concurrent callers share one
+ * load, and repeat calls after success resolve immediately.
+ *
+ * You rarely need to call this yourself — every async entry point in the SDK awaits
+ * it first. Call it at startup if you would rather pay the cost up front.
+ */
+export declare function initGeeq(options?: InitOptions): Promise<void>;
+/** True once the engine is loaded and the synchronous APIs are usable. */
+export declare function isGeeqReady(): boolean;
+/** @internal Guard for synchronous APIs that require a loaded engine. */
+export declare function assertReady(what: string): void;

package/dist/src/runtime/init.js

@@ -0,0 +1,40 @@
+import { GeeqError, notInitialized } from '../errors';
+import { loadWasm } from './wasm-loader.browser';
+let inflight = null;
+let ready = false;
+/**
+ * Load the Geeq engine. Idempotent and single-flight: concurrent callers share one
+ * load, and repeat calls after success resolve immediately.
+ *
+ * You rarely need to call this yourself — every async entry point in the SDK awaits
+ * it first. Call it at startup if you would rather pay the cost up front.
+ */
+export function initGeeq(options = {}) {
+    if (ready)
+        return Promise.resolve();
+    if (inflight === null) {
+        inflight = loadWasm(options.wasm)
+            .then(() => {
+            ready = true;
+        })
+            .catch((cause) => {
+            // Clear the cached promise so a later call can retry with, say, an
+            // explicit `wasm` source rather than being stuck with the first failure.
+            inflight = null;
+            throw new GeeqError('init-failed', 'Could not load the Geeq WebAssembly engine. If your bundler does not emit ' +
+                'geeq_core_bg.wasm automatically, pass its URL as initGeeq({ wasm }).', { cause });
+        });
+    }
+    return inflight;
+}
+/** True once the engine is loaded and the synchronous APIs are usable. */
+export function isGeeqReady() {
+    return ready;
+}
+/** @internal Guard for synchronous APIs that require a loaded engine. */
+export function assertReady(what) {
+    if (!ready) {
+        throw notInitialized(what);
+    }
+}
+//# sourceMappingURL=init.js.map

package/dist/src/runtime/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/runtime/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAErD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAEhD,IAAI,QAAQ,GAAyB,IAAI,CAAA;AACzC,IAAI,KAAK,GAAG,KAAK,CAAA;AAEjB;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,UAAuB,EAAE;IAChD,IAAI,KAAK;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;IAEnC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;aAC9B,IAAI,CAAC,GAAG,EAAE;YACT,KAAK,GAAG,IAAI,CAAA;QACd,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,mEAAmE;YACnE,yEAAyE;YACzE,QAAQ,GAAG,IAAI,CAAA;YACf,MAAM,IAAI,SAAS,CACjB,aAAa,EACb,4EAA4E;gBAC1E,sEAAsE,EACxE,EAAE,KAAK,EAAE,CACV,CAAA;QACH,CAAC,CAAC,CAAA;IACN,CAAC;IAED,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,WAAW;IACzB,OAAO,KAAK,CAAA;AACd,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,cAAc,CAAC,IAAI,CAAC,CAAA;IAC5B,CAAC;AACH,CAAC"}

package/dist/src/runtime/wasm-loader.browser.d.ts

@@ -0,0 +1,14 @@
+import type { WasmSource } from '../types';
+/**
+ * Browser loader: finds the engine's .wasm file and starts it.
+ *
+ * If the app passes its own `source`, that is used. Otherwise it is the .wasm file
+ * that ships next to this script in `dist/browser/`.
+ *
+ * `new URL('./geeq_core_bg.wasm', import.meta.url)` means "geeq_core_bg.wasm in the
+ * same folder as this file". Keep it written exactly this way: Vite, webpack, Rollup
+ * and Parcel spot this pattern and copy the .wasm into the app's build for you.
+ *
+ * The Node build swaps this module for `wasm-loader.node.ts` at bundle time.
+ */
+export declare function loadWasm(source?: WasmSource): Promise<void>;

package/dist/src/runtime/wasm-loader.browser.js

@@ -0,0 +1,20 @@
+import initWasm from '../wasm/browser/geeq_core';
+/**
+ * Browser loader: finds the engine's .wasm file and starts it.
+ *
+ * If the app passes its own `source`, that is used. Otherwise it is the .wasm file
+ * that ships next to this script in `dist/browser/`.
+ *
+ * `new URL('./geeq_core_bg.wasm', import.meta.url)` means "geeq_core_bg.wasm in the
+ * same folder as this file". Keep it written exactly this way: Vite, webpack, Rollup
+ * and Parcel spot this pattern and copy the .wasm into the app's build for you.
+ *
+ * The Node build swaps this module for `wasm-loader.node.ts` at bundle time.
+ */
+export async function loadWasm(source) {
+    const wasm = source ?? new URL('./geeq_core_bg.wasm', import.meta.url);
+    // `module_or_path` is the option name wasm-bindgen expects. Passing `wasm`
+    // directly instead also works, but prints a deprecation warning.
+    await initWasm({ module_or_path: wasm });
+}
+//# sourceMappingURL=wasm-loader.browser.js.map

package/dist/src/runtime/wasm-loader.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-loader.browser.js","sourceRoot":"","sources":["../../../src/runtime/wasm-loader.browser.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,2BAA2B,CAAA;AAGhD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAmB;IAChD,MAAM,IAAI,GAAG,MAAM,IAAI,IAAI,GAAG,CAAC,qBAAqB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAEtE,2EAA2E;IAC3E,iEAAiE;IACjE,MAAM,QAAQ,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAA;AAC1C,CAAC"}

package/dist/src/runtime/wasm-loader.node.d.ts

@@ -0,0 +1,7 @@
+import type { WasmSource } from '../types';
+/**
+ * Node loader: same job as the browser loader, but Node's `fetch` cannot read
+ * local files, so the .wasm is read off disk here and passed in as bytes.
+ * Used by the Node build; the test suite swaps in its own stub (see jest.config.js).
+ */
+export declare function loadWasm(source?: WasmSource): Promise<void>;

package/dist/src/runtime/wasm-loader.node.js

@@ -0,0 +1,14 @@
+import { readFile } from 'node:fs/promises';
+import initWasm from '../wasm/browser/geeq_core';
+/**
+ * Node loader: same job as the browser loader, but Node's `fetch` cannot read
+ * local files, so the .wasm is read off disk here and passed in as bytes.
+ * Used by the Node build; the test suite swaps in its own stub (see jest.config.js).
+ */
+export async function loadWasm(source) {
+    const wasm = source ?? (await readFile(new URL('./geeq_core_bg.wasm', import.meta.url)));
+    // `module_or_path` is the option name wasm-bindgen expects. Passing `wasm`
+    // directly instead also works, but prints a deprecation warning.
+    await initWasm({ module_or_path: wasm });
+}
+//# sourceMappingURL=wasm-loader.node.js.map

package/dist/src/runtime/wasm-loader.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-loader.node.js","sourceRoot":"","sources":["../../../src/runtime/wasm-loader.node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,QAAQ,MAAM,2BAA2B,CAAA;AAGhD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAmB;IAChD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,QAAQ,CAAC,IAAI,GAAG,CAAC,qBAAqB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IAExF,2EAA2E;IAC3E,iEAAiE;IACjE,MAAM,QAAQ,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAA;AAC1C,CAAC"}