All the libraries, contracts and functions should have relevant DoxygenStrings. Docs should follow the same style, describing the interface and purpose. Non-trivial math should be explained in detail. If the code was inherited or inspired, the link to the source should be provided.

Styling references:

@aragon/os/contracts/apps/AragonApp.sol
@aragon/os/contracts/lib/math/SafeMath.sol
@openzeppelin-solidity/contracts/token/ERC20/ERC20.sol

We need to come to an agreement for an insurance spec with cover providers. From what I can gather, no additional smart contract coding is required to buy cover and redeem it, it's just a simple tx by a DAO, but there might be options.

Base branch: steth_depool_linked

Fix muted assertions and setups in integration tests:

• depool_happy_path.js:301-308
• depool.test.js - lines highlighted with //FixMe

This spec describes logic of accounting and distributing rewards on the Ethereum 1 side according to Ethereum 2 side balance changes.

The idea is to distribute rewards by diluting the supply of StETH and giving newly generated tokens to proper parties. Moreover, slashing is taken into account so as not to take fee on Ether2 rewards which just replenish slashed balances.

Initially set:

fee_basis_points = <number in [0..10000]> # protocol fee rate

treasury_fee_basis_points = <number in [0..10000]> # share of protocol fees going into the treasury
insurance_fee_basis_points = <number in [0..10000]> # share of protocol fees going into the insurance fund
staking_providers_fee_basis_points = <number in [0..10000]> # share of protocol fees distributed among staking providers
require(treasury_fee_basis_points + insurance_fee_basis_points + staking_providers_fee_basis_points == 10000)

reward_base = 0

On each deposit to the Ethereum 2 side:

on_deposit(deposit):
    reward_base += deposit  # increase is coming our way, but thats not rewards

On each update of the Ether on the Ethereum 2 side by the oracle:

on_oracle(ether2):
    if ether2 > reward_base:
        rewards = ether2 - reward_base
        distribute(rewards, ether2)
        reward_base = ether2

distribute(rewards, ether2):
    protocol_rewards = rewards * fee_basis_points / 10000
    
    steth_to_mint = protocol_rewards * steth.total_supply() / (getTotalControlledEther() - protocol_rewards)
    // Where getTotalControlledEther = buffered + eth on eth2 side - withdrawals

    steth.mint(vault, steth_to_mint * treasury_fee_basis_points / 10000)
    steth.mint(insurance_fund_vault, steth_to_mint * insurance_fee_basis_points / 10000)
    steth.mint(staking_providers_fund, steth_to_mint * staking_providers_fee_basis_points / 10000)

Distribution inside staking_providers_fund is covered by a staking providers spec.

The following table summarizes the list of DePool contracts, docs and test improvements for RC-2 release candidate. RC2 plans will be confirmed on the zoom call 28 Oct 2020.

Timing:
PRs are ready: 12 Nov 2020

RC-2 release: 19 Nov 2020

For RC-1 backlog see #77

Table maintained by @ongrid. Please feel free to drop your ideas in comments (for discussion) or create the issue with assigned RC-2 milestone if you are able to finally formalize the scope and provide the link to it.

Aragon frontend stubs are utterly useless in this repo, we should remove them

Now IValidatorRegistration interface and ValidatorRegistrationMock are synthetic. To prove compatibility with real-world environment, we should switch to official Ethereum 2 DepositContract and use it in all the test scenarios.

Note: Since there is a lot of math and costly operations (including iterative Merkle Tree walks) inside the real deposit call we can get new gas estimates and the numbers may depend on the Deposit contract state. Probably we'll need to test it at scale.

Related issue: #82

This spec describes the staking provider entity. The staking provider is an entity validating Ethereum 2.0 on behalf of the stakers and controlled by the dao.
Up until now, there was no staking provider distinction in the signing key management. Now we can slice the key management into sub-pools keeping most of the key management logic intact.

Interface

Each staking provider has the following properties:

• id (uint, starting from 1) - a unique key
• active (bool) - a flag indicating if the SP can participate in further staking and reward distribution
• name (string) - human-readable name
• rewardAddress (address) - Ethereum 1 address which receives steth rewards for this SP
• stakingLimit (uint) - the maximum number of validators to stake for this SP
• keys (array of pairs (signing key, deposit signature)) - signing keys to use for signing blocks on the Ethereum 2 side
• stoppedValidators (uint) number of signing keys which stopped validation (e.g. were slashed)
• usedKeys (uint) - internal property, number of signing keys of this SP which were used in deposits to the Ethereum 2

