@qubic.ts/react 0.1.0

package/src/typecheck-stubs/contracts.d.ts

@@ -0,0 +1,77 @@
+export type ContractEntryKind = "function" | "procedure";
+
+export type ContractEntry = Readonly<{
+  kind: ContractEntryKind;
+  name: string;
+  inputType: number;
+  displayName?: string;
+  inputTypeName?: string;
+  outputTypeName?: string;
+  inputSize?: number;
+  outputSize?: number;
+}>;
+
+export type ContractIoFieldDefinition = Readonly<{
+  name: string;
+  type: string;
+  byteOffset?: number;
+}>;
+
+export type ContractIoTypeDefinition =
+  | Readonly<{
+      kind: "struct";
+      name: string;
+      fields: readonly ContractIoFieldDefinition[];
+      byteSize?: number;
+      byteAlign?: number;
+    }>
+  | Readonly<{
+      kind: "alias";
+      name: string;
+      target: string;
+      byteSize?: number;
+      byteAlign?: number;
+    }>;
+
+export type ContractDefinition = Readonly<{
+  name: string;
+  contractIndex: number;
+  address: string;
+  label?: string;
+  filename?: string;
+  githubUrl?: string;
+  website?: string;
+  proposalUrl?: string;
+  entries: readonly ContractEntry[];
+  ioTypes?: readonly ContractIoTypeDefinition[];
+}>;
+
+export type ContractsRegistry = Readonly<{
+  contracts: readonly ContractDefinition[];
+}>;
+
+export declare const coreContractsRegistry: ContractsRegistry;
+
+export declare function bytesToBase64(bytes: Uint8Array): string;
+
+export declare function encodeContractEntryInputData(input: Readonly<{
+  registry: ContractsRegistry | readonly ContractDefinition[];
+  contractName: string;
+  entryName: string;
+  kind?: ContractEntryKind | undefined;
+  value: unknown;
+  allowSequentialLayout?: boolean | undefined;
+}>): Readonly<{
+  bytes: Uint8Array;
+}>;
+
+export declare function decodeContractEntryInputData<Value = unknown>(input: Readonly<{
+  registry: ContractsRegistry | readonly ContractDefinition[];
+  contractName: string;
+  entryName: string;
+  kind?: ContractEntryKind | undefined;
+  bytes: Uint8Array;
+  allowSequentialLayout?: boolean | undefined;
+}>): Readonly<{
+  value: Value;
+}>;

package/src/typecheck-stubs/sdk.d.ts

