@vlayer/sdk 0.1.0-nightly-20250127-96fc5df → 0.1.0-nightly-20250128-0a32cfc

package/src/api/lib/client.ts

@@ -0,0 +1,191 @@
+import { type VlayerClient, type BrandedHash } from "./types/vlayer";
+import { type WebProofProvider } from "./types/webProofProvider";
+import { prove, waitForProof } from "../prover";
+import { createExtensionWebProofProvider } from "../webProof";
+import {
+  type Abi,
+  type AbiStateMutability,
+  type ContractFunctionArgs,
+  type ContractFunctionName,
+  type ContractFunctionReturnType,
+  decodeFunctionResult,
+} from "viem";
+import {
+  ExtensionMessageType,
+  ZkProvingStatus,
+  type PresentationJSON,
+} from "../../web-proof-commons";
+import { type ContractFunctionArgsWithout } from "./types/viem";
+import { type ProveArgs } from "./types/vlayer";
+
+function dropEmptyProofFromArgs(args: unknown) {
+  if (Array.isArray(args)) {
+    return args.slice(1) as unknown[];
+  }
+  return [];
+}
+
+export const createVlayerClient = (
+  {
+    url = "http://127.0.0.1:3000",
+    webProofProvider = createExtensionWebProofProvider(),
+  }: {
+    url?: string;
+    webProofProvider?: WebProofProvider;
+  } = {
+    url: "http://127.0.0.1:3000",
+    webProofProvider: createExtensionWebProofProvider(),
+  },
+): VlayerClient => {
+  const resultHashMap = new Map<string, [Abi, string]>();
+
+  return {
+    prove: async <T extends Abi, F extends ContractFunctionName<T>>({
+      address,
+      proverAbi,
+      functionName,
+      chainId,
+      gasLimit,
+      token,
+      args,
+    }: ProveArgs<T, F>) => {
+      webProofProvider.notifyZkProvingStatus(ZkProvingStatus.Proving);
+
+      const hash = await prove(
+        address,
+        proverAbi,
+        functionName,
+        args,
+        chainId,
+        url,
+        gasLimit,
+        token,
+      ).catch((e) => {
+        webProofProvider.notifyZkProvingStatus(ZkProvingStatus.Error);
+        throw e;
+      });
+
+      resultHashMap.set(hash.hash, [proverAbi, functionName]);
+      return hash;
+    },
+
+    waitForProvingResult: async <
+      T extends Abi,
+      F extends ContractFunctionName<T>,
+    >({
+      hash,
+      numberOfRetries = 240,
+      sleepDuration = 1000,
+    }: {
+      hash: BrandedHash<T, F>;
+      numberOfRetries?: number;
+      sleepDuration?: number;
+    }): Promise<ContractFunctionReturnType<T, AbiStateMutability, F>> => {
+      try {
+        const { data } = await waitForProof(
+          hash,
+          url,
+          numberOfRetries,
+          sleepDuration,
+        );
+        const savedProvingData = resultHashMap.get(hash.hash);
+        if (!savedProvingData) {
+          throw new Error("No result found for hash " + hash.hash);
+        }
+        const [proverAbi, functionName] = savedProvingData;
+
+        const result = dropEmptyProofFromArgs(
+          decodeFunctionResult({
+            abi: proverAbi,
+            data: data.evm_call_result,
+            functionName,
+          }),
+        );
+
+        webProofProvider.notifyZkProvingStatus(ZkProvingStatus.Done);
+
+        return [data.proof, ...result] as ContractFunctionReturnType<
+          T,
+          AbiStateMutability,
+          F
+        >;
+      } catch (e) {
+        webProofProvider.notifyZkProvingStatus(ZkProvingStatus.Error);
+        throw e;
+      }
+    },
+
+    proveWeb: async function ({
+      address,
+      proverAbi,
+      functionName,
+      chainId,
+      gasLimit,
+      token,
+      args,
+    }) {
+      const webProofPlaceholder = args[0];
+      const commitmentArgs = args.slice(1) as ContractFunctionArgsWithout<
+        typeof proverAbi,
+        typeof functionName,
+        { name: "webProof" }
+      >;
+
+      const webProofPromise: Promise<{
+        presentationJSON: PresentationJSON;
+        decodedTranscript: {
+          sent: string;
+          recv: string;
+        };
+      }> = new Promise((resolve, reject) => {
+        webProofProvider.addEventListeners(
+          ExtensionMessageType.ProofDone,
+          ({ payload: { presentationJSON, decodedTranscript } }) => {
+            resolve({ presentationJSON, decodedTranscript });
+          },
+        );
+
+        webProofProvider.addEventListeners(
+          ExtensionMessageType.ProofError,
+          ({ payload: { error } }) => {
+            reject(new Error(error));
+          },
+        );
+      });
+
+      webProofProvider.requestWebProof({
+        proverCallCommitment: {
+          address,
+          proverAbi,
+          functionName,
+          commitmentArgs,
+          chainId,
+        },
+        logoUrl: webProofPlaceholder.logoUrl,
+        steps: webProofPlaceholder.steps,
+      });
+
+      const webProof = await webProofPromise;
+
+      const hash = await this.prove({
+        address,
+        functionName,
+        chainId,
+        gasLimit,
+        proverAbi,
+        token,
+        args: [
+          {
+            webProofJson: JSON.stringify(webProof.presentationJSON),
+          },
+          ...commitmentArgs,
+        ] as ContractFunctionArgs<
+          typeof proverAbi,
+          AbiStateMutability,
+          typeof functionName
+        >,
+      });
+      return hash;
+    },
+  };
+};