Properties active, name, rewardAddress, stakingLimit, keys, stoppedValidators are modifiable by any actor with the proper access rights.
Keys are modifiable by the corresponding rewardAddress (implicit permission).

The active property can be switched back and forth, i.e. an SP can be reactivated.
The stakingLimit property can be set to any value, even less than the current stake.
No one can remove signing keys that were already used.
The stoppedValidators property is incremental, i.e. we can only add a positive number to the existing value.

Implementation details

Keeping SPs in a storage array indexed by the SP id is trivial, as well as changing their properties. Each property should be managed by a dedicated function with a dedicated access role. totalSigningKeys and usedSigningKeys global vars go to the SP structure.

Key management changes.

addSigningKeys and removeSigningKey functions get an extra argument - SP id. This parameter should be eventually passed to the _signingKeyOffset function which should calculate the offset as keccak256(abi.encodePacked(SIGNING_KEYS_MAPPING_NAME, SP_id, _keyIndex)). This way we isolate the keys of each SP from others.

_ETH2Deposit changes.

Before loading the next signing key we have to find an SP to load the key from.
We filter out deactivated SPs and SPs out of available keys.
Then, for the remaining SPs we filter out any for which usedKeys - stoppedValidators + 1 > stakingLimit holds true.
Then, we find the SP with the smallest usedKeys - stoppedValidators value.
Transparent optimizations can be applied, e.g. caching the array of stakes in memory during the main _ETH2Deposit loop execution.

Reward distribution.

We designate total reward to be distributed among stake providers as totalReward.
Then, we filter out deactivated SPs.
Then, for each i-th SP we calculate effectiveStake[i] as usedKeys[i] - stoppedValidators[i].
Then, we sum all the effectiveStakes to effectiveStakeTotal.
Then, for each i-th SP their reward is calculated as effectiveStake[i] * totalReward / effectiveStakeTotal and transferred to their rewardAddress.

To make oracles less dangerous, we can bound rewards report by 0.1% increase in stake and 15% decrease in stake, with both values configurable by DAO voting in case of extremely unusual circumstances.

Currently, multiple different styles are mixed within even a single test file:

• Semicolons/no semicolons;
• Different string literal brackets;
• Indentation (2 or 4 spaces);
• etc.

This makes it harder to read and write the code. I would suggest to agree upon some selected style and use it throughout our whole codebase.

As for the style itself, I'd suggest JavaScript Standard Style since it's used in most projects, including blockchain/DeFi ones.

I would also use some linter to enforce the selected style.

Minimal wrap/unwrap functions

Methods responsible for swapping between stETH and cstETH tokens.

Wrapping

Transforming dynamic stETH token to classical cstETH is made in two-stage approach:

1. the holder authorises cstETH contract to transfer given amount of stETH on his behalf.
2. the holder initiates cstETH.wrap() tx and provides reserved amount of stETH and the address to withdraw stETH from

wrap(addr, stETHamount) called by the holder of stETH.

3. cstETH contract withdraws approved amount of stETH and puts it into collateral, then mints the same amount of cstETH tokens to the holder

Example: yUSD:_deposit

UnWrapping

The opposite action initiated by someone wishing to return cstETH and get the corresponding amount of stETH token back.

1. the holder authorises cstETH contract to withdraw given amount of cstETH.
2. then holder initiates cstETH.withdraw() tx and provides the amount of approved cstETH

unWrap(addr, cstETHamount) called by the holder of cstETH.

3. cstETH contract withdraws and burns the approved amount of cstETH and then calculates the amount of stETH and sends i back from the collateral.

Example: yUSD:_withdraw

• The ratio should be implemented as a constant 1:1 (the spec is in progress).
• Unit tests
• use abstract ERC-20 mock for stETH

Base branch: steth_depool_linked

Unit tests with mocked dePool

• steth.test.js should be extended with OZ-like modular tests
• steth.test.js every share-changing operation need to assert the effect on shares
• user burns his tokens, other users see their balances increase

Integration tests (depool_w_steth.test.js)

• user burns his tokens, other users see their balances increase

        // Calculating real amount of rewards
        uint256 rewardBase = REWARD_BASE_VALUE_POSITION.getStorageUint256();
        if (_eth2balance > rewardBase) {
            uint256 rewards = _eth2balance.sub(rewardBase);
            REWARD_BASE_VALUE_POSITION.setStorageUint256(_eth2balance);
            distributeRewards(rewards);
        }

