diff --git a/docs/source/application_development/testnet.rst b/docs/source/application_development/testnet.rst index 2eeb5d765..2d616e224 100644 --- a/docs/source/application_development/testnet.rst +++ b/docs/source/application_development/testnet.rst @@ -17,7 +17,7 @@ for application development and network users (e.g., Alices wishing to create sh Goerli ETH is required to use the Lynx testnet. -Alice and Bob work support the lynx testnet using the python API: +Alice and Bob can use the lynx testnet using the python API: .. code:: python diff --git a/docs/source/demos/finnegans_wake_demo.rst b/docs/source/demos/finnegans_wake_demo.rst index 0d4a41cd4..ef876002c 100644 --- a/docs/source/demos/finnegans_wake_demo.rst +++ b/docs/source/demos/finnegans_wake_demo.rst @@ -48,8 +48,8 @@ Acquire the ``nucypher`` application code and install the dependencies: Run a fleet of federated Ursulas -------------------------------- - Run the local fleet of federated Ursulas in a separate terminal. This provides a network of 12 federated - Ursulas. + Run the local fleet of federated Ursulas in a separate terminal. + This provides a network of 12 federated Ursulas. .. code:: diff --git a/docs/source/index.rst b/docs/source/index.rst index a13d77677..1c3ff7386 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,27 +10,6 @@ cryptography operations serving users with secrets management and dynamic access ``nucypher`` is the python library and CLI for interacting with the decentralized threshold cryptography network. -Decentralized - The network is permissionless and censorship-resistant. -There are no gate-keepers and anyone can use it. - -Intuitive - The network leverages the classic cryptological narrative of Alice and Bob -(with additional characters where appropriate). This character-based narrative -permeates the code-base and helps developers write safe, misuse-resistant code. - -Extensible - The network supports proxy re-encryption but can be -extended to provide support for other cryptographic primitives. - -Trustless - Data is never decrypted nor can the underlying private keys be -determined by the NuCypher network nodes. - -Secure - Access permissions are baked into the underlying encryption. -Under the hood the network implements the Umbral_ threshold -proxy re-encryption scheme to provide cryptographic access control. - -Privacy-Preserving - Access can only be explicitly granted by the data owner via -sharing policies so that the data owner has ultimate control over access -to their data. - How does NuCypher work? ----------------------- diff --git a/docs/source/staking/remote_worker_cli.rst b/docs/source/staking/remote_worker_cli.rst index 1a86937e0..1267a95ae 100644 --- a/docs/source/staking/remote_worker_cli.rst +++ b/docs/source/staking/remote_worker_cli.rst @@ -3,8 +3,8 @@ Remote Worker Management ======================== -Nucypher maintains some simple tools leveraging open source tools such as Ansible, -to make it easy to keep your Nucypher Ursula nodes working and up to date. +NuCypher maintains an CLI to assist with the management of multiple remote Nucypher Ursula nodes, leveraging +automation tools like Ansible and Docker. .. code:: bash diff --git a/docs/source/staking/running_a_worker.rst b/docs/source/staking/running_a_worker.rst index 6541840b1..dceedf1de 100644 --- a/docs/source/staking/running_a_worker.rst +++ b/docs/source/staking/running_a_worker.rst @@ -47,16 +47,17 @@ Best Practices Workers can demonstrate a vested interest in the success of the network by adhering to three core areas of responsibility (in order of importance): -#1 Keystore Diligence +**#1 Keystore Diligence** Requires that the custodian keep track of a secret seed which can be used to generate the entire keystore. - - Keep an offline backup up mnemonic seed phrases. - - Use a password manager to generate a strong password when one is required. +- Keep an offline backup up mnemonic seed phrases. +- Use a password manager to generate a strong password when one is required. -#2 Datastore Diligence +**#2 Datastore Diligence** Requires that material observed during the runtime be stored. + A running worker stores peer metadata, re-encryption key fragments ("Kfrags"), and "treasure maps". Loss of stored re-encryption key fragments will indicate slashing on the bonded stake. @@ -66,12 +67,13 @@ can issue a challenge which is verified onchain by the Adjudicator contract. As a civic matter, datastore diligence is important for Ursula for several reasons Including storing node validity status (and thus refraining from pestering nodes with unnecessary additional verification requests). Loss of peer metadata means that the worker -must rediscover and validate peers, slowly rebuilding its network view contributing to -lessened availability. +must rediscover and validate peers, slowly rebuilding it's network view while contributing to +lessened availability and higher network traffic. - - Maintain regular backups of the worker's filesystem and database. +- Maintain regular backups of the worker's filesystem and database. -#3 Runtime Diligence + +**#3 Runtime Diligence** Requires active and security-conscious participation in the network. @@ -79,18 +81,17 @@ A bonded node that is unreachable or otherwise invalid will be unable to accept policies, and miss out on inflation rewards. The bonded stake will remain locked until the entre commitment is completed. -.. important:: - - The worker's ethereum account must have enough ether to pay for transaction gas; - however, it is *not* necessary (and potentially risky) to hold NU tokens on a worker's - account for any reason. - - Secure the worker's keystore used in deployment. - Keep enough ETH on the worker to pay for gas. - Maintain high uptime; Keep downtime brief when required by updates or reconfiguration. - Update when a new version is available. - Monitor a running ursula for nominal behaviour and period confirmations. +.. caution:: + The worker's ethereum account must have enough ether to pay for transaction gas; + however, it is *not* necessary (and potentially risky) to hold NU tokens on a worker's + account for any reason. + .. TODO: separate section on backups and data (#2285) @@ -120,27 +121,33 @@ Because worker nodes perform periodic automated transactions to signal continued The worker's ethereum account must remain unlocked while the node is running. While there are several types of accounts workers can use, a software based wallet is the easiest method. -To create a new ethereum software account using the geth CLI run the following instructions: +.. note:: -.. code:: bash + To create a new ethereum software account using the ``geth`` CLI: - geth account new - ... + .. code:: bash + + geth account new + ... + +.. caution:: + + Stay safe handling ETH and NU: + + - Workers **do not** need NU for any reason: Do not keep NU on the worker's account. + - Do not store ETH on the worker - Keep only enough to pay for gas fees. + - Store the ethereum account password in a password manager when using a keystore. .. important:: - - Do not keep NU on the worker account: Workers **do not** need NU for any reason. - - Only keep enough ETH to pay for gas fees (The average cost of a commitment is ~200k gas). - - Store the ethereum account password in a password manager - - Backup the worker's private keys + If the worker's ethereum private key is lost or compromised: -.. important:: If the worker's ethereum private key is lost or compromised - - #. Create a new ethereum keypiar - #. Reconfigure the worker to use the new account ``nucypher ursula config --worker-address
`` + #. Inform the Staking operator/party. + #. Create a new ethereum account + #. Reconfigure the worker to use the new account ``nucypher ursula config --worker-address
--signer `` #. Bond the new address from the staking account (or inform the staking party). - Note that stakers can only rebond once every two periods. + Note that stakers can only rebond to a new worker once every two periods. 3. Run Worker @@ -228,8 +235,8 @@ View worker logs Upgrading to a newer version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When a new version is available a docker-launched worker can be updated by stopping the worker, -running docker pull, then start the worker. +When a new version is available a docker-launched worker can be updated by +stopping the worker, running docker pull, then restarting the worker. .. code:: bash @@ -324,6 +331,29 @@ To start Ursula services using systemd $ sudo systemctl restart ursula + +Run Worker Manually +^^^^^^^^^^^^^^^^^^^ + +If you'd like to use another own method of running the worker process in the background, or are +using one of the testnets, here is how to run Ursula using the CLI directly. + +.. code + + # Initialize Ursula + nucypher ursula init --provider --network --signer + + # Run Worker + nucypher ursula run + + +Replace the following values with your own: + + * ```` - The URI of a local or hosted ethereum node + * ```` - The name of a nucypher network (mainnet, ibex, or lynx) + * ```` - The URI to an ethereum keystore or signer: `keystore:///root/.ethereum/keystore` + + 4. Qualify Worker ----------------- diff --git a/docs/source/staking/stake_management.rst b/docs/source/staking/stake_management.rst index b6810a8e5..ac6fd5c25 100644 --- a/docs/source/staking/stake_management.rst +++ b/docs/source/staking/stake_management.rst @@ -37,17 +37,6 @@ To enable re-staking again: (nucypher)$ nucypher stake restake --enable -Additionally, you can enable **re-stake locking**, an on-chain commitment to continue re-staking -until a future period. Once enabled, the ``StakingEscrow`` contract will not -allow **re-staking** to be disabled until the release period begins, even if you are the stake owner. - -.. code:: bash - - (nucypher)$ nucypher stake restake --lock-until 12345 - -No action is needed to release the re-staking lock once the release period begins. - - .. _staking-prolong: Prolong