{"id":21659784,"url":"https://github.com/moonbeam-foundation/nimbus","last_synced_at":"2025-07-17T22:33:06.883Z","repository":{"id":37605378,"uuid":"420181304","full_name":"moonbeam-foundation/nimbus","owner":"moonbeam-foundation","description":"Upgradeable consensus framework for Substrate blockchains and parachains","archived":true,"fork":false,"pushed_at":"2024-06-06T14:41:13.000Z","size":5576,"stargazers_count":41,"open_issues_count":19,"forks_count":36,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-01-23T04:18:51.960Z","etag":null,"topics":["blockchain","consensus","rust-lang","substrate"],"latest_commit_sha":null,"homepage":"https://purestake.github.io/nimbus","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moonbeam-foundation.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":"2021-10-22T17:09:08.000Z","updated_at":"2024-12-09T01:44:31.000Z","dependencies_parsed_at":"2024-11-25T09:43:53.258Z","dependency_job_id":null,"html_url":"https://github.com/moonbeam-foundation/nimbus","commit_stats":null,"previous_names":["moonbeam-foundation/nimbus","purestake/nimbus"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/moonbeam-foundation/nimbus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonbeam-foundation%2Fnimbus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonbeam-foundation%2Fnimbus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonbeam-foundation%2Fnimbus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonbeam-foundation%2Fnimbus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moonbeam-foundation","download_url":"https://codeload.github.com/moonbeam-foundation/nimbus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moonbeam-foundation%2Fnimbus/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265672343,"owners_count":23808844,"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","consensus","rust-lang","substrate"],"created_at":"2024-11-25T09:31:32.606Z","updated_at":"2025-07-17T22:33:06.577Z","avatar_url":"https://github.com/moonbeam-foundation.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"## ⚠️ Nimbus has been migrated to [Moonkit](https://github.com/Moonsong-Labs/moonkit)\n\n# Cumulo -- Nimbus ⛈️\n\nNimbus is a framework for building parachain consensus systems on [cumulus](https://github.com/paritytech/cumulus)-based parachains.\n\nGiven the regular six-second pulse-like nature of the relay chain, it is natural to think about slot-\nbased consensus algorithms for parachains. The parachain network is responsible for liveness and\ndecentralization and the relay chain is responsible for finality. There is a rich design space for such\nalgorithms, yet some tasks are common to all (or most) of them. These common tasks include:\n\n* Signing and signature checking blocks\n* Injecting authorship information into the parachain\n* Block authorship and import accounting\n* Filtering a large (potentially unbounded) set of potential authors to a smaller (but still potentially unbounded) set.\n* Detecting when it is your turn to author an skipping other slots\n\nNimbus aims to provide standard implementations for the logistical parts of such consensus engines,\nalong with helpful traits for implementing the parts that researchers and developers want to customize.\n\n## Try the Demo\n\nWhile Nimbus is primarily a development framework meant to be included in other projects, it is useful\nto see a basic network in action. An example network is included in the `parachain-template` example collator. You\ncan build it with `cargo build --release` and launch it like any other cumulus parachain.\nMake sure to specify `--chain nimbus`.\n\nRather than reiterate how to start a relay-para network here, I'll simply recommend you use the\nexcellent [Polkadot Launch](https://github.com/paritytech/polkadot-launch) tool. This repo was tested with version 1.4.1.\nA [lauch config file](./parachain-template/polkadot-launch/config.json) is provided.\n\n```bash\n# Install polkadot launch (I used v1.4.1)\nnpm i -g polkadot-launch\n\n# Build polkadot (I used 82aa404c; check Cargo.lock to be sure)\ncd polkadot\ncargo build --release\ncd ..\n\n# Build Polkadot-parachains example collator\ncd cumulus\ngit checkout nimbus\ncargo build --release\n\n# Launch the multi-chain\npolkdot-launch ./parachain-template/polkadot-launch/config.json\n```\n\nTo learn more about launching relay-para networks, check out the [cumulus workshop](https://substrate.dev/cumulus-workshop).\n\n## Design Overview\n\nIf you want to start using Nimbus in your project, it is worth reading this.\n\nAt its core nimbus is a consensus engine that considers blocks valid if and only if they inject the author's public identity into the runtime, _and_ seal the block with a signature\nby the author's private key.\n\nCompared to most consensus engines, this is _very_ permissive -- anyone who can create a signature can author valid blocks. In order to build more useful and familiar consensus engine on this foundation, nimbus provides a framework for creating filters to further restrict the set of eligible authors. These filters live inside the runtime.\n\nBeing general in the consensus layer and deferring most checks to the runtime is the key\nto nimbus's re-usability as a framework. And is the reason that *writing a consensus engine is as easy as writing a pallet* when you use nimbus.\n\n### Author Inherent\n\nThe Author inherent pallet allows block authors to insert their identity into\nthe runtime. This feature alone is useful in many blockchains and can be used for things like block rewards.\n\nThe author inherent provides a validation hook called `CanAuthor`. This check will be called during the inherent execution and is the main entry point to nimbus's author filters.\nIf you don't want to restrict authorship at all, you can just use `()`.\n\nAs a concrete example, in a simple Proof of Stake system this check will determine\nwhether the author is staked. In a more realistic PoS system the `CanAuthor` check might\nfirst make sure the author is staked, and then make sure they are eligible in _this slot_ according to round robin rules.\n\nFinally, the pallet copies the authorship information into a consensus digest that will stick around\nin the block header. This digest can be used by UIs to display the author, and also by the consensus\nengine to verify the block authorship.\n\n**PreRuntimeDigest**\nI believe the design should be changed slightly to use a preruntime digest rather than an inherent for a few reasons:\n\n* The data wouldn't be duplicated between an inherent and a digest.\n* Nimbus client-side worker would support non-frame runtimes.\n* That's how sc-consensus-aura does it.\n\n### Author Filters\n\nA primary job of a consensus engine is deciding who can author each block. Some may have a static set, others\nmay rotate the set each era, others may elect an always-changing subset of all potential authors. There\nis much space for creativity, research, and design, and Nimbus strives to provide a flexible interface\nfor this creative work. You can express all the interesting parts of your\nconsensus engine simply by creating filters that implement the `CanAuthor` trait. The rest of Nimbus will #JustWork for you.\n\nThis repository comes with a few example filters already, and additional examples are welcome. The examples are:\n* PseudoRandom FixedSized Subset - This filter takes a finite set (eg a staked set) and filters it down to a pseudo-random\nsubset at each height. The eligible count is configurable in the pallet. This is a good learning example.\n* Aura - The authority round consensus engine is popular in the Substrate ecosystem because it was one\nof the first (and simplest!) engines implemented in Substrate. Aura can be expressed in the Nimbus\nfilter framework and is included as an example filter. If you are considering using aura, that crate\nhas good documentation on how it differs from `sc-consensus-aura`.\n* (Planned) FixedSizedSubset - The author submits a VRF output that has to be below a threshold to be able to author.\n* (Planed) Filter Combinator - A filter that wraps two other filters. It uses one in even slots and the other in odd slots.\n\n### Author Filter Runtime API\n\nNimbus makes the design choice to include the author checking logic in the runtime. This is in contrast to the existing implementations of Aura and Babe where the authorship checks are offchain.\n\nWhile moving the check in-runtime, provides a lot of flexibility, and simplifies interfacing with relay-chain validators, it makes it impossible\nfor authoring nodes to predict whether they will be eligible without calling into the runtime.\nTo achieve this, we provide a runtime API that makes the minimal calculation necessary to determine\nwhether a specified author will be eligible at the specified slot.\n\n### Nimbus Consensus Worker\n\nNimbus consensus is the primary client-side consensus worker. It implements the `ParachainConsensus`\ntrait introduced to cumulus in https://github.com/paritytech/cumulus/pull/329. It is not likely that\nyou will need to change this code directly to implement your engine as it is entirely abstracted over\nthe filters you use. The consensus engine performs these tasks:\n\n* Slot prediction - it calls the runtime API mentioned previously to determine whether ti is eligible. If not, it returns early.\n* Authorship - It calls into a standard Substrate proposer to construct a block (probably including the author inherent).\n* Self import - it imports the block that the proposer created (called the pre-block) into the node's local database.\n* Sealing - It adds a seal digest to the block - This is what is used by other nodes to verify the authorship information.\n\n### Verifier and Import Queue\n\nFor a parachain node to import a sealed block authored by one of its peers, it needs to first check that the signature is valid by the author that was injected into the runtime. This is the job of the verifier. It\nwill remove the nimbus seal and check it against the nimbus consensus digest from the runtime. If that process fails,\nthe block is immediately thrown away before the expensive execution even begins. If it succeeds, then\nthe pre-block (the part that's left after the seal is stripped) is passed into the\n[import pipeline](https://substrate.dev/docs/en/knowledgebase/advanced/block-import) for processing\nand execution. Finally, the locally produced result is compared to the result received across the network.\n\n### Custom Block Executor\n\nWe've already discussed how parachain nodes (both the one that authors a block, and also its peers)\nimport blocks. In a standalone blockchain, that's the end of the story. But for a parachain, we also\nneed our relay chain validators to re-execute and validate the parachain block. Validators do this in\na unique way, and entirely in wasm. Providing the `validate_block` function that the validators use\nis the job of the `register_validate_block!` macro from Cumulus.\n\nTypically a cumulus runtime invokes that macro like this:\n```rust\ncumulus_pallet_parachain_system::register_validate_block!(Runtime, Executive);\n```\n\nYou can see that the validators use the exact same executive that the parachain nodes do. Now that\nwe have sealed blocks, that must change. The validators need to strip and verify the seal, and re-execute\nthe pre-block just like the parachain nodes did. And without access to an offchain verifier, they must\ndo this all in the runtime. For that purpose, we provide and alternate executive which wraps the normal\nFRAME executive. The wrapper strips and checks the seal, just like the verifier did, and then passes the pre-block to the inner FRAME executive for re-execution.\n\n## Write Your Own Consensus Logic\n\nIf you have an idea for a new slot-based parachain consensus algorithm, Nimbus is a quick way to get\nit working! The fastest way to start hacking is to fork this repo and customize the template node.\n\nIf you'd rather dive in than read one more sentence, then **start hacking in the `author-slot-filter`\npallet.**\n\nIn most cases, you can use all the off-the-shelf components and simply write your filters. It is also\npossible to compose existing filters to build more complex logic from smaller pieces. \n\n## Authoring and Import Diagrams\n\nOne node authors the block, then it is processed in three different ways.\n\n|                     | Author | Parachain Peer | Relay Validator |\n| ------------------- | ------ | -------------- | --------- |\n| Predict Eligibility |    ✅   |    ❌          |    ❌      |\n| Author Block        |    ✅   |    ❌          |    ❌      |\n| Runs Verifier       |    ❌   |    ✅          |    ❌      |\n| Import Pipeline     |    ✅   |    ✅          |    ❌      |\n| Custom Pre exec     |    ❌   |    ❌          |    ✅      |\n| Normal FRAME exec   |    ✅   |    ✅          |    ✅      |\n\n## Roadmap\n\nThe Nimbus framework is intended to be loosely coupled with Cumulus.\n\n### Next tasks\n* Proper trait for interacting with digests\n* More example filters\n* Share code between verifier and wrapper executive\n* Client-side worker for standalone (non para) blockchain\n* Aurand as an example of composing filters\n* Second filter trait for exhaustive sets (As opposed to current propositional approach)\n\n## Contributions Welcome\n\nTry it out, open issues, submit PRs, review code. Whether you like to tinker with a running node, or\nanalyze security from an academic perspective, your contributions are welcome.\n\nI am happy to support users who want to use nimbus, or want feedback on their consensus engines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoonbeam-foundation%2Fnimbus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoonbeam-foundation%2Fnimbus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoonbeam-foundation%2Fnimbus/lists"}