package/src/api/lib/errors.ts

@@ -0,0 +1,19 @@
+export class VersionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "VersionError";
+  }
+}
+
+export function parseVCallResponseError({
+  message,
+}: {
+  message: string | undefined;
+}): Error {
+  if (message?.startsWith("Unsupported CallGuestID")) {
+    return new VersionError(`${message}
+    vlayer uses the daily release cycle, and SDK version must match the proving server version.
+    Please run "vlayer update" to update the SDK to the latest version.`);
+  }
+  return new Error(`Error response: ${message ?? "unknown error"}`);
+}

package/src/api/lib/types/ethereum.ts

@@ -0,0 +1,45 @@
+import { type Abi, type Address, type Hex } from "viem";
+import { type Branded } from "../../../web-proof-commons";
+
+export type Bytecode = {
+  object: Hex;
+};
+
+export type ContractSpec = {
+  abi: Abi;
+  bytecode: Bytecode;
+};
+
+export type ContractArg =
+  | number
+  | string
+  | boolean
+  | bigint
+  | number[]
+  | string[]
+  | boolean[]
+  | bigint[]
+  | Address[]
+  | (string | bigint)[]
+  | (string | bigint)[][];
+
+export type EthereumAddress = Branded<Hex, "EthereumAddress">;
+export type EthereumTxHash = Branded<Hex, "EthereumTxHash">;
+
+export function assertEthereumAddress(
+  hash: string,
+): asserts hash is EthereumAddress {
+  const regex = /^(0x)?[0-9a-fA-F]{40}$/;
+  if (!regex.test(hash)) {
+    throw new Error(`Invalid ethereum account ${hash}`);
+  }
+}
+
+export function assertEthereumTxHash(
+  hash: string,
+): asserts hash is EthereumTxHash {
+  const regex = /^(0x)?[0-9a-fA-F]{64}$/;
+  if (!regex.test(hash)) {
+    throw new Error(`Invalid ethereum tx hash ${hash}`);
+  }
+}

package/src/api/lib/types/index.ts

@@ -0,0 +1,3 @@
+export * from "./ethereum";
+export * from "./vlayer";
+export * from "./webProofProvider";

package/src/api/lib/types/viem.ts

@@ -0,0 +1,26 @@
+import { type Abi, type ContractFunctionName } from "viem";
+import {
+  type AbiParametersToPrimitiveTypes,
+  type ExtractAbiFunction,
+} from "abitype";
+
+type Without<T extends readonly unknown[], P> = T extends readonly [
+  infer F,
+  ...infer R,
+]
+  ? F extends P
+    ? Without<R, P>
+    : readonly [F, ...Without<R, P>]
+  : [];
+
+export type ContractFunctionArgsWithout<
+  abi extends Abi,
+  functionName extends ContractFunctionName<abi>,
+  without,
+> = AbiParametersToPrimitiveTypes<
+  Without<
+    ExtractAbiFunction<abi extends Abi ? abi : Abi, functionName>["inputs"],
+    without
+  >,
+  "inputs"
+>;

