@abstraxn/relayer/Readme.md

Abstraxn Relayer package for handling gas-less transactions, facilitating smart contract interactions, and relaying user transactions efficiently.

# Abstraxn Relayer SDK

## Overview

The Abstraxn Relayer package is designed for handling gas-less transactions, facilitating smart contract interactions, and efficiently relaying user transactions on the Ethereum blockchain. Now with **real-time WebSocket notifications** for instant transaction status updates!

## Installation

Using `npm` package manager:

```bash
npm install @abstraxn/relayer
```

Or using `yarn` package manager:

```bash
yarn add @abstraxn/relayer
```

## Usage

```typescript
import { Relayer } from "@abstraxn/relayer";
import { ChainId } from "@abstraxn/core-types";

const relayerConfig = {
  relayerUrl: "https://your-relayer-url.com",
  chainId: ChainId.MAINNET,
  signer: yourSignerInstance,
  provider: yourProviderInstance,
  webSocket: {
    enabled: true,        // Enable WebSocket real-time updates
    autoConnect: true,    // Auto-connect on initialization
    reconnection: true,   // Auto-reconnect on disconnection
  },
};

const relayer = new Relayer(relayerConfig);

// Example: Building a relayer transaction
const buildTxParams = {
  contractAddress: "0xYourContractAddress",
  abi: yourContractAbi,
  method: "yourMethodName",
  args: ["arg1", "arg2"],
};

// Build and send transaction with real-time updates
relayer.buildRelayerTx(buildTxParams).then(async (txData) => {
  console.log("Build Relayer Transaction Response: ", txData);
  
  // Send with real-time WebSocket notifications
  const response = await relayer.sendRelayerTxWithRealTimeUpdates({
    ...txData,
    enableRealTimeUpdates: true,
    webSocketEvents: {
      onTransactionUpdate: (update) => {
        console.log(`Transaction ${update.txId} status: ${update.status}`);
        if (update.status === 'confirmed') {
          console.log('🎉 Transaction confirmed!', update.blockNumber);
        }
      },
      onError: (error) => {
        console.error('WebSocket error:', error);
      },
    },
  });
  
  console.log("Transaction ID:", response.transactionId);
});
```

## API

### Core Methods

- **buildRelayerTx(params: BuildRelayerTxParams)**
  - Builds a transaction to be sent to the relayer.
  
- **buildRelayerTxEIP712(params: BuildRelayerTxParams)**
  - Builds a transaction using EIP-712 signing standard.

- **sendRelayerTx(params: SendRelayerTxParams)**
  - Sends a transaction to the relayer for processing.

- **sendSafeRelayerTx(params: SendSafeRelayerTxParams)**
  - Sends a safe wallet transaction to the relayer for processing.

- **getRelayerTxStatus(transactionId: string)**
  - Retrieves the status of a relayer transaction.

### 🚀 WebSocket Methods (New!)

- **sendRelayerTxWithRealTimeUpdates(params: SendRelayerTxWithWebSocketParams)**
  - Sends a transaction and automatically subscribes to real-time status updates.

- **sendSafeRelayerTxWithRealTimeUpdates(params: SendSafeRelayerTxWithWebSocketParams)**
  - Sends a safe wallet transaction and automatically subscribes to real-time status updates.

- **subscribeToTransaction(transactionId: string, events?: RelayerWebSocketEvents)**
  - Subscribe to real-time updates for a specific transaction.

- **unsubscribeFromTransaction(transactionId: string)**
  - Unsubscribe from transaction updates.

- **connectWebSocket()** / **disconnectWebSocket()**
  - Manual WebSocket connection control.

- **isWebSocketConnected(): boolean**
  - Check WebSocket connection status.

## 🔄 Real-time Features

### WebSocket Events

```typescript
interface RelayerWebSocketEvents {
  onTransactionUpdate?: (update: TransactionStatusUpdate) => void;
  onTransactionCreated?: (event: TransactionCreatedEvent) => void;
  onConnect?: () => void;
  onDisconnect?: () => void;
  onError?: (error: Error) => void;
}
```

### Transaction Status Flow

1. **initiated** → Transaction created and submitted to relayer
2. **pending** → Transaction submitted to blockchain
3. **confirmed** → Transaction successfully mined ✅
4. **failed** → Transaction failed ❌
5. **rejected** → Transaction rejected by network ❌

## Examples

### Basic Real-time Tracking

```typescript
// Subscribe to existing transaction
await relayer.subscribeToTransaction(txId, {
  onTransactionUpdate: (update) => {
    console.log(`Status: ${update.status}`);
    if (update.status === 'confirmed') {
      console.log(`Confirmed in block ${update.blockNumber}`);
    }
  },
});
```

### Promise-based Tracking

```typescript
const txData = await relayer.buildRelayerTx(params);
const response = await relayer.sendRelayerTx(txData);

const finalStatus = await new Promise((resolve, reject) => {
  relayer.subscribeToTransaction(response.transactionId, {
    onTransactionUpdate: (update) => {
      if (update.status === 'confirmed') resolve(update);
      if (update.status === 'failed') reject(new Error('Failed'));
    },
  });
});
```

### Multiple Transactions

```typescript
const transactions = ['tx1', 'tx2', 'tx3'];

transactions.forEach(txId => {
  relayer.subscribeToTransaction(txId, {
    onTransactionUpdate: (update) => {
      console.log(`[${txId}] Status: ${update.status}`);
    },
  });
});
```

## Migration Guide

### Before (Polling)
```typescript
const response = await relayer.sendRelayerTx(txData);
// Manual polling required
setInterval(async () => {
  const status = await relayer.getRelayerTxStatus(response.transactionId);
  console.log(status);
}, 2000);
```

### After (Real-time)
```typescript
const response = await relayer.sendRelayerTxWithRealTimeUpdates({
  ...txData,
  enableRealTimeUpdates: true,
  webSocketEvents: {
    onTransactionUpdate: (update) => console.log(update.status),
  },
});
// Instant updates! 🚀
```

## Benefits

- ✅ **Instant Updates**: No more 2-5 second polling delays
- ✅ **Better Performance**: Reduced server load and bandwidth
- ✅ **Improved UX**: Real-time feedback for users
- ✅ **Battery Efficient**: No constant background requests
- ✅ **Backward Compatible**: Existing code still works
- ✅ **Auto Fallback**: Falls back to polling if WebSocket fails

For detailed examples, see [WEBSOCKET_EXAMPLES.md](./WEBSOCKET_EXAMPLES.md).