@qubic.ts/sdk 0.1.0

package/src/transactions.ts

@@ -0,0 +1,234 @@
+import {
+  buildSignedTransaction,
+  identityFromSeed,
+  privateKeyFromSeed,
+  publicKeyFromIdentity,
+  publicKeyFromSeed,
+  transactionId,
+} from "@qubic.ts/core";
+import type { BroadcastTransactionResult, QueryTransaction } from "./rpc/client.js";
+import type { TickHelpers } from "./tick.js";
+import type { TxHelpers } from "./tx/tx.js";
+import type { TxQueue } from "./tx/tx-queue.js";
+import type { SeedVault } from "./vault/types.js";
+
+export type TransactionHelpersConfig = Readonly<{
+  tick: TickHelpers;
+  tx: TxHelpers;
+  txQueue?: TxQueue;
+  vault?: SeedVault;
+}>;
+
+export type SeedSourceInput =
+  | Readonly<{ fromSeed: string; fromVault?: never }>
+  | Readonly<{ fromVault: string; fromSeed?: never }>;
+
+export type BuildSignedTransactionInput = SeedSourceInput &
+  Readonly<{
+    toIdentity: string;
+    amount: bigint;
+    targetTick?: bigint | number;
+    inputType?: number;
+    inputBytes?: Uint8Array;
+  }>;
+
+export type BuiltTransaction = Readonly<{
+  txBytes: Uint8Array;
+  /** Deterministic transaction id derived from tx bytes. */
+  txId: string;
+  targetTick: bigint;
+}>;
+
+export type SendTransactionResult = Readonly<{
+  txBytes: Uint8Array;
+  /** Deterministic transaction id derived from tx bytes. */
+  txId: string;
+  /** Transaction id returned by the RPC broadcast call (used for confirmation). */
+  networkTxId: string;
+  targetTick: bigint;
+  broadcast: BroadcastTransactionResult;
+}>;
+
+export type SendTransactionReceipt = SendTransactionResult &
+  Readonly<{
+    confirmedTransaction: QueryTransaction;
+  }>;
+
+export class QueuedTransactionError extends Error {
+  override name = "QueuedTransactionError";
+
+  constructor(
+    message: string,
+    readonly details: Readonly<{
+      status: string;
+      error?: unknown;
+    }>,
+  ) {
+    super(message);
+  }
+}
+
+export type SendAndConfirmTransactionInput = BuildSignedTransactionInput &
+  Readonly<{
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+  }>;
+
+export type TransactionHelpers = Readonly<{
+  buildSigned(input: BuildSignedTransactionInput): Promise<BuiltTransaction>;
+  send(input: BuildSignedTransactionInput): Promise<SendTransactionResult>;
+  sendAndConfirm(input: SendAndConfirmTransactionInput): Promise<SendTransactionResult>;
+  sendQueued(input: SendAndConfirmTransactionInput): Promise<SendTransactionResult>;
+  sendAndConfirmWithReceipt(input: SendAndConfirmTransactionInput): Promise<SendTransactionReceipt>;
+}>;
+
+export function createTransactionHelpers(config: TransactionHelpersConfig): TransactionHelpers {
+  const helpers: TransactionHelpers = {
+    async buildSigned(input: BuildSignedTransactionInput): Promise<BuiltTransaction> {
+      const targetTick =
+        input.targetTick !== undefined
+          ? toBigint(input.targetTick)
+          : await config.tick.getSuggestedTargetTick();
+
+      const tickU32 = toU32Number(targetTick, "targetTick");
+      const seed = await resolveSeed(input, config.vault);
+      const sourcePublicKey32 = await publicKeyFromSeed(seed);
+      const destinationPublicKey32 = publicKeyFromIdentity(input.toIdentity);
+      const secretKey32 = await privateKeyFromSeed(seed);
+
+      const txBytes = await buildSignedTransaction(
+        {
+          sourcePublicKey32,
+          destinationPublicKey32,
+          amount: input.amount,
+          tick: tickU32,
+          inputType: input.inputType ?? 0,
+          inputBytes: input.inputBytes,
+        },
+        secretKey32,
+      );
+      const txId = await transactionId(txBytes);
+      return { txBytes, txId, targetTick };
+    },
+
+    async send(input: BuildSignedTransactionInput): Promise<SendTransactionResult> {
+      const built = await helpers.buildSigned(input);
+      const broadcast = await config.tx.broadcastSigned(built.txBytes);
+      return {
+        ...built,
+        networkTxId: broadcast.transactionId,
+        broadcast,
+      };
+    },
+
+    async sendAndConfirm(input: SendAndConfirmTransactionInput): Promise<SendTransactionResult> {
+      if (config.txQueue) return helpers.sendQueued(input);
+
+      const built = await helpers.buildSigned(input);
+      const broadcast = await config.tx.broadcastSigned(built.txBytes);
+      await config.tx.waitForConfirmation({
+        txId: broadcast.transactionId,
+        targetTick: built.targetTick,
+        timeoutMs: input.timeoutMs,
+        pollIntervalMs: input.pollIntervalMs,
+        signal: input.signal,
+      });
+      return {
+        ...built,
+        networkTxId: broadcast.transactionId,
+        broadcast,
+      };
+    },
+
+    async sendAndConfirmWithReceipt(
+      input: SendAndConfirmTransactionInput,
+    ): Promise<SendTransactionReceipt> {
+      const sent = await helpers.sendAndConfirm(input);
+      const confirmedTransaction = await config.tx.waitForConfirmedTransaction({
+        txId: sent.networkTxId,
+        targetTick: sent.targetTick,
+        timeoutMs: input.timeoutMs,
+        pollIntervalMs: input.pollIntervalMs,
+        signal: input.signal,
+      });
+      return { ...sent, confirmedTransaction };
+    },
+
+    async sendQueued(input: SendAndConfirmTransactionInput): Promise<SendTransactionResult> {
+      const txQueue = config.txQueue;
+      if (!txQueue) throw new Error("Transaction queue is not configured");
+
+      const sourceIdentity = await resolveSourceIdentity(input, config.vault);
+      const built = await helpers.buildSigned(input);
+
+      const queued = await txQueue.enqueue({
+        sourceIdentity,
+        targetTick: built.targetTick,
+        submit: async ({ signal }) => {
+          if (signal.aborted) throw new Error("aborted");
+          const broadcast = await config.tx.broadcastSigned(built.txBytes);
+          return { txId: broadcast.transactionId, result: broadcast };
+        },
+        confirm: ({ txId, targetTick, signal }) =>
+          config.tx.waitForConfirmation({
+            txId,
+            targetTick,
+            timeoutMs: input.timeoutMs,
+            pollIntervalMs: input.pollIntervalMs,
+            signal,
+          }),
+      });
+
+      if (queued.status !== "confirmed") {
+        throw new QueuedTransactionError("Transaction queue did not confirm", {
+          status: queued.status,
+          error: queued.error,
+        });
+      }
+      const broadcast = queued.result as BroadcastTransactionResult | undefined;
+      if (!broadcast) throw new Error("Transaction queue missing broadcast result");
+
+      return {
+        ...built,
+        networkTxId: broadcast.transactionId,
+        broadcast,
+      };
+    },
+  };
+
+  return helpers;
+}
+
+async function resolveSeed(input: SeedSourceInput, vault?: SeedVault): Promise<string> {
+  if (hasFromSeed(input)) return input.fromSeed;
+  if (!vault) throw new Error("Vault is not configured");
+  return vault.getSeed(input.fromVault);
+}
+
+async function resolveSourceIdentity(input: SeedSourceInput, vault?: SeedVault): Promise<string> {
+  if (hasFromSeed(input)) {
+    return identityFromSeed(input.fromSeed);
+  }
+  if (!vault) throw new Error("Vault is not configured");
+  return await vault.getIdentity(input.fromVault);
+}
+
+function hasFromSeed(input: SeedSourceInput): input is Readonly<{ fromSeed: string }> {
+  return "fromSeed" in input && typeof input.fromSeed === "string";
+}
+
+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 toU32Number(value: bigint, name: string): number {
+  if (value < 0n || value > 0xffff_ffffn) {
+    throw new RangeError(`${name} must fit in uint32`);
+  }
+  return Number(value);
+}

