From 3b6d47dfe33df094df20404735d74f750695d082 Mon Sep 17 00:00:00 2001 From: derekpierre Date: Tue, 2 Feb 2021 16:27:11 -0500 Subject: [PATCH] Mostly reordering of specific page content; addition of helpful/contextual links. --- .../application_development/testnet.rst | 9 +- docs/source/references/cli_reference.rst | 145 +++++++++--------- docs/source/references/networks.rst | 8 +- docs/source/references/signers.rst | 52 +++---- docs/source/staking/remote_worker_cli.rst | 8 +- docs/source/staking/stake_initialization.rst | 2 +- docs/source/staking/stake_management.rst | 12 +- docs/source/staking/testnet.rst | 13 +- 8 files changed, 129 insertions(+), 120 deletions(-) diff --git a/docs/source/application_development/testnet.rst b/docs/source/application_development/testnet.rst index 2d616e224..d19e9081c 100644 --- a/docs/source/application_development/testnet.rst +++ b/docs/source/application_development/testnet.rst @@ -1,9 +1,11 @@ +.. _lynx-testnet: + ============= Lynx Testnet ============= -NuCypher provides a public Long-Term Support testnet running on the ethereum Goerli testnet as a stable playground -for application development and network users (e.g., Alices wishing to create sharing policies, grant & Retrieve, etc.). +NuCypher provides a public Long-Term Support testnet running on the Ethereum Goerli testnet as a stable playground +for application development and network users (e.g., Alices wishing to create sharing policies, grant and retrieve, etc.). .. note:: @@ -14,7 +16,8 @@ for application development and network users (e.g., Alices wishing to create sh .. important:: - Goerli ETH is required to use the Lynx testnet. + Goerli ETH is required to use the Lynx testnet, and can be obtained from its `standard faucet `_ + or `authenticated faucet `_. Alice and Bob can use the lynx testnet using the python API: diff --git a/docs/source/references/cli_reference.rst b/docs/source/references/cli_reference.rst index 0fcc56a6d..21fe9a13e 100644 --- a/docs/source/references/cli_reference.rst +++ b/docs/source/references/cli_reference.rst @@ -70,51 +70,6 @@ Bob +--------------------------+-------------------------------------------------------------------------------+ -Cloudworkers ------------- - -Manage worker and other staker-related operations on cloud infrastructure. - - -.. code:: bash - - (nucypher)$ nucypher cloudworkers ACTION [OPTIONS] - -**Cloudworkers Command Actions** - -+----------------------+-------------------------------------------------------------------------------+ -| Action | Description | -+======================+===============================================================================+ -| ``up`` | Creates and deploys hosts for all active local stakers. | -+----------------------+-------------------------------------------------------------------------------+ -| ``create`` | Creates and deploys the given number of hosts independent of stakes | -+----------------------+-------------------------------------------------------------------------------+ -| ``add`` | Add an existing host to be managed by cloudworkers CLI tools | -+----------------------+-------------------------------------------------------------------------------+ -| ``add_for_stake`` | Add an existing host to be managed for a specified local staker address | -+----------------------+-------------------------------------------------------------------------------+ -| ``deploy`` | Install and run Ursula on existing managed hosts. | -+----------------------+-------------------------------------------------------------------------------+ -| ``update`` | Update or manage existing installed Ursula. | -+----------------------+-------------------------------------------------------------------------------+ -| ``destroy`` | Shut down and cleanup resources deployed on AWS or Digital Ocean | -+----------------------+-------------------------------------------------------------------------------+ -| ``stop`` | Stop the selected nodes. | -+----------------------+-------------------------------------------------------------------------------+ -| ``status`` | Prints a formatted status of selected managed hosts. | -+----------------------+-------------------------------------------------------------------------------+ -| ``logs`` | Download and display the accumulated stdout logs of selected hosts | -+----------------------+-------------------------------------------------------------------------------+ -| ``backup`` | Download local copies of critical data from selected installed Ursulas | -+----------------------+-------------------------------------------------------------------------------+ -| ``restore`` | Reconstitute and deploy an operating Ursula from backed up data | -+----------------------+-------------------------------------------------------------------------------+ -| ``list_hosts`` | Print local nicknames of all managed hosts under a given namespace | -+----------------------+-------------------------------------------------------------------------------+ -| ``list_namespaces`` | Print namespaces under a given network | -+----------------------+-------------------------------------------------------------------------------+ - - Enrico ------- @@ -210,34 +165,6 @@ Manage stakes and other staker-related operations. +-------------------------+---------------------------------------------+ -Status ------- - -Echo a snapshot of live NuCypher Network metadata. - -.. code:: bash - - (nucypher)$ nucypher status ACTION [OPTIONS] - - -**Status Command Actions** - - -+--------------------------+---------------------------------------------------------------------+ -| Action | Description | -+==========================+=====================================================================+ -| ``events`` | Show events associated to NuCypher contracts. | -+--------------------------+---------------------------------------------------------------------+ -| ``fee-range`` | Provide information on the global fee range. | -+--------------------------+---------------------------------------------------------------------+ -| ``locked-tokens`` | Display a graph of the number of locked tokens over time. | -+--------------------------+---------------------------------------------------------------------+ -| ``network`` | Overall information of the NuCypher Network. | -+--------------------------+---------------------------------------------------------------------+ -| ``stakers`` | Show relevant information about stakers. | -+--------------------------+---------------------------------------------------------------------+ - - Ursula ------ @@ -267,3 +194,75 @@ Ursula +--------------------------+---------------------------------------------------------------------+ | ``run`` | Start Ursula. | +--------------------------+---------------------------------------------------------------------+ + + +Cloudworkers +------------ + +Manage worker and other staker-related operations on cloud infrastructure. + +.. code:: bash + + (nucypher)$ nucypher cloudworkers ACTION [OPTIONS] + +**Cloudworkers Command Actions** + ++----------------------+-------------------------------------------------------------------------------+ +| Action | Description | ++======================+===============================================================================+ +| ``up`` | Creates and deploys hosts for all active local stakers. | ++----------------------+-------------------------------------------------------------------------------+ +| ``create`` | Creates and deploys the given number of hosts independent of stakes | ++----------------------+-------------------------------------------------------------------------------+ +| ``add`` | Add an existing host to be managed by cloudworkers CLI tools | ++----------------------+-------------------------------------------------------------------------------+ +| ``add_for_stake`` | Add an existing host to be managed for a specified local staker address | ++----------------------+-------------------------------------------------------------------------------+ +| ``deploy`` | Install and run Ursula on existing managed hosts. | ++----------------------+-------------------------------------------------------------------------------+ +| ``update`` | Update or manage existing installed Ursula. | ++----------------------+-------------------------------------------------------------------------------+ +| ``destroy`` | Shut down and cleanup resources deployed on AWS or Digital Ocean | ++----------------------+-------------------------------------------------------------------------------+ +| ``stop`` | Stop the selected nodes. | ++----------------------+-------------------------------------------------------------------------------+ +| ``status`` | Prints a formatted status of selected managed hosts. | ++----------------------+-------------------------------------------------------------------------------+ +| ``logs`` | Download and display the accumulated stdout logs of selected hosts | ++----------------------+-------------------------------------------------------------------------------+ +| ``backup`` | Download local copies of critical data from selected installed Ursulas | ++----------------------+-------------------------------------------------------------------------------+ +| ``restore`` | Reconstitute and deploy an operating Ursula from backed up data | ++----------------------+-------------------------------------------------------------------------------+ +| ``list_hosts`` | Print local nicknames of all managed hosts under a given namespace | ++----------------------+-------------------------------------------------------------------------------+ +| ``list_namespaces`` | Print namespaces under a given network | ++----------------------+-------------------------------------------------------------------------------+ + + +Status +------ + +Echo a snapshot of live NuCypher Network metadata. + +.. code:: bash + + (nucypher)$ nucypher status ACTION [OPTIONS] + + +**Status Command Actions** + + ++--------------------------+---------------------------------------------------------------------+ +| Action | Description | ++==========================+=====================================================================+ +| ``events`` | Show events associated to NuCypher contracts. | ++--------------------------+---------------------------------------------------------------------+ +| ``fee-range`` | Provide information on the global fee range. | ++--------------------------+---------------------------------------------------------------------+ +| ``locked-tokens`` | Display a graph of the number of locked tokens over time. | ++--------------------------+---------------------------------------------------------------------+ +| ``network`` | Overall information of the NuCypher Network. | ++--------------------------+---------------------------------------------------------------------+ +| ``stakers`` | Show relevant information about stakers. | ++--------------------------+---------------------------------------------------------------------+ diff --git a/docs/source/references/networks.rst b/docs/source/references/networks.rst index a572e5b80..60de57eb6 100644 --- a/docs/source/references/networks.rst +++ b/docs/source/references/networks.rst @@ -19,8 +19,8 @@ Mainnet Lynx **** -Public Long-Term Support testnet, A stable playground for network users (e.g., Alices wishing to create sharing -policies). Running on Ethereum Goerli testnet. +Public Long-Term Support testnet to provide a stable playground for network users (e.g., Alices wishing to create sharing +policies). Running on Ethereum Goerli testnet (see :ref:`lynx-testnet`). * `NuCypherToken 0x02B50E38E5872068F325B1A7ca94D90ce2bfff63 `_ * `StakingEscrow (Dispatcher) 0x40Ca356d8180Ddc21C82263F9EbCeaAc6Cad7250 `_ @@ -31,8 +31,8 @@ policies). Running on Ethereum Goerli testnet. Ibex **** -Public testnet, intended as a playground for stakers & node operators (e.g., learning how to create and manage -stakes, setting up a node), as well as for internal development purposes. Running on Ethereun Rinkeby testnet. +Public testnet, intended as a playground for stakers and node operators (e.g., learning how to create and manage +stakes, setting up a node, as well as for internal development purposes. Running on Ethereun Rinkeby testnet (see :ref:`ibex-testnet`). * `NuCypherToken 0x78D591D90a4a768B9D2790deA465D472b6Fe0f18 `_ * `StakingEscrow (Dispatcher) 0x6A6F917a3FF3d33d26BB4743140F205486cD6B4B `_ diff --git a/docs/source/references/signers.rst b/docs/source/references/signers.rst index 31dd03af5..ca11eae6b 100644 --- a/docs/source/references/signers.rst +++ b/docs/source/references/signers.rst @@ -15,8 +15,8 @@ For example, external signers can be used with: The following signers are currently supported: #. :ref:`Hardware Wallet ` (recommended for :ref:`Stakers `) -#. :ref:`Clef ` #. :ref:`Local Keystore ` (recommended for :ref:`Workers `) +#. :ref:`Clef ` .. _signing-with-hardware: @@ -39,6 +39,31 @@ A `Trezor `_ signer can be specified either through the CLI API (``nucypher.blockchain.eth.signers.Signer.from_signer_uri``), using the URI ``trezor``. +.. _signing-with-local-keystore: + +Signing with Local Keystore +*************************** + +.. important:: + + For operational security, the Keystore signer is not recommended for :ref:`Staker operations `. + An exception can be made for testnets, but Staker operations should be performed using a hardware wallet. + +Local keystore signing utilizes `eth-account `_ to sign ethereum transactions +using local ethereum keystore files. By default on Linux, the keystore directory path is ``~/.ethereum/keystore`` +(on MacOS for Rinkeby testnet, ``/Users//Library/Ethereum/rinkeby/keystore``). + + +Usage ++++++ + +Specify the local keystore signer either through the CLI (``--signer``) or API (``nucypher.blockchain.eth.signers.Signer.from_signer_uri``), +using the URI ``keystore://``. + +The path provided can either be a directory of keystore files or an individual keystore file. In the case of a +directory, it is scanned and each of the keystore files contained are processed. + + .. _signing-with-clef: Signing with Clef @@ -167,28 +192,3 @@ Usage Once ``clef`` is running, specify the Clef signer either through the CLI (``--signer``) or API (``nucypher.blockchain.eth.signers.Signer.from_signer_uri``), using the URI ``clef://``. - - -.. _signing-with-local-keystore: - -Signing with Local Keystore -*************************** - -.. important:: - - For operational security, the Keystore signer is not recommended for :ref:`Staker operations `. - An exception can be made for testnets, but Staker operations should be performed using a hardware wallet. - -Local keystore signing utilizes `eth-account `_ to sign ethereum transactions -using local ethereum keystore files. By default on Linux, the keystore directory path is ``~/.ethereum/keystore`` -(on MacOS for Rinkeby testnet, ``/Users//Library/Ethereum/rinkeby/keystore``). - - -Usage -+++++ - -Specify the local keystore signer either through the CLI (``--signer``) or API (``nucypher.blockchain.eth.signers.Signer.from_signer_uri``), -using the URI ``keystore://``. - -The path provided can either be a directory of keystore files or an individual keystore file. In the case of a -directory, it is scanned and each of the keystore files contained are processed. diff --git a/docs/source/staking/remote_worker_cli.rst b/docs/source/staking/remote_worker_cli.rst index 1267a95ae..7182a706c 100644 --- a/docs/source/staking/remote_worker_cli.rst +++ b/docs/source/staking/remote_worker_cli.rst @@ -1,10 +1,10 @@ .. _managing-cloud-workers: -Remote Worker Management -======================== +Cloud Worker Management +======================= -NuCypher maintains an CLI to assist with the management of multiple remote Nucypher Ursula nodes, leveraging -automation tools like Ansible and Docker. +NuCypher maintains a CLI to assist with the management of multiple Nucypher Ursula nodes deployed in the cloud, +that leverages automation tools such as Ansible and Docker. .. code:: bash diff --git a/docs/source/staking/stake_initialization.rst b/docs/source/staking/stake_initialization.rst index 3b24e8324..e9a5e2090 100644 --- a/docs/source/staking/stake_initialization.rst +++ b/docs/source/staking/stake_initialization.rst @@ -246,7 +246,7 @@ bonded a Worker node to your Staker. After initiating a stake, the staker must delegate access to a work address through *bonding*. There is a 1:1 relationship between the roles: A Staker may have multiple substakes but only ever has one Worker at a time. -.. important:: The Worker cannot be changed for a minimum of 2 periods (48 Hours) once bonded. +.. important:: The Worker cannot be changed for a minimum of 2 periods (48 hours) once bonded. .. code:: bash diff --git a/docs/source/staking/stake_management.rst b/docs/source/staking/stake_management.rst index ac6fd5c25..223de5bf7 100644 --- a/docs/source/staking/stake_management.rst +++ b/docs/source/staking/stake_management.rst @@ -16,13 +16,19 @@ Several administrative operations can be performed on active stakes: +----------------------+-------------------------------------------------------------------------------+ | ``increase`` | Increase an existing stake's value | +----------------------+-------------------------------------------------------------------------------+ +| ``merge`` | Merge two stakes into one | ++----------------------+-------------------------------------------------------------------------------+ +| ``remove-unused`` | Remove unused/inactive stakes | ++----------------------+-------------------------------------------------------------------------------+ +| ``collect-rewards`` | Collect earned staking rewards and/or policy fees | ++----------------------+-------------------------------------------------------------------------------+ Re-staking ~~~~~~~~~~~ As your Ursula performs work, all rewards are automatically added to your existing stake to optimize earnings. -This feature, called `re-staking`, is *enabled* by default. +This feature, called `re-staking`, is **enabled** by default. To disable re-staking: @@ -61,9 +67,9 @@ in reduced staking yield. When disabled, the stake's locked duration remains constant and improves staking yield. See :ref:`sub-stake-winddown` for more information. -Wind down is *disabled* by default. +Wind down is **disabled** by default. -.. note:: WorkLock participants have wind down *enabled* by default. +.. note:: WorkLock participants have wind down **enabled** by default. To start winding down an existing stake: diff --git a/docs/source/staking/testnet.rst b/docs/source/staking/testnet.rst index bf3d0b619..af90d54b5 100644 --- a/docs/source/staking/testnet.rst +++ b/docs/source/staking/testnet.rst @@ -1,18 +1,20 @@ +.. _ibex-testnet: + ============= Ibex Testnet ============= -NuCypher provides a Public testnet running on the ethereum Rinkeby testnet meant for stakers & node operators learning how to -create and manage stakes, setting up a node), as well as for internal development purposes. +NuCypher provides a public testnet running on the Ethereum Rinkeby testnet meant for stakers and node operators to learn how to +create and manage stakes, set up a node, as well as for internal development purposes. .. attention:: - Ibex Testnet NU can be obtained by joining the `Discord server `_ and typing + Ibex Testnet NU can be obtained by joining the `Discord Server `_ and typing ``.getfunded `` in the #testnet-faucet channel. Note that Rinkeby ETH is - also required to use the Ibex testnet. + also required to use the Ibex testnet, and can be obtained from its `faucet `_. -Stakers and Workers can be configured to use the ibex testnet using the command line: +Stakers and Workers can be configured to use the Ibex testnet using the command line: .. code:: @@ -22,7 +24,6 @@ Stakers and Workers can be configured to use the ibex testnet using the command # Update an existing staker $ nucypher stake config --network ibex --provider - # While creating a new worker $ nucypher ursula init --network ibex --provider