@@ -0,0 +1,254 @@
+export type SdkConfig = Readonly<{
+  txQueue?: Readonly<{
+    enabled?: boolean | undefined;
+  }> | undefined;
+}>;
+
+export type SeedSourceInput =
+  | Readonly<{
+      fromSeed: string;
+      fromVault?: never;
+    }>
+  | Readonly<{
+      fromVault: string;
+      fromSeed?: never;
+    }>;
+
+export type QueryRawResult = Readonly<{
+  responseBytes: Uint8Array;
+  responseBase64: string;
+  attempts: number;
+}>;
+
+export type SendTransactionResult = Readonly<{
+  txBytes: Uint8Array;
+  txId: string;
+  networkTxId: string;
+  targetTick: bigint;
+  broadcast: unknown;
+}>;
+
+export type QueryRawInput = Readonly<{
+  contractIndex: number | bigint;
+  inputType: number | bigint;
+  inputBytes?: Uint8Array | undefined;
+  inputBase64?: string | undefined;
+  expectedOutputSize?: number | undefined;
+  retries?: number | undefined;
+  retryDelayMs?: number | undefined;
+  signal?: AbortSignal | undefined;
+}>;
+
+export type SendTransactionInput = SeedSourceInput &
+  Readonly<{
+    toIdentity: string;
+    amount: bigint;
+    targetTick?: number | bigint | undefined;
+    inputType?: number | undefined;
+    inputBytes?: Uint8Array | undefined;
+  }>;
+
+export type BuildSignedTransferInput = SeedSourceInput &
+  Readonly<{
+    toIdentity: string;
+    amount: bigint;
+    targetTick?: bigint | number | undefined;
+  }>;
+
+export type SendAndConfirmInput = BuildSignedTransferInput &
+  Readonly<{
+    timeoutMs?: number | undefined;
+    pollIntervalMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+  }>;
+
+export type SendTransferResult = Readonly<{
+  txBytes: Uint8Array;
+  txId: string;
+  networkTxId: string;
+  targetTick: bigint;
+  broadcast: unknown;
+}>;
+
+export type TickInfo = Readonly<{
+  tick: bigint;
+  duration: bigint;
+  epoch: bigint;
+  initialTick: bigint;
+}>;
+
+export type LiveBalance = Readonly<{
+  id: string;
+  balance: bigint;
+  validForTick: bigint;
+  latestIncomingTransferTick: bigint;
+  latestOutgoingTransferTick: bigint;
+  incomingAmount: bigint;
+  outgoingAmount: bigint;
+  numberOfIncomingTransfers: bigint;
+  numberOfOutgoingTransfers: bigint;
+}>;
+
+export type LastProcessedTick = Readonly<{
+  tickNumber: bigint;
+  epoch: bigint;
+  intervalInitialTick: bigint;
+}>;
+
+export type QueryTransaction = Readonly<{
+  hash: string;
+  amount: bigint;
+  source: string;
+  destination: string;
+  tickNumber: bigint;
+  timestamp: bigint;
+  inputType: bigint;
+  inputSize: bigint;
+  inputData: string;
+  signature: string;
+  moneyFlew?: boolean;
+}>;
+
+export type Hits = Readonly<{
+  total: bigint;
+  from: bigint;
+  size: bigint;
+}>;
+
+export type Range = Readonly<{
+  gt?: string | undefined;
+  gte?: string | undefined;
+  lt?: string | undefined;
+  lte?: string | undefined;
+}>;
+
+export type Pagination = Readonly<{
+  offset?: bigint | undefined;
+  size?: bigint | undefined;
+}>;
+
+export type TransactionsForIdentityRequest = Readonly<{
+  identity: string;
+  filters?: Readonly<Record<string, string>> | undefined;
+  ranges?: Readonly<Record<string, Range>> | undefined;
+  pagination?: Pagination | undefined;
+}>;
+
+export type TransactionsForIdentityResponse = Readonly<{
+  validForTick: bigint;
+  hits: Hits;
+  transactions: readonly QueryTransaction[];
+}>;
+
+export type VaultSummary = Readonly<{
+  name: string;
+  identity: string;
+  seedIndex: number;
+  createdAt: string;
+  updatedAt: string;
+}>;
+
+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 VaultKdfParams = Readonly<Record<string, unknown>>;
+
+export type VaultHeader = Readonly<{
+  vaultVersion: number;
+  kdf: Readonly<{
+    name: string;
+    params: VaultKdfParams;
+  }>;
+}>;
+
+export type VaultExport = VaultHeader &
+  Readonly<{
+    entries: readonly VaultEntry[];
+  }>;
+
+export type VaultStore = Readonly<{
+  read(): Promise<string | null>;
+  write(value: string): Promise<void>;
+  remove?(): Promise<void>;
+  label?: string;
+}>;
+
+export type OpenSeedVaultBrowserInput = Readonly<{
+  passphrase: string;
+  create?: boolean | undefined;
+  autoSave?: boolean | undefined;
+  kdfParams?: Readonly<Record<string, unknown>> | undefined;
+  store: VaultStore;
+  path?: string | undefined;
+}>;
+
+export type OpenSeedVaultInput = Readonly<{
+  path: string;
+  passphrase: string;
+  create?: boolean | undefined;
+  autoSave?: boolean | undefined;
+  lock?: boolean | undefined;
+  lockTimeoutMs?: number | undefined;
+  kdfParams?: Readonly<Record<string, unknown>> | undefined;
+}>;
+
+export class VaultError extends Error {}
+export class VaultNotFoundError extends VaultError {}
+export class VaultInvalidPassphraseError extends VaultError {}
+export class VaultEntryNotFoundError extends VaultError {}
+export class VaultEntryExistsError extends VaultError {}
+
+export type SeedVault = Readonly<{
+  path: string;
+  list(): readonly VaultSummary[];
+  getSeed(ref: string): Promise<string>;
+  importEncrypted(
+    input: VaultExport | string,
+    options?: Readonly<{ mode?: "merge" | "replace"; sourcePassphrase?: string }>,
+  ): Promise<void>;
+}>;
+
+export declare function openSeedVaultBrowser(input: OpenSeedVaultBrowserInput): Promise<SeedVault>;
+export declare function createLocalStorageVaultStore(key: string, storage?: Storage): VaultStore;
+export declare function createMemoryVaultStore(label?: string): VaultStore;
+export declare function openSeedVault(input: OpenSeedVaultInput): Promise<SeedVault>;
+export declare function vaultExists(path: string): Promise<boolean>;
+
+export type SdkInstance = Readonly<{
+  rpc: Readonly<{
+    live: Readonly<{
+      tickInfo(): Promise<TickInfo>;
+      balance(identity: string): Promise<LiveBalance>;
+    }>;
+    query: Readonly<{
+      getLastProcessedTick(): Promise<LastProcessedTick>;
+      getTransactionsForIdentity(
+        input: TransactionsForIdentityRequest,
+      ): Promise<TransactionsForIdentityResponse>;
+    }>;
+  }>;
+  contracts: Readonly<{
+    queryRaw(input: QueryRawInput): Promise<QueryRawResult>;
+  }>;
+  transactions: Readonly<{
+    send(input: SendTransactionInput): Promise<SendTransactionResult>;
+  }>;
+  transfers: Readonly<{
+    send(input: BuildSignedTransferInput): Promise<SendTransferResult>;
+    sendAndConfirm(input: SendAndConfirmInput): Promise<SendTransferResult>;
+  }>;
+}>;
+
+export declare function createSdk(config?: SdkConfig): SdkInstance;

