From d09b32182a7627bb6b4c9e90e8e64887d83d6437 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Tue, 23 May 2023 11:39:20 +0200 Subject: [PATCH] feat(docs): Add User's guide --- .markdownlint.yml | 15 +- README.md | 14 +- docs/README.md | 45 ++++ docs/account.md | 610 ++++++++++++++++++++++++++++++++++++++++++++ docs/addressbook.md | 86 +++++++ docs/network.md | 306 ++++++++++++++++++++++ docs/paratime.md | 203 +++++++++++++++ docs/setup.md | 78 ++++++ docs/transaction.md | 128 ++++++++++ docs/wallet.md | 405 +++++++++++++++++++++++++++++ examples/README.md | 4 +- 11 files changed, 1886 insertions(+), 8 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/account.md create mode 100644 docs/addressbook.md create mode 100644 docs/network.md create mode 100644 docs/paratime.md create mode 100644 docs/setup.md create mode 100644 docs/transaction.md create mode 100644 docs/wallet.md diff --git a/.markdownlint.yml b/.markdownlint.yml index ffdbd7e4..f993a52d 100644 --- a/.markdownlint.yml +++ b/.markdownlint.yml @@ -10,8 +10,19 @@ line-length: # Line length checking is not strict by default. strict: true line_length: 80 - # Allow longer lines for code blocks. - code_block_line_length: 100 + # Code blocks for examples are imported directly from the command output + # and do not have sensible max line length. + code_blocks: false + +# Front matter title (shown in the menu and doccards) may differ from the one +# on the actual page. +single-title: + front_matter_title: "" + +# Docusaurus uses custom {#some-title} syntax to define fragments (anchors), see: +# https://docusaurus.io/docs/next/markdown-features/toc#heading-ids +# Unfortunately, it is not compatible with the markdown linter yet. +link-fragments: false # Do not always require language specifiers with fenced code blocks since they # are not part of the Markdown spec. diff --git a/README.md b/README.md index 9e652576..baab28b8 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ in your `$PATH`. *NOTE: The rest of the README assumes the `oasis` binary is somewhere in your `$PATH`.* -## Running +## Quickstart You can interact with the Oasis CLI by invoking it from the command line as follows: @@ -57,7 +57,7 @@ subcommand as follows: ```bash oasis network set-default testnet -oasis paratime set-default testnet emerald +oasis paratime set-default testnet sapphire ``` To be able to sign transactions you will need to first create or import an @@ -82,7 +82,13 @@ To show the account's balance on the default network/ParaTime, run: oasis account show ``` +The `account` command also allows you to transfer tokens, deposit or withdraw to +and from ParaTimes, delegate your assets to validators etc. + +Check out the complete User's guide in [docs/README.md] and example invocations +of the CLI in `examples` folder to learn more. + ## Configuration -All configuration is stored in the `$XDG_CONFIG_HOME/oasis` directory (defaults -to `$HOME/.config/oasis`). +All configuration is stored in the `$XDG_CONFIG_HOME/oasis` directory (e.g. +`$HOME/.config/oasis` on Linux). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..8ce6a0a2 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,45 @@ +--- +title: Oasis CLI +description: Powerful CLI for managing Oasis network, nodes, tokens and dapps +--- + +# Oasis Command Line Interface + +Oasis command-line interface (CLI) is a powerful all-in-one tool for +interacting with the Oasis Network. You can download the latest release +binaries from the [GitHub repository]. + +It boasts a number of handy features: + +- Flexible setup: + - supports Mainnet, Testnet, Localnet or any other Oasis network deployment + - consensus layer configuration with arbitrary token + - configuration of custom ParaTimes with arbitrary token + - connecting to remote (via TCP/IP) or local (Unix socket) Oasis node + instance +- Powerful wallet features: + - standard token operations (transfers, allowances, deposits, withdrawals and + balance queries) + - file-based wallet with password protection + - full Ledger hardware wallet support + - address book + - generation, signing and submitting transactions in non-interactive + (headless) mode + - offline transaction generation for air-gapped machines + - transaction encryption with X25519-Deoxys-II envelope + - support for Ed25519, Ethereum-compatible Secp256k1 and Sr25519 signature + schemes + - raw, BIP-44, ADR-8 and Ledger's legacy derivation paths +- Node operator features: + - Oasis node inspection and healthchecks + - network governance transactions + - staking reward schedule transactions +- Developer features: + - built-in testing accounts compatible with the Oasis test runner, the Oasis + CI and the official sapphire-dev and emerald-dev Docker images + - Oasis Wasm smart contract code deployment, instantiation, management and + calls + - debugging tools for deployed Wasm contracts + - inspection of blocks, transactions, results and events + +[GitHub repository]: https://github.com/oasisprotocol/cli/releases diff --git a/docs/account.md b/docs/account.md new file mode 100644 index 00000000..16fe6d25 --- /dev/null +++ b/docs/account.md @@ -0,0 +1,610 @@ +--- +title: Account +description: Using CLI for performing account-related tasks +--- + +# Account-related Tasks + +The `account` command is the home for most consensus and ParaTime-layer +on-chain transactions that are signed with one of your accounts such as: + +- getting the account balance including delegated assets, +- sending tokens, +- delegating or undelegating tokens to or from validators (*staking*), +- depositing and withdrawing tokens to or from a ParaTime, +- managing withdrawal beneficiaries of your accounts, +- validator utils such as entity registration, setting the commission schedule, + unfreezing your node and similar. + +## Network, ParaTime and Account Selectors {#npa} + +Before we dig into `account` subcommands, let's look at the three most common +selectors. + +### Network + +The `--network ` parameter specifies the [network] which the +Oasis CLI should connect to. + +For example: + +![code shell](../examples/account/show-testnet.in) + +![code](../examples/account/show-testnet.out) + +![code shell](../examples/account/show-mainnet.in) + +![code](../examples/account/show-mainnet.out) + +### ParaTime + +The `--paratime ` sets which [ParaTime] Oasis CLI should use. +If you do not want to use any ParaTime, for example to perform a consensus +layer operation, pass the `--no-paratime` flag explicitly. + +![code shell](../examples/account/show-no-paratime.in) + +![code](../examples/account/show-no-paratime.out) + +### Account + +The `--account ` specifies which account in your wallet the +Oasis CLI should use to sign the transaction with. + +![code shell](../examples/account/transfer-eth.y.in) + +![code](../examples/account/transfer-eth.y.out) + +![code shell](../examples/account/transfer-eth2.y.in) + +![code](../examples/account/transfer-eth2.y.out) + +:::tip + +You can also set **the default [network][network-set-default], +[ParaTime][paratime-set-default] or [account][wallet-set-default] to use**, if +no network, ParaTime or account selectors are provided. + +::: + +[network]: ./network.md +[paratime]: ./paratime.md +[network-set-default]: ./network.md#set-default +[paratime-set-default]: ./paratime.md#set-default +[wallet-set-default]: ./wallet.md#set-default + +## Show the Balance of an Account {#show} + +The `account show [address]` command prints the balance, delegated assets +and other validator information corresponding to: + +- a given address, +- the name of the [address book entry] or +- the name of one of the accounts in your wallet. + +The address is looked up both on the consensus layer and the ParaTime, if +selected. + +Running the command without arguments will show you the balance +of your default account on the default network and ParaTime: + +![code shell](../examples/account/show.in) + +![code](../examples/account/show.out) + +You can also pass the name of the account in your wallet or the name stored in +your address book: + +![code shell](../examples/account/show-named.in) + +![code](../examples/account/show-named.out) + +Or, you can check the balance of an arbitrary account address by passing the +native or Ethereum-compatible addresses. + +![code shell](../examples/account/show-oasis.in) + +![code](../examples/account/show-oasis.out) + +![code shell](../examples/account/show-eth.in) + +![code](../examples/account/show-eth.out) + +To also include any staked assets in the balance, pass the `--show-delegations` +flag. For example: + +![code shell](../examples/account/show-delegations.in.static) + +![code](../examples/account/show-delegations.out.static) + +Let's look more closely at the figures above. The account's **nonce** is the +incremental number starting from 0 that must be unique for each account's +transaction. In our case, the nonce is 32. This means there have been that many +transactions made with this account as the source. The next transaction should +have nonce equal to 32. + +We can see that the total account's **balance** on the consensus layer is \~973 +tokens: + +- \~951 tokens can immediately be transferred. +- \~16.3 tokens (15,000,000,0000 shares) are staked (delegated). +- \~5.4 tokens are debonding and will be available for spending in the epoch + 26558. +- up to \~270 tokens are [allowed](#allow) to be transferred to accounts + `oasis1qqczuf3x6glkgjuf0xgtcpjjw95r3crf7y2323xd` and + `oasis1qrydpazemvuwtnp3efm7vmfvg3tde044qg6cxwzx` without the signature of the + account above. + +Separately, you can notice there are \~7 tokens currently [deposited](#deposit) +in Sapphire. + +:::info + +The `--show-delegations` flag is not enabled by default, because account +delegations are not indexed on-chain. This means that the endpoint needs +to scan block by block to retrieve this information and takes some time +often leading to the timeout on public endpoints due to denial-of-service +protection. + +::: + +Next, let's look at how the account of a validator typically looks like. For +example: + +![code shell](../examples/account/show-delegations-validator.in.static) + +![code](../examples/account/show-delegations-validator.out.static) + +We can see there is a total of \~1833 tokens delegated to this validator. One +delegation was done by the account itself and then there are five more +delegators. Sometimes, we also refer to accounts with delegated assets to it as +*escrow accounts*. + +Next, we can see a *commission schedule*. A validator can charge commission for +tokens that are delegated to it in form of the commission schedule **rate +steps** (7%, 11%, 14% and 18% activated on epochs 15883, 15994, 16000 and 16134 +respectively) and the commission schedule **rate bound steps** (0-10% on +epoch 15883 and then 0-20% activated on epoch 15993). For more details, see the +[account amend-commission-schedule](./account#amend-commission-schedule) +command. + +An escrow account may also accumulate one or more **stake claims** as seen +above. The network ensures that all claims are satisfied at any given point. +Adding a new claim is only possible if **all of the existing claims plus the +new claim can be satisfied**. + +We can observe that the stake accumulator currently has the following claims: + +- The `registry.RegisterEntity` claim is for registering an entity. It needs to + satisfy the global threshold for + [registering the `entity`][show-native-token]. + +- The `registry.RegisterNode.LAdHWnCkjFR5NUkFHVpfGuKFfZW1Cqjzu6wTFY6v2JI=` + claim is for registering the validator node with the public key + `LAdHWnCkjFR5NUkFHVpfGuKFfZW1Cqjzu6wTFY6v2JI=`. The claim needs to satisfy the + [`node-validator`][show-native-token] global staking threshold parameter. + +- The `registry.RegisterNode.xk58fx5ys6CSO33ngMQkgOL5UUHSgOSt0QbqWGGuEF8=` + claim is for registering the three compute nodes with the public key + `xk58fx5ys6CSO33ngMQkgOL5UUHSgOSt0QbqWGGuEF8==`. The claim needs to satisfy + three [`node-compute`][show-native-token] global staking threshold parameters. + +For more details on registering entities, nodes and ParaTimes, see the +[Oasis Core Registry service][oasis-core-registry]. + +[address book entry]: ./addressbook.md +[show-native-token]: ./network#show-native-token + +:::info + +[Network and ParaTime](#npa) selectors are available for the +`account show` command. + +::: + +## Transfer {#transfer} + +Use `account transfer ` command to transfer funds between two +accounts on the consensus layer or between two accounts inside the same +ParaTime. + +The following command will perform a token transfer inside default ParaTime: + +![code shell](../examples/account/transfer-named.y.in) + +![code](../examples/account/transfer-named.y.out) + +Consensus layer token transfers: + +![code shell](../examples/account/transfer-named-no-paratime.y.in) + +![code](../examples/account/transfer-named-no-paratime.y.out) + +:::info + +[Network, ParaTime and account](#npa) selectors are available for the +`account transfer` command. + +::: + +## Allowance {#allow} + +`account allow ` command makes your funds withdrawable by +a 3rd party beneficiary at consensus layer. For example, instead of paying your +partner for a service directly, you can ask for their address and enable +**them** to withdraw the amount which you agreed on from your account. This is a +similar mechanism to how payment checks were used in the past. + +![code shell](../examples/account/allow.y.in) + +![code](../examples/account/allow.y.out) + +The allowance command uses relative amount. For example, if your run the +above command 3 times, Logan will be allowed to withdraw 30 ROSE. + +:::tip + +To reduce the allowed amount or completely **disallow** the withdrawal, use the +negative amount. To avoid flag ambiguity in the shell, you will first need to +pass all desired flags and parameters except the negative amount, then append +`--` to mark the end of options, and finally append the negative amount. + +![code shell](../examples/account/allow-negative.in.static) + +![code](../examples/account/allow-negative.out.static) + +::: + +The allowance transaction is also required if you want to deposit funds from +your consensus account to a ParaTime. The ParaTime will **withdraw** the amount +from your consensus account and fund your ParaTime account with the same +amount deducted by the deposit fee. Oasis CLI can derive the address of the +ParaTime beneficiary, if you use `paratime:` as the beneficiary +address. + +![code shell](../examples/account/allow-paratime.y.in) + +![code](../examples/account/allow-paratime.y.out) + +:::info + +[Network and account](#npa) selectors are available for the `account allow` +command. + +::: + +## Deposit Tokens to a ParaTime {#deposit} + +`account deposit [address]` will deposit funds from your consensus +account to the target address inside the selected ParaTime. + +![code shell](../examples/account/deposit-named.y.in) + +![code](../examples/account/deposit-named.y.out) + +If no address is provided, the deposit will be made to the address +corresponding to your consensus account inside the ParaTime. + +![code shell](../examples/account/deposit.y.in) + +![code](../examples/account/deposit.y.out) + +Currently, deposit transactions are free of charge, hence the `--gas-price 0` +parameter to avoid spending unnecessary gas fees. Also, keep in +mind that **deposit and withdrawal fees are always paid by your ParaTime +account.** If it doesn't contain any ROSE, you will not able to cover the fees. + +You can also make a deposit to an account with arbitrary address inside a +ParaTime. For example, let's deposit to some native address inside the +ParaTime: + +![code shell](../examples/account/deposit-oasis.y.in) + +![code](../examples/account/deposit-oasis.y.out) + +Or to some address in the Ethereum format: + +![code shell](../examples/account/deposit-eth.y.in) + +![code](../examples/account/deposit-eth.y.out) + +:::info + +[Network, ParaTime and account](#npa) selectors are available for the +`account deposit` command. + +::: + +## Withdraw Tokens from the ParaTime {#withdraw} + +`account withdraw [to]` will withdraw funds from your ParaTime account +to a consensus address: + +![code shell](../examples/account/withdraw-named.y.in) + +![code](../examples/account/withdraw-named.y.out) + +If the address is not provided, the address of the account inside ParaTime will +be used as a consensus address: + +![code shell](../examples/account/withdraw.y.in) + +![code](../examples/account/withdraw.y.out) + +:::caution + +Withdrawal transactions are not free of charge and the fee will be deducted +**from your ParaTime balance**. + +::: + +Similar to the [`account deposit`](#deposit) command, you can also specify an +arbitrary Oasis address which you want to withdraw your tokens to. + +![code shell](../examples/account/withdraw-oasis.y.in) + +![code](../examples/account/withdraw-oasis.y.out) + +:::caution + +You cannot use the destination address of your `secp256k1` account or any other +Ethereum-formatted address for the withdrawal, because this signature scheme is +not supported on the consensus layer! + +::: + +:::info + +[Network, ParaTime and account](#npa) selectors are available for the +`account withdraw` command. + +::: + +## Delegate Tokens to a Validator {#delegate} + +To stake your tokens on the consensus layer, run +`account delegate `. This will delegate the specified amount of +tokens to a validator. + +![code shell](../examples/account/delegate.y.in) + +![code](../examples/account/delegate.y.out) + +Once your tokens are staked, they are converted into *shares* since the number +of tokens may change over time based on the +[staking reward schedule][token-metrics] or if your validator is subject to +[slashing]. The number of shares on the other hand will remain constant. Also, +shares are always interpreted as a whole number, whereas the amount of tokens is +usually a rational number and may lead to rounding errors when managing your +delegations. + +To find out how many shares did you delegate, run [`account show`](#show) and +look for the `shares` under the active delegations section: + +:::info + +[Network, ParaTime and account](#npa) selectors are available for the +`account delegate` command. + +::: + +[token-metrics]: https://github.com/oasisprotocol/docs/blob/main/docs/general/oasis-network/token-metrics-and-distribution.mdx#staking-incentives +[slashing]: https://github.com/oasisprotocol/docs/blob/main/docs/general/manage-tokens/terminology.md#slashing + +## Undelegate Tokens from the Validator {#undelegate} + +To reclaim your delegated assets, use `account undelegate `. You +will need to specify the **number of shares instead of tokens** and the +validator address you want to reclaim your assets from. + +![code shell](../examples/account/undelegate.y.in) + +![code](../examples/account/undelegate.y.out) + +After submitting the transaction, a [debonding period] will +commence. After the period has passed, the network will automatically move your +assets back to your account. Note that during the debonding period, your +assets may still be [slashed][slashing]. + +:::info + +[Network, ParaTime and account](#npa) selectors are available for the +`account undelegate` command. + +::: + +[debonding period]: ./network.md#show + +## Advanced + +### Public Key to Address {#from-public-key} + +`account from-public-key ` converts the Base64-encoded public key +to the [Oasis native address](../terminology.md#address). + +![code shell](../examples/account/from-public-key.in) + +![code](../examples/account/from-public-key.out) + +This command is most often used by the network validators for converting the +public key of their entity to a corresponding address. You can find your +entity's ID in the `id` field of the `entity.json` file. + +:::tip + +Oasis consensus transactions hold the public key of the signer instead of their +*from* address. This command can be used for debugging to determine the +signer's staking address on the network. + +::: + +### Non-Interactive Mode {#y} + +Add `-y` flag to any operation, if you want to use Oasis CLI in +non-interactive mode. This will answer "yes to all" for yes/no questions +and for all other prompts it will keep the proposed default values. + +### Output Transaction to File {#output-file} + +You can use `--output-file ` parameter to save a transaction to +a JSON file instead of immediately broadcasting it to the network. Afterwards, +use the [`transaction`] command to verify and submit the transaction. + +[`transaction`]: ./transaction.md + +### Do Not Sign the Transaction {#unsigned} + +If you wish to *prepare* a transaction to be signed by a specific account in +the future, use the `--unsigned` flag. This will cause Oasis CLI to skip the +signing and broadcasting steps. The transaction will be printed to the +standard output instead. + +You can also use [`--output-file`] to store the transaction to a file. This +setup is ideal when you want to sign a transaction with the +[offline/air-gapped machine] machine: + +1. First, generate an unsigned transaction on a networked machine, +2. copy it over to an air-gapped machine, +3. [sign it][transaction-sign] on the air-gapped machine, +4. copy it over to the networked machine, +5. [broadcast the transaction][transaction-submit] on the networked machine. + +[`--output-file`]: #output-file +[transaction-sign]: ./transaction.md#sign +[transaction-submit]: ./transaction.md#submit +[offline/air-gapped machine]: https://en.wikipedia.org/wiki/Air_gap_\(networking\) + +### Offline Mode {#offline} + +To generate a transaction without accessing the network and also without +broadcasting it, add `--offline` flag. In this case Oasis CLI will require that +you provide all necessary transaction details (e.g. [account nonce](#nonce), +[gas limit](#gas-limit), [gas price](#gas-price)) which would otherwise be +automatically obtained from the network. Oasis CLI will print the transaction to +the standard output for you to examine. Use [`--output-file`](#output-file), if +you wish to save the transaction to the file and submit it to the network +afterwards by using the [`transaction submit`][transaction-submit] command. + +### Account's Nonce {#nonce} + +`--nonce ` will override the detection of the account's nonce used +to sign the transaction with the specified one. + +### Gas Price {#gas-price} + +`--gas-price ` sets the transaction's price per gas unit in +base units. + +### Gas Limit {#gas-limit} + +`--gas-limit ` sets the maximum amount of gas that can be spend by the +transaction. + +### Entity Management {#entity} + +#### Register your Entity {#entity-register} + +In order for validators to become part of the validator set and/or the compute +committee, they first need to register as an entity inside the network's +registry. Use the `account entity register ` command to register +your entity and provide a JSON file with the Entity descriptor. You can use the +[`network show`][network-show-id-entities] command to see existing entities and +then examine specific ones to see how entity descriptors of the currently +registered entities look like. + +[network-show-id-entities]: ./network.md#show-id-entities +[oasis-core-registry]: https://github.com/oasisprotocol/oasis-core/blob/master/docs/consensus/services/registry.md#entities-and-nodes + +![code shell](../examples/account/entity-register.y.in) + +![code](../examples/account/entity-register.y.out) + +:::info + +[Network and account](#npa) selectors are available for the +`account entity register` command. + +::: + +#### Deregister Your Entity {#entity-deregister} + +To remove an entity from the network's registry, invoke +`account entity deregister`. No additional arguments are required since each +account can only deregister their own entity, if one exists in the registry. + +![code shell](../examples/account/entity-deregister.y.in) + +![code](../examples/account/entity-deregister.y.out) + +:::info + +[Network and account](#npa) selectors are available for the +`account entity deregister` command. + +::: + +### Change Your Commission Schedule {#amend-commission-schedule} + +Validators can use `account amend-commission-schedule` to add or remove +their commission bounds and rates at consensus layer. Rate bounds can be +defined by using the `--bounds //` parameter. +Actual rates which can be subject to change every epoch can be defined with the +`--rates /` parameter. Rates are specified in milipercents +(100% = 100000m%). The new commission schedule will replace any previous +schedules. + +![code shell](../examples/account/amend-commission-schedule.y.in) + +![code](../examples/account/amend-commission-schedule.y.out) + +To learn more on commission rates read the section inside the Oasis Core +[Staking service][staking-service-commission-schedule] chapter. + +:::info + +[Network and account](#npa) selectors are available for the +`account amend-commission-schedule` command. + +::: + +[staking-service-commission-schedule]: https://github.com/oasisprotocol/oasis-core/blob/master/docs/consensus/services/staking.md#amend-commission-schedule + +### Unfreeze Your Node {#node-unfreeze} + +Once the validators, based on their stake, get elected into the validator set, +it is important that their nodes are actively participating in proposing new +blocks and submitting votes for other proposed blocks. For regular node +upgrades and maintenance, the validators should follow the +[Shutting Down a Node] instructions. Nevertheless, if the network froze your +node, the only way to unfreeze it is to execute the `account node-unfreeze` + +![code shell](../examples/account/node-unfreeze.y.in) + +![code](../examples/account/node-unfreeze.y.out) + +:::info + +[Network and account](#npa) selectors are available for the +`account node-unfreeze` command. + +::: + +[Shutting Down a Node]: https://github.com/oasisprotocol/docs/blob/main/docs/node/run-your-node/maintenance/shutting-down-a-node.md + +### Burn Tokens {#burn} + +`account burn ` command will permanently destroy the amount of tokens +in your account and remove them from circulation. This command should not be +used on public networks since not only no one will be able to access burnt +assets anymore, but will also permanently remove the tokens from circulation. + +![code shell](../examples/account/burn.y.in) + +![code](../examples/account/burn.y.out) + +:::info + +[Network and account](#npa) selectors are available for the `account burn` +command. + +::: diff --git a/docs/addressbook.md b/docs/addressbook.md new file mode 100644 index 00000000..d5084aea --- /dev/null +++ b/docs/addressbook.md @@ -0,0 +1,86 @@ +--- +title: Address book +description: Storing your blockchain contacts for future use +--- + +# Address Book + +If you repeatedly transfer tokens to the same recipients or if you just want to +store an arbitrary address for future use, you can use the `addressbook` +command to **name the address and store it in your address book**. Entries +in your address book are behaving similarly to the +[accounts stored in your wallet][wallet], for example when checking the balance +of the account or sending tokens to. Of course, you cannot sign any +transactions with the address stored in your address book since you do not +possess the private key of that account. Both the Oasis native and the +Ethereum-compatible addresses can be stored. + +:::info + +The name of the address book entry may not clash with any of the account names +in your wallet. The Oasis CLI will prevent you from doing so. + +::: + +[wallet]: wallet.md + +## Add a New Entry {#add} + +Use `addressbook add
` to name the address and store it in your +address book. + +![code shell](../examples/addressbook/00-add-oasis.in) + +![code shell](../examples/addressbook/01-add-eth.in) + +Then, you can for example use the entry name in you address book to send the +tokens to. In this case, we're sending `2.5 TEST` to `meghan` on Sapphire +Testnet: + +![code shell](../examples/addressbook/02-transfer.y.in) + +![code](../examples/addressbook/02-transfer.y.out) + +## List Entries {#list} + +You can list all entries in your address book by invoking `addressbook list`. + +![code shell](../examples/addressbook/03-list.in) + +![code](../examples/addressbook/03-list.out) + +## Show Entry Details {#show} + +You can check the details such as the native Oasis address of the Ethereum +account or simply check, if an entry exists in the address book, by running +`addressbook show `: + +![code shell](../examples/addressbook/04-show-eth.in) + +![code](../examples/addressbook/04-show-eth.out) + +![code shell](../examples/addressbook/05-show-oasis.in) + +![code](../examples/addressbook/05-show-oasis.out) + +## Rename an Entry {#rename} + +You can always rename the entry in your address book by using +`addressbook rename `: + +![code shell](../examples/addressbook/06-rename.in) + +![code shell](../examples/addressbook/07-list.in) + +![code](../examples/addressbook/07-list.out) + +## Remove an Entry {#remove} + +To delete an entry from your address book invoke +`addressbook remove `. + +![code shell](../examples/addressbook/09-remove.in) + +![code shell](../examples/addressbook/10-list.in) + +![code](../examples/addressbook/10-list.out) diff --git a/docs/network.md b/docs/network.md new file mode 100644 index 00000000..80cf6be2 --- /dev/null +++ b/docs/network.md @@ -0,0 +1,306 @@ +--- +title: Network +description: Managing Mainnet, Testnet or Localnet endpoints +--- + +# Manage Your Oasis Networks + +The `network` command is used to manage the Mainnet, Testnet or Localnet +endpoints Oasis CLI will be connecting to. + +The `network` command is commonly used: + +- on network upgrades, because the chain domain separation context is changed + due to a new [genesis document], +- when setting up a local `oasis-node` instance instead of relying on public + gRPC endpoints, +- when running a private Localnet with `oasis-net-runner`, +- when examining network properties such as the native token, the network + registry, the validator set and others. + +Oasis CLI supports both **remote endpoints via the secure gRPC protocol** and +**local Unix socket endpoints**. + +:::tip + +When running the Oasis CLI for the first time, it will automatically configure +the current Mainnet and Testnet endpoints. + +::: + +[genesis document]: https://github.com/oasisprotocol/oasis-core/blob/master/docs/consensus/genesis.md#genesis-documents-hash + +## Add a Network {#add} + +Invoke `network add ` to add a new +endpoint with a specific chain domain separation context and a gRPC address. + +For TCP/IP endpoints, run: + +![code shell](../examples/network/add-tcpip.in.static) + +![code](../examples/network/add-tcpip.out.static) + +For Unix sockets, use: + +![code shell](../examples/network/add-unix.in.static) + +![code](../examples/network/add-unix.out.static) + +## Add a Local Network {#add-local} + +`network add-local ` command can be used if you are +running a local instance of `oasis-node`. In this case, Oasis CLI will +autodetect the native token symbol and decimal places, the chain domain +separation context and registered ParaTimes. + +``` +oasis network add-local testnet_local unix:/serverdir_testnet/internal.sock +``` + +## List Networks {#list} + +Invoke `network list` to list all configured networks. + +![code shell](../examples/network/00-list.in) + +![code](../examples/network/00-list.out) + +The [default network](#set-default) is marked with the `(*)` sign. + +## Remove a Network {#remove} + +Use `network remove ` to remove the given network configuration including +all dependant ParaTimes. + +![code shell](../examples/network/01-remove.in) + +## Set Default Network {#set-default} + +To change the default network for future Oasis CLI operations, use +`network set-default `. + +![code shell](../examples/network/02-list.in) + +![code](../examples/network/02-list.out) + +![code shell](../examples/network/03-set-default.in) + +![code shell](../examples/network/04-list.in) + +![code](../examples/network/04-list.out) + +## Change a Network's RPC Endpoint {#set-rpc} + +To change the RPC address of the already configured network, run +`network set-rpc `: + +![code shell](../examples/network-set-rpc/00-list.in) + +![code](../examples/network-set-rpc/00-list.out) + +![code shell](../examples/network-set-rpc/01-set-rpc.in) + +![code shell](../examples/network-set-rpc/02-list.in) + +![code](../examples/network-set-rpc/02-list.out) + +## Advanced + +### Governance Operations {#governance} + +`network governance` command is aimed towards validators for proposing +or voting on-chain for network upgrades or changes to other crucial network +parameters. + +#### `list` {#governance-list} + +Use `network list` to view all past and still active governance proposals. +Each proposal has its unique subsequent ID, a submitter, an epoch when the +proposal was created and when it closes and a state. + +![code shell](../examples/network-governance/list.in) + +![code](../examples/network-governance/list.out) + +#### `show` {#governance-show} + +`network governance show ` shows detailed information on +past or opened governance proposals on the consensus layer. + +![code shell](../examples/network-governance/show.in.static) + +![code](../examples/network-governance/show.out.static) + +:::info + +Governance proposals are not indexed and an endpoint may take some time to +respond. If you encounter timeouts, consider setting up your own gRPC endpoint! + +::: + +#### `cast-vote` {#governance-cast-vote} + +`network governance cast-vote { yes | no | abstain }` is used +to submit your vote on the governance proposal. The vote can either be `yes`, +`no` or `abstein`. + +![code shell](../examples/network-governance/cast-vote.in.static) + +![code](../examples/network-governance/cast-vote.out.static) + +#### `create-proposal` {#governance-create-proposal} + +To submit a new governance proposal use `network governance create-proposal`. +The following proposal types are currently supported: + +- `upgrade `: Network upgrade proposal. Provide a JSON file + containing the upgrade descriptor. +- `cancel-upgrade `: Cancel network proposed upgrade. Provide the + ID of the network upgrade proposal you wish to cancel. + +### Show Network Properties {#show} + +`network show` shows the network property stored in the registry, scheduler, +genesis document or on chain. + +By passing `--height ` with a block number, you can obtain a +historic value of the property. + +The command expects one of the following parameters: + +#### `entities` {#show-entities} + +Shows all registered entities in the network registry. See the +[`account entity`] command, if you want to register or update your own entity. + +[`account entity`]: ./account.md#entity + +:::info + +This call is not enabled on public Oasis gRPC endpoints. You will have to run +your own client node to enable this functionality. + +::: + +#### `nodes` {#show-nodes} + +Shows all registered nodes in the network registry. See the [`account entity`], +to add a node to your entity. + +:::info + +This call is not enabled on public Oasis gRPC endpoints. You will have to run +your own client node to enable this functionality. + +::: + +#### `paratimes` {#show-paratimes} + +Shows all registered ParaTimes in the network registry. + +#### `validators` {#show-validators} + +Shows all IDs of the nodes in the validator set. + +#### `native-token` {#show-native-token} + +Shows information of the network's native tokens such as its symbol, the number +of decimal points, total supply, debonding period and staking thresholds. + +![code shell](../examples/network-show/native-token.in.static) + +![code](../examples/network-show/native-token.out.static) + +We can see that the token's name is ROSE and that 1 token corresponds to 10^9 +(i.e. one billion) base units. + +Next, we can observe that the **total supply** is 10 billion tokens and that +about 1.3 billion tokens are in the **common pool**. + +**Staking thresholds** are important for the network validators. They show +the minimum staked amount required to become an active validator for the entity +and all node kinds (validator, compute, key manager nodes). At time of writing, +this was 100 tokens. For example, if you wanted to register an entity running a +validator and a compute node, you would need to stake (i.e. *escrow*) at least +300 tokens. + +:::info + +Each runtime may also require a **minimum ParaTime-specific escrow** for +running a compute node. Use the [`network show id`](#show-id) +command and pass a corresponding Paratime ID to see it. + +::: + +The `runtime-` fields show you the required staked amount for +[**registering a new ParaTime**](./paratime.md#register) of any kind (compute, +key manager) was 50,000 tokens at time of writing. + +#### `gas-costs` {#show-gas-costs} + +Shows minimum gas costs for each consensus transaction. + +![code shell](../examples/network-show/gas-costs.in) + +![code](../examples/network-show/gas-costs.out) + +Above, we can see that the [maximum amount of gas](./network.md#gas-limit) our +transaction can spend must be set to at least 1000 **gas units**, otherwise it +will be rejected by the network. + +#### `` {#show-id} + +The provided ID can be one of the following: + +- If the [ParaTime ID] is provided, Oasis CLI shows ParaTime information stored + in the network's registry. + + For example, at time of writing information on Sapphire stored in the Mainnet + registry were as follows: + + ![code shell](../examples/network-show/id-paratime.in.static) + + ![code json](../examples/network-show/id-paratime.out.static) + + Network validators may be interested in the **ParaTime staking threshold** + stored inside the `thresholds` field. In the example above, the amount to run + a Sapphire compute node on the Mainnet is 5,000,000 tokens and should be + considered on top of the consensus-layer validator staking thresholds + obtained by the [`network show native-token`](#show-native-token) command. + +- If the entity ID is provided, Oasis CLI shows information on the entity and + its corresponding nodes in the network registry. For example: + + ![code shell](../examples/network-show/id-entity.in) + + ![code json](../examples/network-show/id-entity.out) + +- If the node ID is provided, Oasis CLI shows detailed information of the node + such as the Oasis Core software version, the node's role, supported + ParaTimes, trusted execution environment support and more. For example: + + ![code shell](../examples/network-show/id-node.in.static) + + ![code json](../examples/network-show/id-node.out.static) + +[ParaTime ID]: https://github.com/oasisprotocol/oasis-core/blob/master/docs/runtime/identifiers.md + +### Status of the Network's Endpoint {#status} + +`network status` will connect to the gRPC endpoint and request extensive status +report from the Oasis Core node. Node operators will find important information +in the report such as: + +- the last proposed consensus block, +- whether the node's storage is synchronized with the network, +- the Oasis Core software version, +- connected peers, +- similar information as above for each ParaTime, if the node is running it. + +At time of writing, the following status of the official gRPC endpoint for +Mainnet was reported: + +![code shell](../examples/network/status.in.static) + +![code json](../examples/network/status.out.static) diff --git a/docs/paratime.md b/docs/paratime.md new file mode 100644 index 00000000..55cb6661 --- /dev/null +++ b/docs/paratime.md @@ -0,0 +1,203 @@ +--- +title: ParaTime +description: Managing ParaTimes +--- + +# Managing Your ParaTimes + +The `paratime` command lets you manage your ParaTime configurations bound to a +specific [network]. If you are a ParaTime developer, the command allows you to +register a new ParaTime into the public network's registry. The command +also supports examining specific block and a transaction inside the ParaTime +and printing different validator-related statistics. + +:::tip + +When running the Oasis CLI for the first time, it will automatically configure +official Oasis ParaTimes running on the [Mainnet] and [Testnet] networks. + +::: + +## Add a ParaTime {#add} + +Invoke `paratime add ` to add a new ParaTime to your Oasis +CLI configuration. Beside the name of the corresponding network and the unique +ParaTime name inside that network, you will also need to provide the +[ParaTime ID]. This is a unique identifier of the ParaTime on the network, and +it remains the same even when the network and ParaTime upgrades occur. You can +always check the IDs of the official Oasis ParaTimes on the respective +[Mainnet] and [Testnet] pages. + +Each ParaTime also has a native token denomination symbol defined with specific +number of decimal places which you will need to specify. + +```shell +oasis paratime add testnet sapphire2 000000000000000000000000000000000000000000000000a6d1e3ebf60dff6d +``` + +``` +? Description: +? Denomination symbol: TEST +? Denomination decimal places: 18 +``` + +:::danger Decimal places of the native and ParaTime token may differ! + +Emerald and Sapphire use **18 decimals** for compatibility with +Ethereum tooling. The Oasis Mainnet and Testnet consensus layer tokens and the +token native to Cipher have **9 decimals**. + +Configuring the wrong number of decimal places will lead to incorrect amount +of tokens to be deposited, withdrawn or transferred from or into the ParaTime! + +::: + +:::tip + +If you configured your network with the [`network add-local`] command, then all +registered ParaTimes of that network will be detected and added to your Oasis +CLI config automatically. + +::: + +[network]: ./network.md +[`network add-local`]: ./network.md#add-local +[ParaTime ID]: https://github.com/oasisprotocol/oasis-core/blob/master/docs/runtime/identifiers.md +[Mainnet]: https://github.com/oasisprotocol/docs/blob/main/docs/node/mainnet/README.md +[Testnet]: https://github.com/oasisprotocol/docs/blob/main/docs/node/testnet/README.md + +## List ParaTimes {#list} + +Invoke `paratime list` to list all configured ParaTimes across the networks. + +For example, at time of writing this section the following ParaTimes were +preconfigured by the Oasis CLI: + +![code shell](../examples/paratime/00-list.in) + +![code](../examples/paratime/00-list.out) + +The [default ParaTime](#set-default) for each network is marked with the `(*)` +sign. + +:::info + +ParaTimes on this list are configured inside your Oasis CLI instance. They +may not actually exist on the network. + +::: + +## Remove a ParaTime {#remove} + +To remove a configuration of a ParaTime for a specific network, use +`paratime remove `. For example, let's remove the +[previously added](#add) ParaTime: + +![code shell](../examples/paratime-remove/00-list.in) + +![code](../examples/paratime-remove/00-list.out) + +![code shell](../examples/paratime-remove/01-remove.in) + +![code shell](../examples/paratime-remove/02-list.in) + +![code](../examples/paratime-remove/02-list.out) + +## Set Default ParaTime {#set-default} + +To change the default ParaTime for Oasis CLI transactions on the specific +network, use `paratime set-default `. + +For example, to set the Cipher ParaTime default on the Testnet, run: + +![code shell](../examples/paratime/01-set-default.in) + +![code shell](../examples/paratime/02-list.in) + +![code](../examples/paratime/02-list.out) + +## Show {#show} + +Use `paratime show ` providing the block round to print its header and +other information. + +![code shell](../examples/paratime-show/show.in) + +![code](../examples/paratime-show/show.out) + +To show the details of the transaction stored inside the block including the +transaction status and any emitted events, pass the transaction index in the +block or its hash: + +![code shell](../examples/paratime-show/show-tx.in) + +![code](../examples/paratime-show/show-tx.out) + +Encrypted transactions can also be examined, although the data chunk will be +encrypted: + +![code shell](../examples/paratime-show/show-tx-encrypted.in) + +![code](../examples/paratime-show/show-tx-encrypted.out) + +## Advanced + +### Register a New ParaTime {#register} + +ParaTime developers may add a new ParaTime to the network's registry by +invoking the `paratime register ` command and providing a JSON file +with the ParaTime descriptor. You can use the +[`network show`][network-show-id] command passing the ParaTime ID to +see how descriptors of the currently registered ParaTimes look like. + +To learn more about registering your own ParaTime, check the +[Oasis Core Registry service]. + +[network-show-id]: ./network.md#show-id +[Oasis Core Registry service]: https://github.com/oasisprotocol/oasis-core/blob/master/docs/consensus/services/registry.md#register-runtime + +### Statistics {#statistics} + +`paratime statistics [ []]` will examine the voting +details for a range of blocks. First, it will print you aggregated statistics +showing you the number of successful rounds in that range, epoch transitions +and also anomalies such as the proposer timeouts, failed rounds and +discrepancies. Then, it will print out detailed validator per-entity +statistics for that range of blocks. + +The passed block number should be enumerated based on the round +inside the ParaTime. The start round can be one of the following: + +- If no round given, the validation of the last block will be examined. +- If a negative round number `N` is passed, the last `N` blocks will be + examined. +- If `0` is given, the oldest block available to the Oasis endpoint will be + considered as a starting block. +- A positive number will be considered as a start round. + +At time of writing, the following statistics was available: + +![code shell](../examples/paratime/statistics.in.static) + +![code](../examples/paratime/statistics.out.static) + +To extend statistics to, say 5 last blocks, you can run: + +![code shell](../examples/paratime/statistics-negative.in.static) + +![code](../examples/paratime/statistics-negative.out.static) + +For further analysis, you can easily export entity statistics to a CSV file by +passing the `--output-file` parameter and the file name: + +```shell +oasis paratime statistics -o stats.csv +``` + +:::info + +The analysis of the range of blocks may require some time or even occasionally +fail due to denial-of-service protection. If you encounter such issues, +consider setting up your own gRPC endpoint! + +::: diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 00000000..bca28cac --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,78 @@ +# Setup + +## Download and Run + +Download the latest release [here][cli-releases] and extract it to your +favorite application folder. + +:::info + +Oasis is currently providing official amd64 for Linux and ARM builds for MacOS. +If you want to run it on another platform, you will have to +[build it from source][cli-source]. + +::: + +:::info + +We suggest that you update your system path to include a directory containing +the `oasis` binary or create a symbolic link to `oasis` in your +system path, so you can access it globally. + +::: + +Run the Oasis CLI by typing `oasis`. + +![code](../examples/setup/first-run.out) + +When running the Oasis CLI for the first time, it will generate a configuration +file and populate it with the current Mainnet and Testnet networks. It will also +configure all [ParaTimes supported by the Oasis Foundation][paratimes]. + +## Configuration + +The configuration folder of Oasis CLI is located: + +- on Windows: + - `%USERPROFILE%\AppData\Roaming\oasis\` +- on macOS: + - `/Users/$USER/Library/Application Support/oasis/` +- on Linux: + - `$HOME/.config/oasis/` + +There, you will find `cli.toml` which contains the configuration of the +networks, ParaTimes and your wallet. Additionally, each file-based account in +your wallet will have a separate, password-encrypted JSON file in the same +folder named after the name of the account with the `.wallet` extension. + +## Multiple Profiles + +You can utilize multiple profiles of your Oasis CLI. To create a new profile, +move your existing configuration folder to another place, for example: + +```shell +mv $HOME/.config/oasis $HOME/.config/oasis_dev +``` + +Then, invoke `oasis` with arbitrary command to set up a fresh configuration +folder under `~/.config/oasis`. For example: + +![code shell](../examples/setup/wallet-list.in) + +![code](../examples/setup/wallet-list.out) + +Now you can switch between the `oasis_dev` and the new profile by passing +`--config` parameter pointing to `cli.toml` in the desired configuration folder. + +![code shell](../examples/setup/wallet-list-config.in.static) + +![code](../examples/setup/wallet-list-config.out.static) + +## Back Up Your Wallet + +To back up your complete Oasis CLI configuration including your wallet, archive +the configuration folder containing `cli.toml` and `.wallet` files. + +[cli-releases]: https://github.com/oasisprotocol/cli/releases +[cli-source]: https://github.com/oasisprotocol/cli +[paratimes]: https://github.com/oasisprotocol/docs/blob/main/docs/dapp/README.mdx diff --git a/docs/transaction.md b/docs/transaction.md new file mode 100644 index 00000000..539fddb1 --- /dev/null +++ b/docs/transaction.md @@ -0,0 +1,128 @@ +--- +title: Transaction +description: Using CLI to submit or decode a transaction +--- + +# Transaction Tools + +The `transaction` command offers convenient tools for processing raw +consensus or ParaTime transactions stored in a JSON file: + +- decoding and displaying the transaction, +- verifying transaction's signature, +- signing the transaction, +- broadcasting the transaction. + +## Decode, Verify and Show a Transaction {#show} + +To show the transaction, invoke `transaction show ` and provide +a filename containing a previously generated transaction by `oasis-node` or the +Oasis CLI's [`--output-file`][account-output-file] parameter. + +[account-output-file]: ./account.md#output-file + +For example, let's take the following transaction transferring `1.0 TEST` from +`test:alice` to `test:bob` on Testnet consensus layer and store it to +`testtx.json`: + +![code json](../examples/transaction/testtx.json "testtx.json") + +We can decode and verify the transaction as follows: + +![code shell](../examples/transaction/show.in) + +![code](../examples/transaction/show.out) + +Since the signature also includes the [chain domain separation context], it +will be invalid on other networks such as Mainnet and Oasis CLI will mark it as +`[INVALID SIGNATURE]`: + +![code shell](../examples/transaction/show-invalid.in) + +![code](../examples/transaction/show-invalid.out) + +A similar approach is suitable for ParaTime transactions. Take the following +transaction which transfers `1.0 TEST` from `test:alice` to `test:bob` inside +Sapphire ParaTime on Testnet and save it as `testtx2.json`: + +![code json](../examples/transaction/testtx2.json "testtx2.json") + +Oasis CLI will be able to verify the transaction only for the exact network and +ParaTime combination since both are included inside the chain domain separation +context of a ParaTime transaction signature. + +![code shell](../examples/transaction/show-paratime-tx.in) + +![code](../examples/transaction/show-paratime-tx.out) + +## Sign a Transaction {#sign} + +To sign a [previously unsigned transaction][unsigned] transaction or to append +another signature to the transaction (*multisig*), run +`transaction sign `. + +For example, let's transfer `1.0 TEST` from `test:alice` to `test:bob` on +Testnet consensus layer, but don't sign it and store it to +`testtx_unsigned.json`: + +![code json](../examples/transaction/testtx_unsigned.json + "testtx_unsigned.json") + +Comparing this transaction to [`testtx.json`](#show) which was signed, we can +notice that the transaction is not wrapped inside the `untrusted_raw_value` +envelope with the `signature` field. + +Decoding unsigned transaction gives us similar output: + +![code shell](../examples/transaction/show-unsigned.in) + +![code](../examples/transaction/show-unsigned.out) + +Finally, let's sign the transaction: + +![code shell](../examples/transaction/sign.y.in) + +![code](../examples/transaction/sign.y.out) + +We can also use [`--output-file`][account-output-file] here and store the +signed transaction back to another file instead of showing it. + +:::info + +[Network and Account][npa] selectors are available for the `transaction sign` +command. + +::: + +[npa]: ./account.md#npa +[unsigned]: ./account.md#unsigned + +## Submit a Transaction {#submit} + +Invoking `transaction submit ` will broadcast the consensus or +ParaTime transaction to the selected network or ParaTime. If the transaction +hasn't been signed yet, Oasis CLI will first sign it with the selected account +in your wallet and then broadcast it. + +```shell +oasis tx submit testtx.json --network testnet --no-paratime +``` + +``` +Broadcasting transaction... +Transaction executed successfully. +Transaction hash: a81a1dcd203bba01761a55527f2c44251278110a247e63a12f064bf41e07f13a +``` + +```shell +oasis tx submit testtx2.json --network testnet --paratime sapphire +``` + +``` +Broadcasting transaction... +Transaction included in block successfully. +Round: 946461 +Transaction hash: 25f0b2a92b6171969e9cd41d047bc20b4e2307c3a329ddef41af73df69d95b5d +``` + +[chain domain separation context]: ../../../core/crypto.md#chain-domain-separation diff --git a/docs/wallet.md b/docs/wallet.md new file mode 100644 index 00000000..d5ed8832 --- /dev/null +++ b/docs/wallet.md @@ -0,0 +1,405 @@ +--- +title: Wallet +description: Manage accounts in your CLI wallet +--- + +# Managing Accounts in Your Wallet + +The `wallet` command is used to manage accounts in your wallet. The wallet +can contain file-based accounts which are stored along your Oasis CLI +configuration, or a reference to an account stored on your hardware wallet. + +The following encryption algorithms and derivation paths are supported by the +Oasis CLI for your accounts: + +- `ed25519-adr8`: [Ed25519] keypair using the [ADR-8] derivation path in order + to obtain a private key from the mnemonic. This is the default setting + suitable for accounts on the Oasis consensus layer and Cipher. +- `secp256k1-bip44`: [Secp256k1] Ethereum-compatible keypair using [BIP-44] + with ETH coin type to derive a private key. This setting is + used for accounts living on EVM-compatible ParaTimes such as Sapphire or + Emerald. The same account can be imported into Metamask and other Ethereum + wallets. +- `ed25519-legacy`: [Ed25519] keypair using a legacy 5-component derivation + path. This is the preferred setting for Oasis accounts stored on a hardware + wallet like Ledger. It is called legacy, because it was first implemented + before the [ADR-8] was standardized. +- `sr25510-adr8`: [Sr25519] keypair using the [ADR-8] derivation path. This is + an alternative signature scheme for signing ParaTime transactions. +- `ed25519-raw`, `secp256k1-raw` and `sr25519-raw`: Respective Ed25519, + Secp256k1 and Sr25519 keypairs imported directly from Base32 or Hex-encoded + private keys. No key derivation is involved. + +:::tip + +For compatibility with Ethereum, each `secp256k1` account corresponds to two +addresses: + +- 20-byte hex-encoded Ethereum-compatible address, e.g. + `0xDCbF59bbcC0B297F1729adB23d7a5D721B481BA9` +- Bech32-encoded Oasis native address, e.g. + `oasis1qq3agel5x07pxz08ns3d2y7sjrr3xf9paquhhhzl`. + +There exists a [mapping][eth-oasis-address-mapping] from the Ethereum address +to the native Oasis address as in the example above, but **there is no reverse +mapping**. + +::: + +[ADR-8]: ../../../adrs/0008-standard-account-key-generation.md +[BIP-44]: https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki +[Ed25519]: https://en.wikipedia.org/wiki/EdDSA +[Secp256k1]: https://en.bitcoin.it/wiki/Secp256k1 +[Sr25519]: https://wiki.polkadot.network/docs/learn-cryptography +[eth-oasis-address-mapping]: https://github.com/oasisprotocol/oasis-sdk/blob/c36a7ee194abf4ca28fdac0edbefe3843b39bf69/client-sdk/go/types/address.go#L135-L142 + +## Create an Account {#create} + +The `wallet create ` command is used add a new account into your Oasis +CLI wallet by: + +- generating a new mnemonic and storing it into a file-based wallet, or +- creating a reference to an account stored on your hardware wallet. + +By default, a password-encrypted file-based wallet will be used for storing the +private key. You will have to enter the password for this account each time to +access use it for signing the transactions (e.g. to send tokens). The account +address is public and can be accessed without entering the passphrase. + +```shell +oasis wallet create oscar +``` + +``` +? Choose a new passphrase: +? Repeat passphrase: +``` + +:::tip + +The first account you create or import will become your **default account**. +This means it will automatically be selected as a source for sending funds or +calling smart contracts unless specified otherwise by using `--account ` +flag. You can always [change the default account](#set-default) later. + +::: + +To use your hardware wallet, add `--kind ledger` parameter and Oasis CLI will +store a reference to an account on your hardware wallet: + +```shell +oasis wallet create logan --kind ledger +``` + +A specific account kind (`ed25519-adr8`, `secp256k1-bip44`) and the derivation +path number can be passed with `--file.algorithm` and `--file.number` or +`--ledger.algorithm` and `--ledger.number` respectively. For example: + +```shell +oasis wallet create lenny --kind ledger --ledger.algorithm secp256k1-bip44 --ledger.number 3 +``` + +:::tip + +When creating a hardware wallet account, Oasis CLI will: + +1. obtain the public key of the account from your hardware wallet, +2. compute the corresponding native address, and +3. store the Oasis native address into the Oasis CLI. + +If you try to open the same account with a different Ledger device or +reset your Ledger with a new mnemonic, Oasis CLI will abort because the address +of the account obtained from the new device will not match the one stored in +your config. + +``` +oasis wallet show logan +Error: address mismatch after loading account (expected: oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl got: oasis1qzdyu09x7hs5nqa0sjgy5jtmz3j5f99ccq0aezjk) +``` + +::: + +## Import an Existing Keypair or a Mnemonic {#import} + +If you already have a mnemonic or a raw private key, you can import it +as a new account by invoking `wallet import`. You will be asked +interactively to select an account kind (`mnemonic` or `private key`), +encryption algorithm (`ed25519` or `secp256k1`) and then provide either the +mnemonic with the derivation number, or the raw private key in the corresponding +format. + +Importing an account with a mnemonic looks like this: + +```shell +oasis wallet import eugene +``` + +``` +? Kind: mnemonic +? Algorithm: secp256k1-bip44 +? Key number: 0 +? Mnemonic: [Enter 2 empty lines to finish]man ankle mystery favorite tone number ice west spare marriage control lucky life together neither + +? Mnemonic: +man ankle mystery favorite tone number ice west spare marriage control lucky life together neither +? Choose a new passphrase: +? Repeat passphrase: +``` + +Let's make another Secp256k1 account and entering a hex-encoded raw private key: + +```shell +oasis wallet import emma +``` + +``` +oasis wallet import emma +? Kind: private key +? Algorithm: secp256k1-raw +? Private key (hex-encoded): [Enter 2 empty lines to finish]4811ebbe4f29f32a758f6f7bad39deb97ea67f07350637e31c75795dc679262a + +? Private key (hex-encoded): +4811ebbe4f29f32a758f6f7bad39deb97ea67f07350637e31c75795dc679262a +? Choose a new passphrase: +? Repeat passphrase: +``` + +## List Accounts Stored in Your Wallet {#list} + +You can list all available accounts in your wallet with `wallet list`: + +![code shell](../examples/wallet/00-list.in) + +![code](../examples/wallet/00-list.out) + +Above, you can see the native Oasis addresses of all local accounts. The +[default account](#set-default) has a special `(*)` sign next to its name. + +## Show Account Configuration Details {#show} + +To verify whether an account exists in your wallet, use `wallet show `. +This will print the account's native address and the public key which requires +entering your account's password. + +```shell +oasis wallet show oscar +``` + +``` +Unlock your account. +? Passphrase: +Name: oscar +Public Key: Bx6gOixnxy15tCs09ua5DcKyX9uo2Forb32O6Hyjoc8= +Native address: oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e +``` + +For `secp256k1` accounts Ethereum's hex-encoded address will also be printed. + +```shell +oasis wallet show eugene +``` + +``` +Unlock your account. +? Passphrase: +Name: eugene +Public Key: ArEjDxsPfDvfeLlity4mjGzy8E/nI4umiC8vYQh+eh/c +Ethereum address: 0xBd16C6bF701a01DF1B5C11B14860b6bDbE776669 +Native address: oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz +``` + +Showing an account stored on your hardware wallet will require connecting it to +your computer: + +```shell +oasis wallet show logan +``` + +``` +Name: logan +Public Key: l+cuboPsOeuY1+kYlROrpmKgiiELmXSw9xl0WEg8cWE= +Native address: oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl +``` + +## Export the Account's Secret {#export} + +You can obtain the secret material of a file-based account such as the mnemonic +or the private key by running `wallet export `. + +For example: + +```shell +oasis wallet export oscar +``` + +``` +WARNING: Exporting the account will expose secret key material! +Unlock your account. +? Passphrase: +Name: oscar +Public Key: Bx6gOixnxy15tCs09ua5DcKyX9uo2Forb32O6Hyjoc8= +Native address: oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e +Export: +promote easily runway junior saddle gold flip believe wet example amount believe habit mixed pistol lemon increase moon rail mail fiction miss clip asset +``` + +The same goes for Secp256k1 accounts: + +```shell +oasis wallet export eugene +``` + +``` +WARNING: Exporting the account will expose secret key material! +Unlock your account. +? Passphrase: +Name: eugene +Public Key: ArEjDxsPfDvfeLlity4mjGzy8E/nI4umiC8vYQh+eh/c +Ethereum address: 0xBd16C6bF701a01DF1B5C11B14860b6bDbE776669 +Native address: oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz +Export: +man ankle mystery favorite tone number ice west spare marriage control lucky life together neither +``` + +```shell +oasis wallet export emma +``` + +``` +WARNING: Exporting the account will expose secret key material! +Unlock your account. +? Passphrase: +Name: emma +Public Key: Az8B2UpSUET0E3n9XMzr+HBvviQKcRvz6C6bJtRFWNYG +Ethereum address: 0xeEbE22411f579682F6f9D68f4C19B3581bCb576b +Native address: oasis1qph93wnfw8shu04pqyarvtjy4lytz3hp0c7tqnqh +Export: +4811ebbe4f29f32a758f6f7bad39deb97ea67f07350637e31c75795dc679262a +``` + +Trying to export an account stored on your hardware wallet will only +export its public key: + +```shell +oasis wallet export lenny +``` + +``` +WARNING: Exporting the account will expose secret key material! +Name: lenny +Public Key: AhhT2TUkEZ7rMasLBvHcsGj4SUO7Iw36ELEpL0evZDV1 +Ethereum address: 0x95e5e3C1BDD92cd4A0c14c62480DB5867946281D +Native address: oasis1qrmw4rhvp8ksj3yx6p2ftnkz864muc3re5jlgall +Export: +``` + +## Renaming the Account {#rename} + +To rename an account, run `wallet rename `. + +For example: + +![code shell](../examples/wallet/01-rename.in) + +![code shell](../examples/wallet/02-list.in) + +![code](../examples/wallet/02-list.out) + +## Deleting an Account {#remove} + +To irreversibly delete the account from your wallet use `wallet remove `. +For file-based accounts this will delete the file containing the private key +from your disk. For hardware wallet accounts this will delete the Oasis CLI +reference, but the private keys will remain intact on your hardware wallet. + +For example, let's delete `lenny` account: + +![code shell](../examples/wallet/00-list.in) + +![code](../examples/wallet/00-list.out) + +```shell +oasis wallet remove lenny +``` + +``` +WARNING: Removing the account will ERASE secret key material! +WARNING: THIS ACTION IS IRREVERSIBLE! +? Enter 'I really want to remove account lenny' (without quotes) to confirm removal: I really want to remove account lenny +``` + +```shell +oasis wallet list +``` + +``` +oasis wallet list +ACCOUNT KIND ADDRESS +emma file (secp256k1-raw) oasis1qph93wnfw8shu04pqyarvtjy4lytz3hp0c7tqnqh +eugene file (secp256k1-bip44:0) oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz +logan ledger (ed25519-legacy:0) oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl +oscar (*) file (ed25519-raw) oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e +``` + +## Set Default Account {#set-default} + +To change your default account, use `wallet set-default ` and the +name of the desired default account. + +![code shell](../examples/wallet/00-list.in) + +![code](../examples/wallet/00-list.out) + +![code shell](../examples/wallet/04-set-default.in) + +![code shell](../examples/wallet/05-list.in) + +![code](../examples/wallet/05-list.out) + +## Advanced + +### Remote Signer for `oasis-node` {#remote-signer} + +You can bind the account in your Oasis CLI wallet with a local instance of +`oasis-node`. To do this, use +`wallet remote-signer `, pick the account you wish +to expose and provide a path to the new unix socket: + +```shell +oasis wallet remote-signer oscar /datadir/oasis-oscar.socket +``` + +``` +Unlock your account. +? Passphrase: +Address: oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e +Node Args: + --signer.backend=remote \ + --signer.remote.address=unix:/datadir/oasis-oscar.socket + +*** REMOTE SIGNER READY *** +``` + +### Test Accounts {#test-accounts} + +Oasis CLI comes with the following hardcoded test accounts: + +- `test:alice`: Ed25519 test account by Oasis core tests +- `test:bob`: Ed25519 test account by Oasis core tests +- `test:charlie`: Secp256k1 test account +- `test:cory`: Ed25519 account used by `oasis-net-runner` +- `test:dave`: Secp256k1 test account +- `test:erin`: Sr25519 test account +- `test:frank`: Sr25519 test account + +:::danger Do not use these accounts on public networks + +Private keys for these accounts are well-known. Do not fund them on public +networks, because anyone can drain them! + +::: + +We suggest that you use these accounts for Localnet development or for +reproducibility when you report bugs to the Oasis core team. You can access the +private key of a test account the same way as you would for ordinary accounts +by running `wallet export`. diff --git a/examples/README.md b/examples/README.md index 8682af49..5bbea02b 100644 --- a/examples/README.md +++ b/examples/README.md @@ -12,7 +12,7 @@ Each example is stored inside its own folder. The folder contains: - input and output artifacts - `config` folder containing custom config file to be used for the scenario. -## Invocation files +## Invocation Files Invocation files have `.in` extension and they will be executed in alphabetic order. This is important, if you have destructive operations (e.g @@ -59,7 +59,7 @@ as the corresponding invocation file, but having `.out` extension instead of Scenarios should be designed in a way that the output files remain equal unless a different behavior of the Oasis CLI is expected. -## Static examples +## Static Examples If you do not want the example to be executed, but you simply want to store Oasis CLI execution snippets for example to be included in the documentation,