{"id":13511267,"url":"https://github.com/casper-network/casper-node","last_synced_at":"2026-01-29T04:13:47.910Z","repository":{"id":37085458,"uuid":"263892105","full_name":"casper-network/casper-node","owner":"casper-network","description":"Reference node for CASPER protocol","archived":false,"fork":false,"pushed_at":"2025-03-14T23:36:17.000Z","size":69391,"stargazers_count":402,"open_issues_count":258,"forks_count":224,"subscribers_count":34,"default_branch":"dev","last_synced_at":"2025-03-17T11:58:56.678Z","etag":null,"topics":["blockchain","casper","casper-network","cspr","rust"],"latest_commit_sha":null,"homepage":"https://casper.network","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":null,"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}},"created_at":"2020-05-14T11:08:11.000Z","updated_at":"2025-03-14T20:31:22.000Z","dependencies_parsed_at":"2023-09-23T12:25:25.574Z","dependency_job_id":"115eda5b-7308-40af-afd1-3e7cbeb864c8","html_url":"https://github.com/casper-network/casper-node","commit_stats":{"total_commits":9455,"total_committers":63,"mean_commits":150.0793650793651,"dds":0.8438921205711264,"last_synced_commit":"78929721699a1c5fd7600127cfc3427bab8af00a"},"previous_names":["casperlabs/casper-node"],"tags_count":57,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/casper-network","download_url":"https://codeload.github.com/casper-network/casper-node/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245931897,"owners_count":20695964,"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","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":["blockchain","casper","casper-network","cspr","rust"],"created_at":"2024-08-01T03:00:45.820Z","updated_at":"2025-12-12T12:53:14.122Z","avatar_url":"https://github.com/casper-network.png","language":"Rust","funding_links":[],"categories":["Blockchains","Smart Contract Platforms","Rust"],"sub_categories":[],"readme":"\u003ca href=\"https://casper.network/\"\u003e\u003cimg src=\"images/Casper-association-logo-new.svg\" alt=\"Casper Network Logo\" width=\"300\" height=\"100\"\u003e\u003c/a\u003e\n\n# casper-node\n\nReference node for the Casper Blockchain Protocol.\n\n## Casper Blockchain\n\nCasper is the blockchain platform purpose-built to scale opportunity for everyone. Building toward blockchain’s next frontier,\nCasper is designed for real-world applications without sacrificing usability, cost, decentralization, or security. It removes\nthe barriers that prevent mainstream blockchain adoption by making blockchain friendly to use, open to the world, and\nfuture-proof to support innovations today and tomorrow. Guided by open-source principles and built from the ground up to\nempower individuals, the team seeks to provide an equitable foundation made for long-lasting impact. Read more about our\nmission at: https://casper.network\n\nThe Casper MainNet is live.\n- [cspr.live Block Explorer](https://cspr.live)\n\n### Specification\n\n- [Platform Specification](https://docs.casper.network/design)\n- [Highway Consensus Proofs](https://github.com/casper-network/highway/releases/latest)\n- [Zug Consensus Whitepaper](http://arxiv.org/pdf/2205.06314)\n\n### Get Started with Smart Contracts\n- [Writing Smart Contracts](https://docs.casper.network/developers/)\n- [Rust Smart Contract SDK](https://crates.io/crates/cargo-casper)\n- [Rust Smart Contract API Docs](https://docs.rs/casper-contract/latest/casper_contract/contract_api/index.html)\n- [AssemblyScript Smart Contract API](https://www.npmjs.com/package/casper-contract)\n\n### Community\n\n- [Discord Server](https://discord.gg/caspernetwork)\n- [Telegram Channel](https://t.me/casperofficialann)\n- [X (Twitter)](https://x.com/Casper_Network)\n\n\n\n## Running a casper-node from source\n\n### Pre-Requisites for Building\n\n* CMake 3.1.4 or greater\n* [Rust](https://www.rust-lang.org/tools/install)\n* libssl-dev\n* pkg-config\n* gcc\n* g++\n* recommended [wasm-strip](https://github.com/WebAssembly/wabt) (used to reduce the size of compiled Wasm)\n\n```sh\n# Ubuntu prerequisites setup example\napt update\napt install cmake libssl-dev pkg-config gcc g++ -y\n# the '-s -- -y' part ensures silent mode. Omit if you want to customize\ncurl https://sh.rustup.rs -sSf | sh -s -- -y\n```\n\n\n### Setup\n\nBefore building a node, prepare your Rust build environment:\n\n```\nmake setup-rs\n```\n\nThe node software can be compiled afterwards:\n\n```\ncargo build -p casper-node --release\n```\n\nThe result will be a `casper-node` binary found in `target/release`.  Copy this somewhere into your\nPATH, or substitute `target/release/casper-node` for `casper-node` in all examples below.\n\n### Running one node\n\nTo run a validator node you will need to specify a config file and launch the validator subcommand, for example\n\n```\ncasper-node validator /etc/casper-node/config.toml\n```\n\nThe node ships with an [example configuration file](resources/local/config.toml) that should be setup first.  There is\nalso a template for a local [chainspec](resources/local/chainspec.toml.in) in the same folder.\n\nFor launching, the following configuration values must be properly set:\n\n| Setting                   | Description |\n| :-------------------------| :---------- |\n| `network.known_addresses` | Must refer to public listening addresses of one or more currently-running nodes.  If the node cannot connect to any of these addresses, it will panic.  The node _can_ be run with this referring to its own address, but it will be equivalent to specifying an empty list for `known_addresses` - i.e. the node will run and listen, but will be reliant on other nodes connecting to it in order to join the network.  This would be normal for the very first node of a network, but all subsequent nodes should normally specify that first  node's public listening address as their `known_addresses`. |\n\n__The node will not run properly without another node to connect to.  It is recommended that multiple nodes are run.__\n\n### Running multiple nodes on one machine\n\nThere is a [tool](https://github.com/casper-network/casper-nctl) which automates the process of running multiple nodes on a single machine.\n\nNote that running multiple nodes on a single machine is normally only recommended for test purposes.\n\n## Configuration\n\nIn general nodes are configured through a configuration file, typically named `config.toml`.  This\nfile may reference other files or locations through relative paths.  When it does, note that all\npaths that are not absolute will be resolved relative to `config.toml` directory.\n\n\n### Environment overrides\n\nSome environments may call for overriding options through the environment.  In this\nscenario, the `NODE_CONFIG` environment variable can be used. For example:\nalternatively expressed as\n\n```\nexport NODE_CONFIG=consensus.secret_key_path=secret_keys/node-1.pem;network.known_addresses=[1.2.3.4:34553, 200.201.203.204:34553]\ncasper-node validator /etc/casper-node/config.toml\n```\n\nNote how the semicolon is used to separate configuration overrides here.\n\n### Other environment variables\n\nTo set the threshold at which a warn-level log message is generated for a long-running reactor event, use the env var\n`CL_EVENT_MAX_MICROSECS`.  For example, to set the threshold to 1 millisecond:\n\n```\nCL_EVENT_MAX_MICROSECS=1000\n```\n\nTo set the threshold above which the size of the current scheduler queues will be dumped to logs, use the `CL_EVENT_QUEUE_DUMP_THRESHOLD` variable. For example, to set the threshold to 10000 events:\n\n```\nCL_EVENT_QUEUE_DUMP_THRESHOLD=10000\n```\n\nThis will dump a line to the log if the total number of events in queues exceeds 10000. After each dump, the threshold will be automatically increased by 10% to avoid log flooding.\n\nExample log entry:\n```\nCurrent event queue size (11000) is above the threshold (10000): details [(\"FinalitySignature\", 3000), (\"FromStorage\", 1000), (\"NetworkIncoming\", 6500), (\"Regular\", 500)]\n```\n\n## Logging\n\nLogging can be enabled by setting the environment variable `RUST_LOG`.  This can be set to one of the following levels,\nfrom lowest priority to highest: `trace`, `debug`, `info`, `warn`, `error`:\n\n```\nRUST_LOG=info cargo run --release -- validator resources/local/config.toml\n```\n\nIf the environment variable is unset, it is equivalent to setting `RUST_LOG=error`.\n\n### Log message format\n\nA typical log message will look like:\n\n```\nJun 09 01:40:17.315 INFO  [casper_node::components::rpc_server rpc_server.rs:127] starting HTTP server; server_addr=127.0.0.1:7777\n```\n\nThis is comprised of the following parts:\n* timestamp\n* log level\n* full module path (not to be confused with filesystem path) of the source of the message\n* filename and line number of the source of the message\n* message\n\n### Filtering log messages\n\n`RUST_LOG` can be set to enable varying levels for different modules.  Simply set it to a comma-separated list of\n`module-path=level`, where the module path is as shown above in the typical log message, with the end truncated to suit.\n\nFor example, to enable `trace` level logging for the `network` module in `components`, `info` level for all other\nmodules in `components`, and `warn` level for the remaining codebase:\n\n```\nRUST_LOG=casper_node::components::network=trace,casper_node::comp=info,warn\n```\n\n### Logging network messages and tracing events\n\nSpecial logging targets exist in `net_in` and `net_out` which can be used to log every single network message leaving or\nentering a node when set to trace level:\n\n```\nRUST_LOG=net_in::TRACE,net_out::TRACE\n```\n\nAll messages in these logs are also assigned a unique ID that is different even if the same message is sent to multiple\nnodes. The receiving node will log them using the same ID as the sender, thus enabling the tracing of a message across\nmultiple nodes provided all logs are available.\n\nAnother helpful logging feature is ancestor logging. If the target `dispatch` is set to at least debug level, events\nbeing dispatched will be logged as well. Any event has an id (`ev`) and may have an ancestor (`a`), which is the previous\nevent whose effects caused the resulting event to be scheduled. As an example, if an incoming network message gets\nassigned an ID of `ev=123`, the first round of subsequent events will show `a=123` as their ancestor in the logs.\n\n### Changing the logging filter at runtime\n\nIf necessary, the filter of a running node can be changed using the diagnostics port, using the `set-log-filter`\ncommand. See the \"Diagnostics port\" section for details on how to access it.\n\n## Debugging\n\nSome additional debug functionality is available, mainly allowed for inspections of the internal event queue.\n\n### Diagnostics port\n\nIf the configuration option `diagnostics_port.enabled` is set to `true`, a unix socket named `debug.socket` by default can be found next to the configuration while the node is running.\n\n#### Interactive use\n\nThe `debug.socket` can be connected to by tools like `socat` for interactive use:\n\n```sh\nsocat readline unix:/path/to/debug.socket\n```\n\nEntering `help` will show available commands. The `set` command allows configuring the current connection, see `set --help`.\n\n#### Example: Collecting a consensus dump\n\nAfter connecting using `socat` (see above), we set the output format to JSON:\n\n```\nset --output=json\n```\n\nA confirmation will acknowledge the settings change (unless `--quiet=true` is set):\n\n```\n{\n  \"Success\": {\n    \"msg\": \"session unchanged\"\n  }\n}\n```\n\nWe can now call `dump-consensus` to get the _latest_ era serialized in JSON format:\n\n```\ndump-consensus\n{\n  \"Success\": {\n    \"msg\": \"dumping consensus state\"\n  }\n}\n{\"id\":8,\"start_time\":\"2022-03-01T14:54:42.176Z\",\"start_height\":88,\"new_faulty\" ...\n```\n\nAn era other than the latest can be dumped by specifying as a parameter, _e.g._ `dump-consensus 3` will dump the third era. See `dump-consensus --help` for details.\n\n#### Example: Dumping the event queue\n\nWith the connection set to JSON output (see previous example), we can also dump the event queues:\n\n```\ndump-queues\n{\n  \"Success\": {\n    \"msg\": \"dumping queues\"\n  }\n}\n{\"queues\":{\"Regular\":[],\"Api\":[],\"Network\":[],\"Control\":[],\"NetworkIncoming\":[]\n}}{\"queues\":{\"Api\":[],\"Regular\":[],\"Control\":[],\"NetworkIncoming\":[],\"Network\":\n[]}}{\"queues\":{\"Network\":[],\"Control\":[],\"Api\":[],\"NetworkIncoming\":[],\"Regular\n\":[]}}\n```\n\nEmpty output will be produced on a node that is working without external pressure, as the queues will be empty most of the time.\n\n\n#### Non-interactive use\n\nThe diagnostics port can also be scripted by sending a newline-terminated list of commands through `socat`. For example, the following sequence of commands will collect a consensus dump without the success-indicating header:\n\n```\nset -o json -q true\ndump-consensus\n```\n\nFor ad-hoc dumps, this can be shortened and piped into `socat`:\n\n```sh\necho -e 'set -o json -q true\\ndump-consensus' | socat - unix-client:debug.socket \u003e consensus-dump.json\n```\n\nThis results in the latest era being dumped into `consensus-dump.json`.\n\n\n## Running a client\n\nSee [the client README](https://github.com/casper-ecosystem/casper-client-rs#readme).\n\n## Running a local network\n\nSee [the nctl utility README](https://github.com/casper-network/casper-nctl#readme).\n\n## Running on an existing network\n\nTo support upgrades with a network, the casper-node is installed using scripts distributed with the\n[casper-node-launcher](https://github.com/casper-network/casper-node-launcher).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcasper-network%2Fcasper-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcasper-network%2Fcasper-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcasper-network%2Fcasper-node/lists"}