@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.
Files changed (76) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/dist/.tsbuildinfo +1 -1
  3. package/dist/aztecRemoteWallet.d.ts +4 -8
  4. package/dist/aztecRemoteWallet.d.ts.map +1 -1
  5. package/dist/aztecRemoteWallet.js +5 -29
  6. package/dist/contractArtifactCache.d.ts.map +1 -1
  7. package/dist/contractArtifactCache.js +20 -9
  8. package/dist/handlers/aztecAccountWallet.d.ts.map +1 -1
  9. package/dist/handlers/aztecAccountWallet.js +11 -44
  10. package/dist/serializers/account.d.ts +16 -16
  11. package/dist/serializers/account.d.ts.map +1 -1
  12. package/dist/serializers/account.js +43 -43
  13. package/dist/serializers/contract.d.ts +22 -76
  14. package/dist/serializers/contract.d.ts.map +1 -1
  15. package/dist/serializers/contract.js +68 -120
  16. package/dist/serializers/index.d.ts +0 -4
  17. package/dist/serializers/index.d.ts.map +1 -1
  18. package/dist/serializers/index.js +15 -20
  19. package/dist/serializers/log.d.ts +16 -16
  20. package/dist/serializers/log.d.ts.map +1 -1
  21. package/dist/serializers/log.js +43 -43
  22. package/dist/serializers/note.d.ts +12 -12
  23. package/dist/serializers/note.d.ts.map +1 -1
  24. package/dist/serializers/note.js +32 -32
  25. package/dist/serializers/transaction.d.ts +25 -26
  26. package/dist/serializers/transaction.d.ts.map +1 -1
  27. package/dist/serializers/transaction.js +92 -44
  28. package/dist/types.d.ts +7 -30
  29. package/dist/types.d.ts.map +1 -1
  30. package/dist/types.js +1 -1
  31. package/docs/README.md +264 -0
  32. package/docs/classes/AztecChainProvider.md +553 -0
  33. package/docs/classes/AztecChainWallet.md +409 -0
  34. package/docs/classes/AztecProvider.md +1112 -0
  35. package/docs/classes/AztecWalletError.md +213 -0
  36. package/docs/classes/ContractArtifactCache.md +81 -0
  37. package/docs/globals.md +34 -0
  38. package/docs/interfaces/AztecWalletBaseMethodMap.md +135 -0
  39. package/docs/interfaces/AztecWalletEventMap.md +17 -0
  40. package/docs/interfaces/AztecWalletMethodMap.md +1012 -0
  41. package/docs/type-aliases/AztecChainId.md +11 -0
  42. package/docs/type-aliases/AztecChainWalletMiddleware.md +13 -0
  43. package/docs/type-aliases/AztecWalletContext.md +29 -0
  44. package/docs/type-aliases/AztecWalletMethodHandler.md +37 -0
  45. package/docs/type-aliases/AztecWalletMiddleware.md +13 -0
  46. package/docs/type-aliases/AztecWalletRouterClient.md +13 -0
  47. package/docs/type-aliases/TransactionFunctionCall.md +33 -0
  48. package/docs/type-aliases/TransactionParams.md +27 -0
  49. package/docs/variables/AztecWalletErrorMap.md +13 -0
  50. package/package.json +9 -9
  51. package/src/aztecRemoteWallet.test.ts +22 -61
  52. package/src/aztecRemoteWallet.ts +8 -35
  53. package/src/chainProvider.test.ts +117 -38
  54. package/src/contractArtifactCache.test.ts +28 -45
  55. package/src/contractArtifactCache.ts +20 -10
  56. package/src/handlers/aztecAccountWallet.test.ts +12 -86
  57. package/src/handlers/aztecAccountWallet.ts +19 -77
  58. package/src/provider.test.ts +0 -2
  59. package/src/serializers/account.test.ts +19 -20
  60. package/src/serializers/account.ts +52 -52
  61. package/src/serializers/contract.test.ts +4 -140
  62. package/src/serializers/contract.ts +93 -166
  63. package/src/serializers/index.test.ts +30 -28
  64. package/src/serializers/index.ts +15 -21
  65. package/src/serializers/log.test.ts +42 -48
  66. package/src/serializers/log.ts +54 -54
  67. package/src/serializers/note.test.ts +43 -16
  68. package/src/serializers/note.ts +39 -39
  69. package/src/serializers/transaction.test.ts +48 -41
  70. package/src/serializers/transaction.ts +146 -58
  71. package/src/types.ts +7 -7
  72. package/src/wallet.test.ts +3 -3
  73. package/dist/serializers/transaction-utils.d.ts +0 -51
  74. package/dist/serializers/transaction-utils.d.ts.map +0 -1
  75. package/dist/serializers/transaction-utils.js +0 -103
  76. 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.