That's the code that is calculating rewards: it thinks that any positive change in eth2 balance (between last and this report) is a reward and any negative one is slashing.

Imagine this scenario:

Block X-100000: deposit 32 eth (total_used_keys = 1)

Block X-1: oracle computes report (epoch,  _eth2balance = 32.01)

Block X: 
1. deposit 32 eth (reward base = 64eth)
2. oracle final report (_eth2balance = 32.01eth, epoch)

Now we have almost 32eth slashing.

rename StakingProviders to NodeOperators

As of now withdraw lets you get a bit of ether from the buffer and burns your tokens + signals that you want to withdraw. At the start there'll be no withdrawal logic implemented yet bc there's no state transitions on eth2 and working temporary solutions around that is too complex for us to possibly fit into the deadline.

Thus, withdraw function should be there with a correct interface (just like now) but it should be always throwing something along the lines of "NOT_IMPLEMENTED"

The following table summarizes the list of DePool contracts, docs and test improvements for RC-1 release candidate. RC1 plans are confirmed on the zoom call 20 Oct 2020.

For RC-2 see #94

Table maintained by @ongrid. Please feel free to drop your ideas in comments (for discussion) or create the issue with assigned RC milestone if you are able to finally formalize the scope.

Short Description and GH issue	Where	Type	Milestone, status, assignee	Details
SP Registry distributeRewards fails with stETH token #72	stETH	Integration	RC-1 @lxzrv @ongrid	Integration tests fail on reward distribution
Fix muted tests in steth_depool_linked #73	DePool, stETH	Tests	RC-1 @lxzrv @ongrid	Fix muted assertions and setups in integration tests: depool_happy_path.js:301-308 depool.test.js - lines highlighted with //FixMe
Withdraw explanation	DePool	Doc	RC-1 @vshvsh	withdraw function has unclear state - ToDo. Since it occludes the key business logic - it will be in the main people focus, so its docstring should describe in detail about future implementation and migration. When and how it will be implemented, how migration to the contract with implemented withdraw will be carried out. It must be the most documented function in the entire codebase.
Fix solc, solium and solhint warnings #84	DePool, Oracle, stETH, cStETH + child libs and interfaces	Unify	RC-1 @ongrid @lxzrv	Fix solhint warnings and stilyze the contract codebase in a single manner including existing comments. Fix compiler warnings. Solc stdout should be clean.
Docstrings #87	DePool, Oracle, stETH	Doc, Unify	RC-1 @ongrid	All the libraries, contracts and functions should have relevant DoxygenStrings. Docs should follow the same style, describing the interface and purpose. Non-trivial math should be explained in detail. If the code was inherited or inspired, should provide the link to the source.
Solc motivation #86	DePool, Oracle, stETH, cstETH	Doc	RC-1 @ongrid	Comment above pragma statement should clearly explain why solidity 0.4.24 or 0.6.x selected for specific contract.
ACL roles	DePool, Oracle, stETH	Doc	RC-1 @skozin	Describe each ACL role and where it's used
Positions	DePool, Oracle, stETH	Doc	RC-1 @skozin	describe why POSITIONs used instead of traditional variables
reportEther2 RBAC #85	DePool, Oracle, stETH	Unify	RC-1 @ongrid @Klyaus	DePool.sol:reportEther2 - use Aragon's approach with role modifier instead of require check
JavaScript code style #19	Tests, Frontend	Tests	RC-1 @krogla or @skozin ?	Currently, multiple different styles are mixed within even a single test file. This makes it harder to read and write the code.
IDepositContract #88	DePool	Unify	RC-2 @Klyaus	use original Ethereum 2 IDepositContract instead of IValidatorRegistration for simplicity and uniform terminology.

Other 16 items were moved to Backlog for RC-2 milestone #94

Suggestions:

1) Implement getSigningKeys() function which will return an array of signing keys that were added for current sp.
Current solution: right now we can only getSigningKey(sp_id,SigningKey_index)
Reason: for testing purposes where we will test the whole system with a big number of signing keys. We must check the correctness of added signing keys with the source. We can't expect how the system will react to it and also it's not too flexible to call getSigningKey(sp_index,signingKey_index) 200 times for example.
2) Implement getActiveSigningKeys() function which will return an array of active signing keys that became active after validators started.
Current solution: right now we can only check that added signing keys are started validation by check sp1.getUsedSigningKeys().
Reasons: To match used signing keys with active validators pubKeys in the eth2 side. We can clearly check sp1.usedSigningKeys() count,but can`t correctly compare usedSigningKeys active validators pubKeys in eth2.

In conclusion, I might admit that in bundle sp signing keys -> to eth2 we can`t track correctly this action.

