# EVM Tx Spammer

## Architecture

The TxSpamSDK operates in two distinct phases to ensure reliable, high-throughput load generation.

### 1. Setup Phase

Before any spam occurs, the `SpamManager` (or Orchestrator) prepares the environment:

1. **Fund Root Account**: Validates the provided root private key.
2. **Worker Derivation**: Generates thousands of ephemeral private keys (Workers) based on the `concurrency` setting.
3. **Funding**: The root account sends a small amount of ETH to each worker account to cover gas fees.

### 2. Attack Phase (Spam)

Once all workers are funded, the attack begins.

* **Parallel Execution**: Each worker runs an independent loop.
* **Gas Estimation**: Before sending a transaction, the worker estimates gas.
* **GasGuardian**: A central state controller (`GasGuardian`) checks if the cumulative gas limit (e.g., 29M) has been reached.
* **Execution**: If within limits, the transaction is signed and broadcasted to the RPC node.

### Architecture Diagram

```text
+------------------+              +------------------+
|   Root Account   |------------->|  SpamOrchestrator|
+------------------+   Funds      +--------+---------+
                                           |
                                           | Spawns & Manages
                                           v
                          +----------------------------------+
                          |          Worker Pool             |
                          | +----------+      +----------+   |
                          | | Worker 1 | ...  | Worker N |   |
                          | +----+-----+      +-----+----+   |
                          +------+------------------+--------+
                                 |                  |
                                 | 1. Estimate      |
                                 v                  |
                          +--------------+          |
                          |   EVM Node   |          |
                          +------+-------+          |
                                 |                  |
                                 | 2. Check Limit   | 3. Send Tx
                                 v                  v
                          +--------------+    +--------------+
                          | GasGuardian  |--->|   EVM Node   |
                          +--------------+    +--------------+
```

### Core Components

#### SpamOrchestrator

The central controller. It validates configuration, handles the funding lifecycle, and manages the worker pool. In "Mixed Mode," it intelligently partitions workers and gas limits according to the specified percentages.

#### GasGuardian

A specialized state manager that acts as a semaphore for gas usage.

* **Atomic Tracking**: Ensures race conditions between parallel workers don't exceed the total gas limit.
* **Fail-Safe**: If `maxGasLimit` is hit, it immediately signals all workers to stop, preventing "over-spamming" (crucial for block building tests).

#### Workers

Lightweight, ephemeral wallet instances.

* **Local Nonce Management**: Workers track their own nonces locally to avoid the latency of `eth_getTransactionCount` calls before every transaction.
* **Zero-Dependency**: Each worker operates independently once funded, maximizing parallel throughput.


## Configuration

The `SpamOrchestrator` is configured via a type-safe Zod schema.

### SpamSequenceConfig

The root configuration object passed to the orchestrator.

| Property          | Type                 | Description                                          |
| :---------------- | :------------------- | :--------------------------------------------------- |
| `rpcUrl`          | `string`             | The HTTP URL of the EVM node.                        |
| `chainId`         | `number`             | The integer Chain ID of the network.                 |
| `maxGasLimit`     | `bigint`             | Cumulative gas usage limit before stopping.          |
| `concurrency`     | `number`             | Number of simultaneous worker wallets to create.     |
| `durationSeconds` | `number`             | (Optional) Max duration to run the spam in seconds.  |
| `totalTxs`        | `number`             | (Optional) Max number of total transactions to send. |
| `strategy`        | `SpamStrategyConfig` | The specific spam strategy to execute.               |

### SpamStrategyConfig

Supports discriminated unions based on `mode`.

#### `transfer`

Simple ETH transfers between accounts.

| Property      | Type         | Description                            |
| :------------ | :----------- | :------------------------------------- |
| `mode`        | `'transfer'` | Discriminator.                         |
| `amountPerTx` | `bigint`     | Amount of Wei to send per transaction. |

#### `deploy`

Deploys a contract bytecode repeatedly.

