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

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}`;
+  });
+}

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

@@ -0,0 +1,52 @@
+import { describe, test, expect } from "vitest";
+import { checkVersionCompatibility } from "./versions";
+
+describe("versions compatibility", () => {
+  test("throws if major version mismatches", () => {
+    expect(() => {
+      checkVersionCompatibility("1.2.3", "2.1.3");
+    }).toThrowError(
+      "SDK version 2.1.3 is incompatible with prover version 1.2.3",
+    );
+  });
+
+  test("throws if major version mismatches with metadata after dash", () => {
+    expect(() => {
+      checkVersionCompatibility("1.2.3-dev-123456-deadbeef", "2.1.3");
+    }).toThrowError(
+      "SDK version 2.1.3 is incompatible with prover version 1.2.3-dev-123456-deadbeef",
+    );
+  });
+
+  test("throws if major version is 0 and minor version mismatches", () => {
+    expect(() => {
+      checkVersionCompatibility("0.2.3", "0.1.3");
+    }).toThrowError(
+      "SDK version 0.1.3 is incompatible with prover version 0.2.3",
+    );
+  });
+
+  test("does not throw if major and minor versions match", () => {
+    expect(() => {
+      checkVersionCompatibility("1.2.3", "1.2.13");
+    }).not.toThrow();
+  });
+
+  test("does not throw if major version is >0 and minor mismatches", () => {
+    expect(() => {
+      checkVersionCompatibility("1.2.3", "1.5.8");
+    }).not.toThrow();
+  });
+
+  test("does not throw if major version is 0 and minor matches", () => {
+    expect(() => {
+      checkVersionCompatibility("0.2.3", "0.2.7");
+    }).not.toThrow();
+  });
+
+  test("works for semvers with metadata after dash", () => {
+    expect(() => {
+      checkVersionCompatibility("0.2.3-dev-123456-deadbeef", "0.2.7");
+    }).not.toThrow();
+  });
+});

package/src/api/utils/versions.ts

@@ -0,0 +1,31 @@
+import { parse, type SemVer } from "semver";
+import { VersionError } from "../lib/errors";
+
+function safeParseSemver(semverString: string): SemVer {
+  const parsed = parse(semverString);
+  if (parsed === null) {
+    throw new VersionError(`Invalid semver string: ${semverString}`);
+  }
+  return parsed;
+}
+
+export function checkVersionCompatibility(
+  proverSemver: string,
+  sdkSemver: string,
+) {
+  const { major: proverMajor, minor: proverMinor } =
+    safeParseSemver(proverSemver);
+  const { major: sdkMajor, minor: sdkMinor } = safeParseSemver(sdkSemver);
+
+  if (proverMajor !== sdkMajor) {
+    throw new VersionError(
+      `SDK version ${sdkSemver} is incompatible with prover version ${proverSemver}`,
+    );
+  }
+
+  if (proverMajor === 0 && proverMinor !== sdkMinor) {
+    throw new VersionError(
+      `SDK version ${sdkSemver} is incompatible with prover version ${proverSemver}`,
+    );
+  }
+}

package/src/api/v_call.ts

@@ -0,0 +1,58 @@
+import {
+  type CallContext,
+  type CallParams,
+  type VCallResponse,
+} from "./lib/types/vlayer";
+import { parseVCallResponseError } from "./lib/errors";
+import debug from "debug";
+
+const log = debug("vlayer:v_call");
+
+function v_callBody(call: CallParams, context: CallContext) {
+  console.log("call", call);
+  console.log("context", context);
+  return {
+    method: "v_call",
+    params: [call, context],
+    id: 1,
+    jsonrpc: "2.0",
+  };
+}
+
+export async function v_call(
+  call: CallParams,
+  context: CallContext,
+  url: string = "http://127.0.0.1:3000",
+  token?: string,
+): Promise<VCallResponse> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (token !== undefined) {
+    headers["Authorization"] = "Bearer " + token;
+  }
+  const response = await fetch(url, {
+    method: "POST",
+    body: JSON.stringify(v_callBody(call, context)),
+    headers,
+  });
+  log("response", response);
+  if (!response.ok) {
+    throw new Error(`HTTP error! status: ${response.status}`);
+  }
+  const response_json = await response.json();
+  log("response_json", response_json);
+  assertObject(response_json);
+  if ("error" in response_json) {
+    throw parseVCallResponseError(
+      response_json.error as { message: string | undefined },
+    );
+  }
+  return response_json as Promise<VCallResponse>;
+}
+
+function assertObject(x: unknown): asserts x is object {
+  if (typeof x !== "object") {
+    throw new Error("Expected object");
+  }
+}

package/src/api/v_getProofReceipt.ts

@@ -0,0 +1,48 @@
+import {
+  type VGetProofReceiptParams,
+  type VGetProofReceiptResponse,
+} from "./lib/types/vlayer";
+import { parseVCallResponseError } from "./lib/errors";
+import { vGetProofReceiptSchema } from "./lib/types/vlayer";
+import debug from "debug";
+
+const log = debug("vlayer:v_getProofReceipt");
+
+function v_getProofReceiptBody(params: VGetProofReceiptParams) {
+  return {
+    method: "v_getProofReceipt",
+    params: params,
+    id: 1,
+    jsonrpc: "2.0",
+  };
+}
+
+export async function v_getProofReceipt(
+  params: VGetProofReceiptParams,
+  url: string = "http://127.0.0.1:3000",
+): Promise<VGetProofReceiptResponse> {
+  const response = await fetch(url, {
+    method: "POST",
+    body: JSON.stringify(v_getProofReceiptBody(params)),
+    headers: { "Content-Type": "application/json" },
+  });
+  log("response", response);
+  if (!response.ok) {
+    throw new Error(`HTTP error! status: ${response.status}`);
+  }
+  const response_json = await response.json();
+  log("response_json", response_json);
+  assertObject(response_json);
+  if ("error" in response_json) {
+    throw parseVCallResponseError(
+      response_json.error as { message: string | undefined },
+    );
+  }
+  return vGetProofReceiptSchema.parse(response_json);
+}
+
+function assertObject(x: unknown): asserts x is object {
+  if (typeof x !== "object") {
+    throw new Error("Expected object");
+  }
+}

package/src/api/v_versions.ts

@@ -0,0 +1,68 @@
+import debug from "debug";
+
+const log = debug("vlayer:v_versions");
+
+const v_versionsBody = {
+  method: "v_versions",
+  params: [],
+  id: 1,
+  jsonrpc: "2.0",
+};
+
+interface VVersionsResponseResult {
+  call_guest_id: string;
+  chain_guest_id: string;
+  api_version: string;
+}
+
+export interface VVersionsResponse {
+  jsonrpc: string;
+  result: VVersionsResponseResult;
+  id: number;
+}
+
+export async function v_versions(
+  url: string = "http://127.0.0.1:3000",
+): Promise<VVersionsResponse> {
+  const response = await fetch(url, {
+    method: "POST",
+    body: JSON.stringify(v_versionsBody),
+    headers: { "Content-Type": "application/json" },
+  });
+  log("response", response);
+  if (!response.ok) {
+    throw new Error(`HTTP error! status: ${response.status}`);
+  }
+  const response_json = await response.json();
+  assertResponseObject(response_json);
+  return response_json;
+}
+
+function isFieldAString(
+  x: object,
+  field: keyof VVersionsResponseResult,
+): boolean {
+  return (
+    field in x && typeof (x as VVersionsResponseResult)[field] === "string"
+  );
+}
+
+function assertResponseObject(x: unknown): asserts x is VVersionsResponse {
+  if (!x || typeof x !== "object") {
+    throw new Error("Expected object");
+  }
+  if (!("result" in x) || !x.result || typeof x.result !== "object") {
+    throw new Error(
+      `Unexpected \`v_versions\` response: ${JSON.stringify(x, null, 2)}`,
+    );
+  }
+  if (
+    !isFieldAString(x.result, "call_guest_id") ||
+    !isFieldAString(x.result, "chain_guest_id") ||
+    !isFieldAString(x.result, "api_version")
+  ) {
+    throw new Error(
+      `Unexpected \`v_versions\` response: ${JSON.stringify(x, null, 2)}`,
+    );
+  }
+}