Currently, the submit function, compiled with 200 optimizer iterations, consumes around 577000 gas plus 107000 gas for each registered validator, so the default limit is set by deploy scripts to 16 validators to make the submit transaction occupy no more than 20% of a block. See this file for the related calculations; you can run them with yarn estimate-deposit-loop-gas.

That is on average 130k+ gas per validation key in a batch of 16, about twice as much as a simple deposit. We might find a way to make this number lower.

Note: Switching to the official Deposit contract #88 will impact the numbers mentioned above

Deposit keys take 48 bytes which means they take 1.5 slots each that is padded to 2 (and signature takes exactly 3). We can try to pack them more tightly, leading to about 10% reduction in storage costs (5 slots to 4.5). Need to investigate if it's worth increased complexity.

According to the official version, the sha256 function is used in the calculation of deposit_data_root (ETH 2.0. spec), whereas in our code keccak256.

As a result, it is impossible to transfer (make submit) more than 32ETH to the DePool contract, due to transaction revert in the Deposit Contract.

#56

addSigningKeys pas a lot of gas for storage (in extremis it's about 1-2k of ether total, but even in the worst case it'll be about 30 eth). Calling functions through dao voting temporarily storages the arguments until the vote is set, leading to double pay for the storage. This is prohibitively expensive for no particular reason, we should do something about it.

Options I see:

1. Staking providers can set or remove their own keys up to threshold set by the DAO (that looks the best so far)
2. DAO votes for a hash of keys to add and then anyone can add the keys with the approved hash (variant: merkle root) (too complex)
3. do a voting modification that allows to vote for an action hash instead of a whole action

There should be an optional parameter in deposit function that takes a referral eth address eg
deposit_with_referral(uint256 referral) payable
That parameter is either unused or emits an event with referral address. I'd prefer a calldata referral bc it's cheaper, but event's okay too

There should be a script to collect referral data in the following format, given block1 and block2.
between block1 and block2 (both included) there have been referalls:

0x123...890 1000.8249240020934eth   10.008249240020934% 
0xabc...def 200eth                  2%

The easiest and most useful way to make that is probably thegraph subgraph, but something simpler might work too

Rename

• ETHER to ETH in constant names (Ether/Ethers allowed in comments)
• getBufferedEther to getBufferedEth
• getTotalControlledEther to getTotalPooledEth
• _getUnaccountedEther to _getUnaccountedEth

In the StakingProvidersRegistry contract, the addSigningKeys and removeSigningKeys functions have a custom realization of the permissions check (via 'canPerform') to run the function, but not the recommended Aragon authP modifier.

The buidler-aragon utility, therefore, generates errors when building the application.

I suggest dividing each one of these functions into three separate functions, two of which are simply a wrapper for a 3-d internal function, and have different call permission checks (1-st via 'authP' modifier, 2-nd with custom check).

Sample implementation:

    function removeSigningKey(uint256 _SP_id, uint256 _index) external
        authP(MANAGE_SIGNING_KEYS, arr(_SP_id))
        SPExists(_SP_id)
    {
        _removeSigningKey(_SP_id, _index);
    }

    function removeSigningKeySP(uint256 _SP_id, uint256 _index) external
        SPExists(_SP_id)
    {
        require(msg.sender == sps[_SP_id].rewardAddress);
        _removeSigningKey(_SP_id, _index);
    }

    function _removeSigningKey(uint256 _SP_id, uint256 _index) internal
    {
       // rest of original code
   }

Implement minimal ERC-20 token with fungible-asset functions and classical behavior. In contrast to native DePool platform's stETH token, account balances should change only by making a transfer, so it can be used in any DApp, that expects such behavior.

• Code should be inherited from recent OpenZeppelin v3.2.x (for solc 0.6.x or 0.7.x). via package if possible.
• Mintable, but external mint function should be removed from base (move to mock).
• All relevant tests should be adapted from OpenZeppelin (keep builder as the framework)
• Add different compiler for token (keep paths of Aragon and its apps intact)

Specification for fungible token functions

Base interface: ERC-20 - de-facto standard for fungible assets on Ethereum. Inherited from well-known OpenZeppelin library.

Decimals: 18 - matches ETH1.0 Ether and stETH

