@qubic.ts/react 0.1.0

package/src/hooks/send-hooks.test.tsx

@@ -0,0 +1,247 @@
+import { describe, expect, it } from "bun:test";
+import type {
+  BuildSignedTransferInput,
+  SendAndConfirmInput,
+  SendTransferResult,
+} from "@qubic.ts/sdk";
+import { createSdk } from "@qubic.ts/sdk";
+import type { UseMutationResult } from "@tanstack/react-query";
+import { QueryClient } from "@tanstack/react-query";
+import React from "react";
+import TestRenderer, { act } from "react-test-renderer";
+import { QubicQueryProvider } from "../providers/query-provider.js";
+import { SdkProvider } from "../providers/sdk-provider.js";
+import { useSend } from "./use-send.js";
+import { useSendAndConfirm } from "./use-send-and-confirm.js";
+
+describe("send mutation hooks", () => {
+  it("useSend exposes success state for successful transfers", async () => {
+    let sendCalls = 0;
+    let receivedInput: BuildSignedTransferInput | undefined;
+    const sdk = createMockSdk({
+      send: async (input) => {
+        sendCalls += 1;
+        receivedInput = input;
+        return createSendResult("send-success");
+      },
+    });
+
+    const queryClient = createTestQueryClient();
+    let hookResult: UseMutationResult<SendTransferResult, Error, BuildSignedTransferInput> | undefined;
+
+    function Consumer() {
+      hookResult = useSend();
+      return null;
+    }
+
+    await act(async () => {
+      TestRenderer.create(
+        <TestProviders sdk={sdk} queryClient={queryClient}>
+          <Consumer />
+        </TestProviders>,
+      );
+    });
+
+    const input = createSendInput("target-1");
+    await act(async () => {
+      await hookResult?.mutateAsync(input);
+    });
+
+    await waitFor(() => hookResult?.isSuccess === true);
+    expect(sendCalls).toBe(1);
+    expect(receivedInput).toEqual(input);
+    expect(hookResult?.data?.txId).toBe("tx-send-success");
+  });
+
+  it("useSend exposes error state when transfer send fails", async () => {
+    const sdk = createMockSdk({
+      send: async () => {
+        throw new Error("send failed");
+      },
+    });
+
+    const queryClient = createTestQueryClient();
+    let hookResult: UseMutationResult<SendTransferResult, Error, BuildSignedTransferInput> | undefined;
+
+    function Consumer() {
+      hookResult = useSend();
+      return null;
+    }
+
+    await act(async () => {
+      TestRenderer.create(
+        <TestProviders sdk={sdk} queryClient={queryClient}>
+          <Consumer />
+        </TestProviders>,
+      );
+    });
+
+    await act(async () => {
+      try {
+        await hookResult?.mutateAsync(createSendInput("target-2"));
+      } catch {
+        // Assertion is state-based below.
+      }
+    });
+
+    await waitFor(() => hookResult?.isError === true);
+    expect(hookResult?.error?.message).toBe("send failed");
+  });
+
+  it("useSendAndConfirm exposes success state for successful send+confirm", async () => {
+    let calls = 0;
+    let receivedInput: SendAndConfirmInput | undefined;
+    const sdk = createMockSdk({
+      sendAndConfirm: async (input) => {
+        calls += 1;
+        receivedInput = input;
+        return createSendResult("send-and-confirm-success");
+      },
+    });
+
+    const queryClient = createTestQueryClient();
+    let hookResult: UseMutationResult<SendTransferResult, Error, SendAndConfirmInput> | undefined;
+
+    function Consumer() {
+      hookResult = useSendAndConfirm();
+      return null;
+    }
+
+    await act(async () => {
+      TestRenderer.create(
+        <TestProviders sdk={sdk} queryClient={queryClient}>
+          <Consumer />
+        </TestProviders>,
+      );
+    });
+
+    const input = createSendAndConfirmInput("target-3");
+    await act(async () => {
+      await hookResult?.mutateAsync(input);
+    });
+
+    await waitFor(() => hookResult?.isSuccess === true);
+    expect(calls).toBe(1);
+    expect(receivedInput).toEqual(input);
+    expect(hookResult?.data?.txId).toBe("tx-send-and-confirm-success");
+  });
+
+  it("useSendAndConfirm exposes error state on failure", async () => {
+    const sdk = createMockSdk({
+      sendAndConfirm: async () => {
+        throw new Error("sendAndConfirm failed");
+      },
+    });
+
+    const queryClient = createTestQueryClient();
+    let hookResult: UseMutationResult<SendTransferResult, Error, SendAndConfirmInput> | undefined;
+
+    function Consumer() {
+      hookResult = useSendAndConfirm();
+      return null;
+    }
+
+    await act(async () => {
+      TestRenderer.create(
+        <TestProviders sdk={sdk} queryClient={queryClient}>
+          <Consumer />
+        </TestProviders>,
+      );
+    });
+
+    await act(async () => {
+      try {
+        await hookResult?.mutateAsync(createSendAndConfirmInput("target-4"));
+      } catch {
+        // Assertion is state-based below.
+      }
+    });
+
+    await waitFor(() => hookResult?.isError === true);
+    expect(hookResult?.error?.message).toBe("sendAndConfirm failed");
+  });
+});
+
+function createTestQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+      },
+      mutations: {
+        retry: false,
+      },
+    },
+  });
+}
+
+function TestProviders(props: {
+  sdk: ReturnType<typeof createSdk>;
+  queryClient: QueryClient;
+  children: React.ReactNode;
+}) {
+  return (
+    <QubicQueryProvider client={props.queryClient}>
+      <SdkProvider sdk={props.sdk}>{props.children}</SdkProvider>
+    </QubicQueryProvider>
+  );
+}
+
+function createMockSdk(overrides: Readonly<{
+  send?: (input: BuildSignedTransferInput) => Promise<SendTransferResult>;
+  sendAndConfirm?: (input: SendAndConfirmInput) => Promise<SendTransferResult>;
+}>): ReturnType<typeof createSdk> {
+  return {
+    transfers: {
+      send: overrides.send ?? (async () => createSendResult("default-send")),
+      sendAndConfirm:
+        overrides.sendAndConfirm ?? (async () => createSendResult("default-send-and-confirm")),
+    },
+  } as unknown as ReturnType<typeof createSdk>;
+}
+
+function createSendInput(toIdentity: string): BuildSignedTransferInput {
+  return {
+    fromSeed: "a".repeat(55),
+    toIdentity,
+    amount: 1n,
+    targetTick: 7n,
+  };
+}
+
+function createSendAndConfirmInput(toIdentity: string): SendAndConfirmInput {
+  return {
+    ...createSendInput(toIdentity),
+    timeoutMs: 2000,
+    pollIntervalMs: 100,
+  };
+}
+
+function createSendResult(tag: string): SendTransferResult {
+  return {
+    txBytes: new Uint8Array([1, 2, 3]),
+    txId: `tx-${tag}`,
+    networkTxId: `network-${tag}`,
+    targetTick: 8n,
+    broadcast: {
+      peersBroadcasted: 1,
+      encodedTransaction: "AQID",
+      transactionId: `network-${tag}`,
+    },
+  };
+}
+
+async function waitFor(predicate: () => boolean, timeoutMs = 3000): Promise<void> {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (predicate()) return;
+    await act(async () => {
+      await sleep(10);
+    });
+  }
+  throw new Error("Timed out waiting for condition");
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/hooks/use-balance.ts

