### Start Casper Sidecar Service

Source: https://github.com/casper-network/casper-sidecar/blob/dev/resources/ETC_README.md

Command to start the casper-sidecar service. Use after installation or stopping.

```bash
sudo systemctl start casper-sidecar.service
```

--------------------------------

### Example Sidecar Event Stream Output

Source: https://github.com/casper-network/casper-sidecar/blob/dev/USAGE.md

This example demonstrates the Sidecar version message received when connecting to the Sidecar's event stream. Colons represent keep-alive messages.

```shell
curl -sN http://127.0.0.1:19999/events/sidecar

data:{"SidecarVersion":"1.1.0"}

:

:


```

--------------------------------

### Example Node Event Stream Output

Source: https://github.com/casper-network/casper-sidecar/blob/dev/USAGE.md

This example shows the structure of events received from the node event stream, including an ApiVersion event and a TransactionProcessed event. Colons indicate keep-alive messages.

```shell
curl -sN http://127.0.0.1:19999/events

data:{"ApiVersion":"2.0.0"}

data:{ "TransactionProcessed": { "transaction_hash": { "Version1": "25329c14a4f9307830f2b4b6b529b0c3fd618dec65af7456ad9f9e2c7ba1ff4a" }, "initiator_addr": { "PublicKey": "02024e2b994a52bcf4c0cc112512c4be04853c4e824203a8e627c107a8d595707801" }, "timestamp": "2020-08-07T01:30:33.119Z", "ttl": "54m 11s 767ms", "block_hash": "315210f005e7d2d7130004f0178c29cf7e4718d8b642f3f832a35a028ed094cf", "execution_result": { "Version1": { "Success": { "effect": { "operations": [], "transforms": [ { "key": "12730438218135504636", "transform": { "AddUInt256": "16420226327505839383" } }, { "key": "10696215255214620472", "transform": { "AddUInt256": "14018730981435988852" } }, { "key": "15638241704090226222", "transform": { "AddUInt256": "2486508393436959391" } } ] }, "transfers": [], "cost": "2379796918402242989" } } }, "messages": [ { "entity_addr": "entity-contract-a8648307789543cbf38afb24c970844e755654d462a25624edd775219d0cdacf", "message": { "String": "Sax8BEJtXE6vRPXMqOruOhyDxar7N70OeiyPVtfYqiOVNzvHThJwennWwoOs3HHd" }, "topic_name": "PTgw4HZ6CPRhYmSSBbXsI0rnMOcQXgrr", "topic_name_hash": "54a3c9afacf3d475ed69af9de5d4f5496798af12d914aa7f5f8b5cec9935096f", "topic_index": 4003932854, "block_index": 2261021254199878090 } ] }}
id:21821471

:

:

:
```

--------------------------------

### Sample JSON-RPC Request

Source: https://github.com/casper-network/casper-sidecar/blob/dev/json_rpc/README.md

Example `curl` command to send a POST request to a JSON-RPC endpoint.

```sh
curl -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"id","method":"get"}' http://127.0.0.1:3030/rpc
```

--------------------------------

### Install Casper Sidecar Debian Package

Source: https://github.com/casper-network/casper-sidecar/blob/dev/resources/ETC_README.md

Installs the Casper Sidecar Debian package. Ensure the package path is correct.

```bash
sudo apt install ./casper-sidecar_0.1.0-0_amd64.deb
```

--------------------------------

### Sample JSON-RPC Response

Source: https://github.com/casper-network/casper-sidecar/blob/dev/json_rpc/README.md

Example JSON-RPC response indicating a successful result.

```json
{"jsonrpc":"2.0","id":"id","result":"got it"}
```

--------------------------------

### Discover Available RPC Methods

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Use `curl` to send a POST request to the `rpc.discover` method on port 7777 to get a list of all supported RPC methods and their parameters.

```bash
curl -X POST http://localhost:7777/rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "method": "rpc.discover", "id": 1}'
```

--------------------------------

### Missing filter example

Source: https://github.com/casper-network/casper-sidecar/blob/dev/USAGE.md

If no filter URL was specified after the root address (HOST:PORT), an error message will be returned.

```APIDOC
## GET /

### Description
This endpoint is not valid. Accessing the root URL without a specified filter path will result in an error.

### Method
GET

### Endpoint
`/`

### Response
#### Error Response (400)
- **code** (integer) - The error code.
- **message** (string) - A message indicating an invalid request path.

### Response Example
```json
{
  "code": 400,
  "message": "Invalid request path provided"
}
```
```

--------------------------------

### Get Step by Era

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves the Step event emitted at the end of a specific era. Step events contain auction state updates.

```bash
curl -s http://127.0.0.1:18888/step/7268
```

--------------------------------

### Discover Available JSON-RPC Methods

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

The RPC API server exposes a JSON-RPC 2.0 interface on port 7777. Use the `rpc.discover` method to get a list of all supported RPC methods and their parameters.

