@arbius/aa-wallet/README.md

A secure and flexible Account Abstraction wallet implementation for Arbitrum One chain applications.

# AA Wallet

A secure and flexible Account Abstraction wallet implementation for Arbitrum One chain applications, specifically designed for the Arbius ecosystem.

## Installation

```bash
npm install @arbius/aa-wallet
```

## Ethers v5 Compatibility

If you're using ethers v5, you'll need to patch the ethers object to ensure compatibility with the library's v6-style API. Here's how to do it:

```typescript
import { ethers } from 'ethers';

// Patch the ethers object for v5 compatibility with v6-style API
const ethersPatched = {
  ...ethers,
  formatEther: ethers.utils.formatEther,
  formatUnits: ethers.utils.formatUnits,
  parseEther: ethers.utils.parseEther,
  parseUnits: ethers.utils.parseUnits,
  // Add any other utils your library needs
};

// Now use ethersPatched instead of ethers in all library calls
const balances = await getDeterministicWalletBalances(ethersPatched, wallet);
```

## Features

- Create deterministic wallets derived from a user's main wallet
- Deposit ETH and ERC20 tokens to the deterministic wallet
- Withdraw ETH and ERC20 tokens from the deterministic wallet
- Send contract transactions using the deterministic wallet
- Get ETH and AIUS token balances
- Automatic gas estimation and management
- TypeScript support
- Optimized for Arbitrum One chain

## Usage

### Initialize a Deterministic Wallet

```typescript
import { ethers } from 'ethers';
import { initDeterministicWallet } from '@arbius/aa-wallet';

// Get the user's signer from their wallet
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

// Initialize the deterministic wallet
const wallet = await initDeterministicWallet(
  ethers,
  signer.address,
  async (message: string) => signer.signMessage(message),
  provider
);
```

### Get Wallet Balances

```typescript
import { getDeterministicWalletBalances } from '@arbius/aa-wallet';

// Get both ETH and AIUS balances
const balances = await getDeterministicWalletBalances(ethers, wallet);
console.log('ETH Balance:', balances.eth);
console.log('AIUS Balance:', balances.aius);
```

### Get Deposit Address

```typescript
import { getDeterministicWalletAddressForDeposit } from '@arbius/aa-wallet';

const depositAddress = await getDeterministicWalletAddressForDeposit(
  ethers,
  signer.address,
  async (message: string) => signer.signMessage(message),
  provider
);
```

### Withdraw Funds

```typescript
import { withdrawFromDeterministicWallet } from '@arbius/aa-wallet';

// Withdraw ETH
const txHash = await withdrawFromDeterministicWallet(
  ethers,
  wallet,
  recipientAddress,
  {
    amount: '0.1', // Optional: specific amount to withdraw
    token: 'ETH'
  }
);

// Withdraw AIUS tokens
const txHash = await withdrawFromDeterministicWallet(
  ethers,
  wallet,
  recipientAddress,
  {
    amount: '100', // Optional: specific amount to withdraw
    token: 'AIUS'
  }
);
```

### Send Contract Transactions

```typescript
import { sendContractTransaction } from '@arbius/aa-wallet';

// Create contract interface
const contractInterface = new ethers.Interface(contractABI);

// Encode function data
const data = contractInterface.encodeFunctionData(
  'functionName',
  [param1, param2]
);

// Send transaction
const txHash = await sendContractTransaction(
  ethers,
  wallet,
  contractAddress,
  data,
  '0' // Optional: ETH value to send
);
```

## API Reference

### `initDeterministicWallet`

Creates or retrieves a cached deterministic wallet.

```typescript
function initDeterministicWallet(
  appEthers: typeof ethers,
  ownerAddress: string,
  signMessage: (message: string) => Promise<string>,
  provider: ethers.BrowserProvider
): Promise<ethers.Wallet>
```

### `getDeterministicWalletBalances`

Gets the ETH and AIUS token balances of the deterministic wallet.

```typescript
function getDeterministicWalletBalances(
  appEthers: typeof ethers,
  wallet: ethers.Wallet
): Promise<{ eth: string; aius: string }>
```

### `getDeterministicWalletAddressForDeposit`

Gets the address of the deterministic wallet for deposit purposes.

```typescript
function getDeterministicWalletAddressForDeposit(
  appEthers: typeof ethers,
  ownerAddress: string,
  signMessage: (message: string) => Promise<string>,
  provider: ethers.BrowserProvider
): Promise<string>
```

### `withdrawFromDeterministicWallet`

Withdraws funds from the deterministic wallet.

```typescript
function withdrawFromDeterministicWallet(
  appEthers: typeof ethers,
  wallet: ethers.Wallet,
  recipientAddress: string,
  options: {
    amount?: string;
    token: 'ETH' | 'AIUS';
  }
): Promise<string | null>
```

### `sendContractTransaction`

Sends a transaction to a contract using the deterministic wallet.

```typescript
function sendContractTransaction(
  appEthers: typeof ethers,
  wallet: ethers.Wallet,
  to: string,
  data: string,
  value: string = '0'
): Promise<string | null>
```

## License

MIT