Header Specifications

Table of contents:

1. Introduction

2. Header Requirements and Options

   • Mandatory Header: X-Flashbots-Signature

     • Using FlashbotsBundleProvider

     • Calculating X-Flashbots-Signature Header Manually

   • Optional Header: X-Oval-Addresses

     • Benefits

     • Format and Constraints

     • Example Usage

Introduction

This document outlines the requirements and usage of headers in bundle requests to the Oval Node, focusing on the mandatory X-Flashbots-Signature header and the optional X-Oval-Addresses header.

Header Requirements and Options

Mandatory Header: X-Flashbots-Signature

The x-flashbots-signature header is required for all bundle requests. This header contains a signature that verifies the authenticity and integrity of the request.

Using FlashbotsBundleProvider

If you are using the flashbots-ethers-v6-provider-bundle package, the FlashbotsBundleProvider.signBundle function automatically signs the bundle and provides the x-flashbots-signature header for you. Here is an example:

const flashbotsProvider = await FlashbotsBundleProvider.create(
  provider, // a normal ethers.js provider, to perform gas estimations and nonce lookups
  authSigner // ethers.js signer wallet, only for signing request payloads, not transactions
)
...
// The transactionBundle is signed and the signature sent in the "x-flashbots-signature"
// header
const flashbotsTransactionResponse = await flashbotsProvider.sendBundle(
  transactionBundle,
  targetBlockNumber,
  )

Calculating X-Flashbots-Signature Header Manually

If you are not using the Flashbots libraries, you can manually calculate the x-flashbots-signature header as shown in the following example:

const serializedBody = JSON.stringify(body);
const hash = ethers.id(serializedBody);
const bundleSignedMessage = ethers.signMessage(hash, privateKey);
const xFlashbotsSignatureHeader = `${publicKey}:${bundleSignedMessage}`;

Optional Header: X-Oval-Addresses

The x-oval-addresses header allows users to specify Oval addresses within bundle requests. This header supports the eth_sendBundle and eth_callBundle methods, providing direct control over the Oval instances to be unlocked.

Benefits

1. Atomic Unlocking of Multiple Instances: Users can unlock several Oval instances within a single bundle. This capability is useful for operations that depend on unlocking prices from various sources, enabling more complex and targeted strategies.

2. Efficient Bundle Preparation: By specifying unlock addresses directly, users can eliminate the extra delay of the Oval Node searching for suitable unlock addresses. This efficiency reduces processing times and speeds up the forwarding of bundles to the Flashbots relay, offering a competitive edge in scenarios where speed is crucial.

Format and Constraints:

• The header expects a JSON-encoded array of Ethereum addresses, with each address representing an Oval instance.

• Only valid Ethereum addresses should be included, and all must correspond to Oval instances configured within the Node.

• A single refund address per request is supported, implying that the specified Oval addresses must be from the same protocol. For example, it's not permitted to include two Oval addresses in the header for two different money markets. This approach ensures simplicity in protocol kickbacks calculations.

• To prevent resource overuse or potential system abuse, the number of addresses per request is capped at a predefined maximum.

Example Usage:

For instance, to include two specific OVAL addresses in a request, add the following header to your API call:

x-oval-addresses: ["0xAddress1", "0xAddress2"]