Merge branch 'main' into node16

Author: nkuba

.gitignore

@@ -2,3 +2,4 @@ node_modules/
 build/
 cache/
 .vscode
+.envrc

.python-version

@@ -0,0 +1 @@
+3.10.9

CONTRIBUTING.adoc

@@ -0,0 +1,64 @@
+= Keep Contribution Guide
+
+🎉 Thanks for taking the time to contribute! 🎉 Contributions are welcome from
+anyone, and even the smallest of fixes is appreciated!
+
+The following is a set of guidelines for contributing to Keep and its packages.
+These are mostly guidelines, not rules. Use your best judgment, and feel free to
+propose changes to this document in a pull request.
+
+== Getting started
+
+1. Fork
+   https://github.com/keep-network/sortition-pools[`keep-network/sortition-pools`]
+2. Clone your fork
+3. Follow the
+   link:README.md#Setup[installation & build steps] in the README.
+4. Set up the <<Development Tooling>>.
+5. Open a PR against the `main` branch and describe the change you are intending
+   to undertake in the PR description.
+
+Before marking the PR as ready for review, make sure:
+
+* It passes the linter checks (`npm run lint` and `npm run lint:fix`).
+* It passes the https://github.com/keep-network/sortition-pools/actions[continuous
+  integration tests].
+* Your changes have sufficient test coverage (e.g regression tests have
+  been added for bug fixes, unit tests for new features).
+
+== Development Tooling
+
+Commits
+https://help.github.com/en/articles/about-commit-signature-verification[must
+be signed].
+
+=== Continuous Integration
+
+Keep uses https://github.com/keep-network/sortition-pools/actions[Github
+Actions] for continuous integration. All jobs must be green to merge a PR.
+
+=== Pre-commit
+
+Pre-commit is a tool to install hooks that check code before commits are made.
+It can be helpful to install this, to automatically run linter checks and avoid
+pushing code that will not be accepted. Follow the
+https://pre-commit.com/[installation instructions here], and then run
+`pre-commit install` to install the hooks.
+
+=== Linting
+
+Linters and formatters for Solidity, JavaScript, and Go code are set up and run
+automatically as part of pre-commit hooks. These are checked again in CI builds
+to ensure they have been run and are passing.
+
+To run the linters and formatters manually, use the following commands:
+* `npm run lint` - checks files against linting rules.
+* `npm run lint:fix` - checks files against linting rules and fixes any
+  issues that can be fixed automatically.
+
+If you want to change a rule, or add a custom rule, to the JavaScript or
+Solidity linting, please propose these changes to our
+https://github.com/keep-network/solium-config-keep[solium-config-keep], 
+https://github.com/keep-network/eslint-config-keep[eslint-config-keep], or 
+https://github.com/keep-network/prettier-config-keep[prettier-config-keep]
+packages. All other packages have them as a dependency.

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 <<optimisic-group-selection,optimistic>>! 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.