@qubic.ts/sdk 0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@qubic.ts/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./browser": {
+      "types": "./src/browser.ts",
+      "import": "./src/browser.ts",
+      "default": "./src/browser.ts"
+    },
+    "./node": {
+      "types": "./src/node.ts",
+      "import": "./src/node.ts",
+      "default": "./src/node.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "qubic-ts-vault": "./src/vault-cli.ts"
+  },
+  "dependencies": {
+    "@qubic.ts/contracts": "^0.1.0",
+    "@qubic.ts/core": "^0.1.0"
+  },
+  "scripts": {
+    "build": "echo \"qubic-ts-sdk build pending\"",
+    "check": "bun test ./src/**/*.test.ts ./src/*.test.ts",
+    "test": "bun test ./src/**/*.test.ts ./src/*.test.ts",
+    "vault:cli": "bun ./src/vault-cli.ts"
+  }
+}

package/src/assets.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "bun:test";
+import {
+  AssetRecordType,
+  encodeRequestAssetsByFilter,
+  encodeRequestAssetsByUniverseIndex,
+  publicKeyFromIdentity,
+  writeI64LE,
+} from "@qubic.ts/core";
+import { createAssetsHelpers } from "./assets.js";
+
+const zeroId = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFXIB";
+const RESPOND_ASSETS_PAYLOAD_SIZE = 56;
+const RESPOND_ASSETS_WITH_SIBLINGS_PAYLOAD_SIZE = 824;
+const RequestAssetsType = {
+  ISSUANCE: 0,
+  OWNERSHIP: 1,
+  POSSESSION: 2,
+  BY_UNIVERSE_INDEX: 3,
+} as const;
+
+describe("assets helpers", () => {
+  it("listIssued encodes filter and decodes response", async () => {
+    const payload = new Uint8Array(RESPOND_ASSETS_PAYLOAD_SIZE);
+    payload[32] = AssetRecordType.ISSUANCE;
+    const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+    view.setUint32(48, 7, true);
+    view.setUint32(52, 9, true);
+
+    const expectedRequest = encodeRequestAssetsByFilter({
+      requestType: RequestAssetsType.ISSUANCE,
+      issuerPublicKey32: publicKeyFromIdentity(zeroId),
+      assetNameU64LE: assetNameToU64LE("ASSET"),
+    });
+
+    const assets = createAssetsHelpers({
+      requestAssets: async (request) => {
+        expect(bytesEqual(request.slice(8), expectedRequest.slice(8))).toBe(true);
+        return [payload];
+      },
+    });
+
+    const res = await assets.listIssued({
+      issuerIdentity: zeroId,
+      assetName: "ASSET",
+    });
+
+    expect(res.length).toBe(1);
+    expect(res[0]?.tick).toBe(7);
+    expect(res[0]?.universeIndex).toBe(9);
+    expect(res[0]?.asset.type).toBe(AssetRecordType.ISSUANCE);
+  });
+
+  it("listOwned decodes siblings response", async () => {
+    const payload = new Uint8Array(RESPOND_ASSETS_WITH_SIBLINGS_PAYLOAD_SIZE);
+    payload[32] = AssetRecordType.OWNERSHIP;
+    const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength);
+    view.setUint16(34, 12, true);
+    view.setUint32(36, 99, true);
+    writeI64LE(123n, payload, 40);
+
+    const assets = createAssetsHelpers({
+      requestAssets: async () => [payload],
+    });
+
+    const res = await assets.listOwned({
+      ownerIdentity: zeroId,
+      getSiblings: true,
+    });
+
+    expect(res.length).toBe(1);
+    const first = res[0];
+    expect(first).toBeDefined();
+    if (!first) throw new Error("Missing assets response");
+    expect("siblings" in first).toBe(true);
+    const record = first.asset;
+    expect(record.type).toBe(AssetRecordType.OWNERSHIP);
+  });
+
+  it("listByUniverseIndex encodes request", async () => {
+    const expectedRequest = encodeRequestAssetsByUniverseIndex({
+      universeIndex: 123,
+      getSiblings: false,
+    });
+
+    const assets = createAssetsHelpers({
+      requestAssets: async (request) => {
+        expect(bytesEqual(request.slice(8), expectedRequest.slice(8))).toBe(true);
+        return [new Uint8Array(RESPOND_ASSETS_PAYLOAD_SIZE)];
+      },
+    });
+
+    await assets.listByUniverseIndex({ universeIndex: 123 });
+  });
+});
+
+function bytesEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.byteLength !== b.byteLength) return false;
+  for (let i = 0; i < a.byteLength; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+function assetNameToU64LE(name: string): bigint {
+  if (name.length > 8) throw new RangeError("assetName must be <= 8 characters");
+  const bytes = new Uint8Array(8);
+  for (let i = 0; i < name.length; i++) {
+    const c = name.charCodeAt(i);
+    if (c < 32 || c > 126) throw new Error("assetName must be ASCII");
+    bytes[i] = c;
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return view.getBigUint64(0, true);
+}

package/src/assets.ts

@@ -0,0 +1,175 @@
+import {
+  type AssetRecord,
+  AssetRecordType,
+  decodeRespondAssets,
+  decodeRespondAssetsWithSiblings,
+  encodeRequestAssetsByFilter,
+  encodeRequestAssetsByUniverseIndex,
+  publicKeyFromIdentity,
+  type RespondAssets,
+  type RespondAssetsWithSiblings,
+} from "@qubic.ts/core";
+
+const RESPOND_ASSETS_PAYLOAD_SIZE = 56;
+const RESPOND_ASSETS_WITH_SIBLINGS_PAYLOAD_SIZE = 824;
+const RequestAssetsType = {
+  ISSUANCE: 0,
+  OWNERSHIP: 1,
+  POSSESSION: 2,
+  BY_UNIVERSE_INDEX: 3,
+} as const;
+
+export type AssetsRequestFn = (
+  request: Uint8Array,
+  signal?: AbortSignal,
+) => Promise<readonly Uint8Array[]>;
+
+export type AssetsHelpersConfig = Readonly<{
+  requestAssets: AssetsRequestFn;
+}>;
+
+export type AssetsQueryInput = Readonly<{
+  getSiblings?: boolean;
+  signal?: AbortSignal;
+}>;
+
+export type ListIssuedInput = AssetsQueryInput &
+  Readonly<{
+    issuerIdentity?: string;
+    assetName?: string;
+  }>;
+
+export type ListOwnedInput = AssetsQueryInput &
+  Readonly<{
+    ownerIdentity?: string;
+    issuerIdentity?: string;
+    assetName?: string;
+    managingContractIndex?: number;
+  }>;
+
+export type ListPossessedInput = AssetsQueryInput &
+  Readonly<{
+    possessorIdentity?: string;
+    issuerIdentity?: string;
+    assetName?: string;
+    managingContractIndex?: number;
+  }>;
+
+export type AssetsHelpers = Readonly<{
+  listIssued(
+    input: ListIssuedInput,
+  ): Promise<readonly (RespondAssets | RespondAssetsWithSiblings)[]>;
+  listOwned(input: ListOwnedInput): Promise<readonly (RespondAssets | RespondAssetsWithSiblings)[]>;
+  listPossessed(
+    input: ListPossessedInput,
+  ): Promise<readonly (RespondAssets | RespondAssetsWithSiblings)[]>;
+  listByUniverseIndex(input: {
+    universeIndex: number;
+    getSiblings?: boolean;
+    signal?: AbortSignal;
+  }): Promise<readonly (RespondAssets | RespondAssetsWithSiblings)[]>;
+}>;
+
+export function createAssetsHelpers(config: AssetsHelpersConfig): AssetsHelpers {
+  const requestAssets = config.requestAssets;
+
+  const decodeResponses = (payloads: readonly Uint8Array[]) =>
+    payloads.map((payload) => {
+      if (payload.byteLength === RESPOND_ASSETS_WITH_SIBLINGS_PAYLOAD_SIZE) {
+        return decodeRespondAssetsWithSiblings(payload);
+      }
+      if (payload.byteLength === RESPOND_ASSETS_PAYLOAD_SIZE) {
+        return decodeRespondAssets(payload);
+      }
+      throw new RangeError("Unexpected RespondAssets payload length");
+    });
+
+  return {
+    async listIssued(input: ListIssuedInput) {
+      const request = encodeRequestAssetsByFilter({
+        requestType: RequestAssetsType.ISSUANCE,
+        getSiblings: input.getSiblings,
+        issuerPublicKey32: input.issuerIdentity
+          ? publicKeyFromIdentity(input.issuerIdentity)
+          : undefined,
+        assetNameU64LE: input.assetName ? assetNameToU64LE(input.assetName) : undefined,
+      });
+      return decodeResponses(await requestAssets(request, input.signal));
+    },
+
+    async listOwned(input: ListOwnedInput) {
+      const request = encodeRequestAssetsByFilter({
+        requestType: RequestAssetsType.OWNERSHIP,
+        getSiblings: input.getSiblings,
+        issuerPublicKey32: input.issuerIdentity
+          ? publicKeyFromIdentity(input.issuerIdentity)
+          : undefined,
+        assetNameU64LE: input.assetName ? assetNameToU64LE(input.assetName) : undefined,
+        ownerPublicKey32: input.ownerIdentity
+          ? publicKeyFromIdentity(input.ownerIdentity)
+          : undefined,
+        ownershipManagingContractIndex: input.managingContractIndex,
+      });
+      return decodeResponses(await requestAssets(request, input.signal));
+    },
+
+    async listPossessed(input: ListPossessedInput) {
+      const request = encodeRequestAssetsByFilter({
+        requestType: RequestAssetsType.POSSESSION,
+        getSiblings: input.getSiblings,
+        issuerPublicKey32: input.issuerIdentity
+          ? publicKeyFromIdentity(input.issuerIdentity)
+          : undefined,
+        assetNameU64LE: input.assetName ? assetNameToU64LE(input.assetName) : undefined,
+        possessorPublicKey32: input.possessorIdentity
+          ? publicKeyFromIdentity(input.possessorIdentity)
+          : undefined,
+        possessionManagingContractIndex: input.managingContractIndex,
+      });
+      return decodeResponses(await requestAssets(request, input.signal));
+    },
+
+    async listByUniverseIndex(input) {
+      const request = encodeRequestAssetsByUniverseIndex({
+        universeIndex: input.universeIndex,
+        getSiblings: input.getSiblings,
+      });
+      return decodeResponses(await requestAssets(request, input.signal));
+    },
+  };
+}
+
+export function isIssuanceAsset(
+  record: AssetRecord,
+): record is AssetRecord & { type: typeof AssetRecordType.ISSUANCE } {
+  return record.type === AssetRecordType.ISSUANCE;
+}
+
+export function isOwnershipAsset(
+  record: AssetRecord,
+): record is AssetRecord & { type: typeof AssetRecordType.OWNERSHIP } {
+  return record.type === AssetRecordType.OWNERSHIP;
+}
+
+export function isPossessionAsset(
+  record: AssetRecord,
+): record is AssetRecord & { type: typeof AssetRecordType.POSSESSION } {
+  return record.type === AssetRecordType.POSSESSION;
+}
+
+function assetNameToU64LE(name: string): bigint {
+  if (typeof name !== "string") {
+    throw new TypeError("assetName must be a string");
+  }
+  if (name.length > 8) {
+    throw new RangeError("assetName must be <= 8 characters");
+  }
+  const bytes = new Uint8Array(8);
+  for (let i = 0; i < name.length; i++) {
+    const c = name.charCodeAt(i);
+    if (c < 32 || c > 126) throw new Error("assetName must be ASCII");
+    bytes[i] = c;
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return view.getBigUint64(0, true);
+}

package/src/bob/client.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "bun:test";
+import type { FetchLike } from "../http.js";
+import { createBobClient } from "./client.js";
+
+describe("bob client", () => {
+  it("querySmartContract sends hex payload and parses response", async () => {
+    let body: Record<string, unknown> | undefined;
+    const requests: string[] = [];
+    const responses: number[] = [];
+    const fetch: FetchLike = async (...args) => {
+      const url = new URL(getUrl(args[0]));
+      const method = getMethod(args[0], args[1]);
+      if (method === "POST" && url.pathname === "/querySmartContract") {
+        body = readJsonBody(args[0], args[1]);
+        return Response.json({ nonce: body?.nonce, data: "abcd" });
+      }
+      return new Response("not found", { status: 404 });
+    };
+
+    const bob = createBobClient({
+      baseUrl: "http://example.test",
+      fetch,
+      onRequest: (info) => requests.push(info.url),
+      onResponse: (info) => responses.push(info.status),
+    });
+    const res = await bob.querySmartContract({
+      scIndex: 1,
+      funcNumber: 2,
+      dataBytes: new Uint8Array([0xab, 0xcd]),
+    });
+
+    expect(res.pending).toBe(false);
+    expect(res.dataHex).toBe("abcd");
+    expect(body?.data).toBe("abcd");
+    expect(requests.length).toBeGreaterThan(0);
+    expect(responses.length).toBeGreaterThan(0);
+  });
+
+  it("querySmartContract handles pending responses", async () => {
+    const fetch: FetchLike = async (...args) => {
+      const url = new URL(getUrl(args[0]));
+      const method = getMethod(args[0], args[1]);
+      if (method === "POST" && url.pathname === "/querySmartContract") {
+        return new Response(JSON.stringify({ error: "pending", message: "try later" }), {
+          status: 202,
+          headers: { "content-type": "application/json" },
+        });
+      }
+      return new Response("not found", { status: 404 });
+    };
+
+    const bob = createBobClient({ baseUrl: "http://example.test", fetch });
+    const res = await bob.querySmartContract({ scIndex: 1, funcNumber: 2, dataHex: "00" });
+    expect(res.pending).toBe(true);
+    expect(res.message).toBe("try later");
+  });
+
+  it("retries failed requests based on retry config", async () => {
+    let attempts = 0;
+    const fetch: FetchLike = async (...args) => {
+      const url = new URL(getUrl(args[0]));
+      const method = getMethod(args[0], args[1]);
+      if (method === "GET" && url.pathname === "/status") {
+        attempts += 1;
+        if (attempts < 2) {
+          return new Response("temporary", { status: 503 });
+        }
+        return Response.json({ ok: true });
+      }
+      return new Response("not found", { status: 404 });
+    };
+
+    const bob = createBobClient({
+      baseUrl: "http://example.test",
+      fetch,
+      retry: { maxRetries: 2, baseDelayMs: 1, jitterMs: 0 },
+    });
+    const res = await bob.status();
+    expect(attempts).toBe(2);
+    expect(res).toEqual({ ok: true });
+  });
+});
+
+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) {
+    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");
+}