@qubic.ts/sdk 0.1.0

package/src/sdk.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "bun:test";
+import { createSdk } from "./sdk.js";
+
+describe("sdk scaffold", () => {
+  it("creates a sdk object", () => {
+    const sdk = createSdk();
+    expect(sdk).toHaveProperty("rpc");
+    expect(sdk).toHaveProperty("tx");
+    expect(sdk).toHaveProperty("txQueue");
+    expect(sdk).toHaveProperty("tick");
+    expect(sdk).toHaveProperty("transactions");
+    expect(sdk).toHaveProperty("transfers");
+    expect(sdk).toHaveProperty("contracts");
+    expect(sdk).toHaveProperty("assets");
+    expect(sdk).toHaveProperty("bob");
+  });
+
+  it("honors txQueue disabled and wires optional assets helper", async () => {
+    const sdk = createSdk({
+      txQueue: { enabled: false },
+      assets: {
+        requestAssets: async () => [new Uint8Array(56)],
+      },
+    });
+
+    expect(sdk.txQueue).toBeUndefined();
+    expect(sdk.assets).toBeDefined();
+    await expect(
+      sdk.assets?.listByUniverseIndex({
+        universeIndex: 1,
+      }),
+    ).resolves.toBeDefined();
+  });
+});

package/src/sdk.ts

@@ -0,0 +1,113 @@
+import { createAssetsHelpers } from "./assets.js";
+import { createBobClient } from "./bob/client.js";
+import { createContractHelpers } from "./contracts.js";
+import type { FetchLike } from "./http.js";
+import type { RetryConfig } from "./retry.js";
+import { createRpcClient } from "./rpc/client.js";
+import { createTickHelpers } from "./tick.js";
+import { createTransactionHelpers } from "./transactions.js";
+import { createTransferHelpers } from "./transfers.js";
+import { createTxConfirmationHelpers } from "./tx/confirm.js";
+import { createTxHelpers } from "./tx/tx.js";
+import type { TxQueuePolicy } from "./tx/tx-queue.js";
+import { TxQueue } from "./tx/tx-queue.js";
+import type { SeedVault } from "./vault/types.js";
+
+export type SdkConfig = Readonly<{
+  /** Partner RPC base URL (recommended: `https://rpc.qubic.org`). */
+  baseUrl?: string;
+  /** Optional custom fetch implementation (for testing, instrumentation, etc). */
+  fetch?: FetchLike;
+  rpc?: Readonly<{
+    headers?: Readonly<Record<string, string>>;
+    retry?: RetryConfig;
+  }>;
+  tick?: Readonly<{
+    minOffset?: bigint | number;
+    defaultOffset?: bigint | number;
+    maxOffset?: bigint | number;
+  }>;
+  tx?: Readonly<{
+    confirmTimeoutMs?: number;
+    confirmPollIntervalMs?: number;
+  }>;
+  txQueue?: Readonly<{
+    enabled?: boolean;
+    policy?: TxQueuePolicy;
+  }>;
+  contracts?: Readonly<{
+    defaultRetries?: number;
+    defaultRetryDelayMs?: number;
+  }>;
+  assets?: Readonly<{
+    requestAssets?: (request: Uint8Array, signal?: AbortSignal) => Promise<readonly Uint8Array[]>;
+  }>;
+  vault?: SeedVault;
+  bob?: Readonly<{
+    baseUrl?: string;
+    fetch?: FetchLike;
+    headers?: Readonly<Record<string, string>>;
+    retry?: RetryConfig;
+  }>;
+}>;
+
+export function createSdk(config: SdkConfig = {}) {
+  const rpc = createRpcClient({
+    baseUrl: config.baseUrl,
+    fetch: config.fetch,
+    headers: config.rpc?.headers,
+    retry: config.rpc?.retry,
+  });
+  const tick = createTickHelpers({
+    rpc,
+    minOffset: config.tick?.minOffset,
+    defaultOffset: config.tick?.defaultOffset,
+    maxOffset: config.tick?.maxOffset,
+  });
+
+  const confirm = createTxConfirmationHelpers({
+    rpc,
+    defaultTimeoutMs: config.tx?.confirmTimeoutMs,
+    defaultPollIntervalMs: config.tx?.confirmPollIntervalMs,
+  });
+  const tx = createTxHelpers({ rpc, confirm });
+  const contracts = createContractHelpers({
+    rpc,
+    defaultRetries: config.contracts?.defaultRetries,
+    defaultRetryDelayMs: config.contracts?.defaultRetryDelayMs,
+  });
+
+  const txQueue =
+    config.txQueue?.enabled === false
+      ? undefined
+      : new TxQueue({
+          policy: config.txQueue?.policy,
+          confirm: ({ txId, targetTick, signal }) =>
+            tx.waitForConfirmation({ txId, targetTick, signal }),
+        });
+
+  const transactions = createTransactionHelpers({ tick, tx, txQueue, vault: config.vault });
+  const transfers = createTransferHelpers({ transactions });
+  const assets = config.assets?.requestAssets
+    ? createAssetsHelpers({ requestAssets: config.assets.requestAssets })
+    : undefined;
+  const bob = createBobClient({
+    baseUrl: config.bob?.baseUrl,
+    fetch: config.bob?.fetch ?? config.fetch,
+    headers: config.bob?.headers,
+    retry: config.bob?.retry,
+  });
+  const vault = config.vault;
+  return {
+    rpc,
+    tick,
+    tx,
+    txQueue,
+    transactions,
+    transfers,
+    contracts,
+    assets,
+    vault,
+    bob,
+  } as const;
+}