```APIDOC
## JSON-RPC API — Discover Available Methods

The RPC API server exposes a JSON-RPC 2.0 interface on port 7777 (configurable). It forwards requests to the Casper node's binary port. The full list of supported methods is discoverable via the `rpc.discover` method.

```bash
curl -X POST http://localhost:7777/rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "method": "rpc.discover", "id": 1}'

# Returns a JSON object describing all available RPC methods and their parameters.
# Example for chain_get_block (get latest block, cached if enable_block_prefetch = true):
curl -X POST http://localhost:7777/rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "method": "chain_get_block", "id": 2}'

# Example for querying a specific block by hash:
curl -X POST http://localhost:7777/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "chain_get_block",
    "params": {
      "block_identifier": {
        "Hash": "290eb1ecd5c4e8bda94dae647fb9c21aeb531fe817467abb60f7c12be6a672eb"
      }
    },
    "id": 3
  }'
```
```

--------------------------------

### Build and Run a JSON-RPC Server

Source: https://github.com/casper-network/casper-sidecar/blob/dev/json_rpc/README.md

Demonstrates how to construct request handlers using RequestHandlersBuilder, register them, and set up a Warp filter for a JSON-RPC server. Requires `tokio` and `hyper`.

```rust
use casper_json_rpc::{ConfigLimit, Error, Params, RequestHandlersBuilder};
use std::{convert::Infallible};

async fn get(params: Option<Params>) -> Result<String, Error> {
    // * parse params or return `ReservedErrorCode::InvalidParams` error
    // * handle request and return result
    Ok("got it".to_string())
}

async fn put(params: Option<Params>, other_input: &str) -> Result<String, Error> {
    Ok(other_input.to_string())
}

#[tokio::main]
async fn main() {
    // Register handlers for methods "get" and "put".
    let mut handlers = RequestHandlersBuilder::new();
    let limit = ConfigLimit::default();
    handlers.register_handler("get", get, &limit);
    let put_handler = move |params| async move { put(params, "other input").await };
    handlers.register_handler("put", put_handler, &limit);
    let handlers = handlers.build();

    // Get the new route.
    let path = "rpc";
    let max_body_bytes = 1024;
    let route = casper_json_rpc::route(path, max_body_bytes, handlers);

    // Convert it into a `Service` and run it.
    let make_svc = hyper::service::make_service_fn(move |_| {
        let svc = warp::service(route.clone());
        async move { Ok::<_, Infallible>(svc.clone()) }
    });

    hyper::Server::bind(&([127, 0, 0, 1], 3030).into())
        .serve(make_svc)
        .await
        .unwrap();
}
```

--------------------------------

### Retrieve Latest Block Information

Source: https://github.com/casper-network/casper-sidecar/blob/dev/USAGE.md

Use this endpoint to get details about the most recent block added to the linear chain. No specific setup is required beyond having the sidecar running.

```sh
curl -s http://127.0.0.1:18888/block
```

--------------------------------

### Configure PostgreSQL via Environment Variables

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Set these environment variables to configure PostgreSQL credentials for the Casper Sidecar. These settings take precedence over the TOML configuration.

```bash
export SIDECAR_POSTGRES_USERNAME="postgres"
export SIDECAR_POSTGRES_PASSWORD="p@\$\$w0rd"
export SIDECAR_POSTGRES_DATABASE_NAME="event_sidecar"
export SIDECAR_POSTGRES_HOST="localhost"
export SIDECAR_POSTGRES_MAX_CONNECTIONS="30"
export SIDECAR_POSTGRES_PORT="5432"

RUST_LOG=info cargo run -p casper-sidecar -- \
  --path-to-config ./resources/example_configs/EXAMPLE_NCTL_POSTGRES_CONFIG.toml
```

--------------------------------

### Configure RPC Server Settings

Source: https://github.com/casper-network/casper-sidecar/blob/dev/README.md

Use this TOML configuration to set up the main RPC API server, speculative execution server, and node client. Adjust IP addresses, ports, rate limits, and timeouts as needed.

```toml
[rpc_server.main_server]
enable_server = true
enable_block_prefetch = true
ip_address = '0.0.0.0'
port = 7777
qps_limit = 100
max_body_bytes = 2_621_440
cors_origin = ''
default_limit_requests = 100
default_limit_period = "1s"

[rpc_server.node_client]
ip_address = '0.0.0.0'
port = 28101
max_message_size_bytes = 4_194_304
message_timeout_secs = 10
client_access_timeout_secs = 10
keepalive_timeout_ms = 4_000

[rpc_server.speculative_exec_server]
enable_server = true
ip_address = '0.0.0.0'
port = 7778
qps_limit = 1
max_body_bytes = 2_621_440
cors_origin = ''


[rpc_server.node_client.exponential_backoff]
initial_delay_ms = 1000
max_delay_ms = 32_000
coefficient = 2
max_attempts = 30

```

--------------------------------

### Configuring SSE Node Connections

Source: https://github.com/casper-network/casper-sidecar/blob/dev/README.md

