@geeqdev/geeq-sdk 0.1.0 → 0.2.0

package/dist/src/socket/tracked-tx.d.ts

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

package/dist/src/socket/tracked-tx.js

@@ -0,0 +1,212 @@
+/**
+ * Hand an error thrown by application code to the platform, without letting it stop the
+ * SDK delivering the same event to everyone else.
+ *
+ * @internal
+ */
+export function reportListenerError(error) {
+    const report = globalThis.reportError;
+    if (typeof report === 'function')
+        report(error);
+    else
+        console.error(error);
+}
+/**
+ * One submitted transaction, followed to its verdict.
+ *
+ * Returned by {@link GeeqSocket.track}. It collapses the node's four verdicts, some of
+ * which arrive more than once and one of which is only usually final, into one of three
+ * outcomes an application can branch on — and it never rejects, because a rejected
+ * transaction is an answer, not a failure:
+ *
+ * ```ts
+ * const outcome = await tracked.settled()
+ * if (outcome.status === 'confirmed') …
+ * else if (outcome.status === 'rejected') show(outcome.reason, outcome.message)
+ * else checkLedgerBeforeRetrying()          // 'unknown'
+ * ```
+ *
+ * In a reactive framework, keep it raw (Vue's `markRaw`) and re-read `status` and
+ * `events` from {@link onChange}.
+ */
+export class GeeqTrackedTx {
+    /** @internal */
+    constructor(init) {
+        this.id = init.id;
+        const hidden = (key, value, writable = false) => {
+            Object.defineProperty(this, key, { value, enumerable: false, writable });
+        };
+        let resolve;
+        const promise = new Promise((settle) => {
+            resolve = settle;
+        });
+        hidden('received', []);
+        hidden('listeners', new Set());
+        hidden('nonsaneGraceMs', init.nonsaneGraceMs);
+        hidden('detach', init.detach);
+        hidden('promise', promise);
+        hidden('resolve', resolve);
+        hidden('current', undefined, true);
+        hidden('grace', null, true);
+        hidden('deadline', init.timeoutMs > 0
+            ? setTimeout(() => {
+                this.finish({
+                    status: 'unknown',
+                    id: this.id,
+                    reason: 'timeout',
+                    message: `No final status for transaction ${this.id} within ${init.timeoutMs}ms. ` +
+                        'That is not a rejection: statuses sent while the socket was reconnecting ' +
+                        'are lost. Check the ledger — whether the account nonce has moved on — ' +
+                        'before sending it again.',
+                    at: new Date(),
+                });
+            }, init.timeoutMs)
+            : null, true);
+    }
+    /** `pending`, then `confirmed`, `rejected` or `unknown` — once, and for good. */
+    get status() {
+        return this.current?.status ?? 'pending';
+    }
+    /** The outcome, once there is one. */
+    get outcome() {
+        return this.current;
+    }
+    /** Every status event received for this transaction, oldest first. */
+    get events() {
+        return [...this.received];
+    }
+    /** Resolves with the outcome. Never rejects — see the class notes. */
+    settled() {
+        return this.promise;
+    }
+    /**
+     * Call `listener` whenever an event arrives for this transaction or it settles.
+     *
+     * Returns the function that removes it. Read {@link status}, {@link events} and
+     * {@link outcome} inside; they are already up to date.
+     */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Report that the node refused the submission — answered it with an error status.
+     *
+     * Settles it `rejected` at once. A refused transaction never reaches a block, so no
+     * status event would ever arrive to settle it, and waiting would only turn a clear
+     * answer into a timeout. Do **not** call this when the POST failed to arrive at all
+     * (a network error): the node may have it, so leave it tracked.
+     */
+    refused(refusal = {}) {
+        if (this.current !== undefined)
+            return;
+        const nonsane = this.received.find((event) => event.verdict === 'nonsane');
+        const said = refusal.message ?? nonsane?.error;
+        this.finish({
+            status: 'rejected',
+            id: this.id,
+            reason: 'refused',
+            message: said === undefined || said === ''
+                ? `The node refused transaction ${this.id}` +
+                    (refusal.status === undefined ? '.' : ` with HTTP ${refusal.status}.`)
+                : said,
+            event: nonsane,
+            httpStatus: refusal.status,
+            at: new Date(),
+        });
+    }
+    /** Stop tracking. Settles `unknown` with reason `released` if it was still pending. */
+    release() {
+        this.abandon('released', `Tracking of transaction ${this.id} was released.`);
+    }
+    /** @internal Settle as unknown because the socket is going away, or on release. */
+    abandon(reason, message) {
+        this.finish({ status: 'unknown', id: this.id, reason, message, at: new Date() });
+    }
+    /**
+     * @internal Take one status event for this transaction.
+     *
+     * The only place the protocol's rules live. First-event-wins would report false
+     * failures: a `nonsane` can be followed by a real verdict when a node carries its buffer
+     * over a restart, so it only settles if nothing final follows within the grace window.
+     * Everything after the outcome — a second node's copy, a duplicate — is ignored.
+     */
+    receive(event) {
+        if (this.current !== undefined)
+            return;
+        this.received.push(event);
+        if (event.verdict === 'nonsane') {
+            if (this.grace === null) {
+                this.grace = setTimeout(() => {
+                    this.finish({
+                        status: 'rejected',
+                        id: this.id,
+                        reason: 'nonsane',
+                        message: event.error ?? 'The node refused this transaction.',
+                        event,
+                        httpStatus: undefined,
+                        at: new Date(),
+                    });
+                }, this.nonsaneGraceMs);
+            }
+            this.notify();
+            return;
+        }
+        if (event.verdict === 'valid') {
+            this.finish({ status: 'confirmed', id: this.id, event, at: new Date() });
+            return;
+        }
+        this.finish({
+            status: 'rejected',
+            id: this.id,
+            reason: event.verdict === 'invalid' ? 'invalid' : 'incorrectly-included',
+            message: event.error ??
+                (event.verdict === 'invalid'
+                    ? 'The chain found this transaction invalid when committing the block.'
+                    : 'This transaction was carried by a node the chain judged dishonest.'),
+            event,
+            httpStatus: undefined,
+            at: new Date(),
+        });
+    }
+    finish(outcome) {
+        if (this.current !== undefined)
+            return;
+        this.current = Object.freeze(outcome);
+        if (this.deadline !== null)
+            clearTimeout(this.deadline);
+        if (this.grace !== null)
+            clearTimeout(this.grace);
+        this.deadline = null;
+        this.grace = null;
+        this.detach();
+        this.resolve(this.current);
+        this.notify();
+    }
+    notify() {
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(this);
+            }
+            catch (error) {
+                reportListenerError(error);
+            }
+        }
+    }
+    toJSON() {
+        return {
+            id: this.id,
+            status: this.status,
+            events: this.received.map((event) => event.verdict),
+            ...(this.current?.status === 'rejected' || this.current?.status === 'unknown'
+                ? { reason: this.current.reason }
+                : {}),
+        };
+    }
+    toString() {
+        return `GeeqTrackedTx(${this.id}, ${this.status})`;
+    }
+}
+//# sourceMappingURL=tracked-tx.js.map

