@walletmesh/aztec-rpc-wallet v0.3.1

WalletMesh Aztec RPC Wallet Library

@walletmesh/aztec-rpc-wallet provides a type-safe RPC interface for interacting with Aztec wallets. It consists of three main components:

• AztecProvider: Client-side provider for dApps to communicate with Aztec wallets
• AztecChainWallet: Server-side implementation that handles RPC requests using an Aztec wallet instance
• AztecOperationBuilder: Fluent API for chaining multiple RPC method calls

The library is built on @walletmesh/jsonrpc and @walletmesh/router.

Features

• Connect to multiple Aztec chains simultaneously
• Flexible chain ID support (any string with 'aztec:' prefix)
• Type-safe RPC interfaces with comprehensive TypeScript definitions
• Efficient batching of multiple method calls
• Fluent chaining API for bulk operations
• Comprehensive error handling
• Contract artifact caching
• Event handling for wallet state changes
• Serialization support for all Aztec data types
• Support for encrypted and unencrypted events/logs

Installation

npm install @walletmesh/aztec-rpc-wallet

Core RPC Methods

The library supports a comprehensive set of RPC methods:

Chain Operations

• aztec_connect: Connect to Aztec chains
• aztec_getBlock: Get block by number
• aztec_getBlockNumber: Get current block number
• aztec_getProvenBlockNumber: Get proven block number
• aztec_getChainId: Get chain ID
• aztec_getVersion: Get protocol version
• aztec_getNodeInfo: Get node information
• aztec_getPXEInfo: Get PXE information
• aztec_getCurrentBaseFees: Get current base fees

Account Operations

• aztec_getAccount: Get wallet's account address
• aztec_getAddress: Get wallet's Aztec address
• aztec_getCompleteAddress: Get complete address details
• aztec_registerAccount: Register a new account
• aztec_getRegisteredAccounts: Get all registered accounts

Transaction Operations

• aztec_sendTransaction: Send one or more transactions
• aztec_simulateTransaction: Simulate transaction without executing
• aztec_sendTx: Send raw transaction
• aztec_createTxExecutionRequest: Create transaction execution request
• aztec_proveTx: Generate transaction proof
• aztec_getTxEffect: Get transaction effect
• aztec_getTxReceipt: Get transaction receipt

Contract Operations

• aztec_registerContract: Register contract instance
• aztec_registerContractClass: Register contract class
• aztec_getContracts: Get registered contracts
• aztec_getContractInstance: Get contract instance details
• aztec_getContractClass: Get contract class details
• aztec_getContractArtifact: Get contract artifact
• aztec_isContractClassPubliclyRegistered: Check if contract class is publicly registered
• aztec_isContractPubliclyDeployed: Check if contract is publicly deployed
• aztec_isContractInitialized: Check if contract is initialized
• aztec_getPublicStorageAt: Get public storage value

Authorization & Scope Management

• aztec_setScopes: Set authorization scopes
• aztec_getScopes: Get current scopes
• aztec_addAuthWitness: Add authorization witness
• aztec_getAuthWitness: Get authorization witness
• aztec_createAuthWit: Create authorization witness

Notes and Events

• aztec_getIncomingNotes: Get incoming notes
• aztec_addNote: Add note
• aztec_addNullifiedNote: Add nullified note
• aztec_getUnencryptedLogs: Get unencrypted logs
• aztec_getContractClassLogs: Get contract class logs
• aztec_getEncryptedEvents: Get encrypted events
• aztec_getUnencryptedEvents: Get unencrypted events

L1->L2 Bridge Operations

• aztec_isL1ToL2MessageSynced: Check if L1->L2 message is synced
• aztec_getL1ToL2MembershipWitness: Get L1->L2 membership witness

See src/types.ts for complete method definitions and parameters.

Usage Examples

Basic Provider Usage

import { AztecProvider } from '@walletmesh/aztec-rpc-wallet';

