Zero Knowledge Token Usage

Because a token transfer always happens with more than one party, we will use the following setup to demonstrate how to use the Zero Knowledge Token service to confidentially make payments.

Organizations involved in the example include Company Alice, Company Bob, and Company Charlie. All participants have already acquired a balance of Acme tokens, with symbol ACE, which is a fungible token implemented according to the ERC20 standard.

Initial state

The environment looks as follows:

The environment currently has 3 members: the respective companies for Alice, Bob and Charlie. Each member has created a node in the environment in order to use it to interact with the blockchain. Both Alice and Charlie will use the built-in wallet inside the blockchain node for signing transactions, whereas Bob has decided to use a separate signing wallet by creating a Kaleido EthWallet service.

An ERC20 token Acme Token with the symbol ACE has already been deployed. The current balances of each participant are as follows:

Creating a ZKP Smart Contract

The Zero Knowledge Smart Contract needs to be deployed in order to manage the confidential transfers. This can be accomplished by any of the private transfer parties. In this example Company Alice will deploy the contract.

Alice first creates a Zero Knowledge Tokens service, which can be accomplished either with the environment dashboard UI, or with an API call. From the service dashboard, Alice can see that the Acme token is eligible for "shielding."

Alice deploys the ZKP Smart Contract by clicking the Shield this token button on the card for the Acme token. After the contract has been successfully deployed, the card changes to display an overview of the confidential token contract:

In the overview above, the current total supply of the Acme token is displayed. Because no one has yet exchanged their Acme token balances for ZTH, the total supply of the confidential token contract, Total Shielded, is zero.

Creating Shielded Accounts

In order to hold ZTH balances, each participant must first create Shielded Accounts based on their Ethereum accounts. These accounts will be registered with the ZKP Smart Contract (deployed above) and are eligible to hold ZTH balances in exchange for the deposited Acme tokens from the corresponding Ethereum accounts.

Essentially, each shielded account is paired with the originating Ethereum account to represent the same identity for the two different token systems: ZTH vs. Acme ERC20.

Alice clicks the "Shield an account" button to enter the Manage Acme Token panel:

The Ethereum accounts owned by Alice are displayed in cards. Each card displays the following information about the account:

• Type of wallet:
  • Node Wallet: accounts are held in the blockchain node's built-in wallet
  • EthWallet: accounts are held in the EthWallet service
• Name of wallet
• Ethereum account address

Alice clicks the "Shield this account" button on the node wallet card to create a shielded account based on this Ethereum account.

After successful creation, the card is updated with some additional information:

• Shielded account address: displayed as an array of two 32-byte hexadecimal strings
• Shielded balance: the shielded account's balance in ZTH
• Public balance: the corresponding Ethereum account's balance in ACE tokens
• Withdraw button: disabled because the account does not have any deposited ACE tokens to withdraw
• Fund button: enabled because the account has a positive balance in ACE tokens to deposit into the ZKP Smart Contract

Bob and Charlie will each perform the same procedure to create a Zero Knowledge Tokens service and then use it to create shielded accounts. Because the ZKP Smart Contract has already been deployed by Alice, Bob and Charlie do not need to deploy it again. They can proceed directly to create shielded accounts within their respective service dashboard.

Funding The Shielded Accounts

In order to perform confidential transfers in ZTH, the sender shielded accounts must first acquire some ZTH balance by funding it with ACE tokens.

Alice can fund her account by clicking the "Fund" button on her shielded account card:

NOTE: due to performance considerations, the Zero Knowledge Token service limits ZTH balance to 100,000. If you have a production use case that requires a higher balance, please click Contact Us to reach out to our support to discuss necessary enhancements.

After successful funding, the shielded balance is now updated to the funded amount, while the public ACE tokens balance is debited accordingly.

Bob and Charlie can also fund their shielded accounts, or wait for transfers from Alice to acquire ZTH balances.

Funding from ACE tokens can be done any time as long as there are remaining ACE tokens.

Transfer ZTH tokens

Alice, Bob and Charlie are now free to transfer ZTH tokens between their shielded accounts and all such transfers are confidential. For instance, if Alice transfers 100 ZTH to Bob, the transaction can not be interpreted by Charlie in order to see the amount or who the sender/receiver are.

Alice clicks the "Initiate transfer" button to configure the transfer to one of Bob's accounts:

There is an additional step before a transfer is fully configured, which is to add anonymity by specifying "decoy" accounts. All available accounts known to the ZKP Smart Contract are listed for use as decoys. Because in the current example only 4 accounts exist, while the smallest recommended number of decoys is 6, this transfer will not have the anonymity protection.

Alice can proceed to submit the transfer transaction by clicking the "COMPLETE TRANSFER" button.

The "COMPLETE TRANSFER" button has a countdown timer that displays the epoch window required to submit the transfer. Details on how the epoch works with Zero Knowledge Token transfers can be found here

Withdrawing From ZTH Balances

To exchange ZTH balances back to ACE tokens, a withdraw operation is required.

From the shielded account card with a greater than zero shielded balance, click the "Withdraw" button and specify the amount to withdraw, and click "Withdraw token".

After a successful withdrawal, the shielded and public balances are updated accordingly.