{"id":24054630,"url":"https://github.com/cardinal-cryptography/alephbft","last_synced_at":"2025-04-06T10:12:54.711Z","repository":{"id":36986253,"uuid":"331309440","full_name":"Cardinal-Cryptography/AlephBFT","owner":"Cardinal-Cryptography","description":"Rust implementation of Aleph consensus protocol","archived":false,"fork":false,"pushed_at":"2024-04-12T08:10:28.000Z","size":3092,"stargazers_count":46,"open_issues_count":4,"forks_count":28,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-04-12T15:05:21.466Z","etag":null,"topics":["asynchronous","bft","blockchain","consensus"],"latest_commit_sha":null,"homepage":"https://cardinal-cryptography.github.io/AlephBFT/index.html","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/Cardinal-Cryptography.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}},"created_at":"2021-01-20T13:05:35.000Z","updated_at":"2024-04-15T16:11:18.283Z","dependencies_parsed_at":"2024-02-15T12:26:51.945Z","dependency_job_id":"efeb4ab8-6383-4a82-ba32-ffb79cd14878","html_url":"https://github.com/Cardinal-Cryptography/AlephBFT","commit_stats":{"total_commits":305,"total_committers":25,"mean_commits":12.2,"dds":0.8032786885245902,"last_synced_commit":"e076b51eb71b886c413e47438d60bd7292ae27de"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cardinal-Cryptography%2FAlephBFT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cardinal-Cryptography%2FAlephBFT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cardinal-Cryptography%2FAlephBFT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cardinal-Cryptography%2FAlephBFT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cardinal-Cryptography","download_url":"https://codeload.github.com/Cardinal-Cryptography/AlephBFT/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464222,"owners_count":20942970,"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":["asynchronous","bft","blockchain","consensus"],"created_at":"2025-01-09T03:49:05.665Z","updated_at":"2025-04-06T10:12:54.694Z","avatar_url":"https://github.com/Cardinal-Cryptography.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Crate][crate-image]][crate-link]\n[![Docs][docs-image]][docs-link]\n[![Build Status][build-image]][build-link]\n[![Apache 2.0 Licensed][license-image]][license-link]\n[![cargo-audit][cargo-audit-image]][cargo-audit-link]\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://alephzero.org\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://alephzero.org/wp-content/uploads/A0_logotype_bft_dark.jpg\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n### Overview\n\nAlephBFT is an asynchronous and Byzantine fault-tolerant consensus protocol aimed\nat ordering arbitrary messages (transactions). It has been designed to operate\ncontinuously under conditions where there is no bound on message-delivery delay\nand under the assumption that there is a significant probability of malicious\nbehavior, making it an excellent fit for blockchain-related applications.\nFor more information, check [the white paper][paper-link].\n\nThis repository contains a Rust implementation of AlephBFT that offers a convenient\nAPI enabling seamless application to various problems. The prime application of\nthe repository is the consensus engine (sometimes called the \"finality gadget\")\nof the [Aleph Zero blockchain][aleph-node-link].\n\nThe code is split into several Rust packages, each having its own directory -\nsee the `Cargo.toml` file, which defines the layout of the whole workspace.\nThe main package, `aleph-bft`, is located in the `consensus` directory.\nAdditionally, every other package has a short README describing its role\nin the AlephBFT toolset.\n\n### Documentation\n\nEvery package is documented on [docs.rs][docs-link]. Comprehensive documentation\nis available as a [mdBook][reference-link].\n\nThe book can be built locally (assuming you have installed `rustup`):\n```\ncargo install mdbook\ncd docs\nmdbook serve --open\n```\n\n### Implementation status\n\nHighlights:\n- The protocol is asynchronous, so it's driven by consensus events as opposed\n  to some clock ticks.\n- The performance is still optimal in a partially synchronous environment.\n- BFT - secure if less than one third of the committee is malicious.\n- Secure against fork bombs.\n- Lowered network overhead of sending DAG parent information.\n- Thorough testing, including malicious scenarios, and high code coverage.\n\nMore details are available [in the book][reference-link-implementation-details].\n\n### Using the crate\n\n- Import AlephBFT in your crate\n  ```toml\n  [dependencies]\n  aleph-bft = \"^0.44\"\n  ```\n- The main entry point is the `run_session` function, which returns a Future that runs the\n  consensus algorithm.\n  To call this function, you need to pass a configuration (defaults are available in the package),\n  and implement certain traits, which will provide all the necessary functionalities, such as networking\n  and message signing.\n  A comprehensive guide is available [in the documentation][reference-link-api].\n\n### Examples\n\nWe provide two basic examples of running AlephBFT, both of which are not cryptographically secure, and assume honest, but possibly malfunctioning, participants.\n\nThe first one, `ordering`, implements a simple node that produces data items, and then waits for them to be finalized. It can also perform a simulated crash after creating a specified number of items.\n\nFor example, you may run the following command:\n```\ncd ./examples/ordering\n./run.sh\n```\nthat will launch 2 properly working nodes, and 2 nodes that will crash 3 times each.\nThe delay before relaunching a crashed node will be set to 1 second.\nA faulty node will create 25 items before every crash, and another `25` in the end.\nEvery node will therefore create `100` items in total, and then wait for other nodes before finishing its run.\n\nSee:\n```\n./run.sh -h\n```\nfor further details.\n\nNote that if the number of properly working nodes is less or equal than two times the number of faulty nodes, they will be unable to advance the protocol on their own.\n\nThe script will try to start nodes at predefined IP addresses, `127.0.0.1:100XX`, where `XX` denotes the node id. If the port is unavailable, the node will log an error and keep trying to aquire it, waiting 10 seconds between consecutive attempts.\n\nRunning this script will result in generating log files `node0.log, node1.log, ...` corresponding to subsequent nodes.\nA directory called `aleph-bft-examples-ordering-backup` will be created to store data required by the crash recovery mechanism, and the logs from subsequent runs will be appended to existing log files.\nThe cache and logs will be automatically cleared when launching the script again.\n\nThe second example, `blockchain`, is meant for benchmarking AlephBFT in the blockchain setting.\nIt implements a simple round-robin blockchain assuming honest participation.\nThe easiest way to run it is to use the provided script as follows (assuming we start in the root directory):\n```\ncd ./examples/blockchain\n./run.sh 5\n```\nwhere, again, `5` denotes the number of nodes that will be started.\nHere we only assume that the address `127.0.0.1:43000` is available, as the network implementation contains a simple node discovery mechanism.\nThe achieved transactions per second will be among the final log messages in these files.\n\nFor further details, see\n```\ncargo run -- --help\n```\n\n### Dependencies\n\nThe repository is mainly self-contained. It is implemented using Rust's async features and depends only on the\n`futures` crate from the standard library. Moreover, it has some usual dependencies like\n`log` and `rand` and one bigger for encoding, namely `parity-scale-codec`. In future work, we plan to get\nrid of this dependency.\n\n### Toolchain\n\nThis release was built and tested against the `nightly-2022-10-30` Rust toolchain.\nIf you want to use another version, edit the `rust-toolchain` file, or use an [override](https://rust-lang.github.io/rustup/overrides.html) with higher priority.\n\n### Tests\n\nThere are many unit tests and several integration tests that may be run by standard command\n`cargo test --lib` or `cargo test --lib --skip medium` if you want to run just small tests.\nAlternatively, you may run the `run_local_pipeline.sh` script.\n\n### Fuzzing\n\nWe provide fuzzing tests that try to crash the whole application by creating arbitrary data for the network layer\nand feeding it into the `member` implementation. To run those tests you need to install `afl` and `cargo-fuzz`.\n`cargo-fuzz` requires you to use a nightly Rust toolchain. `afl` differs from `cargo-fuzz` in that it requires\nso called corpus data to operate, i.e. some non-empty data set that do not crash the application.\nBoth tools are using LLVM's instrumentation capabilities in order to guide the fuzzing process basing on code-coverage statistics.\n\n```sh\ncargo install cargo-fuzz\ncargo install afl\n```\n\n#### cargo-fuzz/libfuzzer\n\n```sh\ncargo fuzz run --features=\"libfuzz\" fuzz_target\n```\n\n#### afl\n\nYou will need to generate some `seed` data first in order to run it.\n\n```sh\n# create some random input containing network data from a locally executed test\nmkdir afl_in\ncargo build --bin gen_fuzz\n./target/debug/gen_fuzz \u003e./afl_in/seed\n```\n\nYou might need to reconfigure your operating system in order to proceed -\nin such a case follow the instructions printed by the afl tool in your terminal.\n\n```sh\ncargo afl build --features=\"afl-fuzz\" --bin fuzz_target_afl\ncargo afl fuzz -i afl_in -o afl_out target/debug/fuzz_target_afl\n```\n\nThe `gen_fuzz` binary is also able to verify data for the afl tool.\n\n```sh\ncargo build --bin gen_fuzz\n./target/debug/gen_fuzz | ./target/debug/gen_fuzz --check-fuzz\n```\n\n### Code Coverage\n\nYou may generate the code coverage summary using the `gen_cov_data.sh` script and then a detailed\nraport for every file with `cov_report.sh`. Make sure to first install all the required\ntools with `install_cov_tools.sh`.\n\n### Resources\n\n- Papers: [current version][paper-link], [old version][old-paper-link]\n- docs: [crate documentation][docs-link], [reference][reference-link]\n\n### Future work\n\n- Asynchronous liveness is an important theoretical property and there is a lot of technical\n  sophistication that comes in the design of AlephBFT in order to achieve it, however on the practical\n  side there is still little evidence that performing such attacks against liveness in real-world\n  scenarios is possible. Still, no matter how unlikely such attacks might be, we take them very\n  seriously and plan to add randomness to AlephBFT in one of the future releases. We decided to go\n  for a version without randomness first, as it gives an incredibly simple and at the same time\n  secure and robust BFT consensus protocol. Adding randomness introduces some complexity into the\n  protocol, so it makes sense to add it on top of a well-tested, working product. The API of the\n  protocol will not change, and we will make the use of randomness configurable.\n- We see a big value in keeping a critical piece of code such as a consensus protocol as\n  self-contained as possible, so we would like to get rid of the only major dependency -\n  `parity-scale-codec`\n\n### License\n\nAlephBFT is licensed under the terms of the Apache License 2.0.\n\n### Funding\n\nThe implementation in this repository is funded by [Aleph Zero Foundation][webpage-link].\n\n[//]: ### \"badges\"\n[dataio-link]: https://cardinal-cryptography.github.io/AlephBFT/aleph_bft_api.html#311-dataio\n[network-link]: https://cardinal-cryptography.github.io/AlephBFT/aleph_bft_api.html#312-network\n[keychain-link]: https://cardinal-cryptography.github.io/AlephBFT/aleph_bft_api.html#313-keychain\n[crate-image]: https://img.shields.io/crates/v/aleph-bft.svg\n[crate-link]: https://crates.io/crates/aleph-bft\n[docs-image]: https://docs.rs/aleph-bft/badge.svg\n[docs-link]: https://docs.rs/aleph-bft\n[build-image]: https://github.com/Cardinal-Cryptography/AlephBFT/workflows/CI/badge.svg\n[build-link]: https://github.com/Cardinal-Cryptography/AlephBFT/actions?query=workflow%3ACI\n[license-image]: https://img.shields.io/badge/license-Apache2.0-blue.svg\n[license-link]: https://github.com/Cardinal-Cryptography/AlephBFT/blob/main/LICENSE\n[rustc-image]: https://img.shields.io/badge/rustc-stable-blue.svg\n[cargo-audit-image]: https://github.com/Cardinal-Cryptography/AlephBFT/actions/workflows/cargo-audit.yml/badge.svg\n[cargo-audit-link]: https://github.com/Cardinal-Cryptography/AlephBFT/actions/workflows/cargo-audit.yml\n[//]: ### \"general links\"\n[reference-link]: https://Cardinal-Cryptography.github.io/AlephBFT/index.html\n[reference-link-implementation-details]: https://cardinal-cryptography.github.io/AlephBFT/differences.html\n[reference-link-api]: https://cardinal-cryptography.github.io/AlephBFT/aleph_bft_api.html\n[paper-link]: https://arxiv.org/abs/1908.05156\n[old-paper-link]: https://arxiv.org/abs/1810.05256\n[aleph-node-link]: https://github.com/Cardinal-Cryptography/aleph-node\n[webpage-link]: https://alephzero.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcardinal-cryptography%2Falephbft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcardinal-cryptography%2Falephbft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcardinal-cryptography%2Falephbft/lists"}