package/src/vault/browser.ts

@@ -0,0 +1,52 @@
+import {
+  createLocalStorageVaultStore as createLocalStorageVaultStoreSdk,
+  createMemoryVaultStore as createMemoryVaultStoreSdk,
+  openSeedVaultBrowser,
+} from "@qubic.ts/sdk/browser";
+import type {
+  OpenSeedVaultBrowserInput,
+  SeedVault,
+  VaultExport,
+  VaultStore,
+} from "@qubic.ts/sdk/browser";
+
+export type CreateBrowserVaultInput = Omit<OpenSeedVaultBrowserInput, "create">;
+
+export async function openBrowserVault(input: OpenSeedVaultBrowserInput): Promise<SeedVault> {
+  return openSeedVaultBrowser(input);
+}
+
+export async function createBrowserVault(input: CreateBrowserVaultInput): Promise<SeedVault> {
+  return openBrowserVault({ ...input, create: true });
+}
+
+export async function importBrowserVault(
+  input: Readonly<{
+    store: VaultStore;
+    passphrase: string;
+    exportData: VaultExport | string;
+    mode?: "merge" | "replace";
+    sourcePassphrase?: string;
+  }>,
+): Promise<SeedVault> {
+  const vault = await openBrowserVault({
+    store: input.store,
+    passphrase: input.passphrase,
+    create: true,
+  });
+  await vault.importEncrypted(input.exportData, {
+    ...(input.mode === undefined ? {} : { mode: input.mode }),
+    ...(input.sourcePassphrase === undefined
+      ? {}
+      : { sourcePassphrase: input.sourcePassphrase }),
+  });
+  return vault;
+}
+
+export function createLocalStorageVaultStore(key: string): VaultStore {
+  return createLocalStorageVaultStoreSdk(key);
+}
+
+export function createMemoryVaultStore(label?: string): VaultStore {
+  return createMemoryVaultStoreSdk(label);
+}