@@ -0,0 +1,27 @@
+import type { LiveBalance } 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 UseBalanceOptions = Omit<UseQueryOptions<LiveBalance, Error>, "queryKey" | "queryFn">;
+
+export function useBalance(
+  identity: string | undefined,
+  options: UseBalanceOptions = {},
+): UseQueryResult<LiveBalance, Error> {
+  const sdk = useSdk();
+  const enabled = Boolean(identity) && (options.enabled ?? true);
+
+  return useQuery({
+    ...options,
+    queryKey: identity ? queryKeys.balance(identity) : queryKeys.balance(""),
+    enabled,
+    queryFn: async () => {
+      if (!identity) {
+        throw new Error("useBalance requires identity");
+      }
+      return sdk.rpc.live.balance(identity);
+    },
+  });
+}

package/src/hooks/use-contract-mutation.ts

@@ -0,0 +1,50 @@
+import type { UseMutationOptions, UseMutationResult } from "@tanstack/react-query";
+import { useMutation } from "@tanstack/react-query";
+import type {
+  ContractCodecSchema,
+  ContractMutationResult,
+  ContractProcedureInput,
+  ContractProcedureOutput,
+  ContractProcedureTxInput,
+} from "../contract-types.js";
+import { useContract } from "./use-contract.js";
+
+export type UseContractMutationOptions<Input = unknown> = Omit<
+  UseMutationOptions<ContractMutationResult, Error, ContractProcedureTxInput<Input>>,
+  "mutationFn"
+>;
+
+type TypedProcedureInput<
+  Schema extends ContractCodecSchema,
+  Name extends string,
+> = ContractProcedureTxInput<
+  ContractProcedureInput<Schema, Name>,
+  ContractProcedureOutput<Schema, Name>
+> &
+  Readonly<{ name: Name }>;
+
+export function useContractMutation<
+  Schema extends ContractCodecSchema,
+  Name extends keyof NonNullable<Schema["procedures"]> & string,
+>(
+  nameOrIndex: string | number,
+  options?: UseContractMutationOptions<ContractProcedureInput<Schema, Name>>,
+): UseMutationResult<
+  ContractMutationResult<ContractProcedureOutput<Schema, Name>>,
+  Error,
+  TypedProcedureInput<Schema, Name>
+>;
+export function useContractMutation<Input = unknown>(
+  nameOrIndex: string | number,
+  options?: UseContractMutationOptions<Input>,
+): UseMutationResult<ContractMutationResult, Error, ContractProcedureTxInput<Input>>;
+export function useContractMutation<Input = unknown>(
+  nameOrIndex: string | number,
+  options: UseContractMutationOptions<Input> = {},
+): UseMutationResult<ContractMutationResult, Error, ContractProcedureTxInput<Input>> {
+  const contract = useContract(nameOrIndex);
+  return useMutation({
+    ...options,
+    mutationFn: (input) => contract.sendProcedure<Input, unknown>(input),
+  });
+}

