Credenza3 EVM Wallet

A TypeScript/JavaScript library that provides an EIP-1193 compatible Ethereum wallet interface for the Credenza3 platform. This library enables seamless integration with popular Ethereum libraries like ethers.js.

Features

• ✅ EIP-1193 Compatible - Works with ethers.js and other standard Ethereum libraries
• 🔐 Secure Authentication - Token-based authentication with Credenza3 API
• 📝 Message Signing - Support for personal_sign and typed data signing (EIP-712)
• 💸 Transaction Management - Sign and send Ethereum transactions
• 🔄 Flexible Configuration - Dynamic RPC and API URL configuration
• 🛡️ Error Handling - Custom error types with detailed error information

Installation

npm install @credenza3/evm-wallet

yarn add @credenza3/evm-wallet

pnpm add @credenza3/evm-wallet

Quick Start

import { Credenza3Wallet } from '@credenza3/evm-wallet';

// Initialize the wallet
const wallet = new Credenza3Wallet({
  rpcUrl: 'https://eth-mainnet.g.alchemy.com/v2/your-api-key',
  apiUrl: 'https://api.credenza3.com'
});

// Set access token (required for signing operations)
wallet.setAccessToken('your-access-token');

// Use with ethers.js
import { BrowserProvider } from 'ethers';
const provider = new BrowserProvider(wallet);
const signer = await provider.getSigner();

Usage

Basic Configuration

import { Credenza3Wallet } from '@credenza3/evm-wallet';

const wallet = new Credenza3Wallet({
  rpcUrl: 'https://mainnet.infura.io/v3/YOUR_INFURA_KEY',
  apiUrl: 'https://api.credenza3.com'
});

// Set authentication token
wallet.setAccessToken('your-jwt-token');

Making Direct RPC Calls

The wallet implements the EIP-1193 request method for direct JSON-RPC calls:

// Get accounts
const accounts = await wallet.request({ 
  method: 'eth_accounts' 
});

// Get balance
const balance = await wallet.request({
  method: 'eth_getBalance',
  params: ['0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb']
});

// Get block number
const blockNumber = await wallet.request({
  method: 'eth_blockNumber'
});

Signing Messages

// Personal sign
const signature = await wallet.request({
  method: 'personal_sign',
  params: ['Hello, Credenza3!', '0xYourAddress']
});

// Typed data signing (EIP-712)
const typedData = {
  domain: {
    name: 'MyDApp',
    version: '1',
    chainId: 1,
    verifyingContract: '0x...'
  },
  types: {
    Person: [
      { name: 'name', type: 'string' },
      { name: 'wallet', type: 'address' }
    ]
  },
  primaryType: 'Person',
  message: {
    name: 'Alice',
    wallet: '0x...'
  }
};

const typedSignature = await wallet.request({
  method: 'eth_signTypedData_v4',
  params: ['0xYourAddress', JSON.stringify(typedData)]
});

Transaction Operations

// Sign a transaction
const signedTx = await wallet.request({
  method: 'eth_signTransaction',
  params: [{
    from: '0xYourAddress',
    to: '0xRecipientAddress',
    value: '0x1000000000000000', // 0.001 ETH in wei
    gas: '0x5208',
    gasPrice: '0x...'
  }]
});

// Send a transaction (signs and broadcasts)
const txHash = await wallet.request({
  method: 'eth_sendTransaction',
  params: [{
    from: '0xYourAddress',
    to: '0xRecipientAddress',
    value: '0x1000000000000000'
  }]
});

Using with Ethers.js

The wallet is fully compatible with ethers.js v6:

import { BrowserProvider } from 'ethers';

const provider = new BrowserProvider(wallet);
const signer = await provider.getSigner();

// Get address
const address = await signer.getAddress();

// Sign message
const signature = await signer.signMessage('Hello World');

// Send transaction
const tx = await signer.sendTransaction({
  to: '0xRecipientAddress',
  value: ethers.parseEther('0.001')
});
await tx.wait();

// Sign typed data
const signature = await signer.signTypedData(domain, types, message);

Dynamic Configuration

Update configuration at runtime:

// Update RPC URL (e.g., switch networks)
wallet.setRpcUrl('https://polygon-rpc.com');

// Update API URL
wallet.setApiUrl('https://api.credenza3.com');

// Update access token (e.g., after re-authentication)
wallet.setAccessToken('new-access-token');