package/src/tick.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "bun:test";
+import type { RpcClient } from "./rpc/client.js";
+import { createTickHelpers } from "./tick.js";
+
+function createMockRpc(tick: bigint): RpcClient {
+  return {
+    live: {
+      async tickInfo() {
+        return { tick, duration: 0n, epoch: 0n, initialTick: 0n };
+      },
+      async balance() {
+        throw new Error("not implemented");
+      },
+      async broadcastTransaction() {
+        throw new Error("not implemented");
+      },
+      async querySmartContract() {
+        throw new Error("not implemented");
+      },
+    },
+    query: {
+      async getLastProcessedTick() {
+        throw new Error("not implemented");
+      },
+      async getTransactionByHash() {
+        throw new Error("not implemented");
+      },
+      async getTransactionsForIdentity() {
+        throw new Error("not implemented");
+      },
+      async *getTransactionsForIdentityPages() {
+        yield* [];
+        throw new Error("not implemented");
+      },
+      async getTransactionsForIdentityAll() {
+        throw new Error("not implemented");
+      },
+      async getTransactionsForTick() {
+        throw new Error("not implemented");
+      },
+      async getTickData() {
+        throw new Error("not implemented");
+      },
+      async getProcessedTickIntervals() {
+        throw new Error("not implemented");
+      },
+      async getComputorListsForEpoch() {
+        throw new Error("not implemented");
+      },
+    },
+  };
+}
+
+describe("tick helpers", () => {
+  it("uses default offset (15) with guardrails", async () => {
+    const tick = createTickHelpers({ rpc: createMockRpc(100n) });
+    await expect(tick.getSuggestedTargetTick()).resolves.toBe(115n);
+  });
+
+  it("rejects offsets below minOffset", async () => {
+    const tick = createTickHelpers({ rpc: createMockRpc(0n), minOffset: 5, defaultOffset: 5 });
+    await expect(tick.getSuggestedTargetTick({ offset: 4 })).rejects.toBeInstanceOf(RangeError);
+  });
+
+  it("rejects offsets above maxOffset", async () => {
+    const tick = createTickHelpers({ rpc: createMockRpc(0n), maxOffset: 10, defaultOffset: 10 });
+    await expect(tick.getSuggestedTargetTick({ offset: 11 })).rejects.toBeInstanceOf(RangeError);
+  });
+});

package/src/tick.ts

