Merge branch 'main' into 18-factory-registry

.changeset/big-lemons-teach.md

@@ -0,0 +1,5 @@
+---
+'rankify-contracts': patch
+---
+
+improved documentation generation for mkdocs compatible markdown outputs

.changeset/cuddly-swans-allow.md

@@ -0,0 +1,5 @@
+---
+'rankify-contracts': minor
+---
+
+eslint major verison change

.changeset/fuzzy-roses-mate.md

@@ -0,0 +1,5 @@
+---
+'rankify-contracts': minor
+---
+
+Updated readme

.changeset/lucky-poems-grow.md

@@ -0,0 +1,5 @@
+---
+'rankify-contracts': minor
+---
+
+moved eds as dependency

.changeset/selfish-cars-study.md

@@ -0,0 +1,5 @@
+---
+'rankify-contracts': patch
+---
+
+doc generation template improvements

.changeset/silly-seahorses-tickle.md

@@ -0,0 +1,30 @@
+---
+'rankify-contracts': minor
+---
+
+## Addition of Ethereum Distribution System (EDS)
+
+- **Feature**: Integrated the Ethereum Distribution System (EDS) for distributing Rankify contracts.
+- **Description**: Rankify contracts are now distributed via the Ethereum Distribution System, enhancing the efficiency and security of the distribution process.
+
+## Redesign of Contracts
+
+- **Feature**: Redesigned contracts to work seamlessly as part of the Ethereum Distribution System.
+- **Description**: The contracts have been restructured and optimized to ensure compatibility and smooth operation within the EDS framework. This redesign includes:
+  - Improved contract architecture for better integration with EDS.
+  - Enhanced security measures to protect against potential vulnerabilities.
+  - Optimized performance to handle the distribution process more efficiently.
+
+## Impact
+
+- **Users**:
+  -  Can create new subjects that are called Meritocratic Autonomous Organizations (MAOs).
+  -  Will benefit from a more secure and efficient distribution process.
+- **Developers**: Developers will need to familiarize themselves with the new contract architecture and EDS integration.
+- **Operations**: The distribution process will be streamlined, reducing the potential for errors and improving overall system reliability.
+
+## Next Steps
+
+- **Documentation**: Update the documentation to include details on the new EDS integration and contract redesign.
+- **Testing**: Conduct thorough testing to ensure the new system operates as expected.
+- **Deployment**: Plan and execute the deployment of the updated contracts and distribution system.

.changeset/ten-hats-watch.md

@@ -0,0 +1,5 @@
+---
+'rankify-contracts': minor
+---
+
+Created new playbook scenario 'gameCreated' and some general playbooks refactors

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: @peeramid-labs
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/workflows/main.yml

@@ -1,8 +1,11 @@
 name: CI
-on: 
+on:
   pull_request:
     branches: [main,staging]
     types: [opened, reopened, labeled, synchronize]
+env:
+    FORK_RPC_URL: ${{ secrets.FORK_RPC_URL }}
+    NODE_ENV: 'TEST'
 jobs:
   lint:
     runs-on: ubuntu-latest
@@ -22,3 +25,4 @@ jobs:
 
       - name: Running tests
         run: pnpm test:parallel
+

.github/workflows/release.yml

@@ -8,6 +8,8 @@ on:
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 permissions: {}
+env: 
+  FORK_RPC_URL: ${{ secrets.FORK_RPC_URL }}
 jobs:
   release:
     permissions:

.gitignore

@@ -273,3 +273,6 @@ types
 bin/
 /deployments/localhost/
 /deployments/hardhat/
+
+abi/
+docs/contracts/

README.md

