npm package: @gashawk-io/hardhat-gashawk
Description: Hardhat plugin for submitting transactions via Gashawk RPC
Author: Gashawk
Latest version: 1.2.1

# @gashawk-io/hardhat-gashawk

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

## Installation

```bash
npm install @gashawk-io/hardhat-gashawk
```

## Usage

Import the plugin in your `hardhat.config.ts`:

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

Add Gashawk configuration to your networks:

```typescript
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

```typescript
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

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