@qubic.ts/react 0.1.0

package/fixtures/next-boundary/client-node-leak.tsx

@@ -0,0 +1,5 @@
+"use client";
+
+import { openNodeVault } from "@qubic.ts/react/node";
+
+export const nodeOnlyReference = openNodeVault;

package/fixtures/next-boundary/client-ok.tsx

@@ -0,0 +1,8 @@
+"use client";
+
+import { useTickInfo } from "@qubic.ts/react/browser";
+
+export function ClientOk() {
+  useTickInfo();
+  return null;
+}

package/fixtures/next-boundary/server-ok.ts

@@ -0,0 +1,5 @@
+import { openNodeVault } from "@qubic.ts/react/node";
+
+export async function serverAction(path: string, passphrase: string) {
+  return openNodeVault({ path, passphrase });
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@qubic.ts/react",
+  "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"
+  },
+  "dependencies": {
+    "@metamask/providers": "^22.1.1",
+    "@tanstack/react-query": "^5.90.19",
+    "@walletconnect/sign-client": "^2.22.4",
+    "@walletconnect/types": "^2.22.4",
+    "@qubic.ts/contracts": "^0.1.0",
+    "@qubic.ts/core": "^0.1.0",
+    "@qubic.ts/sdk": "^0.1.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.27",
+    "@types/react-dom": "^18.3.7",
+    "@types/react-test-renderer": "^18.3.1",
+    "react-test-renderer": "^18.3.1"
+  },
+  "scripts": {
+    "build": "echo \"qubic-ts-react build pending\"",
+    "typecheck": "bunx tsc -p tsconfig.typecheck.json --noEmit",
+    "verify:next": "bun ./scripts/verify-next-boundary.mjs",
+    "check": "bun run typecheck && bun run test && bun run verify:next",
+    "test": "bun test ./src/**/*.test.ts ./src/**/*.test.tsx"
+  }
+}

package/scripts/verify-next-boundary.mjs

@@ -0,0 +1,63 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+const fixtureDir = resolve(process.cwd(), "fixtures/next-boundary");
+const outRoot = mkdtempSync(join(tmpdir(), "qubic-ts-react-next-boundary-"));
+
+try {
+  await assertBuildSuccess("client-ok.tsx", "browser");
+  await assertBuildSuccess("server-ok.ts", "node");
+  await assertBuildFailure("client-node-leak.tsx", "browser");
+  console.log("Next boundary fixture passed.");
+} finally {
+  rmSync(outRoot, { recursive: true, force: true });
+}
+
+async function assertBuildSuccess(entryFile, target) {
+  let result;
+  try {
+    result = await Bun.build({
+      entrypoints: [resolve(fixtureDir, entryFile)],
+      outdir: resolve(outRoot, `${entryFile}.${target}`),
+      target,
+      format: "esm",
+      splitting: false,
+      sourcemap: "none",
+      minify: false,
+    });
+  } catch (error) {
+    throw new Error(`Expected build to succeed for ${entryFile} (${target})\n${String(error)}`);
+  }
+
+  if (!result.success) {
+    throw new Error(
+      [
+        `Expected build to succeed for ${entryFile} (${target})`,
+        ...result.logs.map((log) => log.message),
+      ].join("\n"),
+    );
+  }
+}
+
+async function assertBuildFailure(entryFile, target) {
+  try {
+    const result = await Bun.build({
+      entrypoints: [resolve(fixtureDir, entryFile)],
+      outdir: resolve(outRoot, `${entryFile}.${target}`),
+      target,
+      format: "esm",
+      splitting: false,
+      sourcemap: "none",
+      minify: false,
+    });
+
+    if (result.success) {
+      throw new Error(`Expected build to fail for ${entryFile} (${target})`);
+    }
+    return;
+  } catch {
+    // Build failed as expected.
+    return;
+  }
+}

package/src/browser.ts