package/src/transfers.test.ts

@@ -0,0 +1,59 @@
+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 { createTransferHelpers } from "./transfers.js";
+import type { TxHelpers } from "./tx/tx.js";
+
+describe("transfers", () => {
+  it("builds the same signed tx as core (simple transfer)", async () => {
+    const seed = "jvhbyzjinlyutyuhsweuxiwootqoevjqwqmdhjeohrytxjxidpbcfyg";
+    const toIdentity = "AFZPUAIYVPNUYGJRQVLUKOPPVLHAZQTGLYAAUUNBXFTVTAMSBKQBLEIEPCVJ";
+    const targetTick = 12345n;
+
+    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 transfers = createTransferHelpers({ transactions });
+    const built = await transfers.buildSignedTransfer({
+      fromSeed: seed,
+      toIdentity,
+      amount: 1n,
+      targetTick,
+    });
+
+    const sourcePublicKey32 = await publicKeyFromSeed(seed);
+    const destinationPublicKey32 = publicKeyFromIdentity(toIdentity);
+    const secretKey32 = await privateKeyFromSeed(seed);
+    const expected = await buildSignedTransaction(
+      { sourcePublicKey32, destinationPublicKey32, amount: 1n, tick: 12345 },
+      secretKey32,
+    );
+    const expectedId = await transactionId(expected);
+
+    expect(built.targetTick).toBe(targetTick);
+    expect(built.txBytes).toEqual(expected);
+    expect(built.txId).toBe(expectedId);
+  });
+});

