{"id":15448644,"url":"https://github.com/paritytech/finality-grandpa","last_synced_at":"2025-05-14T21:04:44.778Z","repository":{"id":33055160,"uuid":"138737291","full_name":"paritytech/finality-grandpa","owner":"paritytech","description":"finality gadget for blockchains using common prefix agreement","archived":false,"fork":false,"pushed_at":"2025-02-12T11:45:33.000Z","size":1058,"stargazers_count":142,"open_issues_count":15,"forks_count":47,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-17T11:59:51.477Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/paritytech.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":"2018-06-26T12:48:53.000Z","updated_at":"2025-02-12T11:38:14.000Z","dependencies_parsed_at":"2023-01-14T23:12:59.570Z","dependency_job_id":"97023180-e40c-47f0-ad35-7031fd963d71","html_url":"https://github.com/paritytech/finality-grandpa","commit_stats":{"total_commits":496,"total_committers":32,"mean_commits":15.5,"dds":0.6975806451612903,"last_synced_commit":"8c45a664c05657f0c71057158d3ba555ba7d20de"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paritytech%2Ffinality-grandpa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paritytech%2Ffinality-grandpa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paritytech%2Ffinality-grandpa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paritytech%2Ffinality-grandpa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paritytech","download_url":"https://codeload.github.com/paritytech/finality-grandpa/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247987181,"owners_count":21028891,"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":[],"created_at":"2024-10-01T20:29:12.561Z","updated_at":"2025-04-09T06:01:50.918Z","avatar_url":"https://github.com/paritytech.png","language":"Rust","funding_links":[],"categories":["Repositories","Rust"],"sub_categories":[],"readme":"# finality-grandpa\n\n[![crates.io link][crates-badge]][crates] [![Build Status](https://github.com/paritytech/finality-grandpa/actions/workflows/rust.yml/badge.svg?branch=master)](https://github.com/paritytech/finality-grandpa/actions/workflows/rust.yml) [![Coverage Status](https://coveralls.io/repos/github/paritytech/finality-grandpa/badge.svg?branch=master)](https://coveralls.io/github/paritytech/finality-grandpa?branch=master)\n\n\u003cimg align=\"right\" width=\"150\" height=\"150\" src=\"img/grandpa.png\"\u003e\n\n**GRANDPA**, **G**HOST-based **R**ecursive **AN**cestor **D**eriving **P**refix **A**greement, is a\nfinality gadget for blockchains, implemented in Rust. It allows a set of nodes to come to BFT\nagreement on what is the canonical chain, which is produced by some external block production\nmechanism. It works under the assumption of a partially synchronous network model and with the\npresence of up to 1/3 Byzantine nodes.\n\n## Build \u0026 Test\n\nThe only dependency required to build and run the tests is to have a stable version of Rust\ninstalled.\n\n```\ngit clone https://github.com/paritytech/finality-grandpa\ncd finality-grandpa\ncargo build\ncargo test\n```\n\n## Usage\n\nAdd this to your Cargo.toml:\n\n```toml\n[dependencies]\nfinality-grandpa = \"0.16\"\n```\n\n**Features:**\n\n- `derive-codec` - Derive `Decode`/`Encode` instances of [parity-scale-codec][parity-scale-codec]\n  for all the protocol messages.\n- `test-helpers` - Expose some opaque types for testing purposes.\n\n### Integration\n\nThis crate only implements the state machine for the GRANDPA protocol. In order to use this crate it\nis necessary to implement some traits to do the integration which are responsible for providing\naccess to the underyling blockchain and setting up all the network communication.\n\n#### [`Chain`][chain-docs]\n\nThe `Chain` trait allows the GRANDPA voter to check ancestry of a given block and also to query the\nbest block in a given chain (which will be used for voting on).\n\n#### [`Environment`][environment-docs]\n\nThe `Environment` trait defines the types that will be used for the input and output stream to\nreceive and broadcast messages. It is also responsible for setting these up for a given round\n(through `round_data`), as well as timers which are used for timeouts in the protocol.\n\nThe trait exposes callbacks for the full lifecycle of a round:\n\n- proposed\n- prevoted\n- precommitted\n- completed\n\nAs well as callbacks for notifying about block finality and voter misbehavior (equivocations).\n\n### Substrate\n\nThe main user of this crate is [Substrate][substrate] and should be the main resource used to look\ninto how the integration is done. The [`substrate-finality-grandpa` crate][substrate-finality-grandpa]\nshould have most of the relevant integration code.\n\nMost importantly this crate does not deal with authority set changes. It assumes that the set of\nauthorities is always the same. Authority set handoffs are handled in Substrate by listening to\nsignals emitted on the underlying blockchain.\n\n### Fuzzing\n\nTo run the fuzzing test harness you need to install either `afl` or `cargo-fuzz` (you'll need a nightly Rust toolchain\nfor this):\n\n```sh\ncargo install cargo-fuzz\ncargo install afl\n```\n\n#### libfuzzer\n\n```sh\ncargo fuzz run graph\ncargo fuzz run round\n```\n\n#### afl\n\n```sh\ncd fuzz\ncargo afl build --features afl --bin graph_afl\ncargo afl build --features afl --bin round_afl\n\n# create some random input\nmkdir afl_in \u0026\u0026 dd if=/dev/urandom of=afl_in/seed bs=1024 count=4\n\ncargo afl fuzz -i afl_in -o afl_out target/debug/graph_afl\ncargo afl fuzz -i afl_in -o afl_out target/debug/round_afl\n```\n\n## Resources\n\n- [Paper][paper]\n- [Introductory Blogpost][blogpost]\n- [Polkadot Wiki][polkadot-wiki]\n- [Sub0 Presentation][sub0]\n- [Testnet][testnet]\n\n## License\n\nUsage is provided under the Apache License (Version 2.0). See [LICENSE](LICENSE) for the full\ndetails.\n\n[blogpost]: https://medium.com/polkadot-network/grandpa-block-finality-in-polkadot-an-introduction-part-1-d08a24a021b5\n[chain-docs]: https://docs.rs/finality-grandpa/latest/finality_grandpa/trait.Chain.html\n[codecov-badge]: https://codecov.io/gh/paritytech/finality-grandpa/branch/master/graph/badge.svg\n[codecov]: https://codecov.io/gh/paritytech/finality-grandpa\n[crates-badge]: https://img.shields.io/crates/v/finality-grandpa.svg\n[crates]: https://crates.io/crates/finality-grandpa\n[environment-docs]: https://docs.rs/finality-grandpa/latest/finality_grandpa/voter/trait.Environment.html\n[paper]: https://github.com/w3f/consensus/blob/master/pdf/grandpa.pdf\n[parity-scale-codec]: https://github.com/paritytech/parity-scale-codec\n[polkadot-wiki]: https://wiki.polkadot.network/en/latest/polkadot/learn/consensus/\n[sub0]: https://www.youtube.com/watch?v=QE8svRKVYOU\n[substrate]: https://github.com/paritytech/substrate\n[substrate-finality-grandpa]: https://github.com/paritytech/substrate/tree/master/client/finality-grandpa\n[testnet]: https://telemetry.polkadot.io/#/Alexander\n[travis-badge]: https://travis-ci.org/paritytech/finality-grandpa.svg?branch=master\n[travis]: https://travis-ci.org/paritytech/finality-grandpa\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparitytech%2Ffinality-grandpa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparitytech%2Ffinality-grandpa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparitytech%2Ffinality-grandpa/lists"}