Documentation

RelayXplore is a relayer system that enables DApps to offer gasless transactions for their users. It introduces a provider funding model, allowing DApp developers to deposit/withdraw funds into a relayer account to pay for gas and access the service through a subscription-based SDK authenticated via API keys.

How RelayXplore Works

Traditional blockchain transactions require end-users to pay gas fees, which can be a significant barrier to adoption, especially for new users. RelayXplore solves this problem by allowing DApp developers to cover these costs on behalf of their users.

Key Benefits

• Improve user experience by removing the gas fee barrier
• Simplify onboarding for new users unfamiliar with blockchain
• Maintain control over transaction costs through the provider funding model
• Easy integration with our SDK
• Support for multiple blockchain networks
• Detailed analytics and monitoring tools

Supported Networks

This quick start guide will help you integrate RelayXplore into your DApp in just a few minutes. Follow these steps to enable gasless transactions for your users.

1. Create an Account

First, you'll need to create an account on the RelayXplore platform. Visit dashboard.relayxplore.com to sign up.

2. Generate an API Key

After creating an account, generate an API key from the dashboard. This key will be used to authenticate your requests to the RelayXplore API.

3. Install the SDK

npm install @relayxplore/sdk

4. Initialize the SDK

import { RelayXplore } from '@relayxplore/sdk';

// Initialize the SDK with your API key
const relay = new RelayXplore({
  apiKey: 'your-api-key',
  network: 'mainnet', // or 'polygon', 'arbitrum', 'optimism', 'base'
});

5. Fund Your Account

Before sending transactions, you'll need to fund your RelayXplore account. You can do this from the dashboard by depositing ETH or other native tokens depending on the network.

6. Send a Gasless Transaction

// Example: Send a gasless transaction
const transaction = {
  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
  data: '0x...',  // Contract method call data
  value: '0',     // Amount of ETH to send
};

// Send the transaction through the relayer
const result = await relay.sendTransaction(transaction);
console.log('Transaction hash:', result.hash);

// Server-side code
const relay = new RelayXplore({
  apiKey: process.env.RELAYXPLORE_API_KEY,
  network: 'mainnet',
});

Requirements

• Node.js v14 or higher
• An active RelayXplore account with API keys
• Funded relayer account

Installation Methods

npm install @relayxplore/sdk

Configuration

// Configure the SDK with your project settings
import { RelayXplore } from '@relayxplore/sdk';

const relay = new RelayXplore({
  apiKey: process.env.RELAYXPLORE_API_KEY,
  network: 'mainnet',
  timeout: 30000, // Optional: request timeout in ms
  maxRetries: 3,  // Optional: number of retry attempts
});

Configuration Options

Framework-Specific Setup

API Keys

RelayXplore uses API keys to authenticate requests. You can generate API keys from your dashboard after creating an account.

Securing Your API Keys

Always keep your API keys secure and never expose them in client-side code. Use environment variables to store your API keys and access them in your server-side code.

// Server-side code (e.g., Next.js API route)
import { RelayXplore } from '@relayxplore/sdk';

export async function POST(req) {
  const relay = new RelayXplore({
    apiKey: process.env.RELAYXPLORE_API_KEY,
    network: 'mainnet',
  });
  
  // Process the request
  // ...
}

API Key Rotation

It's a good practice to rotate your API keys periodically. You can generate new API keys from your dashboard and update your applications accordingly. Make sure to revoke old keys after transitioning to new ones.

Authentication Flow

1. Generate an API key from the RelayXplore dashboard
2. Store the API key securely in your server environment
3. Initialize the SDK with your API key
4. The SDK will automatically include your API key in all requests to the RelayXplore API

Before you can start using RelayXplore to send gasless transactions, you need to fund your account with the native token of the blockchain network you're using (e.g., ETH for Ethereum, MATIC for Polygon).

Funding Methods

Managing Your Balance