Sets up connections to Casper nodes for the SSE server. Multiple `[[sse_server.connections]]` sections can be used to connect to several nodes.

```toml
[sse_server]
enable_server = true
disable_event_persistence = false

[[sse_server.connections]]
ip_address = "127.0.0.1"
sse_port = 18101
rest_port = 14101
max_attempts = 10
delay_between_retries_in_seconds = 5
allow_partial_connection = false
enable_logging = true
connection_timeout_in_seconds = 3
no_message_timeout_in_seconds = 60
sleep_between_keep_alive_checks_in_seconds = 30

[[sse_server.connections]]
ip_address = "127.0.0.1"
sse_port = 18102
rest_port = 14102
max_attempts = 10
delay_between_retries_in_seconds = 5
allow_partial_connection = false
enable_logging = false
connection_timeout_in_seconds = 3
no_message_timeout_in_seconds = 60
sleep_between_keep_alive_checks_in_seconds = 30

[[sse_server.connections]]
ip_address = "127.0.0.1"
sse_port = 18103
rest_port = 14103
max_attempts = 10
delay_between_retries_in_seconds = 5
allow_partial_connection = false
enable_logging = false
connection_timeout_in_seconds = 3
no_message_timeout_in_seconds = 60
sleep_between_keep_alive_checks_in_seconds = 30
```

--------------------------------

### Configure SQLite Database

Source: https://github.com/casper-network/casper-sidecar/blob/dev/README.md

Set up the SQLite database connection details, including file name, maximum pool connections, and WAL autocheckpointing interval. The database file is stored within the 'storage_folder'.

```toml
[storage.sqlite_config]
file_name = "sqlite_database.db3"
max_connections_in_pool = 100
wal_autocheckpointing_interval = 1000
```

--------------------------------

### Run Sidecar with Configuration File

Source: https://github.com/casper-network/casper-sidecar/blob/dev/README.md

Execute the Sidecar application using Cargo, specifying the path to the TOML configuration file. Requires root privileges.

```sh
sudo cargo run -- --path-to-config ./resources/example_configs/EXAMPLE_NODE_CONFIG.toml
```

--------------------------------

### Get Finality Signatures by Block

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves all stored FinalitySignature events associated with a specific block hash.

```bash
curl -s http://127.0.0.1:18888/signatures/85aa2a939bc3a4afc6d953c965bab333bb5e53185b96bb07b52c295164046da2
```

--------------------------------

### Basic SSE Server Configuration

Source: https://github.com/casper-network/casper-sidecar/blob/dev/README.md

Enables the SSE server and specifies legacy APIs to emulate. `disable_event_persistence` can be set to true to use the sidecar as a pass-through.

```toml
[sse_server]
enable_server = true
emulate_legacy_sse_apis = ["V1"]
disable_event_persistence = false

[[sse_server.connections]]
 <Described later in the document>

[sse_server.event_stream_server]
 <Described later in the document>
```

--------------------------------

### Get Accepted Transaction

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves only the TransactionAccepted event for a specific transaction using its version 1 hash.

```bash
curl -s http://127.0.0.1:18888/transaction/accepted/version1/942785a412289a5aaffdb01d58ee91478bb0cc6b68646519531f4e859ed80566
```

--------------------------------

### Configure Sidecar Storage Folder

Source: https://github.com/casper-network/casper-sidecar/blob/dev/resources/ETC_README.md

TOML configuration snippet for setting the storage folder for SSE cache and SQLite database.

```toml
[storage]
storage_folder = "./target/storage"
```

--------------------------------

### Configure PostgreSQL Connection Settings

Source: https://github.com/casper-network/casper-sidecar/blob/dev/README.md

Configure PostgreSQL connection parameters directly within the Sidecar's TOML configuration file.

```toml
[storage.postgresql_config]
database_name = "event_sidecar"
host = "localhost"
database_password = "p@$$w0rd"
database_username = "postgres"
max_connections_in_pool = 30
```

--------------------------------

### REST API — Get Block by Height

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves a stored `BlockAdded` event using its numeric chain height.

```APIDOC
## REST API — Get Block by Height

Retrieves a stored `BlockAdded` event by its numeric chain height.

### Method
GET

### Endpoint
/block/{height}

### Parameters
#### Path Parameters
- **height** (integer) - Required - The numeric height of the block to retrieve.

### Response
#### Success Response (200)
- The response structure is identical to the `/block` endpoint, for the block at the given height.

#### Error Response (404)
- Returns 404 if the specified height has not been stored yet.

### Request Example
```bash
curl -s http://127.0.0.1:18888/block/2467498
```
```

--------------------------------

### Get Expired Transaction

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves a stored `TransactionExpired` event for a specific transaction hash. This endpoint is used to check if a transaction has expired.