| Property   | Type       | Description                     |
| :--------- | :--------- | :------------------------------ |
| `mode`     | `'deploy'` | Discriminator.                  |
| `bytecode` | `Hex`      | The compiled contract bytecode. |
| `abi`      | `any`      | The contract ABI.               |

#### `read`

Executes a read-only contract call (`eth_call`). Useful for stressing RPC nodes without consuming on-chain gas.

| Property         | Type      | Description                   |
| :--------------- | :-------- | :---------------------------- |
| `mode`           | `'read'`  | Discriminator.                |
| `targetContract` | `Address` | The contract address to call. |
| `abi`            | `Abi`     | The contract ABI.             |
| `functionName`   | `string`  | The read function to call.    |
| `args`           | `any[]`   | Arguments for the function.   |

#### `write`

Executes a state-changing contract call.

| Property         | Type          | Description                                         |
| :--------------- | :------------ | :-------------------------------------------------- |
| `mode`           | `'write'`     | Discriminator.                                      |
| `targetContract` | `Address`     | The contract address to call.                       |
| `abi`            | `Abi`         | The contract ABI.                                   |
| `functionName`   | `string`      | The write function to call.                         |
| `argsGenerator`  | `() => any[]` | A function that returns arguments per tx (dynamic). |
| `staticArgs`     | `any[]`       | Static arguments for every tx.                      |

#### `mixed`

Splits resources across multiple strategies. The sum of percentages must equal 100.

| Property     | Type      | Description             |
| :----------- | :-------- | :---------------------- |
| `mode`       | `'mixed'` | Discriminator.          |
| `strategies` | `Array`   | List of sub-strategies. |

##### Mixed Strategy Example

```typescript
strategy: {
  mode: 'mixed',
  strategies: [
    {
      percentage: 10, // 10% of workers and gas
      config: { mode: 'transfer', amountPerTx: parseEther('0.01'), depth: 1 } 
    },
    {
      percentage: 90, // 90% of workers and gas
      config: { 
        mode: 'write', 
        targetContract: '0x...', 
        functionName: 'mint', 
        staticArgs: [] 
      }
    }
  ]
}
```


## Example

This is an example page.


## Getting Started

Follow this guide to set up your first spam sequence against a local Anvil node.

### Prerequisites

* **Node.js** v20+
* **Anvil** (Foundry) running locally (`anvil`)

### 1. Installation

Install the package in your project:

```bash
npm install @developeruche/tx-spammer-sdk
```

### 2. Basic Usage

Create a script `spam.ts` to flood the network with simple ETH transfers.

```typescript
import { SpamOrchestrator, SpamSequenceConfig } from '@developeruche/tx-spammer-sdk';
import { parseEther } from 'viem';

// 1. Define Configuration
const config: SpamSequenceConfig = {
    rpcUrl: 'http://127.0.0.1:8545',
    chainId: 31337,
    maxGasLimit: 29_000_000n, // Stop after filling ~1 block
    concurrency: 10, // Number of parallel workers
    strategy: {
        mode: 'transfer',
        amountPerTx: parseEther('0.0001'),
        depth: 10
    }
};

// 2. Initialize Orchestrator (with Anvil default key)
const PRIVATE_KEY = '0xac09...'; 
const orchestrator = new SpamOrchestrator(config, PRIVATE_KEY);

// 3. Run
async function main() {
    await orchestrator.setup(parseEther('1')); // Fund workers with 1 ETH total
    await orchestrator.start();
}

main();
```

### 3. Run It

Execute the script (using `ts-node` or similar):

```bash
npx ts-node spam.ts
```

You should see output indicating workers are being funded, and then a stream of transactions being sent until the gas limit is reached.

### Next Steps

Now that you have a basic stress test running, explore more advanced capabilities:

* [**Architecture**](/architecture): Understand how `GasGuardian` protects your funds.
* [**Configuration**](/configuration): Learn about `mixed` strategies and contract interaction.