You can monitor your account balance and transaction history in the RelayXplore dashboard. The dashboard provides detailed information about your deposits, withdrawals, and gas usage.

Withdrawing Funds

You can withdraw funds from your RelayXplore account at any time. Withdrawals are processed within 24 hours and sent to your specified wallet address.

// Check your account balance programmatically
const balance = await relay.getAccountBalance();
console.log('Account balance:', balance);

// You can also check the minimum required balance
const minBalance = await relay.getMinimumRequiredBalance();
console.log('Minimum required balance:', minBalance);

// If your balance is low, you might want to notify your team
if (parseFloat(balance) < parseFloat(minBalance) * 2) {
  console.warn('Account balance is running low!');
}

How Gasless Transactions Work

Gasless transactions allow users to interact with your DApp without needing to pay for gas. Instead, the DApp provider (you) covers the gas costs through the RelayXplore relayer system.

Implementation Steps

1. Initialize the RelayXplore SDK with your API key
2. Create a transaction object with the necessary parameters
3. Send the transaction through the relayer
4. Handle the response and provide feedback to the user

Example Implementation

import { RelayXplore } from '@relayxplore/sdk';

// Initialize the SDK
const relay = new RelayXplore({
  apiKey: process.env.RELAYXPLORE_API_KEY,
  network: 'mainnet',
});

// Function to send a gasless transaction
async function sendGaslessTransaction(to, data, value = '0') {
  try {
    // Create the transaction object
    const transaction = {
      to,
      data,
      value,
    };
    
    // Send the transaction through the relayer
    const result = await relay.sendTransaction(transaction);
    
    // Return the transaction hash
    return {
      success: true,
      hash: result.hash,
    };
  } catch (error) {
    console.error('Error sending gasless transaction:', error);
    return {
      success: false,
      error: error.message,
    };
  }
}

Contract Interactions

You can use RelayXplore to interact with smart contracts on behalf of your users. Here's an example of how to call a contract method:

import { RelayXplore } from '@relayxplore/sdk';
import { ethers } from 'ethers';

// Initialize the SDK
const relay = new RelayXplore({
  apiKey: process.env.RELAYXPLORE_API_KEY,
  network: 'mainnet',
});

// Function to interact with a contract
async function callContractMethod(contractAddress, abi, methodName, methodArgs) {
  try {
    // Create a contract interface
    const iface = new ethers.utils.Interface(abi);
    
    // Encode the function call
    const data = iface.encodeFunctionData(methodName, methodArgs);
    
    // Create the transaction object
    const transaction = {
      to: contractAddress,
      data,
      value: '0',
    };
    
    // Send the transaction through the relayer
    const result = await relay.sendTransaction(transaction);
    
    return {
      success: true,
      hash: result.hash,
    };
  } catch (error) {
    console.error('Error calling contract method:', error);
    return {
      success: false,
      error: error.message,
    };
  }
}

// Example usage
const contractAddress = '0x123...';
const abi = [...]; // Contract ABI
const methodName = 'transfer';
const methodArgs = ['0x456...', ethers.utils.parseEther('1.0')];

const result = await callContractMethod(contractAddress, abi, methodName, methodArgs);
console.log(result);

Advanced Features

// Batch multiple transactions
const batch = [
  {
    to: '0x123...',
    data: '0x...',
    value: '0',
  },
  {
    to: '0x456...',
    data: '0x...',
    value: '0',
  },
];

const result = await relay.sendBatchTransaction(batch);
console.log('Batch transaction hash:', result.hash);

// Schedule a transaction
const transaction = {
  to: '0x123...',
  data: '0x...',
  value: '0',
  executeAt: new Date(Date.now() + 3600000), // 1 hour from now
};

const result = await relay.scheduleTransaction(transaction);
console.log('Scheduled transaction ID:', result.id);

API keys are used to authenticate your requests to the RelayXplore API. This section covers how to create, manage, and secure your API keys.

Creating API Keys

You can create API keys from the RelayXplore dashboard. Each key can be configured with specific permissions and rate limits.