```APIDOC
## GET /transaction/expired/version1/{hash}

### Description
Retrieves a stored `TransactionExpired` event for a specific transaction hash.

### Method
GET

### Endpoint
`/transaction/expired/version1/{hash}`

### Parameters
#### Path Parameters
- **hash** (string) - Required - The hash of the transaction to retrieve.

### Response
#### Success Response (200)
- **header** (object) - API version and network name.
- **payload** (object) - Contains the transaction hash for the expired transaction.
```

--------------------------------

### Configure SSE Legacy Emulation

Source: https://github.com/casper-network/casper-sidecar/blob/dev/README.md

Enable emulation of V1 SSE APIs by setting 'emulate_legacy_sse_apis' to ["V1"]. This allows applications using version 1 of the Casper node's event stream server to function.

```toml
[sse_server]
enable_server = true
emulate_legacy_sse_apis = ["V1"]
disable_event_persistence = false
```

--------------------------------

### Get Expired Transaction

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves a stored TransactionExpired event for a specific transaction hash. The version 1 hash is used for this query.

```bash
curl -s http://127.0.0.1:18888/transaction/expired/version1/3dcf9cb73977a1163129cb0801163323bea2a780815bc9dc46696a43c00e658c
```

--------------------------------

### Build Custom JSON-RPC Server with `casper-json-rpc`

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

This Rust code demonstrates how to build a custom JSON-RPC 2.0 server using the `casper-json-rpc` crate. It includes registering a handler for `chain_get_block` and setting up a Warp-based route.

```rust
use casper_json_rpc::{ConfigLimit, Error, Params, RequestHandlersBuilder};
use std::convert::Infallible;

// Handler for the "chain_get_block" method
async fn chain_get_block(params: Option<Params>) -> Result<serde_json::Value, Error> {
    // Parse optional block_identifier from params
    let block_id = params
        .and_then(|p| serde_json::from_value::<serde_json::Value>(p.into()).ok());

    Ok(serde_json::json!({ "block": { "hash": "abc123", "height": 42 } }))
}

// Custom error codes
#[derive(Copy, Clone, Eq, PartialEq, serde::Serialize, serde::Deserialize, Debug)]
#[repr(i64)]
pub enum RpcErrorCode {
    NoSuchBlock = -1,
    NodeUnavailable = -2,
}

impl From<RpcErrorCode> for (i64, &'static str) {
    fn from(code: RpcErrorCode) -> Self {
        match code {
            RpcErrorCode::NoSuchBlock    => (code as i64, "No such block"),
            RpcErrorCode::NodeUnavailable => (code as i64, "Node unavailable"),
        }
    }
}
impl casper_json_rpc::ErrorCodeT for RpcErrorCode {}

#[tokio::main]
async fn main() {
    let mut handlers = RequestHandlersBuilder::new();
    let limit = ConfigLimit::default();           // default rate limit (no cap)

    handlers.register_handler("chain_get_block", chain_get_block, &limit);

    let handlers = handlers.build();
    let route = casper_json_rpc::route("rpc", 4_000_000, handlers);

    let make_svc = hyper::service::make_service_fn(move |_| {
        let svc = warp::service(route.clone());
        async move { Ok::<_, Infallible>(svc) }
    });

    hyper::Server::bind(&([0, 0, 0, 0], 7777).into())
        .serve(make_svc)
        .await
        .unwrap();
}

// Test the server:
// curl -X POST http://127.0.0.1:7777/rpc \
//   -H 'Content-Type: application/json' \
//   -d '{"jsonrpc":"2.0","id":"1","method":"chain_get_block"}'
// → {"jsonrpc":"2.0","id":"1","result":{"block":{"hash":"abc123","height":42}}}

```

--------------------------------

### REST API — Get Block by Hash

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves a stored `BlockAdded` event using its 64-character hexadecimal block hash.

```APIDOC
## REST API — Get Block by Hash

Retrieves a stored `BlockAdded` event by its 64-hex-character block hash.

### Method
GET

### Endpoint
/block/{block_hash}

### Parameters
#### Path Parameters
- **block_hash** (string) - Required - The 64-hex-character hash of the block to retrieve.

### Response
#### Success Response (200)
- The response structure is identical to the `/block` endpoint, containing the specific requested block.

#### Error Response (400)
- **code** (integer) - 400
- **message** (string) - "Invalid request path provided" for malformed hashes.

### Request Example
```bash
curl -s http://127.0.0.1:18888/block/290eb1ecd5c4e8bda94dae647fb9c21aeb531fe817467abb60f7c12be6a672eb
```
```

--------------------------------

### Get Latest Block Information

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Query the `chain_get_block` method via `curl` to retrieve the latest block details. This can be cached if `enable_block_prefetch` is true.

```bash
curl -X POST http://localhost:7777/rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "method": "chain_get_block", "id": 2}'
```

--------------------------------

### Get Finality Signatures by Block

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves all stored `FinalitySignature` events associated with a specific block hash. This is useful for verifying block finality.

