LogoLogo
zkBob AppLinks & Resources
  • 🦹zkBob Overview
    • zkBob
    • Basic Concepts
      • Getting Started
      • Open-Source and Decentralized
      • Multichain Deployment
      • Usage Statistics
      • Use Cases
        • Employee Salary
        • Vendor Purchasing
      • Development Timeline
      • zk Privacy Solution Comparison
    • zkBob Pools
      • USDC Pool on Polygon (sunsets January 31, 2025)
      • USDC Pool on Optimism
      • ETH Pool on Optimism
      • USDT Pool on Tron (sunsets Oct 29, 2024)
    • Fees
      • Unspent note handling
    • Deposit & Withdrawal Limits
    • Compliance & Security
      • TRM Labs Integration
    • Conferences, Workshops, Videos
      • International Videos
    • Governance
    • BOB Stablecoin
    • zkBob FAQ
  • πŸ¦Έβ€β™‚οΈzkBob Application
    • UI Overview
    • Account Creation
      • Login to an existing account
      • Lost Password
      • Metamask / Web3 Wallet Warning
    • Deposits
    • Transfers
      • Multitransfers
    • Withdrawals
      • Native Token Conversion
    • Generate a Receiving Address
    • Optional KYC
    • zkBob Direct Deposits
    • Support ID
    • Payment Links
    • Integrated Services
    • Multilingual support
      • PortuguΓͺs
      • Русский
      • δΈ­ζ–‡
  • πŸ‘©β€βš•οΈTechnical Implementation
    • zkBob Application Overview
    • Deployed Contracts
    • Smart Contracts
      • zkBob Pool Contract
        • Transaction Calldata
      • Bob Token Contract
      • Verifier contracts
      • Operator Manager Contract
        • Mutable Operator Manager
      • Voucher (XP) Token Contract
    • Accounts and Notes
      • Accounts
      • Notes
    • Relayer Node
      • Relayer Operations
      • Optimistic State
      • REST API
    • zkBob Keys
      • Address derivation
      • Ephemeral keys
    • zkSNARKs & Circuits
      • Transfer verifier circuit overview
    • zkBob Merkle Tree
      • The Poseidon Hash
    • Elliptic Curve Cryptography
    • Transaction Overview
      • Common Structure
      • Memo Block
        • Memo Block Encryption
      • Transaction Types
      • Nullifiers
      • Signing a Transaction
      • The Transaction Lifecycle
    • Client Library SDK
      • Configuration
        • Initializing the client
          • Client Configuration
        • Attaching a User Account
          • Account Configuration
        • Switching Between Pools
      • Account-less Mode Operations
        • Converting Token Amounts
        • Transaction Fees
        • Transaction Constraints
        • Using the Delegated Prover
        • Getting the State
        • Gift Cards
        • Client Library Status
        • Helpers
        • Versioning
      • Full Mode Operations
        • Balances and History
        • Shielded Addresses
        • Account State
        • Fee Estimations
        • Transaction Configuration
        • Sending Transactions
        • Transaction Maintenance
        • Direct Deposits
        • Gift Cards Maintenance
        • Ephemeral Deposits
        • Forced Exit
        • Other Routines
      • Common Types
      • Full Functions List
      • Utilities
  • πŸ‘©β€πŸ«Deployment
    • Trusted Setup Ceremony
    • Contract Deployment
    • Relayer Subsystem
  • πŸ‘·β€β™‚οΈRoadmap
    • On the Roadmap
    • Exploratory Features
      • XP (Experience Points)
        • XP-based Auctions
      • Multi-chain Custom Rollup Deployment
      • Round-robin Operator Manager
      • Compounding
  • πŸ§‘β€πŸ’»Jobs
    • Zero-Knowledge Researcher & Protocol Developer
  • 🧩Resources
    • Visual Assets
    • Hackathons
      • zkBob Cloud
    • Release Notes
      • October 11, 2023
      • July 13, 2023
      • June 13, 2023
      • March 28, 2023
      • January 30, 2023
      • January 16, 2023
      • January 2, 2023
      • Releases 2022
    • Security Audit
    • Github
    • Link tree
Powered by GitBook
On this page
  • Get Started
  • Next Steps
  • Examples
  • FAQ

Was this helpful?

  1. Technical Implementation

Client Library SDK

Client library v5.4.0 development guide

PreviousThe Transaction LifecycleNextConfiguration

Last updated 1 year ago

Was this helpful?

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.

Get Started

The latest stable version of the library is published on 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.4.0"
    .........
}

All interactions with the solution are performed within the instance of the ZkBobClient object which should be initialized with the desired . 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 ZkBobClient is .

  • Full mode. To switch to full mode you must provide user credentials (spending key) to the library. Do this by a prepared user's . of the account any time

Next Steps

  1. Start with the Configuration section to understand which data you need start designing your own client.

Examples

You can always refer to the existing client implementations to get a better understanding and find answers to your questions:

  • Waiting for your cool implementation to include it here...!

FAQ

What can I build using ZkBob client SDK?

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.

How do I use ZkBob SDK in my React app?

Where do I get Snark parameters for client initialization?

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

How do I login to an existing account using the SDK?

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',
      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"))

See the full code for client instantiation and login in Examples

How do I generate an address for receiving funds?

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()

Associated examples are available for and configurations.

Actual production and development configurations are available for .

a ZkBobClient instance and check that the account-less mode works properly. For example you can or . All available functions for this mode are described in the Account-less Mode Operations section.

Create you own and it to the ZkBobClient instance. Remember only one account can be attached at a time.

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).

Retrieve account related data (e.g. or ). All routines associated with the account are located in the Full Mode Operations section

located in the client repository's README file.

- a simple text Web-client based on jQuery Terminal. It's always synced with the last library version.

- a React App template project with integrated zkbob-client-js library.

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

πŸ‘©β€βš•οΈ
A brief how-to example
zkbob-console
react-template
react-template
npmjs.com
pool configuration
instantiated
account configuration
Initialize
account
fetch privacy pool limits
account
fetch shielded balance
generate a zk-address
Synchronize
attaching
Logout
attach
request the relayer fee
client
download here