Lunul & Jito-Inspired Block Engine Infrastructure Docs

01. System Overview

The Lunul / Jito-inspired Block Engine architecture decouples standard mempool transaction propagation from high-performance auction execution. Validators running modified client software subscribe directly to block engine relayer streams, creating a specialized sidecar for atomic transaction bundles.

Block Space Auctions

Searchers submit transaction bundles (1-5 transactions) containing explicit tip instructions.

CU Efficiency

Evaluates bundles based on total tip relative to Compute Unit consumption (tip / compute_units).

Atomic Execution

Transactions execute sequentially. If any leg fails or reverts, the entire bundle drops atomically.

02. API Reference

The block engine exposes high-throughput HTTP/JSON-RPC endpoints for direct transaction and bundle relaying.

Transactions Proxy Endpoint: https://mainnet.block-engine.lunul.org/api/v1/transactions

Bundles Relay Endpoint: https://mainnet.block-engine.lunul.org/api/v1/bundles

Method	Description	Rate Limit
sendTransaction	Proxies transaction directly to the validator with MEV protection options.	1 RPS / IP
sendBundle	Submits an atomic array of up to 5 signed transactions for block auctions.	5 RPS / project
simulateBundle	Simulates bundle state execution without broadcasting to the relayer.	Standard RPC

Example: Submitting a Transaction via cURL

curl https://mainnet.block-engine.lunul.org/api/v1/transactions \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "sendTransaction",
    "params": ["<BASE64_ENCODED_TRANSACTION>", {"encoding": "base64"}]
  }'

03. Getting Started

To begin routing high-frequency transactions and bundles through the block engine, follow these steps:

Format Encoding: Always encode fully-signed transactions using base64 formatting (recommended over base58 for serialization speed).
Select Tip Accounts: Retrieve active network tip accounts dynamically via getTipAccounts. Randomly select one account for each submission to minimize state contention.
Include Tip Instruction: Append a native transfer instruction paying at least the protocol minimum tip (1,000 lamports for single transactions; 5,000 lamports for bundles).

04. Sandwich Mitigation (`dontfront`)

Harmful MEV extraction—such as sandwich attacks where searchers front-run and back-run user swaps—is mitigated natively using the dontfront account directive.

How It Works

• The `jitodontfront` Prefix: Any valid address starting with jitodontfront can be injected as a read-only, non-signer account into your transaction.
• Enforced Ordering: When detected, your transaction is protected against competing front-running bundles, or if used in sendBundle, must appear strictly at index 0.

Example: Adding a read-only DontFront account protection flag

import { PublicKey } from '@solana/web3.js';

const dontFrontPubkey = new PublicKey("jitodontfront111111111111111111111111111111");

const protectionAccountMeta = {
    pubkey: dontFrontPubkey,
    isSigner: false,
    isWritable: false, // Read-only optimizes landing speed
};

05. Tips & Best Practices

Recommended Fee Split

When utilizing standard sendTransaction, allocate a balanced split between priority fees and validator tips (e.g., 70% Priority / 30% Tip).

Avoid ALTs for Tips

Never use Address Lookup Tables (ALTs) for tip accounts. Ensure tips are routed exclusively through block engine leaders; tipping standard validators is ineffective.

06. Rate Limits

To maintain cluster stability and prevent denial-of-service vectors, the block engine enforces strict rate boundaries:

• Default Limits: Standard unauthenticated endpoints enforce a limit of 1 request per second (RPS) per IP per region for sendTransaction.
• Bundle Limits: Standard project API keys permit up to 5 RPS for sendBundle requests.
• Exceeding Limits: Breaching rate thresholds results in an immediate HTTP 429 Too Many Requests response code.

07. Custom Rate Limit Request

If your trading bot, market maker, or institutional gateway requires higher throughput tiers exceeding default rate limits:

Submit an enterprise throughput upgrade request via the Lunul Portal Developer Dashboard.

Required details include your public key identifier, average daily transaction volume, peak concurrent RPS requirements, and target regional block engine gateways (Frankfurt, Tokyo, New York).

08. Troubleshooting

Error: `The supplied pubkey is not authorized`

Indicates your request payload includes an obsolete auth parameter or keypair variable. Set authentication fields to Null or omit them for standard proxy calls.

Dropped Bundles / Low Tip Auction Losses

Verify that your tip exceeds the dynamic network floor and your compute unit efficiency (tip / compute_units) is competitive against rival bots during volatility.

Expired Recent Blockhash

Ensure your client refreshes blockhashes immediately before signing, as block engine slots progress rapidly in sub-400ms intervals.

09. ⚖️ Legal & Disclaimer

No Guarantee of Inclusion: Use of the block engine, bundle relays, and dontfront mitigation features aids in transaction prioritization and MEV defense but does not guarantee 100% inclusion or absolute immunity against third-party reordering or network splits.

As-Is Provision: All infrastructure APIs are provided on an "as-is" and "as-available" basis without warranties of any kind. The Lunul Foundation assumes no liability for failed trades, slippage losses, or missed block auctions during periods of extreme network congestion.

Infrastructure & Low-Latency Block Engine Reference