@qubic.ts/sdk 0.1.0

package/src/tx/confirm.ts

@@ -0,0 +1,147 @@
+import type { QueryTransaction, RpcClient } from "../rpc/client.js";
+import { RpcError } from "../rpc/client.js";
+
+export type WaitForConfirmationInput = Readonly<{
+  txId: string;
+  targetTick: bigint | number;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+  signal?: AbortSignal;
+}>;
+
+export class TxConfirmationTimeoutError extends Error {
+  override name = "TxConfirmationTimeoutError";
+}
+
+export class TxNotFoundError extends Error {
+  override name = "TxNotFoundError";
+}
+
+export class TxConfirmationAbortedError extends Error {
+  override name = "TxConfirmationAbortedError";
+}
+
+export type TxConfirmationHelpersConfig = Readonly<{
+  rpc: RpcClient;
+  defaultTimeoutMs?: number;
+  defaultPollIntervalMs?: number;
+}>;
+
+export type TxConfirmationHelpers = Readonly<{
+  waitForConfirmation(input: WaitForConfirmationInput): Promise<void>;
+  waitForConfirmedTransaction(input: WaitForConfirmationInput): Promise<QueryTransaction>;
+}>;
+
+export function createTxConfirmationHelpers(
+  config: TxConfirmationHelpersConfig,
+): TxConfirmationHelpers {
+  const defaultTimeoutMs = config.defaultTimeoutMs ?? 60_000;
+  const defaultPollIntervalMs = config.defaultPollIntervalMs ?? 1_000;
+
+  const waitForConfirmedTransaction = async (
+    input: WaitForConfirmationInput,
+  ): Promise<QueryTransaction> => {
+    const start = Date.now();
+    const timeoutMs = input.timeoutMs ?? defaultTimeoutMs;
+    const pollIntervalMs = input.pollIntervalMs ?? defaultPollIntervalMs;
+    const targetTick = toBigint(input.targetTick);
+    let reachedTargetTick = false;
+    let sawNotFoundAfterTarget = false;
+
+    const controller = new AbortController();
+    const signals: AbortSignal[] = [controller.signal];
+    if (input.signal) signals.push(input.signal);
+    const signal = anySignal(signals);
+
+    if (signal.aborted) throw new TxConfirmationAbortedError("Confirmation aborted");
+
+    while (true) {
+      if (signal.aborted) throw new TxConfirmationAbortedError("Confirmation aborted");
+      if (Date.now() - start > timeoutMs) {
+        if (reachedTargetTick && sawNotFoundAfterTarget) {
+          throw new TxNotFoundError(
+            `Transaction ${input.txId} not found after target tick ${targetTick}`,
+          );
+        }
+        throw new TxConfirmationTimeoutError(
+          `Timed out waiting for confirmation of ${input.txId} (target tick ${targetTick})`,
+        );
+      }
+
+      const lastProcessed = await config.rpc.query.getLastProcessedTick();
+      if (lastProcessed.tickNumber < targetTick) {
+        await sleep(pollIntervalMs, signal);
+        continue;
+      }
+      reachedTargetTick = true;
+
+      try {
+        return await config.rpc.query.getTransactionByHash(input.txId);
+      } catch (err) {
+        if (err instanceof RpcError && err.details.status === 404) {
+          sawNotFoundAfterTarget = true;
+          await sleep(pollIntervalMs, signal);
+          continue;
+        }
+        throw err;
+      }
+    }
+  };
+
+  return {
+    async waitForConfirmation(input: WaitForConfirmationInput): Promise<void> {
+      await waitForConfirmedTransaction(input);
+    },
+
+    async waitForConfirmedTransaction(input: WaitForConfirmationInput): Promise<QueryTransaction> {
+      return waitForConfirmedTransaction(input);
+    },
+  };
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const id = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+
+    const onAbort = () => {
+      cleanup();
+      reject(new TxConfirmationAbortedError("Confirmation aborted"));
+    };
+
+    const cleanup = () => {
+      clearTimeout(id);
+      signal.removeEventListener("abort", onAbort);
+    };
+
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function toBigint(value: bigint | number): bigint {
+  if (typeof value === "bigint") return value;
+  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+    throw new TypeError("Expected an integer");
+  }
+  return BigInt(value);
+}
+
+function anySignal(signals: readonly AbortSignal[]): AbortSignal {
+  if (signals.length === 0) return new AbortController().signal;
+  if (signals.length === 1) {
+    const only = signals[0];
+    if (!only) return new AbortController().signal;
+    return only;
+  }
+
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  for (const s of signals) {
+    if (s.aborted) return s;
+    s.addEventListener("abort", onAbort, { once: true });
+  }
+  return controller.signal;
+}

