n8n-nodes-flashbots

[Velocity BPA Licensing Notice]

This n8n node is licensed under the Business Source License 1.1 (BSL 1.1).

Use of this node by for-profit organizations in production environments requires a commercial license from Velocity BPA.

For licensing information, visit https://velobpa.com/licensing or contact [email protected].

A comprehensive n8n community node for Flashbots MEV infrastructure, providing 11 resources and 60+ operations for private transactions, bundle submission, MEV-Share orderflow hints, and blockchain analytics.

Features

• Private Transactions: Submit frontrunning-protected transactions via Flashbots Protect RPC
• Bundle Operations: Create, simulate, and submit transaction bundles to block builders
• MEV-Share: Access orderflow hints, configure rebates, and share in extracted MEV
• Flashbots Protect: Configure privacy settings, builder selection, and fast mode
• Block Building: Monitor builder health, reputation, and block statistics
• Searcher Tools: Build backrun transactions, calculate profits, access hint streams
• MEV-Boost: Query relay status, proposer duties, and delivered payloads
• Bundle Composition: Create nested bundles with validity conditions
• Simulation: Test transactions and bundles before submission
• Analytics: Access protocol-wide metrics and leaderboards
• Utility Functions: Sign bundles, encode transactions, check API health

Installation

Community Nodes (Recommended)

1. Go to Settings > Community Nodes in your n8n instance
2. Click Install
3. Enter n8n-nodes-flashbots
4. Click Install

Manual Installation

# Navigate to your n8n installation
cd ~/.n8n

# Install the package
npm install n8n-nodes-flashbots

# Restart n8n

Development Installation

# 1. Extract the zip file
unzip n8n-nodes-flashbots.zip
cd n8n-nodes-flashbots

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Create symlink to n8n custom nodes directory
# For Linux/macOS:
mkdir -p ~/.n8n/custom
ln -s $(pwd) ~/.n8n/custom/n8n-nodes-flashbots

# For Windows (run as Administrator):
# mklink /D %USERPROFILE%\.n8n\custom\n8n-nodes-flashbots %CD%

# 5. Restart n8n
n8n start

Credentials Setup

Configure your Flashbots credentials in n8n:

| Field | Description | Required | |-------|-------------|----------| | Network | Ethereum network (mainnet, goerli, sepolia, holesky) | Yes | | Auth Signer Private Key | ECDSA secp256k1 key for Flashbots reputation | Yes | | Ethereum RPC URL | RPC endpoint for blockchain queries | Yes | | Transaction Signer Key | Key for signing transactions (optional) | No | | Custom Relay URL | Override default relay URL (optional) | No | | Custom Protect RPC URL | Override default Protect RPC (optional) | No |

Security Note: The auth signer key is used for reputation only and should NOT hold funds. Use a dedicated key for Flashbots authentication.

Resources & Operations

Private Transactions

Submit and manage frontrunning-protected transactions.

| Operation | Description | |-----------|-------------| | Send Private Transaction | Submit protected transaction to Flashbots | | Cancel Private Transaction | Cancel a pending private transaction | | Get Transaction Status | Check inclusion status | | Get Transaction Receipt | Get receipt after inclusion | | Configure Privacy | Set hints and builder preferences |

Bundles

Create, simulate, and submit transaction bundles.

| Operation | Description | |-----------|-------------| | Send Bundle | Submit bundle to relay | | Simulate Bundle | Test bundle execution | | Cancel Bundle | Cancel pending bundle | | Get Bundle Stats | Get inclusion statistics | | Get User Stats | Get account metrics | | Get Conflicting Bundles | Find competing bundles |

MEV-Share

Interact with the MEV-Share orderflow auction.

| Operation | Description | |-----------|-------------| | Subscribe to Events | Get SSE stream URL for hints | | Send MEV-Share Bundle | Submit bundle to matchmaker | | Get Pending Transactions | Get available orderflow hints | | Configure Hints | Set privacy preferences | | Set Refund Address | Configure MEV rebate address | | Get Refund Stats | Get rebate history |

Flashbots Protect

Configure and manage Flashbots Protect RPC settings.

| Operation | Description | |-----------|-------------| | Get Protect Status | Get transaction status | | Configure Protect | Set builder selection | | Get Fast Mode Status | Check TEE status | | Set Auction Timeout | Configure timing | | Get Pending Transactions | Get in-flight transactions |

Block Building

Monitor builder health and block statistics.

| Operation | Description | |-----------|-------------| | Get Builder Status | Get builder health | | Get Block Stats | Get built block statistics | | Get Builder List | Get active builders | | Get Builder Reputation | Get builder performance |

Searcher Operations

Tools for MEV searchers to find and extract value.

| Operation | Description | |-----------|-------------| | Get Event Stream | Get real-time hint stream URL | | Build Backrun Bundle | Create backrun transaction | | Get Searcher Stats | Get performance metrics | | Calculate Profit | Estimate MEV opportunity | | Submit to Builders | Send to multiple builders |

MEV-Boost

Query MEV-Boost relay data and validator information.

| Operation | Description | |-----------|-------------| | Get Relay Status | Get relay health | | Get Proposer Duties | Get upcoming slots | | Get Delivered Payloads | Get past blocks | | Get Builder Submissions | Get received bids | | Get Validator Registration | Get registration status |

Bundle Composition

Create and compose complex bundle structures.