package/src/hooks/use-contract-query.ts

@@ -0,0 +1,71 @@
+import type { UseQueryOptions, UseQueryResult } from "@tanstack/react-query";
+import { useQuery } from "@tanstack/react-query";
+import type {
+  ContractCodecSchema,
+  ContractFunctionInput,
+  ContractFunctionOutput,
+  ContractQueryInput,
+  ContractQueryResult,
+} from "../contract-types.js";
+import { queryKeys } from "../query/keys.js";
+import { useContract } from "./use-contract.js";
+
+export type UseContractQueryOptions<_Output> = Omit<
+  UseQueryOptions<ContractQueryResult<_Output>, Error>,
+  "queryKey" | "queryFn"
+> &
+  Readonly<{
+    inputKey?: string;
+  }>;
+
+export function useContractQuery<
+  Schema extends ContractCodecSchema,
+  Name extends keyof NonNullable<Schema["functions"]> & string,
+>(
+  nameOrIndex: string | number,
+  entry: Name,
+  input: ContractQueryInput<ContractFunctionInput<Schema, Name>>,
+  options?: UseContractQueryOptions<ContractFunctionOutput<Schema, Name>>,
+): UseQueryResult<ContractQueryResult<ContractFunctionOutput<Schema, Name>>, Error>;
+export function useContractQuery<Input = unknown, Output = unknown>(
+  nameOrIndex: string | number,
+  entry: string,
+  input: ContractQueryInput<Input>,
+  options?: UseContractQueryOptions<Output>,
+): UseQueryResult<ContractQueryResult<Output>, Error>;
+export function useContractQuery<Input = unknown, Output = unknown>(
+  nameOrIndex: string | number,
+  entry: string,
+  input: ContractQueryInput<Input>,
+  options: UseContractQueryOptions<Output> = {},
+): UseQueryResult<ContractQueryResult<Output>, Error> {
+  const contract = useContract(nameOrIndex);
+  const inputKey = options.inputKey ?? defaultInputKey(input);
+
+  return useQuery({
+    ...options,
+    queryKey: queryKeys.contractQuery(String(nameOrIndex), entry, inputKey),
+    queryFn: () => contract.query<Input, Output>(entry, input),
+  });
+}
+
+function defaultInputKey(input: ContractQueryInput): string {
+  if (input.inputBytes) return toBase64(input.inputBytes);
+  if (input.inputValue !== undefined) {
+    try {
+      return JSON.stringify(input.inputValue, (_key, value) =>
+        typeof value === "bigint" ? value.toString() : value,
+      );
+    } catch {
+      return "value";
+    }
+  }
+  return "empty";
+}
+
+function toBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}