```APIDOC
## GET /signatures/{blockHash}

### Description
Retrieves all stored `FinalitySignature` events associated with a specific block hash.

### Method
GET

### Endpoint
`/signatures/{blockHash}`

### Parameters
#### Path Parameters
- **blockHash** (string) - Required - The hash of the block to retrieve finality signatures for.

### Response
#### Success Response (200)
- Returns an array of `FinalitySignature` events for the given block.
```

--------------------------------

### Enable Admin API Server

Source: https://github.com/casper-network/casper-sidecar/blob/dev/README.md

Configure the Sidecar's administrative server to be enabled and set its port and request limits.

```toml
[admin_api_server]
enable_server = true
port = 18887
max_concurrent_requests = 1
max_requests_per_second = 1
```

--------------------------------

### Get Processed Transaction

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves only the TransactionProcessed event for a specific transaction, including its execution result. Use the version 1 hash for retrieval.

```bash
curl -s http://127.0.0.1:18888/transaction/processed/version1/8204af872d7d19ef8da947bce67c7a55449bc4e2aa12d2756e9ec7472b4854f7
```

--------------------------------

### Configure Sidecar Storage Path

Source: https://github.com/casper-network/casper-sidecar/blob/dev/resources/ETC_README.md

TOML configuration snippet for setting the storage path for SSE cache and database. Ensure this path is writable by the service.

```toml
[storage]
storage_path = "/var/lib/casper-sidecar"
```

--------------------------------

### Enable Legacy SSE Emulation

Source: https://github.com/casper-network/casper-sidecar/blob/dev/LEGACY_SSE_EMULATION.md

To enable legacy SSE emulation, set the `emulate_legacy_sse_apis` configuration option to `["V1"]`. This is the only supported value currently.

```toml
[sse_server]
(...) 
emulate_legacy_sse_apis = ["V1"]
(...)

```

--------------------------------

### Get Accepted Transaction

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves only the `TransactionAccepted` event for a specific transaction. This endpoint is useful for checking the initial acceptance of a deploy without full processing details.

```APIDOC
## GET /transaction/accepted/version1/{hash}

### Description
Retrieves only the `TransactionAccepted` event for a specific transaction.

### Method
GET

### Endpoint
`/transaction/accepted/version1/{hash}`

### Parameters
#### Path Parameters
- **hash** (string) - Required - The hash of the transaction to retrieve.

### Response
#### Success Response (200)
- **header** (object) - API version and network name.
- **payload** (object) - Contains the `Version1` transaction details, including hash, payload, and approvals.
```

--------------------------------

### Get Processed Transaction

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves only the `TransactionProcessed` event for a specific transaction, including the full execution result with state transforms. This endpoint provides details on how a transaction was executed.

```APIDOC
## GET /transaction/processed/version1/{hash}

### Description
Retrieves only the `TransactionProcessed` event for a specific transaction, including the full execution result with state transforms.

### Method
GET

### Endpoint
`/transaction/processed/version1/{hash}`

### Parameters
#### Path Parameters
- **hash** (string) - Required - The hash of the transaction to retrieve.

### Response
#### Success Response (200)
- **header** (object) - API version and network name.
- **payload** (object) - Contains transaction processing details, including hash, initiator, block hash, execution result, and messages.
```

--------------------------------

### Configure PostgreSQL Host

Source: https://github.com/casper-network/casper-sidecar/blob/dev/README.md

Set the environment variable for the PostgreSQL host. This method takes precedence over configuration file settings.

```bash
SIDECAR_POSTGRES_HOST="your host"
```

--------------------------------

### Get Faults by Public Key or Era

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves stored Fault events. The path parameter can be a validator public key (hex string) or an era ID (integer).

```bash
# Faults for a specific validator public key
curl -s http://127.0.0.1:18888/faults/01a601840126a0363a6048bfcbb0492ab5a313a1a19dc4c695650d8f3b51302703
```

```bash
# Faults from a specific era
curl -s http://127.0.0.1:18888/faults/2304
```

--------------------------------

### SSE API — Legacy V1 Emulation Endpoints

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Exposes three additional endpoints that mirror the Casper 1.x node SSE layout, translating 2.x events into the legacy 1.x format for backward-compatible clients when `emulate_legacy_sse_apis` is set to `["V1"]`.

```APIDOC
## SSE API — Legacy V1 Emulation Endpoints

When `emulate_legacy_sse_apis = ["V1"]` is set, the sidecar exposes three additional endpoints that mirror the three-endpoint layout of Casper 1.x nodes, translating 2.x events into the legacy 1.x format for backward-compatible clients.

### Method
GET

### Endpoint
/events/main

### Description
Emits `ApiVersion`, `BlockAdded`, `DeployProcessed`, `DeployExpired`, `Fault`, `Shutdown` events.

### Request Example
```bash
curl -sN http://127.0.0.1:19999/events/main
```

### Method
GET

### Endpoint
/events/deploys

### Description
Emits `ApiVersion`, `DeployAccepted`, `Shutdown` events.

### Request Example
```bash
curl -sN http://127.0.0.1:19999/events/deploys
```

### Method
GET

### Endpoint
/events/sigs

### Description
Emits `ApiVersion`, `FinalitySignature`, `Shutdown` events.

### Request Example
```bash
curl -sN http://127.0.0.1:19999/events/sigs
```
```