| Operation | Description | |-----------|-------------| | Create Nested Bundle | Create composite bundle | | Add Transaction | Append transaction to bundle | | Set Bundle Privacy | Configure hints for bundle | | Set Validity Conditions | Set refund configuration | | Merge Bundles | Combine multiple bundles |

Simulation

Simulate transactions and bundles before submission.

| Operation | Description | |-----------|-------------| | Simulate Transaction | Simulate single transaction | | Simulate Bundle | Simulate full bundle | | Get State Diff | Get state changes | | Get Trace | Get execution trace | | Estimate Gas | Estimate gas usage |

Analytics

Access protocol-wide metrics and leaderboards.

| Operation | Description | |-----------|-------------| | Get MEV Stats | Get protocol-wide metrics | | Get Builder Stats | Get builder performance | | Get Relay Stats | Get relay metrics | | Get Historical Bundles | Get past bundle data | | Get Searcher Leaderboard | Get top searchers |

Utility

Helper functions for signing, encoding, and health checks.

| Operation | Description | |-----------|-------------| | Sign Bundle | Create bundle signature | | Verify Bundle | Validate bundle signature | | Encode Transaction | Prepare transaction for bundle | | Get Current Block | Get latest block number | | Get Target Block | Calculate target block | | Get API Health | Check service status |

Trigger Node

The Flashbots Trigger node monitors for various events:

| Trigger | Description | |---------|-------------| | MEV-Share Event | New MEV-Share hint available | | Transaction Included | Watched private tx included | | Bundle Landed | Watched bundle included in block | | Large MEV Opportunity | High-value hint detected | | Builder Bid | New builder bid received | | New Pending Hint | New transaction hint available |

Usage Examples

Submit a Private Transaction

// Configure the Flashbots node
{
  "resource": "privateTransactions",
  "operation": "sendPrivateTransaction",
  "rawTransaction": "0x...", // Signed transaction
  "maxBlockNumber": 0, // Auto (25 blocks ahead)
  "fastMode": true, // Use TEE for faster inclusion
  "additionalOptions": {
    "hints": ["calldata", "logs"],
    "builders": "flashbots,builder0x69",
    "refundAddress": "0x...",
    "refundPercent": 90
  }
}

Send a Bundle

// Configure bundle submission
{
  "resource": "bundles",
  "operation": "sendBundle",
  "transactions": "0x...,0x...", // Comma-separated signed txs
  "targetBlock": 0, // Auto (current + 1)
  "additionalOptions": {
    "minTimestamp": 0,
    "maxTimestamp": 0,
    "revertingTxHashes": "",
    "replacementUuid": ""
  }
}

Monitor MEV-Share Events

// Get SSE stream URL for hints
{
  "resource": "mevShare",
  "operation": "subscribeToEvents"
}
// Returns: { "streamUrl": "https://mev-share.flashbots.net/api/v1/bundles" }

Calculate Profit for Backrun

{
  "resource": "searcherOperations",
  "operation": "calculateProfit",
  "expectedRevenue": "0.5", // ETH
  "gasUsed": 150000,
  "gasPrice": 50, // Gwei
  "builderTipPercent": 10
}

Flashbots Concepts

| Concept | Description | |---------|-------------| | MEV | Maximal Extractable Value from transaction ordering | | Bundle | Ordered array of transactions executed atomically | | Searcher | Entity extracting MEV via bundles | | Builder | Entity constructing blocks from bundles | | Relay | Service forwarding bundles and blocks | | Flashbots Protect | Frontrunning protection RPC endpoint | | MEV-Share | User MEV rebate system via orderflow auction | | Hint | Partial transaction info shared with searchers | | Backrun | Transaction placed immediately after target tx | | Pre-trade Privacy | Transaction hidden until block inclusion | | TEE | Trusted Execution Environment for fast mode |

Networks

| Network | Chain ID | Relay URL | |---------|----------|-----------| | Mainnet | 1 | relay.flashbots.net | | Goerli | 5 | relay-goerli.flashbots.net | | Sepolia | 11155111 | relay-sepolia.flashbots.net | | Holesky | 17000 | relay-holesky.flashbots.net |

Error Handling

The node provides detailed error messages for common issues:

| Error | Cause | Solution | |-------|-------|----------| | Invalid private key | Malformed key format | Ensure 64-character hex string | | Authentication failed | Invalid signature | Check auth signer key | | Bundle simulation failed | Transaction reverted | Verify transaction parameters | | Network error | Connectivity issue | Check RPC endpoint |

Security Best Practices

1. Use dedicated keys: Never use keys with funds for Flashbots auth
2. Protect credentials: Store private keys securely in n8n credentials
3. Validate transactions: Always simulate before submission
4. Monitor inclusion: Track transaction and bundle status
5. Set appropriate timeouts: Configure max block numbers
6. Use testnets first: Test on Goerli/Sepolia before mainnet

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run linting
npm run lint

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run dev

Author

Velocity BPA

• Website: velobpa.com
• GitHub: Velocity-BPA

Licensing

This n8n community node is licensed under the Business Source License 1.1.

Free Use

Permitted for personal, educational, research, and internal business use.

Commercial Use

Use of this node within any SaaS, PaaS, hosted platform, managed service, or paid automation offering requires a commercial license.

For licensing inquiries: [email protected]

See LICENSE, COMMERCIAL_LICENSE.md, and LICENSING_FAQ.md for details.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

Support

• Documentation: Flashbots Docs
• Issues: GitHub Issues
• Discord: Flashbots Discord

Acknowledgments

• Flashbots for MEV infrastructure
• n8n for the workflow automation platform
• The MEV research community