JSON-RPC API Reference

This page details the http endpoints serviced by the block engine.

JSON-RPC HTTP Methods

The block engine accepts HTTP requests using the JSON-RPC 2.0 specification.

Request Formatting

To make a JSON-RPC request, send an HTTP POST request with a Content-Type: application/json header. The JSON request data should contain 4 fields:

• jsonrpc: string - set to "2.0"

• id: number - a unique client-generated identifying integer

• method: string - a string containing the method to be invoked

• params: array - a JSON array of ordered parameter values

We follow the same request formatting as Solana JSON-RPC requests. You can find the documentation here.

Authorization

In the short-term we don't require authentication to send the requests.

If there are any changes to the authentication mechanism it would be updated in the document and communicated with all the stakeholders.

Definitions

• Bundle: Bundles are a list of transactions that execute sequentially and atomically. “All or nothing” so to speak. This means that a user can send a bundle that contains multiple transactions and guarantee that they are all executed one after the other and the bundle succeeds only if all individual transactions succeed.

• Hash: A SHA-256 hash of a chunk of data.

• Pubkey: The public key of a Ed25519 key-pair.

• Tip Account: List of accounts to which a tip can be paid for processing the bundles. Clients submitting bundles must pay a tip for bundle processing.

• Transaction: A list of Solana instructions signed by a client keypair to authorize those actions.

• Signature: An Ed25519 signature of transaction's payload data including instructions. This can be used to identify transactions.

State Commitment

The commitment describes how finalized a block is at that point in time.

In descending order of commitment (most finalized to least finalized), these are the commitment levels:

• "finalized" - the node will query the most recent block confirmed by supermajority of the cluster as having reached maximum lockout, meaning the cluster has recognized this block as finalized

• "confirmed" - the node will query the most recent block that has been voted on by supermajority of the cluster.

  • It incorporates votes from gossip and replay.

  • It does not count votes on descendants of a block, only direct votes on that block.

  • This confirmation level also upholds "optimistic confirmation" guarantees in release 1.3 and onwards.

• "processed" - the node will query its most recent block. Note that the block may still be skipped by the cluster.

Please refer to configuring-state-commitment for more details.

RpcResponse Structure

Many methods that take a commitment parameter return an RpcResponse JSON object comprised of two parts:

• context : An RpcResponseContext JSON structure including a slot field at which the operation was evaluated. example:

      "context": {
      "slot": 1
    },

• value : The value returned by the operation itself. example:

        "value": [
            {
                "bundle": {
                    "signatures": [
                        "3Eq21vXNB5s86c62bVuUfTeaMif1N2kUqRPBmGRJhyTA",
                        "2nBhEBYYvfaAe16UMNqRHre4YNSskvuYgx3M6E4JP1oDYvZEJHvoPzyUidNgNX5r9sTyN1J9UxtbCXy2rqYcuyuv"
                    ]
                },
                "slot": 1234,
                "confirmationStatus": "finalized",
                "err": "null"
            }
        ]