package/src/hooks/use-contract.ts

@@ -0,0 +1,231 @@
+import type { ContractDefinition, ContractEntryKind } from "@qubic.ts/contracts";
+import {
+  bytesToBase64,
+  decodeContractEntryInputData,
+  encodeContractEntryInputData,
+} from "@qubic.ts/contracts";
+import type { SeedSourceInput } from "@qubic.ts/sdk";
+import type {
+  ContractHandleLike,
+  ContractMutationResult,
+  ContractProcedureTxInput,
+  ContractQueryInput,
+  ContractQueryResult,
+  ContractRegistryInput,
+} from "../contract-types.js";
+import { useContractsRegistry, useSdk } from "../providers/sdk-provider.js";
+
+export function useContract(nameOrIndex: string | number): ContractHandleLike {
+  const sdk = useSdk();
+  const registry = useContractsRegistry();
+  const contract = resolveContract(registry, nameOrIndex);
+
+  return {
+    async query<Input = unknown, Output = unknown>(
+      name: string,
+      input: ContractQueryInput<Input>,
+    ): Promise<ContractQueryResult<Output>> {
+      const entry = resolveEntry(contract, "function", name);
+      const inputBytes = resolveInputBytes({
+        registry,
+        contract,
+        entryName: name,
+        kind: "function",
+        input,
+      });
+      const raw = await sdk.contracts.queryRaw({
+        contractIndex: contract.contractIndex,
+        inputType: entry.inputType,
+        inputBytes,
+        ...toDefined("expectedOutputSize", input.expectedOutputSize ?? entry.outputSize),
+        ...toDefined("retries", input.retries),
+        ...toDefined("retryDelayMs", input.retryDelayMs),
+        ...toDefined("signal", input.signal),
+      });
+      const decoded = decodeQueryOutput<Output>({
+        registry,
+        contract,
+        entryName: name,
+        bytes: raw.responseBytes,
+        ...toDefined("allowSequentialLayout", input.allowSequentialLayout),
+        ...toDefined("decodeOutput", input.decodeOutput),
+      });
+      return decoded === undefined ? raw : { ...raw, decoded };
+    },
+    async sendProcedure<Input = unknown, Output = unknown>(
+      input: ContractProcedureTxInput<Input, Output>,
+    ): Promise<ContractMutationResult<Output>> {
+      const entry = resolveEntry(contract, "procedure", input.name);
+      const inputBytes = resolveInputBytes({
+        registry,
+        contract,
+        entryName: input.name,
+        kind: "procedure",
+        input,
+      });
+      const seedSource = resolveSeedSource(input);
+      const toIdentity = resolveToIdentity(contract, input.toIdentity);
+      const tx = await sdk.transactions.send({
+        ...seedSource,
+        toIdentity,
+        amount: input.amount ?? 0n,
+        inputType: entry.inputType,
+        inputBytes,
+        ...toDefined("targetTick", input.targetTick),
+      });
+      const baseResult = {
+        ...tx,
+        responseBytes: tx.txBytes,
+        responseBase64: bytesToBase64(tx.txBytes),
+      };
+      const decoded = input.decodeResponse?.(tx);
+      return decoded === undefined ? baseResult : { ...baseResult, decoded };
+    },
+  };
+}
+
+function resolveContract(
+  registry: ContractRegistryInput,
+  nameOrIndex: string | number,
+): ContractDefinition {
+  const contracts = isContractDefinitionList(registry) ? registry : registry.contracts;
+  const contract =
+    typeof nameOrIndex === "number"
+      ? contracts.find((item) => item.contractIndex === nameOrIndex)
+      : contracts.find((item) => item.name === nameOrIndex);
+  if (!contract) {
+    throw new Error(`Unknown contract: ${String(nameOrIndex)}`);
+  }
+  return contract;
+}
+
+function isContractDefinitionList(
+  registry: ContractRegistryInput,
+): registry is readonly ContractDefinition[] {
+  return Array.isArray(registry);
+}
+
+function resolveEntry(contract: ContractDefinition, kind: ContractEntryKind, name: string) {
+  const entry = contract.entries.find((item) => item.kind === kind && item.name === name);
+  if (!entry) {
+    throw new Error(`Unknown ${kind}: ${contract.name}.${name}`);
+  }
+  return entry;
+}
+
+function resolveInputBytes(options: {
+  registry: ContractRegistryInput;
+  contract: ContractDefinition;
+  entryName: string;
+  kind: ContractEntryKind;
+  input: ContractQueryInput | ContractProcedureTxInput<unknown, unknown>;
+}): Uint8Array {
+  if (options.input.inputBytes) return options.input.inputBytes;
+  if (options.input.inputValue === undefined) {
+    throw new Error(
+      `inputBytes or inputValue is required for ${options.contract.name}.${options.entryName}`,
+    );
+  }
+  return encodeContractEntryInputData({
+    registry: options.registry,
+    contractName: options.contract.name,
+    entryName: options.entryName,
+    kind: options.kind,
+    value: options.input.inputValue,
+    ...toDefined("allowSequentialLayout", options.input.allowSequentialLayout),
+  }).bytes;
+}
+
+function resolveSeedSource(input: ContractProcedureTxInput): SeedSourceInput {
+  if ("fromSeed" in input && typeof input.fromSeed === "string") {
+    return { fromSeed: input.fromSeed };
+  }
+  if ("fromVault" in input && typeof input.fromVault === "string") {
+    return { fromVault: input.fromVault };
+  }
+  throw new Error("Procedure input requires fromSeed or fromVault");
+}
+
+function decodeQueryOutput<Output>(options: {
+  registry: ContractRegistryInput;
+  contract: ContractDefinition;
+  entryName: string;
+  bytes: Uint8Array;
+  allowSequentialLayout?: boolean | undefined;
+  decodeOutput?: boolean | undefined;
+}): Output | undefined {
+  if (options.decodeOutput === false) return undefined;
+  const entry = resolveEntry(options.contract, "function", options.entryName);
+  if (!entry.outputTypeName) return undefined;
+  const patchedRegistry = patchRegistryForOutputDecode({
+    registry: options.registry,
+    contractName: options.contract.name,
+    entryName: options.entryName,
+    outputTypeName: entry.outputTypeName,
+  });
+  try {
+    return decodeContractEntryInputData<Output>({
+      registry: patchedRegistry,
+      contractName: options.contract.name,
+      entryName: options.entryName,
+      kind: "function",
+      bytes: options.bytes,
+      ...toDefined("allowSequentialLayout", options.allowSequentialLayout),
+    }).value;
+  } catch {
+    return undefined;
+  }
+}
+
+function patchRegistryForOutputDecode(options: {
+  registry: ContractRegistryInput;
+  contractName: string;
+  entryName: string;
+  outputTypeName: string;
+}): ContractRegistryInput {
+  if (isContractDefinitionList(options.registry)) {
+    return options.registry.map((contract) => patchContractEntry(contract, options));
+  }
+  return {
+    ...options.registry,
+    contracts: options.registry.contracts.map((contract) => patchContractEntry(contract, options)),
+  };
+}
+
+function patchContractEntry(
+  contract: ContractDefinition,
+  options: { contractName: string; entryName: string; outputTypeName: string },
+): ContractDefinition {
+  if (contract.name !== options.contractName) return contract;
+  return {
+    ...contract,
+    entries: contract.entries.map((entry) =>
+      entry.kind === "function" && entry.name === options.entryName
+        ? {
+            ...entry,
+            inputTypeName: options.outputTypeName,
+          }
+        : entry,
+    ),
+  };
+}
+
+function resolveToIdentity(contract: ContractDefinition, override?: string): string {
+  if (typeof override === "string") return override;
+  if (isIdentity(contract.address)) return contract.address;
+  throw new Error(
+    `Missing contract identity for ${contract.name}. Pass input.toIdentity until registry contains identity60 addresses.`,
+  );
+}
+
+function isIdentity(value: string): boolean {
+  return /^[A-Za-z]{60}$/.test(value);
+}
+
+function toDefined<Key extends string, Value>(
+  key: Key,
+  value: Value | undefined,
+): { [K in Key]?: Value } {
+  if (value === undefined) return {};
+  return { [key]: value } as { [K in Key]?: Value };
+}