Symbol: cstETH - Compound-style staked ETHer

Name: Wrapped Liquid staked DePool Ether

Burnable: yes - The ability to discard holder's own tokens allows further maneuvers with introduction of the new contract if needed (swap to new version, bridge one asset to another and so on).

Approvable: yes - transferFrom, approve, and allowance ERC-20 methods are used in DeFi workflows, allowing contracts to send tokens on your behalf.

Mintable: yes, internal - cstETH gets minted "internally" within the same contract. Mint function not exposed outside. New emission os done exclusively by depositing the same amount of underlying stETH

Minter: self - Minting is done by the calling the mint function by the Wrapping/Unwrapping functions of the contract. No external minters implemented.

Cap: no - The maximum circulating amount of tokens is not limited (no capped). The supply depends on: how much underlying stETH stay in collateral.

TotalSupply: Classical behavior - total supply increases on new deposits and decreases on withdrawals. Every totalSupply change strongly correlates with transactions and events.

BalanceOf: Classical behavior - balances are statically stored in the internal storage. Every balance change strongly correlates with transactions and events.

Event Arguments: Classical behavior - transfer event arguments always have strong arithmetical correlaion with balances.

Libraries used: SafeMath, OpenZeppelin

Related: depool-dao#3

If the withdrawal credentials change, staking providers will have to remove not a single erroneous key+signature, but all unused keys at once. Doing it one tx at a time is impractical. There should be a function to either remove all unused keys, or bulk replace the signature part of deposit data for a new withdrawal credential.

Now the insurance part of the protocol fee is going to a main treasury but it makes for a more difficult bookkeeping. Should be a separate treasury managed by the DAO.

For staked ether we need two types of tokens. We'll call them aTokens and cTokens, in honor of aave and compound protocols.

aTokens are the simplest conceptually: if you own 1 staked ether aToken, it means that there is 1 ether on beacon chain reserved just for you. E.g. if you deposit 100 ethers to depool, you get 100 aTokens. When stake under depool control gets a reward, your balance increases accordingly, when it's slashed it decreases.

After phase 2 is enabled, by burning 1 aToken you'll get 1 ether withdrawn from staking.

aToken balances are updated when oracle reposts change in total stake every day. Updating balances one by one in a balance map is unfeasible, that's why getBalance function of aToken should be implemented as (in pseudocode)
aToken.balanceOf(address) = depool.getCoeff()*depool.shareOfStakedETH(address)
Where coeff represents the growth/shrinking of beacon chain ether due to staking activity, and shareOf represents your part of that big pile of ether on beacon chain. It's not normalized (so, sum of all shareOf values is not 1) but if your shareOf is 1% of total shares it means you own 1% of all controlled ether on beacon chain.

If the balance on beacon chain is changed due to staking (rewards or slashing), your balance in aToken changes, but you still own the same share of the stake, and the only thing that changes is coeff. If you transfer your tokens, total beacon chain stake doesn't change and coeff remains the same, but the shareOf changes.

aToken's weakness is that it doesn't work properly in Uniswap v2, and won't work nicely with crosschain transfers (bridges won't report balance changes daily to other chains, we can't expect that)

aToken is the default token for staked Ether. User get it on deposit.

cToken is compound-style: your balance is fixed, but the amount of ether it's representing is changing. It is a "pro" token for staked ether to be used in complex defi and crosschain transfer, etc. If
aToken.balanceOf(address) = depool.getCoeff()*depool.shareOfStakedETH(address)
then
cToken.balanceOf(address) = depool.shareOfStakedETH(address)

shareOf changes on deposit, transfer, transferFrom, burn, things like that. Coeff changes on oracle reports.