package/dist/src/socket/tracked-tx.js.map

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

package/dist/src/socket/tx-status.d.ts

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

package/dist/src/socket/tx-status.js

@@ -0,0 +1,72 @@
+import { toBase64 } from '../encoding/base64';
+/** The wire carries names, but the node's own enum is numbered; accept either. */
+const VERDICTS = [
+    'nonsane',
+    'incorrectlyIncluded',
+    'invalid',
+    'valid',
+];
+function optionalNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function verdictOf(value) {
+    if (typeof value === 'number')
+        return VERDICTS[value];
+    if (typeof value === 'string') {
+        return VERDICTS.find((verdict) => verdict === value);
+    }
+    return undefined;
+}
+/** The node renders timestamps as `Date:<Date#toString()>`. */
+function dateOf(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const parsed = Date.parse(value.replace(/^Date:/u, ''));
+    return Number.isNaN(parsed) ? undefined : new Date(parsed);
+}
+/**
+ * Read a `uut_status` payload, or `undefined` when it is not one this SDK understands.
+ *
+ * Tolerant of the shapes nodes have actually sent: `publicKeys` as an array or the older
+ * single `publicKey`, the verdict as a name or as the node's enum number.
+ *
+ * @internal
+ */
+export function parseTxStatus(payload) {
+    if (payload === null || typeof payload !== 'object')
+        return undefined;
+    const fields = payload;
+    const id = fields.refHash;
+    const verdict = verdictOf(fields.status);
+    if (typeof id !== 'string' || id === '' || verdict === undefined)
+        return undefined;
+    const keys = fields.publicKeys;
+    const signer = Array.isArray(keys)
+        ? keys.find((key) => typeof key === 'string')
+        : typeof fields.publicKey === 'string'
+            ? fields.publicKey
+            : undefined;
+    const direction = fields.type === 'incoming' || fields.type === 'outgoing' ? fields.type : undefined;
+    return Object.freeze({
+        id,
+        verdict,
+        isValid: typeof fields.isValid === 'boolean' ? fields.isValid : verdict === 'valid',
+        error: typeof fields.error === 'string' && fields.error !== '' ? fields.error : undefined,
+        blockNumber: optionalNumber(fields.blockNumber),
+        vlbBlock: optionalNumber(fields.vlbBlock),
+        direction,
+        signer,
+        createdAt: dateOf(fields.createdAt),
+        raw: payload,
+    });
+}
+/**
+ * A transaction's id as status events name it: its `transactionHash`, in base64.
+ *
+ * Works on anything the SDK builds — an attestation or a transfer — because each already
+ * carries the hash its kind is identified by, and the two kinds are hashed differently.
+ */
+export function transactionIdOf(tx) {
+    return toBase64(tx.transactionHash);
+}
+//# sourceMappingURL=tx-status.js.map