package/src/transfers.ts

@@ -0,0 +1,132 @@
+import type { BroadcastTransactionResult, QueryTransaction } from "./rpc/client.js";
+import type { SeedSourceInput, TransactionHelpers } from "./transactions.js";
+
+export type TransferHelpersConfig = Readonly<{
+  transactions: TransactionHelpers;
+}>;
+
+export type BuildSignedTransferInput = SeedSourceInput &
+  Readonly<{
+    toIdentity: string;
+    amount: bigint;
+    targetTick?: bigint | number;
+  }>;
+
+export type SignedTransfer = Readonly<{
+  txBytes: Uint8Array;
+  txId: string;
+  targetTick: bigint;
+}>;
+
+export type SendTransferResult = Readonly<{
+  txBytes: Uint8Array;
+  txId: string;
+  networkTxId: string;
+  targetTick: bigint;
+  broadcast: BroadcastTransactionResult;
+}>;
+
+export type SendTransferReceipt = SendTransferResult &
+  Readonly<{
+    confirmedTransaction: QueryTransaction;
+  }>;
+
+export type SendAndConfirmInput = BuildSignedTransferInput &
+  Readonly<{
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+  }>;
+
+export type TransferHelpers = Readonly<{
+  buildSignedTransfer(input: BuildSignedTransferInput): Promise<SignedTransfer>;
+  send(input: BuildSignedTransferInput): Promise<SendTransferResult>;
+  sendAndConfirm(input: SendAndConfirmInput): Promise<SendTransferResult>;
+  sendAndConfirmWithReceipt(input: SendAndConfirmInput): Promise<SendTransferReceipt>;
+  sendFromVault(
+    input: Omit<BuildSignedTransferInput, "fromSeed" | "fromVault"> &
+      Readonly<{ fromVault: string }>,
+  ): Promise<SendTransferResult>;
+  sendAndConfirmFromVault(
+    input: Omit<SendAndConfirmInput, "fromSeed" | "fromVault"> & Readonly<{ fromVault: string }>,
+  ): Promise<SendTransferResult>;
+}>;
+
+export function createTransferHelpers(config: TransferHelpersConfig): TransferHelpers {
+  const helpers: TransferHelpers = {
+    async buildSignedTransfer(input: BuildSignedTransferInput): Promise<SignedTransfer> {
+      const built = await config.transactions.buildSigned({
+        ...input,
+        toIdentity: input.toIdentity,
+        amount: input.amount,
+        targetTick: input.targetTick,
+      });
+      return { txBytes: built.txBytes, txId: built.txId, targetTick: built.targetTick };
+    },
+
+    async send(input: BuildSignedTransferInput): Promise<SendTransferResult> {
+      const sent = await config.transactions.send({
+        ...input,
+        toIdentity: input.toIdentity,
+        amount: input.amount,
+        targetTick: input.targetTick,
+      });
+      return {
+        txBytes: sent.txBytes,
+        txId: sent.txId,
+        networkTxId: sent.networkTxId,
+        targetTick: sent.targetTick,
+        broadcast: sent.broadcast,
+      };
+    },
+
+    async sendAndConfirm(input: SendAndConfirmInput): Promise<SendTransferResult> {
+      const sent = await config.transactions.sendAndConfirm({
+        ...input,
+        toIdentity: input.toIdentity,
+        amount: input.amount,
+        targetTick: input.targetTick,
+        timeoutMs: input.timeoutMs,
+        pollIntervalMs: input.pollIntervalMs,
+        signal: input.signal,
+      });
+      return {
+        txBytes: sent.txBytes,
+        txId: sent.txId,
+        networkTxId: sent.networkTxId,
+        targetTick: sent.targetTick,
+        broadcast: sent.broadcast,
+      };
+    },
+
+    async sendAndConfirmWithReceipt(input: SendAndConfirmInput): Promise<SendTransferReceipt> {
+      const sent = await config.transactions.sendAndConfirmWithReceipt({
+        ...input,
+        toIdentity: input.toIdentity,
+        amount: input.amount,
+        targetTick: input.targetTick,
+        timeoutMs: input.timeoutMs,
+        pollIntervalMs: input.pollIntervalMs,
+        signal: input.signal,
+      });
+      return {
+        txBytes: sent.txBytes,
+        txId: sent.txId,
+        networkTxId: sent.networkTxId,
+        targetTick: sent.targetTick,
+        broadcast: sent.broadcast,
+        confirmedTransaction: sent.confirmedTransaction,
+      };
+    },
+
+    async sendFromVault(input): Promise<SendTransferResult> {
+      return helpers.send({ ...input, fromVault: input.fromVault });
+    },
+
+    async sendAndConfirmFromVault(input): Promise<SendTransferResult> {
+      return helpers.sendAndConfirm({ ...input, fromVault: input.fromVault });
+    },
+  };
+
+  return helpers;
+}

