{"id":13472419,"url":"https://github.com/IntersectMBO/ouroboros-consensus","last_synced_at":"2025-03-26T15:32:23.952Z","repository":{"id":65776799,"uuid":"574934335","full_name":"IntersectMBO/ouroboros-consensus","owner":"IntersectMBO","description":"Implementation of a Consensus Layer for the Ouroboros family of protocols","archived":false,"fork":false,"pushed_at":"2024-10-29T11:58:03.000Z","size":57629,"stargazers_count":34,"open_issues_count":384,"forks_count":23,"subscribers_count":37,"default_branch":"main","last_synced_at":"2024-10-29T13:36:00.707Z","etag":null,"topics":["blockchain","consensus","ouroboros"],"latest_commit_sha":null,"homepage":"https://ouroboros-consensus.cardano.intersectmbo.org","language":"Haskell","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/IntersectMBO.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-12-06T11:54:50.000Z","updated_at":"2024-10-28T16:58:32.000Z","dependencies_parsed_at":"2024-04-15T09:06:49.771Z","dependency_job_id":null,"html_url":"https://github.com/IntersectMBO/ouroboros-consensus","commit_stats":null,"previous_names":[],"tags_count":97,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fouroboros-consensus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fouroboros-consensus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fouroboros-consensus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntersectMBO%2Fouroboros-consensus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IntersectMBO","download_url":"https://codeload.github.com/IntersectMBO/ouroboros-consensus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222151632,"owners_count":16939423,"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","ouroboros"],"created_at":"2024-07-31T16:00:54.499Z","updated_at":"2024-10-30T02:32:07.700Z","avatar_url":"https://github.com/IntersectMBO.png","language":"Haskell","readme":"# Ouroboros Consensus\n\n[![consensus](https://img.shields.io/badge/ouroboros--consensus-0.20.0.0-blue)](https://chap.intersectmbo.org/package/ouroboros-consensus-0.20.0.0/)\n[![diffusion](https://img.shields.io/badge/ouroboros--consensus--diffusion-0.17.0.1-blue)](https://chap.intersectmbo.org/package/ouroboros-consensus-diffusion-0.17.0.1/)\n[![protocol](https://img.shields.io/badge/ouroboros--consensus--protocol-0.9.0.1-blue)](https://chap.intersectmbo.org/package/ouroboros-consensus-protocol-0.9.0.1/)\n[![cardano](https://img.shields.io/badge/ouroboros--consensus--cardano-0.18.0.0-blue)](https://chap.intersectmbo.org/package/ouroboros-consensus-cardano-0.18.0.0/)\n[![sop-extras](https://img.shields.io/badge/sop--extras-0.2.0.0-blue)](https://chap.intersectmbo.org/package/sop-extras-0.2.0.0/)\n[![strict-sop-core](https://img.shields.io/badge/strict--sop--core-0.1.1.0-blue)](https://chap.intersectmbo.org/package/strict-sop-core-0.1.1.0/)\n\n[![docs](https://img.shields.io/badge/Documentation-yellow)][webpage]\n\nImplementation of the Ouroboros family of consensus algorithms.\n\n## Libraries and executables\n\nThis repository provides four packages, with the following dependencies among\nthem:\n\n``` mermaid\nflowchart TD\n    D[ouroboros-consensus-diffusion] --\u003e C\n    A[ouroboros-consensus-cardano] --\u003e B[ouroboros-consensus-protocol]\n    A --\u003e C\n    B --\u003e C[ouroboros-consensus]\n```\n\nThe packages contain many test-suites that complicate the dependency graph as\nthey create new depencency arcs.\n\nThis repository also provides four executables:\n\n- `ouroboros-consensus-cardano/app/db-analyser.hs`: for analyzing ChainDBs as\n  the ones created by the node. This helps identifying performance hotspots and\n  testing that the validating logic remains correct.\n\n- `ouroboros-consensus-cardano/app/db-synthesizer.hs`: for quickly generating\n  chains to be used in benchmarking.\n\n- `ouroboros-consensus-cardano/app/db-truncater.hs`: for truncating an immutable\n  DB.\n\n- `ouroboros-consensus-cardano/app/immdb-server.hs`: for serving a immutable DB\n  stored locally.\n\nTo list all the available Cabal components, one can use the following script\nbecause unfortunately, `cabal` doesn't have a command to list the [available\ntargets](https://github.com/haskell/cabal/issues/4070):\n\n``` bash\nfor f in $(find ouroboros-consensus* *sop* -type f -name \"*.cabal\"); do\n    printf \"Components of package %s:\\n\" $f;\n    grep -E \"^(library|test-suite|executable|benchmark)\" $f --color=never | column -t | sort | sed 's/^/\\t/'\ndone\n```\n\n## Building the project\n\nWe use `cabal` to build our project, potentially inside a Nix shell (`nix\ndevelop` or `nix-shell`). It should suffice with:\n\n``` bash\n\u003e cabal build all\n```\n\nSpecific executables can be executed through cabal once built:\n\n``` bash\n\u003e cabal run db-analyser\n```\n\n## Testing the project\n\nThe project is tested with numerous Haskell test suites. To run every test\nsuite, one can use:\n\n``` bash\n\u003e cabal test all\n```\n\nFor running specific test-suites (such as `consensus-test`), we recommend one of\nthe following commands:\n\n``` bash\n\u003e cabal run ouroboros-consensus:test:consensus-test -- \u003cargs\u003e\n\u003e cabal test ouroboros-consensus:test:consensus-test --test-show-details=direct\n```\n\nNote the second one cannot be used when we want to provide CLI arguments to the\ntest-suite.\n\n## Using Consensus as a dependency\n\nWe make releases to the [Cardano Haskell\nPackage](https://chap.intersectmbo.org/all-packages/)\nrepository from where you should pull new releases.\n\nTo use CHaP, follow their Readme, but in short:\n\n1. Add this at the top of your `cabal.project` file:\n\n  ```\n  repository cardano-haskell-packages\n    url: https://chap.intersectmbo.org\n    secure: True\n    root-keys:\n      3e0cce471cf09815f930210f7827266fd09045445d65923e6d0238a6cd15126f\n      443abb7fb497a134c343faf52f0b659bd7999bc06b7f63fa76dc99d631f9bea1\n      a86a1f6ce86c449c46666bda44268677abf29b5b2d2eb5ec7af903ec2f117a82\n      bcec67e8e99cabfa7764d75ad9b158d72bfacf70ca1d0ec8bc6b4406d1bf8413\n      c00aae8461a256275598500ea0e187588c35a5d5d7454fb57eac18d9edb86a56\n      d4a35cd3121aa00d18544bb0ac01c3e1691d618f462c46129271bccf39f7e8ee\n  ```\n\n2. Run `cabal update` to pull in the latest index.\n3. Specify which version of the index you want for both Hackage and CHaP. Note\n   that it has to be higher or equal to the highest timestamp of the released\n   versions of the packages that you want to use as dependencies:\n\n   ```\n   index-state:\n    , hackage.haskell.org      2023-04-12T00:00:00Z\n    , cardano-haskell-packages 2023-04-23T00:00:00Z\n   ```\n\nAt this point, you should be able to declare our libraries as dependencies in\nyour `build-depends` list on your cabal files.\n\nIf you use Nix, see the [CHaP\nwebsite](https://chap.intersectmbo.org/) on how to\nconfigure CHaP for haskell.nix.\n\nThe Consensus sublibraries---which are used for our internal testing---are\nvisible and buildable by default only because the appropriate Cabal and/or Nix\ninfrastructure to guard them behind an explicit opt-in is currently immature\nand fragile. **WARNING** breaking changes to the these libraries are **not**\nreflected in the package versions. That is why they all have the `unstable-`\nprefix in their name; use at your own risk, and please reach out to us if this\npolicy of ours is an excessive burden on your use case.\n\n## How to contribute to the project\n\nYour help is greatly appreciated. Please see [our CONTRIBUTING\ndocument](CONTRIBUTING.md).\n\n## How to submit an issue\n\nIssues can be filled in our [GitHub issue\ntracker](https://github.com/IntersectMBO/ouroboros-consensus/issues). Please\nuse the provided issue templates.\n\n## Documentation\n\nWe have several sources of documentation:\n\n- [Haddocks](https://ouroboros-consensus.cardano.intersectmbo.org/haddocks/):\n  our code is full of haddock annotations and comments that try to clarify\n  expected behaviors and subtleties. Reading through the code should provide\n  most of the information on how is Consensus implemented.\n\n- [Website](https://ouroboros-consensus.cardano.intersectmbo.org/): this\n  website provides access to the markdown documentation to which step by step we\n  want to move the bulk of the \"higher level documentation\" as well as\n  achitectural documentation.\n\n- [Report](./docs/tech-reports/report/): this in-depth technical report describes many of the\n  deep choices made in the implementation of the Consensus layer, as well as\n  non-trivial lemmas or properties of the Consensus algorithms that have\n  perspired to the implementation. Although incomplete in some sections, it is a\n  mandatory reading for anyone looking to understand why Consensus does what it\n  does.\n  ([rendered](https://ouroboros-consensus.cardano.intersectmbo.org/pdfs/report.pdf))\n\n\n[webpage]: https://ouroboros-consensus.cardano.intersectmbo.org/\n","funding_links":[],"categories":["Haskell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIntersectMBO%2Fouroboros-consensus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FIntersectMBO%2Fouroboros-consensus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIntersectMBO%2Fouroboros-consensus/lists"}