1. Log in to your RelayXplore dashboard
2. Navigate to the "API Keys" section
3. Click on "Generate New API Key"
4. Provide a name for your key and select the environment (development, testing, production)
5. Configure permissions and rate limits as needed
6. Click "Create" to generate the key

API Key Permissions

You can configure your API keys with specific permissions to limit what actions they can perform. This is useful for creating keys with the minimum necessary permissions for different parts of your application.

Revoking API Keys

If an API key is compromised or no longer needed, you should revoke it immediately. Revoked keys cannot be used to authenticate requests.

1. Log in to your RelayXplore dashboard
2. Navigate to the "API Keys" section
3. Find the key you want to revoke
4. Click on the "Revoke" button
5. Confirm the action

API Key Best Practices

• Use different API keys for different environments (development, testing, production)
• Limit API key permissions to only what is necessary
• Store API keys securely using environment variables or a secrets manager
• Rotate API keys periodically to reduce the risk of compromise
• Monitor API key usage to detect unusual activity
• Revoke unused or compromised API keys immediately

Programmatic API Key Management

You can also manage your API keys programmatically using the RelayXplore Management API. This is useful for automating key rotation and management.

// Example: Create a new API key programmatically
const response = await fetch('https://api.relayxplore.com/v1/api-keys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ADMIN_API_KEY',
  },
  body: JSON.stringify({
    name: 'Production API Key',
    environment: 'production',
    permissions: ['read', 'write'],
  }),
});

const data = await response.json();
console.log('New API key:', data.key);

RelayXplore provides comprehensive monitoring tools to help you track your usage, analyze transaction patterns, and optimize your costs.

Dashboard Analytics

The RelayXplore dashboard provides real-time analytics on your account usage, including:

• Transaction volume and success rates
• Gas usage and costs
• API key usage and rate limit consumption
• Account balance and funding history

Programmatic Monitoring

You can also monitor your usage programmatically using the RelayXplore API. This allows you to integrate RelayXplore metrics into your own monitoring systems.

// Get transaction history
const transactions = await relay.getTransactions({
  limit: 10,
  offset: 0,
  status: 'success', // 'success', 'pending', 'failed'
});

console.log('Recent transactions:', transactions);

// Get usage metrics
const metrics = await relay.getUsageMetrics({
  startDate: '2023-04-01',
  endDate: '2023-04-30',
});

console.log('Monthly usage metrics:', metrics);

Alerts and Notifications

Set up alerts to be notified of important events, such as:

• Low account balance
• High transaction failure rates
• Unusual transaction patterns
• API rate limit warnings

Alerts can be delivered via email, webhook, or Slack integration.

Transaction Explorer

The transaction explorer in the RelayXplore dashboard allows you to search, filter, and analyze your transactions in detail. You can:

• View transaction details, including gas used, status, and timestamps
• Filter transactions by status, date, contract, or user
• Export transaction data for further analysis
• View transaction receipts and event logs

This section covers the core concepts and architecture of RelayXplore, helping you understand how the system works under the hood.

Meta-Transactions

RelayXplore uses meta-transactions to enable gasless transactions. Meta-transactions separate the action of signing a transaction from the action of submitting it to the blockchain.

Relayer Architecture

The RelayXplore relayer system consists of several components working together to provide a reliable and secure service.

Account Model

RelayXplore uses a provider funding model, where DApp developers fund their accounts to cover gas costs for their users.

Security Model

RelayXplore is designed with security as a top priority. The system includes multiple layers of protection to ensure the safety of your funds and transactions.

Gas Management

RelayXplore includes sophisticated gas management features to optimize transaction costs and ensure timely confirmation.

• Dynamic Gas Pricing: Automatically adjusts gas prices based on network conditions to ensure transactions are confirmed in a timely manner.
• Gas Estimation: Accurately estimates gas usage for transactions to avoid overpaying or underpaying for gas.
• Gas Optimization: Implements techniques like transaction batching to reduce overall gas costs.
• EIP-1559 Support: Uses the EIP-1559 fee structure on supported networks for more predictable gas fees and faster transaction confirmations.

