From fad43bc00b37bd4c29bd9f170ef50d23b3ff5e1f Mon Sep 17 00:00:00 2001 From: Guide Date: Mon, 24 Nov 2025 02:55:09 +0300 Subject: [PATCH] Update wallet.md --- yarn-project/alpha-sdk/docs/wallet.md | 74 +++++++++++++++++++-------- 1 file changed, 53 insertions(+), 21 deletions(-) diff --git a/yarn-project/alpha-sdk/docs/wallet.md b/yarn-project/alpha-sdk/docs/wallet.md index 38e901d78..47f5d0230 100644 --- a/yarn-project/alpha-sdk/docs/wallet.md +++ b/yarn-project/alpha-sdk/docs/wallet.md @@ -1,39 +1,71 @@ -# Aztec wallets +# 🛡️ Aztec Connect Wallet Development Utilities -The sdk provides some utilities to make developing a wallet for aztec connect easier. The two main utilities are the KeyStore and the WalletConnect Aztec Wallet Provider Server. +The Aztec SDK provides essential utilities to streamline the development of wallets for the Aztec Connect privacy layer. The primary components designed to facilitate this integration are the **KeyStore** and the **WalletConnect Aztec Wallet Provider Server (AWPS)**. -A full walletconnect-enabled web+iframe wallet example can be found [in this repo](https://github.com/AztecProtocol/wallet-ui). +A complete, production-ready example of a WalletConnect-enabled web and iframe wallet can be referenced [in this repository](https://github.com/AztecProtocol/wallet-ui). -## KeyStore +--- -The KeyStore purpose is to generate, use and export the Account and spending keys of an user. It has to implement [this interface](../src/key_store/key_store.ts). +## 🔑 KeyStore: Managing User Credentials -There are two versions of the keystore: +The **KeyStore** is the core utility responsible for managing a user's cryptographic keys within the Aztec ecosystem. Its main functionalities include key **generation**, **usage** (signing/derivation), and **export**. -- The legacy keystore ([code](../src/key_store/legacy_key_store.ts)): The account key and the spending key are generated from the signature of a message with an ethereum private key -- The Aztec keystore ([code](../src/key_store/aztec_key_store.ts)): - - The account and spending keys are generated using browser-provided randomness - - The keys can be exported encrypted with a password - - A recovery kit can be generated that, if you control the ethereum key it was generated with, allows to recover the account key and the funds associated with the account +All concrete implementations of the KeyStore must adhere to [the standard interface](../src/key_store/key_store.ts). -## WalletConnect Aztec Wallet Provider Server +### KeyStore Implementations -This class allows a walletconnect+iframe Aztec wallet to offer the AztecWalletProvider interface by providing it a walletconnect SignClient, a KeyStore, and a RollupProvider. The implementation can be found [here](../src/eip1193_aztec_wallet_provider/server/walletconnect_aztec_wallet_provider_server.ts). +The SDK currently supports two distinct key management approaches: -This server will interface with the provided keystore, requesting for approval when necessary (using approveProofsRequest and approveProofInputsRequest). +| Implementation | Key Generation Source | Key Storage & Recovery | Use Case | +| :--- | :--- | :--- | :--- | +| **Legacy KeyStore** | Signature derived from an **Ethereum private key**. | No built-in encryption or recovery. Keys are deterministic. | Primarily for backward compatibility or simple testing. | +| **Aztec KeyStore** | Generated using **browser-provided randomness**. | Supports password-encrypted key export and **Recovery Kits**. | Recommended for new wallets requiring robust security and recovery features. | -Example usage on the wallet side: +> **Recovery Kit:** A mechanism generated using an associated Ethereum key. Controlling this Ethereum key allows a user to recover their Account Key and the funds associated with their Aztec account, providing a strong security fallback. + +--- + +## 🔗 WalletConnect Aztec Wallet Provider Server (AWPS) + +The `WalletConnectAztecWalletProviderServer` class is the integration layer that bridges the WalletConnect protocol with the Aztec Provider interface. It allows an Aztec wallet (running typically in an iframe) to seamlessly offer the **AztecWalletProvider** interface to dApps. + +This class requires three main dependencies: a WalletConnect **SignClient**, a **KeyStore**, and a **RollupProvider**. + +The implementation details can be found [here](../src/eip1193_aztec_wallet_provider/server/walletconnect_aztec_wallet_provider_server.ts). + +### Interaction and Approval Flow + +The AWPS handles incoming requests (like transactions or viewing keys) from dApps and interfaces directly with the provided KeyStore. **Crucially, the server mediates security by requesting user confirmation:** + +* **`approveProofsRequest`:** Approval for transactions or state-changing operations that require a zero-knowledge proof. +* **`approveProofInputsRequest`:** Approval for the input data used to construct a zero-knowledge proof. + +> The wallet UI must implement handlers to intercept these approval requests and present the necessary confirmation prompt to the end-user. + +### Example Usage (Wallet Side) + +The following example demonstrates how to initialize and activate the AWPS: ```typescript +import { + WalletConnectAztecWalletProviderServer, + ServerRollupProvider, + AztecKeyStore, +} from '@aztec/sdk'; // Assuming necessary imports from SDK + +// 1. Instantiate the server. const aztecAWPServer = new WalletConnectAztecWalletProviderServer(); -aztecAWPServer.setClient(signClient); +// 2. Set up the WalletConnect client connection. +aztecAWPServer.setClient(signClient); // 'signClient' is the pre-configured WalletConnect SignClient instance. -// The server will start forwarding requests for public keys or signatures to the keystore +// 3. Initialize the wallet provider with necessary dependencies. +// Note: 'wasm' refers to the pre-compiled Aztec WebAssembly module required for cryptographic operations. await aztecAWPServer.initWalletProvider( - keyStore, - new ServerRollupProvider(new URL(process.env.ROLLUP_HOST)), - wasm, + keyStore, // The KeyStore instance (e.g., a new AztecKeyStore()) + new ServerRollupProvider(new URL(process.env.ROLLUP_HOST)), // The interface for communicating with the Aztec Rollup contract. + wasm, ); -``` +// The server is now running and forwarding dApp requests (via WalletConnect) +// to the KeyStore, requesting user approval when necessary.