package/src/tx/tx-queue.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "bun:test";
+import { TxQueue, TxQueueError } from "./tx-queue.js";
+
+function createDeferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject } as const;
+}
+
+describe("TxQueue", () => {
+  it("waits for confirmation by default (single tx per source)", async () => {
+    const confirmations = new Map<string, ReturnType<typeof createDeferred<void>>>();
+    const submitOrder: string[] = [];
+
+    const q = new TxQueue({
+      async confirm({ txId, signal }) {
+        if (signal.aborted) throw new Error("aborted");
+        const d = confirmations.get(txId);
+        if (!d) throw new Error(`missing deferred for ${txId}`);
+        return d.promise;
+      },
+    });
+
+    confirmations.set("tx1", createDeferred<void>());
+    confirmations.set("tx2", createDeferred<void>());
+
+    const p1 = q.enqueue({
+      sourceIdentity: "A",
+      targetTick: 10,
+      async submit() {
+        submitOrder.push("tx1");
+        return { txId: "tx1", result: "r1" };
+      },
+    });
+
+    const p2 = q.enqueue({
+      sourceIdentity: "A",
+      targetTick: 11,
+      async submit() {
+        submitOrder.push("tx2");
+        return { txId: "tx2", result: "r2" };
+      },
+    });
+
+    await Promise.resolve();
+    expect(submitOrder).toEqual(["tx1"]);
+
+    mustGet(confirmations, "tx1").resolve();
+    const r1 = await p1;
+    expect(r1.status).toBe("confirmed");
+
+    mustGet(confirmations, "tx2").resolve();
+    const r2 = await p2;
+    expect(r2.status).toBe("confirmed");
+    expect(submitOrder).toEqual(["tx1", "tx2"]);
+  });
+
+  it("rejects enqueue when policy is reject", async () => {
+    const confirmations = new Map<string, ReturnType<typeof createDeferred<void>>>();
+    confirmations.set("tx1", createDeferred<void>());
+
+    const q = new TxQueue({
+      policy: "reject",
+      async confirm({ txId }) {
+        return mustGet(confirmations, txId).promise;
+      },
+    });
+
+    void q.enqueue({
+      sourceIdentity: "A",
+      targetTick: 10,
+      async submit() {
+        return { txId: "tx1", result: null };
+      },
+    });
+
+    await expect(
+      q.enqueue({
+        sourceIdentity: "A",
+        targetTick: 11,
+        async submit() {
+          return { txId: "tx2", result: null };
+        },
+      }),
+    ).rejects.toBeInstanceOf(TxQueueError);
+
+    mustGet(confirmations, "tx1").resolve();
+  });
+
+  it("replaces with higher tick when policy is replaceHigherTick", async () => {
+    const confirmations = new Map<string, ReturnType<typeof createDeferred<void>>>();
+    confirmations.set("tx1", createDeferred<void>());
+    confirmations.set("tx2", createDeferred<void>());
+
+    const q = new TxQueue({
+      policy: "replaceHigherTick",
+      async confirm({ txId, signal }) {
+        if (signal.aborted) throw new Error("aborted");
+        return mustGet(confirmations, txId).promise;
+      },
+    });
+
+    const p1 = q.enqueue({
+      sourceIdentity: "A",
+      targetTick: 10,
+      async submit() {
+        return { txId: "tx1", result: null };
+      },
+    });
+
+    const p2 = q.enqueue({
+      sourceIdentity: "A",
+      targetTick: 15,
+      async submit() {
+        return { txId: "tx2", result: null };
+      },
+    });
+
+    const r1 = await p1;
+    expect(r1.status).toBe("superseded");
+
+    await expect(
+      q.enqueue({
+        sourceIdentity: "A",
+        targetTick: 14,
+        async submit() {
+          return { txId: "tx3", result: null };
+        },
+      }),
+    ).rejects.toBeInstanceOf(TxQueueError);
+
+    mustGet(confirmations, "tx2").resolve();
+    const r2 = await p2;
+    expect(r2.status).toBe("confirmed");
+  });
+});
+
+function mustGet<K, V>(map: ReadonlyMap<K, V>, key: K): V {
+  const value = map.get(key);
+  if (!value) throw new Error(`Missing key: ${String(key)}`);
+  return value;
+}

