Skip to main content

API Reference

BuilderNet provides these APIs:

eth_sendBundle​

You can use eth_sendBundle to send a bundle of transactions to BuilderNet. You can also use it to replace or cancel past bundles.

Transactions sent with eth_sendBundle are eligible for refunds.

What is a bundle

A bundle is a list of signed transactions that are executed atomically. If any transaction in the bundle fails, the entire bundle fails. This is useful for sending multiple transactions that depend on each other.

Request ​

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "eth_sendBundle",
    "params": [{
        txs               // Array[String], A list of signed transactions to execute in an atomic bundle.
        blockNumber       // String, A hex encoded block number for which this bundle is valid on.

        // Optional fields
        replacementUuid   // String, UUID that can be used to cancel/replace this bundle.

        revertingTxHashes // Array[String], A list of tx hashes that are allowed to revert.
        droppingTxHashes  // Array[String], A list of tx hashes that can be removed from the bundle if it's deemed useful (but not revert).
        refundTxHashes // Array[String], A list of tx hashes (max 1) that should be considered for MEV refunds. If empty, defaults to the last transaction in the bundle.

        minTimestamp      // Number, The minimum timestamp for which this bundle is valid, in seconds since the unix epoch.
        maxTimestamp      // Number, The maximum timestamp for which this bundle is valid, in seconds since the unix epoch.

        refundPercent     // Number (integer between 1-99), How much of the total priority fee + coinbase payment you want to be refunded for.
        refundRecipient   // String, The address that the funds from refundPercent will be sent to. If not specified, they will be sent to the from address of the first transaction.
    }]
}

Notes:

  • blockNumber can be:
    1. A specific block number, hex encoded (e.g. 0x1361bd3)
    2. For next block only: "0x" or null or missing field
  • uuid is supported as alias for replacementUuid.

Bundle replacement and cancellation:

  • Replacing bundles: Send another bundle with the same replacementUuid , and it will override any previous one.
  • Cancelling bundles: Send another bundle with the same replacementUuid and an empty list of transactions.

MEV Refunds:

When a searcher makes money by using some user tx, it pays the builder to be included in the block. Part of that payment is refunded to the user. To determine how much the searcher paid the builder, we check the delta in the builder's balance before and after executing a particular tx in the bundle. By checking this delta, we are considering gas payments and also explicit transfers from the searcher to the builder.

These refunds should not be confused with Gas Fee Refunds.

  • refundTxHashes field (optional): Specifies which transaction in the bundle should be analyzed to measure the payment to the builder.
    • If present, specifies which transactions in the bundle should be considered for refund calculations.
    • If empty or not specified, defaults to the last transaction in the bundle.
    • Currently limited to a maximum of 1 transaction hash.
  • refundPercent field:
    • (Optional) An integer between 1-99 which defines how much of the total priority fee + coinbase payment you want to be refunded for.
    • Example: If a bundle pays 0.2 ETH of priority fee plus 1 ETH to coinbase, a refundPercent set to 50 will result in a transaction being appended after the bundle, paying 0.59 ETH back to the EOA. This is assuming the payout tx will cost BuilderNet 0.01 ETH in fees, which are deducted from the 0.6 ETH payout.

Response ​

The response always contains (a) an empty result and (b) a matching request ID:

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": null
}

Example request ​

curl https://direct-us.buildernet.org \
    --cacert builder-cert.pem \  # or using --insecure
    --header 'Content-Type: application/json' \
    --header 'X-Flashbots-Signature: <public key address>:<signature>' \
    --data '{
        "id": 1,
        "jsonrpc": "2.0",
        "method": "eth_sendBundle",
        "params": [{
            "txs": [
                "0x000000..."
            ],
            "blockNumber": "0x1361bd3"
        }]
    }'

See this example Golang code for sending a transaction with a signed request and a pinned server certificate.

Request signature and authentication ​

eth_sendBundle requests require a X-Flashbots-Signature header for authentication and for the signer to receive refunds:

X-Flashbots-Signature: <public_key_address>:<signature>

The signature is calculated by taking the EIP-191 hash of the json body encoded as UTF-8 bytes. Any valid ECDSA secp256k1 key (i.e. any Ethereum key) can be used to sign the payload. The address associated with this key will be used for Redistribution. For more details and examples on signing the payload, see the documentation here.

Instance TLS certificate ​

The builder node creates a fresh TLS certificate on each startup, of which the private key is guaranteed to stay inside the TEE instance. You can verify the TEE proof for this certificate using the "TEE Proof Validation API". You can also - insecurely - get the certificate with curl like this:

curl -w %{certs} -k https://direct-us.buildernet.org

Example Golang code ​

See this example Golang code for sending a signed transaction to a builder node. The example code supports requiring a specific TLS certificate as well as skipping certificate validation.

eth_sendRawTransaction​

You can use eth_sendRawTransaction to send a single signed transaction to BuilderNet.

Transactions sent with eth_sendRawTransaction are NOT eligible for refunds.

Transactions sent this way are:

  • not sent to the mempool.
  • propagated to other BuilderNet builder nodes.
  • tried to include for up to 5 blocks.

Request ​

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "eth_sendRawTransaction",
    "params": ["0x000000..."]
}

Response ​

The response contains the transaction hash:

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": "0x000000..."
}

Request signature and authentication ​

eth_sendRawTransaction requests also require a X-Flashbots-Signature header for authentication. For more details, see the relevant section for eth_sendBundle.

TEE Proof Validation API (aTLS)​

BuilderNet uses attested TLS (aTLS) to verify the attestation of specific builder node instances.

You can find more details in the Constellation docs:

aTLS modifies the TLS handshake by embedding an attestation statement into the TLS certificate. Instead of relying on a certificate authority, aTLS uses this attestation statement to establish trust in the certificate.

The protocol can be used by clients to verify a server certificate, by a server to verify a client certificate, or for mutual verification (mutual aTLS).

In BuilderNet, github.com/flashbots/cvm-reverse-proxy is responsible for attested TLS (aTLS) communication, both towards users as well as within the network. You can use the attested-get tool to receive the builder certificate over an attested channel:

# Install attested-get
go install github.com/flashbots/cvm-reverse-proxy/cmd/attested-get

# Get the builder certificate over an attested channel
attested-get \
    --addr=https://direct-us.buildernet.org:7936/cert \
    --expected-measurements=https://measurements.builder.flashbots.net \
    --out-response=builder-cert.pem

See also "Orderflow encryption and attestation" for more details.