diff --git a/packages/cli/src/commands/account/claim-account.ts b/packages/cli/src/commands/account/claim-account.ts index dd64ed030a7..a7058f7d09b 100644 --- a/packages/cli/src/commands/account/claim-account.ts +++ b/packages/cli/src/commands/account/claim-account.ts @@ -3,7 +3,8 @@ import { flags } from '@oclif/command' import { ClaimCommand } from '../../utils/identity' export default class ClaimAccount extends ClaimCommand { - static description = 'Claim another account in a local metadata file' + static description = + 'Claim another account, and optionally its public key, and add the claim to a local metadata file' static flags = { ...ClaimCommand.flags, address: flags.string({ @@ -12,11 +13,14 @@ export default class ClaimAccount extends ClaimCommand { }), publicKey: flags.string({ default: undefined, - description: 'The public key of the account if you want others to encrypt messages to you', + description: + 'The public key of the account that others may use to send you encrypted messages', }), } static args = ClaimCommand.args - static examples = ['claim-account ~/metadata.json --address test.com --from 0x0'] + static examples = [ + 'claim-account ~/metadata.json --address 0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95', + ] self = ClaimAccount async run() { const res = this.parse(ClaimAccount) diff --git a/packages/cli/src/commands/account/claim-attestation-service-url.ts b/packages/cli/src/commands/account/claim-attestation-service-url.ts index 43bd3d8aa8f..56958ec0027 100644 --- a/packages/cli/src/commands/account/claim-attestation-service-url.ts +++ b/packages/cli/src/commands/account/claim-attestation-service-url.ts @@ -2,7 +2,8 @@ import { createAttestationServiceURLClaim } from '@celo/contractkit/lib/identity import { Flags } from '../../utils/command' import { ClaimCommand } from '../../utils/identity' export default class ClaimAttestationServiceUrl extends ClaimCommand { - static description = 'Claim the URL of the attestation service in a local metadata file' + static description = + 'Claim the URL of the attestation service and add the claim to a local metadata file' static flags = { ...ClaimCommand.flags, url: Flags.url({ @@ -12,7 +13,7 @@ export default class ClaimAttestationServiceUrl extends ClaimCommand { } static args = ClaimCommand.args static examples = [ - 'claim-attestation-service-url ~/metadata.json --url http://test.com/myurl --from 0x0', + 'claim-attestation-service-url ~/metadata.json --url http://test.com/myurl --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95', ] self = ClaimAttestationServiceUrl diff --git a/packages/cli/src/commands/account/claim-domain.ts b/packages/cli/src/commands/account/claim-domain.ts index 4ad6b4c963d..cf997f79062 100644 --- a/packages/cli/src/commands/account/claim-domain.ts +++ b/packages/cli/src/commands/account/claim-domain.ts @@ -3,7 +3,7 @@ import { flags } from '@oclif/command' import { ClaimCommand } from '../../utils/identity' export default class ClaimDomain extends ClaimCommand { - static description = 'Change the domain in a local metadata file' + static description = 'Claim a domain and add the claim to a local metadata file' static flags = { ...ClaimCommand.flags, domain: flags.string({ @@ -12,7 +12,9 @@ export default class ClaimDomain extends ClaimCommand { }), } static args = ClaimCommand.args - static examples = ['claim-domain ~/metadata.json --domain test.com --from 0x0'] + static examples = [ + 'claim-domain ~/metadata.json --domain test.com --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95', + ] self = ClaimDomain async run() { const res = this.parse(ClaimDomain) diff --git a/packages/cli/src/commands/account/claim-keybase.ts b/packages/cli/src/commands/account/claim-keybase.ts index 07787990526..b69aa1a8c58 100644 --- a/packages/cli/src/commands/account/claim-keybase.ts +++ b/packages/cli/src/commands/account/claim-keybase.ts @@ -18,7 +18,7 @@ import { commandExists, execCmdWithError, execWith0Exit } from '../../utils/exec import { ClaimCommand } from '../../utils/identity' export default class ClaimKeybase extends ClaimCommand { - static description = 'Claim a keybase username in a local metadata file' + static description = 'Claim a keybase username and add the claim to a local metadata file' static flags = { ...ClaimCommand.flags, username: flags.string({ @@ -27,7 +27,9 @@ export default class ClaimKeybase extends ClaimCommand { }), } static args = ClaimCommand.args - static examples = ['claim-keybase ~/metadata.json --from 0x0 --username test'] + static examples = [ + 'claim-keybase ~/metadata.json --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95 --username myusername', + ] self = ClaimKeybase async run() { diff --git a/packages/cli/src/commands/account/claim-name.ts b/packages/cli/src/commands/account/claim-name.ts index 6ce9819c873..79cdf8d69fe 100644 --- a/packages/cli/src/commands/account/claim-name.ts +++ b/packages/cli/src/commands/account/claim-name.ts @@ -3,7 +3,7 @@ import { flags } from '@oclif/command' import { ClaimCommand } from '../../utils/identity' export default class ClaimName extends ClaimCommand { - static description = 'Change the name in a local metadata file' + static description = 'Claim a name and add the claim to a local metadata file' static flags = { ...ClaimCommand.flags, name: flags.string({ @@ -12,7 +12,9 @@ export default class ClaimName extends ClaimCommand { }), } static args = ClaimCommand.args - static examples = ['change-name ~/metadata.json --from 0x0 --name myname'] + static examples = [ + 'claim-name ~/metadata.json --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95 --name myname', + ] self = ClaimName async run() { const res = this.parse(ClaimName) diff --git a/packages/cli/src/commands/account/create-metadata.ts b/packages/cli/src/commands/account/create-metadata.ts index 144221d8860..1c0b6030077 100644 --- a/packages/cli/src/commands/account/create-metadata.ts +++ b/packages/cli/src/commands/account/create-metadata.ts @@ -5,12 +5,15 @@ import { Args } from '../../utils/command' import { ClaimCommand } from '../../utils/identity' export default class CreateMetadata extends ClaimCommand { - static description = 'Create an empty metadata file' + static description = + 'Create an empty identity metadata file. Use this metadata file to store claims attesting to ownership of off-chain resources. Claims can be generated with the account:claim-* commands.' static flags = ClaimCommand.flags static args: IArg[] = [ Args.newFile('file', { description: 'Path where the metadata should be saved' }), ] - static examples = ['create-metadata ~/metadata.json --from 0x0'] + static examples = [ + 'create-metadata ~/metadata.json --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95', + ] async run() { const res = this.parse(CreateMetadata) diff --git a/packages/cli/src/commands/account/get-metadata.ts b/packages/cli/src/commands/account/get-metadata.ts index 490e10c26ba..a8999a817b1 100644 --- a/packages/cli/src/commands/account/get-metadata.ts +++ b/packages/cli/src/commands/account/get-metadata.ts @@ -5,7 +5,8 @@ import { Args } from '../../utils/command' import { displayMetadata } from '../../utils/identity' export default class GetMetadata extends BaseCommand { - static description = 'Show information about an address' + static description = + 'Show information about an address. Retreives the metadata URL for an account from the on-chain, then fetches the metadata file off-chain and verifies proofs as able.' static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/account/register-metadata.ts b/packages/cli/src/commands/account/register-metadata.ts index 4d1af64f9cd..0695fdb5d3a 100644 --- a/packages/cli/src/commands/account/register-metadata.ts +++ b/packages/cli/src/commands/account/register-metadata.ts @@ -4,7 +4,8 @@ import { displaySendTx } from '../../utils/cli' import { Flags } from '../../utils/command' export default class RegisterMetadata extends BaseCommand { - static description = 'Register metadata about an address' + static description = + 'Register metadata URL for an account where users will be able to retieve the metadata file and verify your claims' static flags = { ...BaseCommand.flags, @@ -18,7 +19,9 @@ export default class RegisterMetadata extends BaseCommand { }), } - static examples = ['register-metadata --url https://www.celo.org --from 0x0'] + static examples = [ + 'register-metadata --url https://www.mywebsite.com/celo-metadata --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95', + ] async run() { const { flags } = this.parse(RegisterMetadata) diff --git a/packages/docs/README.md b/packages/docs/README.md index 2de41de9d3a..c66f6e015cf 100644 --- a/packages/docs/README.md +++ b/packages/docs/README.md @@ -98,7 +98,7 @@ Browse the code, raise an issue, or contribute a PR: Try Celo out: - [Using the Mobile Wallet](getting-started/using-the-mobile-wallet.md) on the Alfajores Testnet -- [Using the CLI ](getting-started/using-the-cli.md)on the Alfajores Testnet +- [Introduction to the CLI ](command-line-interface/introduction.md)on the Alfajores Testnet Read the Whitepapers: diff --git a/packages/docs/SUMMARY.md b/packages/docs/SUMMARY.md index f5a79754f86..78a53e524fa 100644 --- a/packages/docs/SUMMARY.md +++ b/packages/docs/SUMMARY.md @@ -11,6 +11,7 @@ - [Baklava Testnet](getting-started/baklava-testnet.md) - [Running a Full Node](getting-started/running-a-full-node.md) - [Running a Validator](getting-started/running-a-validator.md) + - [Running an Attestation Service](getting-started/running-attestation-service.md) - [Glossary](getting-started/glossary.md) ## Celo Codebase diff --git a/packages/docs/celo-codebase/protocol/identity/README.md b/packages/docs/celo-codebase/protocol/identity/README.md index d7a829dbf9b..5505a388f95 100644 --- a/packages/docs/celo-codebase/protocol/identity/README.md +++ b/packages/docs/celo-codebase/protocol/identity/README.md @@ -4,15 +4,15 @@ Celo’s unique purpose is to make financial tools accessible to anyone with a m ![](https://storage.googleapis.com/celo-website/docs/attestations-flow.jpg) -### **Adding their phone number to the mapping** +### Adding their phone number to the mapping -To allow Bob to find an address mapped to her phone number, Alice can request attestations to their phone number \(technically the hash of their phone number\) from the `Attestations` contract by transferring the attestation request fee to it. The fee per attestation request is set on the contract with [Governance](../governance.html). After a brief waiting time of currently `4` blocks, the `Attestations` contract will use the `Random` contract to do a random selection over the current validator set in the `Validators` contract who will become responsible for these attestation requests. +To allow Bob to find an address mapped to her phone number, Alice can request attestations to their phone number \(technically the hash of their phone number\) from the `Attestations` contract by transferring the attestation request fee to it. The fee per attestation request is set on the contract with [Governance](../governance.md). After a brief waiting time of currently `4` blocks, the `Attestations` contract will use the `Random` contract to do a random selection over the current validator set in the `Validators` contract who will become responsible for these attestation requests. -As part of the expectation to validators, they run the attestation service whose endpoint they register in their [Metadata](./metadata.html). Alice can identify the validators responsible for her attestation from the smart contract, determine the validators' attestation service URLs from their [Metadata](./metadata.html) and request attestations from them. In turn, the attestation service produces a signed secret message that acts as an attestation by that validator that Alice owns the phone number. The validator sends that message via SMS. Read more under [attestation service](#attestation-service). +As part of the expectation to validators, they run the attestation service whose endpoint they register in their [Metadata](./metadata.md). Alice can identify the validators responsible for her attestation from the smart contract, determine the validators' attestation service URLs from their [Metadata](./metadata.md) and request attestations from them. In turn, the attestation service produces a signed secret message that acts as an attestation by that validator that Alice owns the phone number. The validator sends that message via SMS. Read more under [attestation service](#attestation-service). When Alice receives the text message, she can take that signed message to the `Attestations` contract, which can verify that the attestation came from the validator indeed. Upon a successful attestation, the validator can redeem for the attestation request fee to pay them for the cost of sending the SMS. In the end, we have recorded an attestation by the validator to a mapping of Alice’s phone number to her account address. -### **Using the mapping for payment** +### Using the mapping for payment Once Alice has completed attestations for their phone number/address, Bob, who has her phone number in his contact book, can see that Alice has an attested account address with her phone number. He can use that address to send funds to Alice, without her having to specifically communicate her address to Bob. @@ -20,11 +20,11 @@ The `Attestations` contract records all attestations of a phone number to any nu There are additional measures we can take to further secure the integrity of the mapping’s usage. In the future we plan to provide reference implementations in the wallet for some of these. For example, we plan to detect remapping of wallet addresses. Many users are already accustomed to sending small amounts first and verifying the receipt of those funds before attempting to transfer larger amounts. -### **Privacy mode** +### Privacy mode One downside to this identity protocol is that knowledge of a phone number can let anyone quickly determine the balance of the associated wallet, which of course may be unacceptable for many use cases. For these circumstances, the contract allows users to use the `Attestations` contract in privacy mode. In this mode, the user does not map their phone number to their wallet address, but to an account that is not meant to be the recipient of transfers. Through a registered encryption key on the user’s account on the contract, schemes can be derived to allow users to selectively reveal their true wallet addresses to authorized participants. Implementing such a scheme is future work. -### **Attestation service** +### Attestation service The attestation service is a simple Node.js service that validators run to send signed messages for attestations. It can be configured with SMS providers, as different providers have different characteristics like reliability, trustworthiness and performance in different regions. The attestation service currently supports [Twilio](https://www.twilio.com) and [Nexmo](https://nexmo.com). We hope to widen the number of supported providers, especially for service in relevant regions. diff --git a/packages/docs/celo-codebase/protocol/proof-of-stake/README.md b/packages/docs/celo-codebase/protocol/proof-of-stake/README.md index 4b6590cbed1..fea399fb478 100644 --- a/packages/docs/celo-codebase/protocol/proof-of-stake/README.md +++ b/packages/docs/celo-codebase/protocol/proof-of-stake/README.md @@ -8,26 +8,26 @@ The first set of active validators are determined in the genesis block. Thereaft ![](https://storage.googleapis.com/celo-website/docs/concepts.jpg) -In Celo's [Validator Elections](validator-elections.md), holders of the native asset, Celo Gold, may participate and earn rewards for doing so. Accounts do not make votes for validators directly, but instead vote for [validator groups](validator-groups.md). +In Celo's [Validator Elections](validator-elections.md), holders of the native asset, Celo Gold, may participate and earn rewards for doing so. Accounts do not make votes for validators directly, but instead vote for [validator groups](validator-groups.md). -Before they can vote, holders of Celo Gold move balances into the [Locked Gold](locked-gold.md) smart contract. Locked Gold can be used concurrently for: placing votes in Validator Elections, maintaining a stake to satisfy the requirements of registering as a validator or validator group, and also voting in on-chain [Governance](../governance.md) proposals. This means that validators and groups can vote and earn rewards with their stake. +Before they can vote, holders of Celo Gold move balances into the [Locked Gold](locked-gold.md) smart contract. Locked Gold can be used concurrently for: placing votes in Validator Elections, maintaining a stake to satisfy the requirements of registering as a validator or validator group, and also voting in on-chain [Governance](../governance.md) proposals. This means that validators and groups can vote and earn rewards with their stake. -Unlike in other Proof of Stake systems, holding Locked Gold or voting for a group does not put that amount 'at risk' from slashing due to the behavior of validators or validator groups. Only the stake put up by a validator or group may be slashed. +Unlike in other Proof of Stake systems, holding Locked Gold or voting for a group does not put that amount 'at risk' from slashing due to the behavior of validators or validator groups. Only the stake put up by a validator or group may be slashed. ## Implementation Most of Celo's Proof of Stake mechanism is implemented as smart contracts, and as such can be changed through Celo's on-chain [Governance](../governance.md) process. -* [`Accounts.sol`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/Accounts.sol) manages key delegation and metadata for all accounts including Validators, Groups and Locked Gold holders. +- [`Accounts.sol`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/Accounts.sol) manages key delegation and metadata for all accounts including Validators, Groups and Locked Gold holders. -* [`LockedGold.sol`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/LockedGold.sol) manages the lifecycle of Locked Gold. +- [`LockedGold.sol`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/LockedGold.sol) manages the lifecycle of Locked Gold. -* [`Validators.sol`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/Validators.sol) handles registration, deregistration, staking, key management and epoch rewards for validators and validator groups, as well as routines to manage the members of groups. +- [`Validators.sol`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/Validators.sol) handles registration, deregistration, staking, key management and epoch rewards for validators and validator groups, as well as routines to manage the members of groups. -* [`Elections.sol`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/Elections.sol) manages Locked Gold voting and epoch rewards and runs Validator Elections. +- [`Elections.sol`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/governance/Elections.sol) manages Locked Gold voting and epoch rewards and runs Validator Elections. In Celo blockchain: -* [`consensus/istanbul/backend/backend.go`](https://github.com/celo-org/celo-blockchain/blob/master/consensus/istanbul/backend/backend.go) performs validator elections in the last block of the epoch and calculates the new [validator set diff](../consensus/validator-set-differences.md). +- [`consensus/istanbul/backend/backend.go`](https://github.com/celo-org/celo-blockchain/blob/master/consensus/istanbul/backend/backend.go) performs validator elections in the last block of the epoch and calculates the new [validator set diff](../consensus/validator-set-differences.md). -* [`consensus/istanbul/backend/pos.go`](https://github.com/celo-org/celo-blockchain/blob/master/consensus/istanbul/backend/pos.go) is called in the last block of the epoch to process validator uptime scores and make epoch rewards. +- [`consensus/istanbul/backend/pos.go`](https://github.com/celo-org/celo-blockchain/blob/master/consensus/istanbul/backend/pos.go) is called in the last block of the epoch to process validator uptime scores and make epoch rewards. diff --git a/packages/docs/celo-codebase/protocol/proof-of-stake/community-fund.md b/packages/docs/celo-codebase/protocol/proof-of-stake/community-fund.md index ec253201b96..45b726c7a84 100644 --- a/packages/docs/celo-codebase/protocol/proof-of-stake/community-fund.md +++ b/packages/docs/celo-codebase/protocol/proof-of-stake/community-fund.md @@ -4,11 +4,11 @@ The Community Fund provides for general upkeep of the Celo platform. Celo Gold h The Community Fund receives assets from three sources: -* The Community Fund obtains a desired epoch payment defined as a fraction of the total desired epoch rewards \(governable, initially planned to be $$25\%$$\). This amount is subject to adjustment up or down in the event of under- or over-spending against the epoch rewards target schedule. It may also be reduced to [bolster the Reserve](#bolster-reserve). +- The Community Fund obtains a desired epoch payment defined as a fraction of the total desired epoch rewards \(governable, initially planned to be $$25\%$$\). This amount is subject to adjustment up or down in the event of under- or over-spending against the epoch rewards target schedule. It may also be reduced to [bolster the Reserve](#bolster-reserve). -* The Community Fund is the default destination for slashed assets. +- The Community Fund is the default destination for slashed assets. -* The Community Fund also receives the 'base' portion of [transaction fees](transactions/gas-pricing.md). +- The Community Fund also receives the 'base' portion of [transaction fees](../transactions/gas-pricing.md). ## Bolstering the Reserve diff --git a/packages/docs/celo-codebase/protocol/proof-of-stake/epoch-rewards.md b/packages/docs/celo-codebase/protocol/proof-of-stake/epoch-rewards.md index 55c75532662..55541f8b102 100644 --- a/packages/docs/celo-codebase/protocol/proof-of-stake/epoch-rewards.md +++ b/packages/docs/celo-codebase/protocol/proof-of-stake/epoch-rewards.md @@ -6,7 +6,7 @@ * Distributed [rewards for validators and validator groups](validator-rewards.md) * Distribute [rewards to holders of Locked Celo Gold](locked-gold-rewards.md) voting for groups that elected validators * Make payments into a [Community Fund](community-fund.md) for protocol infrastructure grants -* [Bolster the stablecoin reserve](community-fund#bolster-reserve) if it is under-collateralized +* [Bolster the stablecoin reserve](community-fund.md#bolster-reserve) if it is under-collateralized * Make payments into a [Carbon Offsetting Fund](carbon-offsetting-fund.md). A total of 400 million Celo Gold will be released for epoch rewards over time. Celo Gold is one of Celo’s reserve currencies and can be used as utility token in Celo. It has a fixed total supply and in the long term will exhibit deflationary characteristics like Bitcoin. diff --git a/packages/docs/celo-codebase/protocol/proof-of-stake/locked-gold.md b/packages/docs/celo-codebase/protocol/proof-of-stake/locked-gold.md index db936284e7c..434aaa9bd2f 100644 --- a/packages/docs/celo-codebase/protocol/proof-of-stake/locked-gold.md +++ b/packages/docs/celo-codebase/protocol/proof-of-stake/locked-gold.md @@ -8,7 +8,7 @@ Locking up Celo Gold guarantees that the same asset is not used more than once i ## Unlocking Period -Celo implements an **unlocking period**, a delay of 3 days after making a request to unlock Locked Gold before it can be recovered from the escrow. +Celo implements an **unlocking period**, a delay of 3 days after making a request to unlock Locked Gold before it can be recovered from the escrow. This value balances two concerns. First, it is long enough that an election will have taken place since the request to unlock, so that those units of Celo Gold will no longer have any impact on which validators are managing the network. This deters an attacker from manipulations in the form of borrowing funds to purchase Celo Gold, then using it to elect malicious validators, since they will not be able to return the borrowed funds until after the attack, when presumably it would have been detected and the borrowed funds’ value have fallen. @@ -19,20 +19,21 @@ Second, the unlocking period is short enough that it does not represent a signif ![](https://storage.googleapis.com/celo-website/docs/locked-gold-flow.jpg) The flow is as follows: -* An account calls `lock`, transferring an amount of Celo Gold from their balance to the `LockedGold` smart contract. This increments the account's 'non-voting' balance by the same amount. -* Then the account calls `vote`, passing in an amount and the address of the group to vote for. This decrements the account's 'non-voting' balance and increments the 'pending' balance associated with that group by the same amount. This counts immediately towards electing validators. Note that the vote may be rejected if it would mean that the account would be voting for more than 3 distinct groups, or that the [voting cap](validator-elections.md#voting-cap) for the group would be exceeded. +- An account calls `lock`, transferring an amount of Celo Gold from their balance to the `LockedGold` smart contract. This increments the account's 'non-voting' balance by the same amount. -* At the end of the current epoch, the protocol will first deliver [epoch rewards](epoch-rewards.md) to validators, groups and voters based on the current epoch (pending votes do not count for these purposes), and then run an [election](validator-election.md) to select the active validator set for the following epoch. +- Then the account calls `vote`, passing in an amount and the address of the group to vote for. This decrements the account's 'non-voting' balance and increments the 'pending' balance associated with that group by the same amount. This counts immediately towards electing validators. Note that the vote may be rejected if it would mean that the account would be voting for more than 3 distinct groups, or that the [voting cap](validator-elections.md#voting-cap) for the group would be exceeded. -* The pending vote continues to contribute towards electing validators until it is changed, but the account must call `activate` (in a subsequent epoch to the one in which the vote was made) to convert the pending vote to one that earns rewards. +- At the end of the current epoch, the protocol will first deliver [epoch rewards](epoch-rewards.md) to validators, groups and voters based on the current epoch (pending votes do not count for these purposes), and then run an [election](validator-elections.md) to select the active validator set for the following epoch. -* At the end of that epoch, if the group for which the vote was made had elected one or more validators in the prior election, then the activated vote is eligible for [Locked Gold rewards](locked-gold-rewards.md). These are applied to the pool of activated votes for the group. This means that activated voting Locked Gold receives automatically compounds, with the rewards increasing the account's votes for the same group, thereby increasing future rewards, benefitting participants who have elected to continuously participate in governance. +- The pending vote continues to contribute towards electing validators until it is changed, but the account must call `activate` (in a subsequent epoch to the one in which the vote was made) to convert the pending vote to one that earns rewards. -* The account may subsequently choose to `unvote` a specific amount of voting Locked Gold from a group, up to the total balance that the account has accrued there. Due to rewards, this Locked Gold amount may be higher than the original value passed to `vote`. +- At the end of that epoch, if the group for which the vote was made had elected one or more validators in the prior election, then the activated vote is eligible for [Locked Gold rewards](locked-gold-rewards.md). These are applied to the pool of activated votes for the group. This means that activated voting Locked Gold receives automatically compounds, with the rewards increasing the account's votes for the same group, thereby increasing future rewards, benefitting participants who have elected to continuously participate in governance. -* This Locked Gold immediately becomes non-voting, receives no further Epoch Rewards, and can be re-used to vote for a different group. +- The account may subsequently choose to `unvote` a specific amount of voting Locked Gold from a group, up to the total balance that the account has accrued there. Due to rewards, this Locked Gold amount may be higher than the original value passed to `vote`. -* The account may choose to `unlock` an amount of Locked Gold at any time, provided that it is inactive: this means it is non-voting in Validator Elections, the `deregistrationPeriod` has elasped if the amount has been used as a validator or validator group stake, and not active in any [Governance proposals](../governance.md). Once an unlocking period of 3 days has passed, the account can call `withdraw` to have the `LockedGold` contract transfer them that amount. +- This Locked Gold immediately becomes non-voting, receives no further Epoch Rewards, and can be re-used to vote for a different group. + +- The account may choose to `unlock` an amount of Locked Gold at any time, provided that it is inactive: this means it is non-voting in Validator Elections, the `deregistrationPeriod` has elasped if the amount has been used as a validator or validator group stake, and not active in any [Governance proposals](../governance.md). Once an unlocking period of 3 days has passed, the account can call `withdraw` to have the `LockedGold` contract transfer them that amount. Votes persist between epochs, and the same vote is applied to each election unless and until it is changed. Vote withdrawal, vote changes, and additional gold being used to vote have no effect on the validator set until the election finalizes at the end of the epoch. diff --git a/packages/docs/command-line-interface/account.md b/packages/docs/command-line-interface/account.md index 09eaedcaf0c..12e925d6c91 100644 --- a/packages/docs/command-line-interface/account.md +++ b/packages/docs/command-line-interface/account.md @@ -46,7 +46,7 @@ _See code: [packages/cli/src/commands/account/balance.ts](https://github.com/cel ### Claim-account -Claim another account in a local metadata file +Claim another account, and optionally its public key, and add the claim to a local metadata file ``` USAGE @@ -59,18 +59,19 @@ OPTIONS --address=address (required) The address of the account you want to claim --from=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Addess of the account to set metadata for - --publicKey=publicKey The public key of the account if you want others to encrypt - messages to you + --publicKey=publicKey The public key of the account that others may use to send you + encrypted messages EXAMPLE - claim-account ~/metadata.json --address test.com --from 0x0 + claim-account ~/metadata.json --address 0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d --from + 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95 ``` _See code: [packages/cli/src/commands/account/claim-account.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/account/claim-account.ts)_ ### Claim-attestation-service-url -Claim the URL of the attestation service in a local metadata file +Claim the URL of the attestation service and add the claim to a local metadata file ``` USAGE @@ -84,14 +85,15 @@ OPTIONS --url=htttps://www.celo.org (required) The url you want to claim EXAMPLE - claim-attestation-service-url ~/metadata.json --url http://test.com/myurl --from 0x0 + claim-attestation-service-url ~/metadata.json --url http://test.com/myurl --from + 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95 ``` _See code: [packages/cli/src/commands/account/claim-attestation-service-url.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/account/claim-attestation-service-url.ts)_ ### Claim-domain -Change the domain in a local metadata file +Claim a domain and add the claim to a local metadata file ``` USAGE @@ -105,14 +107,14 @@ OPTIONS --from=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Addess of the account to set metadata for EXAMPLE - claim-domain ~/metadata.json --domain test.com --from 0x0 + claim-domain ~/metadata.json --domain test.com --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95 ``` _See code: [packages/cli/src/commands/account/claim-domain.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/account/claim-domain.ts)_ ### Claim-keybase -Claim a keybase username in a local metadata file +Claim a keybase username and add the claim to a local metadata file ``` USAGE @@ -126,14 +128,14 @@ OPTIONS --username=username (required) The keybase username you want to claim EXAMPLE - claim-keybase ~/metadata.json --from 0x0 --username test + claim-keybase ~/metadata.json --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95 --username myusername ``` _See code: [packages/cli/src/commands/account/claim-keybase.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/account/claim-keybase.ts)_ ### Claim-name -Change the name in a local metadata file +Claim a name and add the claim to a local metadata file ``` USAGE @@ -147,14 +149,14 @@ OPTIONS --name=name (required) The name you want to claim EXAMPLE - change-name ~/metadata.json --from 0x0 --name myname + claim-name ~/metadata.json --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95 --name myname ``` _See code: [packages/cli/src/commands/account/claim-name.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/account/claim-name.ts)_ ### Create-metadata -Create an empty metadata file +Create an empty identity metadata file. Use this metadata file to store claims attesting to ownership of off-chain resources. Claims can be generated with the account:claim-\* commands. ``` USAGE @@ -167,14 +169,14 @@ OPTIONS --from=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Addess of the account to set metadata for EXAMPLE - create-metadata ~/metadata.json --from 0x0 + create-metadata ~/metadata.json --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95 ``` _See code: [packages/cli/src/commands/account/create-metadata.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/account/create-metadata.ts)_ ### Get-metadata -Show information about an address +Show information about an address. Retreives the metadata URL for an account from the on-chain, then fetches the metadata file off-chain and verifies proofs as able. ``` USAGE @@ -259,7 +261,7 @@ _See code: [packages/cli/src/commands/account/register.ts](https://github.com/ce ### Register-metadata -Register metadata about an address +Register metadata URL for an account where users will be able to retieve the metadata file and verify your claims ``` USAGE @@ -270,7 +272,7 @@ OPTIONS --url=htttps://www.celo.org (required) The url to the metadata you want to register EXAMPLE - register-metadata --url https://www.celo.org --from 0x0 + register-metadata --url https://www.mywebsite.com/celo-metadata --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95 ``` _See code: [packages/cli/src/commands/account/register-metadata.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/account/register-metadata.ts)_ diff --git a/packages/docs/command-line-interface/introduction.md b/packages/docs/command-line-interface/introduction.md index c544e6eb321..954fe86b734 100644 --- a/packages/docs/command-line-interface/introduction.md +++ b/packages/docs/command-line-interface/introduction.md @@ -10,7 +10,7 @@ description: >- ### **Prerequisites** -- **You have a Celo node running.** Commands will connect to a Celo node to execute most functionality. See the [Running a Full Node](running-a-full-node.md) instructions for more details on running a full node. +- **You have a Celo node running.** Commands will connect to a Celo node to execute most functionality. See the [Running a Full Node](../getting-started/running-a-full-node.md) instructions for more details on running a full node. ### NPM Package diff --git a/packages/docs/getting-started/alfajores-testnet.md b/packages/docs/getting-started/alfajores-testnet.md index aa82eddfb79..6de3fc9964e 100644 --- a/packages/docs/getting-started/alfajores-testnet.md +++ b/packages/docs/getting-started/alfajores-testnet.md @@ -1,6 +1,6 @@ # Alfajores Testnet -The **Alfajores Testnet** is the first Celo test network. It is a demonstration of the current Celo codebase. You can use it to try out the [Celo Wallet](https://celo.org/build/wallet) or the [Celo CLI](using-the-cli.md) \(by sending transfers to yourself or other users of the testnet\). You can also assist in running the network by operating a [full node](running-a-full-node.md) or a [validator](running-a-validator.md) on your machine \(or on a cloud or hosting provider\). +The **Alfajores Testnet** is the first Celo test network. It is a demonstration of the current Celo codebase. You can use it to try out the [Celo Wallet](https://celo.org/build/wallet) or the [Celo CLI](../command-line-interface/introduction.md) \(by sending transfers to yourself or other users of the testnet\). You can also assist in running the network by operating a [full node](running-a-full-node.md) or a [validator](running-a-validator.md) on your machine \(or on a cloud or hosting provider\). The [Baklava Testnet](baklava-testnet.md) is focused on building operational experience and best practices for node operators. diff --git a/packages/docs/getting-started/running-attestation-service.md b/packages/docs/getting-started/running-attestation-service.md index d26e1ddb7a9..4c9ce258913 100644 --- a/packages/docs/getting-started/running-attestation-service.md +++ b/packages/docs/getting-started/running-attestation-service.md @@ -1,28 +1,19 @@ # Running the Attestation Service -- [Running the Attestation Service](#running-the-attestation-service) - - [Environment variables](#environment-variables) - - [Sms Providers](#sms-providers) - - [Nexmo](#nexmo) - - [Twilio](#twilio) - - [Accounts Configuration](#accounts-configuration) \* [Database Configuration](#database-configuration) - - [Executing the Attestation Service](#executing-the-attestation-service) - - [Registering the Attestation Service](#registering-the-attestation-service) - As part of the [lightweight identity protocol](/celo-codebase/protocol/identity), validators are expected to run an Attestation Service to provide attestations that allow users to map their phone number to an account on Celo. The Attestation Service is a simple Node.js application that can be run with a Docker image. ## Environment variables The service needs the following environment variables: -| Variable | Explanation | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| DATABASE_URL | The URL under which your database is accessible, currently supported are `postgres://`, `mysql://` and `sqlite://` | | -| CELO_PROVIDER | The endpoint under which your node with the unlocked attestation signer key is available, should be `http://localhost:8545` if you followed the [instructions](./running-a-validator) | | -| CELO_VALIDATOR_ADDRESS | The address of the Validator account | | -| ATTESTATION_SIGNER_ADDRESS | The address of the attestation signer that was authorized by the Validator account | | -| APP_SIGNATURE | The hash with which clients can auto-read SMS messages on android | | -| SMS_PROVIDERS | A comma-separated list of providers you want to configure, we currently support `nexmo` & `twilio` | | +| Variable | Explanation | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| DATABASE_URL | The URL under which your database is accessible, currently supported are `postgres://`, `mysql://` and `sqlite://` | | +| CELO_PROVIDER | The endpoint under which your node with the unlocked attestation signer key is available, should be `http://localhost:8545` if you followed the [getting started guide](./running-a-validator.md) | | +| CELO_VALIDATOR_ADDRESS | The address of the Validator account | | +| ATTESTATION_SIGNER_ADDRESS | The address of the attestation signer that was authorized by the Validator account | | +| APP_SIGNATURE | The hash with which clients can auto-read SMS messages on android | | +| SMS_PROVIDERS | A comma-separated list of providers you want to configure, we currently support `nexmo` & `twilio` | | A part of that we are going to setup the following environment variable about the Attestation Service Docker image: diff --git a/packages/docs/getting-started/using-the-wallet.md b/packages/docs/getting-started/using-the-wallet.md index ec18113f497..3556a3e8c17 100644 --- a/packages/docs/getting-started/using-the-wallet.md +++ b/packages/docs/getting-started/using-the-wallet.md @@ -18,7 +18,7 @@ To download the app on the Play Store, go [here](https://play.google.com/store/a ### Running the Celo Wallet Locally -For more information on how to run the Celo Wallet locally, please refer to the [mobile wallet setup instructions](../celo-codebase/wallet/intro.md) +For more information on how to run the Celo Wallet locally, please refer to the [mobile wallet setup instructions](../../celo-codebase/wallet/intro.md) ### Get More Funds!