From a70b7a6741ad248c84a9e8457145adcb40eefe40 Mon Sep 17 00:00:00 2001 From: Beau Shinkle Date: Wed, 15 Feb 2023 10:23:01 -0500 Subject: [PATCH] Migrate README.md to README.adoc --- README.adoc | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 71 ----------------------------------- 2 files changed, 105 insertions(+), 71 deletions(-) create mode 100644 README.adoc delete mode 100644 README.md diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..d3649b5 --- /dev/null +++ b/README.adoc @@ -0,0 +1,105 @@ +: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. diff --git a/README.md b/README.md deleted file mode 100644 index 5728946..0000000 --- a/README.md +++ /dev/null @@ -1,71 +0,0 @@ -# Sortition Pools - -[![GitHub Workflow Status (event)](https://img.shields.io/github/actions/workflow/status/keep-network/sortition-pools/solidity-test.yml?branch=main&event=schedule&label=Solidity%20tests)](https://github.com/keep-network/sortition-pools/actions/workflows/solidity-test.yml) - -Sortition pool is a logarithmic data structure used to store the pool of -eligible operators weighted by their stakes. In the Keep network the stake -consists of staked KEEP 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. - -## In-Depth Reading - -To familiarize yourself with the sortition pool and it's design, we provide - -+ [Building Intuition](docs/building-intuition.md) -+ [Implementation Details](docs/implementation-details.md) -+ [Rewards](docs/rewards.md) - -[Building Intuition](docs/building-intuition.md) 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. - -[Implementation Details](docs/implementation-details.md) builds off of the -knowledge in [Building Intuition](docs/building-intuition.md), 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. - -[Rewards](docs/rewards.md) 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 [optimistic](#optimisic-group-selection)! 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 - -When an application (like the [Random -Beacon](https://github.com/keep-network/keep-core/tree/main/solidity/random-beacon#group-creation)) -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.