{"id":23099961,"url":"https://github.com/keep-network/sortition-pools","last_synced_at":"2025-08-16T13:32:13.422Z","repository":{"id":40565088,"uuid":"232621265","full_name":"keep-network/sortition-pools","owner":"keep-network","description":"A data structure to perform weighted sortition in Solidity.","archived":false,"fork":false,"pushed_at":"2024-02-21T12:55:57.000Z","size":8774,"stargazers_count":21,"open_issues_count":17,"forks_count":4,"subscribers_count":16,"default_branch":"main","last_synced_at":"2024-11-28T15:41:52.404Z","etag":null,"topics":["cryptocurrency","data-structures","sortition"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/keep-network.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":"CONTRIBUTING.adoc","funding":null,"license":null,"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":"2020-01-08T17:36:20.000Z","updated_at":"2024-08-30T12:41:44.000Z","dependencies_parsed_at":"2024-06-18T20:08:12.685Z","dependency_job_id":"4293df27-115e-46ba-91be-64054fe0f414","html_url":"https://github.com/keep-network/sortition-pools","commit_stats":{"total_commits":718,"total_committers":14,"mean_commits":"51.285714285714285","dds":0.520891364902507,"last_synced_commit":"c5b8a1ee90b72ab0980eccb211e35c7087e66462"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keep-network%2Fsortition-pools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keep-network%2Fsortition-pools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keep-network%2Fsortition-pools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keep-network%2Fsortition-pools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keep-network","download_url":"https://codeload.github.com/keep-network/sortition-pools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230039795,"owners_count":18163465,"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":["cryptocurrency","data-structures","sortition"],"created_at":"2024-12-16T23:29:10.657Z","updated_at":"2024-12-16T23:29:14.435Z","avatar_url":"https://github.com/keep-network.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":":toc: macro\n\n= Sortition Pools\n\nhttps://github.com/keep-network/sortition-pools/actions/workflows/solidity-test.yml[image:https://img.shields.io/github/actions/workflow/status/keep-network/sortition-pools/solidity-test.yml?branch=main\u0026event=schedule\u0026label=Solidity%20tests[GitHub Workflow Status]]\n\nSortition pool is a logarithmic data structure used to store the pool of\neligible operators weighted by their stakes. In the\nhttps://threshold.org/[Threshold Network] the stake consists of staked T tokens.\nIt allows to select a group of operators based on the provided pseudo-random\nseed.\n\nEach privileged application has its own sortition pool and is responsible for\nmaintaining operator weights up-to-date.\n\n== Setup\n\n=== Prerequisites\n\n* clone the repository\n* https://nodejs.org/en/[Node.js] v14.21.2\n* configure git to use https\n\n[source,sh]\n----\ngit config --global url.\"https://\".insteadOf git://\n----\n\n* Python 3.11.1 for `node-gyp`. It is\n  https://opensource.com/article/19/5/python-3-default-mac[suggested] to use\n  `pyenv` to manage multiple Python versions.\n\n[source,sh]\n----\nbrew install pyenv\npyenv install 3.11.1\n----\n\n=== Build And Test\n\n[source,sh]\n----\nnpm ci\nnpm test\n----\n\n== In-Depth Reading\n\nTo familiarize yourself with the sortition pool and it's design, we provide\n\n* link:docs/building-intuition.md[Building Intuition]\n* link:docs/implementation-details.md[Implementation Details]\n* link:docs/rewards.md[Rewards]\n\nlink:docs/building-intuition.md[Building Intuition] starts the reader from the\nproblem description and an easy-to-understand naive solution, and then works its\nway up to the current design of the sortition pool through a series of\noptimizations.\n\nlink:docs/implementation-details.md[Implementation Details] builds off of the\nknowledge in link:docs/building-intuition.md[Building Intuition], and gets into\nthe finer points about the data structure, data (de)serialization, how operators\njoin/leave the pool, and how it all comes together to select a full group.\n\nlink:docs/rewards.md[Rewards] is a deep-dive into how the sortition pool keeps\ntrack of rewards. It features code explanations and walk-throughs of state\ntransitions for common situations.\n\n== Important Facts\n\n* The max number of operators is `2,097,152`\n* The sortition pool is for general purpose group selection. Feel free to use\n  or fork it!\n* The sortition pool can be \u003c\u003coptimisic-group-selection,optimistic\u003e\u003e! The\n  on-chain code then is only run in the case that the selection submission is\n  challenged.\n* The sortition pool tracks rewards!\n\n== Safe Use\n\nMiners and other actors that can predict the selection seed (due to frontrunning\nthe beacon or a public cached seed being used) may be able to manipulate\nselection outcomes to some degree by selectively updating the pool.\n\nTo mitigate this, applications using sortition pool should lock sortition pool\nstate before seed used for the new selection is known and should unlock the pool\nonce the selection process is over, keeping in mind potential timeouts and\nresult challenges.\n\n[[optimistic-group-selection]]\n== Optimistic Group Selection\n\nWhen an application (like the\nhttps://github.com/keep-network/keep-core/tree/main/solidity/random-beacon#group-creation[Random\nBeacon]) needs a new group, sortition is performed off-chain according to the\nsame algorithm that would be performed on-chain, and the results are submitted\non-chain.\n\nThen, we enter a challenge period where anyone can claim that the submitted\nresults are inaccurate. If this happens, the on-chain sortition pool runs the\nsame group selection with the same seed and validates the results.\n\nIf the submission was invalid, the challenger is rewarded and the submitter is\npunished, and we can accept another submission. If the submission was valid, the\nchallenger loses out on their gas, and the submitter is unaffected.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeep-network%2Fsortition-pools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeep-network%2Fsortition-pools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeep-network%2Fsortition-pools/lists"}