From 09d93035e031a356505859cd8cf0fe8c6cef033f Mon Sep 17 00:00:00 2001 From: derekpierre Date: Fri, 21 Feb 2020 12:00:12 -0500 Subject: [PATCH 1/4] Reorganize our doc's table of contents - hopefully, this makes the docs a bit easier to follow. Categorize guides by running a node vs application development Add a blurb about WorkLock Utilize rst reference linking where applicable to reduce URL issues when pages are moved/renamed Remove 'NuCypher' from page titles since it is redundant --- docs/source/architecture/contracts.md | 2 +- docs/source/architecture/sub_stakes.rst | 2 ++ .../upgradeable_proxy_contracts.rst | 4 ++-- .../character_control_guide.rst | 6 +++--- .../guides/{ => development}/cli_guide.rst | 8 ++++---- .../source/guides/development/development.rst | 12 +++++++++++ .../{ => development}/getting_started.md | 2 +- docs/source/guides/installation_guide.md | 2 +- .../guides/network_node/network_node.rst | 11 ++++++++++ .../{ => network_node}/staking_guide.rst | 10 ++++++---- .../ursula_configuration_guide.rst | 10 ++++++---- docs/source/guides/worklock_guide.rst | 20 ++++++++++++++----- docs/source/index.rst | 9 +++------ docs/source/support/faq.rst | 10 +++++----- docs/source/support/troubleshooting.rst | 2 +- 15 files changed, 73 insertions(+), 37 deletions(-) rename docs/source/guides/{ => development}/character_control_guide.rst (98%) rename docs/source/guides/{ => development}/cli_guide.rst (97%) create mode 100644 docs/source/guides/development/development.rst rename docs/source/guides/{ => development}/getting_started.md (99%) create mode 100644 docs/source/guides/network_node/network_node.rst rename docs/source/guides/{ => network_node}/staking_guide.rst (99%) rename docs/source/guides/{ => network_node}/ursula_configuration_guide.rst (97%) diff --git a/docs/source/architecture/contracts.md b/docs/source/architecture/contracts.md index 1d35ac703..4532048f8 100644 --- a/docs/source/architecture/contracts.md +++ b/docs/source/architecture/contracts.md @@ -1,4 +1,4 @@ -# NuCypher Ethereum Contracts +# Ethereum Contracts ## Contract Listing diff --git a/docs/source/architecture/sub_stakes.rst b/docs/source/architecture/sub_stakes.rst index 49c42ccd5..ef5926e11 100644 --- a/docs/source/architecture/sub_stakes.rst +++ b/docs/source/architecture/sub_stakes.rst @@ -150,6 +150,8 @@ Slashing Flags that affect the sub-stake array ------------------------------------- +.. _sub-stake-restaking: + Re-staking ^^^^^^^^^^ *Used in methods* : ``confirmActivity()``, ``mint()`` diff --git a/docs/source/architecture/upgradeable_proxy_contracts.rst b/docs/source/architecture/upgradeable_proxy_contracts.rst index 3e1801c1e..c7c438194 100644 --- a/docs/source/architecture/upgradeable_proxy_contracts.rst +++ b/docs/source/architecture/upgradeable_proxy_contracts.rst @@ -1,5 +1,5 @@ -NuCypher's Approaches to Upgradeable Contracts -============================================== +Approaches to Upgradeable Contracts +=================================== Smart contracts in Ethereum are immutable... In order to fix bugs and provide upgrade logic it is possible to change the contract (address) and save the original contract's storage values. diff --git a/docs/source/guides/character_control_guide.rst b/docs/source/guides/development/character_control_guide.rst similarity index 98% rename from docs/source/guides/character_control_guide.rst rename to docs/source/guides/development/character_control_guide.rst index ed0054ac8..c5849f843 100644 --- a/docs/source/guides/character_control_guide.rst +++ b/docs/source/guides/development/character_control_guide.rst @@ -1,6 +1,6 @@ -================================ -NuCypher Character Control Guide -================================ +======================= +Character Control Guide +======================= The `Character Control` is a module that contains useful REST-like HTTP endpoints for working with NuCypher characters. diff --git a/docs/source/guides/cli_guide.rst b/docs/source/guides/development/cli_guide.rst similarity index 97% rename from docs/source/guides/cli_guide.rst rename to docs/source/guides/development/cli_guide.rst index a8b1cada5..e7bf179ab 100644 --- a/docs/source/guides/cli_guide.rst +++ b/docs/source/guides/development/cli_guide.rst @@ -1,6 +1,6 @@ -================== -NuCypher CLI Guide -================== +========= +CLI Guide +========= Overview -------- @@ -11,7 +11,7 @@ Overview This guide is an example of NuCypher's decentralized network allowing Alice to share a secret with Bob using the NuCypher Network via the ``nucypher`` CLI. It is analogous to the ``python`` example -in :doc:`/guides/getting_started`. +in :doc:`getting_started`. To better understand the commands and their options, use the ``--help`` option. diff --git a/docs/source/guides/development/development.rst b/docs/source/guides/development/development.rst new file mode 100644 index 000000000..2b05132b3 --- /dev/null +++ b/docs/source/guides/development/development.rst @@ -0,0 +1,12 @@ +======================= +Application Development +======================= + +The NuCypher Network provides cryptographic infrastructure for privacy-preserving applications. + +.. toctree:: + :maxdepth: 1 + + getting_started + cli_guide + character_control_guide \ No newline at end of file diff --git a/docs/source/guides/getting_started.md b/docs/source/guides/development/getting_started.md similarity index 99% rename from docs/source/guides/getting_started.md rename to docs/source/guides/development/getting_started.md index 1ff3e8669..00b726314 100644 --- a/docs/source/guides/getting_started.md +++ b/docs/source/guides/development/getting_started.md @@ -141,7 +141,7 @@ alice = Alice(known_nodes=[ursula, another_ursula], ...) ``` For information on how to run a staking Ursula node via CLI, -see +see [Running a Network Node](/guides/network_node/network_node). ## Alice: Grant Access to a Secret diff --git a/docs/source/guides/installation_guide.md b/docs/source/guides/installation_guide.md index 64c662d05..bd58abe4d 100644 --- a/docs/source/guides/installation_guide.md +++ b/docs/source/guides/installation_guide.md @@ -140,7 +140,7 @@ Here is the recommended procedure for setting up `nucypher` in this fashion: docker run -it -v ~/.local/share/nucypher:/root/.local/share/nucypher -v ~/.ethereum/:/root/.ethereum -p 9151:9151 nucypher/nucypher:latest nucypher status network --provider --network - Running a pre-configured Worker as a daemon (See [Configuration Guide](/guides/ursula_configuration_guide)): + Running a pre-configured Worker as a daemon (See [Configuration Guide](/guides/network_node/ursula_configuration_guide)): docker run -d -v ~/.local/share/nucypher:/root/.local/share/nucypher -v ~/.ethereum/:/root/.ethereum -p 9151:9151 -e NUCYPHER_KEYRING_PASSWORD -e NUCYPHER_WORKER_ETH_PASSWORD nucypher/nucypher:latest nucypher ursula run diff --git a/docs/source/guides/network_node/network_node.rst b/docs/source/guides/network_node/network_node.rst new file mode 100644 index 000000000..0a88d3e30 --- /dev/null +++ b/docs/source/guides/network_node/network_node.rst @@ -0,0 +1,11 @@ +====================== +Running a Network Node +====================== + +To be a node on the NuCypher network, operations are divided into two roles “Staker” and “Worker”. + +.. toctree:: + :maxdepth: 1 + + staking_guide + ursula_configuration_guide \ No newline at end of file diff --git a/docs/source/guides/staking_guide.rst b/docs/source/guides/network_node/staking_guide.rst similarity index 99% rename from docs/source/guides/staking_guide.rst rename to docs/source/guides/network_node/staking_guide.rst index 30c565117..4a3444fe5 100644 --- a/docs/source/guides/staking_guide.rst +++ b/docs/source/guides/network_node/staking_guide.rst @@ -1,8 +1,8 @@ .. _staking-guide: -======================= -NuCypher Staking Guide -======================= +========================== +Staker Configuration Guide +========================== NuCypher staking operations are divided into two roles "Staker" and "Worker" - This Guide is for Stakers. @@ -29,7 +29,7 @@ Staking Procedure: 6) Create and fund worker's ethereum address with ETH 7) Bond a Worker to a Staker using the worker's ethereum address (see `Bonding a Worker`_) 8) Optionally, modify stake settings (see `Modifying Active Stakes`_) -9) Configure and Run a Worker Node (see :doc:`/guides/ursula_configuration_guide`) +9) Configure and Run a Worker Node (see :ref:`ursula-config-guide`) Staking CLI @@ -338,6 +338,8 @@ allow **re-staking** to be disabled until the release period begins, even if you No action is needed to release the re-staking lock once the release period begins. +.. _staking-prolong: + Prolong ******* diff --git a/docs/source/guides/ursula_configuration_guide.rst b/docs/source/guides/network_node/ursula_configuration_guide.rst similarity index 97% rename from docs/source/guides/ursula_configuration_guide.rst rename to docs/source/guides/network_node/ursula_configuration_guide.rst index 864e70997..d2ecad29e 100644 --- a/docs/source/guides/ursula_configuration_guide.rst +++ b/docs/source/guides/network_node/ursula_configuration_guide.rst @@ -1,8 +1,8 @@ .. _ursula-config-guide: -========================== -Ursula Configuration Guide -========================== +=================================== +Worker (Ursula) Configuration Guide +=================================== NuCypher staking operations are divided into two roles "Staker" and "Worker" - This Guide is for Workers. @@ -21,7 +21,7 @@ Working Procedure: .. References are needed for links because of the numbers in the section names -1) Ensure that a `Stake` is available (see :doc:`/guides/staking_guide`) +1) Ensure that a `Stake` is available (see :ref:`staking-guide`) 2) Run an ethereum node on the Worker's machine eg. geth, parity, etc. (see :ref:`Running an Ethereum node for Ursula `) 3) Install ``nucypher`` on Worker node (see :doc:`/guides/installation_guide`) 4) Create and fund worker's ethereum address (see :ref:`Fund Worker Account with ETH `) @@ -183,6 +183,8 @@ To stop your node from the interactive console and return to the terminal sessio Ursula >>> stop +.. _run-ursula-with-docker: + Running an Ursula with Docker ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/guides/worklock_guide.rst b/docs/source/guides/worklock_guide.rst index c223aa1fa..9c218c27f 100644 --- a/docs/source/guides/worklock_guide.rst +++ b/docs/source/guides/worklock_guide.rst @@ -1,13 +1,23 @@ -======================= -NuCypher WorkLock Guide -======================= +============== +WorkLock Guide +============== Overview -------- -TODO +`WorkLock` is a novel token distribution mechanism we created that requires participants to run NuCypher nodes +to receive NU tokens. Think of it as a replacement for an ICO or an airdrop as a way to distribute initial +tokens, but with a stronger filter for desirable participants (in our case, people who will stake and run nodes on +the network). -To better understand the commands and their options, use the ``--help`` option. +There will be an open contribution period in which anyone can contribute ETH to the WorkLock contract. That ETH will +be escrowed on-chain and at the end of the contribution period, stake-locked NU will be distributed pro rata across +contributors. If those contributors use that stake-locked NU to run a node, the NU will eventually unlock and their +escrowed ETH will be returned in full. Alternatively, WorkLock participants can cancel their bid to forgo NU and +recoup their escrowed ETH. + +The ``nucypher worklock`` CLI command provides the ability to participate in WorkLock. To better understand the +commands and their options, use the ``--help`` option. Common CLI flags ---------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 40ae911e9..7169b3da2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -115,7 +115,7 @@ Whitepapers .. warning:: - NuCypher is currently in the *Alpha* development stage and is **not** intended for use in production. + NuCypher is currently in the *Beta* development stage and is **not** intended for use in production. .. toctree:: @@ -123,12 +123,9 @@ Whitepapers :caption: Guides guides/installation_guide - guides/getting_started - guides/staking_guide - guides/ursula_configuration_guide - guides/cli_guide + guides/network_node/network_node + guides/development/development guides/worklock_guide - guides/character_control_guide guides/contribution_guide .. toctree:: diff --git a/docs/source/support/faq.rst b/docs/source/support/faq.rst index d3f1f70b9..36b301738 100644 --- a/docs/source/support/faq.rst +++ b/docs/source/support/faq.rst @@ -87,7 +87,7 @@ This is **ONLY** a heuristic to ensure that your node is running correctly, it d What's the best way to run Ursula in the background? ---------------------------------------------------- -Either through `Docker `_ +Either through :ref:`Docker ` or `systemd `_. @@ -117,7 +117,7 @@ are in Period 5 when you start staking: .. note:: - `Restaking `_ is enabled by + :ref:`Restaking ` is enabled by default, so NU inflation rewards are automatically restaked for you, and will be reflected in the ``Staked`` value of the above command. @@ -136,15 +136,15 @@ Run:: Can I extend the duration of my existing stake? -------------------------------------------------------------- -Yes, via the `prolong `_ command. +Yes, via the :ref:`prolong ` command. How can I reuse an Ursula that was connected to the previous version of the testnet? ------------------------------------------------------------------------------------ #. Run ``nucypher ursula destroy`` to destroy the current configuration. -#. Repeat all of the steps with the new tokens in the `Staking Guide `_. -#. Run ``nucypher ursula init`` per the `Ursula Configuration Guide `_. +#. Repeat all of the steps with the new tokens in the :ref:`staking-guide`. +#. Run ``nucypher ursula init`` per the :ref:`ursula-config-guide`. What is a fleet state? diff --git a/docs/source/support/troubleshooting.rst b/docs/source/support/troubleshooting.rst index 7f014ffd3..030c3d7e8 100644 --- a/docs/source/support/troubleshooting.rst +++ b/docs/source/support/troubleshooting.rst @@ -34,7 +34,7 @@ client, this generic error will become extinct. In the most common cases: -- Ensure that your worker is `bonded to a staker `_. +- Ensure that your worker is :ref:`bonded to a staker `. You can confirm by running ``nucypher stake list`` and check that `Worker` is set correctly i.e. not ``0x0000``. - If your worker is configured, ensure that the worker address has (Goerli) ETH and that the correct worker address is provided in the Ursula configuration file being used - the default configuration file is ``~/.local/share/nucypher/ursula.json`` From a90e12d8097138b658c9678894cadff8cc097a7f Mon Sep 17 00:00:00 2001 From: Derek Pierre Date: Fri, 21 Feb 2020 13:12:55 -0500 Subject: [PATCH 2/4] Respond to RFCs for #1731 Co-Authored-By: MacLane S Wilkison --- docs/source/guides/worklock_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/guides/worklock_guide.rst b/docs/source/guides/worklock_guide.rst index 9c218c27f..ea8a4f0e5 100644 --- a/docs/source/guides/worklock_guide.rst +++ b/docs/source/guides/worklock_guide.rst @@ -14,7 +14,7 @@ There will be an open contribution period in which anyone can contribute ETH to be escrowed on-chain and at the end of the contribution period, stake-locked NU will be distributed pro rata across contributors. If those contributors use that stake-locked NU to run a node, the NU will eventually unlock and their escrowed ETH will be returned in full. Alternatively, WorkLock participants can cancel their bid to forgo NU and -recoup their escrowed ETH. +recoup their escrowed ETH immediately. The ``nucypher worklock`` CLI command provides the ability to participate in WorkLock. To better understand the commands and their options, use the ``--help`` option. From 02b6521dc6025d5b0adf04eb15b836294ae287a6 Mon Sep 17 00:00:00 2001 From: jMyles Date: Fri, 21 Feb 2020 12:51:12 -0700 Subject: [PATCH 3/4] Some revisions which may or may not be useful. --- docs/source/guides/worklock_guide.rst | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/docs/source/guides/worklock_guide.rst b/docs/source/guides/worklock_guide.rst index ea8a4f0e5..9166dc78d 100644 --- a/docs/source/guides/worklock_guide.rst +++ b/docs/source/guides/worklock_guide.rst @@ -5,16 +5,11 @@ WorkLock Guide Overview -------- -`WorkLock` is a novel token distribution mechanism we created that requires participants to run NuCypher nodes -to receive NU tokens. Think of it as a replacement for an ICO or an airdrop as a way to distribute initial -tokens, but with a stronger filter for desirable participants (in our case, people who will stake and run nodes on -the network). +`WorkLock` is a novel, permissionless token distribution mechanism, developed at NuCypher, which requires participants to stake ETH and maintain NuCypher nodes in order to receive NU tokens. -There will be an open contribution period in which anyone can contribute ETH to the WorkLock contract. That ETH will -be escrowed on-chain and at the end of the contribution period, stake-locked NU will be distributed pro rata across -contributors. If those contributors use that stake-locked NU to run a node, the NU will eventually unlock and their -escrowed ETH will be returned in full. Alternatively, WorkLock participants can cancel their bid to forgo NU and -recoup their escrowed ETH immediately. +WorkLock offers specific advantages over ICO or airdrop as a distribution mechanism, chiefly: it selects for participants who are most likely to strenghten the network because they commit to staking and running nodes. + +The WorkLock begins with an open bidding period, during which anyone seeking to participate can send ETH to the WorkLock contract to be escrowed on-chain. At the end of the bidding period, stake-locked NU will be distributed pro rata across contributors. If those contributors use that stake-locked NU to run a node, the NU will eventually unlock and their escrowed ETH will be returned in full. Alternatively, WorkLock participants can cancel their bid to forgo NU and recoup their escrowed ETH immediately. The ``nucypher worklock`` CLI command provides the ability to participate in WorkLock. To better understand the commands and their options, use the ``--help`` option. From 68904d25031c162c3a8feccc8a64edfc9a36bb19 Mon Sep 17 00:00:00 2001 From: Derek Pierre Date: Fri, 21 Feb 2020 14:57:19 -0500 Subject: [PATCH 4/4] Update spelling --- docs/source/guides/worklock_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/guides/worklock_guide.rst b/docs/source/guides/worklock_guide.rst index 9166dc78d..dd015c1d5 100644 --- a/docs/source/guides/worklock_guide.rst +++ b/docs/source/guides/worklock_guide.rst @@ -7,7 +7,7 @@ Overview `WorkLock` is a novel, permissionless token distribution mechanism, developed at NuCypher, which requires participants to stake ETH and maintain NuCypher nodes in order to receive NU tokens. -WorkLock offers specific advantages over ICO or airdrop as a distribution mechanism, chiefly: it selects for participants who are most likely to strenghten the network because they commit to staking and running nodes. +WorkLock offers specific advantages over ICO or airdrop as a distribution mechanism, chiefly: it selects for participants who are most likely to strengthen the network because they commit to staking and running nodes. The WorkLock begins with an open bidding period, during which anyone seeking to participate can send ETH to the WorkLock contract to be escrowed on-chain. At the end of the bidding period, stake-locked NU will be distributed pro rata across contributors. If those contributors use that stake-locked NU to run a node, the NU will eventually unlock and their escrowed ETH will be returned in full. Alternatively, WorkLock participants can cancel their bid to forgo NU and recoup their escrowed ETH immediately.