package/src/api/lib/types/vlayer.ts

@@ -0,0 +1,156 @@
+import { type Branded } from "../../../web-proof-commons/utils";
+import {
+  type Abi,
+  type AbiStateMutability,
+  type Address,
+  type ContractFunctionArgs,
+  type ContractFunctionName,
+  type ContractFunctionReturnType,
+  type Hex,
+} from "viem";
+import { type WebProofRequest } from "./webProofProvider";
+import { type ContractFunctionArgsWithout } from "./viem";
+import { z } from "zod";
+
+type Calldata = string;
+
+export type CallParams = {
+  to: Address;
+  data: Calldata;
+  gas_limit: number;
+};
+
+export type CallContext = {
+  chain_id: number;
+};
+
+export type BrandedHash<T, F> = Branded<{ hash: string }, [T, F]>;
+
+export type Proof = {
+  seal: {
+    verifierSelector: Hex;
+    seal: readonly [Hex, Hex, Hex, Hex, Hex, Hex, Hex, Hex];
+    mode: number;
+  };
+  callGuestId: Hex;
+  length: bigint;
+  callAssumptions: {
+    proverContractAddress: Address;
+    functionSelector: Hex;
+    settleBlockHash: Hex;
+    settleBlockNumber: bigint;
+  };
+};
+
+export type VCallResult = Hex;
+
+export interface VCallResponse {
+  jsonrpc: string;
+  result: VCallResult;
+  id: number;
+}
+
+export type VGetProofReceiptParams = {
+  hash: Hex;
+};
+
+export enum ProofState {
+  Queued = "queued",
+  ChainProof = "chain_proof",
+  Preflight = "preflight",
+  Proving = "proving",
+  Done = "done",
+}
+
+export type ProofData = {
+  evm_call_result: Hex;
+  proof: Proof;
+};
+
+export type Metrics = {
+  gas: number;
+  cycles: number;
+  times: {
+    preflight: number;
+    proving: number;
+  };
+};
+
+export type ProofDataWithMetrics = {
+  data: ProofData;
+  metrics: Metrics;
+};
+
+export type ProveArgs<T extends Abi, F extends ContractFunctionName<T>> = {
+  address: Hex;
+  proverAbi: T;
+  functionName: F;
+  chainId?: number;
+  gasLimit?: number;
+  token?: string;
+  args: ContractFunctionArgs<T, AbiStateMutability, F>;
+};
+
+export type VlayerClient = {
+  prove: <T extends Abi, F extends ContractFunctionName<T>>(
+    args: ProveArgs<T, F>,
+  ) => Promise<BrandedHash<T, F>>;
+
+  waitForProvingResult: <
+    T extends Abi,
+    F extends ContractFunctionName<T>,
+  >(args: {
+    hash: BrandedHash<T, F>;
+    numberOfRetries?: number;
+    sleepDuration?: number;
+  }) => Promise<ContractFunctionReturnType<T, AbiStateMutability, F>>;
+
+  proveWeb: <T extends Abi, F extends ContractFunctionName<T>>(args: {
+    address: Hex;
+    proverAbi: T;
+    functionName: F;
+    chainId: number;
+    gasLimit?: number;
+    token?: string;
+    args: [
+      WebProofRequest,
+      ...ContractFunctionArgsWithout<T, F, { name: "webProof" }>,
+    ];
+  }) => Promise<BrandedHash<T, F>>;
+};
+
+export const proofReceiptSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal(0),
+    error: z.string(),
+    data: z.undefined(),
+    metrics: z.custom<Metrics>(),
+    state: z.enum([
+      ProofState.ChainProof,
+      ProofState.Preflight,
+      ProofState.Proving,
+    ]),
+  }),
+  z.object({
+    status: z.literal(1),
+    error: z.undefined(),
+    state: z.enum([
+      ProofState.Done,
+      ProofState.ChainProof,
+      ProofState.Preflight,
+      ProofState.Proving,
+      ProofState.Queued,
+    ]),
+    data: z.custom<ProofData>(),
+    metrics: z.custom<Metrics>(),
+  }),
+]);
+
+export const vGetProofReceiptSchema = z.object({
+  jsonrpc: z.string(),
+  result: proofReceiptSchema,
+  id: z.number(),
+});
+
+export type ProofReceipt = z.infer<typeof proofReceiptSchema>;
+export type VGetProofReceiptResponse = z.infer<typeof vGetProofReceiptSchema>;

