@vlayer/sdk 0.1.0-nightly-20250127-5ee6ca8 → 0.1.0-nightly-20250128-0a32cfc

package/src/api/lib/client.test.ts

@@ -0,0 +1,261 @@
+import {
+  describe,
+  expect,
+  it,
+  vi,
+  beforeEach,
+  type MockInstance,
+  afterEach,
+} from "vitest";
+
+import { createExtensionWebProofProvider } from "../webProof";
+import { createVlayerClient } from "./client";
+import { type BrandedHash, type VlayerClient } from "types/vlayer";
+import { ZkProvingStatus } from "../../web-proof-commons";
+import createFetchMock from "vitest-fetch-mock";
+
+declare const global: {
+  chrome: object;
+};
+
+const fetchMocker = createFetchMock(vi);
+
+beforeEach(() => {
+  fetchMocker.enableMocks();
+  global.chrome = {
+    runtime: {
+      sendMessage: vi.fn(),
+      connect: vi.fn().mockImplementation(() => {
+        return {
+          onMessage: {
+            addListener: vi.fn(),
+          },
+          postMessage: vi.fn(),
+        };
+      }),
+    },
+  };
+});
+
+afterEach(() => {
+  fetchMocker.disableMocks();
+});
+
+function generateRandomHash() {
+  let hash = "0x";
+  for (let i = 0; i < 40; ++i) {
+    hash += Math.floor(Math.random() * 16).toString(16);
+  }
+  return hash;
+}
+
+describe("Success zk-proving", () => {
+  let hashStr: string;
+  let zkProvingSpy: MockInstance<(status: ZkProvingStatus) => void>;
+  let vlayer: VlayerClient;
+
+  beforeEach(() => {
+    hashStr = generateRandomHash();
+    const webProofProvider = createExtensionWebProofProvider();
+    zkProvingSpy = vi.spyOn(webProofProvider, "notifyZkProvingStatus");
+    vlayer = createVlayerClient({ webProofProvider });
+  });
+  it("should send message to extension that zkproving started", async () => {
+    fetchMocker.mockResponseOnce(() => {
+      return {
+        body: JSON.stringify({
+          result: hashStr,
+        }),
+      };
+    });
+
+    const result = await vlayer.prove({
+      address: `0x${"a".repeat(40)}`,
+      functionName: "main",
+      proverAbi: [],
+      args: [],
+      chainId: 42,
+    });
+
+    expect(result.hash).toBe(hashStr);
+    expect(zkProvingSpy).toBeCalledTimes(1);
+    expect(zkProvingSpy).toHaveBeenNthCalledWith(1, ZkProvingStatus.Proving);
+  });
+  it("should send message to extension that zkproving is done", async () => {
+    fetchMocker.mockResponseOnce(() => {
+      return {
+        body: JSON.stringify({
+          result: hashStr,
+        }),
+      };
+    });
+
+    await vlayer.prove({
+      address: `0x${"a".repeat(40)}`,
+      functionName: "main",
+      proverAbi: [],
+      args: [],
+      chainId: 42,
+    });
+
+    fetchMocker.mockResponseOnce(() => {
+      return {
+        body: JSON.stringify({
+          result: {
+            state: "done",
+            status: 1,
+            metrics: {},
+            data: {},
+          },
+          jsonrpc: "2.0",
+          id: 1,
+        }),
+      };
+    });
+
+    const hash = { hash: hashStr } as BrandedHash<[], string>;
+    await vlayer.waitForProvingResult({ hash });
+
+    expect(zkProvingSpy).toBeCalledTimes(2);
+    expect(zkProvingSpy).toHaveBeenNthCalledWith(1, ZkProvingStatus.Proving);
+    expect(zkProvingSpy).toHaveBeenNthCalledWith(2, ZkProvingStatus.Done);
+  });
+  it("should notify that zk-proving failed", async () => {
+    fetchMocker.mockResponseOnce(() => {
+      throw new Error("test");
+    });
+
+    const hash = { hash: hashStr } as BrandedHash<[], string>;
+    try {
+      await vlayer.waitForProvingResult({ hash });
+    } catch (e) {
+      console.log("Error waiting for proving result", e);
+    }
+
+    expect(zkProvingSpy).toBeCalledTimes(1);
+    expect(zkProvingSpy).toHaveBeenNthCalledWith(1, ZkProvingStatus.Error);
+  });
+  it("should pass token if present", async () => {
+    const userToken = "deadbeef";
+
+    fetchMocker.mockResponseOnce((req) => {
+      const token = (req.headers.get("authorization") || "")
+        .split("Bearer ")
+        .at(1);
+      if (token !== undefined && token === userToken) {
+        return {
+          body: JSON.stringify({
+            result: hashStr,
+          }),
+        };
+      }
+      return {
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          error: {
+            code: -32603,
+            message:
+              "Gas meter error: RPC error: HTTP error: HTTP status client error (401 Unauthorized) for url (http://localhost:3000)",
+          },
+        }),
+      };
+    });
+
+    const result = await vlayer.prove({
+      address: `0x${"a".repeat(40)}`,
+      functionName: "main",
+      proverAbi: [],
+      args: [],
+      chainId: 42,
+      token: userToken,
+    });
+    expect(result.hash).toBe(hashStr);
+    expect(zkProvingSpy).toBeCalledTimes(1);
+    expect(zkProvingSpy).toHaveBeenNthCalledWith(1, ZkProvingStatus.Proving);
+  });
+});
+
+describe("Failed zk-proving", () => {
+  let zkProvingSpy: MockInstance<(status: ZkProvingStatus) => void>;
+  let vlayer: VlayerClient;
+  let hashStr: string;
+
+  beforeEach(() => {
+    hashStr = generateRandomHash();
+    const webProofProvider = createExtensionWebProofProvider();
+    zkProvingSpy = vi.spyOn(webProofProvider, "notifyZkProvingStatus");
+    vlayer = createVlayerClient({ webProofProvider });
+  });
+  it("should send message to extension that zkproving started and then that failed when server error 500", async () => {
+    fetchMocker.mockResponseOnce((req) => {
+      if (req.url === "http://127.0.0.1:3000/") {
+        return {
+          status: 500,
+        };
+      }
+      return {};
+    });
+
+    try {
+      const hash = await vlayer.prove({
+        address: `0x${"a".repeat(40)}`,
+        functionName: "main",
+        proverAbi: [],
+        args: [],
+        chainId: 42,
+      });
+      await vlayer.waitForProvingResult({ hash });
+    } catch (e) {
+      console.log("Error waiting for proving result", e);
+    }
+
+    expect(zkProvingSpy).toBeCalledTimes(2);
+    expect(zkProvingSpy).toHaveBeenNthCalledWith(1, ZkProvingStatus.Proving);
+    expect(zkProvingSpy).toHaveBeenNthCalledWith(2, ZkProvingStatus.Error);
+  });
+  it("should send message to extension that zkproving started and then that failed when computation failed at any stage", async () => {
+    fetchMocker.mockResponseOnce(() => {
+      return {
+        body: JSON.stringify({
+          result: hashStr,
+        }),
+      };
+    });
+
+    const hash = await vlayer.prove({
+      address: `0x${"a".repeat(40)}`,
+      functionName: "main",
+      proverAbi: [],
+      args: [],
+      chainId: 42,
+    });
+
+    fetchMocker.mockResponseOnce(() => {
+      return {
+        body: JSON.stringify({
+          result: {
+            state: "preflight",
+            status: 0,
+            metrics: {},
+            error: "Preflight error: ...",
+          },
+          jsonrpc: "2.0",
+          id: 1,
+        }),
+      };
+    });
+
+    try {
+      await vlayer.waitForProvingResult({ hash });
+    } catch (e) {
+      expect((e as Error).message).toMatch(
+        "Preflight failed with error: Preflight error: ...",
+      );
+    }
+
+    expect(zkProvingSpy).toBeCalledTimes(2);
+    expect(zkProvingSpy).toHaveBeenNthCalledWith(1, ZkProvingStatus.Proving);
+    expect(zkProvingSpy).toHaveBeenNthCalledWith(2, ZkProvingStatus.Error);
+  });
+});

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>;