package/src/tx/tx-queue.ts

@@ -0,0 +1,214 @@
+export type TxQueuePolicy = "waitForConfirm" | "reject" | "replaceHigherTick";
+
+export type TxQueueItemStatus =
+  | "pending"
+  | "submitted"
+  | "confirming"
+  | "confirmed"
+  | "failed"
+  | "superseded";
+
+export type TxQueueConfirmFn = (input: {
+  txId: string;
+  targetTick: bigint;
+  signal: AbortSignal;
+}) => Promise<void>;
+
+export type TxQueueConfig = Readonly<{
+  policy?: TxQueuePolicy;
+  confirm: TxQueueConfirmFn;
+}>;
+
+export type EnqueueTxInput<Result> = Readonly<{
+  sourceIdentity: string;
+  targetTick: bigint | number;
+  submit: (input: { signal: AbortSignal }) => Promise<Readonly<{ txId: string; result: Result }>>;
+  confirm?: TxQueueConfirmFn;
+}>;
+
+export type TxQueueItem<Result> = Readonly<{
+  id: string;
+  sourceIdentity: string;
+  targetTick: bigint;
+  createdAtMs: number;
+  status: TxQueueItemStatus;
+  txId?: string;
+  result?: Result;
+  error?: unknown;
+}>;
+
+export class TxQueueError extends Error {
+  override name = "TxQueueError";
+}
+
+export class TxQueue {
+  readonly #policy: TxQueuePolicy;
+  readonly #confirm: TxQueueConfirmFn;
+
+  readonly #activeBySource = new Map<string, ActiveItem<unknown>>();
+  readonly #itemsBySource = new Map<string, TxQueueItem<unknown>[]>();
+
+  constructor(config: TxQueueConfig) {
+    this.#policy = config.policy ?? "waitForConfirm";
+    this.#confirm = config.confirm;
+  }
+
+  getItems(sourceIdentity?: string): readonly TxQueueItem<unknown>[] {
+    if (sourceIdentity) return (this.#itemsBySource.get(sourceIdentity) ?? []).slice();
+    const all: TxQueueItem<unknown>[] = [];
+    for (const items of this.#itemsBySource.values()) all.push(...items);
+    return all;
+  }
+
+  getActive(sourceIdentity: string): TxQueueItem<unknown> | undefined {
+    return this.#activeBySource.get(sourceIdentity)?.item;
+  }
+
+  async enqueue<Result>(input: EnqueueTxInput<Result>): Promise<TxQueueItem<Result>> {
+    const sourceIdentity = input.sourceIdentity;
+    const targetTick = toBigint(input.targetTick);
+    const policy = this.#policy;
+
+    const existing = this.#activeBySource.get(sourceIdentity);
+    if (existing) {
+      if (policy === "waitForConfirm") {
+        await existing.done;
+      } else if (policy === "reject") {
+        throw new TxQueueError(
+          `TxQueue rejected enqueue: source ${sourceIdentity} already has an active transaction`,
+        );
+      } else if (policy === "replaceHigherTick") {
+        if (targetTick <= existing.item.targetTick) {
+          throw new TxQueueError(
+            `TxQueue rejected enqueue: targetTick ${targetTick} must be higher than active targetTick ${existing.item.targetTick}`,
+          );
+        }
+        existing.supersede();
+      } else {
+        throw new TxQueueError(`Unknown policy: ${policy}`);
+      }
+    }
+
+    const id = crypto.randomUUID();
+    const controller = new AbortController();
+    const createdAtMs = Date.now();
+    const deferred = createDeferred<TxQueueItem<Result>>();
+
+    const item: MutableTxQueueItem<Result> = {
+      id,
+      sourceIdentity,
+      targetTick,
+      createdAtMs,
+      status: "pending",
+    };
+
+    const active: ActiveItem<Result> = {
+      item,
+      controller,
+      confirm: input.confirm ?? this.#confirm,
+      done: deferred.promise,
+      supersede: () => {
+        if (
+          item.status === "confirmed" ||
+          item.status === "failed" ||
+          item.status === "superseded"
+        ) {
+          return;
+        }
+        item.status = "superseded";
+        controller.abort();
+        deferred.resolve({ ...item });
+        this.#activeBySource.delete(sourceIdentity);
+      },
+    };
+
+    this.#activeBySource.set(sourceIdentity, active as ActiveItem<unknown>);
+    this.#pushItem(sourceIdentity, item as TxQueueItem<unknown>);
+
+    void this.#run(active, input, deferred);
+    return deferred.promise;
+  }
+
+  #pushItem(sourceIdentity: string, item: TxQueueItem<unknown>) {
+    const list = this.#itemsBySource.get(sourceIdentity);
+    if (list) list.push(item);
+    else this.#itemsBySource.set(sourceIdentity, [item]);
+  }
+
+  async #run<Result>(
+    active: ActiveItem<Result>,
+    input: EnqueueTxInput<Result>,
+    deferred: Deferred<TxQueueItem<Result>>,
+  ) {
+    const item = active.item;
+    try {
+      const submitted = await input.submit({ signal: active.controller.signal });
+      if (getStatus(item) === "superseded") return;
+
+      item.status = "submitted";
+      item.txId = submitted.txId;
+      item.result = submitted.result;
+
+      item.status = "confirming";
+      await active.confirm({
+        txId: submitted.txId,
+        targetTick: item.targetTick,
+        signal: active.controller.signal,
+      });
+      if (getStatus(item) === "superseded") return;
+
+      item.status = "confirmed";
+      deferred.resolve({ ...item });
+    } catch (err) {
+      if (getStatus(item) === "superseded") return;
+      item.status = "failed";
+      item.error = err;
+      deferred.resolve({ ...item });
+    } finally {
+      const current = this.#activeBySource.get(item.sourceIdentity);
+      if (current?.item.id === item.id) {
+        this.#activeBySource.delete(item.sourceIdentity);
+      }
+    }
+  }
+}
+
+type MutableTxQueueItem<Result> = {
+  -readonly [K in keyof TxQueueItem<Result>]: TxQueueItem<Result>[K];
+};
+
+type ActiveItem<Result> = Readonly<{
+  item: MutableTxQueueItem<Result>;
+  controller: AbortController;
+  confirm: TxQueueConfirmFn;
+  done: Promise<TxQueueItem<Result>>;
+  supersede: () => void;
+}>;
+
+type Deferred<T> = Readonly<{
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (error: unknown) => void;
+}>;
+
+function createDeferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function toBigint(value: bigint | number): bigint {
+  if (typeof value === "bigint") return value;
+  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+    throw new TypeError("Expected an integer");
+  }
+  return BigInt(value);
+}
+
+function getStatus(item: { status: TxQueueItemStatus }): TxQueueItemStatus {
+  return item.status;
+}

