{"id":15808811,"url":"https://github.com/cocol-project/probfin","last_synced_at":"2025-08-08T10:42:58.007Z","repository":{"id":119221782,"uuid":"209065769","full_name":"cocol-project/probfin","owner":"cocol-project","description":"Probabilistic Finality for Crystal","archived":false,"fork":false,"pushed_at":"2020-03-04T14:06:38.000Z","size":347,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-06T03:06:57.910Z","etag":null,"topics":["blockchain","cocol","crystal","crystal-lang","crystal-language","dag","finality","probabilistic-finality","topsort"],"latest_commit_sha":null,"homepage":"https://cocol-project.github.io/probfin/","language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cocol-project.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":"2019-09-17T13:46:07.000Z","updated_at":"2020-06-23T15:55:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"92e116f9-ea83-45b1-b4d5-3d014e5c9f7d","html_url":"https://github.com/cocol-project/probfin","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/cocol-project/probfin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cocol-project%2Fprobfin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cocol-project%2Fprobfin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cocol-project%2Fprobfin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cocol-project%2Fprobfin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cocol-project","download_url":"https://codeload.github.com/cocol-project/probfin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cocol-project%2Fprobfin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269409955,"owners_count":24412143,"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","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","cocol","crystal","crystal-lang","crystal-language","dag","finality","probabilistic-finality","topsort"],"created_at":"2024-10-05T03:07:12.285Z","updated_at":"2025-08-08T10:42:57.979Z","avatar_url":"https://github.com/cocol-project.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cocol Probabilistic Finality\n\nBased on DAGs, it manages chains, sidechains and orphans. Given a threshold of\nconfirmations it returns the next finalized block.\n\n## Installation\n\n1. Add the dependency to your `shard.yml`:\n\n``` yaml\n   dependencies:\n     probfin:\n       github: cocol-project/probfin\n```\n\n2. Run `shards install`\n\n## Usage\n\n``` crystal\nrequire \"probfin\"\n```\n\n``` crystal\n# (a0)---aa---ba---ca---da---ea---fa\n#              \\    \\\n#               bb   cb---cc\n\n# add blocks (aa, a0 should be block hashes)\nProbFin.push(block: \"aa\", parent: \"a0\")\nProbFin.push(block: \"ba\", parent: \"aa\")\nProbFin.push(block: \"bb\", parent: \"ba\")\n...\n\n\nProbFin.finalize from: \"aa\",\n    chain_length_threshold: 5, # 5 confirmations (fa being the 5th) \n    tip_diff_threshold: 0 # how many more confirmations should it have compared to sidechains\n    \n# =\u003e ba\n```\n\n## How ProbFin works\n![Alt Text](https://thepracticaldev.s3.amazonaws.com/i/bfimp8gtxgbiyc5pb480.png)\n\nThe data structure above resembles a Directed Acyclic Graph (DAG) and fortunately DAGs allow for an easy way to find the longest chain. This is an important part of achieving probabilistic finality.\n\nA DAG is made up of nodes (also called vertices) and edges. An edge represents a link between 2 vertices (e.g. `3000.1-\u003e3001.1`). We can and should traverse a DAG to find out more about its structure, like how far away is vertex `3005.1` from vertex `3000.1`\n\nAdditionally a DAG has some unique properties. Find out more about it [here](https://www.youtube.com/watch?v=TXkDpqjDMHA)\n\n**2. How to find the longest chain**\n\nIf we look again at the example above, it becomes apparent that `3005.1` is the tip of the longest chain. But how can we find it out programmatically?\n\nWe are going to use [Depth First Search](https://www.youtube.com/watch?v=7fujbpJ0LB4) to traverse the graph and mark every vertex with its distance from the starting vertex.\nWe start at `3000.1` and give it a distance of `0`. Now we traverse through all vertices and give each a distance of `parent distance + 1`. So `3001.1` has a `parent distance` of `0` and `+1` gives a distance of `1`.\n\n![Alt Text](https://thepracticaldev.s3.amazonaws.com/i/qexgjvm9yv8ko8cwv6y2.png)\n\n## Contributing\n\n1. Fork it (\u003chttps://github.com/cocol-project/probfin/fork\u003e)\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\n## Contributors\n\n- [cserb](https://github.com/cserb) - creator and maintainer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcocol-project%2Fprobfin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcocol-project%2Fprobfin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcocol-project%2Fprobfin/lists"}