package/src/vault/node.ts

@@ -0,0 +1,39 @@
+import { openSeedVault, vaultExists as vaultExistsSdk } from "@qubic.ts/sdk/node";
+import type { OpenSeedVaultInput, SeedVault, VaultExport } from "@qubic.ts/sdk/node";
+
+export type CreateVaultInput = Omit<OpenSeedVaultInput, "create">;
+
+export async function openNodeVault(input: OpenSeedVaultInput): Promise<SeedVault> {
+  return openSeedVault(input);
+}
+
+export async function createNodeVault(input: CreateVaultInput): Promise<SeedVault> {
+  return openSeedVault({ ...input, create: true });
+}
+
+export async function importNodeVault(
+  input: Readonly<{
+    path: string;
+    passphrase: string;
+    exportData: VaultExport | string;
+    mode?: "merge" | "replace";
+    sourcePassphrase?: string;
+  }>,
+): Promise<SeedVault> {
+  const vault = await openNodeVault({
+    path: input.path,
+    passphrase: input.passphrase,
+    create: true,
+  });
+  await vault.importEncrypted(input.exportData, {
+    ...(input.mode === undefined ? {} : { mode: input.mode }),
+    ...(input.sourcePassphrase === undefined
+      ? {}
+      : { sourcePassphrase: input.sourcePassphrase }),
+  });
+  return vault;
+}
+
+export async function vaultExists(path: string): Promise<boolean> {
+  return vaultExistsSdk(path);
+}

package/src/vault/runtime-boundary.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "bun:test";
+import * as browserRuntime from "../browser.js";
+import * as nodeRuntime from "../node.js";
+
+describe("vault runtime boundaries", () => {
+  it("browser runtime exports browser vault helpers only", () => {
+    expect(typeof browserRuntime.openBrowserVault).toBe("function");
+    expect(typeof browserRuntime.createBrowserVault).toBe("function");
+    expect(typeof browserRuntime.importBrowserVault).toBe("function");
+    expect(typeof browserRuntime.createLocalStorageVaultStore).toBe("function");
+    expect(typeof browserRuntime.createMemoryVaultStore).toBe("function");
+    expect("openNodeVault" in browserRuntime).toBe(false);
+  });
+
+  it("node runtime exports node vault helpers only", () => {
+    expect(typeof nodeRuntime.openNodeVault).toBe("function");
+    expect(typeof nodeRuntime.createNodeVault).toBe("function");
+    expect(typeof nodeRuntime.importNodeVault).toBe("function");
+    expect(typeof nodeRuntime.vaultExists).toBe("function");
+    expect("openBrowserVault" in nodeRuntime).toBe(false);
+  });
+});

package/src/wallet/metamask-snap.test.ts