package/src/tx/tx.ts

@@ -0,0 +1,36 @@
+import type { BroadcastTransactionResult, QueryTransaction, RpcClient } from "../rpc/client.js";
+import type { TxConfirmationHelpers, WaitForConfirmationInput } from "./confirm.js";
+import { createTxConfirmationHelpers } from "./confirm.js";
+
+export type TxHelpersConfig = Readonly<{
+  rpc: RpcClient;
+  confirm?: TxConfirmationHelpers;
+}>;
+
+export type TxHelpers = Readonly<{
+  broadcastSigned(txBytes: Uint8Array | string): Promise<BroadcastTransactionResult>;
+  waitForConfirmation(input: WaitForConfirmationInput): Promise<void>;
+  waitForConfirmedTransaction(input: WaitForConfirmationInput): Promise<QueryTransaction>;
+}>;
+
+export function createTxHelpers(config: TxHelpersConfig): TxHelpers {
+  const confirm =
+    config.confirm ??
+    createTxConfirmationHelpers({
+      rpc: config.rpc,
+    });
+
+  return {
+    async broadcastSigned(txBytes: Uint8Array | string): Promise<BroadcastTransactionResult> {
+      return config.rpc.live.broadcastTransaction(txBytes);
+    },
+
+    async waitForConfirmation(input: WaitForConfirmationInput): Promise<void> {
+      return confirm.waitForConfirmation(input);
+    },
+
+    async waitForConfirmedTransaction(input: WaitForConfirmationInput): Promise<QueryTransaction> {
+      return confirm.waitForConfirmedTransaction(input);
+    },
+  };
+}

