diff --git a/packages/cli/package.json b/packages/cli/package.json index 0dfd83dceea..2c589cb8782 100644 --- a/packages/cli/package.json +++ b/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,16 +79,16 @@ "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" @@ -96,11 +96,14 @@ "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", diff --git a/packages/cli/src/commands/account/authorize.ts b/packages/cli/src/commands/account/authorize.ts index 4878f7e4013..55d63e24034 100644 --- a/packages/cli/src/commands/account/authorize.ts +++ b/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, diff --git a/packages/cli/src/commands/account/balance.ts b/packages/cli/src/commands/account/balance.ts index d5f44440467..d7800d91d03 100644 --- a/packages/cli/src/commands/account/balance.ts +++ b/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) } diff --git a/packages/cli/src/commands/account/proof-of-possession.ts b/packages/cli/src/commands/account/proof-of-possession.ts index 24b0ab206ba..7c5b0f90cb6 100644 --- a/packages/cli/src/commands/account/proof-of-possession.ts +++ b/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) }) + } } } diff --git a/packages/cli/src/commands/account/register.ts b/packages/cli/src/commands/account/register.ts index 9dd445c5838..c7c4b4791fd 100644 --- a/packages/cli/src/commands/account/register.ts +++ b/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, diff --git a/packages/cli/src/commands/election/current.ts b/packages/cli/src/commands/election/current.ts index 26fda2f61da..5eba5fe88d0 100644 --- a/packages/cli/src/commands/election/current.ts +++ b/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, diff --git a/packages/cli/src/commands/election/list.ts b/packages/cli/src/commands/election/list.ts index 1079dea038f..b0195723394 100644 --- a/packages/cli/src/commands/election/list.ts +++ b/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, diff --git a/packages/cli/src/commands/election/run.ts b/packages/cli/src/commands/election/run.ts index ee1ea8089f8..3026f7b3e27 100644 --- a/packages/cli/src/commands/election/run.ts +++ b/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, diff --git a/packages/cli/src/commands/election/show.ts b/packages/cli/src/commands/election/show.ts index c73247810d2..345e6337bf1 100644 --- a/packages/cli/src/commands/election/show.ts +++ b/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, diff --git a/packages/cli/src/commands/exchange/dollars.ts b/packages/cli/src/commands/exchange/dollars.ts new file mode 100644 index 00000000000..69c335ca533 --- /dev/null +++ b/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) + } +} diff --git a/packages/cli/src/commands/exchange/gold.ts b/packages/cli/src/commands/exchange/gold.ts new file mode 100644 index 00000000000..68e0fa9fa04 --- /dev/null +++ b/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) + } +} diff --git a/packages/cli/src/commands/exchange/selldollar.ts b/packages/cli/src/commands/exchange/selldollar.ts deleted file mode 100644 index 60ad39a9c39..00000000000 --- a/packages/cli/src/commands/exchange/selldollar.ts +++ /dev/null @@ -1,27 +0,0 @@ -import BigNumber from 'bignumber.js' -import { BaseCommand } from '../../base' -import { displaySendTx } from '../../utils/cli' -import { swapArguments } from '../../utils/exchange' - -export default class SellDollar extends BaseCommand { - static description = 'Sell Celo dollars for Celo gold on the exchange' - - static args = swapArguments - - static examples = ['selldollar 100 300 0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d'] - - async run() { - const { args } = this.parse(SellDollar) - const sellAmount = new BigNumber(args.sellAmount) - const minBuyAmount = new BigNumber(args.minBuyAmount) - - this.kit.defaultAccount = args.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) - } -} diff --git a/packages/cli/src/commands/exchange/sellgold.ts b/packages/cli/src/commands/exchange/sellgold.ts deleted file mode 100644 index 977db9839a5..00000000000 --- a/packages/cli/src/commands/exchange/sellgold.ts +++ /dev/null @@ -1,27 +0,0 @@ -import BigNumber from 'bignumber.js' -import { BaseCommand } from '../../base' -import { displaySendTx } from '../../utils/cli' -import { swapArguments } from '../../utils/exchange' - -export default class SellGold extends BaseCommand { - static description = 'Sell Celo gold for Celo dollars on the exchange' - - static args = swapArguments - - static examples = ['sellgold 100 300 0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d'] - - async run() { - const { args } = this.parse(SellGold) - const sellAmount = new BigNumber(args.sellAmount) - const minBuyAmount = new BigNumber(args.minBuyAmount) - - this.kit.defaultAccount = args.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) - } -} diff --git a/packages/cli/src/commands/exchange/list.ts b/packages/cli/src/commands/exchange/show.ts similarity index 74% rename from packages/cli/src/commands/exchange/list.ts rename to packages/cli/src/commands/exchange/show.ts index 1d38232cf06..97139cd7afa 100644 --- a/packages/cli/src/commands/exchange/list.ts +++ b/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() diff --git a/packages/cli/src/commands/lockedgold/show.ts b/packages/cli/src/commands/lockedgold/show.ts index b959faa599a..f6f21de0902 100644 --- a/packages/cli/src/commands/lockedgold/show.ts +++ b/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, diff --git a/packages/cli/src/commands/lockedgold/unlock.ts b/packages/cli/src/commands/lockedgold/unlock.ts index 2438a474aac..6eff5df54fa 100644 --- a/packages/cli/src/commands/lockedgold/unlock.ts +++ b/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, diff --git a/packages/cli/src/commands/lockedgold/withdraw.ts b/packages/cli/src/commands/lockedgold/withdraw.ts index d3432e6516c..2738495c5fe 100644 --- a/packages/cli/src/commands/lockedgold/withdraw.ts +++ b/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, diff --git a/packages/cli/src/commands/network/parameters.ts b/packages/cli/src/commands/network/parameters.ts index a87439ae45b..27369aa1edf 100644 --- a/packages/cli/src/commands/network/parameters.ts +++ b/packages/cli/src/commands/network/parameters.ts @@ -2,7 +2,8 @@ import { BaseCommand } from '../../base' import { printValueMapRecursive } from '../../utils/cli' export default class Parameters extends BaseCommand { - static description = 'View network parameters' + static description = + 'View parameters of the network, including but not limited to configuration for the various Celo core smart contracts.' static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/node/accounts.ts b/packages/cli/src/commands/node/accounts.ts index 10a9299d826..541eebb7efe 100644 --- a/packages/cli/src/commands/node/accounts.ts +++ b/packages/cli/src/commands/node/accounts.ts @@ -1,7 +1,7 @@ import { BaseCommand } from '../../base' export default class NodeAccounts extends BaseCommand { - static description = 'List node accounts' + static description = 'List the addresses that this node has the private keys for.' static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/account/transferdollar.ts b/packages/cli/src/commands/transfer/dollars.ts similarity index 74% rename from packages/cli/src/commands/account/transferdollar.ts rename to packages/cli/src/commands/transfer/dollars.ts index 75fcd38dd6a..4c7d26b0c0e 100644 --- a/packages/cli/src/commands/account/transferdollar.ts +++ b/packages/cli/src/commands/transfer/dollars.ts @@ -4,8 +4,8 @@ import { BaseCommand } from '../../base' import { displaySendTx } from '../../utils/cli' import { Flags } from '../../utils/command' -export default class DollarTransfer extends BaseCommand { - static description = 'Transfer Celo Dollars' +export default class TransferDollars extends BaseCommand { + static description = 'Transfer Celo Dollars to a specified address.' static flags = { ...BaseCommand.flags, @@ -15,11 +15,11 @@ export default class DollarTransfer extends BaseCommand { } static examples = [ - 'transferdollar --from 0xa0Af2E71cECc248f4a7fD606F203467B500Dd53B --to 0x5409ed021d9299bf6814279a6a1411a7e866a631 --value 1', + 'dollars --from 0xa0Af2E71cECc248f4a7fD606F203467B500Dd53B --to 0x5409ed021d9299bf6814279a6a1411a7e866a631 --value 1000000000000000000', ] async run() { - const res = this.parse(DollarTransfer) + const res = this.parse(TransferDollars) const from: string = res.flags.from const to: string = res.flags.to diff --git a/packages/cli/src/commands/account/transfergold.ts b/packages/cli/src/commands/transfer/gold.ts similarity index 79% rename from packages/cli/src/commands/account/transfergold.ts rename to packages/cli/src/commands/transfer/gold.ts index 96e04a39f8d..d56ae4ef7d5 100644 --- a/packages/cli/src/commands/account/transfergold.ts +++ b/packages/cli/src/commands/transfer/gold.ts @@ -4,8 +4,8 @@ import { BaseCommand } from '../../base' import { displaySendTx } from '../../utils/cli' import { Flags } from '../../utils/command' -export default class GoldTransfer extends BaseCommand { - static description = 'Transfer gold' +export default class TransferGold extends BaseCommand { + static description = 'Transfer Celo Gold to a specified address.' static flags = { ...BaseCommand.flags, @@ -15,11 +15,11 @@ export default class GoldTransfer extends BaseCommand { } static examples = [ - 'transfergold --from 0xa0Af2E71cECc248f4a7fD606F203467B500Dd53B --to 0x5409ed021d9299bf6814279a6a1411a7e866a631 --value 1', + 'transfergold --from 0xa0Af2E71cECc248f4a7fD606F203467B500Dd53B --to 0x5409ed021d9299bf6814279a6a1411a7e866a631 --value 10000000000000000000', ] async run() { - const res = this.parse(GoldTransfer) + const res = this.parse(TransferGold) const from: string = res.flags.from const to: string = res.flags.to diff --git a/packages/cli/src/commands/validator/affiliate.ts b/packages/cli/src/commands/validator/affiliate.ts index 26dda68f8a4..13f0bc5b16a 100644 --- a/packages/cli/src/commands/validator/affiliate.ts +++ b/packages/cli/src/commands/validator/affiliate.ts @@ -5,7 +5,8 @@ import { displaySendTx } from '../../utils/cli' import { Args, Flags } from '../../utils/command' export default class ValidatorAffiliate extends BaseCommand { - static description = 'Affiliate to a ValidatorGroup' + static description = + "Affiliate a Validator with a Validator Group. This allows the Validator Group to add that Validator as a member. If the Validator is already a member of a Validator Group, affiliating with a different Group will remove the Validator from the first group's members." static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/validator/deaffiliate.ts b/packages/cli/src/commands/validator/deaffiliate.ts index 54846cc13c4..6488364b012 100644 --- a/packages/cli/src/commands/validator/deaffiliate.ts +++ b/packages/cli/src/commands/validator/deaffiliate.ts @@ -4,7 +4,8 @@ import { displaySendTx } from '../../utils/cli' import { Flags } from '../../utils/command' export default class ValidatorDeAffiliate extends BaseCommand { - static description = 'DeAffiliate to a ValidatorGroup' + static description = + 'Deaffiliate a Validator from a Validator Group, and remove it from the Group if it is also a member.' static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/validator/deregister.ts b/packages/cli/src/commands/validator/deregister.ts index 9c6184c73f1..133d3ea2380 100644 --- a/packages/cli/src/commands/validator/deregister.ts +++ b/packages/cli/src/commands/validator/deregister.ts @@ -4,7 +4,8 @@ import { displaySendTx } from '../../utils/cli' import { Flags } from '../../utils/command' export default class ValidatorDeregister extends BaseCommand { - static description = 'Deregister a Validator' + static description = + 'Deregister a Validator. Approximately 60 days after deregistration, the 10,000 Gold locked up to register the Validator will become possible to unlock. Note that deregistering a Validator will also deaffiliate and remove the Validator from any Group it may be an affiliate or member of.' static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/validator/list.ts b/packages/cli/src/commands/validator/list.ts index c1faa4b5de1..fd3530fb1c3 100644 --- a/packages/cli/src/commands/validator/list.ts +++ b/packages/cli/src/commands/validator/list.ts @@ -2,7 +2,8 @@ import { cli } from 'cli-ux' import { BaseCommand } from '../../base' export default class ValidatorList extends BaseCommand { - static description = 'List registered Validators' + static description = + 'List registered Validators, their name (if provided), affiliation, uptime score, and public keys used for validating.' static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/validator/requirements.ts b/packages/cli/src/commands/validator/requirements.ts index 0cb871b268f..69aa4ac16f0 100644 --- a/packages/cli/src/commands/validator/requirements.ts +++ b/packages/cli/src/commands/validator/requirements.ts @@ -2,7 +2,8 @@ import { BaseCommand } from '../../base' import { printValueMap } from '../../utils/cli' export default class ValidatorRequirements extends BaseCommand { - static description = 'Get Requirements for Validators' + static description = + 'List the Locked Gold requirements for registering a Validator. This consists of a value, which is the amount of Celo Gold that needs to be locked in order to register, and a duration, which is the amount of time that Gold must stay locked following the deregistration of the Validator.' static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/validator/show.ts b/packages/cli/src/commands/validator/show.ts index 17ed3bdcf29..1cde4b17516 100644 --- a/packages/cli/src/commands/validator/show.ts +++ b/packages/cli/src/commands/validator/show.ts @@ -5,7 +5,7 @@ import { printValueMap } from '../../utils/cli' import { Args } from '../../utils/command' export default class ValidatorShow extends BaseCommand { - static description = 'Show information about an existing Validator' + static description = 'Show information about a registered Validator.' static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/validator/update-bls-public-key.ts b/packages/cli/src/commands/validator/update-bls-public-key.ts index e4511839fbf..3c31ca102a8 100644 --- a/packages/cli/src/commands/validator/update-bls-public-key.ts +++ b/packages/cli/src/commands/validator/update-bls-public-key.ts @@ -4,7 +4,8 @@ import { displaySendTx } from '../../utils/cli' import { Flags } from '../../utils/command' export default class ValidatorUpdateBlsPublicKey extends BaseCommand { - static description = 'Update BLS key for a validator' + static description = + 'Update the BLS public key for a Validator to be used in consensus. Regular (ECDSA and BLS) key rotation is recommended for Validator operational security.' static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/validatorgroup/commission.ts b/packages/cli/src/commands/validatorgroup/commission.ts index 19c7263bda5..fae157fb5e0 100644 --- a/packages/cli/src/commands/validatorgroup/commission.ts +++ b/packages/cli/src/commands/validatorgroup/commission.ts @@ -6,7 +6,8 @@ import { displaySendTx } from '../../utils/cli' import { Flags } from '../../utils/command' export default class ValidatorGroupCommission extends BaseCommand { - static description = 'Update the commission for an existing validator group' + static description = + 'Update the commission for a registered Validator Group. This represents the share of the epoch rewards given to elected Validators that goes to the group they are a member of.' static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/validatorgroup/deregister.ts b/packages/cli/src/commands/validatorgroup/deregister.ts index 57c0aeefdbb..bafb6cd95b6 100644 --- a/packages/cli/src/commands/validatorgroup/deregister.ts +++ b/packages/cli/src/commands/validatorgroup/deregister.ts @@ -4,7 +4,8 @@ import { displaySendTx } from '../../utils/cli' import { Flags } from '../../utils/command' export default class ValidatorGroupDeRegister extends BaseCommand { - static description = 'Deregister a ValidatorGroup' + static description = + 'Deregister a Validator Group. Approximately 60 days after deregistration, the 10,000 Gold locked up to register the Validator Group will become possible to unlock. Note that the Group must be empty (i.e. no members) before deregistering.' static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/validatorgroup/list.ts b/packages/cli/src/commands/validatorgroup/list.ts index 096520b8ff9..a7e6482e449 100644 --- a/packages/cli/src/commands/validatorgroup/list.ts +++ b/packages/cli/src/commands/validatorgroup/list.ts @@ -2,7 +2,8 @@ import { cli } from 'cli-ux' import { BaseCommand } from '../../base' export default class ValidatorGroupList extends BaseCommand { - static description = 'List existing Validator Groups' + static description = + 'List registered Validator Groups, their names (if provided), commission, and members.' static flags = { ...BaseCommand.flags, diff --git a/packages/cli/src/commands/validatorgroup/register.ts b/packages/cli/src/commands/validatorgroup/register.ts index 4c9975a1a87..ef3366b71db 100644 --- a/packages/cli/src/commands/validatorgroup/register.ts +++ b/packages/cli/src/commands/validatorgroup/register.ts @@ -11,7 +11,11 @@ export default class ValidatorGroupRegister extends BaseCommand { static flags = { ...BaseCommand.flags, from: Flags.address({ required: true, description: 'Address for the Validator Group' }), - commission: flags.string({ required: true }), + commission: flags.string({ + required: true, + description: + 'The share of the epoch rewards given to elected Validators that goes to the group.', + }), } static examples = ['register --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95 --commission 0.1'] diff --git a/packages/cli/src/utils/lockedgold.ts b/packages/cli/src/utils/lockedgold.ts index 9e9aee7645e..f37c8976e69 100644 --- a/packages/cli/src/utils/lockedgold.ts +++ b/packages/cli/src/utils/lockedgold.ts @@ -1,10 +1,6 @@ export const LockedGoldArgs = { - pendingWithdrawalIndexArg: { - name: 'pendingWithdrawalIndex', - description: 'index of pending withdrawal whose unlocking period has passed', - }, valueArg: { name: 'value', - description: 'unit amount of Celo Gold (cGLD)', + description: 'The unit amount of Celo Gold (cGLD)', }, } diff --git a/packages/contractkit/src/wrappers/Accounts.ts b/packages/contractkit/src/wrappers/Accounts.ts index 7cb87638588..bf369c9818a 100644 --- a/packages/contractkit/src/wrappers/Accounts.ts +++ b/packages/contractkit/src/wrappers/Accounts.ts @@ -1,8 +1,11 @@ import { hashMessageWithPrefix, + LocalSigner, + NativeSigner, parseSignature, Signature, signedMessageToPublicKey, + Signer, } from '@celo/utils/lib/signatureUtils' import Web3 from 'web3' import { Address } from '../base' @@ -180,7 +183,19 @@ export class AccountsWrapper extends BaseWrapper { } async generateProofOfSigningKeyPossession(account: Address, signer: Address) { - return this.getParsedSignatureOfAddress(account, signer) + return this.getParsedSignatureOfAddress( + account, + signer, + NativeSigner(this.kit.web3.eth.sign, signer) + ) + } + + async generateProofOfSigningKeyPossessionLocally( + account: Address, + signer: Address, + privateKey: string + ) { + return this.getParsedSignatureOfAddress(account, signer, LocalSigner(privateKey)) } /** @@ -247,9 +262,9 @@ export class AccountsWrapper extends BaseWrapper { return parseSignature(hash, signature, signer) } - private async getParsedSignatureOfAddress(address: Address, signer: string) { + private async getParsedSignatureOfAddress(address: Address, signer: string, signerFn: Signer) { const hash = Web3.utils.soliditySha3({ type: 'address', value: address }) - const signature = await this.kit.web3.eth.sign(hash, signer) + const signature = await signerFn.sign(hash) return parseSignature(hash, signature, signer) } } diff --git a/packages/docs/command-line-interface/account.md b/packages/docs/command-line-interface/account.md index 938b4ee9623..b1829761ead 100644 --- a/packages/docs/command-line-interface/account.md +++ b/packages/docs/command-line-interface/account.md @@ -1,12 +1,12 @@ --- -description: Manage your account, send and receive Celo Gold and Celo Dollars +description: Manage your account, keys, and metadata --- ## Commands ### Authorize -Authorize an attestation, validator, or vote signer +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. ``` USAGE @@ -29,11 +29,11 @@ _See code: [packages/cli/src/commands/account/authorize.ts](https://github.com/c ### Balance -View Celo Dollar and Gold balances given account address +View Celo Dollar and Gold balances for an address ``` USAGE - $ celocli account:balance ACCOUNT + $ celocli account:balance ADDRESS EXAMPLE balance 0x5409ed021d9299bf6814279a6a1411a7e866a631 @@ -216,15 +216,20 @@ _See code: [packages/cli/src/commands/account/new.ts](https://github.com/celo-or ### Proof-of-possession -Generate proof-of-possession to be used to authorize a signer +Generate proof-of-possession to be used to authorize a signer. See the "account:authorize" command for more details. ``` USAGE $ celocli account:proof-of-possession OPTIONS - --account=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Account Address - --signer=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Account Address + --account=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Address of the account that needs to proove + possession of the signer key. + + --privateKey=privateKey Optional. The signer private key, only necessary if the key is + not being managed by a locally running node. + + --signer=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Address of the signer key to prove possession of. EXAMPLE proof-of-possession --account 0x5409ed021d9299bf6814279a6a1411a7e866a631 --signer @@ -235,7 +240,7 @@ _See code: [packages/cli/src/commands/account/proof-of-possession.ts](https://gi ### Register -Register an account +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. ``` USAGE @@ -287,46 +292,6 @@ EXAMPLE _See code: [packages/cli/src/commands/account/show-metadata.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/account/show-metadata.ts)_ -### Transferdollar - -Transfer Celo Dollars - -``` -USAGE - $ celocli account:transferdollar - -OPTIONS - --from=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Address of the sender - --to=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Address of the receiver - --value=value (required) Amount to transfer (in wei) - -EXAMPLE - transferdollar --from 0xa0Af2E71cECc248f4a7fD606F203467B500Dd53B --to 0x5409ed021d9299bf6814279a6a1411a7e866a631 - --value 1 -``` - -_See code: [packages/cli/src/commands/account/transferdollar.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/account/transferdollar.ts)_ - -### Transfergold - -Transfer gold - -``` -USAGE - $ celocli account:transfergold - -OPTIONS - --from=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Address of the sender - --to=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Address of the receiver - --value=value (required) Amount to transfer (in wei) - -EXAMPLE - transfergold --from 0xa0Af2E71cECc248f4a7fD606F203467B500Dd53B --to 0x5409ed021d9299bf6814279a6a1411a7e866a631 --value - 1 -``` - -_See code: [packages/cli/src/commands/account/transfergold.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/account/transfergold.ts)_ - ### Unlock Unlock an account address to send transactions or validate blocks diff --git a/packages/docs/command-line-interface/election.md b/packages/docs/command-line-interface/election.md index 4629de45e8a..b7fb0140bd1 100644 --- a/packages/docs/command-line-interface/election.md +++ b/packages/docs/command-line-interface/election.md @@ -1,5 +1,5 @@ --- -description: View and manage validator elections +description: Participate in and view the state of Validator Elections --- ## Commands @@ -25,7 +25,7 @@ _See code: [packages/cli/src/commands/election/activate.ts](https://github.com/c ### Current -Outputs the currently elected validator set +Outputs the set of validators currently participating in BFT to create blocks. The validator set is re-elected at the end of every epoch. ``` USAGE @@ -39,7 +39,7 @@ _See code: [packages/cli/src/commands/election/current.ts](https://github.com/ce ### List -Outputs the validator groups and their vote totals +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. ``` USAGE @@ -73,7 +73,7 @@ _See code: [packages/cli/src/commands/election/revoke.ts](https://github.com/cel ### Run -Runs an mock election and outputs the validators that were elected +Runs a "mock" election and prints out the validators that would be elected if the epoch ended right now. ``` USAGE @@ -87,7 +87,7 @@ _See code: [packages/cli/src/commands/election/run.ts](https://github.com/celo-o ### Show -Show election information about a voter or Validator Group +Show election information about a voter or registered Validator Group ``` USAGE diff --git a/packages/docs/command-line-interface/exchange.md b/packages/docs/command-line-interface/exchange.md index 16fc35f9776..9dad11f6ce0 100644 --- a/packages/docs/command-line-interface/exchange.md +++ b/packages/docs/command-line-interface/exchange.md @@ -1,60 +1,62 @@ --- -description: Commands for interacting with the Exchange +description: Exchange Celo Dollars and Celo Gold via the stability mechanism --- ## Commands -### List +### Dollars -List information about tokens on the exchange (all amounts in wei) +Exchange Celo Dollars for Celo Gold via the stability mechanism ``` USAGE - $ celocli exchange:list + $ celocli exchange:dollars OPTIONS - --amount=amount [default: 1000000000000000000] Amount of sellToken (in wei) to report rates for + --commission=commission (required) + --for=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) The minimum value of Celo Gold to receive in return + --from=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) The address with Celo Dollars to exchange + --value=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) The value of Celo Dollars to exchange for Celo Gold EXAMPLE - list + dollars --value 10000000000000 --for 50000000000000 --from 0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d ``` -_See code: [packages/cli/src/commands/exchange/list.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/exchange/list.ts)_ +_See code: [packages/cli/src/commands/exchange/dollars.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/exchange/dollars.ts)_ -### Selldollar +### Gold -Sell Celo dollars for Celo gold on the exchange +Exchange Celo Gold for Celo Dollars via the stability mechanism ``` USAGE - $ celocli exchange:selldollar SELLAMOUNT MINBUYAMOUNT FROM + $ celocli exchange:gold -ARGUMENTS - SELLAMOUNT the amount of sellToken (in wei) to sell - MINBUYAMOUNT the minimum amount of buyToken (in wei) expected - FROM +OPTIONS + --commission=commission (required) + --for=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) The minimum value of Celo Dollars to receive in return + --from=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) The address with Celo Gold to exchange + --value=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) The value of Celo Gold to exchange for Celo Dollars EXAMPLE - selldollar 100 300 0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d + gold --value 5000000000000 --for 100000000000000 --from 0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d ``` -_See code: [packages/cli/src/commands/exchange/selldollar.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/exchange/selldollar.ts)_ +_See code: [packages/cli/src/commands/exchange/gold.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/exchange/gold.ts)_ -### Sellgold +### Show -Sell Celo gold for Celo dollars on the exchange +Show the current exchange rates offered by the Exchange ``` USAGE - $ celocli exchange:sellgold SELLAMOUNT MINBUYAMOUNT FROM + $ celocli exchange:show -ARGUMENTS - SELLAMOUNT the amount of sellToken (in wei) to sell - MINBUYAMOUNT the minimum amount of buyToken (in wei) expected - FROM +OPTIONS + --amount=amount [default: 1000000000000000000] Amount of the token being exchanged to report rates for EXAMPLE - sellgold 100 300 0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d + list ``` -_See code: [packages/cli/src/commands/exchange/sellgold.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/exchange/sellgold.ts)_ +_See code: [packages/cli/src/commands/exchange/show.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/exchange/show.ts)_ diff --git a/packages/docs/command-line-interface/introduction.md b/packages/docs/command-line-interface/introduction.md index 25c74201f36..e28f7fa398b 100644 --- a/packages/docs/command-line-interface/introduction.md +++ b/packages/docs/command-line-interface/introduction.md @@ -40,6 +40,10 @@ Make sure to kill the container when you are done. `$ docker kill celo_cli_container` +### **Prerequisites** + +- **You have a full node running.** See the [Running a Full Node](running-a-full-node.md) instructions for more details on running a full node. + ### Overview The tool is broken down into modules and commands with the following pattern: diff --git a/packages/docs/command-line-interface/lockedgold.md b/packages/docs/command-line-interface/lockedgold.md index 172013b51f0..c792e3f056b 100644 --- a/packages/docs/command-line-interface/lockedgold.md +++ b/packages/docs/command-line-interface/lockedgold.md @@ -14,7 +14,7 @@ USAGE OPTIONS --from=from (required) - --value=value (required) unit amount of Celo Gold (cGLD) + --value=value (required) The unit amount of Celo Gold (cGLD) EXAMPLE lock --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95 --value 10000000000000000000000 @@ -24,7 +24,7 @@ _See code: [packages/cli/src/commands/lockedgold/lock.ts](https://github.com/cel ### Show -Show Locked Gold information for a given account +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". ``` USAGE @@ -38,7 +38,7 @@ _See code: [packages/cli/src/commands/lockedgold/show.ts](https://github.com/cel ### Unlock -Unlocks Celo Gold, which can be withdrawn after the unlocking period. +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". ``` USAGE @@ -46,7 +46,7 @@ USAGE OPTIONS --from=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Account Address - --value=value (required) unit amount of Celo Gold (cGLD) + --value=value (required) The unit amount of Celo Gold (cGLD) EXAMPLE unlock --from 0x47e172F6CfB6c7D01C1574fa3E2Be7CC73269D95 --value 500000000 @@ -56,7 +56,7 @@ _See code: [packages/cli/src/commands/lockedgold/unlock.ts](https://github.com/c ### Withdraw -Withdraw unlocked gold whose unlocking period has passed. +Withdraw any pending withdrawals created via "lockedgold:unlock" that have become available. ``` USAGE diff --git a/packages/docs/command-line-interface/network.md b/packages/docs/command-line-interface/network.md index 094ec8a2738..b9b193e1645 100644 --- a/packages/docs/command-line-interface/network.md +++ b/packages/docs/command-line-interface/network.md @@ -1,12 +1,12 @@ --- -description: View network parameters +description: View parameters of the network, including but not limited to configuration for the various Celo core smart contracts. --- ## Commands ### Parameters -View network parameters +View parameters of the network, including but not limited to configuration for the various Celo core smart contracts. ``` USAGE diff --git a/packages/docs/command-line-interface/node.md b/packages/docs/command-line-interface/node.md index 63a938881ca..031ad811a85 100644 --- a/packages/docs/command-line-interface/node.md +++ b/packages/docs/command-line-interface/node.md @@ -6,7 +6,7 @@ description: Manage your full node ### Accounts -List node accounts +List the addresses that this node has the private keys for. ``` USAGE diff --git a/packages/docs/command-line-interface/transfer.md b/packages/docs/command-line-interface/transfer.md new file mode 100644 index 00000000000..640ae7f409a --- /dev/null +++ b/packages/docs/command-line-interface/transfer.md @@ -0,0 +1,45 @@ +--- +description: Transfer Celo Gold and Celo Dollars +--- + +## Commands + +### Dollars + +Transfer Celo Dollars to a specified address. + +``` +USAGE + $ celocli transfer:dollars + +OPTIONS + --from=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Address of the sender + --to=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Address of the receiver + --value=value (required) Amount to transfer (in wei) + +EXAMPLE + dollars --from 0xa0Af2E71cECc248f4a7fD606F203467B500Dd53B --to 0x5409ed021d9299bf6814279a6a1411a7e866a631 --value + 1000000000000000000 +``` + +_See code: [packages/cli/src/commands/transfer/dollars.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/transfer/dollars.ts)_ + +### Gold + +Transfer Celo Gold to a specified address. + +``` +USAGE + $ celocli transfer:gold + +OPTIONS + --from=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Address of the sender + --to=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Address of the receiver + --value=value (required) Amount to transfer (in wei) + +EXAMPLE + transfergold --from 0xa0Af2E71cECc248f4a7fD606F203467B500Dd53B --to 0x5409ed021d9299bf6814279a6a1411a7e866a631 --value + 10000000000000000000 +``` + +_See code: [packages/cli/src/commands/transfer/gold.ts](https://github.com/celo-org/celo-monorepo/tree/master/packages/cli/src/commands/transfer/gold.ts)_ diff --git a/packages/docs/command-line-interface/validator.md b/packages/docs/command-line-interface/validator.md index 1b389d6bd5f..fc7e1f015c2 100644 --- a/packages/docs/command-line-interface/validator.md +++ b/packages/docs/command-line-interface/validator.md @@ -1,12 +1,12 @@ --- -description: View and manage validators +description: View and manage Validators --- ## Commands ### Affiliate -Affiliate to a ValidatorGroup +Affiliate a Validator with a Validator Group. This allows the Validator Group to add that Validator as a member. If the Validator is already a member of a Validator Group, affiliating with a different Group will remove the Validator from the first group's members. ``` USAGE @@ -26,7 +26,7 @@ _See code: [packages/cli/src/commands/validator/affiliate.ts](https://github.com ### Deaffiliate -DeAffiliate to a ValidatorGroup +Deaffiliate a Validator from a Validator Group, and remove it from the Group if it is also a member. ``` USAGE @@ -43,7 +43,7 @@ _See code: [packages/cli/src/commands/validator/deaffiliate.ts](https://github.c ### Deregister -Deregister a Validator +Deregister a Validator. Approximately 60 days after deregistration, the 10,000 Gold locked up to register the Validator will become possible to unlock. Note that deregistering a Validator will also deaffiliate and remove the Validator from any Group it may be an affiliate or member of. ``` USAGE @@ -60,7 +60,7 @@ _See code: [packages/cli/src/commands/validator/deregister.ts](https://github.co ### List -List registered Validators +List registered Validators, their name (if provided), affiliation, uptime score, and public keys used for validating. ``` USAGE @@ -96,7 +96,7 @@ _See code: [packages/cli/src/commands/validator/register.ts](https://github.com/ ### Requirements -Get Requirements for Validators +List the Locked Gold requirements for registering a Validator. This consists of a value, which is the amount of Celo Gold that needs to be locked in order to register, and a duration, which is the amount of time that Gold must stay locked following the deregistration of the Validator. ``` USAGE @@ -110,7 +110,7 @@ _See code: [packages/cli/src/commands/validator/requirements.ts](https://github. ### Show -Show information about an existing Validator +Show information about a registered Validator. ``` USAGE @@ -127,7 +127,7 @@ _See code: [packages/cli/src/commands/validator/show.ts](https://github.com/celo ### Update-bls-public-key -Update BLS key for a validator +Update the BLS public key for a Validator to be used in consensus. Regular (ECDSA and BLS) key rotation is recommended for Validator operational security. ``` USAGE diff --git a/packages/docs/command-line-interface/validatorgroup.md b/packages/docs/command-line-interface/validatorgroup.md index 10ee77e5c3a..638b396b59e 100644 --- a/packages/docs/command-line-interface/validatorgroup.md +++ b/packages/docs/command-line-interface/validatorgroup.md @@ -1,12 +1,12 @@ --- -description: View and manage validator groups +description: View and manage Validator Groups --- ## Commands ### Commission -Update the commission for an existing validator group +Update the commission for a registered Validator Group. This represents the share of the epoch rewards given to elected Validators that goes to the group they are a member of. ``` USAGE @@ -24,7 +24,7 @@ _See code: [packages/cli/src/commands/validatorgroup/commission.ts](https://gith ### Deregister -Deregister a ValidatorGroup +Deregister a Validator Group. Approximately 60 days after deregistration, the 10,000 Gold locked up to register the Validator Group will become possible to unlock. Note that the Group must be empty (i.e. no members) before deregistering. ``` USAGE @@ -41,7 +41,7 @@ _See code: [packages/cli/src/commands/validatorgroup/deregister.ts](https://gith ### List -List existing Validator Groups +List registered Validator Groups, their names (if provided), commission, and members. ``` USAGE @@ -87,7 +87,9 @@ USAGE $ celocli validatorgroup:register OPTIONS - --commission=commission (required) + --commission=commission (required) The share of the epoch rewards given to elected + Validators that goes to the group. + --from=0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d (required) Address for the Validator Group EXAMPLE diff --git a/packages/docs/getting-started/running-a-full-node.md b/packages/docs/getting-started/running-a-full-node.md index 95aae11f3b2..1367dddea64 100644 --- a/packages/docs/getting-started/running-a-full-node.md +++ b/packages/docs/getting-started/running-a-full-node.md @@ -1,6 +1,15 @@ # Running a Full Node -This section explains how to get a full node running on the [Alfajores Testnet](alfajores-testnet.md), using a Docker image that was built for this purpose. +- [Running a Full Node](#running-a-full-node) + - [Prerequisites](#prerequisites) + - [Celo Networks](#celo-networks) + - [Pull the Celo Docker image](#pull-the-celo-docker-image) + - [Set up a data directory](#set-up-a-data-directory) + - [Create an account and get its address](#create-an-account-and-get-its-address) + - [Configure the node](#configure-the-node) + - [Start the node](#start-the-node) + +This section explains how to get a full node running on the [Alfajores Testnet](alfajores-testnet.md) and Baklava Beta Network, using a Docker image that was built for this purpose. Full nodes play a special purpose in the Celo ecosystem, acting as a bridge between the mobile wallets \(running as light clients\) and the validator nodes. To make sure that full nodes are rewarded for this service, the Celo protocol includes full node incentives. Every time a light client sends a new transaction, a portion of the transaction fees will go to the full node that gossips the transaction to other full nodes and validators. @@ -14,11 +23,25 @@ For this reason, despite the fact that Celo uses a proof-of-stake protocol, user A note about conventions: The code you'll see on this page is bash commands and their output. -A $ signifies the bash prompt. Everything following it is the command you should run in a terminal. The $ isn't part of the command, so don't copy it. - When you see text in angle brackets <>, replace them and the text inside with your own value of what it refers to. Don't include the <> in the command. {% endhint %} +## **Celo Networks** + +First we are going to setup the environment depending on the network we want to use (`Baklava` or `Alfajores`). Run: + +```bash +# If you want to connect to Baklava: +export CELO_NETWORK=baklava +export CELO_IMAGE=us.gcr.io/celo-testnet/celo-node +export NETWORK_ID=1101 + +# If you want to connect to Alfajores: +export CELO_NETWORK=alfajores +export CELO_IMAGE=us.gcr.io/celo-testnet/celo-node +export NETWORK_ID=44785 +``` + ## **Pull the Celo Docker image** We're going to use a Docker image containing the Celo node software in this tutorial. @@ -27,15 +50,17 @@ If you are re-running these instructions, the Celo Docker image may have been up Run: -`$ docker pull us.gcr.io/celo-testnet/celo-node:alfajores` +```bash +docker pull $CELO_IMAGE:$CELO_NETWORK +``` ## **Set up a data directory** First, create the directory that will store your node's configuration and its copy of the blockchain. This directory can be named anything you'd like, but here's a default you can use. The commands below create a directory and then navigate into it. The rest of the steps assume you are running the commands from inside this directory. -``` -$ mkdir celo-data-dir -$ cd celo-data-dir +```bash +mkdir celo-data-dir +cd celo-data-dir ``` ## **Create an account and get its address** @@ -44,13 +69,17 @@ In this step, you'll create an account on the network. If you've already done th Run the command to create a new account: -`` $ docker run -v `pwd`:/root/.celo --entrypoint /bin/sh -it us.gcr.io/celo-testnet/celo-node:alfajores -c "geth account new" `` +```bash +docker run -v $PWD:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE:$CELO_NETWORK -c "geth account new" +``` It will prompt you for a passphrase, ask you to confirm it, and then will output your account address: `Address: {}` Save this address to an environment variables, so that you can reference it below (don't include the braces): -`$ export CELO_ACCOUNT_ADDRESS=` +```bash +export CELO_ACCOUNT_ADDRESS= +``` _Note: this environment variable will only persist while you have this terminal window open. If you want this environment variable to be available in the future, you can add it to your `~/.bash_profile_ @@ -58,17 +87,23 @@ _Note: this environment variable will only persist while you have this terminal The genesis block is the first block in the chain, and is specific to each network. This command gets the `genesis.json` file for alfajores and uses it to initialize your nodes' data directory. -`` $ docker run -v `pwd`:/root/.celo us.gcr.io/celo-testnet/celo-node:alfajores init /celo/genesis.json `` +```bash +docker run -v $PWD:/root/.celo $CELO_IMAGE:$CELO_NETWORK init /celo/genesis.json +``` In order to allow the node to sync with the network, give it the address of existing nodes in the network: -`` $ docker run -v `pwd`:/root/.celo --entrypoint cp us.gcr.io/celo-testnet/celo-node:alfajores /celo/static-nodes.json /root/.celo/ `` +```bash +docker run -v $PWD:/root/.celo --entrypoint cp $CELO_IMAGE:$CELO_NETWORK /celo/static-nodes.json /root/.celo/ +``` ## **Start the node** This command specifies the settings needed to run the node, and gets it started. -`` $ docker run -p 127.0.0.1:8545:8545 -p 127.0.0.1:8546:8546 -p 30303:30303 -p 30303:30303/udp -v `pwd`:/root/.celo us.gcr.io/celo-testnet/celo-node:alfajores --verbosity 3 --networkid 44785 --syncmode full --rpc --rpcaddr 0.0.0.0 --rpcapi eth,net,web3,debug,admin,personal --lightserv 90 --lightpeers 1000 --maxpeers 1100 --etherbase $CELO_ACCOUNT_ADDRESS `` +```bash +docker run -p 127.0.0.1:8545:8545 -p 127.0.0.1:8546:8546 -p 30303:30303 -p 30303:30303/udp -v $PWD:/root/.celo $CELO_IMAGE:$CELO_NETWORK --verbosity 3 --networkid $NETWORK_ID --syncmode full --rpc --rpcaddr 0.0.0.0 --rpcapi eth,net,web3,debug,admin,personal --lightserv 90 --lightpeers 1000 --maxpeers 1100 --etherbase $CELO_ACCOUNT_ADDRESS +``` You'll start seeing some output. There may be some errors or warnings that are ignorable. After a few minutes, you should see lines that look like this. This means your node has synced with the network and is receiving blocks. @@ -80,7 +115,7 @@ INFO [07-16|14:04:48.941] Imported new chain segment blocks=335 t INFO [07-16|14:04:56.944] Imported new chain segment blocks=472 txs=0 mgas=0.000 elapsed=8.003s mgasps=0.000 number=1927 hash=4f1010…1414c1 age=4h52m31s cache=2.34mB ``` -You will have fully synced with the network once you have pulled the latest block number, which you can lookup by visiting at the [Alfajores Testnet Stats](https://alfajores-ethstats.celo-testnet.org/) page. +You will have fully synced with the network once you have pulled the latest block number, which you can lookup by visiting at the [Baklava Testnet Stats](https://baklava-ethstats.celo-testnet.org/) or [Alfajores Testnet Stats](https://alfajores-ethstats.celo-testnet.org/) pages. {% hint style="danger" %} **Security**: The command line above includes the parameter `--rpcaddr 0.0.0.0` which makes the Celo Blockchain software listen for incoming RPC requests on all network adaptors. Exercise extreme caution in doing this when running outside Docker, as it means that any unlocked accounts and their funds may be accessed from other machines on the Internet. In the context of running a Docker container on your local machine, this together with the `docker -p` flags allows you to make RPC calls from outside the container, i.e from your local host, but not from outside your machine. Read more about [Docker Networking](https://docs.docker.com/network/network-tutorial-standalone/#use-user-defined-bridge-networks) here. diff --git a/packages/docs/getting-started/running-a-validator-alfajores.md b/packages/docs/getting-started/running-a-validator-alfajores.md new file mode 100644 index 00000000000..18e7c920bac --- /dev/null +++ b/packages/docs/getting-started/running-a-validator-alfajores.md @@ -0,0 +1,114 @@ +# Running a Validator in Alfajores Network + +- [Running a Validator in Alfajores Network](#running-a-validator-in-alfajores-network) + - [Instructions](#instructions) + - [Pull the Celo Docker image](#pull-the-celo-docker-image) + - [Create accounts](#create-accounts) + - [Deploy the Validator node](#deploy-the-validator-node) + - [Running the Attestation Service](#running-the-attestation-service) + +This section explains how to get a Validator node running on the Alfajores network, using a Docker image that was built for this purpose. Most of this process is the same as running a full node, but with a few additional steps. + +This section is specific for Alfajores Network. You can find more details about running a Validator in different networks at [Running a Validator page](running-a-validator.md). + +## Instructions + +First we are going to setup the main environment variables related with the `Alfajores` network. Run: + +```bash +export CELO_IMAGE=us.gcr.io/celo-testnet/celo-node:alfajores +export NETWORK_ID=44785 +export URL_VERIFICATION_POOL=https://us-central1-celo-testnet-production.cloudfunctions.net/handleVerificationRequestalfajores/v0.1/sms/ +``` + +### Pull the Celo Docker image + +In all the commands we are going to see the `CELO_IMAGE` variable to refer to the right Docker image to use. Now we can get the Docker image: + +```bash +docker pull $CELO_IMAGE +``` + +### Create accounts + +Create and cd into the directory where you want to store the data and any other files needed to run your node. You can name this whatever you’d like, but here’s a default you can use: + +```bash +mkdir celo-alfajores-dir +cd celo-alfajores-dir +``` + +Create two accounts, one for the Validator and one for Validator Group, and get their addresses if you don’t already have them. If you already have your accounts, you can skip this step. + +To create your two accounts, run this command twice: + +```bash +docker run -v $PWD:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "geth account new" +``` + +It will prompt you for a passphrase, ask you to confirm it, and then will output your account address: `Address: {}` + +{% hint style="danger" %} +**Warning**: There is a known issue running geth inside Docker that happens eventually. So if that command fails, please check [this page](https://forum.celo.org/t/setting-up-a-validator-faq/90). +{% endhint %} + +Let's save these addresses to environment variables, so that you can reference it later (don't include the braces): + +```bash +export CELO_VALIDATOR_GROUP_ADDRESS= +export CELO_VALIDATOR_ADDRESS= +``` + +In order to register the Validator later on, generate a "proof of possession" - a signature proving you know your Validator's BLS private key. Run this command: + +```bash +docker run -v $PWD:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "geth account proof-of-possession $CELO_VALIDATOR_ADDRESS" +``` + +It will prompt you for the passphrase you've chosen for the Validator account. Let's save the resulting proof-of-possession to an environment variable: + +```bash +export CELO_VALIDATOR_POP= +``` + +### Deploy the Validator node + +Initialize the docker container, building from an image for the network and initializing Celo with the genesis block found inside the Docker image: + +```bash +docker run -v $PWD:/root/.celo $CELO_IMAGE init /celo/genesis.json +``` + +To participate in consensus, we need to set up our nodekey for our account. We can do so via the following command \(it will prompt you for your passphrase\): + +```bash +docker run -v $PWD:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "geth account set-node-key $CELO_VALIDATOR_ADDRESS" +``` + +In order to allow the node to sync with the network, give it the address of existing nodes in the network: + +```bash +docker run -v $PWD:/root/.celo --entrypoint cp $CELO_IMAGE /celo/static-nodes.json /root/.celo/ +``` + +Start up the node: + +```bash +docker run --name celo-validator --restart always -p 127.0.0.1:8545:8545 -p 127.0.0.1:8546:8546 -p 30303:30303 -p 30303:30303/udp -v $PWD:/root/.celo $CELO_IMAGE --verbosity 3 --networkid 44785 --syncmode full --rpc --rpcaddr 0.0.0.0 --rpcapi eth,net,web3,debug,admin,personal --maxpeers 1100 --mine --miner.verificationpool=$URL_VERIFICATION_POOL --etherbase $CELO_VALIDATOR_ADDRESS +``` + +{% hint style="danger" %} +**Security**: The command line above includes the parameter `--rpcaddr 0.0.0.0` which makes the Celo Blockchain software listen for incoming RPC requests on all the interfaces of the Docker container. Exercise extreme caution in doing this when running outside Docker, as it means that any unlocked accounts and their funds may be accessed from other machines on the Internet. In the context of running a Docker container on your local machine, this together with the `docker -p` flags allows you to make RPC calls from outside the container, i.e from your local host, but not from outside your machine. Read more about [Docker Networking](https://docs.docker.com/network/network-tutorial-standalone/#use-user-defined-bridge-networks) here. +{% endhint %} + +The `mine` flag will tell geth to try participating in the BFT consensus protocol, which is analogous to mining on the Ethereum PoW network. It will not be allowed to validate until it gets elected -- so next we need to stand for election. + +The `networkid` parameter value of `44785` indicates we are connecting the Alfajores Testnet. + +### Running the Attestation Service + +As part of the [lightweight identity protocol](/celo-codebase/protocol/identity), Validators are expected to run an [Attestation Service](https://github.com/celo-org/celo-monorepo/tree/master/packages/attestation-service) to provide attestations that allow users to map their phone number to an account on Celo. + +You can find the complete instructions about how to run the [Attestation Service at the documentation page](running-attestation-service.md). + +Now you may need to wait for your node to complete a full sync. You can check on the sync status with `celocli node:synced`. Your node will be fully synced when it has downloaded and processed the latest block, which you can see on the [Alfajores Testnet Stats](https://alfajores-ethstats.celo-testnet.org/) page. diff --git a/packages/docs/getting-started/running-a-validator-baklava.md b/packages/docs/getting-started/running-a-validator-baklava.md new file mode 100644 index 00000000000..a0e3f6cdf3e --- /dev/null +++ b/packages/docs/getting-started/running-a-validator-baklava.md @@ -0,0 +1,180 @@ +# Running a Validator in Baklava Network + +- [Running a Validator in Baklava Network](#running-a-validator-in-baklava-network) + - [Instructions](#instructions) + - [Environment variables](#environment-variables) + - [Pull the Celo Docker image](#pull-the-celo-docker-image) + - [Create accounts](#create-accounts) + - [Deploy the Validator and Proxy nodes](#deploy-the-validator-and-proxy-nodes) + - [Running the Attestation Service](#running-the-attestation-service) + - [Reference Script](#reference-script) + +This section explains how to get a Validator node running on the Baklava network, using a Docker image that was built for this purpose. Most of this process is the same as running a full node, but with a few additional steps. + +This section is specific for Baklava Network. You can find more details about running a Validator in different networks at [Running a Validator page](running-a-validator.md). + +## Instructions + +If you are re-running these instructions, the Celo Docker image may have been updated, and it's important to get the latest version. + +To run a complete Validator it's necessary to execute the following components: + +- The Validator software +- A Proxy that acts as an intermediary for the Validator requests +- The Attestation Service + +The Proxy is not mandatory but highly recommended. It allows to protect the Validator node from outside connections and hide the Validator behind that Proxy from other nodes of the network. + +### Environment variables + +| Variable | Explanation | +| ----------------------------- | ---------------------------------------------------------------- | +| CELO_IMAGE | The Docker image used for the Validator and Proxy containers | | +| NETWORK_ID | The Celo network chain ID | | +| URL_VERIFICATION_POOL | URL for the Verification pool for the attestation process | | +| CELO_VALIDATOR_GROUP_ADDRESS | The public address for the validation group | | +| CELO_VALIDATOR_ADDRESS | The public address for the Validator instance | | +| CELO_PROXY_ADDRESS | The public address for the Proxy instance | | +| CELO_VALIDATOR_BLS_PUBLIC_KEY | The BLS public key for the Validator instance | | +| CELO_VALIDATOR_BLS_SIGNATURE | A proof-of-possession of the BLS public key | | +| PROXY_ENODE | The enode address for the Validator proxy | | +| PROXY_IP | The Proxy container internal IP address from docker pool address | | +| ATTESTATION_KEY | The private key for the account used in the Attestation Service | | +| ATTESTATION_SERVICE_URL | The URL to access the Attestation Service deployed | | +| METADATA_URL | The URL to access the metadata file for your Attestation Service | | + +First we are going to setup the main environment variables related with the `Baklava` network. Run: + +```bash +export CELO_IMAGE=us.gcr.io/celo-testnet/celo-node:baklava +export NETWORK_ID=1101 +``` + +### Pull the Celo Docker image + +In all the commands we are going to see the `CELO_IMAGE` variable to refer to the right Docker image to use. Now we can get the Docker image: + +```bash +docker pull $CELO_IMAGE +``` + +### Create accounts + +At this point we need to create the accounts that will be used by the Validator and the Proxy. We create and cd into the directory where you want to store the data and any other files needed to run your node. You can name this whatever you’d like, but here’s a default you can use: + +```bash +mkdir -p celo-data-dir/proxy celo-data-dir/validator +cd celo-data-dir +``` + +We are going to need to create 3 accounts, 2 for the Validator and 1 for the Proxy. + +First we create three accounts, one for the Validator, one for the Validator Group and the last one for the Proxy. You can generate their addresses using the below commands if you don’t already have them. If you already have some accounts, you can skip this step. + +To create the accounts needed, run the following commands. The first two create the accounts for the Validator, the third one for the Proxy: + +```bash +docker run -v $PWD/validator:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "geth account new" +docker run -v $PWD/validator:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "geth account new" +docker run -v $PWD/proxy:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "geth account new" +``` + +Those commands will prompt you for a passphrase, ask you to confirm it, and then will output your account address: `Address: {}` + +{% hint style="danger" %} +**Warning**: There is a known issue running geth inside Docker that happens eventually. So if that command fails, please check [this page](https://forum.celo.org/t/setting-up-a-validator-faq/90). +{% endhint %} + +Let's save these addresses to environment variables, so that you can reference it later (don't include the braces): + +```bash +export CELO_VALIDATOR_GROUP_ADDRESS= +export CELO_VALIDATOR_ADDRESS= +export CELO_PROXY_ADDRESS= +``` + +In order to register the Validator later on, generate a "proof of possession" - a signature proving you know your Validator's BLS private key. Run this command to generate this "proof-of-possession", which consists of a the BLS public key and a signature: + +```bash +docker run -v $PWD/validator:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "geth account proof-of-possession $CELO_VALIDATOR_ADDRESS" +``` + +It will prompt you for the passphrase you've chosen for the Validator account. Let's save the resulting proof-of-possession to two environment variables: + +```bash +export CELO_VALIDATOR_BLS_PUBLIC_KEY= +export CELO_VALIDATOR_BLS_SIGNATURE= +``` + +### Deploy the Validator and Proxy nodes + +We initialize the Docker containers for the Validator and the Proxy, building from an image for the network and initializing Celo with the genesis block found inside the Docker image: + +```bash +docker run -v $PWD/proxy:/root/.celo $CELO_IMAGE init /celo/genesis.json +docker run -v $PWD/validator:/root/.celo $CELO_IMAGE init /celo/genesis.json +``` + +To participate in consensus, we need to set up our nodekey for our accounts. We can do so via the following commands \(it will prompt you for your passphrase\): + +```bash +docker run -v $PWD/proxy:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "geth account set-node-key $CELO_PROXY_ADDRESS" +docker run -v $PWD/validator:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "geth account set-node-key $CELO_VALIDATOR_ADDRESS" +``` + +{% hint style="danger" %} +**Warning**: There is a known issue running geth inside Docker that happens eventually. So if that command fails, please check [this page](https://forum.celo.org/t/setting-up-a-validator-faq/90). +{% endhint %} + +In order to allow the node to sync with the network, give it the address of existing nodes in the network: + +```bash +docker run -v $PWD/proxy:/root/.celo --entrypoint cp $CELO_IMAGE /celo/static-nodes.json /root/.celo/ +docker run -v $PWD/validator:/root/.celo --entrypoint cp $CELO_IMAGE /celo/static-nodes.json /root/.celo/ +``` + +At this point we are ready to start up the Proxy: + +```bash +docker run --name celo-proxy --restart always -p 8545:8545 -p 8546:8546 -p 30303:30303 -p 30303:30303/udp -p 30503:30503 -p 30503:30503/udp -v $PWD/proxy:/root/.celo $CELO_IMAGE --verbosity 3 --networkid $NETWORK_ID --syncmode full --rpc --rpcaddr 0.0.0.0 --rpcapi eth,net,web3,debug --maxpeers 1100 --etherbase=$CELO_PROXY_ADDRESS --proxy.proxy --proxy.proxiedvalidatoraddress $CELO_VALIDATOR_ADDRESS --proxy.internalendpoint :30503 +``` + +Now we need to obtain the Proxy enode and ip addresses, running the following commands: + +```bash +export PROXY_ENODE=$(docker exec celo-proxy geth --exec "admin.nodeInfo['enode'].split('//')[1].split('@')[0]" attach | tr -d '"') +export PROXY_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' celo-proxy) +``` + +Now we can start up the Validator node: + +```bash +docker run -v $PWD/validator:/root/.celo --entrypoint sh --rm $CELO_IMAGE -c "echo $DEFAULT_PASSWORD > /root/.celo/.password" +docker run --name celo-validator --restart always -p 127.0.0.1:8547:8545 -p 127.0.0.1:8548:8546 -p 30304:30303 -p 30304:30303/udp -v $PWD/validator:/root/.celo $CELO_IMAGE --verbosity 3 --networkid $NETWORK_ID --syncmode full --rpc --rpcaddr 0.0.0.0 --rpcapi eth,net,web3,debug --maxpeers 125 --mine --istanbul.blockperiod=5 --istanbul.requesttimeout=3000 --etherbase $CELO_VALIDATOR_ADDRESS --nodiscover --proxy.proxied --proxy.proxyenodeurlpair=enode://$PROXY_ENODE@$PROXY_IP:30503\;enode://$PROXY_ENODE@$PROXY_IP:30503 --unlock=$CELO_VALIDATOR_ADDRESS --password /root/.celo/.password +``` + +{% hint style="danger" %} +**Security**: The command line above includes the parameter `--rpcaddr 0.0.0.0` which makes the Celo Blockchain software listen for incoming RPC requests on all the interfaces of the Docker container. Exercise extreme caution in doing this when running outside Docker, as it means that any unlocked accounts and their funds may be accessed from other machines on the Internet. In the context of running a Docker container on your local machine, this together with the `docker -p` flags allows you to make RPC calls from outside the container, i.e from your local host, but not from outside your machine. Read more about [Docker Networking](https://docs.docker.com/network/network-tutorial-standalone/#use-user-defined-bridge-networks) here. +{% endhint %} + +The `mine` flag does not mean the node starts mining blocks, but rather starts trying to participate in the BFT consensus protocol. It cannot do this until it gets elected -- so next we need to stand for election. + +The `networkid` parameter value of `44785` indicates we are connecting the Baklava Beta network. + +### Running the Attestation Service + +As part of the [lightweight identity protocol](/celo-codebase/protocol/identity), Validators are expected to run an [Attestation Service](https://github.com/celo-org/celo-monorepo/tree/master/packages/attestation-service) to provide attestations that allow users to map their phone number to an account on Celo. + +You can find the complete instructions about how to run the [Attestation Service at the documentation page](running-attestation-service.md). + +You’re all set! Note that elections are finalized at the end of each epoch, roughly once an hour in the Baklava Testnet. After that hour, if you get elected, your node will start participating BFT consensus and validating blocks. Users requesting attestations will hit your registered Attestation Service. + +### Reference Script + +You can use (and modify if you want) this [reference bash script](../../../scripts/run-docker-validator-network.sh) automating all the above steps. It requires Docker and screen. + +You can see all the options using the following command: + +```bash +./run-docker-validator-network.sh help +``` diff --git a/packages/docs/getting-started/running-a-validator.md b/packages/docs/getting-started/running-a-validator.md index e073bc3bf06..adca40b2f4b 100644 --- a/packages/docs/getting-started/running-a-validator.md +++ b/packages/docs/getting-started/running-a-validator.md @@ -1,29 +1,42 @@ # Running a Validator -This section explains how to get a validator node running on the network, using a Docker image that was built for this purpose. Most of this process is the same as running a full node, but with a few additional steps. +- [Running a Validator](#running-a-validator) + - [Prerequisites](#prerequisites) + - [Hardware requirements](#hardware-requirements) + - [Software requirements](#software-requirements) + - [Celo Networks](#celo-networks) + - [Obtain and lock up some Celo Gold for staking](#obtain-and-lock-up-some-celo-gold-for-staking) + - [Baklava](#baklava) + - [Alfajores](#alfajores) + - [Lock up Celo Gold](#lock-up-celo-gold) + - [Run for election](#run-for-election) -Validators help secure the Celo network by participating in Celo’s Proof of Stake protocol. Validators are organized into Validator Groups, analogous to parties in representative democracies. A validator group is essentially an ordered list of validators, along with metadata like name and URL. +This section explains how to get a Validator node running on the network, using a Docker image that was built for this purpose. Most of this process is the same as running a full node, but with a few additional steps. -Just as anyone in a democracy can create their own political party, or seek to get selected to represent a party in an election, any Celo user can create a validator group and add themselves to it, or set up a potential validator and work to get an existing validator group to include them. +Validators help secure the Celo network by participating in Celo’s Proof of Stake protocol. Validators are organized into Validator Groups, analogous to parties in representative democracies. A Validator Group is essentially an ordered list of Validators, along with metadata like name and URL. -While other Validator Groups will exist on the Alfajores Testnet, the fastest way to get up and running with a validator will be to register a Validator Group, register a Validator, and add that Validator to your Validator Group. The addresses used to register Validator Groups and Validators must be unique, which will require that you create two accounts in the step-by-step guide below. +Just as anyone in a democracy can create their own political party, or seek to get selected to represent a party in an election, any Celo user can create a Validator group and add themselves to it, or set up a potential Validator and work to get an existing Validator group to include them. + +While other Validator Groups will exist on the Celo Networks, the fastest way to get up and running with a Validator will be to register a Validator Group, register a Validator, and add that Validator to your Validator Group. The addresses used to register Validator Groups and Validators must be unique, which will require that you create two accounts in the step-by-step guide below. + +You can find more details about Celo mission and why becoming a Validator [at the following page](https://medium.com/celohq/calling-all-chefs-become-a-celo-validator-c75d1c2909aa). {% hint style="info" %} -If you are starting up a validator, please consider leaving it running for a few weeks to support the network. +If you are starting up a Validator, please consider leaving it running for a few weeks to support the network. {% endhint %} -## **Prerequisites** +## Prerequisites ### Hardware requirements -Because Celo network is based in Proof of Stake, the hardware requirements are not very high. Proof of Stake consensus is not so CPU intensive as Proof of Work but has a higher requirements of network connectivity and lantency. Here you have a list of the standard requirements for running a validator node: +Because Celo network is based in Proof of Stake, the hardware requirements are not very high. Proof of Stake consensus is not so CPU intensive as Proof of Work but has a higher requirements of network connectivity and lantency. Here you have a list of the standard requirements for running a Validator node: - Memory: 8 GB RAM - CPU: Quad core 3GHz (64-bit) - Disk: 256 GB of SSD storage - Network: At least 1 GB input/output dual Ethernet -It is recommended to run the validator node in an environment that facilitates a 24/7 execution. Deployments in a top-tier datacenter facilitates the security and better uptimes. +It is recommended to run the Validator node in an environment that facilitates a 24/7 execution. Deployments in a top-tier datacenter facilitates the security and better uptimes. ### Software requirements @@ -46,167 +59,126 @@ The code you'll see on this page is bash commands and their output. When you see text in angle brackets <>, replace them and the text inside with your own value of what it refers to. Don't include the <> in the command. {% endhint %} -## **Pull the Celo Docker image** - -We're going to use a Docker image containing the Celo node software in this tutorial. - -If you are re-running these instructions, the Celo Docker image may have been updated, and it's important to get the latest version. - -Run: - -```bash -docker pull us.gcr.io/celo-testnet/celo-node:alfajores` -``` +## Celo Networks -## **Create accounts** +Celo provides different networks for different purposes. You can find the specifics about how to run a Validator in the Celo networks in the following documentation pages: -Create and cd into the directory where you want to store the data and any other files needed to run your node. You can name this whatever you’d like, but here’s a default you can use: +- [Running a Validator in Baklava Network](running-a-validator-baklava.md) +- [Running a Validator in Alfajores Network](running-a-validator-alfajores.md) -```bash -mkdir celo-data-dir -cd celo-data-dir -``` +In this documentation pages we're going to use a Docker image containing the Celo node software. -Create two accounts, one for the Validator and one for Validator Group, and get their addresses if you don’t already have them. If you already have your accounts, you can skip this step. +You can use also this [reference script](../../../scripts/run-docker-validator-network.sh) for running the Celo validator stack using Docker containers. -To create your two accounts, run this command twice: +### Obtain and lock up some Celo Gold for staking -```bash -docker run -v $PWD:/root/.celo --entrypoint /bin/sh -it us.gcr.io/celo-testnet/celo-node:alfajores -c "geth account new" -``` +#### Baklava -It will prompt you for a passphrase, ask you to confirm it, and then will output your account address: `Address: {}` +To participate in The Great Celo Stake Off (aka TGCSO) and get fauceted it's necessary to register online via an [online form](https://docs.google.com/forms/d/e/1FAIpQLSfbn5hTJ4UIWpN92-o2qMTUB0UnrFsL0fm97XqGe4VhhN_r5A/viewform). -Let's save these addresses to environment variables, so that you can reference it later (don't include the braces): +#### Alfajores -```bash -export CELO_VALIDATOR_GROUP_ADDRESS= -export CELO_VALIDATOR_ADDRESS= -``` +Visit the [Alfajores Celo Faucet](https://celo.org/build/faucet) to send **both** of your accounts some funds. -In order to register the validator later on, generate a "proof of possession" - a signature proving you know your validator's BLS private key. Run this command: +In a new tab, unlock your accounts so that you can send transactions. This only unlocks the accounts for the lifetime of the Validator that's running, so be sure to unlock `$CELO_VALIDATOR_ADDRESS` again if your node gets restarted: ```bash -docker run -v $PWD:/root/.celo --entrypoint /bin/sh -it us.gcr.io/celo-testnet/celo-node:alfajores -c "geth account proof-of-possession $CELO_VALIDATOR_ADDRESS" +# You will be prompted for your password. +celocli account:unlock --account $CELO_VALIDATOR_GROUP_ADDRESS +celocli account:unlock --account $CELO_VALIDATOR_ADDRESS ``` -It will prompt you for the passphrase you've chosen for the validator account. Let's save the resulting proof-of-possession to an environment variable: +In a new tab, make a locked Gold account for both of your addresses by running the Celo CLI. This will allow you to stake Celo Gold, which is required to register a Validator and Validator Groups: ```bash -export CELO_VALIDATOR_POP= +celocli account:register --from $CELO_VALIDATOR_GROUP_ADDRESS --name +celocli account:register --from $CELO_VALIDATOR_ADDRESS --name ``` -## Deploy the validator node +#### Lock up Celo Gold -Initialize the docker container, building from an image for the network and initializing Celo with the genesis block: +Lock up Celo Gold for both accounts in order to secure the right to register a Validator and Validator Group. The current requirement is 10k Celo Gold to register a validator, and 10k Celo Gold _per member validator_ to register a Validator Group. For Validators, this gold remains locked for approximately 60 days following deregistration. For groups, this gold remains locked for approximately 60 days following the removal of the Nth validator from the group. ```bash -docker run -v $PWD:/root/.celo us.gcr.io/celo-testnet/celo-node:alfajores init /celo/genesis.json +celocli lockedgold:lock --from $CELO_VALIDATOR_GROUP_ADDRESS --value 10000000000000000000000 +celocli lockedgold:lock --from $CELO_VALIDATOR_ADDRESS --value 10000000000000000000000 ``` -To participate in consensus, we need to set up our nodekey for our account. We can do so via the following command \(it will prompt you for your passphrase\): +### Run for election -```bash -docker run -v $PWD:/root/.celo --entrypoint /bin/sh -it us.gcr.io/celo-testnet/celo-node:alfajores -c "geth account set-node-key $CELO_VALIDATOR_ADDRESS" -``` +In order to be elected as a Validator, you will first need to register your group and Validator. Note that when registering a Validator Group, you need to specify a commission, which is the fraction of epoch rewards paid to the group by its members. -In order to allow the node to sync with the network, give it the address of existing nodes in the network: +Register your Validator Group: ```bash -docker run -v $PWD:/root/.celo --entrypoint cp us.gcr.io/celo-testnet/celo-node:alfajores /celo/static-nodes.json /root/.celo/ +celocli validatorgroup:register --from $CELO_VALIDATOR_GROUP_ADDRESS --commission 0.1 ``` -Start up the node: +Register your Validator: ```bash -docker run -p 127.0.0.1:8545:8545 -p 127.0.0.1:8546:8546 -p 30303:30303 -p 30303:30303/udp -v $PWD:/root/.celo us.gcr.io/celo-testnet/celo-node:alfajores --verbosity 3 --networkid 44785 --syncmode full --rpc --rpcaddr 0.0.0.0 --rpcapi eth,net,web3,debug,admin,personal --maxpeers 1100 --mine --etherbase $CELO_VALIDATOR_ADDRESS +celocli validator:register --from $CELO_VALIDATOR_ADDRESS --blsKey $CELO_VALIDATOR_BLS_PUBLIC_KEY --blsPop $CELO_VALIDATOR_BLS_SIGNATURE ``` -{% hint style="danger" %} -**Security**: The command line above includes the parameter `--rpcaddr 0.0.0.0` which makes the Celo Blockchain software listen for incoming RPC requests on all network adaptors. Exercise extreme caution in doing this when running outside Docker, as it means that any unlocked accounts and their funds may be accessed from other machines on the Internet. In the context of running a Docker container on your local machine, this together with the `docker -p` flags allows you to make RPC calls from outside the container, i.e from your local host, but not from outside your machine. Read more about [Docker Networking](https://docs.docker.com/network/network-tutorial-standalone/#use-user-defined-bridge-networks) here. -{% endhint %} - -The `mine` flag will tell geth to try participating in the BFT consensus protocol, which is analogous to mining on the Ethereum PoW network. It will not be allowed to validate until it gets elected -- so next we need to stand for election. - -The `networkid` parameter value of `44785` indicates we are connecting the Alfajores Testnet. - -Now you may need to wait for your node to complete a full sync. You can check on the sync status with `celocli node:synced`. Your node will be fully synced when it has downloaded and processed the latest block, which you can see on the [Alfajores Testnet Stats](https://alfajores-ethstats.celo-testnet.org/) page. - -## Obtain and lock up some Celo Gold for staking - -Visit the [Alfajores Faucet](https://celo.org/build/faucet) to send **both** of your accounts some funds. - -In a new tab, unlock your accounts so that you can send transactions. This only unlocks the accounts for the lifetime of the validator that's running, so be sure to unlock `$CELO_VALIDATOR_ADDRESS` again if your node gets restarted: +Affiliate your Validator with your Validator Group. Note that you will not be a member of this group until the Validator Group accepts you: ```bash -# You will be prompted for your password. -celocli account:unlock --account $CELO_VALIDATOR_GROUP_ADDRESS -celocli account:unlock --account $CELO_VALIDATOR_ADDRESS +celocli validator:affiliate $CELO_VALIDATOR_GROUP_ADDRESS --from $CELO_VALIDATOR_ADDRESS ``` -In a new tab, make a locked Gold account for both of your addresses by running the Celo CLI. This will allow you to stake Celo Gold, which is required to register a validator and validator groups: +Accept the affiliation: ```bash -celocli account:register --from $CELO_VALIDATOR_GROUP_ADDRESS --name -celocli account:register --from $CELO_VALIDATOR_ADDRESS --name +celocli validatorgroup:member --accept $CELO_VALIDATOR_ADDRESS --from $CELO_VALIDATOR_GROUP_ADDRESS ``` -Make a locked Gold commitment for both accounts in order to secure the right to register a validator and validator group. The current requirement is 1 Celo Gold with a notice period of 60 days. If you choose to stake more gold, or a longer notice period, be sure to use those values below: +Use both accounts to vote for your Validator Group: ```bash -celocli lockedgold:lockup --from $CELO_VALIDATOR_GROUP_ADDRESS --goldAmount 1000000000000000000 --noticePeriod 5184000 -celocli lockedgold:lockup --from $CELO_VALIDATOR_ADDRESS --goldAmount 1000000000000000000 --noticePeriod 5184000 +celocli election:vote --from $CELO_VALIDATOR_ADDRESS --for $CELO_VALIDATOR_GROUP_ADDRESS --value 10000000000000000000000 +celocli election:vote --from $CELO_VALIDATOR_GROUP_ADDRESS --for $CELO_VALIDATOR_GROUP_ADDRESS --value 10000000000000000000000 ``` -## Run for election - -In order to be elected as a validator, you will first need to register your group and validator and give them each an an ID, which people will know them by (e.g. `Awesome Validators Inc.` and `Alice's Awesome Validator`). +You’re all set! Note that elections are finalized at the end of each epoch, roughly once an hour in the Alfajores or Baklava Testnets. After that hour, if you get elected, your node will start participating BFT consensus and validating blocks. -Register your validator group: +You can inspect the current state of voting by running: ```bash -celocli validatorgroup:register --id --from $CELO_VALIDATOR_GROUP_ADDRESS --noticePeriod 5184000 +celocli election:list ``` -Register your validator: +If you find your Validator still not getting elected you may need to faucet yourself more funds and lock more gold in order to be able to cast more votes for your Validator Group! + +At any moment you can check the currently elected validators by running the following command: ```bash -celocli validator:register --id --from $CELO_VALIDATOR_ADDRESS --noticePeriod 5184000 --publicKey 0x`openssl rand -hex 64`$CELO_VALIDATOR_POP +celocli election:current ``` -{% hint style="info" %} -**Roadmap**: Note that the “publicKey” first part of the public key field is currently ignored, and thus can be set to any 128 character hex value. The rest is used for the BLS public key and proof-of-possession. -{% endhint %} - -Affiliate your validator with your validator group. Note that you will not be a member of this group until the validator group accepts you: +### Stop Validating -```bash -celocli validator:affiliation --set $CELO_VALIDATOR_GROUP_ADDRESS --from $CELO_VALIDATOR_ADDRESS -``` +If for some reason you need to stop running your Validator, please do one or all of the following so that it will no longer be chosen as a participant in BFT: -Accept the affiliation: +- Deregister your validator: ```bash -celocli validatorgroup:member --accept $CELO_VALIDATOR_ADDRESS --from $CELO_VALIDATOR_GROUP_ADDRESS +celocli validator:deaffiliate --from $CELO_VALIDATOR_ADDRESS +celocli validator:deregister --from $CELO_VALIDATOR_ADDRESS ``` -Use both accounts to vote for your validator group: +- Stop voting for your validator group: ```bash -celocli validatorgroup:vote --from $CELO_VALIDATOR_ADDRESS --for $CELO_VALIDATOR_GROUP_ADDRESS -celocli validatorgroup:vote --from $CELO_VALIDATOR_GROUP_ADDRESS --for $CELO_VALIDATOR_GROUP_ADDRESS +celocli election:revoke --from $CELO_VALIDATOR_ADDRESS --for $CELO_VALIDATOR_GROUP_ADDRESS --value 10000000000000000000000 +celocli election:revoke --from $CELO_VALIDATOR_GROUP_ADDRESS --for $CELO_VALIDATOR_GROUP_ADDRESS --value 10000000000000000000000 ``` -You’re all set! Note that elections are finalized at the end of each epoch, roughly once an hour in the Alfajores Testnet. After that hour, if you get elected, your node will start participating BFT consensus and validating blocks. - -You can inspect the current state of voting by running: +- Deregister your validator group: ```bash -celocli validatorgroup:list +celocli validatorgroup:deregister --from $CELO_VALIDATOR_GORUP_ADDRESS ``` -If you find your validator still not getting elected you may need to faucet yourself more funds and bond a greater deposit to command more voting weight! - {% hint style="info" %} **Roadmap**: Different parameters will govern elections in a Celo production network. Epochs are likely to be daily, rather than hourly. Running a Validator will also include setting up proxy nodes to protect against DDoS attacks, and using hardware wallets to secure the key used to sign blocks. We plan to update these instructions with more details soon. {% endhint %} diff --git a/packages/docs/getting-started/running-attestation-service.md b/packages/docs/getting-started/running-attestation-service.md new file mode 100644 index 00000000000..739e019bba9 --- /dev/null +++ b/packages/docs/getting-started/running-attestation-service.md @@ -0,0 +1,138 @@ +# 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) + +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 URL under which a celo blockchain node is reachable, i.e. something like `https://integration-forno.celo-testnet.org` | | +| ACCOUNT_ADDRESS | The address of the validator account | | +| ATTESTATION_PRIVATE_KEY | The private key with which attestations should be signed. You could use your account key for attestations, but really you should authorize a dedicated attestation key | | +| 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` | | + +## Sms Providers + +Currently the Sms providers supported are Nexmo & Twilio. You can create your user account in the provider of your election using the [Nexmo Sign Up form](https://dashboard.nexmo.com/sign-up) or the [Twilio Sign Up form](https://www.twilio.com/try-twilio). + +### Nexmo + +Here is the list of the enviromnet variables needed to use the Nexmo SMS broker: + +| Variable | Explanation | +| --------------- | --------------------------------------------------------------- | +| NEXMO_KEY | The API key to the Nexmo API | +| NEXMO_SECRET | The API secret to the Nexmo API | +| NEXMO_BLACKLIST | A comma-sperated list of country codes you do not want to serve | + +### Twilio + +If you prefer using Twilio, this is list of the variables to use: + +| Variable | Explanation | +| ---------------------------- | --------------------------------------------------------------- | +| TWILIO_ACCOUNT_SID | The Twilio account ID | +| TWILIO_MESSAGING_SERVICE_SID | The Twilio Message Service ID. Starts by `MG` | +| TWILIO_AUTH_TOKEN | The API authentication token | +| TWILIO_BLACKLIST | A comma-sperated list of country codes you do not want to serve | + +## Accounts Configuration + +First we need to create an account for getting the attestation key needed to sign the attestations. Run: + +```bash +celocli account:new +``` + +We copy the account details and assign the Private Key to the `ATTESTATION_PRIVATE_KEY` environment variable: + +```bash +export ATTESTATION_PRIVATE_KEY=0x +export ATTESTATION_ADDRESS= +``` + +You can create a proof of posession of this attestation key by running the CLI commands (remember to prefix the key with 0x) + +```bash +celocli account:proof-of-possession --signer $ATTESTATION_ADDRESS --account $CELO_VALIDATOR_ADDRESS --privateKey $ATTESTATION_KEY +``` + +That will give you a signature that you can then use to authorize the key: + +```bash +celocli account:authorize --from $CELO_VALIDATOR_ADDRESS -r attestation --pop SIGNATURE --signer $ATTESTATION_ADDRESS +``` + +The Attestation Service needs to connect to a Web3 Provider. This is going to depend on the network you want to connect. So depending on which network you are making available the service, you need to configure the `CELO_PROVIDER` variable pointing to that. + +For example: + +```bash +# Web3 provider for Alfajores network +export CELO_PROVIDER="https://alfajores-forno.celo-testnet.org/" +``` + +#### Database Configuration + +For storing and retrieving the attestation requests the service needs a database to persist that information. Currently `sqlite`, `postgres` and `mysql` are supported. For testing purposes you can use `sqlite` but it's recommended to run a stand-alone database server using `mysql` or `postgres` if your intention is running the Attestation Service in a production environment. + +So for specifying the database url you need to setup the `DATABASE_URL` variable: + +```bash +export DATABASE_URL="sqlite://db/dev.db" +export DATABASE_URL="mysql://user:password@mysql.example.com:3306/attestation-service" +export DATABASE_URL="postgres://user:password@postgres.example.com:5432/attestation-service" +``` + +You can find the migration scripts for creating the schema at the `celo-monorepo`, `packages/attestation-service` folder. From there, after setting up the `DATABASE_URL` env variable you can run the following commands: + +```bash +yarn run db:create +yarn run db:migrate +``` + +## Executing the Attestation Service + +The following command for running the Attestation Service is using Nexmo, but you can adapt for using Twilio easily: + +```bash +docker run -e ATTESTATION_KEY=$ATTESTATION_KEY -e ACCOUNT_ADDRESS=$CELO_VALIDATOR_ADDRESS -e CELO_PROVIDER=$CELO_PROVIDER -e DATABASE_URL=$DATABASE_URL -e SMS_PROVIDERS=nexmo -e NEXMO_KEY=$NEXMO_KEY -e NEXMO_SECRET=$NEXMO_SECRET -e NEXMO_BLACKLIST=$NEXMO_BLACKLIST -p 3000:80 us.gcr.io/celo-testnet/attestation-service:$CELO_NETWORK +``` + +In order for users to request attestations from your service, you need to register the endpoint under which your service is reachable in your [metadata](/celo-codebase/protocol/identity/metadata). + +```bash +celocli identity:create-metadata ./metadata.json +``` + +The `ATTESTATION_SERVICE_URL` variable stores the URL to access the Attestation Service deployed. In the following command we specify the URL where this Attestation Service is: + +```bash +celocli identity:change-attestation-service-url ./metadata.json --url $ATTESTATION_SERVICE_URL +``` + +And then host your metadata somewhere reachable via HTTP. You can register your metadata URL with: + +```bash +celocli identity:register-metadata --url --from $CELO_VALIDATOR_ADDRESS +``` + +You can use for testing a gist url (i.e: `https://gist.github.com/john.doe/a29f83d478c9daa2ac52596ba9778391`) or similar where you have publicly available your metadata. + +If everything goes well users should see that you are ready for attestations by running: + +```bash +celocli identity:get-metadata $CELO_VALIDATOR_ADDRESS +``` diff --git a/packages/docs/getting-started/using-the-cli.md b/packages/docs/getting-started/using-the-cli.md deleted file mode 100644 index 7185cb2452e..00000000000 --- a/packages/docs/getting-started/using-the-cli.md +++ /dev/null @@ -1,23 +0,0 @@ -# Using the CLI - -This section describes how to make a transaction using the Celo CLI. Doing so is easy and quick once you have fauceted yourself some funds and have a full node running. - -### **Prerequisites** - -- **You have Docker installed.** If you don’t have it already, follow the instructions here: [Get Started with Docker](https://www.docker.com/get-started). It will involve creating or signing in with a Docker account, downloading a desktop app, and then launching the app to be able to use the Docker CLI. If you are running on a Linux server, follow the instructions for your distro [here](https://docs.docker.com/install/#server). You may be required to run Docker with sudo depending on your installation environment. -- **You have celocli installed.** - - See to [Command Line Interface \(CLI\)](../command-line-interface/introduction.md) for instructions on how to get set up. - -- **You have a full node running.** See the [Running a Full Node](running-a-full-node.md) instructions for more details on running a full node. -- **You have fauceted yourself.** See the [Faucet](faucet.md) instructions for help funding your account with testnet tokens. - -### **Sending a payment** - -Unlock your accounts so that you can send transactions: - -`$ celocli account:unlock --account $YOUR_ADDRESS --password ` - -Send a payment to another account: - -`$ celocli account:transferdollar --from $YOUR_ADDRESS --amountInWei $AMOUNT --to $DESTINATION_ADDRESS` diff --git a/scripts/run-docker-validator-network.sh b/scripts/run-docker-validator-network.sh new file mode 100755 index 00000000000..7aaba350b8b --- /dev/null +++ b/scripts/run-docker-validator-network.sh @@ -0,0 +1,200 @@ +#!/usr/bin/bash +set -euo pipefail + +export LC_ALL=en_US.UTF-8 + +# Usage: run-network.sh +COMMAND=${1:-"pull,accounts,deploy,run-validator,status"} +DATA_DIR=${2:-"/tmp/celo/network"} +export CELO_IMAGE=${3:-"us.gcr.io/celo-testnet/geth@sha256:4bc97381db0bb81b7a3e473bb61d447c90be165834316d3f75bc34d7db718b39"} +export NETWORK_ID=${4:-"1101"} +export NETWORK_NAME=${5:-"integration"} +export DEFAULT_PASSWORD=${6:-"1234"} +export CELO_IMAGE_ATTESTATION=${7:-"us.gcr.io/celo-testnet/celo-monorepo@sha256:3e958851e4a89e39eeefcc56e324d9ee0d09286a36cb63c285195183fe4dc4ee"} +export CELO_PROVIDER=${8:-"https://integration-forno.celo-testnet.org/"} # https://berlintestnet001-forno.celo-networks-dev.org/ +export DATABASE_URL=${9:-"sqlite://db/dev.db"} + +export NEXMO_KEY="xx" +export NEXMO_SECRET="xx" +export NEXMO_BLACKLIST="" + + +VALIDATOR_DIR="${DATA_DIR}/validator" +PROXY_DIR="${DATA_DIR}/proxy" +mkdir -p $DATA_DIR +mkdir -p $VALIDATOR_DIR +mkdir -p $PROXY_DIR +__PWD=$PWD + + +#### Internal functions +remove_containers () { + echo -e "\tRemoving previous celo-proxy and celo-validator containers" + docker rm -f celo-proxy celo-validator celo-attestation-service || echo -e "Containers removed" +} + +download_genesis () { + echo -e "\tDownload genesis.json and static-nodes.json to the container" + docker run -v $PWD/proxy:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "wget https://www.googleapis.com/storage/v1/b/static_nodes/o/$NETWORK_NAME?alt=media -O /root/.celo/static-nodes.json" + docker run -v $PWD/proxy:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "wget https://www.googleapis.com/storage/v1/b/genesis_blocks/o/$NETWORK_NAME?alt=media -O /root/.celo/genesis.json" + + docker run -v $PWD/validator:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "wget https://www.googleapis.com/storage/v1/b/static_nodes/o/$NETWORK_NAME?alt=media -O /root/.celo/static-nodes.json" + docker run -v $PWD/validator:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "wget https://www.googleapis.com/storage/v1/b/genesis_blocks/o/$NETWORK_NAME?alt=media -O /root/.celo/genesis.json" + +} + +make_status_requests () { + echo -e "Checking Proxy and Validator state:" + + echo -n "* Proxy eth_blockNumber:" + curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' -H "Content-Type: application/json" localhost:8545 + + echo -n "* Validator net_peerCount:" + curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":74}' -H "Content-Type: application/json" localhost:8547 + + echo -n "* Validator eth_mining:" + curl -X POST --data '{"jsonrpc":"2.0","method":"eth_mining","params":[],"id":1}' -H "Content-Type: application/json" localhost:8547 + echo -e "" + +} + +#### Main + +if [[ $COMMAND == *"help"* ]]; then + + echo -e "Script for running a local validator network using docker containers. This script runs:" + echo -e "\t - A Validator node" + echo -e "\t - A Proxy node" + echo -e "\t - An attestation service\n" + + echo -e "Options:" + echo -e "$0 " + echo -e "\t - Command; comma separated list of actions to execute. Options are: help, pull, clean, accounts, deploy, run-validator, run-attestation, status. Default: pull,accounts,deploy,run-validator,status" + echo -e "\t - Data Dir; Local folder where will be created the data dir for the nodes. Default: /tmp/celo/network" + echo -e "\t - Celo Image; Image to download" + echo -e "\t - Celo Network; Docker image network to use (typically alfajores or baklava, but you can use a commit). " + echo -e "\t - Network Id; 1101 for integration, 44785 for alfajores, etc." + echo -e "\t - Network Name; integration by default" + echo -e "\t - Password; Password to use during the creation of accounts" + + echo -e "\nExamples:" + echo -e "$0 pull,clean,deploy,run-validator " + echo -e "$0 deploy,run-validator /tmp/celo/network" + + echo -e "\n" + exit 0 +fi + +if [[ $COMMAND == *"pull"* ]]; then + + echo -e "* Downloading docker image: $CELO_IMAGE" + docker pull $CELO_IMAGE + +fi + + +if [[ $COMMAND == *"clean"* ]]; then + + echo -e "* Removing data dir $DATA_DIR" + rm -rf $DATA_DIR + mkdir -p $DATA_DIR + mkdir -p $VALIDATOR_DIR + mkdir -p $PROXY_DIR +fi + + +if [[ $COMMAND == *"accounts"* ]]; then + + echo -e "* Creating addresses ..." + cd $DATA_DIR + + export CELO_VALIDATOR_ADDRESS=$(docker run -v $PWD/validator:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c " printf '%s\n' $DEFAULT_PASSWORD $DEFAULT_PASSWORD | geth account new " |tail -1| cut -d'{' -f 2| tr -cd "[:alnum:]\n" ) + export CELO_VALIDATOR_GROUP_ADDRESS=$(docker run -v $PWD/validator:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c " printf '%s\n' $DEFAULT_PASSWORD $DEFAULT_PASSWORD | geth account new " |tail -1| cut -d'{' -f 2| tr -cd "[:alnum:]\n" ) + export CELO_PROXY_ADDRESS=$(docker run -v $PWD/proxy:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c " printf '%s\n' $DEFAULT_PASSWORD $DEFAULT_PASSWORD | geth account new " |tail -1| cut -d'{' -f 2| tr -cd "[:alnum:]\n" ) + + echo -e "\tCELO_VALIDATOR_ADDRESS=$CELO_VALIDATOR_ADDRESS" + echo -e "\tCELO_VALIDATOR_GROUP_ADDRESS=$CELO_VALIDATOR_ADDRESS" + echo -e "\tCELO_PROXY_ADDRESS=$CELO_VALIDATOR_ADDRESS" + + export CELO_VALIDATOR_POP=$(docker run -v $PWD/validator:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c " printf '%s\n' $DEFAULT_PASSWORD | geth account proof-of-possession $CELO_VALIDATOR_ADDRESS "| tail -1| cut -d' ' -f 3| tr -cd "[:alnum:]\n" ) + + echo -e "\tCELO_VALIDATOR_POP=$CELO_VALIDATOR_POP" + +fi + +if [[ $COMMAND == *"deploy"* ]]; then + + echo -e "* Deploying ..." + cd $DATA_DIR + + download_genesis + echo -e "\tInitializing using genesis" + docker run -v $PWD/proxy:/root/.celo $CELO_IMAGE init /root/.celo/genesis.json + docker run -v $PWD/validator:/root/.celo $CELO_IMAGE init /root/.celo/genesis.json + + echo -e "\tSetting up nodekey" + docker run -v $PWD/proxy:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "printf '%s\n' $DEFAULT_PASSWORD | geth account set-node-key $CELO_PROXY_ADDRESS" + docker run -v $PWD/validator:/root/.celo --entrypoint /bin/sh -it $CELO_IMAGE -c "printf '%s\n' $DEFAULT_PASSWORD | geth account set-node-key $CELO_VALIDATOR_ADDRESS" + +fi + + +if [[ $COMMAND == *"run-validator"* ]]; then + + echo -e "* Let's run the validator network ..." + cd $DATA_DIR + + remove_containers + echo -e "\tStarting the Proxy" + screen -S celo-proxy -d -m docker run --name celo-proxy --restart always -p 8545:8545 -p 8546:8546 -p 30303:30303 -p 30303:30303/udp -p 30503:30503 -p 30503:30503/udp -v $PWD/proxy:/root/.celo $CELO_IMAGE --verbosity 3 --networkid $NETWORK_ID --syncmode full --rpc --rpcaddr 0.0.0.0 --rpcapi eth,net,web3,debug --maxpeers 1100 --etherbase=$CELO_PROXY_ADDRESS --proxy.proxy --proxy.proxiedvalidatoraddress $CELO_VALIDATOR_ADDRESS --proxy.internalendpoint :30503 + + sleep 10s + + export PROXY_ENODE=$(docker exec celo-proxy geth --exec "admin.nodeInfo['enode'].split('//')[1].split('@')[0]" attach | tr -d '"') + export PROXY_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' celo-proxy) + echo -e "\tProxy running: enode://$PROXY_ENODE@$PROXY_IP" + + echo -e "\tStarting Validator node" + docker run -v $PWD/validator:/root/.celo --entrypoint sh --rm $CELO_IMAGE -c "echo $DEFAULT_PASSWORD > /root/.celo/.password" + screen -S celo-validator -d -m docker run --name celo-validator --restart always -p 127.0.0.1:8547:8545 -p 127.0.0.1:8548:8546 -p 30304:30303 -p 30304:30303/udp -v $PWD/validator:/root/.celo $CELO_IMAGE --verbosity 3 --networkid $NETWORK_ID --syncmode full --rpc --rpcaddr 0.0.0.0 --rpcapi eth,net,web3,debug --maxpeers 125 --mine --istanbul.blockperiod=5 --istanbul.requesttimeout=3000 --etherbase $CELO_VALIDATOR_ADDRESS --nodiscover --proxy.proxied --proxy.proxyenodeurlpair=enode://$PROXY_ENODE@$PROXY_IP:30503\;enode://$PROXY_ENODE@$PROXY_IP:30503 --unlock=$CELO_VALIDATOR_ADDRESS --password /root/.celo/.password + + sleep 5s + + echo -e "\tEverything should be running, you can check running 'screen -ls'" + screen -ls + + echo -e "\tYou can re-attach to the proxy or the validator running:" + echo -e "\t 'screen -r -S celo-proxy' or 'screen -r -S celo-validator'\n" + +fi + +if [[ $COMMAND == *"run-attestation"* ]]; then + + echo -e "* Let's run the attestation service ..." + + echo -e "\tPulling docker image: $CELO_IMAGE_ATTESTATION" + docker pull $CELO_IMAGE_ATTESTATION + + export ATTESTATION_KEY=$(celocli account:new| tail -3| head -1| cut -d' ' -f 2| tr -cd "[:alnum:]\n") + echo -e "\tATTESTATION_KEY=$ATTESTATION_KEY" + + screen -S attestation-service -d -m docker run --name celo-attestation-service --restart always -e ATTESTATION_KEY=$ATTESTATION_KEY -e ACCOUNT_ADDRESS=$CELO_VALIDATOR_ADDRESS -e CELO_PROVIDER=$CELO_PROVIDER -e DATABASE_URL=$DATABASE_URL -e SMS_PROVIDERS=nexmo -e NEXMO_KEY=$NEXMO_KEY -e NEXMO_SECRET=$NEXMO_SECRET -e NEXMO_BLACKLIST=$NEXMO_BLACKLIST -p 3000:80 $CELO_IMAGE_ATTESTATION + + echo -e "\tAttestation service should be running, you can check running 'screen -ls'" + echo -e "\tYou can re-attach to the attestation-service running:" + echo -e "\t 'screen -r -S celo-attestation-service'\n" + +fi + +if [[ $COMMAND == *"status"* ]]; then + + make_status_requests + +fi + +cd $__PWD + + + + +