{"id":35780207,"url":"https://github.com/casper-network/casper-sidecar","last_synced_at":"2026-01-07T06:00:03.445Z","repository":{"id":225203950,"uuid":"483204525","full_name":"casper-network/casper-sidecar","owner":"casper-network","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-25T13:13:52.000Z","size":16075,"stargazers_count":4,"open_issues_count":29,"forks_count":11,"subscribers_count":6,"default_branch":"dev","last_synced_at":"2025-08-25T15:26:22.325Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/casper-network.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-04-19T10:46:10.000Z","updated_at":"2025-07-31T16:21:52.000Z","dependencies_parsed_at":"2024-07-05T19:18:17.538Z","dependency_job_id":"f527b462-a8e2-4afc-bcaa-51d6f57c1837","html_url":"https://github.com/casper-network/casper-sidecar","commit_stats":null,"previous_names":["casper-network/casper-sidecar"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/casper-network/casper-sidecar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-sidecar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-sidecar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-sidecar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-sidecar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/casper-network","download_url":"https://codeload.github.com/casper-network/casper-sidecar/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-sidecar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28233225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-07T02:00:05.975Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-07T06:00:00.783Z","updated_at":"2026-01-07T06:00:03.438Z","avatar_url":"https://github.com/casper-network.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![LOGO](https://raw.githubusercontent.com/casper-network/casper-node/master/images/casper-association-logo-primary.svg)](https://casper.network/)\n\n[![License](https://img.shields.io/badge/license-Apache-blue)](https://github.com/CasperLabs/casper-node/blob/master/LICENSE)\n\n# The Casper Sidecar\n\n- [Summary of Purpose](#summary-of-purpose)\n- [System Components and Architecture](#system-components-and-architecture)\n  - [The SSE server](#the-sse-server)\n  - [The REST API server](#the-rest-api-server)\n  - [The Admin API server](#the-admin-api-server)\n  - [The RPC API server](#the-rpc-api-server)\n- [Configuring the Sidecar](#configuring-the-sidecar)\n  - [RPC server setup](#rpc-server-setup)\n  - [SSE server setup](#sse-server-setup)\n    - [Configuring SSE node connections](#configuring-sse-node-connections)\n    - [Configuring SSE legacy emulations](#configuring-sse-legacy-emulations)\n    - [Configuring the event stream](#configuring-the-event-stream)\n  - [REST server setup](#rest-server-setup)\n  - [Storage setup](#setup-storage)\n  - [Database connectivity setup](#database-connectivity-setup)\n    - [SQLite database](#sqlite-database)\n    - [PostgreSQL database](#postgresql-database)\n  - [Admin server setup](#admin-server-setup)\n- [Running and Testing the Sidecar](#running-and-testing-the-sidecar)\n  - [Prerequisites](#prerequisites)\n  - [Running the Sidecar](#running-the-sidecar)\n  - [Testing the Sidecar](#testing-the-sidecar)\n- [OpenAPI Specification](#openapi-specification)\n- [Troubleshooting Tips](#troubleshooting-tips)\n  - [Checking liveness](#checking-liveness)\n  - [Checking the node connection](#checking-the-node-connection)\n  - [Diagnosing errors](#diagnosing-errors)\n  - [Monitoring memory consumption](#monitoring-memory-consumption)\n  - [Ensuring sufficient storage](#ensuring-sufficient-storage)\n  - [Inspecting the REST API](#inspecting-the-rest-api)\n  - [Limiting concurrent requests](#limiting-concurrent-requests)\n\n## Summary of Purpose\n\nThe Casper Sidecar is an application running in tandem with the node process. It allows subscribers to monitor a node's event stream, query stored events, and query the node's JSON RPC API, thus receiving faster responses and reducing the load placed on the node. Its primary purpose is to:\n\n- Offload the node from broadcasting SSE events to multiple clients.\n- Provide client features that aren't part of the nodes' functionality, nor should they be.\n\nWhile the primary use case for the Sidecar application is running alongside the node on the same machine, it can be run remotely if necessary.\n\n## System Components and Architecture\n\nThe Casper Sidecar provides the following functionalities:\n\n- A server-sent events (SSE) server with an `/events` endpoint that streams all the events received from all connected nodes. The Sidecar also stores these events.\n- A REST API server that allows clients to query stored events.\n- A JSON RPC bridge between end users and a Casper node's binary port.\n- Legacy emulation for clients using older versions of the SSE API.\n\nThe Sidecar has the following components and external dependencies:\n\n```mermaid\n---\ntitle: The Casper Sidecar Components\n---\n   graph LR;\n   subgraph CASPER_SIDECAR\n      SSE_SERVER[\"SSE server\"]\n      RPC_API_SERVER[\"RPC API server (JSON)\"]\n      REST_API[\"Rest API server\"]\n      ADMIN_API[\"Admin API server\"]\n   end\n   CONFIG{{\"Config file (TOML)\"}}\n   CONFIG --\u003e CASPER_SIDECAR\n   STORAGE[(Storage)]\n   NODE_SSE((\"Casper node SSE port\"))\n   NODE_BINARY((\"Casper node binary port\"))\n   RPC_API_SERVER --\u003e NODE_BINARY\n   SSE_SERVER --\u003e NODE_SSE\n   SSE_SERVER --\u003e STORAGE\n   STORAGE --\u003e REST_API\n```\n\n### The SSE server\n\nThe SSE Server has these components:\n\n```mermaid\n   graph TD;\n   CLIENT{Client}\n   CLIENT --\u003e SSE_SERVER_API\n   STORAGE[(\"Storage\")]\n   CONFIG{{\"Config file (TOML)\"}}\n   MAIN --1.reads--\u003e CONFIG\n   NODE_SSE{Node SSE port}\n   SSE_LISTENER --2--\u003e STORAGE\n   NODE_SSE --1--\u003e SSE_LISTENER\n   subgraph CASPER_SIDECAR\n     MAIN[main.rs]\n     MAIN --2.spawns---\u003e SSE_SERVER\n     subgraph SSE_SERVER\n        SSE_SERVER_API[\"SSE API\"]\n        RING_BUFFER[\"Events buffer\"]\n        SSE_SERVER_API --\u003e RING_BUFFER\n        SSE_LISTENER --3--\u003e RING_BUFFER\n        subgraph \"connection\"\n          SSE_LISTENER[\"SSE listener\"]\n        end\n     end\n   end\n```\n\nThe SSE Listener processes events in this order:\n\n1. Fetch an event from the node's SSE port.\n2. Store the event.\n3. Publish the event to the SSE API.\n\nCasper nodes offer an event stream API that returns server-sent events (SSEs) with JSON-encoded data. The Sidecar reads the event stream of all connected nodes, acting as a passthrough and replicating the SSE interface of the connected nodes.\n\nThe Sidecar can:\n\n- Republish the current events from the node to clients listening to Sidecar's SSE API.\n- Publish a configurable number of previous events to clients connecting to the Sidecar's SSE API with `?start_from=` query (similar to the node's SSE API).\n- Store the events in external storage for clients to query them via the Sidecar's REST API.\n\nEnabling and configuring the SSE Server of the Sidecar is optional.\n\n### The REST API server\n\nThe Sidecar offers an optional REST API that allows clients to query the events stored in external storage. You can discover the specific endpoints of the REST API using [OpenAPI](#openapi-specification). The [usage instructions](USAGE.md) provide more details.\n\n```mermaid\n   graph LR;\n   CLIENT{Client}\n   CLIENT --\u003e REST_API\n   STORAGE[(\"Storage\")]\n   REST_API --\u003e STORAGE\n   CONFIG{{\"Config file (TOML)\"}}\n   MAIN --1.reads--\u003e CONFIG\n   subgraph CASPER_SIDECAR\n      MAIN[main.rs]\n      MAIN --2.spawns--\u003e REST_API\n      REST_API[\"REST API\"]\n   end\n```\n\n### The Admin API server\n\nThe Sidecar offers an administrative API to allow an operator to check its current status. The Sidecar operator has the option to enable and configure this API. Please see the [admin server configuration](#admin-server) for details.\n\n```mermaid\n   graph LR;\n   CLIENT{Client}\n   CLIENT --\u003e ADMIN_API\n   CONFIG{{Config file}}\n   MAIN --1.reads--\u003e CONFIG\n   subgraph CASPER_SIDECAR\n      MAIN[main.rs]\n      MAIN --2.spawns--\u003e ADMIN_API\n      ADMIN_API[\"ADMIN API\"]\n   end\n```\n\n### The RPC API server\n\nThe Sidecar also offers an RPC JSON API server that can be enabled and configured so that clients can interact with a Casper network. It is a JSON bridge between end users and a Casper node's binary port. The RPC API server forwards requests to the Casper node's binary port. For more details on how the RPC JSON API works, see the [RPC Sidecar README](rpc_sidecar/README.md).\n\n```mermaid\n   graph LR;\n   CLIENT{Client}\n   CLIENT --\u003e RPC_API\n   CONFIG{{Config file}}\n   MAIN --1.reads--\u003e CONFIG\n   CASPER_NODE((\"Casper Node binary port\"))\n   RPC_API --forwards request--\u003e CASPER_NODE\n   subgraph \"Casper Sidecar\"\n      MAIN[main.rs]\n      MAIN --2.spawns--\u003e RPC_API\n      RPC_API[\"RPC JSON API\"]\n   end\n```\n\n## Configuring the Sidecar\n\nThe Sidecar service must be configured using a `.toml` file specified at runtime.\n\nThis repository contains several sample configuration files that can be used as examples and adjusted according to your scenario:\n\n- [EXAMPLE_NCTL_CONFIG.toml](./resources/example_configs/EXAMPLE_NCTL_CONFIG.toml) - Configuration for connecting to nodes on a local NCTL network. This configuration is used in the unit and integration tests found in this repository.\n- [EXAMPLE_NCTL_POSTGRES_CONFIG.toml](./resources/example_configs/EXAMPLE_NCTL_POSTGRES_CONFIG.toml) - Configuration for using the PostgreSQL database and nodes on a local NCTL network.\n- [EXAMPLE_NODE_CONFIG.toml](./resources/example_configs/EXAMPLE_NODE_CONFIG.toml) - Configuration for connecting to live nodes on a Casper network.\n\nOnce you create the configuration file and are ready to run the Sidecar service, you must provide the configuration as an argument using the `-- --path-to-config` option as described [here](#running-the-sidecar).\n\n### RPC server setup\n\nHere is an example configuration for the RPC API server:\n\n```toml\n[rpc_server.main_server]\nenable_server = true\nenable_block_prefetch = true\nip_address = '0.0.0.0'\nport = 7777\nqps_limit = 100\nmax_body_bytes = 2_621_440\ncors_origin = ''\ndefault_limit_requests = 100\ndefault_limit_period = \"1s\"\n\n[rpc_server.node_client]\nip_address = '0.0.0.0'\nport = 28101\nmax_message_size_bytes = 4_194_304\nmessage_timeout_secs = 10\nclient_access_timeout_secs = 10\nkeepalive_timeout_ms = 4_000\n\n[rpc_server.speculative_exec_server]\nenable_server = true\nip_address = '0.0.0.0'\nport = 7778\nqps_limit = 1\nmax_body_bytes = 2_621_440\ncors_origin = ''\n\n\n[rpc_server.node_client.exponential_backoff]\ninitial_delay_ms = 1000\nmax_delay_ms = 32_000\ncoefficient = 2\nmax_attempts = 30\n```\n\n- `main_server.enable_server` - The RPC API server will be enabled if set to true.\n- `main_server.enable_block_prefetch` - optional (default `false`). If set to `true` the [prefetching blocks feature](#prefetching-blocks-feature) will be enabled\n- `main_server.ip_address` - Ip address under which the main RPC API server will be available.\n- `main_server.port` - Port under which the main RPC API server will be available.\n- `main_server.qps_limit` - The maximum number of requests per second.\n- `main_server.max_body_bytes` - Maximum body size of request to API in bytes.\n- `main_server.cors_origin` - Configures the CORS origin.\n- `main_server.default_limit_requests` - Default limit for the JSON-RPC per action limitation: maximum requests permitted for one action in a period of time\n- `main_server.default_limit_period` - Default period of time for the JSON-RPC request limit in human-readable format\n\n- `speculative_exec_server.enable_server` - If set to true, the speculative RPC API server will be enabled.\n- `speculative_exec_server.ip_address` - Ip address under which the speculative RPC API server will be available.\n- `speculative_exec_server.port` - port under which the speculative RPC API server will be available.\n- `speculative_exec_server.qps_limit` - The maximum number of requests per second.\n- `speculative_exec_server.max_body_bytes` - Maximum body size of request to API in bytes.\n- `speculative_exec_server.cors_origin` - Configures the CORS origin.\n- `speculative_exec_server.default_limit_requests` - Default limit for the JSON-RPC per action limitation: maximum requests permitted for one action in a period of time\n- `speculative_exec_server.default_limit_period` - Default period of time for the JSON-RPC request limit in human-readable format\n\n- `node_client.ip_address` - Ip address of the Casper Node binary port.\n- `node_client.port` - Port of the Casper Node binary port.\n- `node_client.max_message_size_bytes` - Maximum binary port message size in bytes.\n- `node_client.message_timeout_secs` - Timeout for the message.\n- `node_client.client_access_timeout_secs` - Timeout for the client connection.\n- `node_client.keepalive_timeout_ms` - The amount of ms to wait between sending keepalive requests.\n- `node_client.exponential_backoff.initial_delay_ms` - Timeout after the first broken connection (backoff) in milliseconds.\n- `node_client.exponential_backoff.max_delay_ms` - Maximum timeout after a broken connection in milliseconds.\n- `node_client.exponential_backoff.coefficient` - Coefficient for the exponential backoff. The next timeout is calculated as min(`current_timeout * coefficient`, `max_delay_ms`).\n- `node_client.exponential_backoff.max_attempts` - Maximum number of times to try to reconnect to the binary port of the node.\n\n#### Prefetching blocks feature\n\nThe RPC server can be configured to prefetch highest block. To enable this feature set `rpc_server.main_server.enable_block_prefetch` to `true`. If this flag is set to true, the RPC server will observe `BlockAdded` events from the [sse feed](#SSE-server-setup). If a new `BlockAdded` event will be observed, and it's height is higher than any of the heights observed uptill this point in time - the RPC server will fetch the blocks data from binary port in the node. The obtained data will be cached in memory. If someone calls sidecars `chain_get_block` json RPC API requests without params (effectively asking for \"newest\" block) - the cached data will be served.\nThis feature is based both on the RPC and SSE sides of sidecar. If enabled, it will not verify that the SSE feed is operational, enabled or even defined. There will be no error of warning notice if `enable_block_prefetch` is `true` but SSE is not turned on. This mechanism will react to observed `BlockAdded` events, but it won't obstruct the RPCs function if no `BlockAdded` events will be ever observed.\n\n### SSE server setup\n\nThe Sidecar SSE server is used to connect to Casper nodes, listen to events from them, store them locally and re-broadcast them to clients. Here is a sample configuration for the SSE server:\n\n```toml\n[sse_server]\nenable_server = true\nemulate_legacy_sse_apis = [\"V1\"]\ndisable_event_persistence = false\n\n[[sse_server.connections]]\n \u003cDescribed later in the document\u003e\n\n[sse_server.event_stream_server]\n \u003cDescribed later in the document\u003e\n```\n\n- `sse_server.enable_server` - If set to true, the SSE server will be enabled.\n- `sse_server.emulate_legacy_sse_apis` - A list of legacy Casper node SSE APIs to emulate. The Sidecar will expose SSE endpoints that are compatible with specified versions. Please bear in mind that this feature is an emulation and should be used only for transition periods. In most scenarios, having a 1-to-1 mapping of new messages into old formats is impossible, so this can be a process that loses some data and/or doesn't emit all messages that come from the Casper node. See the [Legacy SSE Emulation](./LEGACY_SSE_EMULATION.md) page for more details.\n- `sse_server.inbound_channel_size` - Optional property, if not set defaults to 1000. This property sets size of the internal buffer of events read from the node.\n- `sse_server.outbound_channel_size` - Optional property, if not set defaults to 1000. This property sets size of the internal buffer of events prepared to be sent to the outbound.\n- `sse_server.disable_event_persistence` - If set to true, SSE server will not send events to storage. This is useful if you want to use sidecar only as a pass-through for sse events. The property is optional, if not defined it will behave as false.\n\n#### Configuring SSE node connections\n\nThe Sidecar's SSE component can connect to Casper nodes' SSE endpoints with versions greater or equal to `2.0.0`.\n\nThe `node_connections` option configures the node (or multiple nodes) to which the Sidecar will connect and the parameters under which it will operate with that node. Connecting to multiple nodes requires multiple `[[sse_server.connections]]` sections.\n\n```toml\n[sse_server]\nenable_server = true\ndisable_event_persistence = false\n\n[[sse_server.connections]]\nip_address = \"127.0.0.1\"\nsse_port = 18101\nrest_port = 14101\nmax_attempts = 10\ndelay_between_retries_in_seconds = 5\nallow_partial_connection = false\nenable_logging = true\nconnection_timeout_in_seconds = 3\nno_message_timeout_in_seconds = 60\nsleep_between_keep_alive_checks_in_seconds = 30\n\n[[sse_server.connections]]\nip_address = \"127.0.0.1\"\nsse_port = 18102\nrest_port = 14102\nmax_attempts = 10\ndelay_between_retries_in_seconds = 5\nallow_partial_connection = false\nenable_logging = false\nconnection_timeout_in_seconds = 3\nno_message_timeout_in_seconds = 60\nsleep_between_keep_alive_checks_in_seconds = 30\n\n[[sse_server.connections]]\nip_address = \"127.0.0.1\"\nsse_port = 18103\nrest_port = 14103\nmax_attempts = 10\ndelay_between_retries_in_seconds = 5\nallow_partial_connection = false\nenable_logging = false\nconnection_timeout_in_seconds = 3\nno_message_timeout_in_seconds = 60\nsleep_between_keep_alive_checks_in_seconds = 30\n```\n\n- `sse_server.connections.ip_address` - The IP address of the node to monitor.\n- `sse_server.connections.sse_port` - The node's event stream (SSE) port. This [example configuration](./resources/example_configs/EXAMPLE_NODE_CONFIG.toml) uses port `9999`.\n- `sse_server.connections.rest_port` - The node's REST endpoint for status and metrics. This [example configuration](./resources/example_configs/EXAMPLE_NODE_CONFIG.toml) uses port `8888`.\n- `sse_server.connections.max_attempts` - The maximum number of attempts the Sidecar will make to connect to the node. If set to `0`, the Sidecar will not attempt to connect.\n- `sse_server.connections.delay_between_retries_in_seconds` - The delay between attempts to connect to the node.\n- `sse_server.connections.allow_partial_connection` - Determining whether the Sidecar will allow a partial connection to this node.\n- `sse_server.connections.enable_logging` - This enables the logging of events from the node in question.\n- `sse_server.connections.connection_timeout_in_seconds` - Number of seconds before the connection request times out. This parameter is optional, and defaults to 5.\n- `sse_server.connections.no_message_timeout_in_seconds` - Number of seconds after which the connection will be restarted if no bytes were received. This parameter is optional, and defaults to 120.\n- `sse_server.connections.sleep_between_keep_alive_checks_in_seconds` - Optional parameter specifying the time intervals (in seconds) for checking if the connection is still alive. Defaults to 60.\n\n#### Configuring SSE legacy emulations\n\nApplications using version 1 of a Casper node's event stream server can still function using an emulated V1 SSE API for a limited time. Enabling the V1 SSE API emulation requires the `emulate_legacy_sse_apis` setting to be `[\"V1\"]`:\n\n```toml\n[sse_server]\nenable_server = true\nemulate_legacy_sse_apis = [\"V1\"]\ndisable_event_persistence = false\n```\n\nThis setting will expose three legacy SSE endpoints with the following events streamed on each endpoint:\n\n- `/events/sigs` - Finality Signature events\n- `/events/deploys` - DeployAccepted events\n- `/events/main` - All other legacy events, including BlockAdded, DeployProcessed, DeployExpired, Fault, Step, and Shutdown events\n\nSee the [Legacy SSE Emulation](./LEGACY_SSE_EMULATION.md) page for more details.\n\n#### Configuring the event stream\n\nTo configure the Sidecar's event stream server, specify the following settings:\n\n```toml\n[sse_server.event_stream_server]\nport = 19999\nmax_concurrent_subscribers = 100\nevent_stream_buffer_length = 5000\n```\n\n- `event_stream_server.port` - The port under which the Sidecar's SSE server publishes events.\n- `event_stream_server.max_concurrent_subscribers` - The maximum number of subscribers that can monitor the Sidecar's event stream.\n- `event_stream_server.event_stream_buffer_length` - The number of events that the stream will hold in its buffer for reference when a subscriber reconnects.\n\n### REST server setup\n\nThe following section determines outbound connection criteria for the Sidecar's REST server.\n\n```toml\n[rest_api_server]\nenable_server = true\nport = 18888\nmax_concurrent_requests = 50\nmax_requests_per_second = 50\nrequest_timeout_in_seconds = 10\n```\n\n- `enable_server` - If set to true, the RPC API server will be enabled.\n- `port` - The port for accessing the Sidecar's REST server. `18888` is the default, but operators are free to choose their own port as needed.\n- `max_concurrent_requests` - The maximum total number of simultaneous requests that can be made to the REST server.\n- `max_requests_per_second` - The maximum total number of requests that can be made per second.\n- `request_timeout_in_seconds` - The total time before a request times out.\n\n### Storage setup\n\nThis directory stores the SSE cache and an SQLite database if the Sidecar was configured to use SQLite.\n\n```toml\n[storage]\nstorage_folder = \"./target/storage\"\n```\n\n### Database connectivity setup\n\nThe Sidecar can connect to different types of databases. The current options are `SQLite` or `PostgreSQL`. The following sections show how to configure the database connection. Note that the Sidecar can only connect to one database at a time.\n\n#### SQLite database\n\nThis section includes configurations for the SQLite database.\n\n```toml\n[storage.sqlite_config]\nfile_name = \"sqlite_database.db3\"\nmax_connections_in_pool = 100\nwal_autocheckpointing_interval = 1000\n```\n\n- `storage.sqlite_config.file_name` - The database file name. The base folder where this file will be stored comes from `storage.storage_folder`.\n- `storage.sqlite_config.max_connections_in_pool` - The maximum number of connections to the database (should generally be left as is).\n- `storage.sqlite_config.wal_autocheckpointing_interval` - This controls how often the system commits pages to the database. The value determines the maximum number of pages before forcing a commit. More information can be found [here](https://www.sqlite.org/compile.html#default_wal_autocheckpoint).\n\n#### PostgreSQL database\n\nThe properties listed below are elements of the PostgreSQL database connection that can be configured for the Sidecar.\n\n- `storage.postgresql_config.database_name` - Name of the database.\n- `storage.postgresql_config.host` - URL to PostgreSQL instance.\n- `storage.postgresql_config.database_username` - Username.\n- `storage.postgresql_config.database_password` - Database password.\n- `storage.postgresql_config.max_connections_in_pool` - The maximum number of connections to the database.\n- `storage.postgresql_config.port` - The port for the database connection.\n\nTo run the Sidecar with PostgreSQL, you can set the following database environment variables to control how the Sidecar connects to the database. This is the suggested method to set the connection information for the PostgreSQL database.\n\n```\nSIDECAR_POSTGRES_USERNAME=\"your username\"\n```\n\n```\nSIDECAR_POSTGRES_PASSWORD=\"your password\"\n```\n\n```\nSIDECAR_POSTGRES_DATABASE_NAME=\"your database name\"\n```\n\n```\nSIDECAR_POSTGRES_HOST=\"your host\"\n```\n\n```\nSIDECAR_POSTGRES_MAX_CONNECTIONS=\"max connections\"\n```\n\n```\nSIDECAR_POSTGRES_PORT=\"port\"\n```\n\nHowever, DB connectivity can also be configured using the Sidecar configuration file. If the DB environment variables and the Sidecar's configuration file have the same variable set, the DB environment variables will take precedence.\n\nIt is possible to completely omit the PostgreSQL configuration from the Sidecar's configuration file. In this case, the Sidecar will attempt to connect to the PostgreSQL using the database environment variables or use some default values for non-critical variables.\n\n```toml\n[storage.postgresql_config]\ndatabase_name = \"event_sidecar\"\nhost = \"localhost\"\ndatabase_password = \"p@$$w0rd\"\ndatabase_username = \"postgres\"\nmax_connections_in_pool = 30\n```\n\n### Admin server setup\n\nThis optional section configures the Sidecar's administrative server. If this section is not specified, the Sidecar will not start an admin server.\n\n```toml\n[admin_api_server]\nenable_server = true\nport = 18887\nmax_concurrent_requests = 1\nmax_requests_per_second = 1\n```\n\n- `enable_server` - If set to true, the RPC API server will be enabled.\n- `port` - The port for accessing the Sidecar's admin server.\n- `max_concurrent_requests` - The maximum total number of simultaneous requests that can be sent to the admin server.\n- `max_requests_per_second` - The maximum total number of requests that can be sent per second to the admin server.\n\nAccess the admin server at `http://localhost:18887/metrics/`.\n\n## Running and Testing the Sidecar\n\n### Prerequisites\n\nTo compile, test, and run the Sidecar, install the following software first:\n\n- CMake 3.1.4 or greater\n- [Rust](https://www.rust-lang.org/tools/install)\n- pkg-config\n- gcc\n- g++\n\n### Running the Sidecar\n\nAfter creating the configuration file, run the Sidecar using `cargo` and point to the configuration file using the `--path-to-config` option, as shown below. The command needs to run with `root` privileges.\n\n```sh\nsudo cargo run -- --path-to-config ./resources/example_configs/EXAMPLE_NODE_CONFIG.toml\n```\n\nThe Sidecar application leverages tracing, which can be controlled by setting the `RUST_LOG` environment variable.\n\nThe following command will run the Sidecar application with the `INFO` log level.\n\n```sh\nRUST_LOG=info cargo run -p casper-sidecar -- --path-to-config ./resources/example_configs/EXAMPLE_NCTL_CONFIG.toml\n```\n\nThe log levels, listed in order of increasing verbosity, are:\n\n- `ERROR`\n- `WARN`\n- `INFO`\n- `DEBUG`\n- `TRACE`\n\nFurther details about log levels can be found [here](https://docs.rs/env_logger/0.9.1/env_logger/#enabling-logging).\n\n### Testing the Sidecar\n\nYou can run the unit and integration tests included in this repository with the following command:\n\n```sh\ncargo test\n```\n\nYou can also run the performance tests using this command:\n\n```sh\ncargo test -- --include-ignored\n```\n\nThe [EXAMPLE_NCTL_CONFIG.toml](./resources/example_configs/EXAMPLE_NCTL_CONFIG.toml) file contains the configurations used for these tests.\n\n#### Testing the Sidecar using NCTL\n\nThe Sidecar application can be tested against live Casper nodes or a local [NCTL network](https://docs.casper.network/condor/local-setup).\n\nThe configuration shown [here](./resources/example_configs/EXAMPLE_NCTL_CONFIG.toml) will direct the Sidecar application to a locally hosted NCTL network if one is running. The Sidecar should function the same way it would while connected to a live node, displaying events as they occur in the local NCTL network.\n\n## OpenAPI Specification\n\nAn OpenAPI schema is available at `http://localhost:18888/api-doc.json/`. You need to replace `localhost` with the IP address of the machine running the Sidecar application if you are running the Sidecar remotely.\n\n## Troubleshooting Tips\n\nThis section covers helpful tips when troubleshooting the Sidecar service. Replace the URL and ports provided in the examples as appropriate.\n\n### Checking liveness\n\nTo check whether the Sidecar is running, run the following `curl` command, which returns the newest stored block.\n\n```sh\ncurl http://SIDECAR_URL:SIDECAR_REST_PORT/block\n```\n\nEach block should have a `.block.header.timestamp` field. Even if there were no deploys, a block should be produced every 30-60 seconds. If the latest block falls behind, it means there is an issue with the Sidecar reading events from the node. Here is a helpful script provided `jq` is installed:\n\n```sh\ncurl http://SIDECAR_URL:SIDECAR_REST_PORT/block | jq '.block.header.timestamp'\n```\n\n### Checking the node connection\n\nChecking the node connection status requires the admin server to be enabled, as shown [here](#admin-server). Use this `curl` command and observe the output:\n\n```sh\ncurl http://SIDECAR_URL:SIDECAR_ADMIN_PORT/metrics\n```\n\n**Sample output**:\n\n```sh\n# HELP node_statuses Current status of node to which the Sidecar is connected. Numbers mean: 0 - preparing; 1 - connecting; 2 - connected; 3 - reconnecting; -1 - connections_exhausted -\u003e used up all connection attempts ; -2 - incompatible -\u003e node is in an incompatible version\n# TYPE node_statuses gauge\nnode_statuses{node=\"35.180.42.211:9999\"} 2\nnode_statuses{node=\"69.197.42.27:9999\"} 2\n```\n\nIn the above `node_statuses`, you can see which nodes are connecting, which are already connected, which are disconnected due to no more retries, etc. The number next to each node represents the connection status:\n\n- `0` - The Sidecar is preparing to connect\n- `1` - The Sidecar is connecting to the node\n- `2` - The Sidecar is connected to this node\n- `3` - The Sidecar is reconnecting\n- `-1` - The Sidecar is not connected and has reached the maximum connection attempts\n- `-2` - The Sidecar is not connected due to an incompatible node version\n\n### Diagnosing errors\n\nTo diagnose errors, look for `error` logs and check the `error_counts` on the metrics page, `http://SIDECAR_URL:SIDECAR_ADMIN_PORT/metrics`, where most of the errors related to data flow will be stored:\n\n```sh\n# HELP error_counts Error counts\n# TYPE error_counts counter\nerror_counts{category=\"connection_manager\",description=\"fetching_from_stream_failed\"} 6\n```\n\n### Monitoring memory consumption\n\nTo monitor the Sidecar's memory consumption, observe the metrics page, `http://SIDECAR_URL:SIDECAR_ADMIN_PORT/metrics`. Search for `process_resident_memory_bytes`:\n\n```sh\n# HELP process_resident_memory_bytes Resident memory size in bytes.\n# TYPE process_resident_memory_bytes gauge\nprocess_resident_memory_bytes 292110336\n```\n\nIf memory consumption is high without an apparent reason, please inform the Sidecar team by creating an [issue in GitHub](https://github.com/casper-network/casper-sidecar/issues).\n\nRemember to check the `event_stream_buffer_length` setting in the configuration because it dramatically impacts how much memory the Sidecar consumes. Also, some events, like step events, consume more memory.\n\n### Ensuring sufficient storage\n\nEnsuring enough space in the database is essential for the Sidecar to consume events produced from the nodes' SSE streams over a more extended period. Each event is written to the database in a raw format for future processing. Running the Sidecar for an extended period (weeks or months) can result in storing multiple Gigabytes of data. If the database runs out of space, the Sidecar will lose events, as it cannot record them.\n\n### Inspecting the REST API\n\nThe easiest way to inspect the Sidecar’s REST API is by analyzing the [Open API specification](# openapi-specification).\n\n### Limiting concurrent requests\n\nThe Sidecar can be configured to limit concurrent requests (`max_concurrent_requests`) and requests per second (`max_requests_per_second`) for the REST and admin servers.\n\nHowever, remember that those are application-level guards, meaning that the operating system already accepted the connection, which used up the operating system's resources. Limiting potential DDoS attacks requires consideration before the requests are directed to the Sidecar application.\n\n## License\n\nLicensed under the [Apache License Version 2.0](https://github.com/casper-network/casper-node/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcasper-network%2Fcasper-sidecar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcasper-network%2Fcasper-sidecar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcasper-network%2Fcasper-sidecar/lists"}