Smart wallet overview
This document provides an overview of zkFold Smart Wallet and its Web2 login feature. Smart Wallet enables wallet recovery using Google OAuth. Under the hood, Smart Wallet uses a Cardano smart contract to lock the user's funds. The user gets access to those funds by proving that they have access to the corresponding Google account (other OAuth options are in development). This feature also enables applications to send funds to any Gmail address without any prior setup.
Smart Wallet APIs
Smart Wallet Backend and Prover APIs are free-to-use REST APIs that enable developers to integrate Smart Wallet functionality into their applications. The Backend API handles wallet creation, fund transfers, and transaction submissions, while the Prover API generates zero-knowledge proofs for JWT verification. The prover server is open-source and can be self-hosted if needed. We describe the typical application flow in the corresponding section.
Google OAuth
The Web2 login feature relies on Google OAuth. It allows other services to authenticate a Google user with their Google account without disclosing any login credentials.
The way it works is that upon user login, authorization server issues a JSON Web Token with its signature. The signature can be verified using Google public keys.
For more details, see the corresponding section.
The JWT verification is performed offline using PlonK protocol.
Zero-knowledge proofs
A zero-knowledge proof is a cryptographic protocol that lets one party (the prover) demonstrate to another party (the verifier) that a particular statement is true without revealing any underlying data that supports the claim. In practice, the prover computes a short proof that can be checked quickly by the verifier; the verifier learns nothing beyond the validity of the assertion. This property is valuable whenever privacy is essential, such as proving ownership of credentials, confirming that a computation was performed correctly, or validating that input data satisfies certain rules, while keeping the raw inputs hidden.
Smart wallet exploits this property of ZK proofs, so that the JWT never leaves user's device and is never stored on-chain. Only proof bytes which do not allow an attacker to reconstruct the sensitive information are included in the transactions as redeemers of the smart contract.
For more details, see the corresponding section.
Smart contract
Cardano smart contracts are written in Plinth, a subset of Haskell that compiles to on-chain scripts executed by the Cardano Virtual Machine. The payment credential of user's smart wallet address is given by the spending validator, so they don't need to create a wallet in traditional sense, and thus avoid generating a seed phrase. This is the key difference between a regular wallet and the Smart wallet. When a user submits a transaction that spends funds from that address, the blockchain automatically runs the validator with the provided redeemer, datum, and context; if the script returns True, the transaction is accepted, otherwise it is rejected.
For more details, see the corresponding section.
Building transactions
There are two types of transactions:
- Initializing the wallet
- Spend funds from the wallet
The initialising transaction verifies the JWT ownership and mints a token. The subsequent spending transactions only verify that the correct token is present as a reference input.
For more details, see the corresponding section.
Useful links
zkFold Wallet is an open-source implementation of a wallet that leverages the Smart Wallet APIs. Its core business logic is implemented in the TypeScript library here: https://github.com/zkFold/smart-wallet-api You can find the Wallet UI implementation here: https://github.com/zkFold/smart-wallet-ui