@@ -1,83 +1,116 @@
-# Rankify smart contracts
-![rankToken_resize](https://github.com/rankify-it/contracts/assets/61459744/82d4496e-7e46-47ee-8f2f-2fca6d3c30b8)
+### Installation
 
+1. Clone the repository:
+
+   ```sh
+   git clone https://github.com/rankify-it/contracts.git
+   cd contracts
+   ```
 
-## What is it about?
+2. Install dependencies:
 
-This is a gamified implementation of "Continious voting" protocol where participants assumed to engage over large periouds of time in a series of rounds and even diffenrent instances. Final goal being - to allow creating ladder where winners are ultemately selected for their ability to propose best ideas, that their group accepts in a blind voting/proposal cycle and which is averaged over large number of rounds, and, frankly - can be played indefinately.
+   ```sh
+   pnpm install
+   ```
 
-### Manifesto
+3. Setup environment variables
 
-Think of today governance systems and how projects are extremely dependent on a centralized authority of core develoepers, organizations - on their creators etc. This happens because de-facto way how governing happens is still based on principles of leadership that are defined in same rules as thousands years ago.
-In a modern technology world there are ways to improve such systems and processes. We are able to build more robust, sustainable and lasting collectives by basing them on algorithms. Hence in this project - it is a **social experiment** on finding such a system that would proove it's effectiveness and would be hence in demand by any institution from family-friends to larger enterprise or DAOs.
+   ```sh
+   mkdir .secrets
+   cp dev.env.sample .secrets/dev.env
+   vi .secrets/dev.env
+   ```
 
-#### Assumptions
-In this manifesto we assume that **More effective governance systems are possible**, that eventually **effeciveness is the key for adoption** and that this is the only way for **DAOs** to see large scale adoption. It is asserted also that Distributed-Ledger technology is de-facto graal for building such a system, because this allows to build trust and verify trust in trully trustless enviroments.
+4. Compile the smart contracts:
 
-#### Building better world
-All contents of this work are related primarly towards allowing growth of not just Ethereum ecosystem. Belive in better world for everyone and that this Application can become a worlds first mass-adopted system. Hence requirements are put as follows: it must be **simple** to use, **require as less wallet actions as possible**, **fun and easy** and even allow **vote-to-earn** mechanisms in some cases.
+   ```sh
+   pnpm hardhat compile
+   ```
 
-### How it works?
+5. Deploy the smart contracts:
+   ```sh
+   pnpm hardhat deploy --network <network> --tags <tags>
+   ```
 
-#### Ideally (not everything is yet implemented):
-There will be DAO who custodies the Governance Technology Research & Development; It will act as custodian for a **InstanceFactory** that is able to emit new Instances contracts. Each **instance** has its **subject**, that is being voted on, and a game settings such as max/min players, time per turn etc;
-For each such instance, at least one **Rank Token** will be deployed from same factory as well; This is an ERC1155 extension that allows to level up tokens as well as some extended functionality which we will touch on later. This token acts as a representation of **rank** of the bearer for a particular voting subject of the **instance**. **Token id** - represents rank level; In order to get higher level rank tokens players need to have previous rank token in their possesion; This creates a ladder, where you need to either win a lot of games. Optionally making the rank tokens **tradable** enables users for **vote-to-earn** mechanism, where they could potentially sell their high-ranking token to somone who wants to have a "social lift". This is a subject to explore as tokenazible "lobbying".
+## Available Distributions
 
-To allow maximum participation, DAO will create games that can be joined by **anyone** who can fulfill basic payment requirement, however **game creators** are able to impose additional requirements, such as betting, locking, possesing as start, or paying game creator - to make games more exciting and also to allow scoping access to a particular game.
+We are using [Ethereum Distribution System](https://github.com/peeramid-labs/eds) to enable users to deploy their own infrastructure in transparent and decentralized way.
 
-Hence player can play a game of "best music" with his friends, but if he later on wants to proove his musical taste capacity somewhere in the world - he can show the rank of the token, therefore justifying his level. Furthermore such mechanisms can be explored as "burning reputation" in exchange for goods or services. Which might sound wierd, but if we give it a thought - werent we doing this some times in our lives?
+In order to be out of box compatible with the interfaces & notifications of the Rankify platform, any deployment should should be done from the Peeramid Labs Distributor contract ([PeeramidLabsDistributor.sol](./src/distributors/PeeramidLabsDistributor.sol)).
 
-The fact that there can be multiple such games also creates ability to get a **multidimensional** pattern of players competences.
+Specific address for distributor deployment can be found in the [deployments](./deployments) folder.
 
-And as a **byproduct** we are getting lists, sorted by highest score, that represent best ideas of some particular group over set of rounds.
+### Meritocratic Autonomous Organization (MAO)
 
-It's worth of noting that important concept for such a system is to ensure not just voting privacy, but also proposing privacy, together with emposing some rules (since there are subjects - at least subject must be followed). Which is untrivial task and so far the implementation falls-back to using web2 servers that will run as **Game Masters**  to ensure proposer/voter semi-privacy (after round is over we will publish accounts) and proposal moderation. This is short-medium term solution
-**ZK-Proofs** and eventually **FHE** and/or **TEE** should as a long term goal allow us to have fully trustless setup where we will achieve at least Full verification of data integrity or at best case - full encapsulation of data from any 3rd party viewer.
+[MAODistribution.sol](./src/distributions/MAODistribution.sol) is used to create a new Meritocratic Autonomous Organization (MAO).
 
-#### What do we have today
-We can create a game, and simple dApp for that; Factory still to be implemented, as well as DAO contract and ZKProofs/Signature workflows;
+This deployment will create following infrastructure:
 
+- [RankToken](./src/tokens/RankToken.sol) - ERC1155 token used to represent the ranks in the MAO.
+- [Governance token](./src/tokens/DistributableGovernanceERC20.sol) - ERC20 token used to represent the governance in the MAO.
+- [ACID Distribution](./src/distributions/ArguableVotingTournament.sol) - Arguable Voting Tournament contract used to distribute governance tokens.
+- [Aragon OSx DAO](https://aragon.org/) - Aragon DAO used as wrapped smart account that represents the MAO.
+- [Aragon Token Voting Plugin](https://github.com/aragon/token-voting-plugin) - Aragon plugin used to vote on proposals within the DAO.
 
-### Who will use it
-For blockchain-native people this can be used as extension to any DAO system. You could determine subjects of competence (i.e. financial or technical topics) and multiply DAO participant weights against their Rank Token.
+#### How to instantiate
 
-However worth mentioning that this is going to be a first really end-user blockchain app, that is really able to change everyday life of regular people by playing such games and gradually learning way of blockchain governances.
+In order to instantiate the MAO distribution, you don't need to deploy a thing. You just need to call the `instantiate` function of the the [PeeramidLabsDistributor.sol](./src/distributors/PeeramidLabsDistributor.sol) contract and specify proper distribution Id and arguments.
 
-## Contracts
+```ts
+import { MAODistribution } from 'rankify-contracts/types';
+const distributorArguments: MAODistribution.DistributorArgumentsStruct = {
+  DAOSEttings: {
+    daoURI: 'https://example.com/dao',
+    subdomain: 'example',
+    metadata: ethers.utils.hexlify(ethers.utils.toUtf8Bytes('metadata')),
+    tokenName: 'tokenName',
+    tokenSymbol: 'tokenSymbol',
+  },
+  ACIDSettings: {
+    RankTokenContractURI: 'https://example.com/rank',
+    gamePrice: 1,
+    joinGamePrice: 1,
+    maxPlayersSize: 16,
+    maxTurns: 1,
+    metadata: ethers.utils.hexlify(ethers.utils.toUtf8Bytes('metadata')),
+    minPlayersSize: 4,
+    paymentToken: rankify.address,
+    rankTokenURI: 'https://example.com/rank',
+    timePerTurn: 1,
+    timeToJoin: 1,
+    voteCredits: 14,
+  },
+};
+const data = ethers.utils.defaultAbiCoder.encode(
+  [
+    'tuple(tuple(string daoURI, string subdomain, bytes metadata, string tokenName, string tokenSymbol) DAOSEttings, tuple(uint256 timePerTurn, uint256 maxPlayersSize, uint256 minPlayersSize, uint256 timeToJoin, uint256 maxTurns, uint256 voteCredits, uint256 gamePrice, address paymentToken, uint256 joinGamePrice, string metadata, string rankTokenURI, string RankTokenContractURI) ACIDSettings)',
+  ],
+  [distributorArguments],
+);
+const distributorsDistId = process.env.DISTRIBUTOR_DIST_ID;
+const tx = await distributorContract.instantiate(distributorsDistId, data);
+```
 
-### RankifyInstance
-It is a diamond contract that consit of
-- [RankifyInstanceMainFacet.sol](https://github.com/rankify-it/contracts/tree/main/src/facets/RankifyInstanceMainFacet.sol) - main functionality availible to players and for read operations
-- [RankifyInstanceGameMastersFacet.sol](https://github.com/rankify-it/contracts/tree/main/src/facets/RankifyInstanceGameMastersFacet.sol) - game master access only methods
-- [RankifyInstanceGameOwnersFacet.sol](https://github.com/rankify-it/contracts/tree/main/src/facets/RankifyInstanceGameOwnersFacet.sol) - game owner access only
-- [RankifyInstanceRequirementsFacet.sol](https://github.com/rankify-it/contracts/tree/main/src/facets/RankifyInstanceRequirementsFacet.sol) - requirements module additional functionality
-- [IRankifyInstanceCommons.sol](https://github.com/rankify-it/contracts/tree/main/src/interfaces/IRankifyInstanceCommons.sol) - some common structures shared across facets and libraries
+In order to get `distributorsDistId` you can call `getDistributions` at `PeeramidLabsDistributor` contract and look for. We will host a public API to get the list of distributions soon.
 
-On the background these facets refer to a libraries that implement storage and logic, main to note are:
-- [LibTurnBasedGame.sol](https://github.com/rankify-it/contracts/tree/main/src/libraries/LibTurnBasedGame.sol) - generalized functionality of a turn based game (welcome to reuse for your project :) )
-- [LibQuadraticVoting.sol](https://github.com/rankify-it/contracts/tree/main/src/libraries/LibQuadraticVoting.sol) - generalized functionality of quadradtic voting for case of multiple proposals/proposers and pre-defined vote credits
-- [LibRankify.sol](https://github.com/rankify-it/contracts/tree/main/src/libraries/LibRankify.sol) - game instance functionality itself
-- [LibCoinVending.sol](https://github.com/rankify-it/contracts/tree/main/src/libraries/LibCoinVending.sol) - Library that manages requirements, funds/refunds and adds ability to lock/bet/pay/burn when game reaches certain conditions
+### ACID distribution
 
-### Rank token
-It's an extension of ERC1155 that adds following functionality:
-- [IRankToken.sol](https://github.com/rankify-it/contracts/tree/main/src/interfaces/IRankToken.sol) - adds ability to level up tokens, set up a instance who it is connected to for emitting new tokens and ability to find accoount rank level
-- [CompositeERC1155.sol](https://github.com/rankify-it/contracts/tree/main/src/abstracts/CompositeERC1155.sol) - adds ability to compose multiple rank tokens tokens in one. This we need to provide ability to create games that represent a "vector" of different "dimensions"
-- [LockableERC1155.sol](https://github.com/rankify-it/contracts/tree/main/src/abstracts/LockableERC1155.sol) - adds ability to lock tokens without changing their owner. This allows to correctly display owners rank even if he is in the game, or if he composed his token in a composite
-
-### [Rankify token ](https://github.com/rankify-it/contracts/tree/main/src/tokens/rankify.sol)
-It is just an ERC20 token, it will be owned by governing organization and will be emitted to control quotas for joining games (you will need to pay this token to join the game)
-
-
-### Smart contract security model
-
-From a high level overview there is splitt of highly complex and sophisticated **RankifyInstance** from actual assets - **Rank tokens**, this is a primary reason why they are not encapsulated under one proxy. Diamond Proxy is needed for GameInstance because of planned upgrades for ZKP privacy and other improvements, and also because of size constraints on EVM bytecode.
-
-While all this, the DAO and Rankify Token contracts will be kept as simple as possible and isolated from depending on these contracts (at least until they are well established and battle tested)
+[ArguableVotingTournament.sol](./src/distributions/ArguableVotingTournament.sol) is used to distribute governance tokens to the participants of the MAO by conducting autonomous competence identification tournaments.
 
+This distribution deploys the Diamond Proxy that contains the following facets:
 
+- [EIP712InspectorFacet](./src/facets/EIP712InspectorFacet.sol) - Facet that contains the main logic of the distribution.
+- [RankifyInstanceMainFacet](./src/facets//RankifyInstanceMainFacet.sol) - Facet that contains the main logic of the distribution.
+- [RankifyGameMastersFacetFacet](./src/facets/RankifyInstanceGameMastersFacet.sol) - Facet that contains the main logic of the distribution.
+- [RankifyInstanceGameOwnersFacet](./src/facets/RankifyInstanceGameOwnersFacet.sol) - Facet that contains the ownable logic of the distribution. (NB this will be deprecated)
+- [RankifyInstanceRequirementsFacet](./src/facets/RankifyInstanceRequirementsFacet.sol) - Facet that contains the requirements logic of the distribution.
 
+To understand how it works further please refer to [docs.rankify.it](https://docs.rankify.it/governance) or ask us a question in [Discord](https://discord.gg/EddGgGUuWC)
 
+## Contributing
 
+We welcome contributions to improve the Rankify smart contracts. Please fork the repository and submit a pull request.
 
+## License
 
+This project is licensed under the MIT License.