--------------------------------

### REST API — Get Latest Block

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves the most recently stored `BlockAdded` event. This endpoint can serve as a liveness check for the sidecar's event ingestion.

```APIDOC
## REST API — Get Latest Block

Retrieves the most recently stored `BlockAdded` event. Useful as a liveness check — if the timestamp in the response is more than ~60 seconds old, the sidecar may not be receiving events.

### Method
GET

### Endpoint
/block

### Response
#### Success Response (200)
- **payload** (object) - Contains the `BlockAdded` event details.
  - **BlockAdded** (object)
    - **block_hash** (string) - The hash of the block.
    - **block** (object) - The block data.
      - **Version2** (object)
        - **header** (object)
          - **timestamp** (string) - The timestamp of the block.
          - **era_id** (integer) - The era ID of the block.
          - **height** (integer) - The height of the block.
          - **protocol_version** (string) - The protocol version used for the block.
          - **proposer** (string) - The public key of the block proposer.
          - **current_gas_price** (integer) - The current gas price at the time of the block.
        - **body** (object)
          - **transactions** (object) - A map of transaction indices to transaction details.
          - **rewarded_signatures** (array) - List of rewarded signatures.

### Request Example
```bash
curl -s http://127.0.0.1:18888/block
```

### Response Example
```json
{
  "header": { "api_version": "2.0.0", "network_name": "casper" },
  "payload": {
    "BlockAdded": {
      "block_hash": "290eb1ecd5c4e8bda94dae647fb9c21aeb531fe817467abb60f7c12be6a672eb",
      "block": {
        "Version2": {
          "hash": "290eb1ecd5c4e8bda94dae647fb9c21aeb531fe817467abb60f7c12be6a672eb",
          "header": {
            "timestamp": "2025-04-28T10:12:52.090Z",
            "era_id": 246749,
            "height": 2467498,
            "protocol_version": "1.0.0",
            "proposer": "0203c5ecdb1ad56b65cbc7dbbf99ea492e7566a6b2259191f9ab604c58b19d2a01f3",
            "current_gas_price": 1,
            ...
          },
          "body": { "transactions": { "1": [...], "3": [...] }, "rewarded_signatures": [] }
        }
      }
    }
  }
}
```
```

--------------------------------

### Build a Custom JSON-RPC Server with `casper-json-rpc`

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

The `casper-json-rpc` crate provides a framework for building JSON-RPC 2.0 servers. You can register custom handlers for methods like `chain_get_block` and configure rate limiting.

```APIDOC
## `casper-json-rpc` Library — Build a Custom JSON-RPC Server

The `casper-json-rpc` crate provides a reusable warp-based framework for building JSON-RPC 2.0 servers with per-method rate limiting. Register handlers using `RequestHandlersBuilder`, then pass the result to `casper_json_rpc::route`.

```rust
use casper_json_rpc::{ConfigLimit, Error, Params, RequestHandlersBuilder};
use std::convert::Infallible;

// Handler for the "chain_get_block" method
async fn chain_get_block(params: Option<Params>) -> Result<serde_json::Value, Error> {
    // Parse optional block_identifier from params
    let block_id = params
        .and_then(|p| serde_json::from_value::<serde_json::Value>(p.into()).ok());

    Ok(serde_json::json!({ "block": { "hash": "abc123", "height": 42 } }))
}

// Custom error codes
#[derive(Copy, Clone, Eq, PartialEq, serde::Serialize, serde::Deserialize, Debug)]
#[repr(i64)]
pub enum RpcErrorCode {
    NoSuchBlock = -1,
    NodeUnavailable = -2,
}

impl From<RpcErrorCode> for (i64, &'static str) {
    fn from(code: RpcErrorCode) -> Self {
        match code {
            RpcErrorCode::NoSuchBlock    => (code as i64, "No such block"),
            RpcErrorCode::NodeUnavailable => (code as i64, "Node unavailable"),
        }
    }
}
impl casper_json_rpc::ErrorCodeT for RpcErrorCode {}

#[tokio::main]
async fn main() {
    let mut handlers = RequestHandlersBuilder::new();
    let limit = ConfigLimit::default();           // default rate limit (no cap)

    handlers.register_handler("chain_get_block", chain_get_block, &limit);

    let handlers = handlers.build();
    let route = casper_json_rpc::route("rpc", 4_000_000, handlers);

    let make_svc = hyper::service::make_service_fn(move |_| {
        let svc = warp::service(route.clone());
        async move { Ok::<_, Infallible>(svc) }
    });

    hyper::Server::bind(&([0, 0, 0, 0], 7777).into())
        .serve(make_svc)
        .await
        .unwrap();
}