API Reference

Constructor

new Credenza3Wallet(options)

Creates a new wallet instance.

Parameters:

• options.rpcUrl (string): Ethereum JSON-RPC endpoint URL
• options.apiUrl (string): Credenza3 API base URL

Example:

const wallet = new Credenza3Wallet({
  rpcUrl: 'https://mainnet.infura.io/v3/YOUR_KEY',
  apiUrl: 'https://api.credenza3.com'
});

Methods

request(options)

Implements EIP-1193 request method for making JSON-RPC calls.

Parameters:

• options.method (string): JSON-RPC method name
• options.params (array, optional): Method parameters

Returns: Promise

Throws: Credenza3WalletError

setAccessToken(token)

Sets the authentication token for API requests.

Parameters:

• token (string): JWT access token

setRpcUrl(url)

Updates the RPC endpoint URL.

Parameters:

• url (string): New RPC URL

setApiUrl(url)

Updates the Credenza3 API URL.

Parameters:

• url (string): New API base URL

Supported Methods

Methods Routed to Credenza3 API

These methods require authentication and are handled by the Credenza3 backend:

• eth_accounts - Get wallet accounts
• eth_sign - Sign data (deprecated, may throw)
• personal_sign - Sign messages
• eth_signTypedData - Sign typed data (v1)
• eth_signTypedData_v3 - Sign typed data (v3)
• eth_signTypedData_v4 - Sign typed data (v4, recommended)
• eth_signTransaction - Sign transactions
• eth_sendTransaction - Sign and send transactions

Methods Routed to RPC Provider

All other standard Ethereum JSON-RPC methods are forwarded to your configured RPC endpoint:

• eth_blockNumber
• eth_getBalance
• eth_getTransactionCount
• eth_getTransactionReceipt
• eth_call
• eth_estimateGas
• And more...

Error Handling

The library provides a custom error class with detailed error information:

import { Credenza3WalletError } from '@credenza3/evm-wallet';

try {
  const accounts = await wallet.request({ method: 'eth_accounts' });
} catch (error) {
  if (error instanceof Credenza3WalletError) {
    console.error('Error code:', error.code);
    console.error('Error message:', error.message);
    console.error('Error data:', error.data);
  }
}

Error Codes

• 4100 - Unauthorized (no access token)
• 4000 - Internal error (HTTP request failed)
• Other codes - JSON-RPC error codes from the provider

TypeScript Support

The library is written in TypeScript and includes full type definitions:

import { 
  Credenza3Wallet,
  Credenza3WalletError,
  TCredenza3WalletOptions 
} from '@credenza3/evm-wallet';

const options: TCredenza3WalletOptions = {
  rpcUrl: 'https://...',
  apiUrl: 'https://...'
};

const wallet = new Credenza3Wallet(options);

Security Best Practices

1. Never hardcode access tokens - Load them from environment variables or secure storage
2. Use HTTPS endpoints - Always use secure connections for RPC and API URLs
3. Rotate tokens regularly - Implement token refresh mechanisms
4. Handle errors gracefully - Don't expose sensitive error details to end users
5. Validate user input - Always validate addresses and transaction parameters

Examples

Complete Integration Example

import { Credenza3Wallet } from '@credenza3/evm-wallet';
import { BrowserProvider, parseEther } from 'ethers';

async function main() {
  // Initialize wallet
  const wallet = new Credenza3Wallet({
    rpcUrl: process.env.RPC_URL!,
    apiUrl: process.env.API_URL!
  });
  
  // Authenticate
  wallet.setAccessToken(process.env.ACCESS_TOKEN!);
  
  // Setup provider
  const provider = new BrowserProvider(wallet);
  const signer = await provider.getSigner();
  
  // Get account info
  const address = await signer.getAddress();
  const balance = await provider.getBalance(address);
  
  console.log('Address:', address);
  console.log('Balance:', balance.toString());
  
  // Send transaction
  const tx = await signer.sendTransaction({
    to: '0xRecipientAddress',
    value: parseEther('0.001')
  });
  
  console.log('Transaction hash:', tx.hash);
  await tx.wait();
  console.log('Transaction confirmed!');
}

main().catch(console.error);

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Repository

https://github.com/credenza-web3/evm-wallet

License

See the LICENSE file in the repository for license information.

Support

For issues, questions, or contributions, please visit the GitHub repository.