{"id":18679360,"url":"https://github.com/kaoimin/bft-core","last_synced_at":"2025-04-12T03:14:20.085Z","repository":{"id":57507671,"uuid":"182191947","full_name":"KaoImin/bft-core","owner":"KaoImin","description":"An efficient and stable Rust library of BFT core for distributed system.","archived":false,"fork":false,"pushed_at":"2019-06-21T03:42:01.000Z","size":134,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2025-04-12T03:14:14.619Z","etag":null,"topics":["bft","consensus","distributed-systems","rust","rust-library"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KaoImin.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}},"created_at":"2019-04-19T02:58:37.000Z","updated_at":"2023-07-25T14:25:13.000Z","dependencies_parsed_at":"2022-09-26T18:31:32.606Z","dependency_job_id":null,"html_url":"https://github.com/KaoImin/bft-core","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaoImin%2Fbft-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaoImin%2Fbft-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaoImin%2Fbft-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaoImin%2Fbft-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KaoImin","download_url":"https://codeload.github.com/KaoImin/bft-core/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248510001,"owners_count":21116130,"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":["bft","consensus","distributed-systems","rust","rust-library"],"created_at":"2024-11-07T09:43:18.898Z","updated_at":"2025-04-12T03:14:20.057Z","avatar_url":"https://github.com/KaoImin.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BFT\n\n[![Build Status](https://travis-ci.com/KaoImin/bft-core.svg?branch=develop)](https://travis-ci.com/KaoImin/bft-core)\n[![Crate](https://img.shields.io/crates/v/bft-core.svg)](https://crates.io/crates/bft-core)\n\nAn efficient and stable Rust library of BFT protocol for distributed system.\n\n## What is BFT?\n\nBFT(Byzantine Fault Tolerance) comprise a class of consensus algorithms that achieve byzantine fault tolerance. BFT can guarantee liveness and safety for a distributed system where there are not more than 33% malicious byzantine nodes, and thus BFT is often used in the blockchain network.\n\n## BFT Protocol\n\n### Protocol\n\nBFT is a State Machine Replication algorithm, and some states are shown below:\n\n1. The three states protocol\n\n```\n    NewHeight -\u003e (Propose -\u003e Prevote -\u003e Precommit)+ -\u003e Commit -\u003e NewHeight -\u003e ...\n```\n\n2. The three states protocol in a height\n\n```\n                            +-------------------------------------+\n                            |                                     | (Wait new block)\n                            v                                     |\n                      +-----------+                         +-----+-----+\n         +----------\u003e |  Propose  +--------------+          | NewHeight |\n         |            +-----------+              |          +-----------+\n         |                                       |                ^\n         | (Else)                                |                |\n         |                                       v                |\n   +-----+-----+                           +-----------+          |\n   | Precommit |  \u003c------------------------+  Prevote  |          | (Wait RichStatus)\n   +-----+-----+                           +-----------+          |\n         |                                                        |\n         | (When +2/3 Precommits for the block found)             |\n         v                                                        |\n   +--------------------------------------------------------------+-----+\n   |  Commit                                                            |\n   |                                                                    |\n   |  * Generate Proof;                                                 |\n   |  * Set CommitTime = now;                                           |\n   +--------------------------------------------------------------------+\n```\n\n### Architecture\n\nA complete BFT model consists of 4 essential parts:\n\n1. Consensus Module, the consensus algorithm module includes signature verification, proof generation, version check, etc.;\n\n2. State Machine, the BFT state machine is focused on consensus proposal;\n\n3. Transport Module, the network for consensus module to communicate with other modules;\n\n4. Wal Module, the place saving BFT logs.\n\n**NOTICE**: The bft-core only provides a basic BFT state machine and does not support the advanced functions such as signature verification, proof generation, compact block, etc. These functions are in consensus module rather than bft-core library.\n\n## Feature\n\nThe bft-core provides `async_verify` feature to verify transcation after received a proposal. BFT state machine will check the verify result of the proposal before `Precommit` step. If it has not received the result of the proposal yet, it will wait for an extra 1/2 of the consensus duration.\n\n## Interface\n\nIf bft-core works correctly, it needs to receive 4 types of message: `Proposal`, `Vote`, `Feed`, `Status`. And  bft-core can send 4 types of message: `Proposal`, `Vote`, `Commit` and `GetProposalRequest`. Besides, bft-core also provides `Stop` and `Start` message that can control state machine stop or go on. These types of messages consist in the enum `CoreInput` and `CoreOutput`:\n\n```rust\nenum CoreInput {\n    Proposal(Proposal),\n    Vote(Vote),\n    Feed(Feed),\n    Status(Status),\n    Commit(Commit),\n    #[cfg(feature = \"async_verify\")]\n    VerifyResp(VerifyResp),\n    Pause,\n    Start,\n}\n\nenum CoreOutput {\n    Proposal(Proposal),\n    Vote(Vote),\n    Commit(Commit),\n    GetProposalRequest(u64),\n}\n```\n\nFor detailed introduction, click [here](src/types.rs).\n\n## Usage\n\nFirst, add bft-core to your `Cargo.toml`:\n\n```rust\n[dependencies]\nbft-core = { git = \"https://github.com/KaoImin/bft-core.git\", branch = \"develop\" }\n```\n\nIf you want to use `async_verify` feature, needs to add following codes:\n\n```rust\n[features]\nasync_verify = [\"bft-core/async_verify\"]\n```\n\nSecond, add BFT and channel to your crate as following:\n\n```rust\nextern crate bft_core as bft;\n\nuse bft::{types::*, Core, FromCore};\n```\n\nThird, initialize a BFT core:\n\n```rust\nlet bft = BFT::new(address);\n```\n\n*The `address` here is the address of this node with type `Vec\u003cu8\u003e`.*\n\nWhat needs to illustrate is that the BFT machine is in stop step by default, therefore, the first thing is send `CoreInput::Start` message. Use `send_bft_msg()` function to send a message to BFT state machine as following:\n\n```rust\nbft.send_bft_msg(CoreInput::Start).map_err();\n\nbft.send_bft_msg(CoreInput::Status(status)).map_err();\n\n// only in feature async_verify\nbft.send_bft_msg(CoreInput::VerifyResq(result)).map_err();\n```\n\nAnd implement the trait `FromCore` to receive messages from BFT core.\n\nIf you want to use the BFT height to do some verify, use `get_height` function as following:\n\n```rust\nlet height: u64 = bft.get_height();\n```\n\n## License\n\nThis an open source project under the [MIT License](https://github.com/KaoImin/bft-core/blob/develop/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaoimin%2Fbft-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaoimin%2Fbft-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaoimin%2Fbft-core/lists"}