Client Library SDK
Client library v5.2.0 development guide
The
zkbob-client-js library SDK is used to interact with the zkBob ecosystem from the client side. The SDK supports different privacy pool deployments and can be used to create custom clients.The latest stable version of the library is published on npmjs.com with the
latest tag. To use the library install it with your preferred packet manager like npm:npm i zkbob-client-js
or
yarn:yarn add zkbob-client-js
...or manually include it in the
package.json file as follows:"dependencies": {
.........
"zkbob-client-js": "5.2.0"
.........
}
All interactions with the solution are performed within the instance of the
ZkBobClient object which should be initialized with the desired pool configuration. There are two available modes for the ZkBobClient instance:- Account-less mode. The library can interact with most of the system components (such as relayers, contracts and so on) to retrieve publicly available data (transaction fee, limits, Merkle tree indexes and other data needed to render the UI), but cannot perform any actions belonging to the concrete user account (e.g. getting user's balance, making deposits\transfers\withdrawals and so on). The library starts on this state when the
ZkBobClientis instantiated. - Full mode. To switch to full mode you must provide user credentials (spending key) to the library. Do this by attaching a prepared user's account configuration. Logout of the account any time
- 1.Start with the Configuration section to understand which data you need start designing your own client.
- 2.Initialize a
ZkBobClientinstance and check that the account-less mode works properly. For example you can request the relayer fee or fetch privacy pool limits. All available functions for this mode are described in the Account-less Mode Operations section. - 4.Synchronize the local state with the relayer and privacy pool state. This operation can take some time depending on pool size (overall number of transactions in the pool).
- 5.Retrieve account related data (e.g. fetch shielded balance or generate a zk-address). All routines associated with the account are located in the Full Mode Operations section
You can always refer to the existing client implementations to get a better understanding and find answers to your questions:
- zkbob-console - a simple text Web-client based on jQuery Terminal. It's always synced with the last library version.
- Waiting for your cool implementation to include it here...!
You can build a custom client for the platform of your choice or add extended functionality like a custodial wallet service or mobile wallet. It should also be noted that the SDK relies heavily on underlying low-level Rust code compiled to WASM, so for example mobile support in React Native would impose additional challenges.
The SDK can be imported as a regular JS library, but it requires some customization of the webpack configuration, which can be challenging if you use
create-react-app. This is why we have created a ready-to-go react-template that utilizes react-app-rewired tool to override some configurations and make it all work.
Alternatively you can use Next.js or Vite to bootstrap your React app that allows you to access the webpack configuration.In order for a client to create a valid transaction proof, parameters and a verification key are required (for a quick sanity check before sending a transaction). These parameters are generated using a trusted setup ceremony for production usage, while the development environment uses some random values.
All the testing and development environments on testnets use the following parameters:
snarkParams: {
transferParamsUrl: 'https://r2-staging.zkbob.com/transfer_params_20022023.bin',
transferVkUrl: 'https://r2-staging.zkbob.com/transfer_verification_key_20022023.json'
}
All of the production environments use these parameters:
snarkParams: {
transferParamsUrl: 'https://r2.zkbob.com/transfer_params_22022023.bin',
transferVkUrl: 'https://r2.zkbob.com/transfer_verification_key_22022023.json'
}
The CDN is configured so that only requests from localhost and zkbob domains are processed, so you would have to download params files and include them in the bundle. You can see how to do that in the Examples
Currently the API between the front end and the SDK allows you to pass the account credentials in the form of a spending key that is derived from the mnemonic seed phrase. You can export your seed phrase and pass it to the function
deriveSpendingKeyZkBob to get a secret key: const sk = deriveSpendingKeyZkBob("general team spot pass shoulder domain axis crazy since kind athlete buzz")
Then pass the resulting spending key to the
accountConfig object to login. const client = await ZkBobClient.create(config, 'BOB-sepolia');
const accountConfig: AccountConfig = {
sk,
pool: 'BOB-sepolia',
birthindex: -1,
proverMode: ProverMode.Local,
};
await client.login(accountConfig);
If you'd rather derive a spending key from your Web3 wallet (such as MetaMask) signature then you need to get the menmonic first:
const mnemonic = ethers.utils.entropyToMnemonic(hexToBuf("9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"))
In the current version of the protocol, only the user can generate a new address for receiving funds inside the pool (zkAddress). Generating a zkAddress requires a secret encryption key which can only be provided by the user. Address generation itself is very easy, simply call the corresponding method of the client object.
const zkAddress = await zkClient?.generateAddress()
Last modified 2mo ago