package/src/api/lib/types/webProofProvider.ts

@@ -0,0 +1,68 @@
+import { type Hex, type Abi, type ContractFunctionName } from "viem";
+import type { ContractFunctionArgsWithout } from "./viem";
+import {
+  type Branded,
+  type ExtensionMessageType,
+  type ExtensionMessage,
+  type PresentationJSON,
+  type WebProofStep,
+  type ZkProvingStatus,
+} from "../../../web-proof-commons";
+
+export type WebProofRequestInput = {
+  logoUrl: string;
+  steps: WebProofStep[];
+};
+
+export type WebProofRequest = Branded<
+  WebProofRequestInput & {
+    isWebProof: true;
+  },
+  "webProof"
+>;
+
+export type ProverCallCommitment<
+  T extends Abi,
+  F extends ContractFunctionName<T>,
+> = {
+  address: Hex;
+  proverAbi: T;
+  functionName: F;
+  commitmentArgs: ContractFunctionArgsWithout<T, F, { name: "webProof" }>;
+  chainId: number;
+};
+
+export type GetWebProofArgs<
+  T extends Abi,
+  F extends ContractFunctionName<T>,
+> = {
+  proverCallCommitment: ProverCallCommitment<T, F>;
+} & WebProofRequestInput;
+
+export type WebProofProvider = {
+  getWebProof: <T extends Abi, F extends ContractFunctionName<T>>(
+    args: GetWebProofArgs<T, F>,
+  ) => Promise<{
+    presentationJSON: PresentationJSON;
+    decodedTranscript: {
+      sent: string;
+      recv: string;
+    };
+  }>;
+
+  requestWebProof: <T extends Abi, F extends ContractFunctionName<T>>(
+    args: GetWebProofArgs<T, F>,
+  ) => void;
+
+  notifyZkProvingStatus: (status: ZkProvingStatus) => void;
+
+  addEventListeners: <T extends ExtensionMessageType>(
+    messageType: T,
+    listener: (args: Extract<ExtensionMessage, { type: T }>) => void,
+  ) => void;
+};
+
+export type WebProofProviderSetup = {
+  notaryUrl?: string;
+  wsProxyUrl?: string;
+};

package/src/api/prover.ts