package/src/vault/types.ts

@@ -0,0 +1,131 @@
+export type ScryptKdfParams = Readonly<{
+  N: number;
+  r: number;
+  p: number;
+  dkLen: number;
+  saltBase64: string;
+}>;
+
+export type Pbkdf2Hash = "SHA-256" | "SHA-384" | "SHA-512";
+
+export type Pbkdf2KdfParams = Readonly<{
+  iterations: number;
+  hash: Pbkdf2Hash;
+  dkLen: number;
+  saltBase64: string;
+}>;
+
+export type VaultKdfParams = ScryptKdfParams | Pbkdf2KdfParams;
+
+export type VaultKdf =
+  | Readonly<{
+      name: "scrypt";
+      params: ScryptKdfParams;
+    }>
+  | Readonly<{
+      name: "pbkdf2";
+      params: Pbkdf2KdfParams;
+    }>;
+
+export type VaultHeader = Readonly<{
+  vaultVersion: number;
+  kdf: VaultKdf;
+}>;
+
+export type VaultEntryEncrypted = Readonly<{
+  nonceBase64: string;
+  ciphertextBase64: string;
+  tagBase64: string;
+}>;
+
+export type VaultEntry = Readonly<{
+  name: string;
+  identity: string;
+  seedIndex: number;
+  createdAt: string;
+  updatedAt: string;
+  encrypted: VaultEntryEncrypted;
+}>;
+
+export type VaultSummary = Readonly<{
+  name: string;
+  identity: string;
+  seedIndex: number;
+  createdAt: string;
+  updatedAt: string;
+}>;
+
+export type VaultExport = VaultHeader & Readonly<{ entries: readonly VaultEntry[] }>;
+
+export class VaultError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "VaultError";
+  }
+}
+
+export class VaultNotFoundError extends VaultError {
+  constructor(path: string) {
+    super(`Vault file not found: ${path}`);
+    this.name = "VaultNotFoundError";
+  }
+}
+
+export class VaultInvalidPassphraseError extends VaultError {
+  constructor() {
+    super("Invalid passphrase or corrupted vault data");
+    this.name = "VaultInvalidPassphraseError";
+  }
+}
+
+export class VaultEntryNotFoundError extends VaultError {
+  constructor(ref: string) {
+    super(`Vault entry not found: ${ref}`);
+    this.name = "VaultEntryNotFoundError";
+  }
+}
+
+export class VaultEntryExistsError extends VaultError {
+  constructor(name: string) {
+    super(`Vault entry already exists: ${name}`);
+    this.name = "VaultEntryExistsError";
+  }
+}
+
+export type SeedVault = Readonly<{
+  path: string;
+  list(): readonly VaultSummary[];
+  getEntry(ref: string): VaultEntry;
+  getIdentity(ref: string): string;
+  signer(ref: string): Readonly<{ fromVault: string }>;
+  getSeed(ref: string): Promise<string>;
+  addSeed(
+    input: Readonly<{ name: string; seed: string; seedIndex?: number; overwrite?: boolean }>,
+  ): Promise<VaultSummary>;
+  remove(ref: string): Promise<void>;
+  rotatePassphrase(newPassphrase: string): Promise<void>;
+  exportEncrypted(): VaultExport;
+  exportJson(): string;
+  importEncrypted(
+    input: VaultExport | string,
+    options?: Readonly<{ mode?: "merge" | "replace"; sourcePassphrase?: string }>,
+  ): Promise<void>;
+  getSeedSource(ref: string): Promise<Readonly<{ fromSeed: string }>>;
+  save(): Promise<void>;
+  close(): Promise<void>;
+}>;
+
+export type OpenSeedVaultInput = Readonly<{
+  path: string;
+  passphrase: string;
+  create?: boolean;
+  autoSave?: boolean;
+  lock?: boolean;
+  lockTimeoutMs?: number;
+  kdfParams?: Readonly<{
+    N?: number;
+    r?: number;
+    p?: number;
+    dkLen?: number;
+  }>;
+}>;