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.
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).
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:- A specific block number, hex encoded (e.g.
0x1361bd3
) - For next block only:
"0x"
ornull
or missing field
- A specific block number, hex encoded (e.g.
uuid
is supported as alias forreplacementUuid
.
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.
Refunds:
- Refunds are based on the last transaction in the bundle.
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 beaver 0.01 ETH in fees, which are deduced from the 0.6 ETH payout.
- See also Refunds for more details.
Response
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"bundleHash": "0x2228f5d8954ce31dc1601a8ba264dbd401bf1428388ce88238932815c5d6f23f"
}
}
Example request
curl https://buildernet-flashbots-azure-eastus2-05.builder.flashbots.net \
--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://buildernet-flashbots-azure-eastus2-05.builder.flashbots.net
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://buildernet-flashbots-azure-eastus2-05.builder.flashbots.net:7936/cert \
--expected-measurements=https://measurements.builder.flashbots.net \
--out-response=builder-cert.pem
See also "Orderflow encryption and attestation" for more details.