diff --git a/.gitmodules b/.gitmodules index 9a030b891a..eebeeb7859 100644 --- a/.gitmodules +++ b/.gitmodules @@ -11,3 +11,6 @@ [submodule "external/adrs"] path = external/adrs url = https://github.com/oasisprotocol/adrs +[submodule "external/cli"] + path = external/cli + url = https://github.com/oasisprotocol/cli diff --git a/README.md b/README.md index ea30934b86..0d9c0223d1 100644 --- a/README.md +++ b/README.md @@ -117,7 +117,7 @@ Markdown files hosted by this repository should: `../howto-use-wallet.md`. `../../../operators/set-up-your-node.md` -Markdown files hosted by other Oasis repositories should: +Symlinked Markdown files hosted by other Oasis repositories should: - reference markdown files in the same repository by a relative path e.g. `../howto-write-contract.md`. diff --git a/docs/general/manage-tokens/README.mdx b/docs/general/manage-tokens/README.mdx index 0bafad7b23..63f167e33b 100644 --- a/docs/general/manage-tokens/README.mdx +++ b/docs/general/manage-tokens/README.mdx @@ -10,7 +10,7 @@ This documentation will guide you on how to use your ROSE tokens, where to keep * For **self-custody**, we recommend using one of our **official** [**Oasis Wallets**](oasis-wallets/README.mdx), [Web](oasis-wallets/web.md) or [Browser Extension](oasis-wallets/browser-extension.md). * ROSE is supported via three [**custody providers**](holding-rose-tokens/custody-providers.md): [Copper.co](https://copper.co), [Anchorage](https://anchorage.com) and [Finoa](https://finoa.io). * For extra security with self-custody, we recommend using the [Ledger](https://www.ledger.com) wallet with one of our official [Oasis Wallets](oasis-wallets/README.mdx). -* For experienced developers/power users, we offer [Oasis CLI Tools](advanced/oasis-cli-tools/README.md). +* For experienced developers/power users, we offer [Oasis CLI Tools](cli/README.md). :::caution @@ -24,7 +24,7 @@ For your own security and peace of mind, please only use wallets that are listed findSidebarItem('/general/manage-tokens/terminology'), findSidebarItem('/general/manage-tokens/staking-and-delegating'), findSidebarItem('/general/manage-tokens/oasis-wallets/'), - findSidebarItem('/general/manage-tokens/advanced/oasis-cli-tools/'), + findSidebarItem('/general/manage-tokens/cli/'), findSidebarItem('/general/manage-tokens/holding-rose-tokens/custody-providers'), findSidebarItem('/general/manage-tokens/holding-rose-tokens/ledger-wallet'), ]} /> diff --git a/docs/general/manage-tokens/advanced/README.mdx b/docs/general/manage-tokens/advanced/README.mdx deleted file mode 100644 index e0763a3759..0000000000 --- a/docs/general/manage-tokens/advanced/README.mdx +++ /dev/null @@ -1,13 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Advanced - -This section provides documentation on more advanced options on managing your ROSE tokens. - -:::caution - -If you are not familiar with the command line, we recommend using one of the available [Oasis Wallets](../oasis-wallets/README.mdx). - -::: - - diff --git a/docs/general/manage-tokens/advanced/file-based-signer.md b/docs/general/manage-tokens/advanced/file-based-signer.md deleted file mode 100644 index 28346a2f03..0000000000 --- a/docs/general/manage-tokens/advanced/file-based-signer.md +++ /dev/null @@ -1,41 +0,0 @@ -# Oasis File-Based Signer - -:::danger - -We strongly suggest that you do not use any entity/staking account that is generated with the file-based signer on the Mainnet. - -In case you need to use the file-based signer, make sure you only use it on an [offline/air-gapped machine](https://en.wikipedia.org/wiki/Air_gap_\(networking\)). Gaining access to your entity's/staking account's private key can compromise your tokens. - -::: - -To hold your ROSE tokens via a private key stored in a file, use the Oasis file-based signer. - -## Manage Your Tokens - -### Using Oasis Wallets - -This is a simpler option since it allows you to import your private key stored in a file into a web browser app or a web browser extension. - -Follow the instructions in the [Oasis Wallets](../oasis-wallets/README.mdx) doc. - -:::danger - -Importing your private key into an online web browser app or a web browser extension will significantly increase its exposure and chances for it to be compromised. - -We recommend ONLY doing this with wallets with small amounts of ROSE tokens or wallets only used with the Testnet. - -::: - -### Using Oasis CLI Tools - -This is the most powerful option that allows performing any token-related management task. - -Follow the instructions in the [Oasis CLI Tools](oasis-cli-tools/README.md) doc. - -:::caution - -To ensure your private key's safety, we recommend only exposing/using your private key on an [offline/air-gapped machine](https://en.wikipedia.org/wiki/Air_gap_\(networking\)). - -Exposing your entity's/staking account's private key on an online machine can compromise your tokens. - -::: diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/README.md b/docs/general/manage-tokens/advanced/oasis-cli-tools/README.md deleted file mode 100644 index ad8ca40933..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# Oasis CLI Tools - -This section provides documentation on how to manage your ROSE tokens via Oasis CLI tools. - -:::caution - -If you are not familiar with the command line, we recommend using one of the available [Oasis Wallets](../../oasis-wallets/README.mdx). - -::: - -:::caution - -Oasis CLI Tools are only fully supported on x86_64 Linux systems. - -Support for x86_64 macOS systems is in development. Currently, macOS binary [releases of Oasis Core Ledger](https://github.com/oasisprotocol/oasis-core-ledger/releases) include both, the Oasis Core Ledger CLI and the Ledger Signer Plugin, while there are no binary releases of [Oasis Node CLI](../../../../node/run-your-node/prerequisites/oasis-node.md) for macOS systems. To use Oasis Node CLI on macOS, you will need to [build it from source](../../../../node/run-your-node/prerequisites/oasis-node.md#building-from-source). - -::: diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/address.md b/docs/general/manage-tokens/advanced/oasis-cli-tools/address.md deleted file mode 100644 index 8e6f5a6749..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/address.md +++ /dev/null @@ -1,20 +0,0 @@ -# Obtain Account Address From Entity's ID - -To convert an entity ID (Base64 encoded), e.g. `nyjbDRKAXgUkL6CYfJP0WVA0XbF0pAGuvObZNMufgfY=`, to a [staking account address](../../terminology.md#address), run: - -```bash -oasis-node stake pubkey2address \ - --public_key nyjbDRKAXgUkL6CYfJP0WVA0XbF0pAGuvObZNMufgfY= -``` - -This will output the staking account address for the given entity ID: - -``` -oasis1qrvsa8ukfw3p6kw2vcs0fk9t59mceqq7fyttwqgx -``` - -:::info - -You can find your entity's ID in the `id` field of the `entity.json` file. - -::: diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/common-staking-info.md b/docs/general/manage-tokens/advanced/oasis-cli-tools/common-staking-info.md deleted file mode 100644 index c2d6c8d768..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/common-staking-info.md +++ /dev/null @@ -1,83 +0,0 @@ -# Common Staking Info - -:::info - -This example assumes you have read and followed the -[Prerequisites](prerequisites.md) and [Setup](setup.md) sections. - -::: - -To query an Oasis node for the common staking information, run: - -```bash -oasis-node stake info -a $ADDR -``` - -At time of writing this document, the command will output the following: - -```text -Token's ticker symbol: ROSE -Token's value base-10 exponent: 9 -Total supply: 10000000000.0 ROSE -Common pool: 1319242295.211384785 ROSE -Last block fees: 0.0 ROSE -Governance deposits: 0.0 ROSE -Staking threshold (entity): 100.0 ROSE -Staking threshold (node-validator): 100.0 ROSE -Staking threshold (node-compute): 100.0 ROSE -Staking threshold (node-keymanager): 100.0 ROSE -Staking threshold (runtime-compute): 50000.0 ROSE -Staking threshold (runtime-keymanager): 50000.0 ROSE -``` - -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**. - -The **staking thresholds** for the entity and all node kinds (validator, -compute, key manager) are 100 tokens. - -This means that if you want to register, e.g. an entity with a validator node, -you need to escrow (i.e. stake) at least 200 tokens. - -Staking threshold for registering a **new runtime** (ParaTime) of any kind -(compute, key manager) is 50,000 tokens. - -In addition, each runtime may require an **additional staking threshold** for -running a compute node. You need to query the registry in verbose mode to -obtain it: - -```bash -$ ./oasis-node registry runtime list -v -a $ADDR -``` - -For example, Emerald ParaTime running on the Mainnet has the following -additional staking requirements: - -```json -{ - "v": 3, - "id": "000000000000000000000000000000000000000000000000e2eaa99fc008f87f", - ... - "staking": { - "thresholds": { - "node-compute": "5000000000000000" - }, - "min_in_message_fee": "0" - }, - ... -} -``` - -To register a node that is both a validator and a compute node for Emerald -ParaTime, the entity for which the node is registered would need to satisfy the following: - -* Entity registration staking threshold (currently 100 tokens), -* Validator node staking threshold (currently 100 tokens), -* Compute node staking threshold (currently 100 tokens), -* Emerald-specific staking threshold (currently 5,000,000 tokens), - -All together, there would need to be at least 5,000,300 tokens staked in your -entity's escrow account. diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/delegate-tokens.md b/docs/general/manage-tokens/advanced/oasis-cli-tools/delegate-tokens.md deleted file mode 100644 index d9493ae681..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/delegate-tokens.md +++ /dev/null @@ -1,155 +0,0 @@ -# Delegate/Stake Tokens - -:::info - -This example assumes you have read and followed the instructions in the [Prerequisites](prerequisites.md) and [Setup](setup.md) sections. - -::: - -Let's assume: - -* we want to stake (i.e. self-delegate) 208 tokens, -* `oasis1qr6swa6gsp2ukfjcdmka8wrkrwz294t7ev39nrw` is our staking account address. - -:::info - -Minimum delegation amount is specified by the `staking.params.min_delegation` consensus parameter. - -To obtain its value from the genesis file, run: - -```bash -cat $GENESIS_FILE | \ - python3 -c 'import sys, json; \ - print(json.dumps(json.load(sys.stdin)["staking"]["params"]["min_delegation"], indent=4))' -``` - -Note that this value is in base units. E.g., a value of `"10000000000"` would correspond to 10 tokens. - -::: - -To achieve this we need to put 208 tokens to our own escrow account. - -## Query Our Account's Info - -To query our staking account's information, use the following command: - -```bash -oasis-node stake account info \ - -a $ADDR \ - --stake.account.address oasis1qr6swa6gsp2ukfjcdmka8wrkrwz294t7ev39nrw6 -``` - -:::info - -For a detailed explanation on querying account information, see the [Get Info](get-account-info.md) section. - -::: - -Before the transaction, this outputs: - -``` -General Account: - Balance: ROSE 431.492490765 - Nonce: 8 -Escrow Account: - Active: - Balance: ROSE 11242.38481664 - Total Shares: 10000000000000 - Debonding: - Balance: ROSE 0.0 - Total Shares: 0 - ... -``` - -We can observe that: - -* General account's balance is ~431 tokens. -* Account's nonce is 8. -* ~11242 tokens are actively bounded to the escrow account. -* The amount of tokens that are currently debonding is 0. - -## Generate an Escrow Transaction - -Let's generate an escrow transaction of 208 tokens (i.e. 208 * 10^9 base units) to our own escrow account and store it to `tx_escrow.json`: - -```bash -oasis-node stake account gen_escrow \ - "${TX_FLAGS[@]}" \ - --stake.amount 208000000000 \ - --stake.escrow.account oasis1qr6swa6gsp2ukfjcdmka8wrkrwz294t7ev39nrw6 \ - --transaction.file tx_escrow.json \ - --transaction.nonce 8 \ - --transaction.fee.gas 1000 \ - --transaction.fee.amount 2000 -``` - -This will output a preview of the generated transaction: - -``` -You are about to sign the following transaction: - Nonce: 8 - Fee: - Amount: ROSE 0.000002 - Gas limit: 1000 - (gas price: ROSE 0.000000002 per gas unit) - Method: staking.AddEscrow - Body: - Account: oasis1qr6swa6gsp2ukfjcdmka8wrkrwz294t7ev39nrw6 - Amount: ROSE 208.0 -Other info: - Genesis document's hash: 976c302f696e417bd861b599e79261244f4391f3887a488212ee122ca7bbf0a8 -``` - -and ask you for confirmation. - -## Submit the Transaction - -To submit the generated transaction, we need to copy `tx_escrow.json` to the online Oasis node (i.e. the `server`) and submit it from there: - -```bash -oasis-node consensus submit_tx \ - -a $ADDR \ - --transaction.file tx_escrow.json -``` - -## Query Our Account's Info Again - -Let's check [our account's info](delegate-tokens.md#query-our-accounts-info) again: - -``` -General Account: - Balance: ROSE 223.492486765 - Nonce: 9 -Escrow Account: - Active: - Balance: ROSE 11450.38481664 - Total Shares: 10185014125910 - Debonding: - Balance: ROSE 0.0 - Total Shares: 0 - ... -``` - -We can observe that: - -* Our general account's balance decreased by 208.000002 tokens. The 0.000002 token corresponds to the fee that we specified we will pay for this transaction. -* Our account's nonce increased to 9. -* Our escrow account's active balance increased by 208 tokens. -* The total number of shares in our escrow account's active part - - increased from 10,000,000,000,000 to 10,185,014,125,910. - -### Computation of Shares - -When a delegator delegates some amount of tokens to a staking account, the delegator receives the number of shares proportional to the current **share price** (in tokens) calculated from the total number of tokens delegated to a staking account so far and the number of shares issued so far: - -``` -shares_per_token = account_issued_shares / account_delegated_tokens -``` - -In our case, the current share price (i.e. `shares_per_token`) is 10,000,000,000,000 / 11242.384816640 which is 889,490,989.9542729 shares per token. - -For 208 tokens, the amount of newly issued shares is thus 208 * 889,490,989.9542729 which is 185,014,125,910.48877 shares (rounded to 185,014,125,910 shares). - -Hence, the escrow account's total number of shares increased by 185,014,125,910 shares. - diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/deposit-withdraw-tokens-to-from-paratime.mdx b/docs/general/manage-tokens/advanced/oasis-cli-tools/deposit-withdraw-tokens-to-from-paratime.mdx deleted file mode 100644 index 0cba240d0d..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/deposit-withdraw-tokens-to-from-paratime.mdx +++ /dev/null @@ -1,309 +0,0 @@ -import DocCard from '@theme/DocCard'; -import {findSidebarItem} from '@site/src/sidebarUtils'; - -# Deposit/Withdraw Tokens to/from ParaTime - -To perform ParaTime deposits or withdrawals using a command line interface, you will need `oasis` executable which is part of the [Oasis CLI](https://github.com/oasisprotocol/oasis-sdk/tree/main/cli). `oasis` is supplemental to `oasis-node` and supports ParaTime-related operations such as deposits, withdrawals, transfers and manipulation of the smart contracts, in contrast to `oasis-node` which only supports consensus layer features. - -We will assume that your already have an Oasis wallet with some ROSE and that you want to Deposit or Withdraw ROSE to or from Emerald ParaTime running on the Mainnet network. - -:::info - -At time of writing, no precompiled `oasis` binaries are available. You will need to clone the [`oasis-sdk` git repository](https://github.com/oasisprotocol/oasis-sdk/) and compile the tool yourself. The process is straight forward - just follow the [Readme](https://github.com/oasisprotocol/oasis-sdk/blob/main/cli/README.md). - -::: - -:::info - -This chapter describes the command line interface for depositing and withdrawing ROSE which is tailored toward advanced users such as node operators. If you are interested in the end-user wallets with a graphical user interface, consult the [How to Transfer ROSE into a ParaTime](../../how-to-transfer-rose-into-paratime.mdx) chapter. - -::: - -## Import your wallet - -To sign any transaction you will need to import an Oasis wallet. Prepare your base64-encoded private key or the BIP39 mnemonic of your Oasis account and run: - -``` -oasis wallet import -``` - -Follow the interactive instructions that will guide you through the import procedure. If this is the first time you are running `oasis`, the imported wallet will become your default wallet and transactions will be signed with the key stored in this wallet, if not otherwise specified with the `--wallet` parameter. - -## Configure Allowance - -In order to deposit ROSE to a ParaTime, you will first need to grant the ParaTime access to your Oasis account on the consensus layer. The following command allows Emerald to access up to 100 ROSE stored on your Oasis account which you will deposit afterwards: - -``` -$ oasis accounts allow paratime:emerald 100 -Unlock your wallet. -? Passphrase: -You are about to sign the following transaction: -Method: staking.Allow -Body: - Beneficiary: oasis1qqdpkrh0v9jn80kymcvgk57v38x38qwdxvvtnjfm - Amount change: +10.0 ROSE -Nonce: 5 -Fee: - Amount: 0.0 ROSE - Gas limit: 0 - (gas price: 0.0 ROSE per gas unit) - -Network: mainnet -Paratime: none (consensus layer) -? Sign this transaction? Yes -Broadcasting transaction... -Transaction executed successfully. -Transaction hash: a28a67b7af6bdce84760d5d61b982c0e89aa6874dda0aad01b61ef85feea8601 -``` - -The allowance above **adds** the amount of ROSE Emerald ParaTime will be allowed to access. For example, if your run the command above 3 times, Emerald will obtain the permission to access 300 ROSE. Later, each deposit will subtract ROSE from the allowed amount. - -:::info - -By default the Oasis CLI will execute transactions on Emerald ParaTime deployed on the Mainnet. You can always use another ParaTime and the network by using the `--paratime` and `--network` parameters respectively. - -::: - -## Deposit - -After setting up the allowance policy, we can execute the deposit transaction. The following command will deposit 100 ROSE from your consensus account to your ParaTime account. - -``` -$ oasis accounts deposit 100 --gas-price 0 -Unlock your wallet. -? Passphrase: -You are about to sign the following transaction: -{ - "v": 1, - "call": { - "method": "consensus.Deposit", - "body": "oWZhbW91bnSCSA3gtrOnZAAAQA==" - }, - "ai": { - "si": [ - { - "address_spec": { - "signature": { - "ed25519": "OxEJPYSJW55VEDZyzJ6drxzZ6MeSwz/JuTwCAlWJ0ks=" - } - }, - "nonce": 8 - } - ], - "fee": { - "amount": { - "Amount": "0", - "Denomination": "" - }, - "gas": 11284, - "consensus_messages": 1 - } - } -} - -Network: mainnet -Paratime: emerald -? Sign this transaction? Yes -Broadcasting transaction... -Transaction executed successfully. -Round: 564 -Transaction hash: 2bccec1776df6c2028f7ece6ae9b53b8c12875f3f10b39b962d9ac82238bc60b -Waiting for deposit result... -Deposit succeeded. -``` - -Currently, deposit transactions are free of charge, so we can avoid spending ROSE for the gas fee by adding the `--gas-price 0` parameter. Also, keep in mind that **deposit and withdrawal fees are always paid by your ParaTime account.** If it doesn't contain any ROSE, you are not able to cover the fees. - -To deposit ROSE to a different ParaTime account, simply add the bech32-encoded `oasis1` address to the deposit command: - -``` -$ oasis accounts deposit 100 oasis1qpxhsf7xnm007csw2acaa7mta2krzpwex5c90qu6 --gas-price 0 -Unlock your wallet. -? Passphrase: -You are about to sign the following transaction: -{ - "v": 1, - "call": { - "method": "consensus.Deposit", - "body": "omJ0b1UATXgnxp7e/2IOV3He+2vqrDEF2TVmYW1vdW50gkkFa8deLWMQAABA" - }, - "ai": { - "si": [ - { - "address_spec": { - "signature": { - "ed25519": "NcPzNW3YU2T+ugNUtUWtoQnRvbOL9dYSaBfbjHLP1pE=" - } - }, - "nonce": 9 - } - ], - "fee": { - "amount": { - "Amount": "0", - "Denomination": "" - }, - "gas": 11310, - "consensus_messages": 1 - } - } -} - -Network: mainnet -Paratime: emerald -? Sign this transaction? Yes -Broadcasting transaction... -Transaction executed successfully. -Round: 710 -Transaction hash: aab2262def5a4d6e28b769b6372e07d271e6a9f0857502f2b8a6a0c777ef2b05 -Waiting for deposit result... -Deposit succeeded. -``` - -Also, Ethereum hex-encoded addresses are supported which are common in Emerald ParaTime: - -``` -$ oasis accounts deposit 100 0x90adE3B7065fa715c7a150313877dF1d33e777D5 --gas-price 0 -Unlock your wallet. -? Passphrase: -You are about to sign the following transaction: -{ - "v": 1, - "call": { - "method": "consensus.Deposit", - "body": "omJ0b1UAeBTz2VT0G2RZ655LyPvGdn7OWqlmYW1vdW50gkgN4Lazp2QAAEA=" - }, - "ai": { - "si": [ - { - "address_spec": { - "signature": { - "ed25519": "NcPzNW3YU2T+ugNUtUWtoQnRvbOL9dYSaBfbjHLP1pE=" - } - }, - "nonce": 10 - } - ], - "fee": { - "amount": { - "Amount": "1130900000000000", - "Denomination": "" - }, - "gas": 11309, - "consensus_messages": 1 - } - } -} - -Network: mainnet -Paratime: emerald -? Sign this transaction? Yes -Broadcasting transaction... -Transaction executed successfully. -Round: 712 -Transaction hash: bd587656e92515efb326614fda554b3ce1b7ec69768880bf21895424e06bddb9 -Waiting for deposit result... -Deposit succeeded. -``` - -## Withdraw - -To withdraw 100 ROSE from your ParaTime account to the same account on the consensus layer, run: - -``` -$ oasis accounts withdraw 100 -Unlock your wallet. -? Passphrase: -You are about to sign the following transaction: -{ - "v": 1, - "call": { - "method": "consensus.Withdraw", - "body": "oWZhbW91bnSCSIrHIwSJ6AAAQA==" - }, - "ai": { - "si": [ - { - "address_spec": { - "signature": { - "ed25519": "NcPzNW3YU2T+ugNUtUWtoQnRvbOL9dYSaBfbjHLP1pE=" - } - }, - "nonce": 12 - } - ], - "fee": { - "amount": { - "Amount": "112850000000000", - "Denomination": "" - }, - "gas": 11285, - "consensus_messages": 1 - } - } -} - -Network: mainnet -Paratime: emerald -? Sign this transaction? Yes -Broadcasting transaction... -Transaction executed successfully. -Round: 727 -Transaction hash: c357b0661208a93301a07edc912cec9111ba1a60a08a1d85f221c906b41ad121 -Waiting for withdraw result... -Withdraw succeeded. -``` - -Withdraw transactions are not free of charge and the fee will be deducted **from your ParaTime balance**. - -You can specify a custom Oasis address which you want to withdraw your ROSE to by appending it to the withdraw command: - -``` -$ oasis accounts withdraw 100 oasis1qpxhsf7xnm007csw2acaa7mta2krzpwex5c90qu6 -Unlock your wallet. -? Passphrase: -You are about to sign the following transaction: -{ - "v": 1, - "call": { - "method": "consensus.Withdraw", - "body": "omJ0b1UATXgnxp7e/2IOV3He+2vqrDEF2TVmYW1vdW50gkiKxyMEiegAAEA=" - }, - "ai": { - "si": [ - { - "address_spec": { - "signature": { - "ed25519": "NcPzNW3YU2T+ugNUtUWtoQnRvbOL9dYSaBfbjHLP1pE=" - } - }, - "nonce": 14 - } - ], - "fee": { - "amount": { - "Amount": "113100000000000", - "Denomination": "" - }, - "gas": 11310, - "consensus_messages": 1 - } - } -} - -Network: mainnet -Paratime: emerald -? Sign this transaction? Yes -Broadcasting transaction... -Transaction executed successfully. -Round: 762 -Transaction hash: 85b9c65d2df54a4bb698f4ced7c89fe91462ff78a68136280e030ee38780e687 -Waiting for withdraw result... -Withdraw succeeded. -``` - -## See also - - diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/gas-costs.md b/docs/general/manage-tokens/advanced/oasis-cli-tools/gas-costs.md deleted file mode 100644 index 7f07f972e0..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/gas-costs.md +++ /dev/null @@ -1,31 +0,0 @@ -# Gas Costs - -:::info - -This example assumes you have read and followed the instructions in the [Prerequisites](prerequisites.md) and [Setup](setup.md) sections. - -::: - -### Obtaining Transactions' Gas Costs - -As explained in the [Common Transaction Flags](setup.md#common-transaction-flags) section, we can obtain gas costs for different staking transactions from the genesis file by running: - -```bash -cat $GENESIS_FILE | \ - python3 -c 'import sys, json; \ - print(json.dumps(json.load(sys.stdin)["staking"]["params"]["gas_costs"], indent=4))' -``` - -For our network, this returns: - -```javascript -{ - "add_escrow": 1000, - "burn": 1000, - "reclaim_escrow": 1000, - "transfer": 1000 -} -``` - -Hence, we will need to set the `--transaction.fee.gas` flag, i.e. the maximum amount of gas a transaction can spend, in the following transactions to at least 1000 **gas units**. - diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/get-account-info.md b/docs/general/manage-tokens/advanced/oasis-cli-tools/get-account-info.md deleted file mode 100644 index 2a72523622..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/get-account-info.md +++ /dev/null @@ -1,83 +0,0 @@ -# Get Account Info - -:::info - -This example assumes you have read and followed the instructions in the [Prerequisites](prerequisites.md) and [Setup](setup.md) sections. - -::: - -To get more information about a particular staking account, e.g. `oasis1qrvsa8ukfw3p6kw2vcs0fk9t59mceqq7fyttwqgx`, run: - -```bash -oasis-node stake account info \ - -a $ADDR \ - --stake.account.address oasis1qrvsa8ukfw3p6kw2vcs0fk9t59mceqq7fyttwqgx -``` - -This will output all staking information about this particular account, e.g.: - -``` -General Account: - Balance: ROSE 376.594833237 - Nonce: 0 -Escrow Account: - Active: - Balance: ROSE 10528.684187046 - Total Shares: 10000000000000 - Debonding: - Balance: ROSE 0.0 - Total Shares: 0 - Commission Schedule: - Rates: (none) - Rate Bounds: (none) - Stake Accumulator: - Claims: - - Name: registry.RegisterEntity - Staking Thresholds: - - Global: entity - - Name: registry.RegisterNode.9Epy5pYPGa91IJlJ8Ivb5iby+2ii8APXdfQoMZDEIDc= - Staking Thresholds: - - Global: node-validator -``` - -## General Account - -We can observe that: - -* General account's **balance**, the amount of tokens that are available to the account owner, is \~377 tokens. -* General account's **nonce**, the incremental number that must be unique for each account's transaction, is 0. That means there haven't been any transactions made with this account as the source. Therefore, the next transaction should have nonce equal to 0. - -## Escrow Account - -We can observe that: - -* The amount of tokens that are **actively bounded** to the escrow account is \~10529 tokens. -* The total number of **shares** for the tokens actively bounded to the escrow account is 10 trillion. -* The amount of tokens that are currently **debonding** is 0. -* The total number of **shares** for the tokens that are currently debonding is 0. - -### Commission Schedule - -An entity can also charge commission for tokens that are delegated to it. It would defined the commission schedule **rate steps** and the commission schedule **rate bound steps**. For more details, see the [Amend Commission Schedule](../../../../node/run-your-node/validator-node/amend-commission-schedule.md) documentation. - -### Stake Accumulator - -Each escrow account also has a corresponding stake accumulator. It stores **stake claims** for an escrow account and ensures 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 two claims: - -* The `registry.RegisterEntity` claim is for registering an entity. - - It needs to satisfy the global threshold for registering an entity (`entity`) which is defined by the staking consensus parameters. - - To see the value of the `entity` global staking threshold, run the `oasis-node stake info` command as described in [Common Staking Info](common-staking-info.md) doc. - -* The `registry.RegisterNode.9Epy5pYPGa91IJlJ8Ivb5iby+2ii8APXdfQoMZDEIDc=` claim is for registering the node with ID `9Epy5pYPGa91IJlJ8Ivb5iby+2ii8APXdfQoMZDEIDc=`. - - It needs to satisfy the global staking threshold for registering a validator node (`node-validator`) which is defined by the staking consensus parameters. - - To see the value of the `node-validator` global staking threshold, run the `oasis-node stake info` command as described in [Common Staking Info](common-staking-info.md) doc. - - In addition to the global thresholds, each runtime the node is registering for may define their own thresholds. In case the node is registering for multiple runtimes, it needs to satisfy the sum of thresholds of all the runtimes it is registering for. - - For more details, see [Oasis Core Developer Docs on registering a node](../../../../core/consensus/services/registry.md#register-node). diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/get-account-nonce.md b/docs/general/manage-tokens/advanced/oasis-cli-tools/get-account-nonce.md deleted file mode 100644 index a6dbc0c319..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/get-account-nonce.md +++ /dev/null @@ -1,35 +0,0 @@ -# Get Account Nonce - -:::info - -This example assumes you have read and followed the instructions in the [Prerequisites](prerequisites.md) and [Setup](setup.md) sections. - -::: - -To get more a particular staking account's, e.g. `oasis1qrvsa8ukfw3p6kw2vcs0fk9t59mceqq7fyttwqgx`, nonce, run: - -```bash -oasis-node stake account nonce \ - -a $ADDR \ - --stake.account.address oasis1qrvsa8ukfw3p6kw2vcs0fk9t59mceqq7fyttwqgx -``` - -### Get Your Entity's Nonce - -:::info - -This example assumes you have the [jq](https://stedolan.github.io/jq/) tool installed on your system. - -::: - -If you want to get your entity's nonce, you can use the following combination of commands: - -```bash -ENTITY_DIR= -ADDRESS=$(oasis-node stake pubkey2address --public_key \ - $(cat $ENTITY_DIR/entity.json | jq .id -r)) -NONCE=$(oasis-node stake account nonce --stake.account.address $ADDRESS -a $ADDR) -``` - -where `` is the path to your entity's descriptor, e.g. `/serverdir/node/entity/`. - diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/list-accounts.md b/docs/general/manage-tokens/advanced/oasis-cli-tools/list-accounts.md deleted file mode 100644 index 986321b242..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/list-accounts.md +++ /dev/null @@ -1,40 +0,0 @@ -# List Accounts - -:::info - -This example assumes you have read and followed the instructions in the [Prerequisites](prerequisites.md) and [Setup](setup.md) sections. - -::: - -To list all staking accounts with positive balance, run: - -```bash -oasis-node stake list -a $ADDR -``` - -This will list all accounts' addresses, e.g.: - -``` -oasis1qqqfalz4xars9nxn0mjy8fcf9quqg8ml0szm5ped -oasis1qqqd4wrmk8z9p3hz0vyc6zy3khx3gqnckywyg2s5 -oasis1qqqul8678xs9tnj74x54k8ch2qdh7jveeswqf67j -oasis1qqzrcyed78mkxmt9qpv3pemsugknnhvnpv8v5vc3 -oasis1qqz0qcmy932p69493qdkszcf9emgl55azys3xr8f -oasis1qq95xthkg20ra6ue8zyngqkkm92xqkvrms88axkj -oasis1qq9meupznk90d4lgluvcaqa27ggs55dscc6msc33 -oasis1qq9acq6v5knfmatc9fvuwyzlexs0f7j3uvarusu6 -oasis1qqxqlpfslwuuh5342qnstymyutancj7csucxv2ec -oasis1qqxmp9lggptm0pt23za7g5cfg2hzspezcumw7c3j -oasis1qq89qxh538sunk6p2fca487pfsy0ncxk9q4xf2un -oasis1qq8hgj2yzssawtpfqr8utj6d57k9zvx3wc989kqm -oasis1qq8atykwecy3p5rnspkweapzz847exaqwyv80wgx -oasis1qqgv5rxl4w27l89rf4j5dv8392kh42wt35yn0as6 -oasis1qqg0h3mt7klha4w2kxjvsktv5ke6suuwpg8rvpdh -oasis1qqf3ctyg49tnwclksxun3dzhrv4zuww7hu7w3cul -oasis1qqfasfrrx2tae50kcy8mcclhp0kqymswsqnqytyg -oasis1qq2rlaz3yjfk8gtdhnrfkrz5rrxjnnrzeq7mst0r - -... output trimmed ... -``` - -For more information on account's address format, see the [Terminology](../../terminology.md#address) doc. diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/prerequisites.md b/docs/general/manage-tokens/advanced/oasis-cli-tools/prerequisites.md deleted file mode 100644 index 58132062e2..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/prerequisites.md +++ /dev/null @@ -1,38 +0,0 @@ -# Prerequisites - -This sections lists the prerequisites for using your tokens. - -:::info - -Currently, the only supported and documented way to use your tokens is by utilizing the Oasis Node CLI in combination with: - -* [Ledger-based signer](../../../../oasis-core-ledger/README.md), or -* file-based signer. - -::: - -## Oasis Node CLI - -To setup Oasis Node CLI, follow the [Oasis Node documentation](../../../../node/run-your-node/prerequisites/oasis-node.md). - -## Ledger-based signer - -:::info - -This is only needed if you will use the [Ledger wallet](../../holding-rose-tokens/ledger-wallet.md) to hold your tokens. - -::: - -To use the Ledger-based signer in combination with Oasis Node CLI, follow the [Setup](../../../../oasis-core-ledger/usage/setup.md) guide in our [Oasis Core Ledger](../../../../oasis-core-ledger/README.md) docs. - -## File-based signer - -:::danger - -We strongly suggest that you do not use any entity/staking account that is generated with the file-based signer on the Mainnet. - -In case you need to use the file-based signer, make sure you only use it on an [offline/air-gapped machine](https://en.wikipedia.org/wiki/Air_gap_\(networking\)). Gaining access to your entity's/staking account's private key can compromise your tokens. - -::: - -There are no additional things needed since the file-based signer is a part of Oasis Node CLI. diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/reclaim-tokens.md b/docs/general/manage-tokens/advanced/oasis-cli-tools/reclaim-tokens.md deleted file mode 100644 index f3bfc01209..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/reclaim-tokens.md +++ /dev/null @@ -1,175 +0,0 @@ -# Reclaim Delegated/Staked Tokens - -:::info - -This example assumes you have read and followed the instructions in the [Prerequisites](prerequisites.md) and [Setup](setup.md) sections. - -::: - -When we want to reclaim escrowed tokens, we can't do that directly. Instead, we need to specify the number of shares we want to reclaim from an escrow account. - -Let's assume: - -* we want to reclaim 357 billion shares from our escrow account, -* `oasis1qr6swa6gsp2ukfjcdmka8wrkrwz294t7ev39nrw`is our staking account address. - -## Query Our Account's Info - -To query our staking account's information, use the following command: - -```bash -oasis-node stake account info \ - -a $ADDR \ - --stake.account.address oasis1qr6swa6gsp2ukfjcdmka8wrkrwz294t7ev39nrw6 -``` - -:::info - -For a detailed explanation on querying account information, see the [Get Info](get-account-info.md) section. - -::: - -Before the transaction, this outputs: - -``` -General Account: - Balance: ROSE 223.492486765 - Nonce: 9 -Escrow Account: - Active: - Balance: ROSE 11450.38481664 - Total Shares: 10185014125910 - Debonding: - Balance: ROSE 0.0 - Total Shares: 0 - ... -``` - -We can observe that: - -* General account's balance is ~223 tokens. -* Account's nonce is 9. -* ~11450 tokens are actively bounded to the escrow account. -* The amount of tokens that are currently debonding is 0. - -## Generate a Reclaim Escrow Transaction - -Let's generate a reclaim escrow transaction of 357 billion shares from our own escrow account and store it to `tx_reclaim.json`: - -```bash -oasis-node stake account gen_reclaim_escrow \ - "${TX_FLAGS[@]}" \ - --stake.shares 357000000000 \ - --stake.escrow.account oasis1qr6swa6gsp2ukfjcdmka8wrkrwz294t7ev39nrw6 \ - --transaction.file tx_reclaim.json \ - --transaction.nonce 9 \ - --transaction.fee.gas 1000 \ - --transaction.fee.amount 2000 -``` - -This will output a preview of the generated transaction: - -``` -You are about to sign the following transaction: - Nonce: 9 - Fee: - Amount: ROSE 0.000002 - Gas limit: 1000 - (gas price: ROSE 0.000000002 per gas unit) - Method: staking.ReclaimEscrow - Body: - Account: oasis1qr6swa6gsp2ukfjcdmka8wrkrwz294t7ev39nrw6 - Shares: 357000000000 -Other info: - Genesis document's hash: 976c302f696e417bd861b599e79261244f4391f3887a488212ee122ca7bbf0a8 -``` - -and ask you for confirmation. - -## Submit the Transaction - -To submit the generated transaction, we need to copy `tx_reclaim.json` to the online Oasis node (i.e. the `server`) and submit it from there: - -```bash -oasis-node consensus submit_tx \ - -a $ADDR \ - --transaction.file tx_reclaim.json -``` - -## Query Our Account's Info Again - -Let's check [our account's info](reclaim-tokens.md#query-our-accounts-info) again: - -``` -General Account: - Balance: ROSE 223.492486765 - Nonce: 10 -Escrow Account: - Active: - Balance: ROSE 11049.031678686 - Total Shares: 9828014125910 - Debonding: - Balance: ROSE 401.353137954 - Total Shares: 401353137954 - ... -``` - -We can observe that: - -* Our general account's balance decreased by 0.000002 token. This corresponds to the fee - - that we specified we will pay for this transaction. - -* Our account's nonce increased to 10. -* Our escrow account's active number of shares decreased by 357 billion shares - - to 9,828,014,125,910. - -* Our escrow account's active balance decreased by 401.353137954 tokens and - - is now 11049.031678686 tokens. - -* Our escrow account's debonding balance increased to 401.353137954 tokens - - and its number of shares to the same amount. - -### Computation of Reclaimed Tokens - -When a delegator wants to reclaim a certain number of escrowed tokens, the **token price** (in shares) must be calculated based on the escrow account's current active balance and the number of issued shares: - -``` -tokens_per_share = account_delegated_tokens / account_issued_shares -``` - -In our case, the current token price (i.e. `tokens_per_share`) is 11450.384816640 / 10,185,014,125,910 which is 1.124238481664054 * 10^-9 token per share. - -For 357 billion shares, the amount of tokens that will be reclaimed is thus 357 * 10^9 * 1.124238481664054 * 10^-9 which is 401.35313795406726 tokens (rounded to 401.353137954 tokens). - -Hence, the escrow account's active balance decreased by 401.353137954 tokens and the debonding balance increased by the same amount. - -:::caution - -While the number of debonding shares currently equals the number of base units that are currently subject to debonding and hence, the amount of tokens we can expect to reclaim after debonding period is over is a little over 401 tokens, there is no guarantee that this stays the same until the end of the debonding period. Any slashing (e.g. for double signing) could change shares' price. - -::: - -### Debonding Period - -The debonding period is specified by the `staking.params.debonding_interval` consensus parameter and is represented as a number of epochs that need to pass. - -To obtain its value from the genesis file, run: - -```bash -cat $GENESIS_FILE | \ - python3 -c 'import sys, json; \ - print(json.load(sys.stdin)["staking"]["params"]["debonding_interval"])' -``` - -For our example network, this returns: - -``` -10 -``` - -After the debonding period has passed, the network will automatically move an escrow account's debonding balance into the general account. - diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/setup.md b/docs/general/manage-tokens/advanced/oasis-cli-tools/setup.md deleted file mode 100644 index bf75effa92..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/setup.md +++ /dev/null @@ -1,141 +0,0 @@ -# Setup - -Make sure you have installed everything described in the [Prerequisites](prerequisites.md) section. - -## Server commands - -To run a command that requires a connection to an online Oasis node (i.e. the `server`), you need to either: - -* change the working directory to where the internal Oasis node UNIX socket is located (e.g. `/serverdir/node/`) before executing the command, or -* pass the `-a $ADDR` flag where `ADDR` represents the path to the internal Oasis node UNIX socket prefixed with `unix:` (e.g.`unix:/serverdir/node/internal.sock`). - -Here are some examples of Oasis Node CLI commands that need a connection to an online Oasis node: - -* `oasis-node stake info`: Shows general staking information. -* `oasis-node stake list`: Lists all accounts with positive balance. -* `oasis-node stake account info`: Shows detailed information for an account. -* `oasis-node consensus submit_tx`: Submits a pre-generated transaction to the network. - -## Local commands - -The following commands are intended to be run on your local machine and only need access to the [network's current genesis file](../../../../node/mainnet/README.md) and your signer's private key: - -* `oasis-node stake account gen_transfer` -* `oasis-node stake account gen_escrow` -* `oasis-node stake account gen_reclaim_escrow` -* `oasis-node stake account gen_amend_commission_schedule` - -:::danger - -We strongly suggest that you do not use any entity/staking account that is generated with the file-based signer on the Mainnet. - -In case you need to use the file-based signer, make sure you only use it on an [offline/air-gapped machine](https://en.wikipedia.org/wiki/Air_gap_\(networking\)). Gaining access to your entity's/staking account's private key can compromise your tokens. - -::: - -## JSON pretty-printing - -We will pipe the output of commands that return JSON through [Python's `json.tool` module](https://docs.python.org/3/library/json.html#module-json.tool) to pretty-print it. - -:::caution - -Be aware that [jq](https://stedolan.github.io/jq/), the popular JSON CLI tool, [converts all numbers to IEEE 754 64-bit values](https://github.com/stedolan/jq/wiki/FAQ#caveats) which can result in silent loss of precision and/or other changes. - -Hence, we recommend avoiding its usage until this issue is resolved. - -::: - -## Common CLI Flags - -### Base Flags - -All commands for generating and signing transactions need the following base flags set: - -* `--genesis.file`: Path to the genesis file, e.g. `/localhostdir/genesis.json`. - -For convenience, set the `GENESIS_FILE` environment value to its value, e.g.: - -```bash - GENESIS_FILE=/localhostdir/genesis.json -``` - -* `--signer.dir`: Path to entity's artifacts directory, e.g. `entity-$LEDGER_INDEX` - - or `/localhostdir/entity/` - -### Signer Flags - -Currently, we provide two options for signing transactions: - -* **Ledger-based signer.** - - You will need to set it up as described in our [Oasis Core Ledger](../../../../oasis-core-ledger/usage/transactions.md) docs. -* **File-based signer.** - - You will need to create your Entity as described in [Running a Node on the Network](../../../../node/run-your-node/validator-node/README.md#creating-your-entity) docs and set the following flags: - - * `--signer.backend file`: Specifies use of the file signer. - -### Storing Base and Signer flags in an Environment Variable - -To make the transaction commands shorter and avoid typing errors, one can create an environment variable, e.g. `TX_FLAGS`, with all the [Base Flags](setup.md#base-flags) and [Signer Flags](setup.md#signer-flags) configured for his particular set up. - -For example, one could set `TX_FLAGS` for a Ledger device like below (make sure all `LEDGER_*` environment variables are set appropriately): - -```bash -TX_FLAGS=(--genesis.file "$GENESIS_FILE" - --signer.dir /localhostdir/entity - --signer.backend plugin - --signer.plugin.name ledger - --signer.plugin.path "$LEDGER_SIGNER_PATH" -) -``` - -Or, one could set `TX_FLAGS` like below to use a file signer: - -```bash -TX_FLAGS=(--genesis.file "$GENESIS_FILE" - --signer.backend file - --signer.dir /localhostdir/entity/ -) -``` - -### Common Transaction Flags - -When generating a transaction, one needs to set the following transaction flags as appropriate for a given transaction: - -* `--stake.amount`: Amount of base units to transfer, escrow, burn, etc. -* `--transaction.file`: Path to the file where to store the generated transaction. -* `--transaction.nonce`: Incremental number that must be unique for each account's transaction. To - get your current account's nonce, see [Checking Your Account nonce](get-account-nonce.md) doc. -* `--transaction.fee.gas`: Maximum amount of gas (in _gas units_) a transaction can spend. - -Gas costs for different staking transactions are specified by the `staking.params.gas_costs` consensus parameter. - -To obtain its value from the genesis file, run: - -```bash - cat $GENESIS_FILE | \ - python3 -c 'import sys, json; \ - print(json.dumps(json.load(sys.stdin)["staking"]["params"]["gas_costs"], indent=4))' -``` - -* `--transaction.fee.amount`: Amount of base units we will pay as a fee for a transaction. - -Note that specifying a transaction's fee amount (via `--transaction.fee.amount`) and maximum gas amount (via `--transaction.fee.gas`) implicitly defines the _gas price_ (in base units): - -``` -gas_price = fee_amount / gas_amount -``` - -Gas price tells how much base units we are willing to pay for one gas unit. - -Consensus validators can configure their own _minimum gas price_ (via `consensus.tendermint.min_gas_price` configuration flag) and will refuse to process transactions that have their gas price set below their minimum gas price. - -:::info - -Currently, there is no mechanism to discover what minimum gas prices are used by validators. - -For more details, see [Oasis Core #2526](https://github.com/oasisprotocol/oasis-core/issues/2526). - -::: diff --git a/docs/general/manage-tokens/advanced/oasis-cli-tools/transfer-tokens.md b/docs/general/manage-tokens/advanced/oasis-cli-tools/transfer-tokens.md deleted file mode 100644 index 4fa468b659..0000000000 --- a/docs/general/manage-tokens/advanced/oasis-cli-tools/transfer-tokens.md +++ /dev/null @@ -1,170 +0,0 @@ -# Transfer Tokens - -:::info - -This example assumes you have read and followed the instructions in the [Prerequisites](prerequisites.md) and [Setup](setup.md) sections. - -::: - -Let's assume: - -* `oasis1qr6swa6gsp2ukfjcdmka8wrkrwz294t7ev39nrw6` is our staking account address, -* `oasis1qr3jc2yfhszpyy0daha2l9xjlkrxnzas0uaje4t3` is the destination's staking account address. - -:::info - -To convert your entity's ID to a staking account address, see the [Obtain Account Address From Entity's ID](address.md#obtain-account-address-from-entitys-id) section. - -::: - -## Query Our Account's Info - -To query our staking account's information, use the following command: - -```bash -oasis-node stake account info \ - -a $ADDR \ - --stake.account.address oasis1qr6swa6gsp2ukfjcdmka8wrkrwz294t7ev39nrw6 -``` - -:::info - -For a detailed explanation on querying account information, see the [Get Info](get-account-info.md) section. - -::: - -Before the transaction, this outputs: - -``` -General Account: - Balance: ROSE 601.492492765 - Nonce: 7 -Escrow Account: - Active: - Balance: ROSE 11242.38481664 - Total Shares: 10000000000000 - Debonding: - Balance: ROSE 0.0 - Total Shares: 0 - ... -``` - -We can observe that: - -* General account's balance is ~601 tokens. -* Account's nonce is 7. -* ~11242 tokens are actively bounded to the escrow account. -* The amount of tokens that are currently debonding is 0. - -## Query Destination Account's Info - -To query the destination account's information, use the following command: - -```bash -oasis-node stake account info \ - -a $ADDR \ - --stake.account.address oasis1qr3jc2yfhszpyy0daha2l9xjlkrxnzas0uaje4t3 -``` - -Before the transaction, this outputs: - -``` -General Account: - Balance: ROSE 0.0 - Nonce: 1030 -Escrow Account: - Active: - Balance: ROSE 0.0 - Total Shares: 0 - Debonding: - Balance: ROSE 0.0 - Total Shares: 0 - ... -``` - -We can observe that both, the general account and the escrow account (actively bounded and debonding), have a balance of 0 tokens. - -## Generate a Transfer Transaction - -Let's generate a transfer transaction of 170 tokens, (i.e. 170 * 10^9 base units), from our account to the chosen destination account and store it to `tx_transfer.json`: - -```bash -oasis-node stake account gen_transfer \ - "${TX_FLAGS[@]}" \ - --stake.amount 170000000000 \ - --stake.transfer.destination oasis1qr3jc2yfhszpyy0daha2l9xjlkrxnzas0uaje4t3 \ - --transaction.file tx_transfer.json \ - --transaction.nonce 7 \ - --transaction.fee.gas 1000 \ - --transaction.fee.amount 2000 -``` - -This will output a preview of the generated transaction: - -``` -You are about to sign the following transaction: - Nonce: 7 - Fee: - Amount: ROSE 0.000002 - Gas limit: 1000 - (gas price: ROSE 0.000000002 per gas unit) - Method: staking.Transfer - Body: - To: oasis1qr3jc2yfhszpyy0daha2l9xjlkrxnzas0uaje4t3 - Amount: ROSE 170.0 -Other info: - Genesis document's hash: 976c302f696e417bd861b599e79261244f4391f3887a488212ee122ca7bbf0a8 -``` - -and ask you for confirmation. - -## Submit the Transaction - -To submit the generated transaction, we need to copy `tx_transfer.json` to the online Oasis node (i.e. the `server`) and submit it from there: - -```bash -oasis-node consensus submit_tx \ - -a $ADDR \ - --transaction.file tx_transfer.json -``` - -## Query Both Accounts' Info - -Let's check both accounts' info, [first ours](transfer-tokens.md#query-our-accounts-info): - -``` -General Account: - Balance: ROSE 431.492490765 - Nonce: 8 -Escrow Account: - Active: - Balance: ROSE 11242.38481664 - Total Shares: 10000000000000 - Debonding: - Balance: ROSE 0.0 - Total Shares: 0 - ... -``` - -and then the [destination's](transfer-tokens.md#query-destination-accounts-info): - -``` -General Account: - Balance: ROSE 170.0 - Nonce: 1030 -Escrow Account: - Active: - Balance: ROSE 0.0 - Total Shares: 0 - Debonding: - Balance: ROSE 0.0 - Total Shares: 0 - ... -``` - -We can observe that: - -* Our general balance decreased by 170.000002 tokens. The 0.000002 token corresponds to the fee that we specified we will pay for this transaction. -* Our account's nonce increased to 8. -* Destination account's general balance increased by 170 tokens. - diff --git a/docs/general/manage-tokens/cli b/docs/general/manage-tokens/cli new file mode 120000 index 0000000000..2bb2935175 --- /dev/null +++ b/docs/general/manage-tokens/cli @@ -0,0 +1 @@ +../../../external/cli/docs \ No newline at end of file diff --git a/docs/general/manage-tokens/holding-rose-tokens/ledger-wallet.md b/docs/general/manage-tokens/holding-rose-tokens/ledger-wallet.md index b5b95cb37b..8ff8146416 100644 --- a/docs/general/manage-tokens/holding-rose-tokens/ledger-wallet.md +++ b/docs/general/manage-tokens/holding-rose-tokens/ledger-wallet.md @@ -158,4 +158,4 @@ Ledger is supported by the Oasis CLI. Follow the instructions in the [Nano S Plus]: https://support.ledger.com/hc/en-us/articles/4445777839901-Update-Ledger-Nano-S-Plus-firmware [BIP 39]: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki [Oasis Wallets]: ../oasis-wallets/README.mdx -[Oasis CLI Tools]: ../advanced/oasis-cli-tools/README.md +[Oasis CLI Tools]: ../cli/README.md diff --git a/docs/general/manage-tokens/how-to-transfer-rose-into-paratime.mdx b/docs/general/manage-tokens/how-to-transfer-rose-into-paratime.mdx index 653c289e3e..a7d9b85ef3 100644 --- a/docs/general/manage-tokens/how-to-transfer-rose-into-paratime.mdx +++ b/docs/general/manage-tokens/how-to-transfer-rose-into-paratime.mdx @@ -198,7 +198,7 @@ learn how to use Oasis CLI instead. ::: -[Oasis CLI]: advanced/oasis-cli-tools/deposit-withdraw-tokens-to-from-paratime.mdx +[Oasis CLI]: cli/account.md ### Verifying ParaTime deposits and withdrawals @@ -233,5 +233,5 @@ addresses, Token Transfers, Contract Calls, etc.), you have to use the findSidebarItem('/dapp/emerald/writing-dapps-on-emerald'), findSidebarItem('/dapp/sapphire/quickstart'), findSidebarItem('/dapp/cipher/'), - findSidebarItem('/general/manage-tokens/advanced/oasis-cli-tools/deposit-withdraw-tokens-to-from-paratime') + findSidebarItem('/general/manage-tokens/cli/account') ]} /> diff --git a/docs/general/manage-tokens/staking-and-delegating.md b/docs/general/manage-tokens/staking-and-delegating.md index 5472431d37..7287c3cf83 100644 --- a/docs/general/manage-tokens/staking-and-delegating.md +++ b/docs/general/manage-tokens/staking-and-delegating.md @@ -14,7 +14,7 @@ The Oasis Network is supported by an amazing community of validators and infrast ### Tools to use for Staking and Delegation -In addition to using the [Oasis CLI](advanced/oasis-cli-tools/README.md) for generating the `staking.AddEscrow` transaction, there is a number of wallets and custodians that support staking and delegation on the Oasis Network. Those include: +In addition to using the [Oasis CLI](cli/README.md) for generating the `staking.AddEscrow` transaction, there are a number of wallets and custodians that support staking and delegation on the Oasis Network. Those include: * [Oasis Wallet - Web](oasis-wallets/web.md) * [Oasis Wallet - Browser Extension](oasis-wallets/browser-extension.md) diff --git a/docs/general/manage-tokens/terminology.md b/docs/general/manage-tokens/terminology.md index 1d6fc7a986..8510726b12 100644 --- a/docs/general/manage-tokens/terminology.md +++ b/docs/general/manage-tokens/terminology.md @@ -68,7 +68,8 @@ if we manually deposited them). A portion of your delegated tokens can be **slashed** (seized) by the network, if the node that you delegated your tokens to gets slashed, e.g. as a penalty -for validating invalid blocks containing double signed transactions. +for equivocating in the protocol by signing diverging blocks for the same +height. [Bech32 encoding]: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#bech32 diff --git a/docs/get-involved/run-node/validator-node.md b/docs/get-involved/run-node/validator-node.md index 7712f482ec..ba0d394803 100644 --- a/docs/get-involved/run-node/validator-node.md +++ b/docs/get-involved/run-node/validator-node.md @@ -13,7 +13,7 @@ Hence, it needs a set of distributed node operators that run different nodes (in Make sure your system meets the [Hardware](../../node/run-your-node/prerequisites/hardware-recommendations.md) prerequisites and has [Oasis Node](../../node/run-your-node/prerequisites/oasis-node.md) installed. -Then proceed by following the [Run a Validator Node](../../node/run-your-node/validator-node/README.md) guide to: +Then proceed by following the [Run a Validator Node](../../node/run-your-node/validator-node.mdx) guide to: * Create your entity. * Initialize and configure your node. @@ -26,7 +26,7 @@ To become a validator on the Oasis Network, you need to have enough tokens stake :::info -For more information about obtaining information on your entity's account, see the [Account Get Info](../../general/manage-tokens/advanced/oasis-cli-tools/get-account-info.md) doc. +For more information about obtaining information on your entity's account, see the [Account Get Info](../../general/manage-tokens/cli/account.md#show) doc. ::: diff --git a/docs/node/README.mdx b/docs/node/README.mdx index 90531e6531..8180918aee 100644 --- a/docs/node/README.mdx +++ b/docs/node/README.mdx @@ -63,7 +63,7 @@ to use. [Hardware]: ./run-your-node/prerequisites/hardware-recommendations.md [System]: ./run-your-node/prerequisites/system-configuration.mdx [Oasis Node]: ./run-your-node/prerequisites/oasis-node.md -[Run a Validator Node]: ./run-your-node/validator-node/README.md +[Run a Validator Node]: ./run-your-node/validator-node.mdx [trusted execution environment (TEE)]: ./run-your-node/prerequisites/set-up-trusted-execution-environment-tee.md [Run a ParaTime node]: ./run-your-node/paratime-node.mdx [ParaTime client node]: ./run-your-node/paratime-node.mdx @@ -75,7 +75,7 @@ to use. findSidebarItem('/node/mainnet/'), findSidebarItem('/node/testnet/'), findSidebarItem('/node/run-your-node/prerequisites'), - findSidebarItem('/node/run-your-node/validator-node/'), + findSidebarItem('/node/run-your-node/validator-node'), findSidebarItem('/node/run-your-node/non-validator-node'), findSidebarItem('/node/web3'), ]} /> diff --git a/docs/node/mainnet/previous-upgrades/cobalt-upgrade.md b/docs/node/mainnet/previous-upgrades/cobalt-upgrade.md index 87650ac1ba..80d2bf54a2 100644 --- a/docs/node/mainnet/previous-upgrades/cobalt-upgrade.md +++ b/docs/node/mainnet/previous-upgrades/cobalt-upgrade.md @@ -72,7 +72,7 @@ The **`epochtime`**object will be removed since it became obsolete with the new Removing entities from **`registry.entities`** will effectively deregister them but the entities' accounts in **`staking.ledger`** will remain intact. -Deregistered entities can always re-register by submitting the [entity registration transaction](../../run-your-node/validator-node/README.md#generating-entity-registration-transaction) after the upgrade. +Deregistered entities can always re-register by submitting the [entity registration transaction](../../run-your-node/validator-node.mdx#generating-entity-registration-transaction) after the upgrade. ::: diff --git a/docs/node/mainnet/upgrade-log.md b/docs/node/mainnet/upgrade-log.md index 575f2a80aa..960ea3803a 100644 --- a/docs/node/mainnet/upgrade-log.md +++ b/docs/node/mainnet/upgrade-log.md @@ -158,8 +158,8 @@ oasis-node consensus submit_tx \ ``` [upgrade governance proposal]: ../../core/consensus/services/governance.md#submit-proposal -[your entity's nonce]: ../../general/manage-tokens/advanced/oasis-cli-tools/get-account-nonce.md#get-your-entitys-nonce -[Oasis CLI Tools Setup]: ../../general/manage-tokens/advanced/oasis-cli-tools/setup.md#storing-base-and-signer-flags-in-an-environment-variable +[your entity's nonce]: ../../general/manage-tokens/cli/account.md#show +[Oasis CLI Tools Setup]: ../../core/oasis-node/cli.md#storing-base-and-signer-flags-in-an-environment-variable [Installing Oasis App on Your Ledger Wallet]: ../../oasis-core-ledger/usage/setup#installing-oasis-app-on-your-ledger-wallet @@ -504,7 +504,7 @@ The output should look like: ] ``` -Obtain [your entity's nonce](../../general/manage-tokens/advanced/oasis-cli-tools/get-account-nonce.md#get-your-entitys-nonce) and store it in the `NONCE` variable. You can do that by running: +Obtain [your entity's nonce](../../general/manage-tokens/cli/account.md#show) and store it in the `NONCE` variable. You can do that by running: ```yaml ENTITY_DIR= @@ -528,7 +528,7 @@ oasis-node governance gen_cast_vote \ --transaction.fee.amount 2000 ``` -where `TX_FLAGS` refer to previously set base and signer flags as described in the [Oasis CLI Tools Setup](../../general/manage-tokens/advanced/oasis-cli-tools/setup.md#storing-base-and-signer-flags-in-an-environment-variable) doc. +where `TX_FLAGS` refer to previously set base and signer flags as described in the [Oasis CLI Tools Setup](../../core/oasis-node/cli.md#storing-base-and-signer-flags-in-an-environment-variable) doc. :::caution diff --git a/docs/node/run-your-node/advanced/copy-state-from-one-node-to-the-other.md b/docs/node/run-your-node/advanced/copy-state-from-one-node-to-the-other.md index 31d8a2b55d..6277344104 100644 --- a/docs/node/run-your-node/advanced/copy-state-from-one-node-to-the-other.md +++ b/docs/node/run-your-node/advanced/copy-state-from-one-node-to-the-other.md @@ -10,7 +10,7 @@ Another way to speed up bootstraping an Oasis Node is to sync the node using [St ::: -To bootstrap a new Oasis Node by copying state from a synced Oasis Node, first set up your new Oasis Node as a [Validator Node](../validator-node/README.md), a [Non-validator Node](../non-validator-node.md) or a [ParaTime Node](../paratime-node.mdx). +To bootstrap a new Oasis Node by copying state from a synced Oasis Node, first set up your new Oasis Node as a [Validator Node](../validator-node.mdx), a [Non-validator Node](../non-validator-node.md) or a [ParaTime Node](../paratime-node.mdx). :::caution diff --git a/docs/node/run-your-node/advanced/sync-node-using-state-sync.md b/docs/node/run-your-node/advanced/sync-node-using-state-sync.md index cf119480c8..6c7a8a1723 100644 --- a/docs/node/run-your-node/advanced/sync-node-using-state-sync.md +++ b/docs/node/run-your-node/advanced/sync-node-using-state-sync.md @@ -1,6 +1,6 @@ # Using State Sync for Quick Bootstraping -The State Sync is a way to **quickly bootstrap** a **full Oasis node** (either a [validator node](../validator-node/README.md) or a [non-validator node](../non-validator-node.md)) by using [Tendermint's Light Client protocol](https://docs.tendermint.com/main/tendermint-core/light-client.html). It allows one to initialize a node from a trusted height, its corresponding block's header and a trusted validator set (given in the [genesis document](../../genesis-doc.md)). It does so by securely updating the node's trusted state by requesting and verifying a minimal set of data from the network's full nodes. +The State Sync is a way to **quickly bootstrap** a **full Oasis node** (either a [validator node](../validator-node.mdx) or a [non-validator node](../non-validator-node.md)) by using [Tendermint's Light Client protocol](https://docs.tendermint.com/main/tendermint-core/light-client.html). It allows one to initialize a node from a trusted height, its corresponding block's header and a trusted validator set (given in the [genesis document](../../genesis-doc.md)). It does so by securely updating the node's trusted state by requesting and verifying a minimal set of data from the network's full nodes. :::info diff --git a/docs/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer.md b/docs/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer.md index 015c2b6bed..b1a9adeab7 100644 --- a/docs/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer.md +++ b/docs/node/run-your-node/advanced/using-ledger-backed-consensus-key-with-a-remote-signer.md @@ -1,6 +1,6 @@ # Using Ledger-backed Consensus Key with a Remote Signer -This guide will describe how you can set up your [_validator_ node](../validator-node/README.md) with a detached consensus key stored on a [Ledger](https://www.ledger.com) wallet connected via [Oasis Core's Remote Signer](https://github.com/oasisprotocol/oasis-core/tree/master/go/oasis-remote-signer). +This guide will describe how you can set up your [_validator_ node](../validator-node.mdx) with a detached consensus key stored on a [Ledger](https://www.ledger.com) wallet connected via [Oasis Core's Remote Signer](https://github.com/oasisprotocol/oasis-core/tree/master/go/oasis-remote-signer). :::caution @@ -106,7 +106,7 @@ For the Oasis node system to be able to connect to the Oasis Remote Signer on th ## Set Up Oasis Node System -For setting up your Oasis Node system, follow the [Run a Validator Node](../validator-node/README.md) docs. +For setting up your Oasis Node system, follow the [Run a Validator Node](../validator-node.mdx) docs. :::info @@ -116,7 +116,7 @@ Make sure you've copied the remote signer's certificate and remote signer's clie ### Initialize Oasis Node -When [initializing your Oasis node](../validator-node/README.md#initializing-a-node), you need to pass appropriate `--signer.*` flags to configure the composite and remote signers. For example: +When [initializing your Oasis node](../validator-node.mdx#initializing-a-node), you need to pass appropriate `--signer.*` flags to configure the composite and remote signers. For example: ``` ENTITY_DIR= @@ -146,7 +146,7 @@ The resulting directory only has `consensus_pub.pem` and no `consensus.pem` sinc ### Configure Oasis Node -When [configuring your Oasis Node](../validator-node/README.md#configuring-the-oasis-node), you need to add the appropriate `signer` section to configure the composite and remote signers. For example: +When [configuring your Oasis Node](../validator-node.mdx#configuring-the-oasis-node), you need to add the appropriate `signer` section to configure the composite and remote signers. For example: ```yaml # Signer. diff --git a/docs/node/run-your-node/keymanager-node/README.md b/docs/node/run-your-node/keymanager-node/README.md index cacf7925c6..c98c369e0c 100644 --- a/docs/node/run-your-node/keymanager-node/README.md +++ b/docs/node/run-your-node/keymanager-node/README.md @@ -2,7 +2,7 @@ :::info -These instructions are for setting up a _key manager_ node. Key manager nodes run a special runtime that provides confidentiality to other ParaTimes. If you want to run a _validator_ node instead, see the [instructions for running a validator node](../validator-node/README.md). Similarly, if you want to run a _ParaTime_ node instead, see the [instructions for running a ParaTime node](../paratime-node.mdx). +These instructions are for setting up a _key manager_ node. Key manager nodes run a special runtime that provides confidentiality to other ParaTimes. If you want to run a _validator_ node instead, see the [instructions for running a validator node](../validator-node.mdx). Similarly, if you want to run a _ParaTime_ node instead, see the [instructions for running a ParaTime node](../paratime-node.mdx). ::: @@ -33,7 +33,7 @@ Before following this guide, make sure you've followed the [Prerequisites](../pr :::tip -Reading the rest of the [validator node setup instructions](../validator-node/README.md) and [ParaTime node setup instructions](../paratime-node.mdx) may also be useful. +Reading the rest of the [validator node setup instructions](../validator-node.mdx) and [ParaTime node setup instructions](../paratime-node.mdx) may also be useful. ::: diff --git a/docs/node/run-your-node/maintenance/handling-network-upgrades.md b/docs/node/run-your-node/maintenance/handling-network-upgrades.md index 64a6e196e1..015c1ba935 100644 --- a/docs/node/run-your-node/maintenance/handling-network-upgrades.md +++ b/docs/node/run-your-node/maintenance/handling-network-upgrades.md @@ -72,7 +72,7 @@ and observe the value of the `consensus.latest_height` and ::: -[governance proposal]: ../validator-node/governance.md +[governance proposal]: ../../../general/manage-tokens/cli/network.md#governance-cast-vote Once the upgrade epoch is reached, follow the instructions in the corresponding [upgrade log]. diff --git a/docs/node/run-your-node/non-validator-node.md b/docs/node/run-your-node/non-validator-node.md index bab543badc..b26b120d17 100644 --- a/docs/node/run-your-node/non-validator-node.md +++ b/docs/node/run-your-node/non-validator-node.md @@ -2,7 +2,7 @@ :::info -These instructions are for setting up a _non-validator_ node. If you want to run a _validator_ node instead, see the [instructions for running a validator node](validator-node/README.md). Similarly, if you want to run a _ParaTime_ node instead, see the [instructions for running a ParaTime node](paratime-node.mdx). +These instructions are for setting up a _non-validator_ node. If you want to run a _validator_ node instead, see the [instructions for running a validator node](validator-node.mdx). Similarly, if you want to run a _ParaTime_ node instead, see the [instructions for running a ParaTime node](paratime-node.mdx). ::: diff --git a/docs/node/run-your-node/paratime-client-node.mdx b/docs/node/run-your-node/paratime-client-node.mdx index 4d9e626434..0f457639f5 100644 --- a/docs/node/run-your-node/paratime-client-node.mdx +++ b/docs/node/run-your-node/paratime-client-node.mdx @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; :::info -These instructions are for setting up a _ParaTime client_ node which only observes ParaTime activity and can submit transactions. If you want to run a _ParaTime_ node instead, see the [instructions for running a ParaTime node](paratime-node.mdx). Similarly, if you want to run a _validator_ or a _non-validator_ node instead, see the [instructions for running a validator node](validator-node/README.md) or [instructions for running a non-validator node](non-validator-node.md). +These instructions are for setting up a _ParaTime client_ node which only observes ParaTime activity and can submit transactions. If you want to run a _ParaTime_ node instead, see the [instructions for running a ParaTime node](paratime-node.mdx). Similarly, if you want to run a _validator_ or a _non-validator_ node instead, see the [instructions for running a validator node](validator-node.mdx) or [instructions for running a non-validator node](non-validator-node.md). ::: diff --git a/docs/node/run-your-node/paratime-node.mdx b/docs/node/run-your-node/paratime-node.mdx index ec2df0eb95..c8200b269a 100644 --- a/docs/node/run-your-node/paratime-node.mdx +++ b/docs/node/run-your-node/paratime-node.mdx @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; :::info -These instructions are for setting up a _ParaTime_ node which participates in one or more ParaTime compute committees. If you want to run a _ParaTime client_ node instead, see the [instructions for running a ParaTime client node](paratime-client-node.mdx). If you want to run a _validator_ node instead, see the [instructions for running a validator node](validator-node/README.md). Similarly, if you want to run a non-validator node instead, see the [instructions for running a non-validator node](non-validator-node.md). +These instructions are for setting up a _ParaTime_ node which participates in one or more ParaTime compute committees. If you want to run a _ParaTime client_ node instead, see the [instructions for running a ParaTime client node](paratime-client-node.mdx). If you want to run a _validator_ node instead, see the [instructions for running a validator node](validator-node.mdx). Similarly, if you want to run a non-validator node instead, see the [instructions for running a non-validator node](non-validator-node.md). ::: @@ -54,7 +54,7 @@ Just make sure to use the correct working directory path in the instructions bel :::tip -Reading the rest of the [validator node setup instructions](validator-node/README.md) may also be useful. +Reading the rest of the [validator node setup instructions](validator-node.mdx) may also be useful. ::: @@ -112,13 +112,13 @@ change in the future. ::: [Run a ParaTime Node]: ../../get-involved/run-node/paratime-node.mdx -[Common Staking Info]: ../../general/manage-tokens/advanced/oasis-cli-tools/common-staking-info.md -[Oasis CLI tools]: ../../general/manage-tokens/advanced/oasis-cli-tools/delegate-tokens.md -[Oasis Node Stake Account Info]: ../../general/manage-tokens/advanced/oasis-cli-tools/get-account-info.md +[Common Staking Info]: ../../general/manage-tokens/cli/network.md#show-native-token +[Oasis CLI tools]: ../../general/manage-tokens/cli/account.md#delegate +[Oasis Node Stake Account Info]: ../../general/manage-tokens/cli/account.md#show ### Register a New Entity or Update Your Entity Registration -If you don't have an entity yet, create a new one by following the [Creating Your Entity](validator-node/README.md#creating-your-entity) instructions. +If you don't have an entity yet, create a new one by following the [Creating Your Entity](validator-node.mdx#creating-your-entity) instructions. :::danger @@ -126,7 +126,7 @@ Everything in this section should be done on the `localhost` as there are sensit ::: -If you will be running the ParaTime on a new Oasis Node, initialize a new node by following the [Initializing a Node](validator-node/README.md#initializing-a-node) instructions. +If you will be running the ParaTime on a new Oasis Node, initialize a new node by following the [Initializing a Node](validator-node.mdx#initializing-a-node) instructions. Then update your entity descriptor by enumerating paths to all your node's descriptors (existing and new ones) in the `--entity.node.descriptor` flag. For example: @@ -161,7 +161,7 @@ For example: ::: -Then generate and submit the new/updated entity descriptor via the entity registration transaction by following the [Generating Entity Registration Transaction](validator-node/README.md#generating-entity-registration-transaction) instructions. +Then generate and submit the new/updated entity descriptor via the entity registration transaction by following the [Generating Entity Registration Transaction](validator-node.mdx#generating-entity-registration-transaction) instructions. :::caution @@ -179,7 +179,7 @@ No manual node registration is necessary. :::info -ParaTime rewards for running the compute node will be sent to your entity address **inside the ParaTime**. To access the rewards on the consensus layer, you will need to withdraw them first. Read the [Deposit/Withdraw Tokens to/from ParaTime](../../general/manage-tokens/advanced/oasis-cli-tools/deposit-withdraw-tokens-to-from-paratime.mdx) chapter to learn more. +ParaTime rewards for running the compute node will be sent to your entity address **inside the ParaTime**. To access the rewards on the consensus layer, you will need to withdraw them first. Read the [Deposit/Withdraw Tokens to/from ParaTime](../../general/manage-tokens/cli/account.md) chapter to learn more. ::: diff --git a/docs/node/run-your-node/prerequisites/hardware-recommendations.md b/docs/node/run-your-node/prerequisites/hardware-recommendations.md index 6ce1cc2ef5..5e96d6a606 100644 --- a/docs/node/run-your-node/prerequisites/hardware-recommendations.md +++ b/docs/node/run-your-node/prerequisites/hardware-recommendations.md @@ -168,7 +168,7 @@ parameters appropriately in your [node's configuration]. [Damask upgrade]: ../../mainnet/damask-upgrade.md [Emerald Mainnet launch]: https://medium.com/oasis-protocol-project/oasis-emerald-evm-paratime-is-live-on-mainnet-13afe953a4c9 -[node's configuration]: ../validator-node/README.md#configuring-the-oasis-node +[node's configuration]: ../validator-node.mdx#configuring-the-oasis-node ### Network diff --git a/docs/node/run-your-node/prerequisites/stake-requirements.md b/docs/node/run-your-node/prerequisites/stake-requirements.md index 4891953824..f1db38ea3d 100644 --- a/docs/node/run-your-node/prerequisites/stake-requirements.md +++ b/docs/node/run-your-node/prerequisites/stake-requirements.md @@ -22,14 +22,13 @@ such as [Oasis Scan]. For more information about obtaining information on your entity's account, see the [Account Get Info] doc. -Staking thresholds may change in the future. Read [Common staking info] chapter, -to learn how to check the current network thresholds directly from the -`oasis-node`. +Staking thresholds may change in the future. Read the +[native token information] to see the current values used by the network. [staking thresholds]: ../../genesis-doc.md#staking-thresholds [Oasis Scan]: https://www.oasisscan.com/validators -[Account Get Info]: ../../../general/manage-tokens/advanced/oasis-cli-tools/get-account-info.md -[Common staking info]: ../../../general/manage-tokens/advanced/oasis-cli-tools/common-staking-info.md +[Account Get Info]: ../../../general/manage-tokens/cli/account.md#show +[native token information]: ../../../general/manage-tokens/cli/network.md#show-native-token :::info diff --git a/docs/node/run-your-node/sentry-node.md b/docs/node/run-your-node/sentry-node.md index 7e6edc11a4..698dd40175 100644 --- a/docs/node/run-your-node/sentry-node.md +++ b/docs/node/run-your-node/sentry-node.md @@ -12,7 +12,7 @@ This is only an example of a Sentry node deployment, and we take no responsibili ## Prerequisites -Before following this guide, make sure you've read the [Prerequisites](prerequisites/oasis-node.md) and [Running a Node on the Network](validator-node/README.md) guides and created your Entity. +Before following this guide, make sure you've read the [Prerequisites](prerequisites/oasis-node.md) and [Running a Node on the Network](validator-node.mdx) guides and created your Entity. ## Configuring the Oasis Sentry Node @@ -152,7 +152,7 @@ If your validator node is already registered and running in a non-sentry setup, ::: -When you are [initializing a validator node](validator-node/README.md#initializing-a-node), you should use the sentry node's external address and Consensus ID in the `node.consensus_address` flag. If you are running multiple sentry nodes, you can specify the `node.consensus_address` flag multiple times. +When you are [initializing a validator node](validator-node.mdx#initializing-a-node), you should use the sentry node's external address and Consensus ID in the `node.consensus_address` flag. If you are running multiple sentry nodes, you can specify the `node.consensus_address` flag multiple times. To initialize a validator node with 2 sentry nodes, run the following commands from the `/localhostdir/node` directory: diff --git a/docs/node/run-your-node/validator-node/README.md b/docs/node/run-your-node/validator-node.mdx similarity index 94% rename from docs/node/run-your-node/validator-node/README.md rename to docs/node/run-your-node/validator-node.mdx index a1aee643f5..af67a1dd42 100644 --- a/docs/node/run-your-node/validator-node/README.md +++ b/docs/node/run-your-node/validator-node.mdx @@ -1,22 +1,25 @@ +import DocCard from '@theme/DocCard'; +import {findSidebarItem} from '@site/src/sidebarUtils'; + # Validator Node -This guide will walk you through the process of setting up your **validator node** -for the Oasis Network on either the Mainnet or the Testnet. It is designed for -individuals who have a basic understanding of command line tools. +This guide will walk you through the process of setting up your **validator node** +for the Oasis Network on either the Mainnet or the Testnet. It is designed for +individuals who have a basic understanding of command line tools. ## Prerequisites -Before proceeding with this guide, ensure that you have completed the steps +Before proceeding with this guide, ensure that you have completed the steps outlined in the [Prerequisites] section so that: * your system meets the [hardware requirements], * you have the [Oasis Node binary] installed on your systems, * you understand what are [Stake requirements] to become a validator on the Oasis Network. -[Prerequisites]: ../prerequisites/ -[hardware requirements]: ../prerequisites/hardware-recommendations.md -[Oasis Node binary]: ../prerequisites/oasis-node.md -[Stake requirements]: ../prerequisites/stake-requirements.md +[Prerequisites]: prerequisites/ +[hardware requirements]: prerequisites/hardware-recommendations.md +[Oasis Node binary]: prerequisites/oasis-node.md +[Stake requirements]: prerequisites/stake-requirements.md ## Physical Machines @@ -38,7 +41,7 @@ such as the [Ledger wallet]. ../../../general/manage-tokens/holding-rose-tokens/ledger-wallet **Server:** After the entity has been created, proceed to [set up the server in - order to start the Oasis node]. The server needs to meet the hardware + order to start the Oasis node]. The server needs to meet the hardware requirements and have an acces to the internet. [create your entity]: #creating-your-entity @@ -104,7 +107,7 @@ Then, set the environment variable that points to its path as follows: GENESIS_FILE_PATH=/localhostdir/genesis.json ``` -[Network Parameters]: ../../mainnet/README.md +[Network Parameters]: ../mainnet/README.md ### Initializing an Entity @@ -114,9 +117,9 @@ An entity is critical to operating nodes on the network as it controls the stake The Ledger-based signer stores your private keys on your Ledger wallet. It is implemented as an Oasis Core signer plugin. -You will need to set it up as described in the [Setup](../../../oasis-core-ledger/usage/setup.md) section of our [Oasis Core Ledger docs](../../../oasis-core-ledger). +You will need to set it up as described in the [Setup](../../oasis-core-ledger/usage/setup.md) section of our [Oasis Core Ledger docs](../../../oasis-core-ledger). -As the entity's private key is stored on your Ledger wallet, you only need to export the entity's public key as described in [Exporting Public Key to Entity](../../../oasis-core-ledger/usage/entity.md) section of our [Oasis Core Ledger docs](../../../oasis-core-ledger). +As the entity's private key is stored on your Ledger wallet, you only need to export the entity's public key as described in [Exporting Public Key to Entity](../../oasis-core-ledger/usage/entity.md) section of our [Oasis Core Ledger docs](../../../oasis-core-ledger). This will create 1 file in `/localhostdir/entity`: @@ -288,7 +291,7 @@ We will also need to have the public entity artifacts from the `/localhostdir` p #### Copying the Genesis File to the server -The latest Genesis file can be found in the [Network Parameters](../../mainnet/README.md). You should download the latest `genesis.json` file and copy it to `/serverdir/etc/genesis.json` on the `server`. +The latest Genesis file can be found in the [Network Parameters](../mainnet/README.md). You should download the latest `genesis.json` file and copy it to `/serverdir/etc/genesis.json` on the `server`. #### Configuring the Oasis Node @@ -300,13 +303,13 @@ Before using this configuration you should collect the following information to :::info -If you are using a [Sentry Node](../sentry-node.md), you should use the public IP of that machine. +If you are using a [Sentry Node](sentry-node.md), you should use the public IP of that machine. ::: * `{{ seed_node_address }}`: The seed node address in the form `ID@IP:port`. - You can find the current Oasis Seed Node address in the [Network Parameters](../../mainnet/README.md). + You can find the current Oasis Seed Node address in the [Network Parameters](../mainnet/README.md). To use this configuration, save it in the `/serverdir/etc/config.yml` file and pass it to the `oasis-node` command as an argument to the `--config` flag. @@ -454,7 +457,7 @@ This step is not necessary if your entity was fully staked at genesis. :::caution -If you've submitted staking or registry transactions before, your nonce is likely different than the nonce used in the examples. If you're uncertain, please check your account nonce by using [this guide](../../../general/manage-tokens/advanced/oasis-cli-tools/get-account-info.md). +If you've submitted staking or registry transactions before, your nonce is likely different than the nonce used in the examples. If you're uncertain, please check your account nonce by using [this guide](../../general/manage-tokens/cli/account.md#show). ::: @@ -507,7 +510,7 @@ Before generating the escrow transaction, you need to set the following environm For this guide, we will use `/localhostdir/signed-escrow.tx`. * `ACCOUNT_ADDRESS`: Your staking account address. - To obtain your staking account address from your Entity's ID, see [Obtaining Account Address From Entity's ID](../../../general/manage-tokens/advanced/oasis-cli-tools/address.md#obtain-account-address-from-entitys-id). + To obtain your staking account address from your Entity's ID, see [Obtaining Account Address From Entity's ID](../../general/manage-tokens/cli/account.md#from-public-key). Then execute the following command: @@ -528,7 +531,7 @@ oasis-node stake account gen_escrow \ The option `--stake.amount` looks like a very large number, but this is actually just an equivalent to 200 tokens on the Oasis consensus layer as each unit value used to track the account balance is 1x10^-9 tokens. -The `--transactions.fee.gas` and `--transaction.fee.amount` options depend on the network configuration, see [Common Transaction Flags](../../../general/manage-tokens/advanced/oasis-cli-tools/setup.md#common-transaction-flags) for details. +The `--transactions.fee.gas` and `--transaction.fee.amount` options depend on the network configuration, see [Common Transaction Flags](../../core/oasis-node/cli.md#common-transaction-flags) for details. ::: @@ -563,7 +566,7 @@ oasis-node registry entity gen_register \ :::info -The `--transactions.fee.gas` and `--transaction.fee.amount` options depend on the network configuration, see [Common Transaction Flags](../../../general/manage-tokens/advanced/oasis-cli-tools/setup.md#common-transaction-flags) for details. +The `--transactions.fee.gas` and `--transaction.fee.amount` options depend on the network configuration, see [Common Transaction Flags](../../core/oasis-node/cli.md#common-transaction-flags) for details. ::: @@ -659,3 +662,8 @@ operator's avatar. [Metadata Registry]: https://github.com/oasisprotocol/metadata-registry [Oasis Scan]: https://www.oasisscan.com/validators + +# See also + + + diff --git a/docs/node/run-your-node/validator-node/amend-commission-schedule.md b/docs/node/run-your-node/validator-node/amend-commission-schedule.md deleted file mode 100644 index 91048875f3..0000000000 --- a/docs/node/run-your-node/validator-node/amend-commission-schedule.md +++ /dev/null @@ -1,232 +0,0 @@ -# Amend Commission Schedule - -:::info - -This example assumes you have read and followed the instructions in the [Prerequisites](../../../general/manage-tokens/advanced/oasis-cli-tools/prerequisites.md) and [Setup](../../../general/manage-tokens/advanced/oasis-cli-tools/setup.md) sections of the _Use Your Tokens_ docs. - -::: - -We can configure our account to take a commission on staking rewards given to our node(s). The **commission rate** must be within **commission rate bounds**, which we can also configure. - -Let's assume: - -* we want to change our commission rate bounds to allow us to set any rate between 0% - 25%, and -* change our commission rate to 10%, -* `oasis1qr6swa6gsp2ukfjcdmka8wrkrwz294t7ev39nrw6`is our staking account address. - -We're not allowed to change the commission bounds too close in near future, so we'd have to make changes a number of epochs in the future. - -## Commission Schedule Rules - -The commission schedule rules are specified by the `staking.params.commission_schedule_rules` consensus parameter. - -To obtain its value from the genesis file, run: - -```bash -cat $GENESIS_FILE | \ - python3 -c 'import sys, json; \ - rules = json.load(sys.stdin)["staking"]["params"]["commission_schedule_rules"]; \ - print(json.dumps(rules, indent=4))' -``` - -For our example network this returns: - -```javascript -{ - "rate_change_interval": 1, - "rate_bound_lead": 336, - "max_rate_steps": 10, - "max_bound_steps": 10 -} -``` - -This means that we must submit a commission rate bound at least 336 epochs in advance (`rate_bound_lead`) and that we can change a commission rate on every epoch (`rate_change_interval`). - -The `max_rate_steps` and `max_bound_steps` determine the maximum number of commission rate steps and rate bound steps, respectively. - -## Query Our Account's Info - -To query our staking account's information, use the following command: - -```bash -oasis-node stake account info \ - -a $ADDR \ - --stake.account.address oasis1qr6swa6gsp2ukfjcdmka8wrkrwz294t7ev39nrw6 -``` - -:::info - -For a detailed explanation on querying account information, see the [Get Info](../../../general/manage-tokens/advanced/oasis-cli-tools/get-account-info.md) section of the _Use Your Tokens_ docs. - -::: - -Before the transaction, this outputs: - -```javascript -General Account: - ... - Nonce: 10 -Escrow Account: - ... - Commission Schedule: - Rates: (none) - Rate Bounds: (none) - ... -``` - -We can observe that: - -* Account's nonce is 10. -* No commissions rates or bounds are currently set. - -## Generate an Amend Commission Schedule Transaction - -In this example, we'll set the bounds to start on epoch 1500. An account's default bounds are 0% maximum, so we have to wait until our new bounds go into effect to raise our rate to 10%. Because of that, we'll specify that our rate also starts on epoch 1500. - -Let's generate an amend commission schedule transaction for this example and store it to `tx_amend_commission_schedule.json`: - -```bash -oasis-node stake account gen_amend_commission_schedule \ - "${TX_FLAGS[@]}" \ - --stake.commission_schedule.bounds 1500/0/25000 \ - --stake.commission_schedule.rates 1500/10000 \ - --transaction.file tx_amend_commission_schedule.json \ - --transaction.nonce 10 \ - --transaction.fee.gas 1000 \ - --transaction.fee.amount 2000 -``` - -:::info - -Rates and minimum/maximum rates are in units of 1/100,000, so `0`, `50000`, and `100000` come out to 0%, 50%, and 100%, respectively. - -::: - -This will output a preview of the generated transaction: - -```javascript -You are about to sign the following transaction: - Nonce: 10 - Fee: - Amount: ROSE 0.000002 - Gas limit: 1000 - (gas price: ROSE 0.000000002 per gas unit) - Method: staking.AmendCommissionSchedule - Body: - Amendment: - Rates: - (1) start: epoch 1500 - rate: 10.0% - Rate Bounds: - (1) start: epoch 1500 - minimum rate: 0.0% - maximum rate: 25.0% -Other info: - Genesis document's hash: 976c302f696e417bd861b599e79261244f4391f3887a488212ee122ca7bbf0a8 -``` - -and ask you for confirmation. - -## Submit the Transaction - -To submit the generated transaction, we need to copy `tx_amend_commission_schedule.json` to the online Oasis node (i.e. the `server`) and submit it from there: - -```bash -oasis-node consensus submit_tx \ - -a $ADDR \ - --transaction.file tx_amend_commission_schedule.json -``` - -## Query Our Account's Info Again - -Let's check [our account's info](amend-commission-schedule.md#query-our-accounts-info) again: - -```javascript -General Account: - ... - Nonce: 11 -Escrow Account: - ... - Commission Schedule: - Rates: - (1) start: epoch 1500 - rate: 10.0% - Rate Bounds: - (1) start: epoch 1500 - minimum rate: 0.0% - maximum rate: 25.0% - ... -``` - -We can observe that: - -* Our account's nonce increased to 11. -* We set the commission rate of 10.0% to start on epoch 1500. -* We set the commission rate bounds of 0% - 25% to also start on epoch 1500. - -:::info - -For more information on how commissions work in general, see the [Commission](../../../general/manage-tokens/terminology.md#commission) explanation in the _Use Your Tokens_ docs. - -::: - -## Setting a More Complex Commission Schedule - -It is also possible to set multiple commission rate steps and rate bound steps by passing the `--stake.commission_schedule.rates` and `--stake.commission_schedule.bounds` CLI flags multiple times. - -For example, setting multiple commission rate steps and rate bound steps (for the same account as in the previous example) as follows: - -``` -oasis-node stake account gen_amend_commission_schedule \ - "${TX_FLAGS[@]}" \ - --stake.commission_schedule.bounds 2000/10000/30000 \ - --stake.commission_schedule.bounds 3000/20000/40000 \ - --stake.commission_schedule.rates 2000/15000 \ - --stake.commission_schedule.rates 2200/20000 \ - --stake.commission_schedule.rates 2500/25000 \ - --stake.commission_schedule.rates 2800/30000 \ - --stake.commission_schedule.rates 3000/35000 \ - --transaction.file tx_amend_commission_schedule.json \ - --transaction.nonce 11 \ - --transaction.fee.gas 1000 \ - --transaction.fee.amount 2000 -``` - -would result in the following commission schedule being printed out in [our account's info](amend-commission-schedule.md#query-our-accounts-info): - -``` -... -Escrow Account: - ... - Commission Schedule: - Rates: - (1) start: epoch 1500 - rate: 10.0% - (2) start: epoch 2000 - rate: 15.0% - (3) start: epoch 2200 - rate: 20.0% - (4) start: epoch 2500 - rate: 25.0% - (5) start: epoch 2800 - rate: 30.0% - (6) start: epoch 3000 - rate: 35.0% - Rate Bounds: - (1) start: epoch 1500 - minimum rate: 0.0% - maximum rate: 25.0% - (2) start: epoch 2000 - minimum rate: 10.0% - maximum rate: 30.0% - (3) start: epoch 3000 - minimum rate: 20.0% - maximum rate: 40.0% - ... -``` - -:::info - -To troubleshoot an amendment that's rejected, consult our [compendium of 23 common ways for a commission schedule amendment to fail](https://github.com/oasisprotocol/oasis-core/blob/0dee03d75b3e8cfb36293fbf8ecaaec6f45dd3a5/go/staking/api/commission_test.go#L61-L610). - -::: diff --git a/docs/node/run-your-node/validator-node/governance.md b/docs/node/run-your-node/validator-node/governance.md deleted file mode 100644 index 19910eb4d9..0000000000 --- a/docs/node/run-your-node/validator-node/governance.md +++ /dev/null @@ -1,127 +0,0 @@ -# Governance - -:::info - -This example assumes you have read and followed the instructions in the [Prerequisites](../../../general/manage-tokens/advanced/oasis-cli-tools/prerequisites) and [Setup](../../../general/manage-tokens/advanced/oasis-cli-tools/setup.md) sections of the _Use Your Tokens_ docs. - -::: - -## Listing Active Proposals - -In order to list all active governance proposals, you can use the following command: - -```bash -oasis-node governance list_proposals -a $ADDR -``` - -In case there are currently any active proposals this should return a list of them similar to the following: - -```javascript -[{ - "id":1, - "submitter":"oasis1qrs2dl6nz6fcxxr3tq37laxlz6hxk6kuscnr6rxj", - "state":"active", - "deposit":"10000000000000", - "content":{ - "upgrade":{ - "v":1, - "handler":"1304_testnet_upgrade", - "target":{ - "runtime_host_protocol":{"major":2}, - "runtime_committee_protocol":{"major":2}, - "consensus_protocol":{"major":4} - }, - "epoch":5662 - } - }, - "created_at":5633, - "closes_at":5645 -}] -``` - -## View Votes for a Proposal - -To view votes for a given proposal, you can use the following command: - -```bash -oasis-node governance proposal_votes -a $ADDR --proposal.id -``` - -replacing `` with the id of the proposal you want see. - -It should return a list of cast votes for the chosen proposal similar to the following: - -```bash -[ - { - "voter": "oasis1qq2vzcvxn0js5unsch5me2xz4kr43vcasv0d5eq4", - "vote": "yes" - }, - { - "voter": "oasis1qqv25adrld8jjquzxzg769689lgf9jxvwgjs8tha", - "vote": "yes" - }, - { - "voter": "oasis1qz2tg4hsatlxfaf8yut9gxgv8990ujaz4sldgmzx", - "vote": "yes" - }, - { - "voter": "oasis1qz424yg28jqmgfq3xvly6ky64jqnmlylfc27d7cp", - "vote": "no" - }, - { - "voter": "oasis1qr37y56g92chzvsew54kj7gu47cxyly7jytt5rm0", - "vote": "yes" - } -] -``` - -## Voting for a Proposal - -:::info - -At this time only entities which have active validator nodes scheduled in the validator set are eligible to vote for governance proposals. - -::: - -If you want to vote for an active proposal, you can use the following command to generate a suitable transaction: - -```bash -oasis-node governance gen_cast_vote \ - "${TX_FLAGS[@]}" \ - --vote.proposal.id 1 \ - --vote yes \ - --transaction.file tx_cast_vote.json \ - --transaction.nonce 1 \ - --transaction.fee.gas 2000 \ - --transaction.fee.amount 2000 -``` - -This will output a preview of the generated transaction: - -```bash -You are about to sign the following transaction: - Method: governance.CastVote - Body: - Proposal ID: 1 - Vote: yes - Nonce: 1 - Fee: - Amount: 0.000002 ROSE - Gas limit: 2000 - (gas price: 0.000000001 ROSE per gas unit) -Other info: - Genesis document's hash: 9ce956ef5999024e148f0c21f1e8a05ab4fc98a44c4696b289770705aeb1dd77 -``` - -and ask you for confirmation. - -## Submit the Transaction - -To submit the generated transaction, we need to copy `tx_cast_vote.json` to the online Oasis node (i.e. the `server`) and submit it from there: - -```bash -oasis-node consensus submit_tx \ - -a $ADDR \ - --transaction.file tx_cast_vote.json -``` diff --git a/docs/node/testnet/upgrade-log.md b/docs/node/testnet/upgrade-log.md index 2d6b6fe267..6822ebe6bf 100644 --- a/docs/node/testnet/upgrade-log.md +++ b/docs/node/testnet/upgrade-log.md @@ -23,7 +23,7 @@ We expect the Testnet network to reach this epoch at around 2022-04-04 7:45 UTC. * (optional) Vote for the upgrade. On 2022-04-01, an upgrade proposal will be proposed which (if accepted) will schedule the upgrade on epoch **15056**. - See the [Governance documentation](../run-your-node/validator-node/governance.md) + See the [Governance documentation](../../general/manage-tokens/cli/network.md#governance-cast-vote) for details on voting for proposals. :::info @@ -106,7 +106,7 @@ We expect the Testnet network to reach this epoch at around 2022-03-03 12:45 UTC ### Instructions -* (optional) Vote for the upgrade. On 2022-03-02, an upgrade proposal will be proposed which (if accepted) will schedule the upgrade on epoch **14209.** See the [Governance documentation](../run-your-node/validator-node/governance.md) for details on voting for proposals. +* (optional) Vote for the upgrade. On 2022-03-02, an upgrade proposal will be proposed which (if accepted) will schedule the upgrade on epoch **14209.** See the [Governance documentation](../../general/manage-tokens/cli/network.md#governance-cast-vote) for details on voting for proposals. :::caution @@ -395,7 +395,7 @@ We expect the Testnet network to reach this epoch at around 2021-06-23 14:30 UTC ### Instructions * See [Before upgrade](upgrade-log.md#before-upgrade) section for required steps to be done before upgrade. -* (optional) Vote for the upgrade. On 2021-06-21, an upgrade proposal will be proposed which (if accepted) will schedule the upgrade on epoch **7553.** See the [Governance documentation](../run-your-node/validator-node/governance.md) for details on voting for proposals. +* (optional) Vote for the upgrade. On 2021-06-21, an upgrade proposal will be proposed which (if accepted) will schedule the upgrade on epoch **7553.** See the [Governance documentation](../../general/manage-tokens/cli/network.md#governance-cast-vote) for details on voting for proposals. :::info @@ -510,7 +510,7 @@ We expect the Testnet network to reach this epoch at around 2021-04-13 12:00 UTC ### Instructions * Runtime operators see [Before upgrade](upgrade-log.md#before-upgrade) section for required steps to be done before upgrade. -* (optional) Vote for the upgrade. On 2021-04-12 an upgrade proposal will be proposed which (if accepted) will schedule a network shutdown on epoch **5662.** See the [Governance documentation](../run-your-node/validator-node/governance.md) for details on voting for proposals. +* (optional) Vote for the upgrade. On 2021-04-12 an upgrade proposal will be proposed which (if accepted) will schedule a network shutdown on epoch **5662.** See the [Governance documentation](../../general/manage-tokens/cli/network.md#governance-cast-vote) for details on voting for proposals. :::caution diff --git a/external/adrs b/external/adrs index 7062dd8365..98fb01ea02 160000 --- a/external/adrs +++ b/external/adrs @@ -1 +1 @@ -Subproject commit 7062dd83658c2ddd7517823d95357c85f3301bd6 +Subproject commit 98fb01ea020c07b319b2a04abbce2f64cccfce1b diff --git a/external/cli b/external/cli new file mode 160000 index 0000000000..098968e015 --- /dev/null +++ b/external/cli @@ -0,0 +1 @@ +Subproject commit 098968e015059ff16b4e3e37fbe27dbf9d241b99 diff --git a/external/oasis-core b/external/oasis-core index 6987cde989..de57b13959 160000 --- a/external/oasis-core +++ b/external/oasis-core @@ -1 +1 @@ -Subproject commit 6987cde9890861c93ee57c45e020ce4c72696e18 +Subproject commit de57b13959839842495163302f3f59333f7288fc diff --git a/redirects.js b/redirects.js index ef64ac33ab..61773e8dbd 100644 --- a/redirects.js +++ b/redirects.js @@ -3,6 +3,21 @@ /** @type {import('@docusaurus/plugin-client-redirects').PluginOptions} */ const redirectsOptions = { redirects: [ + // Write down PR responsible for the removal of a page next to the "from" redirect. + // TODO: Add fragments (anchors) in "to" URLs once https://github.com/facebook/docusaurus/issues/6845 is implemented. Since then, put the fragment name in the comment. + { + to: '/adrs', + from: [ + '/adrs/0000-architectural-decision-records', // #200 Restructure docs + '/adrs/template' // #200 Restructure docs + ], + }, + { + to: '/core/oasis-node/cli', + from: [ + '/general/manage-tokens/advanced/oasis-cli-tools/list-accounts', // #list // #399 Replace oasis-node with Oasis CLI + ], + }, { to: '/general/manage-tokens/how-to-transfer-rose-into-paratime', from: [ @@ -10,151 +25,188 @@ const redirectsOptions = { '/general/manage-tokens/how-to-transfer-rose-into-evm-paratime', // #200 Restructure docs ], }, - // #475 Delete bitpie-wallet.md { to: '/general/manage-tokens/faq', // #how-can-i-transfer-rose-tokens-from-my-bitpie-wallet-to-my-oasis-wallet - from: '/general/manage-tokens/holding-rose-tokens/bitpie-wallet', + from: '/general/manage-tokens/holding-rose-tokens/bitpie-wallet', // #475 Delete bitpie-wallet.md }, - // #200 Restructure docs { - to: '/adrs', - from: ['/adrs/0000-architectural-decision-records', '/adrs/template'], + to: '/general/manage-tokens/cli', + from: [ + '/general/manage-tokens/advanced', // #399 Replace oasis-node with Oasis CLI + '/general/manage-tokens/advanced/oasis-cli-tools/', // #399 Replace oasis-node with Oasis CLI + '/general/manage-tokens/advanced/file-based-signer', // #399 Replace oasis-node with Oasis CLI + ], + }, + { + to: '/general/manage-tokens/cli/account', + from: [ + '/general/manage-tokens/advanced/oasis-cli-tools/deposit-withdraw-tokens-to-from-paratime', // #deposit // #399 Replace oasis-node with Oasis CLI + '/general/manage-tokens/advanced/oasis-cli-tools/get-account-info', // #show // #399 Replace oasis-node with Oasis CLI + '/general/manage-tokens/advanced/oasis-cli-tools/get-account-nonce', // #show // #399 Replace oasis-node with Oasis CLI + '/general/manage-tokens/advanced/oasis-cli-tools/address', // #from-public-key // #399 Replace oasis-node with Oasis CLI + '/general/manage-tokens/advanced/oasis-cli-tools/transfer-tokens', // #transfer // #399 Replace oasis-node with Oasis CLI + '/general/manage-tokens/advanced/oasis-cli-tools/delegate-tokens', // #delegate // #399 Replace oasis-node with Oasis CLI + '/general/manage-tokens/advanced/oasis-cli-tools/reclaim-tokens', // #undelegate // #399 Replace oasis-node with Oasis CLI + '/general/run-a-node/set-up-your-node/amend-commission-schedule', // #amend-commission-schedule // #200 Restructure docs + '/node/run-your-node/validator-node/amend-commission-schedule', // #amend-commission-schedule // #399 Replace oasis-node with Oasis CLI + ], + }, + { + to: '/general/manage-tokens/cli/network', + from: [ + '/general/manage-tokens/advanced/oasis-cli-tools/common-staking-info', // #show-native-token // #399 Replace oasis-node with Oasis CLI + '/general/manage-tokens/advanced/oasis-cli-tools/gas-costs', // #gas-costs // #399 Replace oasis-node with Oasis CLI + '/general/run-a-node/set-up-your-node/governance', // #governance_cast_vote // #200 Restructure docs + '/node/run-your-node/validator-node/governance', // #governance_cast_vote // #399 Replace oasis-node with Oasis CLI + ], + }, + { + to: '/general/manage-tokens/cli/setup', + from: [ + '/general/manage-tokens/advanced/oasis-cli-tools/prerequisites', // #399 Replace oasis-node with Oasis CLI + '/general/manage-tokens/advanced/oasis-cli-tools/setup', // #399 Replace oasis-node with Oasis CLI + ] }, { to: '/get-involved/', - from: ['/general/community-resources/community-hub', '/general/community-resources/community-made-resources', '/general/oasis-network/connect-with-us'], + from: [ + '/general/community-resources/community-hub', // #200 Restructure docs + '/general/community-resources/community-made-resources', // #200 Restructure docs + '/general/oasis-network/connect-with-us', // #200 Restructure docs + ], }, { to: '/get-involved/delegation-policy', - from: '/general/foundation/delegation-policy', + from: '/general/foundation/delegation-policy', // #200 Restructure docs }, { to: '/get-involved/oasis-core', - from: '/general/contribute-to-the-network/contribution-guidelines', + from: '/general/contribute-to-the-network/contribution-guidelines', // #200 Restructure docs }, { to: '/get-involved/run-node/validator-node', - from: '/general/contribute-to-the-network/run-validator', + from: '/general/contribute-to-the-network/run-validator', // #200 Restructure docs }, { to: '/get-involved/run-node/paratime-node', - from: '/general/contribute-to-the-network/run-a-paratime-node', + from: '/general/contribute-to-the-network/run-a-paratime-node', // #200 Restructure docs }, { to: '/get-involved/network-governance', - from: '/general/contribute-to-the-network/network-governance', + from: '/general/contribute-to-the-network/network-governance', // #200 Restructure docs }, { to: '/get-involved/token-delivery-and-kyc', - from: '/general/community-resources/token-delivery-and-kyc', + from: '/general/community-resources/token-delivery-and-kyc', // #200 Restructure docs }, { to: '/dapp/', - from: ['/oasis-sdk/', '/general/developer-resources/overview'], + from: [ + '/oasis-sdk/', // #200 Restructure docs + '/general/developer-resources/overview' // #200 Restructure docs + ], }, { to: '/dapp/cipher/', - from: '/oasis-sdk/contract/getting-started', + from: '/oasis-sdk/contract/getting-started', // #200 Restructure docs }, { to: '/dapp/sapphire/', - from: '/general/developer-resources/sapphire-paratime', + from: '/general/developer-resources/sapphire-paratime', // #200 Restructure docs }, { to: '/dapp/sapphire/quickstart', - from: ['/general/developer-resources/sapphire-paratime/writing-dapps-on-sapphire', '/dapp/sapphire/writing-dapps-on-sapphire'], // #218 Add sapphire tutorial + from: [ + '/general/developer-resources/sapphire-paratime/writing-dapps-on-sapphire', // #218 Add sapphire tutorial + '/dapp/sapphire/writing-dapps-on-sapphire', // #218 Add sapphire tutorial + ], }, { to: '/general/oasis-network/faq', - from: '/general/faq/oasis-network-faq', + from: '/general/faq/oasis-network-faq', // #200 Restructure docs }, { to: '/general/manage-tokens/', - from: '/general/manage-tokens/overview', + from: '/general/manage-tokens/overview', // #200 Restructure docs }, { to: '/general/oasis-network/', - from: '/general/oasis-network/overview', + from: '/general/oasis-network/overview', // #200 Restructure docs }, { to: '/general/oasis-network/why-oasis', - from: '/oasis-network-primer/', + from: '/oasis-network-primer/', // #200 Restructure docs }, { to: '/general/oasis-network/token-metrics-and-distribution', - from: '/oasis-network-primer/token-metrics-and-distribution', + from: '/oasis-network-primer/token-metrics-and-distribution', // #200 Restructure docs }, { to: '/node/', - from: '/general/run-a-node/node-operator-overview', + from: '/general/run-a-node/node-operator-overview', // #200 Restructure docs }, { to: '/node/mainnet/', - from: '/general/oasis-network/network-parameters', + from: '/general/oasis-network/network-parameters', // #200 Restructure docs }, { to: '/node/mainnet/upgrade-log', - from: '/general/run-a-node/upgrade-log', + from: '/general/run-a-node/upgrade-log', // #200 Restructure docs }, { to: '/node/run-your-node/archive-node', - from: '/general/run-a-node/set-up-your-node/run-archive-node', + from: '/general/run-a-node/set-up-your-node/run-archive-node', // #200 Restructure docs }, { to: '/node/genesis-doc', - from: '/general/oasis-network/genesis-doc', + from: '/general/oasis-network/genesis-doc', // #200 Restructure docs }, { to: '/node/run-your-node/ias-proxy', - from: '/general/run-a-node/set-up-your-node/run-an-ias-proxy', + from: '/general/run-a-node/set-up-your-node/run-an-ias-proxy', // #200 Restructure docs }, { to: '/node/run-your-node/non-validator-node', - from: '/general/run-a-node/set-up-your-node/run-non-validator', + from: '/general/run-a-node/set-up-your-node/run-non-validator', // #200 Restructure docs }, { to: '/node/run-your-node/paratime-client-node', - from: '/general/run-a-node/set-up-your-node/run-a-paratime-client-node', + from: '/general/run-a-node/set-up-your-node/run-a-paratime-client-node', // #200 Restructure docs }, { to: '/node/run-your-node/paratime-node', - from: '/general/run-a-node/set-up-your-node/run-a-paratime-node', + from: '/general/run-a-node/set-up-your-node/run-a-paratime-node', // #200 Restructure docs }, { to: '/node/run-your-node/seed-node', - from: '/general/run-a-node/set-up-your-node/run-seed-node', + from: '/general/run-a-node/set-up-your-node/run-seed-node', // #200 Restructure docs }, { to: '/node/run-your-node/sentry-node', - from: '/general/run-a-node/set-up-your-node/sentry-node-architecture', - }, - { - to: '/node/run-your-node/validator-node/', - from: ['/general/run-a-node/set-up-your-node/run-validator', '/general/run-a-node/set-up-your-node/creating-an-entity-package'], + from: '/general/run-a-node/set-up-your-node/sentry-node-architecture', // #200 Restructure docs }, { - to: '/node/run-your-node/validator-node/amend-commission-schedule', - from: '/general/run-a-node/set-up-your-node/amend-commission-schedule', - }, - { - to: '/node/run-your-node/validator-node/governance', - from: '/general/run-a-node/set-up-your-node/governance', + to: '/node/run-your-node/validator-node', + from: [ + '/general/run-a-node/set-up-your-node/run-validator', // #200 Restructure docs + '/general/run-a-node/set-up-your-node/creating-an-entity-package', // #200 Restructure docs + ], }, { to: '/node/run-your-node/troubleshooting', - from: '/general/run-a-node/troubleshooting', + from: '/general/run-a-node/troubleshooting', // #200 Restructure docs }, { to: '/node/testnet/', - from: '/general/foundation/testnet/', + from: '/general/foundation/testnet/', // #200 Restructure docs }, { to: '/node/testnet/upgrade-log', - from: '/general/foundation/testnet/upgrade-log', + from: '/general/foundation/testnet/upgrade-log', // #200 Restructure docs }, { to: '/paratime/', - from: '/oasis-sdk/runtime/getting-started' + from: '/oasis-sdk/runtime/getting-started' // #200 Restructure docs }, ], createRedirects(existingPath) { diff --git a/sidebarGeneral.js b/sidebarGeneral.js index d1a259e917..ab4590cca7 100644 --- a/sidebarGeneral.js +++ b/sidebarGeneral.js @@ -65,40 +65,24 @@ const sidebars = { }, 'general/manage-tokens/how-to-transfer-rose-into-paratime', 'general/manage-tokens/how-to-transfer-eth-erc20-to-emerald-paratime', - 'general/manage-tokens/faq', { type: 'category', - label: 'Advanced', + label: 'Oasis CLI', link: { type: 'doc', - id: 'general/manage-tokens/advanced/README', + id: 'general/manage-tokens/cli/README', }, items: [ - 'general/manage-tokens/advanced/file-based-signer', - { - type: 'category', - label: 'Oasis CLI Tools', - link: { - type: 'doc', - id: 'general/manage-tokens/advanced/oasis-cli-tools/README', - }, - items: [ - 'general/manage-tokens/advanced/oasis-cli-tools/prerequisites', - 'general/manage-tokens/advanced/oasis-cli-tools/setup', - 'general/manage-tokens/advanced/oasis-cli-tools/common-staking-info', - 'general/manage-tokens/advanced/oasis-cli-tools/list-accounts', - 'general/manage-tokens/advanced/oasis-cli-tools/get-account-info', - 'general/manage-tokens/advanced/oasis-cli-tools/get-account-nonce', - 'general/manage-tokens/advanced/oasis-cli-tools/address', - 'general/manage-tokens/advanced/oasis-cli-tools/transfer-tokens', - 'general/manage-tokens/advanced/oasis-cli-tools/delegate-tokens', - 'general/manage-tokens/advanced/oasis-cli-tools/reclaim-tokens', - 'general/manage-tokens/advanced/oasis-cli-tools/deposit-withdraw-tokens-to-from-paratime', - 'general/manage-tokens/advanced/oasis-cli-tools/gas-costs', - ] - }, + 'general/manage-tokens/cli/setup', + 'general/manage-tokens/cli/network', + 'general/manage-tokens/cli/paratime', + 'general/manage-tokens/cli/wallet', + 'general/manage-tokens/cli/account', + 'general/manage-tokens/cli/transaction', + 'general/manage-tokens/cli/addressbook', ] }, + 'general/manage-tokens/faq', ], }, ], diff --git a/sidebarNode.js b/sidebarNode.js index 20d3519d60..db17e25645 100644 --- a/sidebarNode.js +++ b/sidebarNode.js @@ -73,18 +73,7 @@ const sidebars = { 'node/run-your-node/prerequisites/set-up-trusted-execution-environment-tee', ] }, - { - type: 'category', - label: 'Validator Node', - link: { - type: 'doc', - id: 'node/run-your-node/validator-node/README', - }, - items: [ - 'node/run-your-node/validator-node/governance', - 'node/run-your-node/validator-node/amend-commission-schedule', - ], - }, + 'node/run-your-node/validator-node', 'node/run-your-node/non-validator-node', 'node/run-your-node/seed-node', 'node/run-your-node/archive-node', diff --git a/src/editUrl.js b/src/editUrl.js index 946de20a77..6e74ffeb8f 100644 --- a/src/editUrl.js +++ b/src/editUrl.js @@ -4,6 +4,7 @@ const path = require('path'); const gitModules = { 'external/adrs/': 'https://github.com/oasisprotocol/adrs/{mode}/main/', + 'external/cli/': 'https://github.com/oasisprotocol/cli/{mode}/master/', 'external/oasis-core/': 'https://github.com/oasisprotocol/oasis-core/{mode}/stable/22.2.x/', 'external/oasis-core-ledger/': 'https://github.com/oasisprotocol/oasis-core-ledger/{mode}/master/', 'external/oasis-sdk/': 'https://github.com/oasisprotocol/oasis-sdk/{mode}/main/', diff --git a/src/remark/cross-repo-links.js b/src/remark/cross-repo-links.js index de6a3c6bdc..172bf78208 100644 --- a/src/remark/cross-repo-links.js +++ b/src/remark/cross-repo-links.js @@ -1,5 +1,6 @@ const visit = require('unist-util-visit'); +const cliRegex = /https:\/\/github\.com\/oasisprotocol\/cli\/blob\/master\/docs\/(.*)\.mdx?(#.*)?/; const oasisSdkContractRegex = /https:\/\/github\.com\/oasisprotocol\/oasis-sdk\/blob\/main\/docs\/contract\/(.*)\.mdx?(#.*)?/; const oasisSdkRuntimeRegex = /https:\/\/github\.com\/oasisprotocol\/oasis-sdk\/blob\/main\/docs\/runtime\/(.*)\.mdx?(#.*)?/; const oasisCoreRegex = /https:\/\/github\.com\/oasisprotocol\/oasis-core\/blob\/master\/docs\/(.*)\.mdx?(#.*)?/; @@ -27,6 +28,8 @@ module.exports = function (options) { node.url = node.url.replace(oasisSdkContractRegex, '/dapp/cipher/$1$2'); } else if (oasisSdkRuntimeRegex.test(node.url)) { node.url = node.url.replace(oasisSdkRuntimeRegex, '/paratime/$1$2'); + } else if (cliRegex.test(node.url)) { + node.url = node.url.replace(cliRegex, '/general/manage-tokens/cli/$1$2'); } else if (oasisCoreRegex.test(node.url)) { node.url = node.url.replace(oasisCoreRegex, '/core/$1$2'); } else if (oasisCoreLedgerRegex.test(node.url)) {