diff --git a/docs/source/architecture/upgradeable_proxy_contracts.rst b/docs/source/architecture/upgradeable_proxy_contracts.rst index 7bae697f7..c20cb27d7 100644 --- a/docs/source/architecture/upgradeable_proxy_contracts.rst +++ b/docs/source/architecture/upgradeable_proxy_contracts.rst @@ -2,7 +2,7 @@ Nucypher's Approaches to Upgradeable Contracts ============================================== Smart contracts in Ethereum are immutable... -Even if a contract can be deleted, it still exists in the blockchain after `selfdestruct`, and only the storage is cleared. +Even if a contract can be deleted, it still exists in the blockchain after ``selfdestruct``, and only the storage is cleared. 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. @@ -14,7 +14,7 @@ When this happens, the client changes the address used for a requested contract. .. note:: - There will be two deployed versions of the contract during storage migration)* + There will be two deployed versions of the contract during storage migration Approach B @@ -36,7 +36,7 @@ This is similar to the previous option, but this proxy doesn't have interface me This approach is not ideal, and has some restrictions: -* Sending Ether from a client's account to the contract uses the fallback function and such transactions can only consume 2300 gas (http://solidity.readthedocs.io/en/develop/contracts.html#fallback-function) +* Sending Ether from a client's account to the contract uses the fallback function and such transactions can only consume 2300 gas (http://solidity.readthedocs.io/en/develop/contracts.html#fallback-function). * Proxy contracts (Dispatcher) hold storage (not in the contract itself). While upgrading storage, values must be the same or equivalent (see below). @@ -48,18 +48,18 @@ Interaction scheme :target: ../.static/img/Dispatcher.png -`Dispatcher` - a proxy contract that redirects requests to the target address. +``Dispatcher`` - a proxy contract that redirects requests to the target address. It also holds its own values (owner and target address) and stores the values of the target contract, but not explicitly. -The client should use the resulting contract or interface ABI while sending request to the `Dispatcher` address. -The contract's owner can change the target address by using the `Dispatcher`'s ABI. -The `Dispatcher` contract uses `delegatecall` for redirecting requests, so `msg.sender` remains as the client address +The client should use the resulting contract or interface ABI while sending request to the ``Dispatcher`` address. +The contract's owner can change the target address by using the ``Dispatcher``'s ABI. +The ``Dispatcher`` contract uses ``delegatecall`` for redirecting requests, so ``msg.sender`` remains as the client address and uses the dispatcher's storage when executing methods in the target contract. .. warning:: - If target address is not set, or the target contract does not exist, results may be unpredictable because `delegatecall` will return `true`. + If target address is not set, or the target contract does not exist, results may be unpredictable because ``delegatecall`` will return ``true``. -Contract - upgradeable contract, each version must have the same ordering of storage values. +``Contract`` - upgradeable contract, each version must have the same ordering of storage values. New versions of the contract can expand values, but must contain all the old values (containing values from dispatcher **first**). This contract is like a library because its storage is not used. If a client sends a request to the contract directly to its deployed address without using the dispatcher, @@ -69,10 +69,10 @@ then the request may execute (without exception) using the wrong target address. Development ----------- -* Use `Upgradeable` as base contract for all contracts that will be used with `Dispatcher` -* Implement `verifyState(address)` method which checks that a new version has correct storage values -* Implement `finishUpgrade(address)` method which copies initialization data from library storage to the dispatcher's storage -* Each upgrade should include tests which check storage equivalence +* Use ``Upgradeable`` as base contract for all contracts that will be used with ``Dispatcher``. +* Implement ``verifyState(address)`` method which checks that a new version has correct storage values. +* Implement ``finishUpgrade(address)`` method which copies initialization data from library storage to the dispatcher's storage. +* Each upgrade should include tests which check storage equivalence. Sources @@ -80,6 +80,6 @@ Sources More examples: -* https://github.com/maraoz/solidity-proxy - Realization of using libraries (not contracts) but too complex and some ideas are obsolete after Byzantium hard fork -* https://github.com/willjgriff/solidity-playground - Most of the upgradeable proxy contract code is taken from this repository -* https://github.com/0v1se/contracts-upgradeable - Source code for verifying upgrade +* https://github.com/maraoz/solidity-proxy - Realization of using libraries (not contracts) but too complex and some ideas are obsolete after Byzantium hard fork. +* https://github.com/willjgriff/solidity-playground - Most of the upgradeable proxy contract code is taken from this repository. +* https://github.com/0v1se/contracts-upgradeable - Source code for verifying upgrade. diff --git a/docs/source/demos/finnegans_wake_demo.rst b/docs/source/demos/finnegans_wake_demo.rst index 9e8fb8da4..a3c68c103 100644 --- a/docs/source/demos/finnegans_wake_demo.rst +++ b/docs/source/demos/finnegans_wake_demo.rst @@ -9,7 +9,7 @@ Overview .. important:: - This demo requires connecting to a running network. By default the demo is hardcoded to connect to the local demo fleet. + This demo requires connecting to a running network. By default the demo is hardcoded to connect to the :doc:`local demo fleet `. This demo is an example of a NuCypher decentralized network allowing Alice to share @@ -40,16 +40,24 @@ Install Nucypher ---------------- Acquire the nucypher application code and install the dependencies. - For a full installation guide see the [NuCypher Installation Guide](../guides/installation_guide). + For a full installation guide see the :doc:`/guides/installation_guide`. Download the Book Text ---------------------- - For your convienence we have provided a bash script to acquire the "Finnegan's Wake" text. However, + For your convenience we have provided a bash script to acquire the "Finnegan's Wake" text. However, feel free to use any text of your choice, as long you you edit the demo code accordingly. - To run the script: `./download_finnegans_wake.sh` + To run the script: + +.. code:: + + (nucypher)$ ./download_finnegans_wake.sh Run the Demo --------------- - After acquiring a text file to re-encrypt, execute the demo by running: `python3 finnegans-wake-demo.py` + After acquiring a text file to re-encrypt, execute the demo by running: + +.. code:: + + (nucypher)$ python3 finnegans-wake-demo.py diff --git a/docs/source/demos/local_fleet_demo.rst b/docs/source/demos/local_fleet_demo.rst index 16c5dfbf6..5a1e576b2 100644 --- a/docs/source/demos/local_fleet_demo.rst +++ b/docs/source/demos/local_fleet_demo.rst @@ -12,9 +12,9 @@ Overview Currently only "Federated Only" mode is supported for local fleets All Demo Ursulas: - * Run on `localhost` - * In `--federated-only` mode - * On the `TEMPORARY_DOMIAN` (Implied by `--dev`) + * Run on ``localhost`` + * In ``--federated-only`` mode + * On the ``TEMPORARY_DOMIAN`` (implied by ``--dev``) * Using temporary resources (files, database, etc.) @@ -23,8 +23,8 @@ Running A Local Fleet 1. Install Nucypher -Acquire the nucypher application code and install the dependencies. -For a full installation guide see the [NuCypher Installation Guide](/guides/installation_guide). +Acquire the Nucypher application code and install the dependencies. +For a full installation guide see the :doc:`/guides/installation_guide`. 2. Run a Lonely Ursula @@ -37,7 +37,7 @@ The first step is to launch the first Ursula on the network by running: This will start an Ursula node: * With seednode discovery disabled - * On port `11500` + * On port ``11500`` 3. Run a Local Fleet of Ursulas @@ -51,13 +51,13 @@ Next, launch subsequent Ursulas, informing them of the first Ursula: This will run 5 temporary Ursulas that: * All specify the lonely Ursula as a seednode - * Run on ports `11501` through `11506` + * Run on ports ``11501`` through ``11506`` 4. Run an Entry-Point Ursula (Optional) While the local fleet is running, you may want an entry-point to introspect the code in a debugger. -For this we provide the optional script `run_single_demo_ursula.py` for your convenience. +For this we provide the optional script ``run_single_demo_ursula.py`` for your convenience. .. code:: @@ -75,9 +75,9 @@ Connecting to the Local Fleet Alternately, you can connect any node run from the CLI by specifying one of the nodes in the local fleet as a teacher, the same network domain, and the same operating mode. -By default, nodes started with the `--dev` flag run on a dedicated domain (`TEMPORARY_DOMAIN`) and -on a different port than the production default port (`9151`). -Local fleet Ursulas range from ports `11500` to `11506` by default. +By default, nodes started with the ``--dev`` flag run on a dedicated domain (``TEMPORARY_DOMAIN``) and +on a different port than the production default port (``9151``). +Local fleet Ursulas range from ports ``11500`` to ``11506`` by default. Here is an example of connecting to a node in the local development fleet: diff --git a/docs/source/guides/contribution_guide.rst b/docs/source/guides/contribution_guide.rst index ce3111ad9..3891cbb28 100644 --- a/docs/source/guides/contribution_guide.rst +++ b/docs/source/guides/contribution_guide.rst @@ -15,9 +15,9 @@ Running the Tests .. _Pytest Documentation: https://docs.pytest.org/en/latest/ -There are several test implementations in `nucypher`, however, the vast majority -of test are written for execution with `pytest`. -For more details see the `Pytest Documentation`_ +There are several test implementations in ``nucypher``, however, the vast majority +of test are written for execution with ``pytest``. +For more details see the `Pytest Documentation`_. To run the tests: @@ -38,13 +38,13 @@ Building Documentation .. note:: - `sphinx`, `recommonmark`, and `sphinx_rtd_theme` are non-standard dependencies that can be installed - by running `pip install -e .[docs]` from the project directory. + ``sphinx``, ``recommonmark``, and ``sphinx_rtd_theme`` are non-standard dependencies that can be installed + by running ``pip install -e .[docs]`` from the project directory. .. _Read The Docs: https://nucypher.readthedocs.io/en/latest/ -Documentation for `nucypher` is hosted on `Read The Docs`_, and is automatically built without intervention by following the release procedure. +Documentation for ``nucypher`` is hosted on `Read The Docs`_, and is automatically built without intervention by following the release procedure. However, you may want to build the documentation html locally for development. To build the project dependencies locally: @@ -55,8 +55,8 @@ To build the project dependencies locally: (nucypher)$ make html -If the build is successful, the resulting html output can be found in `nucypher/docs/build/html`; -Opening `nucypher/docs/build/html/index.html` in a web browser is a reasonable next step. +If the build is successful, the resulting html output can be found in ``nucypher/docs/build/html``; +Opening ``nucypher/docs/build/html/index.html`` in a web browser is a reasonable next step. Building Docker @@ -65,7 +65,7 @@ Building Docker Docker builds are automated as part of the publication workflow on circleCI and pushed to docker cloud. However you may want to build a local version of docker for development. -We provide both a `docker-compose.yml` and a `Dockerfile` which can be used as follows: +We provide both a ``docker-compose.yml`` and a ``Dockerfile`` which can be used as follows: *Docker Compose:* @@ -79,13 +79,13 @@ Issuing a New Release .. note:: - `bumpversion` is a non-standard dependency that can be installed by running `pip install -e .[deployment]` or 'pip install bumpversion'. + ``bumpversion`` is a non-standard dependency that can be installed by running ``pip install -e .[deployment]`` or ``pip install bumpversion``. .. important:: - Ensure your local tree is based on `master` and has no uncommitted changes. + Ensure your local tree is based on ``master`` and has no uncommitted changes. -1. Increment the desired version part (options are `major`, `minor`, `patch`, `stage`, `devnum`), for example: +1. Increment the desired version part (options are ``major``, ``minor``, ``patch``, ``stage``, ``devnum``), for example: .. code:: bash @@ -103,11 +103,11 @@ Issuing a New Release (nucypher)$ git push origin master && git push origin -5. Push the tag directly upstream by its name to trigger the publication webhooks on circleCI: +5. Push the tag directly upstream by its name to trigger the publication webhooks on CircleCI: .. code:: bash (nucypher)$ git push upstream -7. Monitor the triggered deployment build on circleCI for manual approval -8. Open a pull request with the resulting history in order to update `master` +7. Monitor the triggered deployment build on CircleCI for manual approval. +8. Open a pull request with the resulting history in order to update ``master``. diff --git a/docs/source/guides/federated_testnet_guide.rst b/docs/source/guides/federated_testnet_guide.rst index eba44f969..389aeef9f 100644 --- a/docs/source/guides/federated_testnet_guide.rst +++ b/docs/source/guides/federated_testnet_guide.rst @@ -48,21 +48,21 @@ As of January 2019, we are working with Python 3.6, 3.7, and 3.8. 2. Create Virtual Environment -Create a system directory for the nucypher application code +Create a system directory for the nucypher application code: .. code:: $ mkdir nucypher -Create a virtual environment for your node to run in using virtualenv +Create a virtual environment for your node to run in using ``virtualenv``: .. code:: $ virtualenv nucypher -p python3 ... -Activate your virtual environment +Activate your virtual environment: .. code:: @@ -73,15 +73,16 @@ Activate your virtual environment 3. Install Nucypher -Install nucypher with git and pip3 into your virtual environment +Install ``nucypher`` with ``git`` and ``pip3`` into your virtual environment. + +.. code:: + + (nucypher)$ pip3 install nucypher .. note:: We recommend NuFT nodes install directly from master to help ensure your node is using pre-released features and hotfixes - -.. code:: - (nucypher)$ pip3 install nucypher Re-activate your environment after installing