// Test the server:
// curl -X POST http://127.0.0.1:7777/rpc \
//   -H 'Content-Type: application/json' \
//   -d '{"jsonrpc":"2.0","id":"1","method":"chain_get_block"}'
// → {"jsonrpc":"2.0","id":"1","result":{"block":{"hash":"abc123","height":42}}}
```
```

--------------------------------

### Get Block by Chain Height

Source: https://github.com/casper-network/casper-sidecar/blob/dev/USAGE.md

Retrieves detailed information about a specific block on the Casper network using its chain height. This endpoint is useful for querying historical block data.

```APIDOC
## GET /block/<block-height>

### Description
Retrieves information about a block, given a specific block height. Enter a valid number representing the block height.

### Method
GET

### Endpoint
`/block/<block-height>`

### Parameters
#### Path Parameters
- **block-height** (number) - Required - The height of the block to retrieve.

### Request Example
```sh
curl -s http://127.0.0.1:18888/block/3467498
```

### Response
#### Success Response (200)
- **header** (object) - Contains API version and network name.
- **payload** (object) - Contains the block data.
  - **BlockAdded** (object) - Details of the block addition event.
    - **block_hash** (string) - The unique hash of the block.
    - **block** (object) - The block object containing header and body.
      - **Version2** (object) - Block structure for version 2.
        - **hash** (string) - The block's hash.
        - **header** (object) - The block's header information.
          - **parent_hash** (string) - Hash of the parent block.
          - **state_root_hash** (string) - Root hash of the state.
          - **body_hash** (string) - Hash of the block body.
          - **random_bit** (boolean) - Random bit value.
          - **accumulated_seed** (string) - Accumulated seed value.
          - **era_end** (null) - Era end information (currently null).
          - **timestamp** (string) - Timestamp of the block.
          - **era_id** (number) - Era ID.
          - **height** (number) - The block's height.
          - **protocol_version** (string) - Protocol version.
          - **proposer** (string) - Address of the block proposer.
          - **current_gas_price** (number) - Current gas price.
          - **last_switch_block_hash** (string) - Hash of the last switch block.
        - **body** (object) - The block's body.
          - **transactions** (object) - Transactions included in the block, categorized by type.
          - **rewarded_signatures** (array) - Rewarded signatures.

### Response Example
```json
{
  "header": { "api_version": "2.0.0", "network_name": "some-network" },
  "payload": {
    "BlockAdded": {
      "block_hash": "290eb1ecd5c4e8bda94dae647fb9c21aeb531fe817467abb60f7c12be6a672eb",
      "block": {
        "Version2": {
          "hash": "290eb1ecd5c4e8bda94dae647fb9c21aeb531fe817467abb60f7c12be6a672eb",
          "header": {
            "parent_hash": "3236c683ec5f220c1936a25a0be96b976cfbe784f06d2319933b432f2a1fe1eb",
            "state_root_hash": "89ba71746096011be36cda29fdf1d1bd8067af51a0ea7eaf65e90666a35bcbf6",
            "body_hash": "11b6c10321aea27c2fc4d292f570a93b32488759c16cf9ee22e747c35c3873fc",
            "random_bit": true,
            "accumulated_seed": "e376199ca38015a57760e9431fc6723e9500ab3f18c93a26830b5b4ccc9f6a29",
            "era_end": null,
            "timestamp": "2025-04-28T10:12:52.090Z",
            "era_id": 246749,
            "height": 3467498,
            "protocol_version": "1.0.0",
            "proposer": "0203c5ecdb1ad56b65cbc7dbbf99ea492e7566a6b2259191f9ab604c58b19d2a01f3",
            "current_gas_price": 1,
            "last_switch_block_hash": "0808080808080808080808080808080808080808080808080808080808080808"
          },
          "body": {
            "transactions": {
              "0": [],
              "1": [
                { "Version1": "1f3b12822cfa6ef26d8f1e369ffbab37fa0e963385d124db5ab09ba22d2ec452" },
                { "Version1": "a13c6a737a926562a02e88f62bf84c3811f2fe20bcc6a9b1454802640dfc730d" }
              ],
              "2": [],
              "3": [
                { "Deploy": "5825b4fcdb6e180bd80f83d743910b16e6217dd4e74d1147ac0eb656214ab5d4" },
                { "Deploy": "e83a459beef99015de50e3c33ba0acbe658aea8f0b72f0f55599889dc3025b68" }
              ],
              "4": [],
              "5": []
            },
            "rewarded_signatures": []
          }
        }
      }
    }
  }
}
```
```

--------------------------------

### Get Step by Era

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves the `Step` event emitted at the end of a specific era. Step events contain auction state updates including validator rewards and evictions.

```APIDOC
## GET /step/{era}

### Description
Retrieves the `Step` event emitted at the end of a specific era. Step events contain auction state updates including validator rewards and evictions.

### Method
GET

### Endpoint
`/step/{era}`

### Parameters
#### Path Parameters
- **era** (integer) - Required - The era ID to retrieve the step event for.

### Response
#### Success Response (200)
- Returns the `Step` event for the specified era.
```

--------------------------------

### Configure PostgreSQL Max Connections

