From 6e8572250ddb5657be81b6787d0914fb3355c66c Mon Sep 17 00:00:00 2001 From: Moody Salem Date: Fri, 15 Mar 2024 11:09:44 -0400 Subject: [PATCH] update the docs --- README.md | 51 +++++++++++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index c1ec920..c1eaed1 100644 --- a/README.md +++ b/README.md @@ -8,42 +8,49 @@ Simple contracts for governance on Starknet. Each component of the governance contracts in this repository may be used independently. -### Airdrop +### Distribution -`Airdrop` can be used to distribute any fungible token, including the `GovernanceToken`. To use it, you must compute a binary merkle tree using the pedersen hash function. The root of this tree and the token address are passed as constructor arguments. +#### Airdrop -- Compute a merkle root by computing a list of amounts and recipients, hashing them, and arranging them into a merkle binary tree -- Deploy the airdrop with the root and the token address -- Transfer the total amount of tokens to the `Airdrop` contract -- The contract has no owner and is not upgradeable. Unclaimed tokens, by design, cannot be recovered. +`Airdrop` is a highly-optimized distribution contract for distributing a fungible ERC20-like token to many (`O(1e6)`) accounts. To use it, you must compute a binary merkle tree using the pedersen hash function of an `id`-sorted list of `Claim` structs. The root of this tree and the token address are passed as constructor arguments and cannot change. -### Staker +- Compute a merkle root by producing a list of `Claim` structs, hashing them, sorting by sequentially-assigned ID, and arranging them into a merkle binary tree + - Claim IDs must be sorted, start from `0` and be contiguous to make optimal use of the contract's `claim_128` entrypoint +- Deploy the airdrop with the `root` from this merkle tree and the token address +- Transfer the total amount of tokens to the `Airdrop` contract +- Unclaimed tokens can be refunded to the specified `refund_to` address after the `refundable_timestamp`, _iff_ `refundable_timestamp` is not zero -`Staker` is a contract used by the governor for staking tokens to be used in voting. +### Governance -- Users MAY delegate their tokens to other addresses -- Users lock up their tokens, staking them which allows them to be delegated -- The average historical delegation weight is computable over *any* historical period -- The contract has no owner and is not upgradeable. +#### Staker -### Timelock +`Staker` enables users to delegate the balance of their token towards an account, and tracks the historical delegation at each block, plus allows the computation of the time-weighted average delegation of any account over any historical period. -`Timelock` allows a list of calls to be executed, after a configurable delay, by its owner +- Users call `Token#approve(staker, stake_amount)`, then `Staker#stake(delegate)` to stake and delegate their tokens to other addresses +- Users call `Staker#withdraw(delegate, recipient, amount)` to remove part or all of their delegation +- The average historical delegation weight is computable over *any* historical period +- The contract has no owner, and cannot be updated nor configured. -- Anyone can execute the calls after a period of time, once queued by the owner -- Designed to be the owner of all the assets held by a DAO -- Must re-configure, change ownership, or upgrade itself via a call queued to itself +#### Governor -### Governor +`Governor` allows holders to vote on whether to make a _single call_ -`Governor` allows `GovernanceToken` holders to vote on whether to make a _single call_ -- The single call can be to `Timelock#queue(calls)`, which can execute multiple calls in a single proposal - None of the proposal metadata is stored in governor, simply the number of votes - Proposals can be canceled at any time if the voting weight of the proposer falls below the configurable threshold +- The single call can be to `Timelock#queue(calls)`, which may execute multiple calls +- The contract has no owner, and cannot be updated nor re-configured. + +#### Timelock + +`Timelock` allows a list of calls to be executed after a configurable delay by its owner + +- Anyone can execute the calls after a period of time, once queued by the owner +- Designed to be the principal agent in representation of the DAO, i.e. hold all assets +- The contract has an owner, and may be upgraded or configured via a call to self. -### Factory +#### Factory -`Factory` allows creating the entire set of contracts with a single call. +`Factory` creates the set of governance contracts (`Staker`, `Timelock`, `Governor`) in a single call. ## Testing