package/src/api/webProof/createWebProofRequest.ts

@@ -0,0 +1,15 @@
+import {
+  type WebProofRequest,
+  type WebProofRequestInput,
+} from "../lib/types/webProofProvider";
+
+export const createWebProofRequest = ({
+  logoUrl,
+  steps,
+}: WebProofRequestInput) => {
+  return {
+    logoUrl,
+    steps,
+    isWebProof: true,
+  } as WebProofRequest;
+};

package/src/api/webProof/index.ts

@@ -0,0 +1,3 @@
+export * from "./createWebProofRequest";
+export * from "./steps";
+export * from "./providers";

package/src/api/webProof/providers/extension.test.ts

@@ -0,0 +1,122 @@
+import { createExtensionWebProofProvider } from "./extension";
+import { describe, it, expect, vi } from "vitest";
+import { expectUrl, startPage, notarize } from "../steps";
+import { StepValidationError } from "../../../web-proof-commons";
+
+const chrome = {
+  runtime: {
+    disconnectCallbacks: [] as (() => void)[],
+    connect: vi.fn().mockImplementation(() => ({
+      postMessage: vi.fn().mockImplementation(() => {}),
+      onMessage: {
+        addListener: vi.fn().mockImplementation(() => {}),
+      },
+      onDisconnect: {
+        addListener: vi.fn().mockImplementation((callback: () => void) => {
+          chrome.runtime.disconnectCallbacks.push(callback);
+        }),
+      },
+    })),
+    disconnect: vi.fn().mockImplementation(() => {
+      chrome.runtime.disconnectCallbacks.forEach((callback) => {
+        callback();
+      });
+    }),
+  },
+};
+
+vi.stubGlobal("chrome", chrome);
+
+const defaults = {
+  logoUrl: "https://example.com/logo.png",
+  proverCallCommitment: {
+    address: "0x" as `0x${string}`,
+    proverAbi: [],
+    chainId: 1,
+    functionName: "test",
+    commitmentArgs: null as never,
+  },
+};
+
+const invalidUrl = "http:/example.com";
+const invalidUrlPattern = "http://+.test";
+const validUrl = "https://example.com";
+const validUrlPattern = "https://example.com/test";
+const label = "test";
+
+describe("ExtensionWebProofProvider", () => {
+  it("should properly validate startPage step", () => {
+    const provider = createExtensionWebProofProvider();
+    expect(() =>
+      provider.requestWebProof({
+        ...defaults,
+        steps: [startPage(invalidUrl, label)],
+      }),
+    ).toThrow(StepValidationError);
+  });
+
+  it("should properly validate expectUrl step", () => {
+    const provider = createExtensionWebProofProvider();
+    expect(() =>
+      provider.requestWebProof({
+        ...defaults,
+        steps: [expectUrl(invalidUrlPattern, label)],
+      }),
+    ).toThrow(StepValidationError);
+  });
+
+  it("should properly validate notarize step", () => {
+    const provider = createExtensionWebProofProvider();
+    expect(() =>
+      provider.requestWebProof({
+        ...defaults,
+        steps: [notarize(invalidUrlPattern, "GET", label)],
+      }),
+    ).toThrow(StepValidationError);
+  });
+
+  it("successfully validates all steps", () => {
+    const provider = createExtensionWebProofProvider();
+    expect(() =>
+      provider.requestWebProof({
+        ...defaults,
+        steps: [
+          startPage(validUrl, label),
+          expectUrl(validUrlPattern, label),
+          notarize(validUrlPattern, "GET", label),
+        ],
+      }),
+    ).not.toThrow(StepValidationError);
+  });
+
+  it("should properly work backward compatible way with only urls used", () => {
+    const provider = createExtensionWebProofProvider();
+
+    expect(() =>
+      provider.requestWebProof({
+        ...defaults,
+        steps: [
+          startPage(validUrl, label),
+          expectUrl(validUrl, label),
+          expectUrl(validUrl, label),
+          notarize(validUrl, "GET", label),
+        ],
+      }),
+    ).not.toThrow();
+  });
+
+  it("should reconnect extension on disconnect", () => {
+    const provider = createExtensionWebProofProvider();
+    provider.requestWebProof({
+      ...defaults,
+      steps: [
+        startPage(validUrl, label),
+        expectUrl(validUrlPattern, label),
+        notarize(validUrlPattern, "GET", label),
+      ],
+    });
+    chrome.runtime.connect.mockClear();
+    chrome.runtime.disconnect();
+    expect(chrome.runtime.connect).toHaveBeenCalled();
+  });
+});