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

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

Usage

Basic Setup

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

// 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:

// 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

// 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