Source: https://github.com/casper-network/casper-sidecar/blob/dev/README.md

Set the environment variable for the maximum number of connections to the PostgreSQL database. This method takes precedence over configuration file settings.

```bash
SIDECAR_POSTGRES_MAX_CONNECTIONS="max connections"
```

--------------------------------

### REST API — Get Transaction Aggregate by Hash

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Returns an aggregate of all stored lifecycle events for a single transaction, identified by type and hash. This is a synthesized response from the sidecar.

```APIDOC
## REST API — Get Transaction Aggregate by Hash

Returns an aggregate of all stored lifecycle events (`TransactionAccepted`, `TransactionProcessed`, `TransactionExpired`) for a single transaction identified by type (`deploy` or `version1`) and hash. This is a sidecar-synthesized response, not a raw node event.

### Method
GET

### Endpoint
/transaction/{type}/{hash}

### Parameters
#### Path Parameters
- **type** (string) - Required - The type of the transaction, either `deploy` or `version1`.
- **hash** (string) - Required - The hash of the transaction.

### Response
#### Success Response (200)
- **transaction_hash** (string) - The hash of the transaction.

### Request Example
```bash
# Query a Version1 transaction
curl -s http://127.0.0.1:18888/transaction/version1/3141e85f8075c3a75c2a1abcc79810c07d103ff97c03200ab0d0baf91995fe4a
```

### Response Example
```json
{
  "transaction_hash": "3141e85f8075c3a75c2a1abcc79810c07d103ff97c03200ab0d0baf91995fe4a"
}
```
```

--------------------------------

### SSE API — Replay Events from a Specific ID

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Allows clients to request a replay of past events from a known event ID using the `start_from` query parameter. Passing `0` or an ID older than the buffer replays the entire buffer.

```APIDOC
## SSE API — Replay Events from a Specific ID

The sidecar maintains an in-memory ring buffer of past events (size set by `event_stream_buffer_length`). Reconnecting clients can request a replay of all events since a known event ID using the `start_from` query parameter. Passing `0` or an ID older than the buffer replays the entire buffer.

### Method
GET

### Endpoint
/events

### Query Parameters
- **start_from** (integer) - Required - The event ID from which to start replaying events.

### Request Example
```bash
# Replay all events from event ID 29267508 onward
curl -sN 'http://127.0.0.1:19999/events?start_from=29267508'

# zsh requires escaping the '?':
# curl -sN http://127.0.0.1:19999/events\?start_from=29267508

# Replay full buffer (pass id=0)
curl -sN 'http://127.0.0.1:19999/events?start_from=0'
```
```

--------------------------------

### Emulate Legacy V1 SSE APIs

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

When 'emulate_legacy_sse_apis = ["V1"]' is set, the sidecar exposes legacy endpoints (/events/main, /events/deploys, /events/sigs) that mirror Casper 1.x event layouts for backward-compatible clients.

```bash
# /events/main  →  ApiVersion, BlockAdded, DeployProcessed, DeployExpired, Fault, Shutdown
curl -sN http://127.0.0.1:19999/events/main

# /events/deploys  →  ApiVersion, DeployAccepted, Shutdown
curl -sN http://127.0.0.1:19999/events/deploys

# /events/sigs  →  ApiVersion, FinalitySignature, Shutdown
curl -sN http://127.0.0.1:19999/events/sigs

# Example legacy DeployAccepted event emitted on /events/deploys
# (translated from a 2.x TransactionAccepted{"Deploy": {...}} event):
data:{"DeployAccepted":{"hash":"5a7709969c210db93d3c21bf49f8bf705d7c75a01609f606d04b0211af171d43","header":{...},"approvals":[...]}}
```

--------------------------------

### Get Faults by Public Key or Era

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Retrieves stored `Fault` events. The path parameter can be either a validator's public key (hex string) or an era ID (integer).

```APIDOC
## GET /faults/{identifier}

### Description
Retrieves stored `Fault` events. The path parameter is interpreted as a public key (hex string) or an era ID (integer) depending on its format.

### Method
GET

### Endpoint
`/faults/{identifier}`

### Parameters
#### Path Parameters
- **identifier** (string or integer) - Required - The validator public key (hex string) or era ID (integer) to query faults for.

### Response
#### Success Response (200)
- Returns an array of `Fault` events.
```

--------------------------------

### Replay Events from a Specific ID using SSE

Source: https://context7.com/casper-network/casper-sidecar/llms.txt

Replay past events from the sidecar's in-memory buffer using the 'start_from' query parameter on the /events endpoint. Passing '0' or an ID older than the buffer replays the entire buffer.

```bash
# Replay all events from event ID 29267508 onward
curl -sN 'http://127.0.0.1:19999/events?start_from=29267508'

# zsh requires escaping the '?':
# curl -sN http://127.0.0.1:19999/events\?start_from=29267508

# Replay full buffer (pass id=0)
curl -sN 'http://127.0.0.1:19999/events?start_from=0'
```