@qubic.ts/react 0.1.0

package/src/hooks/use-tick-info.ts

@@ -0,0 +1,16 @@
+import type { TickInfo } from "@qubic.ts/sdk";
+import type { UseQueryOptions, UseQueryResult } from "@tanstack/react-query";
+import { useQuery } from "@tanstack/react-query";
+import { useSdk } from "../providers/sdk-provider.js";
+import { queryKeys } from "../query/keys.js";
+
+export type UseTickInfoOptions = Omit<UseQueryOptions<TickInfo, Error>, "queryKey" | "queryFn">;
+
+export function useTickInfo(options: UseTickInfoOptions = {}): UseQueryResult<TickInfo, Error> {
+  const sdk = useSdk();
+  return useQuery({
+    ...options,
+    queryKey: queryKeys.tickInfo(),
+    queryFn: () => sdk.rpc.live.tickInfo(),
+  });
+}

package/src/hooks/use-transactions.ts

@@ -0,0 +1,97 @@
+import type {
+  TransactionsForIdentityRequest,
+  TransactionsForIdentityResponse,
+} from "@qubic.ts/sdk";
+import type { InfiniteData, UseInfiniteQueryOptions, UseInfiniteQueryResult } from "@tanstack/react-query";
+import { useInfiniteQuery } from "@tanstack/react-query";
+import { useSdk } from "../providers/sdk-provider.js";
+import { queryKeys } from "../query/keys.js";
+
+export type UseTransactionsInput = Readonly<{
+  identity: string | undefined;
+  filters?: TransactionsForIdentityRequest["filters"];
+  ranges?: TransactionsForIdentityRequest["ranges"];
+  pageSize?: bigint | number;
+  limit?: bigint | number;
+  offset?: bigint | number;
+}>;
+
+export type UseTransactionsOptions = Omit<
+  UseInfiniteQueryOptions<
+    TransactionsForIdentityResponse,
+    Error,
+    InfiniteData<TransactionsForIdentityResponse>,
+    ReturnType<typeof queryKeys.transactions>,
+    bigint
+  >,
+  "queryKey" | "queryFn" | "getNextPageParam" | "initialPageParam"
+>;
+
+export function useTransactions(
+  input: UseTransactionsInput,
+  options: UseTransactionsOptions = {},
+): UseInfiniteQueryResult<InfiniteData<TransactionsForIdentityResponse>, Error> {
+  const sdk = useSdk();
+  const identity = input.identity;
+  const enabled = Boolean(identity) && (options.enabled ?? true);
+  const startOffset = toBigint(input.offset ?? 0);
+  const pageSize = toBigint(input.pageSize ?? 100);
+  const limit = input.limit !== undefined ? toBigint(input.limit) : undefined;
+  const paramsKey = serializeParams(input);
+
+  return useInfiniteQuery({
+    ...options,
+    queryKey: queryKeys.transactions(identity ?? "", paramsKey),
+    enabled,
+    initialPageParam: startOffset,
+    queryFn: async ({ pageParam }) => {
+      if (!identity) {
+        throw new Error("useTransactions requires identity");
+      }
+      const consumed = pageParam - startOffset;
+      const remaining = limit !== undefined ? limit - consumed : undefined;
+      const size = remaining !== undefined ? minBigint(pageSize, remaining) : pageSize;
+      return sdk.rpc.query.getTransactionsForIdentity({
+        identity,
+        ...(input.filters === undefined ? {} : { filters: input.filters }),
+        ...(input.ranges === undefined ? {} : { ranges: input.ranges }),
+        pagination: { offset: pageParam, size },
+      });
+    },
+    getNextPageParam: (lastPage, pages) => {
+      if (lastPage.transactions.length === 0) return undefined;
+      const totalFetched = pages.reduce((acc, page) => acc + BigInt(page.transactions.length), 0n);
+      if (limit !== undefined && totalFetched >= limit) return undefined;
+      const nextOffset = startOffset + totalFetched;
+      if (nextOffset >= lastPage.hits.total) return undefined;
+      return nextOffset;
+    },
+  });
+}
+
+function serializeParams(input: UseTransactionsInput): string {
+  const payload = {
+    identity: input.identity ?? "",
+    filters: input.filters ?? null,
+    ranges: input.ranges ?? null,
+    pageSize: input.pageSize ?? null,
+    limit: input.limit ?? null,
+    offset: input.offset ?? null,
+  };
+  return JSON.stringify(payload, (_key, value) => {
+    if (typeof value === "bigint") return value.toString();
+    return value;
+  });
+}
+
+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 minBigint(a: bigint, b: bigint): bigint {
+  return a < b ? a : b;
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+export type {
+  ContractCodecSchema,
+  ContractFunctionInput,
+  ContractFunctionName,
+  ContractFunctionOutput,
+  ContractHandleLike,
+  ContractMutationResult,
+  ContractProcedureInput,
+  ContractProcedureName,
+  ContractProcedureOutput,
+  ContractProcedureTxInput,
+  ContractQueryInput,
+  ContractQueryResult,
+  ContractRegistryInput,
+  ContractRegistrySchema,
+  ContractRegistryToSchema,
+} from "./contract-types.js";
+export type { UseContractMutationOptions } from "./hooks/use-contract-mutation.js";
+export { useContractMutation } from "./hooks/use-contract-mutation.js";
+export type { UseContractQueryOptions } from "./hooks/use-contract-query.js";
+export { useContractQuery } from "./hooks/use-contract-query.js";
+export { useContract } from "./hooks/use-contract.js";
+export type { UseBalanceOptions } from "./hooks/use-balance.js";
+export { useBalance } from "./hooks/use-balance.js";
+export type { UseLastProcessedTickOptions } from "./hooks/use-last-processed-tick.js";
+export { useLastProcessedTick } from "./hooks/use-last-processed-tick.js";
+export type { UseTickInfoOptions } from "./hooks/use-tick-info.js";
+export { useTickInfo } from "./hooks/use-tick-info.js";
+export type { UseTransactionsInput, UseTransactionsOptions } from "./hooks/use-transactions.js";
+export { useTransactions } from "./hooks/use-transactions.js";
+export type { UseSendAndConfirmOptions } from "./hooks/use-send-and-confirm.js";
+export { useSendAndConfirm } from "./hooks/use-send-and-confirm.js";
+export type { UseSendOptions } from "./hooks/use-send.js";
+export { useSend } from "./hooks/use-send.js";
+export type { QubicQueryProviderProps } from "./providers/query-provider.js";
+export { QubicQueryProvider } from "./providers/query-provider.js";
+export type { SdkProviderProps } from "./providers/sdk-provider.js";
+export {
+  createSdkProvider,
+  SdkProvider,
+  useContractsRegistry,
+  useSdk,
+} from "./providers/sdk-provider.js";
+export type {
+  WalletContextValue,
+  WalletProviderProps,
+  WalletState,
+} from "./providers/wallet-provider.js";
+export { useWallet, WalletProvider } from "./providers/wallet-provider.js";
+export { queryKeys } from "./query/keys.js";
+export type { MetaMaskSnapConfig } from "./wallet/metamask-snap.js";
+export { MetaMaskSnapConnector } from "./wallet/metamask-snap.js";
+export type {
+  WalletAccount,
+  WalletConnector,
+  WalletConnectorType,
+  WalletConnectResult,
+  WalletSession,
+  WalletSignTransactionRequest,
+  WalletSignTransactionResult,
+  WalletStatus,
+} from "./wallet/types.js";
+export type { VaultConnectorConfig } from "./wallet/vault.js";
+export { VaultConnector } from "./wallet/vault.js";
+export type { WalletConnectConfig } from "./wallet/walletconnect.js";
+export { WalletConnectConnector } from "./wallet/walletconnect.js";
+export const reactPackageVersion = "0.0.0-development";

package/src/node.ts

@@ -0,0 +1,21 @@
+export * from "./index.js";
+export type {
+  OpenSeedVaultInput,
+  SeedVault,
+  VaultEntry,
+  VaultEntryEncrypted,
+  VaultExport,
+  VaultHeader,
+  VaultKdfParams,
+  VaultStore,
+  VaultSummary,
+} from "@qubic.ts/sdk/node";
+export {
+  VaultEntryExistsError,
+  VaultEntryNotFoundError,
+  VaultError,
+  VaultInvalidPassphraseError,
+  VaultNotFoundError,
+} from "@qubic.ts/sdk/node";
+export type { CreateVaultInput } from "./vault/node.js";
+export { createNodeVault, importNodeVault, openNodeVault, vaultExists } from "./vault/node.js";

package/src/providers/query-provider.test.tsx

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "bun:test";
+import { QueryClient, useQueryClient } from "@tanstack/react-query";
+import React from "react";
+import TestRenderer from "react-test-renderer";
+import { QubicQueryProvider } from "./query-provider.js";
+
+describe("QubicQueryProvider", () => {
+  it("uses provided query client", () => {
+    const client = new QueryClient();
+    let seen: QueryClient | undefined;
+
+    function Consumer() {
+      seen = useQueryClient();
+      return null;
+    }
+
+    TestRenderer.create(
+      <QubicQueryProvider client={client}>
+        <Consumer />
+      </QubicQueryProvider>,
+    );
+
+    expect(seen).toBe(client);
+  });
+});

package/src/providers/query-provider.tsx

@@ -0,0 +1,13 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+import { useMemo } from "react";
+
+export type QubicQueryProviderProps = Readonly<{
+  client?: QueryClient;
+  children: ReactNode;
+}>;
+
+export function QubicQueryProvider({ client, children }: QubicQueryProviderProps) {
+  const value = useMemo(() => client ?? new QueryClient(), [client]);
+  return <QueryClientProvider client={value}>{children}</QueryClientProvider>;
+}

package/src/providers/sdk-provider.test.tsx

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "bun:test";
+import { coreContractsRegistry } from "@qubic.ts/contracts";
+import { createSdk } from "@qubic.ts/sdk";
+import React from "react";
+import TestRenderer from "react-test-renderer";
+import {
+  createSdkProvider,
+  SdkProvider,
+  useContractsRegistry,
+  useSdk,
+} from "./sdk-provider.js";
+
+describe("SdkProvider", () => {
+  it("provides sdk and contracts registry contexts", () => {
+    const sdk = createSdk({ txQueue: { enabled: false } });
+    let seenSdk: ReturnType<typeof createSdk> | undefined;
+    let seenRegistry: typeof coreContractsRegistry | undefined;
+
+    function Consumer() {
+      seenSdk = useSdk();
+      seenRegistry = useContractsRegistry() as typeof coreContractsRegistry;
+      return null;
+    }
+
+    TestRenderer.create(
+      <SdkProvider sdk={sdk} contractsRegistry={coreContractsRegistry}>
+        <Consumer />
+      </SdkProvider>,
+    );
+
+    expect(seenSdk).toBe(sdk);
+    expect(seenRegistry).toBe(coreContractsRegistry);
+  });
+
+  it("createSdkProvider exposes typed hook helpers", () => {
+    const sdk = createSdk({ txQueue: { enabled: false } });
+    const api = createSdkProvider();
+    let contractApi: ReturnType<typeof api.useContract> | undefined;
+
+    function Consumer() {
+      contractApi = api.useContract("QUTIL");
+      return null;
+    }
+
+    TestRenderer.create(
+      <api.SdkProvider sdk={sdk} contractsRegistry={coreContractsRegistry}>
+        <Consumer />
+      </api.SdkProvider>,
+    );
+
+    expect(typeof contractApi?.query).toBe("function");
+    expect(typeof contractApi?.sendProcedure).toBe("function");
+  });
+});

package/src/providers/sdk-provider.tsx

@@ -0,0 +1,83 @@
+import { coreContractsRegistry } from "@qubic.ts/contracts";
+import type { SdkConfig } from "@qubic.ts/sdk/browser";
+import { createSdk } from "@qubic.ts/sdk/browser";
+import type { ReactNode } from "react";
+import { createContext, useContext, useMemo } from "react";
+import type {
+  ContractFunctionInput,
+  ContractFunctionName,
+  ContractFunctionOutput,
+  ContractProcedureInput,
+  ContractProcedureName,
+  ContractQueryInput,
+  ContractRegistryInput,
+  ContractRegistrySchema,
+  ContractRegistryToSchema,
+} from "../contract-types.js";
+import { useContract } from "../hooks/use-contract.js";
+import type { UseContractMutationOptions } from "../hooks/use-contract-mutation.js";
+import { useContractMutation } from "../hooks/use-contract-mutation.js";
+import type { UseContractQueryOptions } from "../hooks/use-contract-query.js";
+import { useContractQuery } from "../hooks/use-contract-query.js";
+
+type SdkInstance = ReturnType<typeof createSdk>;
+
+const SdkContext = createContext<SdkInstance | null>(null);
+const ContractsRegistryContext = createContext<ContractRegistryInput>(coreContractsRegistry);
+
+export type SdkProviderProps = Readonly<{
+  sdk?: ReturnType<typeof createSdk>;
+  config?: SdkConfig;
+  contractsRegistry?: ContractRegistryInput;
+  children: ReactNode;
+}>;
+
+export function SdkProvider({ sdk, config, contractsRegistry, children }: SdkProviderProps) {
+  const value = useMemo(() => sdk ?? createSdk(config), [sdk, config]);
+  const registry = useMemo(() => contractsRegistry ?? coreContractsRegistry, [contractsRegistry]);
+  return (
+    <SdkContext.Provider value={value}>
+      <ContractsRegistryContext.Provider value={registry}>
+        {children}
+      </ContractsRegistryContext.Provider>
+    </SdkContext.Provider>
+  );
+}
+
+export function useSdk(): SdkInstance {
+  const value = useContext(SdkContext);
+  if (!value) throw new Error("useSdk must be used within SdkProvider");
+  return value;
+}
+
+export function useContractsRegistry(): ContractRegistryInput {
+  return useContext(ContractsRegistryContext);
+}
+
+export function createSdkProvider<
+  Registry extends ContractRegistrySchema = ContractRegistryToSchema<typeof coreContractsRegistry>,
+>() {
+  return {
+    SdkProvider,
+    useSdk,
+    useContract: (name: keyof Registry & string) => useContract(name),
+    useContractQuery: <
+      ContractName extends keyof Registry & string,
+      EntryName extends ContractFunctionName<Registry[ContractName]>,
+    >(
+      name: ContractName,
+      entry: EntryName,
+      input: ContractQueryInput<ContractFunctionInput<Registry[ContractName], EntryName>>,
+      options?: UseContractQueryOptions<ContractFunctionOutput<Registry[ContractName], EntryName>>,
+    ) => useContractQuery<Registry[ContractName], EntryName>(name, entry, input, options),
+    useContractMutation: <
+      ContractName extends keyof Registry & string,
+      EntryName extends ContractProcedureName<Registry[ContractName]>,
+    >(
+      name: ContractName,
+      options?: UseContractMutationOptions<
+        ContractProcedureInput<Registry[ContractName], EntryName>
+      >,
+    ) => useContractMutation<Registry[ContractName], EntryName>(name, options),
+  } as const;
+}

package/src/providers/wallet-provider.test.tsx

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "bun:test";
+import TestRenderer, { act } from "react-test-renderer";
+import type { WalletConnector } from "../wallet/types.js";
+import { useWallet, WalletProvider } from "./wallet-provider.js";
+
+describe("WalletProvider", () => {
+  it("connects with an immediate connector and updates state", async () => {
+    const connector: WalletConnector = {
+      type: "walletconnect",
+      isAvailable: () => true,
+      connect: async () => ({
+        status: "connected",
+        accounts: [{ address: "QUBICADDRESS1" }],
+      }),
+      disconnect: async () => {},
+      requestAccounts: async () => [{ address: "QUBICADDRESS1" }],
+      signTransaction: async () => ({ signedTxBase64: "" }),
+    };
+
+    let api: ReturnType<typeof useWallet> | undefined;
+
+    function Consumer() {
+      api = useWallet();
+      return null;
+    }
+
+    TestRenderer.create(
+      <WalletProvider connectors={[connector]}>
+        <Consumer />
+      </WalletProvider>,
+    );
+
+    await act(async () => {
+      await api?.connect("walletconnect");
+    });
+
+    expect(api?.state.status).toBe("connected");
+    expect(api?.state.accounts[0]?.address).toBe("QUBICADDRESS1");
+  });
+
+  it("handles pending walletconnect sessions via approveWalletConnect", async () => {
+    const connector: WalletConnector = {
+      type: "walletconnect",
+      isAvailable: () => true,
+      connect: async () => ({
+        status: "pending",
+        uri: "wc://example",
+        approve: async () => [{ address: "QUBICADDRESS2" }],
+      }),
+      disconnect: async () => {},
+      requestAccounts: async () => [{ address: "QUBICADDRESS2" }],
+      signTransaction: async () => ({ signedTxBase64: "" }),
+    };
+
+    let api: ReturnType<typeof useWallet> | undefined;
+
+    function Consumer() {
+      api = useWallet();
+      return null;
+    }
+
+    TestRenderer.create(
+      <WalletProvider connectors={[connector]}>
+        <Consumer />
+      </WalletProvider>,
+    );
+
+    await act(async () => {
+      await api?.connect("walletconnect");
+    });
+
+    expect(api?.state.status).toBe("connecting");
+    expect(api?.state.pendingUri).toBe("wc://example");
+
+    await act(async () => {
+      await api?.approveWalletConnect();
+    });
+
+    expect(api?.state.status).toBe("connected");
+    expect(api?.state.accounts[0]?.address).toBe("QUBICADDRESS2");
+  });
+});

package/src/providers/wallet-provider.tsx

@@ -0,0 +1,209 @@
+import type { ReactNode } from "react";
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from "react";
+import type {
+  WalletAccount,
+  WalletConnector,
+  WalletConnectorType,
+  WalletConnectResult,
+  WalletSession,
+  WalletSignTransactionRequest,
+  WalletSignTransactionResult,
+  WalletStatus,
+} from "../wallet/types.js";
+
+export type WalletState = Readonly<{
+  status: WalletStatus;
+  connectorType?: WalletConnectorType;
+  accounts: readonly WalletAccount[];
+  pendingUri?: string;
+  error?: Error;
+}>;
+
+export type WalletProviderProps = Readonly<{
+  connectors: readonly WalletConnector[];
+  autoConnect?: boolean;
+  storageKey?: string;
+  children: ReactNode;
+}>;
+
+export type WalletContextValue = Readonly<{
+  state: WalletState;
+  connect(type: WalletConnectorType): Promise<WalletConnectResult | undefined>;
+  approveWalletConnect(): Promise<void>;
+  disconnect(): Promise<void>;
+  requestAccounts(): Promise<readonly WalletAccount[]>;
+  signTransaction(input: WalletSignTransactionRequest): Promise<WalletSignTransactionResult>;
+}>;
+
+const WalletContext = createContext<WalletContextValue | null>(null);
+
+export function WalletProvider({
+  connectors,
+  autoConnect = true,
+  storageKey = "qubic.wallet.connector",
+  children,
+}: WalletProviderProps) {
+  const [state, setState] = useState<WalletState>({
+    status: "idle",
+    accounts: [],
+  });
+  const pendingApproval = useRef<(() => Promise<readonly WalletAccount[]>) | null>(null);
+
+  const connectorMap = useMemo(() => {
+    const map = new Map<WalletConnectorType, WalletConnector>();
+    for (const connector of connectors) map.set(connector.type, connector);
+    return map;
+  }, [connectors]);
+
+  useEffect(() => {
+    if (!autoConnect) return;
+    const stored = getStorage()?.getItem(storageKey);
+    if (!stored) return;
+    const connector = connectorMap.get(stored as WalletConnectorType);
+    if (!connector || !connector.restore) return;
+    connector
+      .restore()
+      .then((accounts) => {
+        if (!accounts) return;
+        setState({
+          status: "connected",
+          connectorType: connector.type,
+          accounts,
+        });
+      })
+      .catch((error) => {
+        setState({
+          status: "error",
+          connectorType: connector.type,
+          accounts: [],
+          error: error instanceof Error ? error : new Error(String(error)),
+        });
+      });
+  }, [autoConnect, connectorMap, storageKey]);
+
+  const connect = async (type: WalletConnectorType) => {
+    const connector = connectorMap.get(type);
+    if (!connector) {
+      throw new Error(`Unknown wallet connector: ${type}`);
+    }
+    const available = await connector.isAvailable();
+    if (!available) throw new Error(`${type} connector is not available`);
+    setState((current) => ({
+      status: "connecting",
+      connectorType: type,
+      accounts: current.accounts,
+    }));
+    try {
+      const result = await connector.connect();
+      if (result.status === "pending") {
+        pendingApproval.current = result.approve;
+        setState((current) => ({
+          ...current,
+          status: "connecting",
+          pendingUri: result.uri,
+        }));
+        return result;
+      }
+      const session: WalletSession = { type, accounts: result.accounts };
+      persistConnector(session.type, storageKey);
+      setState({
+        status: "connected",
+        connectorType: session.type,
+        accounts: session.accounts,
+      });
+      return result;
+    } catch (error) {
+      setState({
+        status: "error",
+        connectorType: type,
+        accounts: [],
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+      throw error;
+    }
+  };
+
+  const approveWalletConnect = async () => {
+    if (!pendingApproval.current) return;
+    try {
+      const accounts = await pendingApproval.current();
+      const type = state.connectorType ?? "walletconnect";
+      persistConnector(type, storageKey);
+      setState({
+        status: "connected",
+        connectorType: type,
+        accounts,
+      });
+    } catch (error) {
+      setState((current) => ({
+        ...current,
+        status: "error",
+        error: error instanceof Error ? error : new Error(String(error)),
+      }));
+      throw error;
+    } finally {
+      pendingApproval.current = null;
+    }
+  };
+
+  const disconnect = async () => {
+    if (!state.connectorType) return;
+    const connector = connectorMap.get(state.connectorType);
+    if (connector) {
+      await connector.disconnect();
+    }
+    pendingApproval.current = null;
+    setState({ status: "idle", accounts: [] });
+    clearConnector(storageKey);
+  };
+
+  const requestAccounts = async () => {
+    if (!state.connectorType) throw new Error("No connector selected");
+    const connector = connectorMap.get(state.connectorType);
+    if (!connector) throw new Error("Connector not available");
+    const accounts = await connector.requestAccounts();
+    setState((current) => ({ ...current, accounts }));
+    return accounts;
+  };
+
+  const signTransaction = async (input: WalletSignTransactionRequest) => {
+    if (!state.connectorType) throw new Error("No connector selected");
+    const connector = connectorMap.get(state.connectorType);
+    if (!connector) throw new Error("Connector not available");
+    return connector.signTransaction(input);
+  };
+
+  const value: WalletContextValue = {
+    state,
+    connect,
+    approveWalletConnect,
+    disconnect,
+    requestAccounts,
+    signTransaction,
+  };
+
+  return <WalletContext.Provider value={value}>{children}</WalletContext.Provider>;
+}
+
+export function useWallet() {
+  const value = useContext(WalletContext);
+  if (!value) throw new Error("useWallet must be used within WalletProvider");
+  return value;
+}
+
+function getStorage(): Storage | undefined {
+  const anyGlobal = globalThis as typeof globalThis & { localStorage?: Storage };
+  return anyGlobal.localStorage;
+}
+
+function persistConnector(type: WalletConnectorType, storageKey: string) {
+  const storage = getStorage();
+  if (!storage) return;
+  storage.setItem(storageKey, type);
+}
+
+function clearConnector(storageKey: string) {
+  const storage = getStorage();
+  if (!storage) return;
+  storage.removeItem(storageKey);
+}

package/src/query/keys.ts

@@ -0,0 +1,9 @@
+export const queryKeys = {
+  tickInfo: () => ["qubic", "tickInfo"] as const,
+  lastProcessedTick: () => ["qubic", "lastProcessedTick"] as const,
+  balance: (identity: string) => ["qubic", "balance", identity] as const,
+  transactions: (identity: string, paramsKey = "default") =>
+    ["qubic", "transactions", identity, paramsKey] as const,
+  contractQuery: (contract: string, entry: string, argsKey: string) =>
+    ["qubic", "contracts", contract, entry, argsKey] as const,
+};