@@ -0,0 +1,73 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { MetaMaskSnapConnector } from "./metamask-snap.js";
+
+type FakeProvider = {
+  request: (input: { method: string; params?: unknown }) => Promise<unknown>;
+};
+
+describe("MetaMaskSnapConnector", () => {
+  const previous = (globalThis as typeof globalThis & { ethereum?: FakeProvider | undefined })
+    .ethereum;
+
+  beforeEach(() => {
+    (globalThis as typeof globalThis & { ethereum?: FakeProvider }).ethereum = {
+      request: async ({ method }) => {
+        if (method === "wallet_requestSnaps") return {};
+        if (method === "wallet_invokeSnap") {
+          return [{ address: "QUBICADDRESS1", alias: "main" }, { address: "QUBICADDRESS2" }];
+        }
+        return {};
+      },
+    };
+  });
+
+  afterEach(() => {
+    const anyGlobal = globalThis as typeof globalThis & { ethereum?: FakeProvider | undefined };
+    if (previous) {
+      anyGlobal.ethereum = previous;
+    } else {
+      delete anyGlobal.ethereum;
+    }
+  });
+
+  it("detects availability", () => {
+    const connector = new MetaMaskSnapConnector();
+    expect(connector.isAvailable()).toBe(true);
+  });
+
+  it("connects and requests accounts", async () => {
+    const connector = new MetaMaskSnapConnector();
+    const result = await connector.connect();
+    expect(result.status).toBe("connected");
+    if (result.status !== "connected") {
+      throw new Error("Expected immediate connected result from snap connector");
+    }
+    expect(result.accounts.length).toBe(2);
+  });
+
+  it("requests accounts", async () => {
+    const connector = new MetaMaskSnapConnector();
+    const accounts = await connector.requestAccounts();
+    expect(accounts.length).toBe(2);
+    expect(accounts[0]?.address).toBe("QUBICADDRESS1");
+  });
+
+  it("signs transactions", async () => {
+    const signed = Buffer.from([1, 2, 3]).toString("base64");
+    (globalThis as typeof globalThis & { ethereum?: FakeProvider }).ethereum = {
+      request: async ({ method }) => {
+        if (method === "wallet_requestSnaps") return {};
+        if (method === "wallet_invokeSnap") return { signedTx: signed };
+        return {};
+      },
+    };
+    const connector = new MetaMaskSnapConnector();
+    const result = await connector.signTransaction({
+      kind: "snap",
+      txBytes: new Uint8Array([9, 9, 9]),
+      signatureOffset: 0,
+    });
+    expect(result.signedTxBase64).toBe(signed);
+    expect(result.signedTxBytes?.length).toBe(3);
+  });
+});

package/src/wallet/metamask-snap.ts

@@ -0,0 +1,121 @@
+import type { MetaMaskInpageProvider } from "@metamask/providers";
+import type {
+  WalletAccount,
+  WalletConnector,
+  WalletConnectResult,
+  WalletSignTransactionRequest,
+  WalletSignTransactionResult,
+} from "./types.js";
+import { base64ToBytes, bytesToBase64 } from "./utils.js";
+
+export type MetaMaskSnapConfig = Readonly<{
+  snapId?: string;
+  requestAccountsMethod?: string;
+  signTransactionMethod?: string;
+  accountIndex?: number;
+}>;
+
+export class MetaMaskSnapConnector implements WalletConnector {
+  readonly type = "metamask-snap" as const;
+  private readonly snapId: string;
+  private readonly requestAccountsMethod: string;
+  private readonly signTransactionMethod: string;
+  private readonly accountIndex: number | undefined;
+
+  constructor(config: MetaMaskSnapConfig = {}) {
+    this.snapId = config.snapId ?? "npm:@qubic-lib/qubic-mm-snap";
+    this.requestAccountsMethod = config.requestAccountsMethod ?? "getAccounts";
+    this.signTransactionMethod = config.signTransactionMethod ?? "signTransaction";
+    this.accountIndex = config.accountIndex;
+  }
+
+  isAvailable(): boolean {
+    return Boolean(this.getProvider());
+  }
+
+  async connect(): Promise<WalletConnectResult> {
+    const provider = this.requireProvider();
+    await provider.request({
+      method: "wallet_requestSnaps",
+      params: {
+        [this.snapId]: {},
+      },
+    });
+    const accounts = await this.requestAccounts();
+    return { status: "connected", accounts };
+  }
+
+  async disconnect(): Promise<void> {
+    // Snaps do not expose an explicit disconnect; clear local state in provider.
+  }
+
+  async requestAccounts(): Promise<readonly WalletAccount[]> {
+    const provider = this.requireProvider();
+    try {
+      const result = await provider.request({
+        method: "wallet_invokeSnap",
+        params: {
+          snapId: this.snapId,
+          request: {
+            method: this.requestAccountsMethod,
+            params: {
+              accountIdx: this.accountIndex ?? 0,
+            },
+          },
+        },
+      });
+      if (Array.isArray(result)) {
+        return result
+          .filter((entry) => entry && typeof entry.address === "string")
+          .map((entry) =>
+            entry.alias === undefined
+              ? { address: entry.address }
+              : { address: entry.address, alias: entry.alias },
+          );
+      }
+      return [];
+    } catch {
+      return [];
+    }
+  }
+
+  async signTransaction(input: WalletSignTransactionRequest): Promise<WalletSignTransactionResult> {
+    if (input.kind !== "snap") {
+      throw new Error("MetaMask Snap expects kind: 'snap'");
+    }
+    const provider = this.requireProvider();
+    const signed = await provider.request({
+      method: "wallet_invokeSnap",
+      params: {
+        snapId: this.snapId,
+        request: {
+          method: this.signTransactionMethod,
+          params: {
+            base64Tx: bytesToBase64(input.txBytes),
+            offset: input.signatureOffset,
+            accountIdx: input.accountIndex ?? this.accountIndex ?? 0,
+          },
+        },
+      },
+    });
+    const result = signed as { signedTx?: string } | undefined;
+    const signedBase64 = result?.signedTx ?? String(signed);
+    return {
+      signedTxBase64: signedBase64,
+      signedTxBytes: base64ToBytes(signedBase64),
+    };
+  }
+
+  private getProvider(): MetaMaskInpageProvider | undefined {
+    const anyGlobal = globalThis as typeof globalThis & { ethereum?: MetaMaskInpageProvider };
+    return anyGlobal.ethereum;
+  }
+
+  private requireProvider(): MetaMaskInpageProvider {
+    const provider = this.getProvider();
+    if (!provider) {
+      throw new Error("MetaMask provider not available");
+    }
+    return provider;
+  }
+}

