Commitments API

Overview

The commitments-API is how users interact with Bolt proposers. It defines and limits what commitments can be given, and how requests should be authenticated.

Endpoints

bolt_requestInclusion

Description

Requests an inclusion preconfirmation for one or more transactions. If len(txs) > 1, the array will be considered a batch (all or nothing inclusion).

info

Authentication: messages should be authenticated by an ECDSA signer by placing the <signer:signature> string in the X-Bolt-Signature header. Both the signer and signature must be hex encoded. Example:

X-Bolt-Signature: 0x717C2fA1eA96019057A80D57156F14352e2A4F13:0x474e4b55b506aae6d557ba83c74146ffdcbdd27266605df3baf6084e96fb3289372c7481b2097b6ddf43f5850eebf8f8d511de85184f7056569b0602d695bb0100

The signature should be over the message digest, which is computed like this:

let message_digest = {
    let mut data = Vec::new();
    // First field is the concatenation of all the transaction hashes
    data.extend_from_slice(
        txs
          .iter()
          .map(|tx| tx.hash().as_slice())
          .collect::<Vec<_>>()
          .concat(),
    );

    // Second field is the little endian encoding of the target slot
    data.extend_from_slice(&target_slot.to_le_bytes());
    keccak256(data)
};

Or in pseudo-code:

digest = keccak256(bytes(tx_hash1) | bytes(tx_hash2) | ... | le_bytes(target_slot))

Method

POST

Headers

Content-Type	X-Bolt-Signature
application/json	<signer_address>:<ecdsa_signature>

Body

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "bolt_requestInclusion",
  "params": [
    {
      txs,     // Array[String], A list of hex-encoded "raw" transactions. If type 3, must include blobs.
      slot     // Number, the target slot.
    }
  ]
}

Response

• Example success response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "signature": "0xac0a81b31490fd7d1b9a9e794ef0a6ce1eb65bd7ff8f9b104095604bd95956030e0509ebe53c97c50593e641122e9d2611672c081dfb55b28d92d9c1f3d4ca8e01",
    "slot": 12,
    "txs": [
      "0x02f86d82053980843b9aca008504a817c8008252089400000000000000000000000000000000000000006480c001a041a577ade2d7f3455cfbc87c34c8e91ac2b8104a9c0e1140cb56976badeeb820a00c5bc88e7a024f6991acc9cfaf5dd34812b3870d0c14bba2f2fe53fceae44596"
    ]
  }
}

note

The signature is using the same format as the X-Bolt-Signature header, meaning it is a ECDSA signature over the same message digest.

• Example error response:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32003,
    "message": "Missing X-Bolt-Signature header"
  }
}