Add custody docs #2880
Add custody docs #2880
Conversation
Codecov Report
@@ Coverage Diff @@
## master #2880 +/- ##
========================================
Coverage 73.58% 73.58%
========================================
Files 567 567
Lines 14160 14160
Branches 1765 1464 -301
========================================
Hits 10420 10420
Misses 3455 3455
Partials 285 285
Continue to review full report at Codecov.
|
| @@ -0,0 +1,34 @@ | |||
| # Custody | |||
|
|
|||
| Custody in this section refers to the holding of Celo assets such as Celo Dollar and Celo Gold on behalf of a user. This page lines out information to help you integrate these into your services. | |||
There was a problem hiding this comment.
nit: "Dollars" reads better to me (here and everywhere) but don't feel strongly
|
|
||
| ## Balance model | ||
|
|
||
| As a fork of Ethereum, Celo retains the account model to keep track of users' balances. Celo Dollar and Celo Gold are [ERC20](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md) contracts. Thus it is easy and common for smart contracts to have balances on the token contracts in another account's association. An example is the [`LockedGold`](celo-codebase/protocol/proof-of-stake/locked-gold) smart contract that holds the "locked portion of a user's `cGLD` balance". Another one is the [`ReleasingGold`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/ReleaseGoldInstance.sol) smart contract that holds `cGLD` that is being released over time to some schedule. |
There was a problem hiding this comment.
nit: that is being released to a beneficiary address over time according to some schedule.
|
|
||
| ## Balance model | ||
|
|
||
| As a fork of Ethereum, Celo retains the account model to keep track of users' balances. Celo Dollar and Celo Gold are [ERC20](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md) contracts. Thus it is easy and common for smart contracts to have balances on the token contracts in another account's association. An example is the [`LockedGold`](celo-codebase/protocol/proof-of-stake/locked-gold) smart contract that holds the "locked portion of a user's `cGLD` balance". Another one is the [`ReleasingGold`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/ReleaseGoldInstance.sol) smart contract that holds `cGLD` that is being released over time to some schedule. |
There was a problem hiding this comment.
It is common for smart contracts to hold balances on behalf of other addresses. One example is the LockedGold...
|
|
||
| As a fork of Ethereum, Celo retains the account model to keep track of users' balances. Celo Dollar and Celo Gold are [ERC20](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-20.md) contracts. Thus it is easy and common for smart contracts to have balances on the token contracts in another account's association. An example is the [`LockedGold`](celo-codebase/protocol/proof-of-stake/locked-gold) smart contract that holds the "locked portion of a user's `cGLD` balance". Another one is the [`ReleasingGold`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/ReleaseGoldInstance.sol) smart contract that holds `cGLD` that is being released over time to some schedule. | ||
|
|
||
| It is up you to decide how you would like to represent a user's "balance" in your service. |
There was a problem hiding this comment.
Applications that display balances may need to be written to be aware of this possibility.
|
|
||
| ## Transfers | ||
|
|
||
| Since all Celo assets are implementing an ERC-20 like interface, transfers can be done simply with the `transfer` function. Celo Gold is special as the native currency of the network, and can thus be transfered (in addition to the ERC20 interface) by specifying the `value` field of the transaction, similarly to `ETH` in Ethereum. Transfers to smart contracts can often be accomplished via the `approve/transferFrom` method, or via `value` in the case of contracts such as `LockedGold`. |
There was a problem hiding this comment.
Celo Gold and Celo Dollars implement the ERC20 interface, as will any future core stable Celo currencies. Celo Gold, as the native currency of the network, can also be transferred by specifying the value field of a transaction, in the same way that ETH can be transferred in Ethereum.
Consider cutting everything after this ^, as folks familiar with ethereum won't need that additional information.
|
|
||
| ## LockedGold | ||
|
|
||
| The `LockedGold` contract is part of Celo's [Proof of Stake system] to allow users to vote in validator elections, receive rewards for doing so and participate in on-chain governance. `Celo Gold` can be transferred to the `LockedGold` contract and be voted with (after [creating an account](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/Accounts.sol#L89) on the `Accounts` smart contract). There are two ways through which you can support your users' voting in the validator elections: |
There was a problem hiding this comment.
The LockedGold contract is part of Celo's [Proof of Stake system]. Users can lock Celo Gold by creating an account in the Accounts smart contract and sending it to LockedGold. This allows users to vote in validator elections, receive epoch rewards, and participate in on-chain governance.
There are two ways in which users can vote:
- Directly, by sending voting transactions with the same key used to lock up Celo Gold
- Via an authorized validator signer, which can submit voting transactions on behalf of the account with locked Celo Gold
|
|
||
| ## ReleasingGold | ||
|
|
||
| A common problem in more recent PoS projects is the fact that early token holders have their balances release over time to ensure long-term alignment, yet wanting to have those balances participate in the PoS system to increase the security of the network. For that purpose, many early token balances are released via the `ReleasingGold` contract. Beneficiaries of these contracts can participate in the PoS system by locking/unlocking already-released/to-be-released Celo Gold and authoring voting/validating keys to act on behalf of the beneficiary. |
|
|
||
| A common problem in more recent PoS projects is the fact that early token holders have their balances release over time to ensure long-term alignment, yet wanting to have those balances participate in the PoS system to increase the security of the network. For that purpose, many early token balances are released via the `ReleasingGold` contract. Beneficiaries of these contracts can participate in the PoS system by locking/unlocking already-released/to-be-released Celo Gold and authoring voting/validating keys to act on behalf of the beneficiary. | ||
|
|
||
| Custodians of benefiaries will want to support this functionality to increase the security of the network. |
There was a problem hiding this comment.
Many users are likely to prefer custodians that support this functionality so that they can maximize their epoch rewards and participate in governance of the network.
Description
This PR adds documentation to help custodians integrate Celo assets onto their system