package/dist/src/socket/tx-status.js.map

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

package/dist/src/tx/attestation.d.ts

@@ -0,0 +1,60 @@
+import { Message } from 'capnp-ts';
+import { AttestationSubgroup as CapnpAttestationSubgroup } from '../capnp/payload.capnp';
+import { UserAppTx as CapnpUserAppTx } from '../capnp/userAppTx.capnp';
+import type { AttestationTx, AttestationTxInput, GeeqKeypair } from '../types';
+/**
+ * Build and sign an attestation subgroup: a hash, its labels, and the account vouching
+ * for them. An attestation and an NFT mint carry the same subgroup; it names the signer's
+ * own account in one and the minting proxy in the other.
+ *
+ * Also returns the signature-excluded flatten — what was signed, and what an NFT's id is
+ * the hash of.
+ *
+ * @internal
+ */
+export declare function signAttestationSubgroup(input: {
+    readonly keypair: GeeqKeypair;
+    readonly attestHash: Uint8Array;
+    readonly metadata: readonly Uint8Array[];
+    readonly chainNumber: number;
+    readonly accountId: Uint8Array;
+}): {
+    subgroup: CapnpAttestationSubgroup;
+    flattened: Uint8Array;
+};
+/**
+ * A payload as it is submitted, the hash its transaction references it by, and its
+ * flattened size, which the fee charges for.
+ *
+ * @internal
+ */
+export declare function packPayload(message: Message): {
+    payload: string;
+    refHashPayload: Uint8Array;
+    bytes: number;
+};
+/**
+ * Sign a built application-layer transaction and work out the id the node files it under.
+ * Every application-layer transaction — an attestation, an NFT mint — ends this way.
+ *
+ * @internal
+ */
+export declare function signAppTx(message: Message, tx: CapnpUserAppTx, keypair: GeeqKeypair): {
+    transaction: string;
+    transactionHash: Uint8Array;
+    bytes: number;
+};
+/**
+ * Build and sign an attestation transaction. Synchronous; requires a loaded engine.
+ *
+ * This function is offline: it opens no sockets and reads no ledger. It needs chain
+ * state that only a node can supply, so either pass the four values yourself or let
+ * {@link GeeqChain} read them and hand you a `chainState`.
+ *
+ * The transaction is signed but **not submitted**. Post
+ * {@link AttestationTx.transaction} and {@link AttestationTx.payload} to the node named
+ * by {@link AttestationTx.nodeUrl}.
+ */
+export declare function createAttestationTxSync(input: AttestationTxInput): AttestationTx;
+/** Build and sign an attestation transaction, loading the engine if needed. */
+export declare function createAttestationTx(input: AttestationTxInput): Promise<AttestationTx>;