@walletmesh/aztec-rpc-wallet 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/dist/.tsbuildinfo +1 -1
- package/dist/aztecRemoteWallet.d.ts +4 -8
- package/dist/aztecRemoteWallet.d.ts.map +1 -1
- package/dist/aztecRemoteWallet.js +5 -29
- package/dist/contractArtifactCache.d.ts.map +1 -1
- package/dist/contractArtifactCache.js +20 -9
- package/dist/handlers/aztecAccountWallet.d.ts.map +1 -1
- package/dist/handlers/aztecAccountWallet.js +11 -44
- package/dist/serializers/account.d.ts +16 -16
- package/dist/serializers/account.d.ts.map +1 -1
- package/dist/serializers/account.js +43 -43
- package/dist/serializers/contract.d.ts +22 -76
- package/dist/serializers/contract.d.ts.map +1 -1
- package/dist/serializers/contract.js +68 -120
- package/dist/serializers/index.d.ts +0 -4
- package/dist/serializers/index.d.ts.map +1 -1
- package/dist/serializers/index.js +15 -20
- package/dist/serializers/log.d.ts +16 -16
- package/dist/serializers/log.d.ts.map +1 -1
- package/dist/serializers/log.js +43 -43
- package/dist/serializers/note.d.ts +12 -12
- package/dist/serializers/note.d.ts.map +1 -1
- package/dist/serializers/note.js +32 -32
- package/dist/serializers/transaction.d.ts +25 -26
- package/dist/serializers/transaction.d.ts.map +1 -1
- package/dist/serializers/transaction.js +92 -44
- package/dist/types.d.ts +7 -30
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +1 -1
- package/docs/README.md +264 -0
- package/docs/classes/AztecChainProvider.md +553 -0
- package/docs/classes/AztecChainWallet.md +409 -0
- package/docs/classes/AztecProvider.md +1112 -0
- package/docs/classes/AztecWalletError.md +213 -0
- package/docs/classes/ContractArtifactCache.md +81 -0
- package/docs/globals.md +34 -0
- package/docs/interfaces/AztecWalletBaseMethodMap.md +135 -0
- package/docs/interfaces/AztecWalletEventMap.md +17 -0
- package/docs/interfaces/AztecWalletMethodMap.md +1012 -0
- package/docs/type-aliases/AztecChainId.md +11 -0
- package/docs/type-aliases/AztecChainWalletMiddleware.md +13 -0
- package/docs/type-aliases/AztecWalletContext.md +29 -0
- package/docs/type-aliases/AztecWalletMethodHandler.md +37 -0
- package/docs/type-aliases/AztecWalletMiddleware.md +13 -0
- package/docs/type-aliases/AztecWalletRouterClient.md +13 -0
- package/docs/type-aliases/TransactionFunctionCall.md +33 -0
- package/docs/type-aliases/TransactionParams.md +27 -0
- package/docs/variables/AztecWalletErrorMap.md +13 -0
- package/package.json +9 -9
- package/src/aztecRemoteWallet.test.ts +22 -61
- package/src/aztecRemoteWallet.ts +8 -35
- package/src/chainProvider.test.ts +117 -38
- package/src/contractArtifactCache.test.ts +28 -45
- package/src/contractArtifactCache.ts +20 -10
- package/src/handlers/aztecAccountWallet.test.ts +12 -86
- package/src/handlers/aztecAccountWallet.ts +19 -77
- package/src/provider.test.ts +0 -2
- package/src/serializers/account.test.ts +19 -20
- package/src/serializers/account.ts +52 -52
- package/src/serializers/contract.test.ts +4 -140
- package/src/serializers/contract.ts +93 -166
- package/src/serializers/index.test.ts +30 -28
- package/src/serializers/index.ts +15 -21
- package/src/serializers/log.test.ts +42 -48
- package/src/serializers/log.ts +54 -54
- package/src/serializers/note.test.ts +43 -16
- package/src/serializers/note.ts +39 -39
- package/src/serializers/transaction.test.ts +48 -41
- package/src/serializers/transaction.ts +146 -58
- package/src/types.ts +7 -7
- package/src/wallet.test.ts +3 -3
- package/dist/serializers/transaction-utils.d.ts +0 -51
- package/dist/serializers/transaction-utils.d.ts.map +0 -1
- package/dist/serializers/transaction-utils.js +0 -103
- package/src/serializers/transaction-utils.ts +0 -174
package/docs/README.md
ADDED
@@ -0,0 +1,264 @@
|
|
1
|
+
**@walletmesh/aztec-rpc-wallet v0.3.0**
|
2
|
+
|
3
|
+
***
|
4
|
+
|
5
|
+
# WalletMesh Aztec RPC Wallet Library
|
6
|
+
|
7
|
+
[@walletmesh/aztec-rpc-wallet](https://github.com/WalletMesh/walletmesh-packages/tree/main/aztec/aztec-rpc-wallet) provides a type-safe RPC interface for interacting with [Aztec](https://aztec.network) wallets. It consists of three main components:
|
8
|
+
|
9
|
+
- **AztecProvider**: Client-side provider for dApps to communicate with Aztec wallets
|
10
|
+
- **AztecChainWallet**: Server-side implementation that handles RPC requests using an Aztec wallet instance
|
11
|
+
- **AztecOperationBuilder**: Fluent API for chaining multiple RPC method calls
|
12
|
+
|
13
|
+
The library is built on [@walletmesh/jsonrpc](https://github.com/WalletMesh/walletmesh-packages/tree/main/core/jsonrpc#readme) and [@walletmesh/router](https://github.com/WalletMesh/walletmesh-packages/tree/main/core/router#readme).
|
14
|
+
|
15
|
+
## Features
|
16
|
+
|
17
|
+
- Connect to multiple Aztec chains simultaneously
|
18
|
+
- Flexible chain ID support (any string with 'aztec:' prefix)
|
19
|
+
- Type-safe RPC interfaces with comprehensive TypeScript definitions
|
20
|
+
- Efficient batching of multiple method calls
|
21
|
+
- Fluent chaining API for bulk operations
|
22
|
+
- Comprehensive error handling
|
23
|
+
- Contract artifact caching
|
24
|
+
- Event handling for wallet state changes
|
25
|
+
- Serialization support for all Aztec data types
|
26
|
+
- Support for encrypted and unencrypted events/logs
|
27
|
+
|
28
|
+
## Installation
|
29
|
+
|
30
|
+
```bash
|
31
|
+
npm install @walletmesh/aztec-rpc-wallet
|
32
|
+
```
|
33
|
+
|
34
|
+
## Core RPC Methods
|
35
|
+
|
36
|
+
The library supports a comprehensive set of RPC methods:
|
37
|
+
|
38
|
+
### Chain Operations
|
39
|
+
- `aztec_connect`: Connect to Aztec chains
|
40
|
+
- `aztec_getBlock`: Get block by number
|
41
|
+
- `aztec_getBlockNumber`: Get current block number
|
42
|
+
- `aztec_getProvenBlockNumber`: Get proven block number
|
43
|
+
- `aztec_getChainId`: Get chain ID
|
44
|
+
- `aztec_getVersion`: Get protocol version
|
45
|
+
- `aztec_getNodeInfo`: Get node information
|
46
|
+
- `aztec_getPXEInfo`: Get PXE information
|
47
|
+
- `aztec_getCurrentBaseFees`: Get current base fees
|
48
|
+
|
49
|
+
### Account Operations
|
50
|
+
- `aztec_getAccount`: Get wallet's account address
|
51
|
+
- `aztec_getAddress`: Get wallet's Aztec address
|
52
|
+
- `aztec_getCompleteAddress`: Get complete address details
|
53
|
+
- `aztec_registerAccount`: Register a new account
|
54
|
+
- `aztec_getRegisteredAccounts`: Get all registered accounts
|
55
|
+
|
56
|
+
### Transaction Operations
|
57
|
+
- `aztec_sendTransaction`: Send one or more transactions
|
58
|
+
- `aztec_simulateTransaction`: Simulate transaction without executing
|
59
|
+
- `aztec_sendTx`: Send raw transaction
|
60
|
+
- `aztec_createTxExecutionRequest`: Create transaction execution request
|
61
|
+
- `aztec_proveTx`: Generate transaction proof
|
62
|
+
- `aztec_getTxEffect`: Get transaction effect
|
63
|
+
- `aztec_getTxReceipt`: Get transaction receipt
|
64
|
+
|
65
|
+
### Contract Operations
|
66
|
+
- `aztec_registerContract`: Register contract instance
|
67
|
+
- `aztec_registerContractClass`: Register contract class
|
68
|
+
- `aztec_getContracts`: Get registered contracts
|
69
|
+
- `aztec_getContractInstance`: Get contract instance details
|
70
|
+
- `aztec_getContractClass`: Get contract class details
|
71
|
+
- `aztec_getContractArtifact`: Get contract artifact
|
72
|
+
- `aztec_isContractClassPubliclyRegistered`: Check if contract class is publicly registered
|
73
|
+
- `aztec_isContractPubliclyDeployed`: Check if contract is publicly deployed
|
74
|
+
- `aztec_isContractInitialized`: Check if contract is initialized
|
75
|
+
- `aztec_getPublicStorageAt`: Get public storage value
|
76
|
+
|
77
|
+
### Authorization & Scope Management
|
78
|
+
- `aztec_setScopes`: Set authorization scopes
|
79
|
+
- `aztec_getScopes`: Get current scopes
|
80
|
+
- `aztec_addAuthWitness`: Add authorization witness
|
81
|
+
- `aztec_getAuthWitness`: Get authorization witness
|
82
|
+
- `aztec_createAuthWit`: Create authorization witness
|
83
|
+
|
84
|
+
### Notes and Events
|
85
|
+
- `aztec_getIncomingNotes`: Get incoming notes
|
86
|
+
- `aztec_addNote`: Add note
|
87
|
+
- `aztec_addNullifiedNote`: Add nullified note
|
88
|
+
- `aztec_getUnencryptedLogs`: Get unencrypted logs
|
89
|
+
- `aztec_getContractClassLogs`: Get contract class logs
|
90
|
+
- `aztec_getEncryptedEvents`: Get encrypted events
|
91
|
+
- `aztec_getUnencryptedEvents`: Get unencrypted events
|
92
|
+
|
93
|
+
### L1->L2 Bridge Operations
|
94
|
+
- `aztec_isL1ToL2MessageSynced`: Check if L1->L2 message is synced
|
95
|
+
- `aztec_getL1ToL2MembershipWitness`: Get L1->L2 membership witness
|
96
|
+
|
97
|
+
See [src/types.ts](https://github.com/WalletMesh/walletmesh-packages/blob/main/aztec/aztec-rpc-wallet/src/types.ts) for complete method definitions and parameters.
|
98
|
+
|
99
|
+
## Usage Examples
|
100
|
+
|
101
|
+
### Basic Provider Usage
|
102
|
+
|
103
|
+
```typescript
|
104
|
+
import { AztecProvider } from '@walletmesh/aztec-rpc-wallet';
|
105
|
+
|
106
|
+
// Create provider with transport
|
107
|
+
const provider = new AztecProvider(transport);
|
108
|
+
|
109
|
+
// Connect to chains
|
110
|
+
await provider.connect(['aztec:testnet', 'aztec:devnet']);
|
111
|
+
|
112
|
+
// Get account address
|
113
|
+
const address = await provider.getAccount('aztec:testnet');
|
114
|
+
|
115
|
+
// Send transaction
|
116
|
+
const txHash = await provider.sendTransaction('aztec:testnet', {
|
117
|
+
functionCalls: [{
|
118
|
+
contractAddress: "0x1234...",
|
119
|
+
functionName: "transfer",
|
120
|
+
args: [recipient, amount]
|
121
|
+
}]
|
122
|
+
});
|
123
|
+
|
124
|
+
// Register contract
|
125
|
+
await provider.registerContract('aztec:testnet', {
|
126
|
+
instance: contractInstance,
|
127
|
+
artifact: contractArtifact // optional if class already registered
|
128
|
+
});
|
129
|
+
|
130
|
+
// Listen for chain connection events
|
131
|
+
provider.on('chain:connected', ({ chainId }) => {
|
132
|
+
console.log(`Connected to chain: ${chainId}`);
|
133
|
+
});
|
134
|
+
|
135
|
+
// Listen for chain disconnection events
|
136
|
+
provider.on('chain:disconnected', ({ chainId }) => {
|
137
|
+
console.log(`Disconnected from chain: ${chainId}`);
|
138
|
+
});
|
139
|
+
```
|
140
|
+
|
141
|
+
### Chaining API for Bulk Operations
|
142
|
+
|
143
|
+
The provider supports a fluent chaining API for executing multiple operations efficiently:
|
144
|
+
|
145
|
+
```typescript
|
146
|
+
// Multiple reads in single batch
|
147
|
+
const [account, contracts, blockNumber] = await provider
|
148
|
+
.chain('aztec:testnet')
|
149
|
+
.call('aztec_getAccount')
|
150
|
+
.call('aztec_getContracts')
|
151
|
+
.call('aztec_getBlockNumber')
|
152
|
+
.execute();
|
153
|
+
|
154
|
+
// Contract setup and interaction
|
155
|
+
const [classId, instanceId, txHash] = await provider
|
156
|
+
.chain('aztec:testnet')
|
157
|
+
.call('aztec_registerContractClass', { artifact: contractArtifact })
|
158
|
+
.call('aztec_registerContract', {
|
159
|
+
instance: contractInstance,
|
160
|
+
artifact: contractArtifact
|
161
|
+
})
|
162
|
+
.call('aztec_sendTransaction', {
|
163
|
+
functionCalls: [{
|
164
|
+
contractAddress: contractInstance.address,
|
165
|
+
functionName: 'initialize',
|
166
|
+
args: [param1, param2]
|
167
|
+
}]
|
168
|
+
})
|
169
|
+
.execute();
|
170
|
+
|
171
|
+
// Multi-chain operations
|
172
|
+
const [testnetData, devnetData] = await Promise.all([
|
173
|
+
provider
|
174
|
+
.chain('aztec:testnet')
|
175
|
+
.call('aztec_getAccount')
|
176
|
+
.call('aztec_getContracts')
|
177
|
+
.execute(),
|
178
|
+
provider
|
179
|
+
.chain('aztec:devnet')
|
180
|
+
.call('aztec_getAccount')
|
181
|
+
.call('aztec_getContracts')
|
182
|
+
.execute()
|
183
|
+
]);
|
184
|
+
```
|
185
|
+
|
186
|
+
### Error Handling
|
187
|
+
|
188
|
+
The library provides comprehensive error handling through `AztecWalletError`:
|
189
|
+
|
190
|
+
```typescript
|
191
|
+
try {
|
192
|
+
await provider.sendTransaction('aztec:testnet', {
|
193
|
+
functionCalls: [{
|
194
|
+
contractAddress: "0x1234...",
|
195
|
+
functionName: "transfer",
|
196
|
+
args: [recipient, amount]
|
197
|
+
}]
|
198
|
+
});
|
199
|
+
} catch (error) {
|
200
|
+
if (error instanceof AztecWalletError) {
|
201
|
+
switch (error.code) {
|
202
|
+
case -32001: // User refused
|
203
|
+
console.log('Transaction rejected by user');
|
204
|
+
break;
|
205
|
+
case -32002: // Wallet not connected
|
206
|
+
console.log('Please connect wallet first');
|
207
|
+
break;
|
208
|
+
default:
|
209
|
+
console.error('RPC error:', error.message);
|
210
|
+
}
|
211
|
+
}
|
212
|
+
}
|
213
|
+
```
|
214
|
+
|
215
|
+
### Implementing a Wallet
|
216
|
+
|
217
|
+
Server-side implementation using `AztecWallet`:
|
218
|
+
|
219
|
+
```typescript
|
220
|
+
import { AztecChainWallet } from '@walletmesh/aztec-rpc-wallet';
|
221
|
+
import type { PXE, AccountWallet } from '@aztec/aztec.js';
|
222
|
+
|
223
|
+
// Create wallet instance
|
224
|
+
const wallet = new AztecChainWallet(
|
225
|
+
pxe, // PXE instance
|
226
|
+
accountWallet, // Aztec AccountWallet instance
|
227
|
+
transport // Transport layer
|
228
|
+
);
|
229
|
+
|
230
|
+
// Handle incoming requests
|
231
|
+
transport.on('message', async (request) => {
|
232
|
+
const response = await wallet.handleRequest(request);
|
233
|
+
// Send response back to dApp
|
234
|
+
});
|
235
|
+
|
236
|
+
// Use with WalletMesh router
|
237
|
+
const routerClient = wallet.asWalletRouterClient();
|
238
|
+
```
|
239
|
+
|
240
|
+
## Error Codes
|
241
|
+
|
242
|
+
Common error codes returned by the library:
|
243
|
+
|
244
|
+
- -32000: Unknown internal error
|
245
|
+
- -32001: User refused transaction
|
246
|
+
- -32002: Wallet not connected
|
247
|
+
- -32003: Contract instance not registered
|
248
|
+
- -32004: Contract class not registered
|
249
|
+
- -32005: Sender not registered
|
250
|
+
- -32006: Invalid response format
|
251
|
+
- -32007: Not connected to any chain
|
252
|
+
- -32008: Chain not supported
|
253
|
+
- -32009: Invalid request format
|
254
|
+
- -32010: Invalid parameters
|
255
|
+
- -32011: Permission denied
|
256
|
+
- -32012: Session not found
|
257
|
+
- -32013: Session expired
|
258
|
+
- -32014: Transaction not found
|
259
|
+
- -32015: Block not found
|
260
|
+
- -32016: Authorization witness not found
|
261
|
+
|
262
|
+
## Example Project
|
263
|
+
|
264
|
+
See the [example project](https://github.com/WalletMesh/walletmesh-packages/tree/main/aztec/example) for a complete implementation using this library.
|