@@ -0,0 +1,47 @@
+import type { RpcClient } from "./rpc/client.js";
+
+export type TickHelpersConfig = Readonly<{
+  rpc: RpcClient;
+  minOffset?: bigint | number;
+  defaultOffset?: bigint | number;
+  maxOffset?: bigint | number;
+}>;
+
+export type SuggestedTargetTickInput = Readonly<{ offset?: bigint | number }>;
+
+export type TickHelpers = Readonly<{
+  getSuggestedTargetTick(input?: SuggestedTargetTickInput): Promise<bigint>;
+}>;
+
+export function createTickHelpers(config: TickHelpersConfig): TickHelpers {
+  const minOffset = toBigint(config.minOffset ?? 5);
+  const defaultOffset = toBigint(config.defaultOffset ?? 15);
+  const maxOffset = toBigint(config.maxOffset ?? 300);
+
+  if (minOffset < 0n) throw new RangeError("minOffset must be >= 0");
+  if (defaultOffset < 0n) throw new RangeError("defaultOffset must be >= 0");
+  if (maxOffset < 0n) throw new RangeError("maxOffset must be >= 0");
+  if (minOffset > maxOffset) throw new RangeError("minOffset must be <= maxOffset");
+
+  return {
+    async getSuggestedTargetTick(input: SuggestedTargetTickInput = {}): Promise<bigint> {
+      const offset = toBigint(input.offset ?? defaultOffset);
+      if (offset < minOffset) {
+        throw new RangeError(`offset must be >= ${minOffset}`);
+      }
+      if (offset > maxOffset) {
+        throw new RangeError(`offset must be <= ${maxOffset}`);
+      }
+      const { tick } = await config.rpc.live.tickInfo();
+      return tick + offset;
+    },
+  };
+}
+
+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);
+}