The RelayXplore SDK provides a comprehensive set of methods for interacting with the RelayXplore API. This section documents all available methods and their parameters.

Transaction Methods

Account Methods

Utility Methods

The RelayXplore SDK may throw errors or exceptions in various scenarios, such as invalid API keys, insufficient balance, or network issues. This section provides guidance on how to handle these errors gracefully.

Common Error Codes

Handling Errors in Code

import { RelayXplore } from '@relayxplore/sdk';

const relay = new RelayXplore({
  apiKey: process.env.RELAYXPLORE_API_KEY,
  network: 'mainnet',
});

async function sendTransaction(transaction) {
  try {
    const result = await relay.sendTransaction(transaction);
    console.log('Transaction hash:', result.hash);
  } catch (error) {
    console.error('Error sending transaction:', error.message);

    if (error.code === 'INSUFFICIENT_BALANCE') {
      console.warn('Your account balance is too low. Please fund your account.');
    } else if (error.code === 'INVALID_API_KEY') {
      console.error('Invalid API key. Please check your API key.');
    } else {
      console.error('An unexpected error occurred.');
    }
  }
}

Custom Error Handling

You can implement custom error handling logic to suit your specific needs. For example, you might want to retry failed transactions, notify your users of errors, or log errors for debugging purposes.

async function sendTransactionWithRetry(transaction, maxRetries = 3) {
  let retries = 0;

  while (retries < maxRetries) {
    try {
      const result = await relay.sendTransaction(transaction);
      console.log('Transaction hash:', result.hash);
      return result;
    } catch (error) {
      console.error(`Transaction failed (retry ${retries + 1}):`, error.message);
      retries++;

      // Wait for a short period before retrying
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }

  console.error('Transaction failed after multiple retries.');
  throw new Error('Transaction failed after multiple retries.');
}

This section provides code examples demonstrating how to use the RelayXplore SDK in various scenarios, such as sending gasless transactions, interacting with smart contracts, and managing API keys.

Sending a Gasless Transaction

import { RelayXplore } from '@relayxplore/sdk';

const relay = new RelayXplore({
  apiKey: process.env.RELAYXPLORE_API_KEY,
  network: 'mainnet',
});

async function sendGaslessTransaction(to, data, value = '0') {
  try {
    const transaction = {
      to,
      data,
      value,
    };

    const result = await relay.sendTransaction(transaction);
    console.log('Transaction hash:', result.hash);
    return result;
  } catch (error) {
    console.error('Error sending transaction:', error);
    throw error;
  }
}

Interacting with a Smart Contract

import { RelayXplore } from '@relayxplore/sdk';
import { ethers } from 'ethers';

const relay = new RelayXplore({
  apiKey: process.env.RELAYXPLORE_API_KEY,
  network: 'mainnet',
});

async function callContractFunction(contractAddress, abi, functionName, args) {
  try {
    const iface = new ethers.utils.Interface(abi);
    const data = iface.encodeFunctionData(functionName, args);

    const transaction = {
      to: contractAddress,
      data,
      value: '0',
    };

    const result = await relay.sendTransaction(transaction);
    console.log('Transaction hash:', result.hash);
    return result;
  } catch (error) {
    console.error('Error calling contract function:', error);
    throw error;
  }
}

Batching Transactions

import { RelayXplore } from '@relayxplore/sdk';

const relay = new RelayXplore({
  apiKey: process.env.RELAYXPLORE_API_KEY,
  network: 'mainnet',
});

async function sendBatchTransactions(transactions) {
  try {
    const result = await relay.sendBatchTransaction(transactions);
    console.log('Batch transaction hash:', result.hash);
    return result;
  } catch (error) {
    console.error('Error sending batch transactions:', error);
    throw error;
  }
}