celo-org · nategraf · Dec 4, 2019 · Dec 4, 2019 · Dec 4, 2019 · Dec 4, 2019
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -4,27 +4,27 @@ 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.
 
 The `Attestations` contract records all attestations of a phone number to any number of addresses. That for example could happen when a user loses their private key and wants to map a new wallet address. However, it could also happen through the collusion of a validator with Alice. Therefore, it is important that clients of the identity protocol highlight possible conflicting attestations. Attestations can theoretically be attacked, whether by a service provider or collusion with a validator. In general, the more attestations an address has received, the more likely it is to map to the valid owner of a phone number based upon the existing trust assumptions for validators for consensus.
 
 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
@@ -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
@@ -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).
 
 ## <a name="bolster-reserve"></a>Bolstering the Reserve