package/src/hooks/use-last-processed-tick.ts

@@ -0,0 +1,21 @@
+import type { LastProcessedTick } 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 UseLastProcessedTickOptions = Omit<
+  UseQueryOptions<LastProcessedTick, Error>,
+  "queryKey" | "queryFn"
+>;
+
+export function useLastProcessedTick(
+  options: UseLastProcessedTickOptions = {},
+): UseQueryResult<LastProcessedTick, Error> {
+  const sdk = useSdk();
+  return useQuery({
+    ...options,
+    queryKey: queryKeys.lastProcessedTick(),
+    queryFn: () => sdk.rpc.query.getLastProcessedTick(),
+  });
+}

package/src/hooks/use-send-and-confirm.ts

@@ -0,0 +1,19 @@
+import type { SendAndConfirmInput, SendTransferResult } from "@qubic.ts/sdk";
+import type { UseMutationOptions, UseMutationResult } from "@tanstack/react-query";
+import { useMutation } from "@tanstack/react-query";
+import { useSdk } from "../providers/sdk-provider.js";
+
+export type UseSendAndConfirmOptions = Omit<
+  UseMutationOptions<SendTransferResult, Error, SendAndConfirmInput>,
+  "mutationFn"
+>;
+
+export function useSendAndConfirm(
+  options: UseSendAndConfirmOptions = {},
+): UseMutationResult<SendTransferResult, Error, SendAndConfirmInput> {
+  const sdk = useSdk();
+  return useMutation({
+    ...options,
+    mutationFn: (input) => sdk.transfers.sendAndConfirm(input),
+  });
+}

package/src/hooks/use-send.ts

@@ -0,0 +1,21 @@
+import type { BuildSignedTransferInput, SendTransferResult } from "@qubic.ts/sdk";
+import type { UseMutationOptions, UseMutationResult } from "@tanstack/react-query";
+import { useMutation } from "@tanstack/react-query";
+import { useSdk } from "../providers/sdk-provider.js";
+
+export type UseSendOptions = Omit<
+  UseMutationOptions<SendTransferResult, Error, BuildSignedTransferInput>,
+  "mutationFn"
+>;
+
+export function useSend(options: UseSendOptions = {}): UseMutationResult<
+  SendTransferResult,
+  Error,
+  BuildSignedTransferInput
+> {
+  const sdk = useSdk();
+  return useMutation({
+    ...options,
+    mutationFn: (input) => sdk.transfers.send(input),
+  });
+}