// Create provider with transport
const provider = new AztecProvider(transport);

// Connect to chains
await provider.connect(['aztec:testnet', 'aztec:devnet']);

// Get account address
const address = await provider.getAccount('aztec:testnet');

// Send transaction
const txHash = await provider.sendTransaction('aztec:testnet', {
  functionCalls: [{
    contractAddress: "0x1234...",
    functionName: "transfer",
    args: [recipient, amount]
  }]
});

// Register contract
await provider.registerContract('aztec:testnet', {
  instance: contractInstance,
  artifact: contractArtifact // optional if class already registered
});

// Listen for chain connection events
provider.on('chain:connected', ({ chainId }) => {
  console.log(`Connected to chain: ${chainId}`);
});

// Listen for chain disconnection events
provider.on('chain:disconnected', ({ chainId }) => {
  console.log(`Disconnected from chain: ${chainId}`);
});

Chaining API for Bulk Operations

The provider supports a fluent chaining API for executing multiple operations efficiently:

// Multiple reads in single batch
const [account, contracts, blockNumber] = await provider
  .chain('aztec:testnet')
  .call('aztec_getAccount')
  .call('aztec_getContracts')
  .call('aztec_getBlockNumber')
  .execute();

// Contract setup and interaction
const [classId, instanceId, txHash] = await provider
  .chain('aztec:testnet')
  .call('aztec_registerContractClass', { artifact: contractArtifact })
  .call('aztec_registerContract', { 
    instance: contractInstance,
    artifact: contractArtifact
  })
  .call('aztec_sendTransaction', {
    functionCalls: [{
      contractAddress: contractInstance.address,
      functionName: 'initialize',
      args: [param1, param2]
    }]
  })
  .execute();

// Multi-chain operations
const [testnetData, devnetData] = await Promise.all([
  provider
    .chain('aztec:testnet')
    .call('aztec_getAccount')
    .call('aztec_getContracts')
    .execute(),
  provider
    .chain('aztec:devnet')
    .call('aztec_getAccount')
    .call('aztec_getContracts')
    .execute()
]);

Error Handling

The library provides comprehensive error handling through AztecWalletError:

try {
  await provider.sendTransaction('aztec:testnet', {
    functionCalls: [{
      contractAddress: "0x1234...",
      functionName: "transfer",
      args: [recipient, amount]
    }]
  });
} catch (error) {
  if (error instanceof AztecWalletError) {
    switch (error.code) {
      case -32001: // User refused
        console.log('Transaction rejected by user');
        break;
      case -32002: // Wallet not connected
        console.log('Please connect wallet first');
        break;
      default:
        console.error('RPC error:', error.message);
    }
  }
}

Implementing a Wallet

Server-side implementation using AztecWallet:

import { AztecChainWallet } from '@walletmesh/aztec-rpc-wallet';
import type { PXE, AccountWallet } from '@aztec/aztec.js';

// Create wallet instance
const wallet = new AztecChainWallet(
  pxe,           // PXE instance
  accountWallet, // Aztec AccountWallet instance
  transport     // Transport layer
);

// Handle incoming requests
transport.on('message', async (request) => {
  const response = await wallet.handleRequest(request);
  // Send response back to dApp
});

// Use with WalletMesh router
const routerClient = wallet.asWalletRouterClient();

Error Codes

Common error codes returned by the library:

• -32000: Unknown internal error
• -32001: User refused transaction
• -32002: Wallet not connected
• -32003: Contract instance not registered
• -32004: Contract class not registered
• -32005: Sender not registered
• -32006: Invalid response format
• -32007: Not connected to any chain
• -32008: Chain not supported
• -32009: Invalid request format
• -32010: Invalid parameters
• -32011: Permission denied
• -32012: Session not found
• -32013: Session expired
• -32014: Transaction not found
• -32015: Block not found
• -32016: Authorization witness not found

Example Project

See the example project for a complete implementation using this library.