package/src/wallet/types.ts

@@ -0,0 +1,55 @@
+export type WalletConnectorType = "metamask-snap" | "walletconnect" | "vault";
+
+export type WalletStatus = "idle" | "connecting" | "connected" | "error";
+
+export type WalletAccount = Readonly<{
+  address: string;
+  alias?: string;
+}>;
+
+export type WalletSession = Readonly<{
+  type: WalletConnectorType;
+  accounts: readonly WalletAccount[];
+}>;
+
+export type WalletSignTransactionRequest =
+  | Readonly<{
+      kind: "snap";
+      txBytes: Uint8Array;
+      signatureOffset: number;
+      accountIndex?: number;
+    }>
+  | Readonly<{
+      kind: "walletconnect";
+      from: string;
+      to: string;
+      amount: number;
+      tick?: number;
+      inputType?: number;
+      payloadBase64?: string | null;
+      nonce?: string;
+    }>
+  | Readonly<{
+      kind: "vault";
+      unsignedTxBytes: Uint8Array;
+      vaultRef?: string;
+    }>;
+
+export type WalletSignTransactionResult = Readonly<{
+  signedTxBase64: string;
+  signedTxBytes?: Uint8Array;
+}>;
+
+export type WalletConnectResult =
+  | Readonly<{ status: "connected"; accounts: readonly WalletAccount[] }>
+  | Readonly<{ status: "pending"; uri: string; approve: () => Promise<readonly WalletAccount[]> }>;
+
+export type WalletConnector = Readonly<{
+  type: WalletConnectorType;
+  isAvailable(): boolean | Promise<boolean>;
+  connect(): Promise<WalletConnectResult>;
+  disconnect(): Promise<void>;
+  requestAccounts(): Promise<readonly WalletAccount[]>;
+  signTransaction(input: WalletSignTransactionRequest): Promise<WalletSignTransactionResult>;
+  restore?(): Promise<readonly WalletAccount[] | null>;
+}>;