Validator UX docs for baklava network (#1688) (#1849)

packages/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@celo/celocli",
   "description": "CLI Tool for transacting with the Celo protocol",
-  "version": "0.0.29",
+  "version": "0.0.30-beta",
   "author": "Celo",
   "license": "Apache-2.0",
   "repository": "celo-org/celo-monorepo",
@@ -79,28 +79,31 @@
     "commands": "./lib/commands",
     "topics": {
       "account": {
-        "description": "Manage your account, send and receive Celo Gold and Celo Dollars"
+        "description": "Manage your account, keys, and metadata"
       },
       "config": {
         "description": "Configure CLI options which persist across commands"
       },
       "election": {
-        "description": "View and manage validator elections"
+        "description": "Participate in and view the state of Validator Elections"
       },
       "exchange": {
-        "description": "Commands for interacting with the Exchange"
+        "description": "Exchange Celo Dollars and Celo Gold via the stability mechanism"
       },
       "lockedgold": {
         "description": "View and manage locked Celo Gold"
       },
       "node": {
         "description": "Manage your full node"
       },
+      "transfer": {
+        "description": "Transfer Celo Gold and Celo Dollars"
+      },
       "validator": {
-        "description": "View and manage validators"
+        "description": "View and manage Validators"
       },
       "validatorgroup": {
-        "description": "View and manage validator groups"
+        "description": "View and manage Validator Groups"
       }
     },
     "bin": "celocli",

packages/cli/src/commands/account/authorize.ts

@@ -5,7 +5,8 @@ import { displaySendTx } from '../../utils/cli'
 import { Flags } from '../../utils/command'
 
 export default class Authorize extends BaseCommand {
-  static description = 'Authorize an attestation, validator, or vote signer'
+  static description =
+    'Keep your locked Gold more secure by authorizing alternative keys to be used for signing attestations, voting, or validating. By doing so, you can continue to participate in the protocol why keeping the key with access to your locked Gold in cold storage. You must include a "proof-of-possession" of the key being authorized, which can be generated with the "account:proof-of-possession" command.'
 
   static flags = {
     ...BaseCommand.flags,

packages/cli/src/commands/account/balance.ts

@@ -3,13 +3,13 @@ import { printValueMap } from '../../utils/cli'
 import { Args } from '../../utils/command'
 
 export default class Balance extends BaseCommand {
-  static description = 'View Celo Dollar and Gold balances given account address'
+  static description = 'View Celo Dollar and Gold balances for an address'
 
   static flags = {
     ...BaseCommand.flags,
   }
 
-  static args = [Args.address('account')]
+  static args = [Args.address('address')]
 
   static examples = ['balance 0x5409ed021d9299bf6814279a6a1411a7e866a631']
 
@@ -19,8 +19,8 @@ export default class Balance extends BaseCommand {
     const goldToken = await this.kit.contracts.getGoldToken()
     const stableToken = await this.kit.contracts.getStableToken()
     const balances = {
-      goldBalance: await goldToken.balanceOf(args.account),
-      dollarBalance: await stableToken.balanceOf(args.account),
+      goldBalance: await goldToken.balanceOf(args.address),
+      dollarBalance: await stableToken.balanceOf(args.address),
     }
     printValueMap(balances)
   }

packages/cli/src/commands/account/proof-of-possession.ts

@@ -1,15 +1,26 @@
 import { serializeSignature } from '@celo/utils/lib/signatureUtils'
+import { flags } from '@oclif/command'
 import { BaseCommand } from '../../base'
 import { printValueMap } from '../../utils/cli'
 import { Flags } from '../../utils/command'
-
 export default class ProofOfPossession extends BaseCommand {
-  static description = 'Generate proof-of-possession to be used to authorize a signer'
+  static description =
+    'Generate proof-of-possession to be used to authorize a signer. See the "account:authorize" command for more details.'
 
   static flags = {
     ...BaseCommand.flags,
-    signer: Flags.address({ required: true }),
-    account: Flags.address({ required: true }),
+    signer: Flags.address({
+      required: true,
+      description: 'Address of the signer key to prove possession of.',
+    }),
+    account: Flags.address({
+      required: true,
+      description: 'Address of the account that needs to proove possession of the signer key.',
+    }),
+    privateKey: flags.string({
+      description:
+        'Optional. The signer private key, only necessary if the key is not being managed by a locally running node.',
+    }),
   }
 
   static examples = [
@@ -19,10 +30,19 @@ export default class ProofOfPossession extends BaseCommand {
   async run() {
     const res = this.parse(ProofOfPossession)
     const accounts = await this.kit.contracts.getAccounts()
-    const pop = await accounts.generateProofOfSigningKeyPossession(
-      res.flags.account,
-      res.flags.signer
-    )
-    printValueMap({ signature: serializeSignature(pop) })
+    if (res.flags.privateKey) {
+      const pop = await accounts.generateProofOfSigningKeyPossessionLocally(
+        res.flags.account,
+        res.flags.signer,
+        res.flags.privateKey
+      )
+      printValueMap({ signature: serializeSignature(pop) })
+    } else {
+      const pop = await accounts.generateProofOfSigningKeyPossession(
+        res.flags.account,
+        res.flags.signer
+      )
+      printValueMap({ signature: serializeSignature(pop) })
+    }
   }
 }

packages/cli/src/commands/account/register.ts

@@ -5,7 +5,8 @@ import { displaySendTx } from '../../utils/cli'
 import { Flags } from '../../utils/command'
 
 export default class Register extends BaseCommand {
-  static description = 'Register an account'
+  static description =
+    'Register an account on-chain. This allows you to lock Gold, which is a pre-requisite for registering a Validator or Group, participating in Validator elections and on-chain Governance, and earning epoch rewards.'
 
   static flags = {
     ...BaseCommand.flags,

packages/cli/src/commands/election/current.ts

@@ -2,7 +2,8 @@ import { cli } from 'cli-ux'
 import { BaseCommand } from '../../base'
 
 export default class ElectionCurrent extends BaseCommand {
-  static description = 'Outputs the currently elected validator set'
+  static description =
+    'Outputs the set of validators currently participating in BFT to create blocks. The validator set is re-elected at the end of every epoch.'
 
   static flags = {
     ...BaseCommand.flags,

packages/cli/src/commands/election/list.ts

@@ -2,7 +2,8 @@ import { cli } from 'cli-ux'
 import { BaseCommand } from '../../base'
 
 export default class List extends BaseCommand {
-  static description = 'Outputs the validator groups and their vote totals'
+  static description =
+    'Prints the list of validator groups, the number of votes they have received, the number of additional votes they are able to receive, and whether or not they are eleigible to elect validators.'
 
   static flags = {
     ...BaseCommand.flags,

packages/cli/src/commands/election/run.ts

@@ -2,7 +2,8 @@ import { cli } from 'cli-ux'
 import { BaseCommand } from '../../base'
 
 export default class ElectionRun extends BaseCommand {
-  static description = 'Runs an mock election and outputs the validators that were elected'
+  static description =
+    'Runs a "mock" election and prints out the validators that would be elected if the epoch ended right now.'
 
   static flags = {
     ...BaseCommand.flags,

packages/cli/src/commands/election/show.ts

@@ -6,7 +6,7 @@ import { printValueMapRecursive } from '../../utils/cli'
 import { Args } from '../../utils/command'
 
 export default class ElectionShow extends BaseCommand {
-  static description = 'Show election information about a voter or Validator Group'
+  static description = 'Show election information about a voter or registered Validator Group'
 
   static flags = {
     ...BaseCommand.flags,

packages/cli/src/commands/exchange/dollars.ts

@@ -0,0 +1,47 @@
+import { flags } from '@oclif/command'
+import BigNumber from 'bignumber.js'
+import { BaseCommand } from '../../base'
+import { displaySendTx } from '../../utils/cli'
+import { Flags } from '../../utils/command'
+
+export default class ExchangeDollars extends BaseCommand {
+  static description = 'Exchange Celo Dollars for Celo Gold via the stability mechanism'
+
+  static flags = {
+    ...BaseCommand.flags,
+    from: Flags.address({
+      required: true,
+      description: 'The address with Celo Dollars to exchange',
+    }),
+    value: Flags.address({
+      required: true,
+      description: 'The value of Celo Dollars to exchange for Celo Gold',
+    }),
+    for: Flags.address({
+      required: true,
+      description: 'The minimum value of Celo Gold to receive in return',
+    }),
+    commission: flags.string({ required: true }),
+  }
+
+  static args = []
+
+  static examples = [
+    'dollars --value 10000000000000 --for 50000000000000 --from 0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d',
+  ]
+
+  async run() {
+    const res = this.parse(ExchangeDollars)
+    const sellAmount = new BigNumber(res.flags.value)
+    const minBuyAmount = new BigNumber(res.flags.for)
+
+    this.kit.defaultAccount = res.flags.from
+    const stableToken = await this.kit.contracts.getStableToken()
+    const exchange = await this.kit.contracts.getExchange()
+
+    await displaySendTx('approve', stableToken.approve(exchange.address, sellAmount.toFixed()))
+
+    const exchangeTx = exchange.exchange(sellAmount.toFixed(), minBuyAmount.toFixed(), false)
+    await displaySendTx('exchange', exchangeTx)
+  }
+}

packages/cli/src/commands/exchange/gold.ts

@@ -0,0 +1,44 @@
+import { flags } from '@oclif/command'
+import BigNumber from 'bignumber.js'
+import { BaseCommand } from '../../base'
+import { displaySendTx } from '../../utils/cli'
+import { Flags } from '../../utils/command'
+
+export default class ExchangeGold extends BaseCommand {
+  static description = 'Exchange Celo Gold for Celo Dollars via the stability mechanism'
+
+  static flags = {
+    ...BaseCommand.flags,
+    from: Flags.address({ required: true, description: 'The address with Celo Gold to exchange' }),
+    value: Flags.address({
+      required: true,
+      description: 'The value of Celo Gold to exchange for Celo Dollars',
+    }),
+    for: Flags.address({
+      required: true,
+      description: 'The minimum value of Celo Dollars to receive in return',
+    }),
+    commission: flags.string({ required: true }),
+  }
+
+  static args = []
+
+  static examples = [
+    'gold --value 5000000000000 --for 100000000000000 --from 0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d',
+  ]
+
+  async run() {
+    const res = this.parse(ExchangeGold)
+    const sellAmount = new BigNumber(res.flags.value)
+    const minBuyAmount = new BigNumber(res.flags.for)
+
+    this.kit.defaultAccount = res.flags.from
+    const goldToken = await this.kit.contracts.getGoldToken()
+    const exchange = await this.kit.contracts.getExchange()
+
+    await displaySendTx('approve', goldToken.approve(exchange.address, sellAmount.toFixed()))
+
+    const exchangeTx = exchange.exchange(sellAmount.toFixed(), minBuyAmount.toFixed(), true)
+    await displaySendTx('exchange', exchangeTx)
+  }
+}

packages/cli/src/commands/exchange/list.ts → packages/cli/src/commands/exchange/show.ts

@@ -2,13 +2,13 @@ import { flags } from '@oclif/command'
 import { cli } from 'cli-ux'
 import { BaseCommand } from '../../base'
 
-export default class List extends BaseCommand {
-  static description = 'List information about tokens on the exchange (all amounts in wei)'
+export default class ExchangeShow extends BaseCommand {
+  static description = 'Show the current exchange rates offered by the Exchange'
 
   static flags = {
     ...BaseCommand.flags,
     amount: flags.string({
-      description: 'Amount of sellToken (in wei) to report rates for',
+      description: 'Amount of the token being exchanged to report rates for',
       default: '1000000000000000000',
     }),
   }
@@ -18,7 +18,7 @@ export default class List extends BaseCommand {
   static examples = ['list']
 
   async run() {
-    const { flags: parsedFlags } = this.parse(List)
+    const { flags: parsedFlags } = this.parse(ExchangeShow)
 
     cli.action.start('Fetching exchange rates...')
     const exchange = await this.kit.contracts.getExchange()

packages/cli/src/commands/lockedgold/show.ts

@@ -4,7 +4,8 @@ import { printValueMapRecursive } from '../../utils/cli'
 import { Args } from '../../utils/command'
 
 export default class Show extends BaseCommand {
-  static description = 'Show Locked Gold information for a given account'
+  static description =
+    'Show Locked Gold information for a given account. This includes the total amount of locked gold, the amount being used for voting in Validator Elections, and any pending withdrawals that have been initiated via "lockedgold:unlock".'
 
   static flags = {
     ...BaseCommand.flags,

packages/cli/src/commands/lockedgold/unlock.ts

@@ -6,7 +6,8 @@ import { Flags } from '../../utils/command'
 import { LockedGoldArgs } from '../../utils/lockedgold'
 
 export default class Unlock extends BaseCommand {
-  static description = 'Unlocks Celo Gold, which can be withdrawn after the unlocking period.'
+  static description =
+    'Unlocks Celo Gold, which can be withdrawn after the unlocking period. Unlocked gold will appear as a "pending withdrawal" until the unlocking period is over, after which it can be withdrawn via "lockedgold:withdraw".'
 
   static flags = {
     ...BaseCommand.flags,

packages/cli/src/commands/lockedgold/withdraw.ts

@@ -4,7 +4,8 @@ import { displaySendTx } from '../../utils/cli'
 import { Flags } from '../../utils/command'
 
 export default class Withdraw extends BaseCommand {
-  static description = 'Withdraw unlocked gold whose unlocking period has passed.'
+  static description =
+    'Withdraw any pending withdrawals created via "lockedgold:unlock" that have become available.'
 
   static flags = {
     ...BaseCommand.flags,