package/src/transactions.queue.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "bun:test";
+import type { BroadcastTransactionResult } from "./rpc/client.js";
+import { createTransactionHelpers } from "./transactions.js";
+import type { TxHelpers } from "./tx/tx.js";
+import { TxQueue } from "./tx/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("transactions (queued)", () => {
+  it("enforces one in-flight tx per source identity", async () => {
+    const confirmations = new Map<string, ReturnType<typeof createDeferred<void>>>();
+    const broadcastOrder: string[] = [];
+
+    const tx: TxHelpers = {
+      async broadcastSigned() {
+        const txId = `tx${broadcastOrder.length + 1}`;
+        broadcastOrder.push(txId);
+        confirmations.set(txId, createDeferred<void>());
+        const res: BroadcastTransactionResult = {
+          peersBroadcasted: 1,
+          encodedTransaction: "",
+          transactionId: txId,
+        };
+        return res;
+      },
+      async waitForConfirmation({ txId }) {
+        const d = confirmations.get(txId);
+        if (!d) throw new Error(`missing deferred for ${txId}`);
+        await d.promise;
+      },
+      async waitForConfirmedTransaction() {
+        throw new Error("not implemented");
+      },
+    };
+
+    const txQueue = new TxQueue({
+      confirm: ({ txId, targetTick, signal }) =>
+        tx.waitForConfirmation({ txId, targetTick, signal }),
+    });
+
+    const transactions = createTransactionHelpers({
+      tick: {
+        async getSuggestedTargetTick() {
+          return 100n;
+        },
+      },
+      tx,
+      txQueue,
+    });
+
+    const seed = "jvhbyzjinlyutyuhsweuxiwootqoevjqwqmdhjeohrytxjxidpbcfyg";
+    const toIdentity = "AFZPUAIYVPNUYGJRQVLUKOPPVLHAZQTGLYAAUUNBXFTVTAMSBKQBLEIEPCVJ";
+
+    const p1 = transactions.sendQueued({
+      fromSeed: seed,
+      toIdentity,
+      amount: 1n,
+      targetTick: 10n,
+    });
+    const p2 = transactions.sendQueued({
+      fromSeed: seed,
+      toIdentity,
+      amount: 1n,
+      targetTick: 11n,
+    });
+
+    await waitFor(() => broadcastOrder.length === 1);
+    expect(broadcastOrder).toEqual(["tx1"]);
+
+    mustGet(confirmations, "tx1").resolve();
+    const r1 = await p1;
+    expect(r1.networkTxId).toBe("tx1");
+
+    await waitFor(() => broadcastOrder.length === 2);
+    mustGet(confirmations, "tx2").resolve();
+    const r2 = await p2;
+    expect(r2.networkTxId).toBe("tx2");
+    expect(broadcastOrder).toEqual(["tx1", "tx2"]);
+  });
+});
+
+async function waitFor(condition: () => boolean, timeoutMs = 1000): Promise<void> {
+  const start = Date.now();
+  while (!condition()) {
+    if (Date.now() - start > timeoutMs) throw new Error("Timed out waiting for condition");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+}
+
+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/transactions.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "bun:test";
+import {
+  buildSignedTransaction,
+  privateKeyFromSeed,
+  publicKeyFromIdentity,
+  publicKeyFromSeed,
+  transactionId,
+} from "@qubic.ts/core";
+import type { TickHelpers } from "./tick.js";
+import { createTransactionHelpers } from "./transactions.js";
+import type { TxHelpers } from "./tx/tx.js";
+
+describe("transactions", () => {
+  it("builds the same signed tx as core (generic inputType + bytes)", async () => {
+    const seed = "jvhbyzjinlyutyuhsweuxiwootqoevjqwqmdhjeohrytxjxidpbcfyg";
+    const toIdentity = "AFZPUAIYVPNUYGJRQVLUKOPPVLHAZQTGLYAAUUNBXFTVTAMSBKQBLEIEPCVJ";
+    const targetTick = 12345n;
+    const inputType = 7;
+    const inputBytes = new Uint8Array([1, 2, 3, 4]);
+
+    const tick: TickHelpers = {
+      async getSuggestedTargetTick() {
+        return 999n;
+      },
+    };
+    const tx: TxHelpers = {
+      async broadcastSigned() {
+        throw new Error("not used");
+      },
+      async waitForConfirmation() {
+        throw new Error("not used");
+      },
+      async waitForConfirmedTransaction() {
+        throw new Error("not used");
+      },
+    };
+
+    const transactions = createTransactionHelpers({ tick, tx });
+    const built = await transactions.buildSigned({
+      fromSeed: seed,
+      toIdentity,
+      amount: 1n,
+      targetTick,
+      inputType,
+      inputBytes,
+    });
+
+    const sourcePublicKey32 = await publicKeyFromSeed(seed);
+    const destinationPublicKey32 = publicKeyFromIdentity(toIdentity);
+    const secretKey32 = await privateKeyFromSeed(seed);
+    const expected = await buildSignedTransaction(
+      {
+        sourcePublicKey32,
+        destinationPublicKey32,
+        amount: 1n,
+        tick: 12345,
+        inputType,
+        inputBytes,
+      },
+      secretKey32,
+    );
+    const expectedId = await transactionId(expected);
+
+    expect(built.targetTick).toBe(targetTick);
+    expect(built.txBytes).toEqual(expected);
+    expect(built.txId).toBe(expectedId);
+  });
+
+  it("accepts fromVault source inputs", async () => {
+    const seed = "jvhbyzjinlyutyuhsweuxiwootqoevjqwqmdhjeohrytxjxidpbcfyg";
+    const toIdentity = "AFZPUAIYVPNUYGJRQVLUKOPPVLHAZQTGLYAAUUNBXFTVTAMSBKQBLEIEPCVJ";
+
+    const tick: TickHelpers = {
+      async getSuggestedTargetTick() {
+        return 123n;
+      },
+    };
+    const tx: TxHelpers = {
+      async broadcastSigned() {
+        throw new Error("not used");
+      },
+      async waitForConfirmation() {
+        throw new Error("not used");
+      },
+      async waitForConfirmedTransaction() {
+        throw new Error("not used");
+      },
+    };
+
+    const transactions = createTransactionHelpers({
+      tick,
+      tx,
+      vault: {
+        path: "vault.json",
+        list() {
+          return [];
+        },
+        getEntry() {
+          throw new Error("not used");
+        },
+        getIdentity() {
+          return "IDENTITY";
+        },
+        signer() {
+          return { fromVault: "main" };
+        },
+        async getSeed() {
+          return seed;
+        },
+        async addSeed() {
+          throw new Error("not used");
+        },
+        async remove() {
+          throw new Error("not used");
+        },
+        async rotatePassphrase() {
+          throw new Error("not used");
+        },
+        exportEncrypted() {
+          throw new Error("not used");
+        },
+        exportJson() {
+          throw new Error("not used");
+        },
+        async importEncrypted() {
+          throw new Error("not used");
+        },
+        async getSeedSource() {
+          return { fromSeed: seed };
+        },
+        async save() {
+          throw new Error("not used");
+        },
+        async close() {
+          throw new Error("not used");
+        },
+      },
+    });
+
+    const built = await transactions.buildSigned({
+      fromVault: "main",
+      toIdentity,
+      amount: 1n,
+      targetTick: 123n,
+    });
+
+    expect(built.txBytes.length).toBeGreaterThan(0);
+  });
+});