package/src/tx/confirm.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "bun:test";
+import type { FetchLike } from "../http.js";
+import { createRpcClient } from "../rpc/client.js";
+import {
+  createTxConfirmationHelpers,
+  TxConfirmationTimeoutError,
+  TxNotFoundError,
+} from "./confirm.js";
+
+function createTestFetch() {
+  let lastProcessed = 0;
+  let getTxCalls = 0;
+
+  return async (...args: Parameters<FetchLike>) => {
+    const url = new URL(getUrl(args[0]));
+    const method = getMethod(args[0], args[1]);
+
+    if (method === "GET" && url.pathname === "/query/v1/getLastProcessedTick") {
+      lastProcessed = Math.min(lastProcessed + 5, 10);
+      return Response.json({ tickNumber: lastProcessed, epoch: 0, intervalInitialTick: 0 });
+    }
+
+    if (method === "POST" && url.pathname === "/query/v1/getTransactionByHash") {
+      getTxCalls++;
+      const body = readJsonBody(args[0], args[1]);
+      if (body.hash !== "tx") return new Response("bad hash", { status: 400 });
+
+      if (getTxCalls < 2) return new Response("not found", { status: 404 });
+      return Response.json({
+        hash: "tx",
+        amount: "0",
+        source: "S",
+        destination: "D",
+        tickNumber: 10,
+        timestamp: "0",
+        inputType: 0,
+        inputSize: 0,
+        inputData: "",
+        signature: "",
+      });
+    }
+
+    return new Response("not found", { status: 404 });
+  };
+}
+
+describe("tx confirmation", () => {
+  it("waits for lastProcessedTick >= targetTick and then finds tx", async () => {
+    const rpc = createRpcClient({ baseUrl: "https://example.test", fetch: createTestFetch() });
+    const confirm = createTxConfirmationHelpers({
+      rpc,
+      defaultTimeoutMs: 5_000,
+      defaultPollIntervalMs: 1,
+    });
+    await confirm.waitForConfirmation({ txId: "tx", targetTick: 10, pollIntervalMs: 1 });
+  });
+
+  it("returns the confirmed transaction (receipt)", async () => {
+    const rpc = createRpcClient({ baseUrl: "https://example.test", fetch: createTestFetch() });
+    const confirm = createTxConfirmationHelpers({
+      rpc,
+      defaultTimeoutMs: 5_000,
+      defaultPollIntervalMs: 1,
+    });
+    const tx = await confirm.waitForConfirmedTransaction({
+      txId: "tx",
+      targetTick: 10,
+      pollIntervalMs: 1,
+    });
+    expect(tx.hash).toBe("tx");
+    expect(tx.tickNumber).toBe(10n);
+  });
+
+  it("throws TxNotFoundError if target tick is reached but tx stays 404", async () => {
+    const fetch: FetchLike = async (...args) => {
+      const url = new URL(getUrl(args[0]));
+      const method = getMethod(args[0], args[1]);
+      if (method === "GET" && url.pathname === "/query/v1/getLastProcessedTick") {
+        return Response.json({ tickNumber: 10, epoch: 0, intervalInitialTick: 0 });
+      }
+      if (method === "POST" && url.pathname === "/query/v1/getTransactionByHash") {
+        return new Response("not found", { status: 404 });
+      }
+      return new Response("not found", { status: 404 });
+    };
+
+    const rpc = createRpcClient({ baseUrl: "https://example.test", fetch });
+    const confirm = createTxConfirmationHelpers({
+      rpc,
+      defaultTimeoutMs: 20,
+      defaultPollIntervalMs: 1,
+    });
+    await expect(
+      confirm.waitForConfirmation({ txId: "tx", targetTick: 10 }),
+    ).rejects.toBeInstanceOf(TxNotFoundError);
+  });
+
+  it("throws TxConfirmationTimeoutError if lastProcessedTick never reaches target", async () => {
+    const fetch: FetchLike = async (...args) => {
+      const url = new URL(getUrl(args[0]));
+      const method = getMethod(args[0], args[1]);
+      if (method === "GET" && url.pathname === "/query/v1/getLastProcessedTick") {
+        return Response.json({ tickNumber: 0, epoch: 0, intervalInitialTick: 0 });
+      }
+      if (method === "POST" && url.pathname === "/query/v1/getTransactionByHash") {
+        return new Response("not found", { status: 404 });
+      }
+      return new Response("not found", { status: 404 });
+    };
+
+    const rpc = createRpcClient({ baseUrl: "https://example.test", fetch });
+    const confirm = createTxConfirmationHelpers({
+      rpc,
+      defaultTimeoutMs: 20,
+      defaultPollIntervalMs: 1,
+    });
+    await expect(
+      confirm.waitForConfirmation({ txId: "tx", targetTick: 10 }),
+    ).rejects.toBeInstanceOf(TxConfirmationTimeoutError);
+  });
+});
+
+function getUrl(input: Parameters<typeof fetch>[0]): string {
+  if (typeof input === "string") return input;
+  if (input instanceof URL) return input.toString();
+  return input.url;
+}
+
+function getMethod(input: Parameters<typeof fetch>[0], init: Parameters<typeof fetch>[1]): string {
+  if (init?.method) return init.method;
+  if (input instanceof Request) return input.method;
+  return "GET";
+}
+
+function readJsonBody(
+  input: Parameters<typeof fetch>[0],
+  init: Parameters<typeof fetch>[1],
+): Record<string, unknown> {
+  if (input instanceof Request) {
+    // Our client doesn't use this path in tests, but keep it safe.
+    throw new Error("Unexpected Request body");
+  }
+  const body = init?.body;
+  if (typeof body === "string") {
+    return JSON.parse(body) as Record<string, unknown>;
+  }
+  if (!body) return {};
+  throw new Error("Unsupported body type");
+}