@@ -0,0 +1,120 @@
+import {
+  type Abi,
+  type AbiStateMutability,
+  type Address,
+  type ContractFunctionArgs,
+  type ContractFunctionName,
+  encodeFunctionData,
+  type Hex,
+} from "viem";
+import {
+  type CallContext,
+  type CallParams,
+  type BrandedHash,
+  type ProofDataWithMetrics,
+  type ProofReceipt,
+  ProofState,
+  type VGetProofReceiptParams,
+  type VGetProofReceiptResponse,
+} from "./lib/types/vlayer";
+import { match } from "ts-pattern";
+import { v_call } from "./v_call";
+import { v_getProofReceipt } from "./v_getProofReceipt";
+import { foundry } from "viem/chains";
+import { v_versions } from "./v_versions";
+import { checkVersionCompatibility } from "./utils/versions";
+import meta from "../../package.json" with { type: "json" };
+const sdkVersion = meta.version;
+
+export interface ProveOptions {
+  preverifyVersions?: boolean;
+}
+
+async function preverifyVersions(url: string, shouldPreverify: boolean) {
+  if (shouldPreverify) {
+    const proverVersions = await v_versions(url);
+    checkVersionCompatibility(proverVersions.result.api_version, sdkVersion);
+  }
+}
+
+export async function prove<T extends Abi, F extends ContractFunctionName<T>>(
+  prover: Address,
+  abi: T,
+  functionName: F,
+  args: ContractFunctionArgs<T, AbiStateMutability, F>,
+  chainId: number = foundry.id,
+  url: string = "http://127.0.0.1:3000",
+  gasLimit: number = 10_000_000,
+  token?: string,
+  options: ProveOptions = { preverifyVersions: false },
+): Promise<BrandedHash<T, F>> {
+  await preverifyVersions(url, !!options.preverifyVersions);
+  const calldata = encodeFunctionData({
+    abi: abi as Abi,
+    functionName: functionName as string,
+    args: args as readonly unknown[],
+  });
+  const call: CallParams = { to: prover, data: calldata, gas_limit: gasLimit };
+  const context: CallContext = {
+    chain_id: chainId,
+  };
+  const resp = await v_call(call, context, url, token);
+  return { hash: resp.result } as BrandedHash<T, F>;
+}
+
+export async function getProofReceipt<
+  T extends Abi,
+  F extends ContractFunctionName<T>,
+>(
+  hash: BrandedHash<T, F>,
+  url: string = "http://127.0.0.1:3000",
+): Promise<ProofReceipt> {
+  const params: VGetProofReceiptParams = {
+    hash: hash.hash as Hex,
+  };
+  const resp = await v_getProofReceipt(params, url);
+  handleErrors(resp);
+  return resp.result;
+}
+
+const handleErrors = (resp: VGetProofReceiptResponse) => {
+  const { status, state, error } = resp.result;
+  if (status === 0) {
+    match(state)
+      .with(ProofState.ChainProof, () => {
+        throw new Error("Waiting for chain proof failed with error: " + error);
+      })
+      .with(ProofState.Preflight, () => {
+        throw new Error("Preflight failed with error: " + error);
+      })
+      .with(ProofState.Proving, () => {
+        throw new Error("Proving failed with error: " + error);
+      })
+      .exhaustive();
+  }
+};
+
+export async function waitForProof<
+  T extends Abi,
+  F extends ContractFunctionName<T>,
+>(
+  hash: BrandedHash<T, F>,
+  url: string,
+  numberOfRetries: number = 240,
+  sleepDuration: number = 1000,
+): Promise<ProofDataWithMetrics> {
+  for (let retry = 0; retry < numberOfRetries; retry++) {
+    const { state, data, metrics } = await getProofReceipt(hash, url);
+    if (state === ProofState.Done) {
+      return { data, metrics };
+    }
+    await sleep(sleepDuration);
+  }
+  throw new Error(
+    `Timed out waiting for ZK proof generation after ${numberOfRetries * sleepDuration}ms. Consider increasing numberOfRetries.`,
+  );
+}
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/api/utils/prefixAllButNthSubstring.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "vitest";
+import { prefixAllButNthSubstring } from "./prefixAllButNthSubstring";
+
+describe("prefixAllButNthSubstring", () => {
+  test("adds 'X-' prefix to all matches except n-th (indexed from 0)", () => {
+    const str = "abc 123 abc 456 abc 789";
+    expect(prefixAllButNthSubstring(str, /abc/gi, 3, 0)).toBe(
+      "abc 123 X-abc 456 X-abc 789",
+    );
+    expect(prefixAllButNthSubstring(str, /abc/gi, 3, 1)).toBe(
+      "X-abc 123 abc 456 X-abc 789",
+    );
+    expect(prefixAllButNthSubstring(str, /abc/gi, 3, 2)).toBe(
+      "X-abc 123 X-abc 456 abc 789",
+    );
+  });
+
+  test("does not add prefix to substrings past total substring count", () => {
+    const str = "abc 123 abc 456 abc 789 abc abc";
+    expect(prefixAllButNthSubstring(str, /abc/gi, 3, 1)).toBe(
+      "X-abc 123 abc 456 X-abc 789 abc abc",
+    );
+  });
+});

package/src/api/utils/prefixAllButNthSubstring.ts

@@ -0,0 +1,13 @@
+export function prefixAllButNthSubstring(
+  str: string,
+  pattern: RegExp,
+  substringsCount: number,
+  skippedIndex: number,
+) {
+  let occurrence = 0;
+  return str.replace(pattern, (match) => {
+    return occurrence++ === skippedIndex || occurrence > substringsCount
+      ? match
+      : `X-${match}`;
+  });
+}