Skip to main content

Overview

info

This is the documentation for the legacy ZK Email SDK. For the latest version, please see the Blueprint SDK page.

Getting started

Google Client API key: You will need a Google OAuth token if you want users to be able to directly query emails from their inbox. Go to Google Cloud's dashboard to enable the Gmail API.

Learn how to create your GOOGLE_CLIENT_ID here.

React Project: The SDK currently only works with reactjs. If you are using nextjs, you might need some workarounds to make sure the page you integrate the SDK runs fully on the client side. Refer to this for reference example.

Wiring it up

Surround a page with the ZkEmailSDKProvider given by the SDK. If you are using nextjs, it is recommended that you only include this in a page that uses the SDK. Else, your entire application will need to be client-side rendered.

import { ZkEmailSDKProvider } from "@zk-email/zk-email-sdk";

function TryPage(props: Props) {
return (
<ZkEmailSDKProvider clientId={GOOGLE_CLIENT_ID} zkEmailSDKRegistryUrl='https://registry-dev.zkregex.com'>
<Page {...props}/>
</ZkEmailSDKProvider>
);
};

In your page, the SDK exposes a few hooks to interact with the library.

export function Page(props: Props) {
const {
googleAuthToken,
isGoogleAuthed,
loggedInGmail,
googleLogIn,
googleLogOut,
} = useGoogleAuth();

const {
createInputWorker,
generateInputFromEmail,
generateProofRemotely,
proofStatus,
inputWorkers
} = useZkEmailSDK();
}
HookTypeArgumentsDescription
googleAuthTokenstring-
isGoogleAuthedboolean-
loggedInGmailstring-User's email
googleLogInmethod-Triggers the OAuth page for users to login
googleLogOutmethod-Deletes the credentials stored in local browser
createInputWorkermethodpattern IDCreates a worker in the background that processes emails into circuit inputs. This always happens on the client side. It downloads a worker script from the registry and runs it in a sandboxed WebWorker.
generateInputFromEmailmethodpattern ID, raw emailReturns the circuit input generated by processing the email provided
generateProofRemotelymethodpattern ID, circuit inputUses the circuit input generated and queues a job. Circuit inputs are stored only before/during proof generation. This will automatically poll the server for updates.
proofStatus{[key:string]: ProofStatus}-A map of proof job IDs and the current status + proof outputs.
inputWorkers{[key: string]: Worker}-A map of input worker slugs and their associated web workers.
interface ProofStatus {
status: string;
id: string;
pollUrl: string;
estimatedTimeLeft: number;
publicOutput: any;
proof: any;
}

Example integration

First, create an inputWorker:

createInputWorker("<slug-name>");

Once the input worker is created, it will be populated in the inputWorkers variable. You can monitor this variable. As soon as the inputWorker is created, you can call the generateProofRemotely method:

const [externalInputs, setExternalInputs] = useState<Record<string,string>>({});

// externalInputs - External inputs added when submitting a new pattern at https://registry-dev.zkregex.com/submit
const entryExternalInputs = externalInputs as {name: string, maxLength: number}[] || [];

for (const input of entryExternalInputs) {
setExternalInputs({
...externalInputs,
[input.name]: "",
});
}

const input = await generateInputFromEmail(
"<slug-name>",
emailFull,
externalInputs
);

const proofRes = await generateProofRemotely(
"<slug-name>",
input
);