Total sum of shares changes both on deposits and on oracle updates, bc reward fee is minted as new steth tokens (see #2 )

Task: depool should have both types of tokens and aToken should be convertible to cToken and vice versa at will. aToken should have the default name of stEth.

I see two ways to make that:

1. one is where cToken is the default token, and aToken is minted when you lock cToken and burned when you withdraw aToken (or vice versa)

    aToken.lock(cToken) -> return minted aToken
    aToken.burn_and_unlock(amount) -> return unlocked cToken

2. other is common interface and two tokens that use it

share_map
|       \
|        \
atoken   ctoken

I think having cToken as base and aToken as minted/burned is the simplest way to do that.

Here is my proposal for README structure for the repo.

I assume that we aim to leave only the contracts code along with unit tests in the repository. If everyone agrees with this statement, I also propose to discuss moving the code for running the local test environment and the web interface for Aragon into a separate repo. If possible.

Feel free to add things that I missed🙌

DePool Ethereum Liquid Staking Protocol

Overview

Brief description of the protocol
DAO description
Before getting started with this repo, please read:

• Whitepaper
• Documentation

Other Links

• Discord
• Audits
• Mainnet address

Contracts

The protocol is implemented as a set of smart contracts connected by Aragon.

DePool

Liquid staking pool implementation. The core contract that is responsible for acceptance Ether from users and minting liquid tokens in return, delegating staking to DAO's picked validators and manage/reward them, update StETH token balances according to staking performance reported by DePoolOracle.

DePoolOracle

Oracle tasked to inform other parts of the system about balances controlled by the DAO on the ETH 2.0 side

StETH token

StETH is a tokenized version of staked ether. Tokens are minted upon deposit and burned when redeemed. StETH tokens are pegged 1:1 to the Ethers that are held by DePool. StETH token’s balances are updated when oracle reports change in total stake every day.

CstETH token

CstETH is a compound style version of StETH token. Unlike the default StETH token, the balance of CstETH token remains fixed despite the changes Ether held by DePool DAO. But as DePool’s validators earn interest, CstETH becomes convertible into an increasing quantity of the underlying asset.

CstETH Vault

CstETH Vault is a contract that is responsible for minting CstETH. Minting CstETH is optional, users can stick with their StETH, which is fine for a lot of DeFi apps, but some of them are accepting only compound-style tokens. Users can deposit their StETH tokens to the contract and gets CstETH in return and vice versa (in this case CstETH tokens got burned).

Development

• Requirements
• Installation
• Build & test all our apps
• Other things

License

DePool is under ??? licence

Since official deposit contract is not our part, solidity linters should ignore it.

$ yarn run lint
yarn run v1.16.0
$ yarn lint:sol && yarn lint:js
$ yarn lint:sol:solhint && yarn lint:sol:solium
$ solhint "contracts/**/*.sol"

contracts/0.6.11/deposit_contract.sol
  114:15  error  Parse error: missing ';' at '('
  114:30  error  Parse error: missing ';' at 'gwei'
  114:39  error  Parse error: mismatched input ',' expecting ';'
  114:94  error  Parse error: extraneous input ')' expecting ';'
  115:44  error  Parse error: extraneous input 'gwei' expecting ';'

✖ 6 problems (5 errors, 1 warning)

error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Keeping the Aragon approach, implement dynamic outputs of balanceOf and totalSupply and related functions as specified in stETH token specification.

Base branch: steth_depool_linked

• Current tests don't actually cover dual SP configuration (just one SP active).
  The best option is to use modular setup like this

 with single sp configuration
  <adapt existing tests>
  then added second (inactive) SP
  <adapt setup. Asserts should produce the same result as above>
   then activated second sp with equal amount of keys
     <Adapt math>
     then added keys to first sp (now unequal amount of keys)
      <Adapt math>

Cosmetic:

• Initialize human-readeble sp reward addresses in the contract context instead of ADDRESS_1
• Fix function order according to the Natspec - external, public, internal, pure; const after non-const.

Parent issues: #70, #3

Depool name will be deprecated in favor of Lido.

Base branch: steth_depool_linked

Reason: PR review note "I think we need to add a test for burning (that burning stETH makes every other stETH account's balance bigger)" by @vshvsh

So need to add specific test where burning intentionally not synchronized with totalControlledEther. So we should see the burnt share and proportionally incremented balances of other users.

Parents: #70, #3

Current tight coupling of tokens with the AragonApp makes it inconsistent with the best practices:

• older solidity 0.4.24 available for Aragon is too far from 0.7 stable
• newer tools and approaches are unavailable for older solc

The tokens should be decoupled from this unnecessary dependency:

• Aragon should have just the required interfaces written in solidity 0.4.24
• The tokens are compiled by the separate solc 0.7 with up-to-date dependencies from OpenZeppelin
• The unit-tests for tokens are separate (based on open-zeppelin flow)
• The integration tests are still common

function reportEther2(uint256 _epoch, uint256 _eth2balance) uses in-block check of the caller:
require(msg.sender == getOracle(), "APP_AUTH_FAILED"). For RBAC it's correct to use Aragon's auth modifier. Examples: setWithdrawalCredentials and setDepositIterationLimit.

Effects stay the same.

E2E scenario should include running Oracle daemon (in single instance mode for now). So startup.sh script should

• initalize all relevant contracts (shouldn't need to navigate Aragon's UI)
• generate signatures
• submit the keys to the staking provider registry
• expose all relevant data to the oracle (ORACLE_CONTRACT, DEPOOL_CONTRACT)
• run the oracle instance

Oracle instance should:

• run with given envs
• connect to ETH1 and Beacon nodes
• pull validators' keys from the DEPOOL contract
• poll the keys for beacon balances and summarize them
• report the balances to the ORACLE contract

Related depool-dao#4

Currently, submitting even a small amount of Ether to the pool consumes a lot of gas, see #82 (comment). This can be fixed by moving staking to a separate function in Lido.sol:

• When a user submits Ether to the pool, it gets buffered and tokens are minted.
• Actual staking of the buffered Ether happens in a separate function (which can be called by anyone).

Currently, deploying DAO from the template consumes the amount of gas close to 12M limit, see #98 (comment).

The workaround is to extract assigning permissions to a separate function in the template and call it in a different transaction. Maybe smth else can be safely extracted from the main deployDAO function — need to think about it.

In the e2e environment an error occurs when trying to execute the pushData function in the oracle contract.
Presumably the error comes from an external call in function _tryFinalize

ValueError: {'message': 'VM Exception while processing transaction: revert', 'code': -32000, 'data': {'stack': 'c: VM Exception while processing transaction: revert\n at Function.c.fromResults (/usr/local/lib/node_modules/ganache-cli/build/ganache-core.node.cli.js:4:183508)\n at e.exports (/usr/local/lib/node_modules/ganache-cli/build/ganache-core.node.cli.js:48:1989251)', 'name': 'c'}}

Need to figure out why deploying the DAO from the template uses more than 12m gas.

Problem 1: we had an error in the DAO template - the stETH contract was initialized incorrectly: it has zero DePool contract address.

As a solution, it was possible, by analogy, to add a setPool function to the stETH contract. However, as the tests revealed, this leads to problem 2: more than 12 million of Gas is needed for the DAO deployment and the transaction fails.

I propose the following solution for both problems:
Remove the setPool functionality from the Oracle and SPRegistry contracts, and set the DePool address via the initialize function.
In the DePool contract, on the contrary, move the set of all associated contracts to a separate setApps function.
And simply change the order in which applications are initialized in the template.

This small optimization will reduce the amount of Gas to ~ 11M.

Base branch: steth_depool_linked

Integration tests with stETH fail on the line:

https://github.com/depools/depool-dao/blob/16820516a8e481e660f5dd106d150c7ff7b8866c/contracts/0.4.24/sps/StakingProvidersRegistry.sol#L312

Also noted that some transfers on this line were called with zero amount, that shouldn't be done.

This can affect depool.test.js:381 (reverts, commented-out)

Need to unmute treasury, insurance and SP balance assertions in depool.test.js:117 to 121

Fix function-order, indentation, blank-lines and line-length in solidity files. Keep comments and docstrings intact (they will be the subject of separate issue).

Styling references:

@aragon/os/contracts/apps/AragonApp.sol
@aragon/os/contracts/lib/math/SafeMath.sol
@openzeppelin-solidity/contracts/token/ERC20/ERC20.sol

• Add relevant configs for solium and solhint.
• Add solhint to package.json lint script (should run both)
• mute compile-time SPDX-License-Identifier warning (retaled to our code)

Add dynamic formula for wrap/unwrap functions of cstETH based on the following model discussed in modeling repo

    def get_cst_eth_by_st_eth(self, st_eth):
        st_eth_collateralized = self.st_eth.balanceOf(self)
        cst_eth_issued = self.total_supply
        cst_eth_per_st_eth = cst_eth_issued/st_eth_collateralized if st_eth_collateralized != 0 else 1.0
        return(cst_eth_per_st_eth * st_eth)
    
    def get_st_eth_by_cst_eth(self, cst_eth):
        st_eth_collateralized = self.st_eth.balanceOf(self)
        cst_eth_issued = self.total_supply
        st_eth_per_cst_eth = st_eth_collateralized/cst_eth_issued if cst_eth_issued != 0 else 1.0
        return(st_eth_per_cst_eth * cst_eth)

Add test-cases for later deposit with increased and decreased amounts of st_eth.balanceOf(cst_eth). Reward/Loss should be 'fair' - amounts of stETH after wrapping/waiting/unwraping should be strictly the same as if holder did nothing.

Parent Issue: #3

All contracts should contain comment above pragma statement that should clearly explain why solidity 0.4.24 or 0.6.x selected for specific contract.

Currently, the _ETH2Deposit function (which is used by DePool to stake Ether buffered in the contract) tries to register as many validators as possible, as long as there is Ether buffered and unused validator keys left in the registry.

This makes it possible for this loop to revert due to it consuming more gas than allowed in a single block, which may happen if the amount of Ether buffered in the contract is large enough. This, in turn, may happen either if somebody sends a large amount of Ether in a single transaction, or if staking providers run out of registered validator keys for some reason (e.g. technical issues) and users continue to send Ether in the meantime.

The situation that arises will effectively lock all buffered Ether and stop the contract from registering new validators.

The proposed fix is to bound the loop using some predefined iteration limit that will ensure that the loop won't consume more than a fraction (e.g. 20%) of block gas. Also, we'll need to add an externally-accessible function that would trigger staking of the remaining buffered Ether, so one may resume the staking loop broken by the iteration limit:

/**
  * @notice Signals that some received Ether was left buffered in the contract
  * due to the inability to register enough Ethereum2 validators in a single
  * transaction. In this case, one needs to manually call depositBufferedEther()
  * function to resume the registration loop.
  */
event NeedToResumeETH2DepositLoop();


/// @dev TODO: determine the optimal limit
uint256 constant internal MAX_VALIDATOR_REGISTRATIONS_IN_A_BLOCK = 30;


/**
  * @notice Deposits as much buffered Ether as possible in a single transaction.
  * The NeedToResumeETH2DepositLoop() event will be generated if more buffered Ether
  * can be deposited by calling the function once again.
  */
function depositBufferedEther() external whenNotStopped {
  _depositBufferedEther();
}


function _submit(address _referral) internal whenNotStopped returns (uint256 StETH) {
  // ...
  _depositBufferedEther();
}


function _depositBufferedEther() internal {
  uint256 buffered = _getBufferedEther();
  if (buffered >= DEPOSIT_SIZE) {
    uint256 unaccounted = _getUnaccountedEther();

    uint256 toUnbuffer = buffered.div(DEPOSIT_SIZE).mul(DEPOSIT_SIZE);
    assert(toUnbuffer <= buffered && toUnbuffer != 0);

    (uint256 deposited, bool canDepositMore) = _ETH2Deposit(toUnbuffer);
    _markAsUnbuffered(deposited);

    assert(_getUnaccountedEther() == unaccounted);

    if (canDepositMore) {
      emit NeedToResumeETH2DepositLoop();
    }
  }
}


function _ETH2Deposit(uint256 _amount) internal returns (uint256 deposited, bool canDepositMore) {
  // ...
  uint256 iter = 0;
  while (_amount != 0 && ++iter <= MAX_VALIDATOR_REGISTRATIONS_IN_A_BLOCK) {
    // ...
  }
  canDepositMore = bestSPidx != cache.length && _amount >= DEPOSIT_SIZE;
}

The depositBufferedEther() can be called by anyone. The MAX_VALIDATOR_REGISTRATIONS_IN_A_BLOCK constant may be made configurable via the DAO voting.

oracle (smart contract)

based on https://github.com/depools/depool-dao/blob/master/apps/depooloracle/contracts/DePoolOracle.sol but

1. oracles should report uniform data: it's eth2 blockchain, when finalized there should be no two different views on network and all honest oracles should report the exact same result
   thus https://github.com/depools/depool-dao/blob/master/apps/depooloracle/contracts/DePoolOracle.sol#L225
   should count quorum on exact results instead of mean result
2. Find a different name for Epoch (maybe interval) bc people are confusing it with eth2 Epoch
3. allow reporting epochs from the past (not current epochs) as long as epoch is > than the last reported one and <= current one (nb can be exploited in edge cases for a short time)

oracle (daemon)

oracle should report balance for every 7200*x slot (0, 7200, 14400, ...) when it's finalized but not earlier. In pushData(uint256 _epoch, ...) _epoch (that needs to be renamed to _data_timestamp or something) should be the blocktime of the slot. Edge cases are when there's no block for the slot - in that case, balance and blocktime should be for the last finalized block before 7200*x, usually 7200*x-1.

Balance reported = sum of all balances on active validators under depool control (up to date list of keys is in the smart contract), + sum of all balances on validators under depool control in the activation queue + sum of all balances under depool control in the exit queue + sum of all balances on inactive (exited) validators under depool control