@@ -0,0 +1,27 @@
+export * from "./index.js";
+export type {
+  OpenSeedVaultBrowserInput,
+  SeedVault,
+  VaultEntry,
+  VaultEntryEncrypted,
+  VaultExport,
+  VaultHeader,
+  VaultKdfParams,
+  VaultStore,
+  VaultSummary,
+} from "@qubic.ts/sdk/browser";
+export {
+  VaultEntryExistsError,
+  VaultEntryNotFoundError,
+  VaultError,
+  VaultInvalidPassphraseError,
+  VaultNotFoundError,
+} from "@qubic.ts/sdk/browser";
+export type { CreateBrowserVaultInput } from "./vault/browser.js";
+export {
+  createBrowserVault,
+  createLocalStorageVaultStore,
+  createMemoryVaultStore,
+  importBrowserVault,
+  openBrowserVault,
+} from "./vault/browser.js";

package/src/contract-types.ts

@@ -0,0 +1,309 @@
+import type { ContractDefinition, ContractsRegistry } from "@qubic.ts/contracts";
+import type { QueryRawResult, SeedSourceInput, SendTransactionResult } from "@qubic.ts/sdk";
+
+export type ContractCodecSchema = Readonly<{
+  functions?: Readonly<Record<string, Readonly<{ input: unknown; output: unknown }>>>;
+  procedures?: Readonly<Record<string, Readonly<{ input: unknown; output: unknown }>>>;
+}>;
+
+export type ContractRegistrySchema = Readonly<Record<string, ContractCodecSchema>>;
+
+type SchemaFunctions<S extends ContractCodecSchema> = NonNullable<S["functions"]>;
+type SchemaProcedures<S extends ContractCodecSchema> = NonNullable<S["procedures"]>;
+
+type ContractEntryLike = Readonly<{
+  kind: "function" | "procedure";
+  name: string;
+  inputTypeName?: string;
+  outputTypeName?: string;
+}>;
+
+type ContractIoFieldLike = Readonly<{
+  name: string;
+  type: string;
+}>;
+
+type ContractIoTypeLike =
+  | Readonly<{
+      kind: "struct";
+      name: string;
+      fields: readonly ContractIoFieldLike[];
+    }>
+  | Readonly<{
+      kind: "alias";
+      name: string;
+      target: string;
+    }>;
+
+type ContractDefinitionLike = Readonly<{
+  name: string;
+  address?: string;
+  entries: readonly ContractEntryLike[];
+  ioTypes?: readonly ContractIoTypeLike[];
+}>;
+
+type RegistryLike = Readonly<{
+  contracts: readonly ContractDefinitionLike[];
+}>;
+
+type TrimLeft<Value extends string> = Value extends ` ${infer Rest}` ? TrimLeft<Rest> : Value;
+type TrimRight<Value extends string> = Value extends `${infer Rest} ` ? TrimRight<Rest> : Value;
+type Trim<Value extends string> = TrimLeft<TrimRight<Value>>;
+type TailSegment<Value extends string> = Value extends `${string}::${infer Rest}`
+  ? TailSegment<Rest>
+  : Value;
+type DecrementMap = [0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+type Dec<Depth extends number> = Depth extends keyof DecrementMap ? DecrementMap[Depth] : 0;
+
+type PrimitiveTypeValue<TypeName extends string> = TypeName extends
+  | "uint8"
+  | "uint16"
+  | "uint32"
+  | "sint8"
+  | "sint16"
+  | "sint32"
+  | "bit"
+  | "char"
+  ? number
+  : TypeName extends "uint64" | "sint64"
+    ? bigint
+    : TypeName extends "bool"
+      ? boolean
+      : TypeName extends "id"
+        ? string
+        : TypeName extends "m256i"
+          ? Uint8Array
+          : never;
+
+type ExactIoType<Contract extends ContractDefinitionLike, TypeName extends string> = Extract<
+  NonNullable<Contract["ioTypes"]>[number],
+  { name: TypeName }
+>;
+
+type LookupIoType<Contract extends ContractDefinitionLike, TypeName extends string> = [
+  ExactIoType<Contract, TypeName>,
+] extends [never]
+  ? ExactIoType<Contract, TailSegment<TypeName>>
+  : ExactIoType<Contract, TypeName>;
+
+type StructValueFromFields<
+  Contract extends ContractDefinitionLike,
+  Fields extends readonly ContractIoFieldLike[],
+  Depth extends number,
+> = Fields extends readonly []
+  ? Record<string, never>
+  : {
+      [Field in Fields[number] as Field["name"]]: ResolveContractType<
+        Contract,
+        Field["type"],
+        Depth
+      >;
+    };
+
+type ResolveDeclaredContractType<
+  Contract extends ContractDefinitionLike,
+  TypeName extends string,
+  Depth extends number,
+> = LookupIoType<Contract, TypeName> extends infer Io
+  ? Io extends { kind: "alias"; target: infer Target extends string }
+    ? ResolveContractType<Contract, Target, Dec<Depth>>
+    : Io extends { kind: "struct"; fields: infer Fields extends readonly ContractIoFieldLike[] }
+      ? StructValueFromFields<Contract, Fields, Dec<Depth>>
+      : unknown
+  : unknown;
+
+type ResolveContractType<
+  Contract extends ContractDefinitionLike,
+  TypeName extends string,
+  Depth extends number = 6,
+> = Depth extends 0
+  ? unknown
+  : PrimitiveTypeValue<Trim<TypeName>> extends never
+    ? Trim<TypeName> extends `Array<${infer ElementType}, ${string}>`
+      ? ReadonlyArray<ResolveContractType<Contract, Trim<ElementType>, Dec<Depth>>>
+      : ResolveDeclaredContractType<Contract, Trim<TypeName>, Depth>
+    : PrimitiveTypeValue<Trim<TypeName>>;
+
+type EntryFunctionMap<
+  Entry extends ContractEntryLike,
+  Contract extends ContractDefinitionLike,
+> = Entry extends { kind: "function"; name: infer Name extends string }
+  ? Name extends string
+    ? Readonly<
+        Record<
+          Name,
+          Readonly<{
+            input: Entry extends { inputTypeName: infer InputTypeName extends string }
+              ? ResolveContractType<Contract, InputTypeName>
+              : unknown;
+            output: Entry extends { outputTypeName: infer OutputTypeName extends string }
+              ? ResolveContractType<Contract, OutputTypeName>
+              : unknown;
+          }>
+        >
+      >
+    : Readonly<Record<never, never>>
+  : Readonly<Record<never, never>>;
+
+type EntryProcedureMap<
+  Entry extends ContractEntryLike,
+  Contract extends ContractDefinitionLike,
+> = Entry extends { kind: "procedure"; name: infer Name extends string }
+  ? Name extends string
+    ? Readonly<
+        Record<
+          Name,
+          Readonly<{
+            input: Entry extends { inputTypeName: infer InputTypeName extends string }
+              ? ResolveContractType<Contract, InputTypeName>
+              : unknown;
+            output: Entry extends { outputTypeName: infer OutputTypeName extends string }
+              ? ResolveContractType<Contract, OutputTypeName>
+              : unknown;
+          }>
+        >
+      >
+    : Readonly<Record<never, never>>
+  : Readonly<Record<never, never>>;
+
+type UnionToIntersection<Value> = (Value extends unknown ? (arg: Value) => void : never) extends (
+  arg: infer Intersection,
+) => void
+  ? Intersection
+  : never;
+
+type Merge<Value> = { [Key in keyof Value]: Value[Key] };
+
+type ContractSchemaFromDefinition<Definition extends ContractDefinitionLike> = Readonly<{
+  __meta: Readonly<{
+    address: Definition extends { address: infer Address extends string } ? Address : string;
+  }>;
+  functions: Merge<
+    UnionToIntersection<EntryFunctionMap<Definition["entries"][number], Definition>>
+  >;
+  procedures: Merge<
+    UnionToIntersection<EntryProcedureMap<Definition["entries"][number], Definition>>
+  >;
+}>;
+
+export type ContractRegistryToSchema<Registry extends RegistryLike> = Readonly<{
+  [Definition in Registry["contracts"][number] as Definition["name"]]: ContractSchemaFromDefinition<Definition>;
+}>;
+
+export type ContractFunctionName<S extends ContractCodecSchema> = keyof SchemaFunctions<S> & string;
+export type ContractProcedureName<S extends ContractCodecSchema> = keyof SchemaProcedures<S> &
+  string;
+
+export type ContractFunctionInput<
+  S extends ContractCodecSchema,
+  Name extends string,
+> = Name extends keyof SchemaFunctions<S>
+  ? SchemaFunctions<S>[Name] extends { input: infer Input }
+    ? Input
+    : unknown
+  : unknown;
+
+export type ContractFunctionOutput<
+  S extends ContractCodecSchema,
+  Name extends string,
+> = Name extends keyof SchemaFunctions<S>
+  ? SchemaFunctions<S>[Name] extends { output: infer Output }
+    ? Output
+    : unknown
+  : unknown;
+
+export type ContractProcedureInput<
+  S extends ContractCodecSchema,
+  Name extends string,
+> = Name extends keyof SchemaProcedures<S>
+  ? SchemaProcedures<S>[Name] extends { input: infer Input }
+    ? Input
+    : unknown
+  : unknown;
+
+export type ContractProcedureOutput<
+  S extends ContractCodecSchema,
+  Name extends string,
+> = Name extends keyof SchemaProcedures<S>
+  ? SchemaProcedures<S>[Name] extends { output: infer Output }
+    ? Output
+    : unknown
+  : unknown;
+
+type StringToTuple<
+  Value extends string,
+  Accumulator extends readonly unknown[] = readonly [],
+> = Value extends `${infer _}${infer Rest}`
+  ? StringToTuple<Rest, readonly [unknown, ...Accumulator]>
+  : Accumulator;
+
+type IsStringLiteral<Value extends string> = string extends Value ? false : true;
+
+type IsLength60<Value extends string> =
+  IsStringLiteral<Value> extends true
+    ? StringToTuple<Value>["length"] extends 60
+      ? true
+      : false
+    : false;
+
+type ContractAddress<Schema extends ContractCodecSchema> = Schema extends {
+  __meta: { address: infer Address extends string };
+}
+  ? Address
+  : string;
+
+export type ContractRequiresExplicitToIdentity<Schema extends ContractCodecSchema> =
+  IsLength60<ContractAddress<Schema>> extends true ? false : true;
+
+export type ContractRegistryInput = ContractsRegistry | readonly ContractDefinition[];
+
+export type ContractQueryInput<Input = unknown> = Readonly<{
+  inputBytes?: Uint8Array;
+  inputValue?: Input;
+  expectedOutputSize?: number;
+  retries?: number;
+  retryDelayMs?: number;
+  signal?: AbortSignal;
+  allowSequentialLayout?: boolean;
+  decodeOutput?: boolean;
+}>;
+
+export type ContractQueryResult<Output = unknown> = QueryRawResult &
+  Readonly<{
+    decoded?: Output;
+  }>;
+
+export type ContractMutationResult<Output = unknown> = SendTransactionResult &
+  Readonly<{
+    responseBytes: Uint8Array;
+    responseBase64: string;
+    decoded?: Output;
+  }>;
+
+export type ContractProcedureTxInput<
+  Input = unknown,
+  Output = unknown,
+  RequiresToIdentity extends boolean = false,
+> = SeedSourceInput &
+  Readonly<{
+    name: string;
+    amount?: bigint;
+    targetTick?: bigint | number;
+    inputBytes?: Uint8Array;
+    inputValue?: Input;
+    allowSequentialLayout?: boolean;
+    decodeResponse?: (result: SendTransactionResult) => Output;
+  }> &
+  (RequiresToIdentity extends true
+    ? Readonly<{ toIdentity: string }>
+    : Readonly<{ toIdentity?: string }>);
+
+export type ContractHandleLike = Readonly<{
+  query<Input = unknown, Output = unknown>(
+    name: string,
+    input: ContractQueryInput<Input>,
+  ): Promise<ContractQueryResult<Output>>;
+  sendProcedure<Input = unknown, Output = unknown>(
+    input: ContractProcedureTxInput<Input, Output>,
+  ): Promise<ContractMutationResult<Output>>;
+}>;

package/src/contracts-types.typecheck.ts

@@ -0,0 +1,85 @@
+import type {
+  ContractCodecSchema,
+  ContractFunctionInput,
+  ContractFunctionOutput,
+  ContractRegistrySchema,
+} from "./contract-types.js";
+import { createSdkProvider } from "./providers/sdk-provider.js";
+
+type DemoSchema = Readonly<{
+  QUTIL: Readonly<{
+    functions: Readonly<{
+      GetFees: Readonly<{
+        input: Record<string, never>;
+        output: bigint;
+      }>;
+      GetPollInfo: Readonly<{
+        input: Readonly<{ poll_id: bigint }>;
+        output: Readonly<{ title: string }>;
+      }>;
+    }>;
+    procedures: Readonly<Record<never, never>>;
+  }>;
+  QX: Readonly<{
+    functions: Readonly<Record<never, never>>;
+    procedures: Readonly<{
+      IssueAsset: Readonly<{
+        input: Readonly<{
+          assetName: bigint;
+          numberOfShares: bigint;
+          unitOfMeasurement: bigint;
+          numberOfDecimalPlaces: number;
+        }>;
+        output: Readonly<{ txHash: string }>;
+      }>;
+    }>;
+  }>;
+}>;
+
+type _SchemaSatisfiesContract = DemoSchema extends ContractRegistrySchema ? true : false;
+const _schemaSatisfiesContract: _SchemaSatisfiesContract = true;
+
+type GetPollInfoInput = ContractFunctionInput<DemoSchema["QUTIL"], "GetPollInfo">;
+type GetPollInfoOutput = ContractFunctionOutput<DemoSchema["QUTIL"], "GetPollInfo">;
+
+const _validGetPollInfoInput: GetPollInfoInput = { poll_id: 1n };
+const _validGetPollInfoOutput: GetPollInfoOutput = { title: "ok" };
+
+// @ts-expect-error poll_id expects bigint
+const _invalidGetPollInfoInputType: GetPollInfoInput = { poll_id: 1 };
+
+const _provider = createSdkProvider<DemoSchema>();
+const _useContractQuery = _provider.useContractQuery;
+const _useContractMutation = _provider.useContractMutation;
+
+_useContractQuery("QUTIL", "GetFees", {});
+_useContractQuery("QUTIL", "GetPollInfo", { inputValue: { poll_id: 1n } });
+
+// @ts-expect-error unknown function for QUTIL
+_useContractQuery("QUTIL", "NotARealFunction", { inputValue: {} });
+
+_useContractQuery("QUTIL", "GetPollInfo", {
+  // @ts-expect-error wrong input shape for GetPollInfo
+  inputValue: { pollId: 1n },
+});
+
+const _qxMutation = _useContractMutation("QX");
+
+_qxMutation.mutate({
+  name: "IssueAsset",
+  fromSeed: "...",
+  toIdentity: "YOUR_CONTRACT_IDENTITY60",
+  inputValue: {
+    assetName: 0n,
+    numberOfShares: 1n,
+    unitOfMeasurement: 0n,
+    numberOfDecimalPlaces: 0,
+  },
+});
+
+_useContractMutation("QUTIL").mutate({
+  // @ts-expect-error QUTIL does not have IssueAsset
+  name: "IssueAsset",
+  fromSeed: "...",
+  toIdentity: "YOUR_CONTRACT_IDENTITY60",
+});