How does Zerowallet work?

We'll cover all components used by the Zerowallet with an example flow in the end of the doc

In-app wallet (Zerowallet)

For each user interacting with your dapp, we will create an in-app wallet that will be the signer of all transactions going into the blockchain. This wallet is stored on your localStorage in case of a browser or in the SharedPrferences in case of a mobile app.

The Zerowallet goes through three steps to be able to send a gasless transaction:

  1. Send the raw transaction to the backend service to be built with correct types and structure

  2. Sign the retrieved transaction

  3. Send the transaction to the backend service to execute it on-chain

In case the user wants to use this wallet on a different device, we support several recovery mechanisms to import the wallet onto another device (or to restore the wallet in case the storage was cleared). See Recovery Mechanisms

Smart Contract Wallet (SCW)

The SCW (Smart Contract Wallet) is the on-chain transaction executor of theIn-app wallet (Zerowallet). There's a one-to-one mapping between each Zerowallet and SCW. The SCW is the one that will pay the gas and relayingrelay all transactions to the blockchain on behalf of the Zerowallet. Since the SCW will be the one sending the transactions to the blockchain, we know that it will be the msg.sender on any contract. So basically the SCW will be the owner and executor of any transaction signed by the Zerowallet.

Zerowallet Backend Service

This is where transactions will be sent after the Zerowallet signs the transaction.Authentication checks and transaction processing will happen here. If everything passes, the transaction will be sent to the SCW to be executed on-chain. See Running the docker service.


All SCWs will get the gas they need to carry out transactions from the gastank. You will be the one deciding which gastank should be used for each transaction. Each gastank is responsible for one chain, and it's possible to create multiple gastanks on the same chain.


Only authorized Zerowallets are allowed to send gasless transactions. You decide which wallets to authorize and when to authorize them. We create a tokennonce in the backend service for each authorized wallet with an expiration date. When it expires, you decide whether you want to refresh it or not.

When the Zerowallet sends a request to execute a transaction to the backend service, it should first retrieve its corresponding nonce, sign it, and append the signature to the request. In the backend service, we will check if the signer matches one of the authorized Zerowallets.

Recovery Mechanisms

To allow users to log into their zero wallets on new machines, Zerowallet allows users to backup and recover their wallets using Google Drive or using a web3 wallet like Metamask. Learn moreRecovery.

Example flow

A user enters the website with Zerowallet integrated. The user will be asked to take some action to prove that they're eligible to use gasless transactions (here you will authorize their Zerowallet). Then, when the user wants to interact with the dapp, all he has to do is press the button that triggers the contract function call. Here's what's happening under the hood:

  1. Authorize the Zerowallet in the backend service (here we create the nonce).

  2. Retrieve the nonce linked to the user's Zerowallet and sign it.

  3. Deploy the SCW for the user's Zerowallet by sending a request to the backend service (and appending the signature of the nonce to the request).

  4. Send another request to the backend service to build the transaction with correct types and structure (and appending the signature of the nonce to the request).

  5. Signing the built transaction.

  6. Send the final request to the backend service to execute the transaction (and appending the signature of the nonce to the request).

You can find a complete example here

Last updated