@gashawk-io/hardhat-gashawk

A Hardhat plugin for submitting transactions via Gashawk RPC or API with configurable settings.

Installation

npm install @gashawk-io/hardhat-gashawk

Usage

Import the plugin in your hardhat.config.ts:

import "@gashawk-io/hardhat-gashawk";

Add Gashawk configuration to your networks:

import { HardhatUserConfig } from "hardhat/config";
import "@gashawk-io/hardhat-gashawk";

const config: HardhatUserConfig = {
  networks: {
    // RPC-only mode (default)
    mainnet: {
      // Other RPC - https://app.gashawk.io/docs/Network/setup
      url: "https://core.gashawk.io/rpc/1",
      gashawk: {
        txDeadline: 300000, // 5 minutes (default)
        apiKey: null, // Use RPC only (default)
      },
    },
    // API mode with basic settings
    mainnetApi: {
      url: "https://mainnet.gashawk.io/rpc",
      gashawk: {
        txDeadline: 300000,
        apiKey: process.env.GASHAWK_API_KEY,
        
        // API mode with advanced settings
        apiSettings: { // apiSettings is optional
          rpcSelection: "flashbots",
          gasOptimization: true,
          maxGasPrice: "50000000000", // 50 gwei
          priorityFee: "2000000000", // 2 gwei
          slippageTolerance: 0.5, // 0.5%
          safeMonitor: true, // Will be skipped
        },
      },
    },
  },
};

export default config;

Configuration Options

txDeadline (optional)

• Type: number
• Default: 300000 (5 minutes)
• Description: Transaction deadline in milliseconds.

apiKey (optional)

• Type: string | null
• Default: null
• Description: Gashawk API key. When null, transactions are submitted via RPC only. When provided, transactions are submitted via Gashawk API with enhanced features. You can generate the api from https://app.gashawk.io/ All the transactions submitted via API can be monitored and managed from the gashawk dashboard.

apiSettings (optional)

• Type: object
• Default: undefined
• Description: Configuration settings for Gashawk API (only used when apiKey is provided)

API Settings Properties:

• rpcSelection (optional): RPC selection preference ("flashbots", "mevblocker", "public")
• gasOptimization (optional): Enable gas optimization (boolean)
• maxGasPrice (optional): Maximum gas price in wei (string)
• priorityFee (optional): Priority fee in wei (string)
• slippageTolerance (optional): Slippage tolerance percentage (number)
• safeMonitor (optional): Enable safe monitor (boolean) - Note: This setting is skipped in implementation

API Reference

The plugin extends the Hardhat Runtime Environment with a gashawk object:

hre.gashawk.submitTransaction(tx)

Submit a transaction via Gashawk RPC.

Parameters:

• tx: Transaction object with the following properties:
  • to?: Recipient address
  • from?: Sender address
  • value?: Transaction value in wei
  • data?: Transaction data
  • gasLimit?: Gas limit
  • gasPrice?: Gas price in wei
  • maxFeePerGas?: Max fee per gas (EIP-1559)
  • maxPriorityFeePerGas?: Max priority fee per gas (EIP-1559)
  • nonce?: Transaction nonce
  • type?: Transaction type
  • chainId?: Chain ID

Returns: Promise<string> - Transaction hash

hre.gashawk.getTransactionStatus(txHash)

Get the status of a submitted transaction.

Parameters:

• txHash: Transaction hash to check

Returns: Promise<TransactionStatus> - Transaction status object:

• hash: Transaction hash
• status: One of "pending", "confirmed", "failed", "timeout"
• blockNumber?: Block number (if confirmed)
• blockHash?: Block hash (if confirmed)
• gasUsed?: Gas used (if confirmed)
• effectiveGasPrice?: Effective gas price (if confirmed)
• timestamp?: Transaction timestamp

hre.gashawk.getConfig()

Get the current Gashawk configuration.

Returns: GashawkConfig - Current configuration object

Examples

RPC Mode vs API Mode

The plugin supports two modes:

RPC Mode (Default)

• Uses eth_sendRawTransaction for direct RPC submission
• No API key required
• Basic transaction submission and status tracking

API Mode

• Uses Gashawk API endpoints for enhanced features
• Requires API key
• Advanced settings and optimizations available
• Applies user settings before each transaction

Basic ETH Transfer

import { ethers } from "hardhat";

async function transferETH(hre: HardhatRuntimeEnvironment) {
  const txHash = await hre.gashawk.submitTransaction({
    to: "0x1234567890123456789012345678901234567890",
    value: ethers.utils.parseEther("0.1").toString(),
    gasLimit: "21000",
    gasPrice: ethers.utils.parseUnits("20", "gwei").toString(),
  });
  
  console.log("Transaction submitted:", txHash);
  
  const status = await hre.gashawk.getTransactionStatus(txHash);
  console.log("Transaction status:", status);
}

Transaction Monitoring

async function monitorTransaction(hre: HardhatRuntimeEnvironment, txHash: string) {
  let attempts = 0;
  const maxAttempts = 10;
  
  while (attempts < maxAttempts) {
    const status = await hre.gashawk.getTransactionStatus(txHash);
    console.log(`Status: ${status.status}`);
    
    if (status.status === "confirmed" || status.status === "failed" || status.status === "timeout") {
      console.log("Final status:", status);
      break;
    }
    
    await new Promise(resolve => setTimeout(resolve, 5000));
    attempts++;
  }
}

API Mode Examples

Using API with Basic Settings

// hardhat.config.ts
networks: {
  mainnet: {
    url: "rpc-url",
    gashawk: {
      apiKey: process.env.GASHAWK_API_KEY,
    },
  },
}

// Transaction submission (same interface)
const txHash = await hre.gashawk.submitTransaction({
  to: "0x1234567890123456789012345678901234567890",
  value: ethers.utils.parseEther("0.1").toString(),
  gasLimit: "21000",
  gasPrice: ethers.utils.parseUnits("20", "gwei").toString(),
});

Using API with Advanced Settings

// hardhat.config.ts
networks: {
  mainnet: {
    url: "",
    gashawk: {
      apiKey: process.env.GASHAWK_API_KEY,
      apiSettings: {
        rpcSelection: "flashbots",
        gasOptimization: true,
        maxGasPrice: "50000000000", // 50 gwei max
        priorityFee: "2000000000", // 2 gwei priority
        slippageTolerance: 0.5, // 0.5% slippage
      },
    },
  },
}

// Settings are applied automatically before each transaction
const txHash = await hre.gashawk.submitTransaction({
  to: "0x1234567890123456789012345678901234567890",
  value: ethers.utils.parseEther("0.1").toString(),
  gasLimit: "21000",
  gasPrice: ethers.utils.parseUnits("20", "gwei").toString(),
});

License

MIT