npm package: @generationsoftware/viem-raf-relayer-client
Description: A TypeScript viem client for the RAF Relayer
Author: Generation Software
Latest version: 1.0.0

# Viem RAF Relayer Client

A TypeScript library for interacting with the Ready Aim Fire Relayer server (ERC2771 sponsored transactions). This library provides a simple, object-oriented interface for signing and forwarding meta-transactions.

## Installation

```bash
npm install @generationsoftware/viem-raf-relayer-client
```

## Usage

### Basic Setup

```typescript
import { createPublicClient, createWalletClient, http } from 'viem';
import { arbitrum } from 'viem/chains';
import { RafRelayer } from '@generationsoftware/viem-raf-relayer-client';

// Create a public client for reading blockchain state
const publicClient = createPublicClient({
  chain: arbitrum,
  transport: http('https://your-rpc-url.com')
});

// Create a wallet client for signing transactions
const walletClient = createWalletClient({
  chain: arbitrum,
  transport: http('https://your-rpc-url.com'),
  account: privateKeyToAccount('0x...')
});

// Initialize the forwarder
const forwarder = new RafRelayer(
  '0x...', // forwarder contract address
  publicClient,
  'https://your-relayer.com/forward' // relayer URL
);
```

### Forwarding a Transaction

```typescript
// Forward a transaction through the relayer
const txHash = await forwarder.forward({
  to: '0x...', // target contract address
  data: '0x...', // encoded function call
  value: 0n, // optional: ETH value to send
  gas: 10000000n, // optional: gas limit
  deadline: Math.floor(Date.now() / 1000) + 60 // optional: deadline timestamp
}, walletClient);

console.log('Transaction hash:', txHash);
```

### Manual Signing (Advanced)

If you need more control over the signing process:

```typescript
// Get the current nonce for an address
const nonce = await forwarder.getNonce(walletClient.account.address);

// Create a forward request
const request = {
  from: walletClient.account.address,
  to: '0x...',
  value: 0n,
  gas: 10000000n,
  nonce,
  deadline: Math.floor(Date.now() / 1000) + 60,
  data: '0x...'
};

// Sign the request
const signature = await forwarder.sign(walletClient, request);

// Now you can send the signed request to your relayer manually
```

### Verifying Requests

```typescript
// Verify a signed forward request
const isValid = await forwarder.verify({
  from: '0x...',
  to: '0x...',
  value: 0n,
  gas: 10000000n,
  nonce: 0n,
  deadline: Math.floor(Date.now() / 1000) + 60,
  data: '0x...',
  signature: '0x...'
});

// Get detailed validation information
const validation = await forwarder.validate(signedRequest);
console.log('Is trusted forwarder:', validation.isTrustedForwarder);
console.log('Is active:', validation.active);
console.log('Signer match:', validation.signerMatch);
```

## API Reference

### `new RafRelayer(forwarderAddress, publicClient, relayerUrl)`

Creates a new RafRelayer instance.

- `forwarderAddress`: The address of the ERC2771 forwarder contract
- `publicClient`: A viem PublicClient instance for reading blockchain state
- `relayerUrl`: The URL of your relayer endpoint

### `forwarder.forward(options, walletClient)`

Forwards a transaction through a relayer.

**Options:**
- `to`: Target contract address
- `data`: Encoded function call data
- `value?`: ETH value to send (default: 0n)
- `gas?`: Gas limit (default: 10000000n)
- `deadline?`: Deadline timestamp (default: 60 seconds from now)

**Returns:** Transaction hash

### `forwarder.sign(walletClient, request)`

Signs a forward request.

**Request:**
- `from`: Sender address
- `to`: Target contract address
- `value`: ETH value
- `gas`: Gas limit
- `nonce`: Account nonce from the forwarder
- `deadline`: Deadline timestamp
- `data`: Encoded function call data

**Returns:** Signature

### `forwarder.getNonce(address)`

Gets the current nonce for an address from the forwarder contract.

### `forwarder.verify(signedRequest)`

Verifies a signed forward request.

### `forwarder.validate(signedRequest)`

Gets detailed validation information for a signed request.

## Types

The library exports the following TypeScript types:

- `ForwardRequest`: Basic forward request structure
- `SignedForwardRequest`: Forward request with signature
- `ForwardTransactionOptions`: Options for the `forward()` method
- `RelayerResponse`: Response from relayer
- `EIP712Domain`: EIP-712 domain structure

## License

MIT