@abstraxn/relayer

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:

npm install @abstraxn/relayer

Or using yarn package manager:

yarn add @abstraxn/relayer

Usage

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

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

Transaction Status Flow

• initiated → Transaction created and submitted to relayer
• pending → Transaction submitted to blockchain
• confirmed → Transaction successfully mined ✅
• failed → Transaction failed ❌
• rejected → Transaction rejected by network ❌

Examples

Basic Real-time Tracking

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

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

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

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

Migration Guide

Before (Polling)

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)

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.