Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/keep-network/sortition-pools

A data structure to perform weighted sortition in Solidity.
https://github.com/keep-network/sortition-pools

cryptocurrency data-structures sortition

Last synced: 8 days ago
JSON representation

A data structure to perform weighted sortition in Solidity.

Awesome Lists containing this project

README 

        
:toc: macro



= Sortition Pools



https://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&event=schedule&label=Solidity%20tests[GitHub Workflow Status]]



Sortition pool is a logarithmic data structure used to store the pool of

eligible operators weighted by their stakes. In the

https://threshold.org/[Threshold Network] the stake consists of staked T tokens.

It allows to select a group of operators based on the provided pseudo-random

seed.



Each privileged application has its own sortition pool and is responsible for

maintaining operator weights up-to-date.



== Setup



=== Prerequisites



* clone the repository

* https://nodejs.org/en/[Node.js] v14.21.2

* configure git to use https



[source,sh]

----

git config --global url."https://".insteadOf git://

----



* Python 3.11.1 for `node-gyp`. It is

  https://opensource.com/article/19/5/python-3-default-mac[suggested] to use

  `pyenv` to manage multiple Python versions.



[source,sh]

----

brew install pyenv

pyenv install 3.11.1

----



=== Build And Test



[source,sh]

----

npm ci

npm test

----



== In-Depth Reading



To familiarize yourself with the sortition pool and it's design, we provide



* link:docs/building-intuition.md[Building Intuition]

* link:docs/implementation-details.md[Implementation Details]

* link:docs/rewards.md[Rewards]



link:docs/building-intuition.md[Building Intuition] starts the reader from the

problem description and an easy-to-understand naive solution, and then works its

way up to the current design of the sortition pool through a series of

optimizations.



link:docs/implementation-details.md[Implementation Details] builds off of the

knowledge in link:docs/building-intuition.md[Building Intuition], and gets into

the finer points about the data structure, data (de)serialization, how operators

join/leave the pool, and how it all comes together to select a full group.



link:docs/rewards.md[Rewards] is a deep-dive into how the sortition pool keeps

track of rewards. It features code explanations and walk-throughs of state

transitions for common situations.



== Important Facts



* The max number of operators is `2,097,152`

* The sortition pool is for general purpose group selection. Feel free to use

  or fork it!

* The sortition pool can be <>! The

  on-chain code then is only run in the case that the selection submission is

  challenged.

* The sortition pool tracks rewards!



== Safe Use



Miners and other actors that can predict the selection seed (due to frontrunning

the beacon or a public cached seed being used) may be able to manipulate

selection outcomes to some degree by selectively updating the pool.



To mitigate this, applications using sortition pool should lock sortition pool

state before seed used for the new selection is known and should unlock the pool

once the selection process is over, keeping in mind potential timeouts and

result challenges.



[[optimistic-group-selection]]

== Optimistic Group Selection



When an application (like the

https://github.com/keep-network/keep-core/tree/main/solidity/random-beacon#group-creation[Random

Beacon]) needs a new group, sortition is performed off-chain according to the

same algorithm that would be performed on-chain, and the results are submitted

on-chain.



Then, we enter a challenge period where anyone can claim that the submitted

results are inaccurate. If this happens, the on-chain sortition pool runs the

same group selection with the same seed and validates the results.



If the submission was invalid, the challenger is rewarded and the submitter is

punished, and we can accept another submission. If the submission was valid, the

challenger loses out on their gas, and the submitter is unaffected.