Nucypher
/
nucypher
mirror of https://github.com/nucypher/nucypher.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Remove legacy documentation. (please see https://docs.threshold.network instead).

pull/3312/head
Kieran Prasch 2023-10-24 23:21:10 +02:00 committed by KPrasch
parent 4a145e13ba
commit deada0f324
52 changed files with 0 additions and 24846 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
docs/Makefile
View File

@ -1,25 +0,0 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS = -W
SPHINXBUILD = python3 -m sphinx
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
clean:
echo "Removing old autodoc generated files..."
rm -rf "$(SOURCEDIR)/api"
@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

645
docs/NuCypher_Beachhead.ipynb
View File

@ -1,645 +0,0 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# The NuCypher Beachhead\n",
"### A starter kit for developers leveraging the NuCypher access management system \n",
"\n",
"*by Arjun Hassard, Product Lead & Struggling Writer @ NuCypher*\n",
"\n",
"\n",
"This resource is aimed at developers who have decided to leverage (or are considering leveraging) NuCypher's access management system – located on Github as *nucypher/nucypher*. By focusing on the most straightforward and fundamental functionality in the NuCypher codebase, this notebook serves as a 'beachhead' for one's technical strategy – an initial foothold for developers to: \n",
"\n",
"1) understand the principal capabilities of the NuCypher system\n",
"\n",
"2) form sensible plans for integrating NuCypher into their application or protocol \n",
"\n",
"3) scope out and develop features involving data sharing and access control\n",
"\n",
"We recommend using this resource to get comfortable with relatively high-level operations, for instance *ALICE.grant()* and *BOB.join_policy()*, before moving on to more advanced NuCypher libraries, such as *nucypher/pyUmbral* – that afford greater customization, provide opportunities to economize NuCypher network usage, and enable the architecting of more complex delegation workflows.\n",
"\n",
"Note: we will hereafter refer to the NuCypher access management system simply as 'NuCypher'."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### A note regarding the data sharing 'narrative'\n",
"We're going to walk through a typical data sharing journey, or 'narrative', centered around production-ready code snippets. In general terms, the narrative stars a *data controller*, who intends for a *designated recipient* to gain access to her data. The data controller proceeds to connect to the NuCypher network, then creates a data sharing policy specifically for the recipient. Later, when the recipient decides to request access to the data, the NuCypher network performs the necessary permission update. Without spoiling the ending, the recipient's access is delivered swiftly and securely, and without any subsequent action required from the data controller.\n",
"\n",
"In order to better illustrate the relationship between the functionality present here and the real-world outcomes one might observe in a digital application (that has integrated NuCypher), we will occasionally refer to two human end-users of a hypothetical *health record management platform*: \n",
"\n",
"- A medical patient (this is the aforementioned *data controller*) \n",
"- A doctor (this is the aforementioned *designated recipient*) \n",
"\n",
"These references will mostly appear under the subtitle: *\"Relevance to example real-world application\"*. It's worth noting that there is nothing special about patients or doctors from an access management perspective, other than that the underlying data shared via a medical application is likely to be sensitive, and the data's correct delivery critical. Hence, these hypothetical application users can be swapped out for any other end-user. \n",
"\n",
"Over the course of the narrative, we will also dive into important lower-level work occurring in the background, plus abstracted opportunities to customize. Please note that these are primarily conceptual explanations, and do not cover every single background process. Rather, the explanations are what we deem to be relevant to a developer's over-arching technical strategy. These reference will appear under the subtitle: \"Relevant work/optionality abstracted by *function/method/etc.*\"."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### A high-level refresher on NuCypher's underlying cryptography (this section can be skipped)\n",
"\n",
"*'Threshold proxy re-encryption' is the primary cryptographic scheme powering NuCypher technology. If you've read our white paper (\"NuCypher KMS: Decentralized key management system\"), or are already familiar with proxy re-encryption, you can safely skip this section. \n",
"\n",
"#### *Re-encryption* (traditional approach) \n",
"\n",
"Let's begin by establishing what we mean by *re-encryption*. In short, re-encryption is a method to update the permission(s) associated with encrypted data. For instance, say you wish to share a document with a colleague. The document file is encrypted with your public key (i.e. only you can decrypt it) and living in remote storage. In order for your colleague to gain access securely, the document file must be encrypted again – to their public key – that is, it must be *re-encrypted*. Traditionally, files can only be re-encrypted when they are in a plaintext state – i.e. it has been decrypted. Since this prerequisite decryption process tends to occur on a remote server, this is commonly known as *server-side decryption*. Typically, the file itself isn’t subject to server-side decryption. Instead, a cryptographic conduit to the file, such as a symmetric key, undergoes the necessary decryption (and subsequent re-encryption to the colleague's public key). Either way, this approach requires you to trust at least one central authority with direct or indirect access to the contents of your document. \n",
"\n",
"#### *Proxy* Re-encryption \n",
"\n",
"Proxy re-encryption brings us closer to *true privacy* by replacing the fully trusted central authority (who *can* see your data during the re-encryption process, if they choose to), with a 'semi-trusted' third-party proxy (who *cannot* see your data during the re-encryption process, unless they successfully collude with the recipient). \n",
"\n",
"Let's walk through a simplified proxy re-encryption flow. As with traditional re-encryption, we'll begin with your encrypted bulk data (a document), living in remote storage. The 'conduit' to the document – a standard symmetric key – has been encrypted with your public key – and we'll call the output of this encryption *'Ciphertext A'*. \n",
"\n",
"As before, you wish to grant a colleague access to the document. To achieve this with proxy re-encryption, your application generates a special kind of key known as a *re-encryption key*. This is ‘constructed’ using your private key, and your colleague’s public key. At no point is your private key transferred anywhere, nor exposed to anyone. Nor is it possible to reverse engineer your private key from the re-encryption key – again, barring collusion between the proxy and the recipient, your colleague.\n",
"\n",
"Next, the *re-encryption key* and *Ciphertext A* are sent to an available proxy. The proxy’s job is to transform Ciphertext A using the re-encryption key. What emerges from the transformation is a totally new ciphertext – *'Ciphertext B'* – made especially for your colleague – decryptable using their private key. When they decrypt *Ciphertext B*, they get the original symmetric key in plaintext – which they use to access the original document you shared with them.\n",
"\n",
"The presence of a third-party (the proxy) confers a range of benefits to developers, which we'll explore in detail over the course of this notebook. However, there is a deeply significant attribute to note at this stage - despite the fact a third-party is *managing access* to your data, they do not ever *gain access* to the data. Both the document and corresponding symmetric key remained safely encrypted throughout entire the sharing journey. In other words, you didn't have to trust the proxy, or indeed anyone, to get your colleague access to your document. \n",
"\n",
"#### *Threshold* Proxy Re-encryption \n",
"\n",
"*Threshold proxy re-encryption*, also known as *'Umbral'*, is the official cryptographic foundation on which the NuCypher access management system is built. *Umbral* takes standard *Proxy Re-encryption* and increases the security and performance.\n",
"\n",
"At a very high-level, the main improvement Umbral brings to *proxy re-encryption* involves the all-important re-encryption key. Rather than sending it to a single proxy, the re-encryption key for a sharing policy is split into multiple fragments (called *'KFrags'*). These are sent to participating proxies (for example, 20 proxies), each of whom uses their KFrag to transform a ciphertext. This generates a fragment of transformed ciphertext (called a *'CFrag'*). When a requisite number of CFrag outputs are combined, a complete ciphertext emerges (similar to *'Ciphertext B'* from earlier), that the recipient can use to access the underlying data. \n",
"\n",
"Umbral is an *'M-of-N'* scheme that employs a form a of Shamir Secret Sharing at the CFrag collation stage. This enables the generation of a complete *Ciphertext B* from a smaller number of CFrags than the number of KFrags originally sent out to proxies. The minimum 'threshold' of CFrags required to complete the sharing process can be set in advance by the developer, hence the scheme's name. This approach brings valuable security and network redunancy benefits. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"With all this in mind, let's look at some code!"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Importing stuff\n",
"We'll start by importing two built-in functions. We'll also import *maya*, which makes managing timezones easier."
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {
"collapsed": true
},
"outputs": [
{
"ename": "ModuleNotFoundError",
"evalue": "No module named 'maya'",
"output_type": "error",
"traceback": [
"\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
"\u001b[0;31mModuleNotFoundError\u001b[0m Traceback (most recent call last)",
"\u001b[0;32m<ipython-input-4-61648c1aad25>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[1;32m 1\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0mdatetime\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 2\u001b[0m \u001b[0;32mimport\u001b[0m \u001b[0msys\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 3\u001b[0;31m \u001b[0;32mimport\u001b[0m \u001b[0mmaya\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
"\u001b[0;31mModuleNotFoundError\u001b[0m: No module named 'maya'"
]
}
],
"source": [
"import datetime\n",
"import sys\n",
"import maya"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next, we'll import some Classes – these bestow specific powers to each 'character' involved in the data sharing narrative. \n",
"\n",
"A common misconception made about the characters present in the NuCypher codebase is that they precisely embody the end-users of a digital application – a patient, a doctor, etc. Instead, the NuCypher characters are in fact the *tools*, or *devices*, utilized by end-users to achieve their goals – not the end-users themselves. This distinction will become clearer as we introduce each character (*Alice*, *Bob*, *Ursula* & *Enrico*) in detail."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from nucypher.characters.lawful import Alice, Bob, Ursula\n",
"from nucypher.characters.lawful import Enrico"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Finally, we'll import modules which enable the NuCypher network to function correctly."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"from examples.sandbox_resources import SandboxNetworkyStuff\n",
"from nucypher.network.node import NetworkyStuff"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### *Ursula*: the proxy & network node\n",
"The first character to introduce is *Ursula* – fulfilling the role of *proxy* in *proxy re-encryption*. Generally, we can think of a proxy as a third-party, anonymous, remote machine whose sole purpose is to ingest encrypted text and transform it, thereby performing a permission update. In other words, provide the *re-encryption* in *proxy re-encryption*. \n",
"\n",
"The NuCypher network, once launched, will comprise thousands of proxies scattered around the world, collectively performing the re-encryptions necessary to power the data sharing narratives within applications/protocols leveraging NuCypher. Every time a permission needs updating, or a data recipient has their access to granted or revoked, multiple Ursulas are marshalled to make this happen. Ursulas provide this service in exchange for fees, paid by developers like yourself. Ursulas are referred to as nodes, network participants, network nodes, miners, re-encryptors, proxies and service-providers in other contexts. Similar to the other characters, 'Ursula' represents the device utilized by a human node operator to provide a re-encryption service.\n",
"\n",
"We won't be touching Ursula directly over the course of this narrative. Instead, we'll be focusing on the characters most pertinent to an end-user facing application: Alice, Bob & Enrico. Nonetheless, it's critical to have a grasp of Ursula's role, at least on a conceptual level – as there is a great deal of behind-the-scenes interaction with Ursulas occurring in virtually all NuCypher data sharing narratives. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### *Alice*: the data controller\n",
"Let's now introduce Alice, the second character in our data sharing narrative. Like all NuCypher characters, Alice has a Class which prescribes her various unique abilities/powers. She represents all of the following: \n",
"- Data producer\n",
"- Data owner\n",
"- Data delegator\n",
"- Data controller (we will use hereafter 'data controller' to signify all of the above) \n",
"\n",
"As mentioned previously, it's most precise to think of Alice as the device, or devices, that a real-life data controller would use to manage their data. In our hypothetical application, that would be the patient, managing their medical data 'through' the Alice character.\n",
"\n",
"Let's instantiate Alice and ensure that she is properly connected to the NuCypher network. *Network_middleware* works as a 'bridge' between our application and the network – the details of which are not relevant to this narrative. "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"ALICE = Alice(network_middleware=network_middleware)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The next step is to set some basic parameters for a sharing policy, which we'll invoke later when we add a designated recipient to it. For this narrative, we'll choose the following four settings:\n",
"\n",
"1) We set the policy to expire 5 days from the moment it is created. \n",
"\n",
"*Note: This is an example of policy revocation. This feature is powerful because, with NuCypher, policies can be revoked (and granted) based on arbitrary conditions. Revocation is also, uniquely, enforced by the network itself. In this case, the policy is time-bounded. However, a policy could also be programmed to expire based on express input from a user, or the fulfilment (or lack of fulfilment) of other conditions – such as a confirmed payment, receipt of data, receipt of signature, or more complicated rules written into a smart contract. Policy statuses could even be determined by the output of an Oracle in relation to the outcome of a real-world event.*\n",
"\n",
"*You will notice that there are no further references to revoking policies after this line. That's because the relevant functions for more advanced policy revocation are not complete, and this notebook only contains working code. Look out for updates on this front.*"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"policy_end_datetime = maya.now() + datetime.timedelta(days=5)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"2) We'll set 'n', the number of Ursulas (proxies) to which the forthcoming re-encryption job will be assigned, to 1. \n",
"\n",
"*Note: Normally, outside of a demo walkthrough like this, a policy's re-encryption job is always assigned to many more Ursulas than just 1. Setting n > 1 splits the re-encryption key into a corresponding number of fragments, each of which is sent to a different Ursula. Generally, the greater the number of key fragments (& Ursulas), the greater the security of the policy. We'll explain this process in greater detail later, in the section entitled 'Retrieiving the data with Bob'.* "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"n = 1"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"3) We'll set 'm', the minimum number of Ursulas required to complete the re-encryption job for the recipient to access the data, also to 1. \n",
"\n",
"*Note: Similarly, the minimum number of re-encrypting Ursulas, or the 'threshold', would always be set to greater than 1. As this is an 'm-of-n' scheme, n should be greater than m. A possible choice is m = 10, n = 20.*"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [],
"source": [
"m = 1"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"4) Finally, we'll add a path – this is the 'label' of the data we intend to share. \n",
"\n",
"*Note: the label variable does not refer to the exact file that we intend to share. Rather, it functions more like a tag, where any amount of data can utilize the same label – somewhat like multiple files in a single directory. As we shall see, this means that the data does not necessarily need to exist at this stage, and can be produced later.*"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"label = b\"secret/files/and/stuff\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Before we can begin granting permissions to anyone, we need Alice to connect to the NuCypher network and the Ursulas/proxies that will perform the re-encryption service on her behalf. We bootstrap this process by connecting Alice to one known Ursula, who then connects Alice to other Ursulas in their network. Note: there will be an option to start the connection process with Ursulas run by NuCypher, if this is preferable. "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"ALICE.network_bootstrap([(\"localhost\", 3601)])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### *Bob*: the designated recipient\n",
"Bob is the second character in the data sharing narrative. Conceptually, his role is fairly passive – he is simply the chosen recipient. However, as we shall see, there are a number of more complex actions/requirements this character must perform/fulfill in order to securely gain access to the data. Remember, like Alice, Bob represents the device(s) a real-world data recipient – or in our hypothetical application, the doctor – would use to achieve their goals. \n",
"\n",
"Right now, we'll just instantiate Bob, so we can add him to Alice's sharing policy in the next section. "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"BOB = Bob()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Creating a sharing policy with *Alice*\n",
"It's time to create our first sharing policy, using the .*grant()* function. Sharing policies have three distinguishing features, which are defined when a policy is granted: \n",
"\n",
" 1) The data controller, *Alice*.\n",
" \n",
" 2) The designated recipient, *Bob*.\n",
" \n",
" 3) The file(s) location, *label*.\n",
"\n",
"In theory we could leave the *label* argument empty at this stage. However, this would mean ceding important security benefits. For example, in the highly unlikely scenario where the designated recipient (Bob) successfully colludes with all the proxies (Ursulas) partaking in this sharing narrative, the colluders would only gain access to the data tagged with this policy's single label. This security feature is defined as *weak perfect forward secrecy* (wPFS), wherein all other data belonging to the data controller, accessible via older sharing policies, is protected from these adversaries – provided that said adversaries did not also actively interfere (i.e. collude in the same way) with those older policies. In this way, labels are a compromise for creating a practical, reliable form of forward secrecy in a proxy re-encryption environment.\n",
"\n",
"\n",
"##### Relevance to example real-world application\n",
"\n",
"In our hypothetical real-world application, the granting of a policy is likely to be the first instance where the medical patient proactively does something: namely, decides to add a specific doctor to an approved list of those that can see her health records. Note that Alice does not need to encrypt or send the actual data at this moment. In fact, the data doesn't even need to exist yet – for example, not-yet-available results from a medical exam could be shared automatically under this policy (to all the doctors added to it), once they are ready. More on this scenario below, when we introduce *Enrico*.\n",
"\n",
"A few more words on the *label* architecture. Besides the security benefits mentioned above, they are a flexible way to choose per-category sharing parameters for specific data. For example, a patient might have various categories of health data, each with its own unique set of permissions – their oncology results might be shared with a small group of specialists for a limited period, while the cardio data from a wearable device is shared with all their doctors, indefinitely. Labels enable the application developer to stratify the data in this way, without having to store all the data with the same parameters in the same location or file path. \n",
"\n",
"\n",
"##### Relevant work/optionality abstracted by the .grant() method\n",
"\n",
"When *.grant()* is run, a great deal of background work is triggered – work which lays a metaphorical path through the NuCypher network for the forthcoming sharing of data. \n",
"\n",
"Firstly, the number of Ursulas we requested earlier (n), need to be located. Next, an \"arrangement\" is proposed to those Ursulas, which contains relevant parameters to help each Ursula decide if they want to participate. For example, the arrangement object specifies the funds available to pay for the re-encryption service (known as the \"deposit\" – this can be altered to suit the application's economic requirements) as well as the duration of the policy, which we set earlier. \n",
"\n",
"Once the required number (n) of Ursulas have accepted the arrangement, an equivalent number of re-encryption key fragments, known as \"KFrags\", are generated. A quick reminder: a *re-encryption key* is a special key unique to NuCypher. It is constructed, safely and locally, using Alice's private key and Bob's public key. Ursulas use re-encryption keys to transform/re-encrypt ciphertexts such that they are decryptable by Bobs – specifically, the Bobs who supplied their public key. So, to get KFrags, the re-encryption key is split into multiple fragments. Each of those stands ready to be sent to the participating Ursulas – one KFrag for each Ursula. \n",
"\n",
"Finally, the *.grant()* method also triggers the generation of a \"TreasureMap\" – this returns the locations of all the participating Ursulas, once they have confirmed their involvement. Bob will use the TreasureMap later, when he wants to retrieve the data Alice has shared with him. \n",
"\n",
"Now we have a sense of what's happening under the hood, let's go ahead and create a sharing policy: "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"policy = ALICE.grant(BOB, \n",
" label,\n",
" threshold=m, \n",
" shares=n,\n",
" expiration=policy_end_datetime)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Our final step involving Alice is to save her public key, such that Bob can easily locate and use it, once the designated recipient is ready to request access. \n",
"\n",
"*Note: Alice has multiple public keys, that perform different roles in the data sharing process. The public key we are saving in this step is her signing public key. Later, when we want to encrypt the underlying data, we will employ her encrypting public key.*\n",
"\n",
"We can quickly get her *signing* public key via the 'stamp' function, then cast it into a convenient, immutable byte sequence for retrieval later."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"alices_pubkey_saved_for_posterity = bytes(ALICE.stamp)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This juncture marks the end of Alice's involvement in the data sharing narrative, and by extension, the required involvement of a real-life data controller – or medical patient. \n",
"\n",
"Of course, if the data controller wished to create another policy, they would need to return online in order to choose the recipient and label, potentially tweak other parameters, and execute the grant function. \n",
"\n",
"Nevertheless, with NuCypher, a medical patient would be able to go permanently offline at this point, and still see data shared with their doctor, provided that it fell under the correct label – for example, diagnosis data that is yet to be finalized. This affords our medical application, or any other application leveraging NuCypher, a great deal of flexibility. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Joining a sharing policy with *Bob*\n",
"As it stands, we have successfully created a sharing policy for a specific Bob (our recipient's device), and this policy is now sitting on the NuCypher network, readily awaiting for Bob to join it. Once Bob joins the policy, the designated recipient (the doctor) will be able to access future data shared on it. \n",
"\n",
"##### Relevance to example real-world application\n",
"\n",
"Before getting into the joining details, it's worth acknowledging the various ways a recipient would actually join a policy. In this example, we have chosen a situation where some time passes in between the creation of the policy and the first time it is used. There is also a sense that the recipient has *decided* to join the policy. However, one could very well design an application where the opposite occurs – the specified recipient is automatically, and immediately, added to any policy bearing their public key. Plus, anything in between, including the joining action being contingent on the fulfilment of specified conditions. \n",
"\n",
"##### Relevant work/optionality abstracted by the .join_policy() method\n",
"\n",
"When Bob joins the policy, a few important things occur in the background. Information relating to the policy, including the data controller and recipient's respective public keys, and the data's *label*, are hashed and saved as a variable ('hrac') for record-keeping and other uses. Separately, Bob also connects to the NuCypher network, and, using the TreasureMap and *hrac*, finds the participating Ursulas. This gets Bob, and therefore the recipient, ready to receieve data once it is sent. \n",
"\n",
"To join the policy, Bob needs certain information to hand: \n",
"\n",
"1) The *label* – he needs to know what data he's after.\n",
"\n",
"2) *Alice's signing key* – he needs the data controller's signature\n",
"\n",
"3) *Signature verification* – he needs to check the signature is legitimate and that he's receiving data from the correct source. \n",
"\n",
"4) *List of nodes* – he can optionally connect himself to the network at this time, using the same 'bootstrap' method Alice used earlier on in the narrative."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"BOB.join_policy(label, #1 \n",
" alices_pubkey_saved_for_posterity, #2\n",
" verify_sig=True, #3\n",
" node_list=[(\"localhost\", 3601)] #4 \n",
" )"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Preparing the bulk data (this section can be skipped)\n",
"We're going to prepare some data to play the role of the data that would actually be shared in a real-world application - the 'underlying' or 'bulk' data. The main reason we include this section is to give readers a sense of the data format we'll be working with next, but there's nothing here that's unique to NuCypher. \n",
"\n",
"In short, we're going to decompose the novel 'Finnegans Wake' into plaintext lumps, and then share these periodically. We'll also print out some metadata to gauge performance. \n",
"\n",
"##### Relevance to example real-world application\n",
"\n",
"It's worth pointing out that, in a normal application's architecture, the 'data' shared in a narrative like this is unlikely to a human-readable text. Instead, the literary passage we are sharing here is standing in for a more likely candidate – a symmetric key pertaining to some individual bulk data (e.g. photos, videos, chat message(s), collaborative documents, medical data, etc.), hosted in decentralized (IPFS, Storj etc.) or centralized (S3, etc.) storage somewhere, that the recipient can use to decrypt and view it. "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"finnegans_wake = open(sys.argv[1], 'rb')\n",
"\n",
"start_time = datetime.datetime.now()\n",
"\n",
"for counter, plaintext in enumerate(finnegans_wake):\n",
" if counter % 20 == 0:\n",
" now_time = datetime.datetime.now()\n",
" time_delta = now_time - start_time\n",
" seconds = time_delta.total_seconds()\n",
" print(\"********************************\")\n",
" print(\"Performed {} PREs\".format(counter))\n",
" print(\"Elapsed: {}\".format(time_delta.total_seconds()))\n",
" print(\"PREs per second: {}\".format(counter / seconds))\n",
" print(\"********************************\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Encrypting and sharing on Alice's behalf with *Enrico*\n",
"\n",
"We're nearly there! We have a sharing policy, a confirmed recipient, and some underlying/bulk data we want to share. However, the bulk data is currently in plaintext format. To securely transport it to the recipient, we need to encrypt it – in such a way that it can remain encrypted until it reaches Bob, and that he alone can decrypt it.\n",
"\n",
"To achieve this, we're going to introduce the final character in our narrative: *'Enrico'*. An important reason Enrico exists is so that Alice (& the data controller) are not needed at this stage in the narrative to perform the encryption themselves. However, this may be doing Enrico a disservice, as the character can be harnessed for more – including 'producing' data on the data controller's behalf. \n",
"\n",
"##### Relevance to example real-world application\n",
"\n",
"In general, Enrico affords great flexibility to applications leveraging NuCypher, because it widens the range of possible entities that can encrypt for Bob. \n",
"\n",
"Imagine a medical scenario where the patient is expecting a regular stream of test results, from a third-party blood-testing lab, at some point in the future, and wants those results to be immediately shared with the doctors on an existing sharing policy. It would be undesirable to stay online and continually grant access to each test-result as it arrived. \n",
"\n",
"To avoid this, the application can assign a special role to the blood-testing lab, such that the lab gains the encryption powers of Enrico. Similar to the way 'Alice' represents the patient's device, Enrico can do the same for primary producers of data – in this case, the blood-testing lab. Hence, the lab can write the new data onto the sharing policy, under the specified label. Then, the designated doctors can access it. Thus, Enrico is 'producing' data on the patient's behalf. \n",
"\n",
"Note: this does not mean that Enrico, or the lab, can access other data on the sharing policy - including their own test results, once they've been saved. Accessing the data would require a *read* permission, which has only been granted to Bob – through the existence of a sharing policy, and re-encryption key, in his name. Rather, Enrico(s) have been solely granted a *write* permission to the policy. \n",
"\n",
"In general, these write permissions can be recorded directly onto a distributed ledger, such that the application can reliably confirm the correct actor is producing/encrypting data for a given sharing policy. As we will encounter below, this data also comes with a signature, which helps the recipient further verify its authenticity. \n",
"\n",
"\n",
"Let's first create a Enrico specifically for our sharing policy. "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"data_source = Enrico(policy_pubkey_enc=policy.public_key)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We're going to use Enrico to encrypt the data we wish to share – the passages from Finnegans Wake. We're also going to generate an artifact known as a 'MessageKit' – this contains a ciphertext (the encrypted version of the passages), plus two unique identifiers: the policy's public key, and the recipient's public key. \n",
"\n",
"We'll also take this opportunity to generate a signature. The signature is unique to that message, and, when verified, can confirm that the data has not been corrupted or manipulated while in transit, and that the data did indeed come from the expected, correct Enrico. This further mitigates the risk of incorrect data being added to a label from a malignant source that has gotten hold of the relevant public keys. The signature can be sent to Bob via a side-channel, or published publicly as a evidence of the manner in which the data was shared.\n",
"\n",
"Let's go ahead and create a tuple for these: "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"message_kit, _signature = data_source.encapsulate_single_message(plaintext)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We want Bob to be able to verify that MessageKit and signature he will soon access came from the right Enrico, so we'll save its public key, in the same way we did Alice's public key earlier: "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"data_source_public_key = bytes(data_source.stamp)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Retrieiving the data with *Bob*\n",
"To give the designated recipient even greater independence with regard to when and how they access the data, we're going to include a snippet which reconstructs the Enrico from Bob's perspective. This may not be necessary, if the Enrico remains online and available, but this means there's no obligation to keep Enrico around."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"enrico_as_understood_by_bob = Enrico.from_public_keys(\n",
" policy_public_key=policy.public_key,\n",
" enrico_public_key=data_source_public_key,\n",
" label=label\n",
" )"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We're now in the endzone – just one more method to run before our recipient gets their hands on the 'cleartext' – the data that the data controller intended them to see, decrypted and readable. We'll achieve this with *.retrieve()*, which takes three arguments to compute correctly: \n",
"\n",
"1) The MessageKit – the actual data. \n",
"\n",
"2) Enrico – where we got the data from.\n",
"\n",
"3) Alice's public key – an identifier for the original delegator of the data. \n",
"\n",
"##### Relevance to example real-world application\n",
"\n",
"In our hypothetical medical application, this is the stage where the doctor accesses the patient's health records. How the doctor does this is flexible – the application could automatically retrieve the data as soon as it is suitably encrypted by Enrico, or the doctor could be required to proactively decide when they want their access to begin – the latter may be useful if it's desirable to notify the patient that the doctor has now begun their analysis/diagnosis, and/or how much time the doctor spends looking at the data, for example. \n",
"\n",
"##### Relevant work/optionality abstracted by the .retrieve() method\n",
"\n",
"Although the inputs above are easy to grasp, what happens in the background is more complex. \n",
"\n",
"The first thing that needs to be checked is that the number of Ursulas who completed a re-encryption is equal to or greater than the minimum we specified, right at the start (m). We set this to be some fraction of n (the total number of Ursulas involved), to protect against redundancy and ensure that, even if some Ursulas fail to re-encrypt the KFrags they'd received, that the data could reach it's destination. We perform this check using the TreasureMap we generated above, which guides us to the participating Ursulas. \n",
"\n",
"Now we know that a sufficient number of re-encryptions occurred, it's time to work with the output of that work – \"CFrags\". In the same way a KFrag is a fragment of key, a CFrag is a fragment of ciphertext. When brought together by Bob, these fragments combine into a complete ciphertext, that can be used to access the underlying data. \n",
"\n",
"So, the next step is to gather those CFrags. In order to ensure that the number of collectable CFrags is as expected, the figure is checked against something called a WorkOrder, which was generated previously. It's not worth digging into this, other than to say there is an auditable trail that helps prevent aberrant or malicious behavior by Ursulas.\n",
"\n",
"Finally, we're going to attach the gathered CFrags to an artifact called a 'capsule'. The capsule's role, for the purposes of this narrative, is to bring together the MessageKit (the data we want to share) and the collection of ciphertext fragments, such that Bob can get to the cleartext, and hence the designated recipient is able to access the data they were granted. In reality, the capsule fulfils more than just this, but we can think of the capsule as a way of simply protecting the underlying data – for example in the scenario where Bob makes a request without the correct CFrags.\n",
"\n",
"\n",
"Now we understand the essential processes taken care of by *.retrieve()*, let's use it to get our hands on the data we set out to share:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
" delivered_cleartext = BOB.retrieve(message_kit=message_kit,\n",
" data_source=enrico_as_understood_by_bob,\n",
" alice_verifying_key=alices_pubkey_saved_for_posterity)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We've done it! Let's quickly check it's correct:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
" assert plaintext == delivered_cleartext\n",
" print(\"Retrieved: {}\".format(delivered_cleartext))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Congratulations on making it through the NuCypher Beachhead. This notebook is certainly lengthy, but it exists as a initial point of reference for the entire NuCypher Access Management System. Once you have digested the concepts that we explored here, you are in a great position to plan out an NuCypher integration, and eventually, provide your users with secure, flexible and powerful data sharing functionality. \n",
"\n",
"Whether reading this notebook was your first dive into NuCypher, or you've been familiar with our codebase for a while, we're very keen to hear your feedback. We're particularly interested in whether this notebook has the right depth, detail, clarity and coherence. You can email me – arjun [at] nucypher [dot] com. "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.6.4"
}
},
"nbformat": 4,
"nbformat_minor": 2
}

35
docs/make.bat
View File

@ -1,35 +0,0 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
:end
popd

BIN
docs/source/.static/img/Annotated-Ursula-Status-Webpage-v1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 566 KiB

705
docs/source/.static/img/Annotated-Ursula-Status-Webpage-v2.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 864 KiB

BIN
docs/source/.static/img/Dispatcher.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 131 KiB

3434
docs/source/.static/img/alice_grant.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 564 KiB

3283
docs/source/.static/img/bob_retrieve.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 562 KiB

3
docs/source/.static/img/correctness_verification_schematic.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 18 KiB

2025
docs/source/.static/img/enrico_encrypt.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 424 KiB

667
docs/source/.static/img/heart_monitor.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 414 KiB

BIN
docs/source/.static/img/nu_epics.jpg
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.5 MiB

BIN
docs/source/.static/img/nu_support.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 6.5 MiB

BIN
docs/source/.static/img/nucypher.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 11 KiB

234
docs/source/.static/img/nucypher_logo.svg
View File

@ -1,234 +0,0 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="756.9975"
height="665.00201"
viewBox="0 0 756.9975 665.00201"
version="1.1"
id="svg2"
inkscape:version="0.92.3 (2405546, 2018-03-11)"
sodipodi:docname="nucypher_logo_transparent.svg">
<metadata
id="metadata65">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title>Desktop 4</dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<sodipodi:namedview
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1"
objecttolerance="10"
gridtolerance="10"
guidetolerance="10"
inkscape:pageopacity="0"
inkscape:pageshadow="2"
inkscape:window-width="3440"
inkscape:window-height="1351"
id="namedview63"
showgrid="false"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0"
inkscape:zoom="1.3037281"
inkscape:cx="-20.614352"
inkscape:cy="361.37589"
inkscape:window-x="0"
inkscape:window-y="40"
inkscape:window-maximized="1"
inkscape:current-layer="svg2" />
<title
id="title4">Desktop 4</title>
<desc
id="desc6">Created using Figma</desc>
<g
id="wordmark"
transform="translate(-3901,3136)">
<g
id="Vector">
<use
xlink:href="#path0_fill"
transform="translate(3901,-2624.64)"
id="use17"
style="fill:#343131"
x="0"
y="0"
width="100%"
height="100%" />
</g>
<g
id="g19">
<use
xlink:href="#path1_fill"
transform="translate(4016.34,-2590.23)"
id="use21"
style="fill:#343131"
x="0"
y="0"
width="100%"
height="100%" />
</g>
<g
id="g23">
<use
xlink:href="#path2_fill"
transform="translate(4107.25,-2627)"
id="use25"
style="fill:#343131"
x="0"
y="0"
width="100%"
height="100%" />
</g>
<g
id="g27">
<use
xlink:href="#path3_fill"
transform="translate(4224.29,-2590.25)"
id="use29"
style="fill:#343131"
x="0"
y="0"
width="100%"
height="100%" />
</g>
<g
id="g31">
<use
xlink:href="#path4_fill"
transform="translate(4322.33,-2592.59)"
id="use33"
style="fill:#343131"
x="0"
y="0"
width="100%"
height="100%" />
</g>
<g
id="g35">
<use
xlink:href="#path5_fill"
transform="translate(4423.35,-2624.68)"
id="use37"
style="fill:#343131"
x="0"
y="0"
width="100%"
height="100%" />
</g>
<g
id="g39">
<use
xlink:href="#path6_fill"
transform="translate(4512.54,-2592.61)"
id="use41"
style="fill:#343131"
x="0"
y="0"
width="100%"
height="100%" />
</g>
<g
id="g43">
<use
xlink:href="#path7_fill"
transform="translate(4610.36,-2592.59)"
id="use45"
style="fill:#343131"
x="0"
y="0"
width="100%"
height="100%" />
</g>
</g>
<g
id="coinmark"
transform="translate(-3901,3136)">
<g
id="g48">
<use
xlink:href="#path8_fill"
transform="translate(3964,-3136)"
id="use50"
style="fill:#ffffff"
x="0"
y="0"
width="100%"
height="100%" />
</g>
</g>
<defs
id="defs52">
<path
id="path0_fill"
d="M -1.92724e-6,1.54153e-5 H 18.5035 L 71.4878,82.3147 c 1.8468,2.8867 3.5334,5.8729 5.0521,8.9449 V 1.54153e-5 H 94.0961 V 118.073 H 75.5295 L 22.7136,35.7588 C 20.8667,32.872 19.1801,29.8859 17.6614,26.8138 V 118.073 H -1.92724e-6 Z"
inkscape:connector-curvature="0" />
<path
id="path1_fill"
d="M 0,-3.85381e-6 H 17.2194 V 50.2601 c 0,12.986 6.7362,19.9105 18.5456,19.9105 12.3145,0 21.9347,-10.5235 21.9347,-24.9617 V -3.85381e-6 H 74.919 V 83.6617 H 57.6997 V 70.1495 C 55.1099,75.0671 51.192,79.1593 46.3915,81.961 41.591,84.7627 36.1005,86.1613 30.5444,85.9979 14.167,85.9979 0,75.8743 0,53.7961 Z"
inkscape:connector-curvature="0" />
<path
id="path2_fill"
d="M 110.158,91.7647 C 97.8431,111.822 84.0129,122.788 58.5417,122.788 24.966,122.788 5.1393e-6,97.5316 5.1393e-6,61.394 5.1393e-6,25.2563 26.65,-6.42302e-6 59.3837,-6.42302e-6 83.5077,-6.42302e-6 101.716,12.6282 109.905,30.5181 L 95.4012,41.0416 C 86.981,24.6881 75.319,16.585 59.1311,16.585 c -22.2715,0 -40.5013,18.9423 -40.5013,44.8721 0,25.6352 17.0509,44.8719 40.3329,44.8719 15.8511,0 28.3341,-7.5977 37.2806,-24.4563 z"
inkscape:connector-curvature="0" />
<path
id="path3_fill"
d="m 12.483,101.741 c 2.4002,1.048 4.981,1.62 7.5993,1.684 4.3785,0 7.073,-1.347 10.1253,-8.9452 L 34.0809,84.1879 -1.41331e-5,7.70763e-6 H 19.7454 L 43.3642,60.3838 66.8145,7.70763e-6 H 85.7601 L 45.2798,100.541 c -5.3889,13.66 -13.325,18.711 -23.4503,18.711 -4.119,-10e-4 -8.2141,-0.626 -12.14623,-1.852 z"
inkscape:connector-curvature="0" />
<path
id="path4_fill"
d="M -3.08358e-5,2.35726 H 17.1983 V 15.1748 C 22.4399,6.90339 33.9125,6.42302e-6 46.9007,6.42302e-6 67.804,6.42302e-6 85.5285,16.5219 85.5285,44.1986 c 0,27.1506 -17.7245,44.1986 -40.1434,44.1986 -11.9989,0 -22.7978,-5.388 -28.1868,-13.8278 V 120.452 H -3.08358e-5 Z M 16.0826,44.1986 c 0,16.8376 11.641,28.3293 25.9765,28.3293 14.3354,0 25.9764,-11.4707 25.9764,-28.3293 0,-16.8586 -11.641,-28.3502 -25.9764,-28.3502 -14.3355,0 -25.9765,11.4706 -25.9765,28.3502 z"
inkscape:connector-curvature="0" />
<path
id="path5_fill"
d="M 75.9084,118.116 H 58.7101 V 66.8451 c 0,-11.9757 -7.094,-18.9422 -18.5666,-18.9422 -12.3146,0 -22.9452,10.1236 -22.9452,25.9719 V 118.073 H 1.28483e-5 V 6.42302e-6 H 17.1983 V 48.408 c 3.0669,-4.952 7.3366,-9.0481 12.412,-11.9074 5.0753,-2.8592 10.7915,-4.3887 16.6168,-4.4461 16.3563,0 29.6813,10.292 29.6813,29.4658 z"
inkscape:connector-curvature="0" />
<path
id="path6_fill"
d="m 17.1351,47.9239 c 0.6737,14.8381 10.6306,25.4669 25.4713,25.4669 13.6618,0 20.0823,-7.4296 24.966,-17.3848 l 13.325,7.9347 C 73.1508,79.9574 60.9835,88.3973 42.1012,88.3973 19.156,88.3973 2.56965e-6,70.36 2.56965e-6,44.1986 2.56965e-6,18.0372 19.2402,-1.41307e-5 43.0274,-1.41307e-5 67.3198,-1.41307e-5 83.5287,17.3638 83.5287,41.8203 v 6.0826 z m 0,-13.1543 h 49.932 C 65.7199,21.1101 54.2473,13.8489 42.6064,13.8489 c -12.5462,0 -22.2716,8.7766 -25.4713,20.9207 z"
inkscape:connector-curvature="0" />
<path
id="path7_fill"
d="m 44.6904,17.1954 c -2.1233,-0.6765 -4.3393,-1.0174 -6.5678,-1.0103 -12.1462,0 -20.9243,10.9655 -20.9243,25.8036 V 86.019 H 5.1393e-6 V 2.35726 H 17.1983 V 16.5219 C 21.7452,6.73501 29.8287,6.42302e-6 41.3223,6.42302e-6 43.4534,0.0279467 45.5735,0.310566 47.6375,0.841872 Z"
inkscape:connector-curvature="0" />
<path
id="path8_fill"
d="M 442.752,0.195422 394.487,23.0953 c -0.245,0.1158 -0.465,0.2788 -0.648,0.4798 -0.182,0.2011 -0.323,0.4361 -0.415,0.6917 -0.091,0.2555 -0.131,0.5267 -0.118,0.7978 0.014,0.2711 0.081,0.5368 0.197,0.7821 l 73.405,154.7373 c 27.275,57.564 19.97,101.23 -21.5,120.963 -33.56,15.927 -62.53,4.815 -85.133,-33.988 L 273.363,84.3358 C 238.119,10.0622 190.115,-9.62392 133.17,17.3911 96.1237,34.9663 74.6358,66.3811 75.0627,106.251 c 0.0083,0.471 -0.1449,0.931 -0.4342,1.303 -0.2892,0.372 -0.697,0.634 -1.1556,0.742 -0.4586,0.108 -0.9403,0.056 -1.3652,-0.148 -0.4248,-0.203 -0.7672,-0.546 -0.9702,-0.972 L 52.1637,67.1993 c -0.1156,-0.2455 -0.2787,-0.4657 -0.48,-0.6478 -0.2013,-0.1821 -0.4367,-0.3224 -0.6926,-0.4128 -0.2559,-0.0905 -0.5272,-0.1292 -0.7981,-0.1141 -0.271,0.0151 -0.5363,0.0839 -0.7805,0.2023 L 1.15964,89.0557 c -0.483848,0.2336 -0.856754,0.6476 -1.038583,1.1532 -0.1818296,0.5056 -0.1580702,1.0624 0.066172,1.5507 L 133.478,372.82 c 0.237,0.494 0.658,0.874 1.173,1.059 0.516,0.184 1.083,0.157 1.579,-0.074 l 48.264,-22.9 c 0.246,-0.116 0.466,-0.279 0.649,-0.48 0.182,-0.201 0.323,-0.436 0.414,-0.692 0.092,-0.255 0.132,-0.526 0.118,-0.798 -0.013,-0.271 -0.08,-0.536 -0.196,-0.782 L 114.125,197.744 C 85.0596,136.456 90.5739,92.139 135.139,70.9943 c 34.2,-16.2233 60.787,-5.3129 84.659,36.2537 0.032,0.048 0.06,0.1 0.083,0.154 l 86.058,181.444 c 33.204,69.969 84.777,93.995 139.244,68.154 42.098,-19.97 59.554,-50.033 58.534,-89.572 -0.011,-0.472 0.14,-0.933 0.429,-1.308 0.288,-0.374 0.696,-0.637 1.155,-0.747 0.46,-0.11 0.943,-0.059 1.369,0.145 0.426,0.204 0.769,0.547 0.973,0.974 l 19.163,40.404 c 0.116,0.245 0.279,0.465 0.48,0.648 0.201,0.182 0.436,0.323 0.692,0.415 0.255,0.091 0.526,0.131 0.797,0.118 0.271,-0.014 0.537,-0.081 0.782,-0.197 l 48.265,-22.9 c 0.246,-0.116 0.466,-0.279 0.648,-0.48 0.182,-0.201 0.322,-0.437 0.413,-0.693 0.09,-0.256 0.129,-0.527 0.114,-0.798 -0.015,-0.271 -0.084,-0.536 -0.203,-0.78 L 445.503,1.17973 c -0.236,-0.49368 -0.658,-0.8741 -1.173,-1.058445 -0.515,-0.1843464 -1.082,-0.1576979 -1.578,0.074137 z"
inkscape:connector-curvature="0" />
<clipPath
clipPathUnits="userSpaceOnUse"
id="clipPath4195">
<rect
style="fill:none;fill-opacity:1;stroke:#350000;stroke-width:1.51212192;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
id="rect4197"
width="868.08447"
height="711.8811"
x="3845.9578"
y="-3137.9404"
ry="36.954494" />
</clipPath>
<clipPath
style="clip-rule:evenodd"
id="clip-0">
<path
style="fill:#ffffff"
inkscape:connector-curvature="0"
id="path10"
d="m 3768,-3294 h 1024 v 1024 H 3768 Z" />
</clipPath>
</defs>
</svg>
Side by Side

Before

Width:  |  Height:  |  Size: 10 KiB

BIN
docs/source/.static/img/nucypher_overview.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 1.4 MiB

3446
docs/source/.static/img/nucypher_overview.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 732 KiB

1185
docs/source/.static/img/porter_diagram.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 151 KiB

2009
docs/source/.static/img/staking_initialization_process.svg
View File

File diff suppressed because it is too large Load Diff
Side by Side

Before

Width:  |  Height:  |  Size: 282 KiB

BIN
docs/source/.static/img/testnet_bond_dashboard.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 207 KiB

BIN
docs/source/.static/img/testnet_stake_dashboard.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 192 KiB

BIN
docs/source/.static/img/threshold_logo_purple.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 7.9 KiB

2144
docs/source/.static/img/ursula_reencrypt.svg
View File

File diff suppressed because one or more lines are too long
Side by Side

Before

Width:  |  Height:  |  Size: 369 KiB

13
docs/source/.static/style.css
View File

@ -1,13 +0,0 @@
.wy-side-nav-search {
background-color: #7038F1;
}
h2 {
font-size: 24px;
}
h3 {
font-size: 18px;
}
h4 {
font-size: 16px;
}

8
docs/source/apidoc/module.rst_t
View File

@ -1,8 +0,0 @@
{%- if show_headings %}
{{- basename | e | heading }}
{% endif -%}
.. automodule:: {{ qualname }}
{%- for option in automodule_options %}
:{{ option }}:
{%- endfor %}

53
docs/source/apidoc/package.rst_t
View File

@ -1,53 +0,0 @@
{%- macro automodule(modname, options) -%}
.. automodule:: {{ modname }}
{%- for option in options %}
:{{ option }}:
{%- endfor %}
{%- endmacro %}
{%- macro toctree(docnames) -%}
.. toctree::
:maxdepth: {{ maxdepth }}
{% for docname in docnames %}
{{ docname }}
{%- endfor %}
{%- endmacro %}
{%- if is_namespace %}
{{- pkgname | e | heading }}
{% else %}
{{- pkgname | e | heading }}
{% endif %}
{%- if modulefirst and not is_namespace %}
{{ automodule(pkgname, automodule_options) }}
{% endif %}
{%- if subpackages %}
Subpackages
-----------
{{ toctree(subpackages) }}
{% endif %}
{%- if submodules %}
Submodules
----------
{% if separatemodules %}
{{ toctree(submodules) }}
{%- else %}
{%- for submodule in submodules %}
{% if show_headings %}
{{- submodule | e | heading(2) }}
{% endif %}
{{ automodule(submodule, automodule_options) }}
{% endfor %}
{%- endif %}
{% endif %}
{%- if not modulefirst and not is_namespace %}
Module contents
---------------
{{ automodule(pkgname, automodule_options) }}
{% endif %}

7
docs/source/apidoc/toc.rst_t
View File

@ -1,7 +0,0 @@
{{ header | heading }}
.. toctree::
:maxdepth: {{ maxdepth }}
{% for docname in docnames %}
{{ docname }}
{%- endfor %}

355
docs/source/application_development/getting_started.rst
View File

@ -1,355 +0,0 @@
Getting Started with Characters
===============================
* `A Note about Side Channels`_
* `Alice: Grant Access to a Secret`_
* `Enrico: Encrypt a Secret`_
* `Bob: Decrypt a Secret`_
A Note about Side Channels
--------------------------
The PRE Application nodes do not store or handle an application's data; instead - it manages access *to* application data.
Management of encrypted secrets and public keys tends to be highly domain-specific - the surrounding architecture
will vary greatly depending on the throughput, sensitivity, and sharing cadence of application secrets.
In all cases, the PRE Application must be integrated with a storage and transport layer in order to function properly.
Along with the transport of ciphertexts, a nucypher application also needs to include channels for Alice and Bob
to discover each other's public keys, and provide policy encrypting information to Bob and Enrico.
The Application Side Channel
-----------------------------
* Secrets:
* Message Kits - Encrypted Messages, or "Ciphertexts"
* Identities:
* Alice Verifying Key - Public key used for verifying Alice
* Bob Encrypting Key - Public key used to encrypt for Bob
* Bob Verifying Key - Public key used to verify Bob
* Policies:
* Policy Encrypting Key - Public key used to encrypt messages for a Policy.
* Labels - A label for specifying a Policy's target, like a filepath
Choosing an Ethereum Provider
-----------------------------
Operation of a decentralized NuCypher character [\ ``Alice``\ , ``Bob``\ , ``Ursula``\ ] requires
a connection to an Ethereum node and wallet to interact with :doc:`smart contracts </architecture/contracts>`.
For general background information about choosing a node technology and node operation,
see https://web3py.readthedocs.io/en/stable/node.html.
Ursula: Untrusted Re-Encryption Proxies
----------------------------------------
When initializing an ``Alice``\ , ``Bob``\ , or ``Ursula``\ , an initial "Stranger-\ ``Ursula``\ " is needed to perform
the role of a ``Teacher``\ , or "seednode":
.. code-block:: python
from nucypher.characters.lawful import Ursula
seed_uri = "<SEEDNODE URI>:9151"
seed_uri2 = "<OTHER SEEDNODE URI>:9151"
ursula = Ursula.from_seed_and_stake_info(seed_uri=seed_uri)
another_ursula = Ursula.from_seed_and_stake_info(seed_uri=seed_uri2)
.. note::
While any PRE node can be used to seed your peers, NuCypher maintains
workers that can be used as seed nodes:
- mainnet: ``https://mainnet.nucypher.network:9151``
- lynx: ``https://lynx.nucypher.network:9151``
- tapir: ``https://tapir.nucypher.network:9151``
.. code::
seed_uri = 'https://lynx.nucypher.network:9151'
ursula = Ursula.from_seed_and_stake_info(seed_uri=seed_uri)
Stranger ``Ursula``\ s can be created by invoking the ``from_seed_and_stake_info`` method, then a ``list`` of ``known_nodes``
can be passed into any ``Character``\ 's init. The ``known_nodes`` will inform your character of all of the nodes
they know about network-wide, then kick-off the automated node-discovery loop:
.. code-block:: python
from nucypher.characters.lawful import Alice
alice = Alice(known_nodes=[ursula, another_ursula], ...)
For information on how to run a staking Ursula node via CLI,
see :doc:`Running a Node </pre_application/running_a_node>`.
Alice: Grant Access to a Secret
-------------------------------
Setup Alice Keys
^^^^^^^^^^^^^^^^
Alice uses an ethereum wallet to create publish access control policies to the ethereum blockchain,
and a set of related keys derived from a *"nucypher keystore"*.
First, instantiate a ``Signer`` to use for signing transactions. This is an API for Alice's ethereum
wallet, which can be an keystore file.
- Keystore directory or keyfile: ``'keystore://<ABSOLUTE PATH TO KEYSTORE>'``
Here are some examples of usage:
.. code-block:: python
from nucypher.blockchain.eth.signers import Signer
wallet = Signer.from_signer_uri('<YOUR SIGNER URI>')
software_wallet = Signer.from_signer_uri('keystore:///home/user/.ethereum/keystore/<KEY FILENAME>')
If you are using a software wallet, be sure to unlock it:
.. code-block:: python
# Unlocking a software wallet
>>> software_wallet.unlock_account(account='0x287A817426DD1AE78ea23e9918e2273b6733a43D', password=<ETH_PASSWORD>)
Next, create a NuCypher Keystore. This step will generate a new set of related private keys used for nucypher cryptography operations,
which can be integrated into your application's user on-boarding or setup logic. These keys will be stored on the disk,
encrypted-at-rest using the supplied password. Use the same account as the signer; Keystores are timestamped and named by public key,
so be sure to specify an account you control with a ``Signer``.
.. code-block:: python
from nucypher.crypto.keystore import Keystore
keystore = Keystore.generate(password=NEW_PASSWORD) # used to encrypt nucypher private keys
# Public Key
>>> keystore.id
e76f101f35846f18d80bfda5c61e9ec2
# The root directory containing the private keys
>>> keystore.keystore_dir
'/home/user/.local/share/nucypher/keystore'
After generating a keystore, any future usage can decrypt the keys from the disk:
.. code-block:: python
from nucypher.crypto.keystore import Keystore
# Restore an existing Alice keystore
path = '/home/user/.local/share/nucypher/keystore/1621399628-e76f101f35846f18d80bfda5c61e9ec2.priv'
keystore = Keystore(path)
# Unlock Alice's keystore
keystore.unlock(password=NUCYPHER_PASSWORD)
.. code-block:: python
from nucypher.characters.lawful import Alice, Ursula
# Instantiate a default peer (optional)
ursula = Ursula.from_seed_and_stake_info(seed_uri='https://tapir.nucypher.network:9151')
# Instantiate Alice
alice = Alice(
keystore=keystore, # NuCypher Keystore
known_nodes=[ursula], # Peers (Optional)
signer=signer, # Alice Wallet
eth_provider_uri=<RPC ENDPOINT>, # Ethereum RPC endpoint
domain='tapir' # PRE Application network (mainnet, lynx, tapir)
)
# Alice is identified by her ethereum address
alice.checksum_address
'0x287A817426DD1AE78ea23e9918e2273b6733a43D'
# Start node discovery
alice.start_learning_loop(now=True)
Alice needs to know Bob's public keys in order to grant him access. Alice's are expected to acquiring Bob's public
keys through the application side channel. Umbral public keys used in NuCypher's proxy re-encryption can be restored
from hex for API usage:
.. code-block:: python
from umbral.keys import UmbralPublicKey
verifying_key = UmbralPublicKey.from_hex(verifying_key_as_hex),
encrypting_key = UmbralPublicKey.from_hex(encryption_key_as_hex)
Grant
^^^^^
Alice can grant access to Bob using his public keys:
.. code-block:: python
from umbral.keys import UmbralPublicKey
from nucypher.characters.lawful import Bob
from datetime import timedelta
from web3 import Web3
import maya
# Deserialize bob's public keys from the application side-channel
verifying_key = UmbralPublicKey.from_hex(verifying_key_as_hex),
encrypting_key = UmbralPublicKey.from_hex(encryption_key_as_hex)
# Make a representation of Bob
bob = Bob.from_public_keys(verifying_key=bob_verifying_key, encrypting_key=bob_encrypting_key)
policy = alice.grant(
bob,
label=b'my-secret-stuff', # Send to Bob via side channel
threshold=2, # Threshold shares for access
shares=3, # Total nodes with shares
rate=Web3.toWei(50, 'gwei'), # 50 Gwei is the minimum rate (per node per period)
expiration= maya.now() + timedelta(days=5) # Five days from now
)
# The policy's public key
policy_encrypting_key = policy.public_key
Putting it all together, here's an example starter script for granting access using a
software wallet and an existing keystore:
.. code-block:: python
from nucypher.blockchain.eth.signers import Signer
from nucypher.crypto.keystore import Keystore
from nucypher.characters.lawful import Alice, Bob
from umbral.keys import UmbralPublicKey
from datetime import timedelta
from web3 import Web3
import maya
# Restore Existing NuCypher Keystore
keystore = Keystore(keystore_path=path)
keystore.unlock('YOUR KEYSTORE PASSWORD')
# Ethereum Software Wallet
wallet = Signer.from_signer_uri("keystore:///home/user/.ethereum/goerli/keystore/UTC--2021...0278ad02...')
wallet.unlock_account('0x287A817426DD1AE78ea23e9918e2273b6733a43D', 'SOFTWARE WALLET PASSWORD')
# Make Alice
alice = Alice(
domain='tapir', # testnet
eth_provider_uri='GOERLI RPC ENDPOINT',
keystore=keystore,
signer=wallet,
)
# From Public Key Side Channel
verifying_key = UmbralPublicKey.from_hex('0278ad02da8083aea357a8ed675dcc0b6e9c78557c506ea10b102b4b282c006b12')
encrypting_key = UmbralPublicKey.from_hex('03ec6b4e1f2b7d06ac544dde86730f9a4047e80a0a4d3c1566e88afe4bb449bdd9')
# Make Stranger-Bob
bob = Bob.from_public_keys(verifying_key=verifying_key, encrypting_key=encrypting_key)
# Grant Bob Access
policy = alice.grant(
bob,
label=b'my-secret-stuff', # Send to Bob via side channel
threshold=2, # Threshold shares for access
shares=3, # Total nodes with shares
rate=Web3.toWei(50, 'gwei'), # 50 Gwei is the minimum rate (per node per period)
expiration= maya.now() + timedelta(days=5) # Five days from now
)
Enrico: Encrypt a Secret
------------------------
First, a ``policy_encrypting_key`` must be retrieved from the application side channel, then
to encrypt a secret using Enrico:
Encrypt
^^^^^^^
.. code-block:: python
from nucypher.characters.lawful import Enrico
enrico = Enrico(policy_encrypting_key=policy_encrypting_key)
message_kit = enrico.encrypt_message(plaintext=b'Peace at dawn.')
The message kit can then be sent to Bob via the application side channel.
Note that Alice can get the public key even before creating the policy.
From this moment on, any Data Source (Enrico) that knows the public key
can encrypt data originally intended for Alice, but can be shared with
any Bob that Alice grants access.
``policy_pubkey = alice.get_policy_encrypting_key_from_label(label)``
Bob: Decrypt a Secret
---------------------
For Bob to retrieve a secret, the message kit, label, policy encrypting key, and Alice's verifying key must all
be fetched from the application side channel. Then, Bob constructs his perspective of the policy's network actors:
Setup Bob
^^^^^^^^^
Bob's setup is similar to Alice's above.
.. code-block:: python
from nucypher.characters.lawful import Alice, Bob, Enrico, Ursula
# Application Side-Channel
# --------------------------
# encrypted_treasure_map = <Side Channel>
# message_kit = <Side Channel>
# policy_encrypting_key = <Side Channel>
# alice_verifying_key = <Side Channel>
# Everyone!
ursula = Ursula.from_seed_and_stake_info(seed_uri='https://tapir.nucypher.network:9151')
alice = Alice.from_public_keys(verifying_key=alice_verifying_key)
enrico = Enrico(policy_encrypting_key=policy_encrypting_key)
# Restore Existing Bob keystore
keystore = Keystore(keystore_path=path)
# Unlock keystore and make Bob
keystore.unlock(PASSWORD)
bob = Bob(
keystore=keystore,
known_nodes=[ursula],
domain='tapir'
)
Retrieve and Decrypt
^^^^^^^^^^^^^^^^^^^^
Then Bob can retrieve and decrypt the message kit:
.. code-block:: python
cleartexts = bob.retrieve_and_decrypt(
message_kits=[message_kit],
alice_verifying_key=alice_public_key,
encrypted_treasure_map=policy.treasure_map,
)

763
docs/source/application_development/web_development.rst
View File

@ -1,763 +0,0 @@
.. _web-development:
===============
Web Development
===============
Web development / browser support for the PRE Application can be split into 3 projects:
#. :ref:`rust-umbral-library` - Rust implementation of Umbral, the underlying threshold PRE cryptography library.
#. `Porter`_ - the "Infura for NuCypher" - a web-based service for interacting with the network PRE Application protocol.
#. :ref:`nucypher-ts-library` - middleware javascript layer that ties the underlying cryptography ``rust-umbral`` layer to the use of Porter.
By leveraging rust-umbral and its associated javascript bindings for cryptography, and Porter for
communication with the network of PRE nodes, a lightweight, richer and full-featured web and mobile
experience is accessible to web application developers.
.. _rust-umbral-library:
Rust-Umbral
===========
`Rust-Umbral <https://github.com/nucypher/rust-umbral>`_ is the cryptography
layer for client-side applications. The underlying Umbral threshold PRE scheme has been re-written in Rust,
and provides bindings to other languages:
* Rust (primary)
* JavaScript (WASM-based)
* Python
Porter
======
Overview
--------
NuCypher Porter can be described as the *“Infura for NuCypher”*. Porter is a web-based service that performs
nucypher-based protocol operations on behalf of applications.
Its goal is to simplify and abstract the complexities surrounding the nucypher protocol to negate the need for
applications to interact with it via a python client. Porter introduces the nucypher protocol to cross-platform
functionality including web and mobile applications.
.. image:: ../.static/img/porter_diagram.svg
:target: ../.static/img/porter_diagram.svg
Running Porter
--------------
There are a variety of possible infrastructure setups for running the Porter service, and two scenarios for running
the Porter service are provided here:
#. Run the Porter service directly via docker, docker-compose, or the CLI (see `Run Porter Directly`_)
#. Run the Porter service with a reverse proxy via docker-compose (see `Run Porter with Reverse Proxy`_)
Run Porter Directly
*******************
.. note::
If running the Porter service using Docker or Docker Compose, it will run on port 80 (HTTP) or 443 (HTTPS). If
running via the CLI the default port is 9155, unless specified otherwise via the ``--http-port`` option.
Security
^^^^^^^^
* **HTTPS:** To run the Porter service over HTTPS, it will require a TLS key and a TLS certificate. These can be
specified via the `` --tls-key-filepath`` and ``--tls-certificate-filepath`` CLI options or via the ``TLS_DIR``
environment variable for docker-compose.
* **CORS:** Allowed origins for `Cross-Origin Resource Sharing (CORS) <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`_
is not enabled by default and can be enabled either via the ``--allow-origins`` option for the CLI,
or the ``PORTER_CORS_ALLOW_ORIGINS`` environment variable for docker-compose.
The value is expected to be a comma-delimited list of strings/regular expressions for origins to allow requests from. To allow all origins,
simply use "*".
.. note::
Origin values can be a string (for exact matches) or regular expressions (for more complex matches).
As part of CORS, the scheme (``https`` or ``http``) is also checked, so using only ``example.com`` is incorrect
to allow an origin from that specific domain. For exact matches, you can use ``https://example.com`` for HTTPS or
``http://example.com`` for HTTP. For non-default ports (i.e. not 443 or 80), the ports should be specified
e.g. ``https://example.com:8000`` or ``http://example.com:8001``.
For regular expressions, to allow all sub-domains of ``example.com``, you could use ``.*\.example\.com$`` which
incorporates wildcards for scheme and sub-domain. To allow multiple top-level domains you could use
``.*\.example\.(com|org)$`` which allows any origins from both ``example.com`` and ``example.org`` domains.
* **Authentication:** Porter will allow the configuration of Basic Authentication out of the box via
an `htpasswd <https://httpd.apache.org/docs/2.4/programs/htpasswd.html>`_ file. This file can be provided via the
``--basic-auth-filepath`` CLI option or ``HTPASSWD_FILE`` environment variable for docker-compose. The use
of Basic Authentication necessitates HTTPS since user credentials will be passed over the network as cleartext.
via Docker
^^^^^^^^^^
Run Porter within Docker without acquiring or installing the ``nucypher`` codebase.
#. Get the latest ``nucypher`` image:
.. code:: bash
$ docker pull nucypher/porter:latest
#. Run Porter service
For HTTP service (on default port 80):
.. code:: bash
$ docker run -d --rm \
--name porter-http \
-v ~/.local/share/nucypher/:/root/.local/share/nucypher \
-p 80:9155 \
nucypher/porter:latest \
nucypher porter run \
--eth-provider <YOUR WEB3 PROVIDER URI> \
--network <NETWORK NAME>
For HTTPS service (on default port 443):
* Without Basic Authentication:
.. code:: bash
$ docker run -d --rm \
--name porter-https \
-v ~/.local/share/nucypher/:/root/.local/share/nucypher \
-v <TLS DIRECTORY>:/etc/porter/tls \
-p 443:9155 \
nucypher/porter:latest \
nucypher porter run \
--eth-provider <YOUR WEB3 PROVIDER URI> \
--network <NETWORK NAME> \
--tls-key-filepath /etc/porter/tls/<KEY FILENAME> \
--tls-certificate-filepath /etc/porter/tls/<CERT FILENAME>
* Without Basic Authentication, but with CORS enabled to allow all origins:
.. code:: bash
$ docker run -d --rm \
--name porter-https-cors \
-v ~/.local/share/nucypher/:/root/.local/share/nucypher \
-v <TLS DIRECTORY>:/etc/porter/tls \
-p 443:9155 \
nucypher/porter:latest \
nucypher porter run \
--eth-provider <YOUR WEB3 PROVIDER URI> \
--network <NETWORK NAME> \
--tls-key-filepath /etc/porter/tls/<KEY FILENAME> \
--tls-certificate-filepath /etc/porter/tls/<CERT FILENAME> \
--allow-origins "*"
* With Basic Authentication:
.. code:: bash
$ docker run -d --rm \
--name porter-https-auth \
-v ~/.local/share/nucypher/:/root/.local/share/nucypher \
-v <TLS DIRECTORY>:/etc/porter/tls \
-v <HTPASSWD FILE>:/etc/porter/auth/htpasswd \
-p 443:9155 \
nucypher/porter:latest \
nucypher porter run \
--eth-provider <YOUR WEB3 PROVIDER URI> \
--network <NETWORK NAME> \
--tls-key-filepath /etc/porter/tls/<KEY FILENAME> \
--tls-certificate-filepath /etc/porter/tls/<CERT FILENAME> \
--basic-auth-filepath /etc/porter/auth/htpasswd
The ``<TLS DIRECTORY>`` is expected to contain the TLS key file (``<KEY FILENAME>``) and the
certificate (``<CERT FILENAME>``) to run Porter over HTTPS.
.. note::
The commands above are for illustrative purposes and can be modified as necessary.
#. Porter will be available on default ports 80 (HTTP) or 443 (HTTPS). The porter service running will be one of
the following depending on the mode chosen:
* ``porter-http``
* ``porter-https``
* ``porter-https-cors``
* ``porter-https-auth``
#. View Porter logs
.. code:: bash
$ docker logs -f <PORTER SERVICE>
#. Stop Porter service
.. code:: bash
$ docker stop <PORTER SERVICE>
via Docker Compose
^^^^^^^^^^^^^^^^^^
Docker Compose will start the Porter service within a Docker container.
#. :ref:`acquire_codebase`. There is no need
to install ``nucypher`` after acquiring the codebase since Docker will be used.
#. Set the required environment variables:
* Web3 Provider URI environment variable
.. code:: bash
$ export WEB3_PROVIDER_URI=<YOUR WEB3 PROVIDER URI>
.. note::
Local ipc is not supported when running via Docker.
* Network Name environment variable
.. code:: bash
$ export NUCYPHER_NETWORK=<NETWORK NAME>
* *(Optional)* TLS directory containing the TLS key and certificate to run Porter over HTTPS.
The directory is expected to contain two files:
* ``key.pem`` - the TLS key
* ``cert.pem`` - the TLS certificate
Set the TLS directory environment variable
.. code:: bash
$ export TLS_DIR=<ABSOLUTE PATH TO TLS DIRECTORY>
* *(Optional)* Enable CORS. For example, to only allow access from your sub-domains for ``example.com``:
.. code:: bash
$ export PORTER_CORS_ALLOW_ORIGINS=".*\.example\.com$"
* *(Optional)* Filepath to the htpasswd file for Basic Authentication
Set the htpasswd filepath environment variable
.. code:: bash
$ export HTPASSWD_FILE=<ABSOLUTE PATH TO HTPASSWD FILE>
#. Run Porter service
For HTTP service (on default port 80):
.. code:: bash
$ docker-compose -f deploy/docker/porter/docker-compose.yml up -d porter-http
For HTTPS service (on default port 443):
* Without Basic Authentication
.. code:: bash
$ docker-compose -f deploy/docker/porter/docker-compose.yml up -d porter-https
* With Basic Authentication
.. code:: bash
$ docker-compose -f deploy/docker/porter/docker-compose.yml up -d porter-https-auth
Porter will be available on default ports 80 (HTTP) or 443 (HTTPS). The porter service running will be one of
the following depending on the mode chosen:
* ``porter-http``
* ``porter-https``
* ``porter-https-auth``
#. View Porter logs
.. code:: bash
$ docker-compose -f deploy/docker/porter/docker-compose.yml logs -f <PORTER SERVICE>
#. Stop Porter service
.. code:: bash
$ docker-compose -f deploy/docker/porter/docker-compose.yml down
via CLI
^^^^^^^
Install ``nucypher`` - see :doc:`/references/installation`.
For a full list of CLI options, run:
.. code:: console
$ nucypher porter run --help
* Run Porter service
* Run via HTTP
.. code:: console
$ nucypher porter run --eth-provider <YOUR WEB3 PROVIDER URI> --network <NETWORK NAME>
______
(_____ \ _
_____) )__ ____| |_ ____ ____
| ____/ _ \ / ___) _)/ _ )/ ___)
| | | |_| | | | |_( (/ /| |
|_| \___/|_| \___)____)_|
the Pipe for PRE Application network operations
Network: <NETWORK NAME>
Provider: ...
Running Porter Web Controller at http://127.0.0.1:9155
* Run via HTTPS
To run via HTTPS use the ``--tls-key-filepath`` and ``--tls-certificate-filepath`` options:
.. code:: console
$ nucypher porter run --eth-provider <YOUR WEB3 PROVIDER URI> --network <NETWORK NAME> --tls-key-filepath <TLS KEY FILEPATH> --tls-certificate-filepath <CERT FILEPATH>
______
(_____ \ _
_____) )__ ____| |_ ____ ____
| ____/ _ \ / ___) _)/ _ )/ ___)
| | | |_| | | | |_( (/ /| |
|_| \___/|_| \___)____)_|
the Pipe for PRE Application network operations
Network: <NETWORK NAME>
Provider: ...
Running Porter Web Controller at https://127.0.0.1:9155
To enable CORS, use the ``--allow-origins`` option:
.. code:: console
$ nucypher porter run --eth-provider <YOUR WEB3 PROVIDER URI> --network <NETWORK NAME> --tls-key-filepath <TLS KEY FILEPATH> --tls-certificate-filepath <CERT FILEPATH> --allow-origins ".*\.example\.com$"
______
(_____ \ _
_____) )__ ____| |_ ____ ____
| ____/ _ \ / ___) _)/ _ )/ ___)
| | | |_| | | | |_( (/ /| |
|_| \___/|_| \___)____)_|
the Pipe for PRE Application network operations
Network: <NETWORK NAME>
Provider: ...
CORS Allow Origins: ['.*\\.example\\.com$']
Running Porter Web Controller at https://127.0.0.1:9155
To enable Basic Authentication, add the ``--basic-auth-filepath`` option:
.. code:: console
$ nucypher porter run --eth-provider <YOUR WEB3 PROVIDER URI> --network <NETWORK NAME> --tls-key-filepath <TLS KEY FILEPATH> --tls-certificate-filepath <CERT FILEPATH> --allow-origins ".*\.example\.com$" --basic-auth-filepath <HTPASSWD FILE>
______
(_____ \ _
_____) )__ ____| |_ ____ ____
| ____/ _ \ / ___) _)/ _ )/ ___)
| | | |_| | | | |_( (/ /| |
|_| \___/|_| \___)____)_|
the Pipe for PRE Application network operations
Network: <NETWORK NAME>
Provider: ...
CORS Allow Origins: ['.*\\.example\\.com$']
Basic Authentication enabled
Running Porter Web Controller at https://127.0.0.1:9155
Run Porter with Reverse Proxy
*****************************
This type of Porter execution illustrates the use of a reverse proxy that is a go between or intermediate server that
handles requests from clients to an internal Porter service. An NGINX reverse proxy instance is
used in this case. It will handle functionality such as TLS, CORS, and authentication so that the Porter service
itself does not have to, and allows for more complex configurations than provided by Porter itself. More information
about the NGINX reverse proxy docker image used and additional configuration options
is available `here <https://hub.docker.com/r/nginxproxy/nginx-proxy>`_.
via Docker Compose
^^^^^^^^^^^^^^^^^^
Docker Compose will be used to start the NGINX reverse proxy and the Porter service containers.
#. :ref:`acquire_codebase`. There is no need
to install ``nucypher`` after acquiring the codebase since Docker will be used.
#. Set the required environment variables:
* Web3 Provider URI environment variable
.. code:: bash
$ export WEB3_PROVIDER_URI=<YOUR WEB3 PROVIDER URI>
.. note::
Local ipc is not supported when running via Docker.
* Network Name environment variable
.. code:: bash
$ export NUCYPHER_NETWORK=<NETWORK NAME>
* The reverse proxy is set up to run over HTTPS by default, and therefore requires a TLS directory containing
the TLS key and certificate for the reverse proxy. The directory is expected to contain two files:
* ``porter.local.key`` - the TLS key
* ``porter.local.crt`` - the TLS certificate
Set the TLS directory environment variable
.. code:: bash
$ export TLS_DIR=<ABSOLUTE PATH TO TLS DIRECTORY>
* *(Optional)* The CORS configuration is set in the ``nucypher/deploy/docker/porter/nginx/porter.local_location`` file.
.. important::
By default, CORS for the reverse proxy is configured to allow all origins
If you would like to modify the CORS allowed origin setting to be more specific, you can modify the file to
check for specific domains. There are some examples in the file - see `NGINX if-directive <https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#if>`_
for adding ore complex conditional checks.
For example, to only allow requests from all sub-domains of ``example.com``, the file should be edited to include:
.. code::
if ($http_origin ~* (.*\.example\.com$)) {
set $allow_origin "true";
}
.. note::
If you modify the file you should rebuild the docker images using docker-compose.
#. *(Optional)* Build the docker images:
.. code:: bash
$ docker-compose -f deploy/docker/porter/nginx/docker-compose.yml build
#. Run the NGINX reverse proxy and Porter service
.. code:: bash
$ docker-compose -f deploy/docker/porter/nginx/docker-compose.yml up -d
#. The NGINX reverse proxy will be publicly accessible via the default HTTPS port 443, and will route requests to the
internal Porter service.
#. View Porter service logs
.. code:: bash
$ docker-compose -f deploy/docker/porter/nginx/docker-compose.yml logs -f nginx-porter
#. Stop Porter service and NGINX reverse proxy
.. code:: bash
$ docker-compose -f deploy/docker/porter/nginx/docker-compose.yml down
API
---
Status Codes
************
All documented API endpoints use JSON and are REST-like.
Some common returned status codes you may encounter are:
- ``200 OK`` -- The request has succeeded.
- ``400 BAD REQUEST`` -- The server cannot or will not process the request due to something that is perceived to
be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
- ``401 UNAUTHORIZED`` -- Authentication is required and the request has failed to provide valid authentication credentials.
- ``404 NOT FOUND`` -- Request could not be completed because requested resources could not be found.
- ``500 INTERNAL SERVER ERROR`` -- The server encountered an unexpected condition that prevented it from
fulfilling the request.
Typically, you will want to ensure that any given response results in a 200 status code.
This indicates that the server successfully completed the call.
If a 400 status code is returned, double-check the request data being sent to the server. The text provided in the
error response should describe the nature of the problem.
If a 401 status code is returned, ensure that valid authentication credentials are being used in the request e.g. if
Basic authentication is enabled.
If a 500 status code, note the reason provided. If the error is ambiguous or unexpected, we'd like to
know about it! The text provided in the error response should describe the nature of the problem.
For any bugs/un expected errors, see our :ref:`Contribution Guide <contribution-guide>` for issue reporting and
getting involved. Please include contextual information about the sequence of steps that caused the 500 error in the
GitHub issue. For any questions, message us in our `Discord <https://discord.gg/7rmXa3S>`_.
URL Query Parameters
********************
All parameters can be passed as either JSON data within the request or as query parameter strings in the URL.
Query parameters used within the URL will need to be URL encoded e.g. ``/`` in a base64 string becomes ``%2F`` etc.
For ``List`` data types to be passed via a URL query parameter, the value should be provided as a comma-delimited
String. For example, if a parameter is of type ``List[String]`` either a JSON list of strings can be provided e.g.
.. code:: bash
curl -X GET <PORTER URI>/<ENDPOINT> \
-H "Content-Type: application/json" \
-d '{"parameter_with_list_of_values": ["value1", "value2", "value3"]}'
OR it can be provided via a URL query parameter
.. code:: bash
curl -X GET <PORTER URI>/<ENDPOINT>?parameter_with_list_of_values=value1,value2,value3
More examples shown below.
.. important::
If URL query parameters are used and the URL becomes too long, the request will fail. There is no official limit
and it is dependent on the tool being used.
GET /get_ursulas
****************
Sample available Ursulas for a policy as part of Alice's ``grant`` workflow. Returns a list of Ursulas
and their associated information that is used for the policy.
Parameters
^^^^^^^^^^
+----------------------------------+---------------+-----------------------------------------------+
| **Parameter** | **Type** | **Description** |
+==================================+===============+===============================================+
| ``quantity`` | Integer | Number of total Ursulas to return. |
+----------------------------------+---------------+-----------------------------------------------+
| ``include_ursulas`` *(Optional)* | List[String] | | List of Ursula checksum addresses to |
| | | | give preference to. If any of these Ursulas |
| | | | are unavailable, they will not be included |
| | | | in result. |
+----------------------------------+---------------+-----------------------------------------------+
| ``exclude_ursulas`` *(Optional)* | List[String] | | List of Ursula checksum addresses to not |
| | | | include in the result. |
+----------------------------------+---------------+-----------------------------------------------+
Returns
^^^^^^^
List of Ursulas with associated information:
* ``encrypting_key`` - Ursula's encrypting key encoded as hex
* ``checksum_address`` - Ursula's checksum address
* ``uri`` - Ursula's URI
Example Request
^^^^^^^^^^^^^^^
.. code:: bash
curl -X GET <PORTER URI>/get_ursulas \
-H "Content-Type: application/json" \
-d '{"quantity": 5,
"include_ursulas": ["0xB04FcDF9327f65AB0107Ea95b78BB200C07FA752"],
"exclude_ursulas": ["0x5cF1703A1c99A4b42Eb056535840e93118177232", "0x9919C9f5CbBAA42CB3bEA153E14E16F85fEA5b5D"]}'
OR
.. code:: bash
curl -X GET "<PORTER URI>/get_ursulas?quantity=5&include_ursulas=0xB04FcDF9327f65AB0107Ea95b78BB200C07FA752&exclude_ursulas=0x5cF1703A1c99A4b42Eb056535840e93118177232,0x9919C9f5CbBAA42CB3bEA153E14E16F85fEA5b5D"
Example Response
^^^^^^^^^^^^^^^^
.. code::
Status: 200 OK
.. code:: json
{
"result": {
"ursulas": [
{
"encrypting_key": "025a335eca37edce8191d43c156e7bc6b451b21e5258759966bbfe0e6ce44543cb",
"checksum_address": "0x5cF1703A1c99A4b42Eb056535840e93118177232",
"uri": "https://3.236.144.36:9151"
},
{
"encrypting_key": "02b0a0099ee180b531b4937bd7446972296447b2479ca6259cb6357ed98b90da3a",
"checksum_address": "0x7fff551249D223f723557a96a0e1a469C79cC934",
"uri": "https://54.218.83.166:9151"
},
{
"encrypting_key": "02761c765e2f101df39a5f680f3943d0d993ef9576de8a3e0e5fbc040d6f8c15a5",
"checksum_address": "0x9C7C824239D3159327024459Ad69bB215859Bd25",
"uri": "https://92.53.84.156:9151"
},
{
"encrypting_key": "0258b7c79fe73f3499de91dd5a5341387184035d0555b10e6ac762d211a39684c0",
"checksum_address": "0x9919C9f5CbBAA42CB3bEA153E14E16F85fEA5b5D",
"uri": "https://3.36.66.164:9151"
},
{
"encrypting_key": "02e43a623c24db4f62565f82b6081044c1968277edfdca494a81c8fd0826e0adf6",
"checksum_address": "0xfBeb3368735B3F0A65d1F1E02bf1d188bb5F5BE6",
"uri": "https://128.199.124.254:9151"
}
]
},
"version": "6.1.0"
}
POST /retrieve_cfrags
*********************
Get data re-encrypted by the network as part of Bob's ``retrieve`` workflow.
Parameters
^^^^^^^^^^
+-------------------------------------------+---------------+----------------------------------------+
| **Parameter** | **Type** | **Description** |
+===========================================+===============+========================================+
| ``treasure_map`` | String | | Unencrypted treasure map bytes |
| | | | encoded as base64. |
+-------------------------------------------+---------------+----------------------------------------+
| ``retrieval_kits`` | List[String] | | List of retrieval kit bytes encoded |
| | | | as base64. |
+-------------------------------------------+---------------+----------------------------------------+
| ``alice_verifying_key`` | String | Alice's verifying key encoded as hex. |
+-------------------------------------------+---------------+----------------------------------------+
| ``bob_encrypting_key`` | String | Bob's encrypting key encoded as hex. |
+-------------------------------------------+---------------+----------------------------------------+
| ``bob_verifying_key`` | String | Bob's verifying key encoded as hex. |
+-------------------------------------------+---------------+----------------------------------------+
| ``context`` *(Optional)* | String | | Associated JSON dictionary required |
| | | | during re-encryption e.g. data to |
| | | | satisfy re-encryption conditions. |
+-------------------------------------------+---------------+----------------------------------------+
* A single *retrieval kit* is an encapsulation of the information necessary to obtain cfrags from Ursulas.
It contains a capsule and the checksum addresses of the Ursulas from which the requester has
already received cfrags, i.e. the Ursulas in the treasure map to skip.
The format of a *retrieval kit* is:
* .. code::
base64(<capsule bytes>)
if no cfrags were obtained from Ursulas in previous ``/retrieve_cfrags`` calls
OR
* .. code::
base64(<capsule bytes><bytes of ursula_1 checksum address><bytes of ursula_2 checksum address>...)
if some cfrags were already obtained from a subset of Ursulas for a *retrieval kit* in a
previous ``/retrieve_cfrags`` call; for example, retrying after receiving less than a threshold of cfrags
because some Ursulas may have experienced a blip in connectivity. This is an optional optimization that provides
retry functionality that skips previously successful reencryption operations.
* A *context* is an associated JSON dictionary of data required during re-encryption. One such example is when a condition for re-encryption
requires proof of ownership of a wallet address; the *context* is used to provide the data and signature required for the proof.
Returns
^^^^^^^
The result of the re-encryption operations performed:
* ``retrieval_results`` - The list of results from the re-encryption operations performed; contains a mapping of
Ursula checksum address/cfrag pairs. The cfrags are base64 encoded. The list of results corresponds to the order
of the ``retrieval_kits`` list provided. If there were issues obtaining cfrags for a particular
*retrieval kit*, the corresponding list of cfrags could be empty or less than the expected threshold.
Example Request
^^^^^^^^^^^^^^^
.. code:: bash
curl -X POST <PORTER URI>/retrieve_cfrags \
-H "Content-Type: application/json" \
-d '{"treasure_map": "ivOS2/MarBpkLAksM0O+pgLUHAV/0ceIBarBKwqUpAXARhpvuwAAAm0DoDAtioScWJSHWNGzQd9pMGW2dRF4IvJX/ExALF6AcLICLCBP+tte8QR4l0GLNy3YwK4oO8f8Ht0Ij+v0feWWwgeo3R7FVeC4ExDuYvgdsV6jCP3vqZnLphIPk8LQeo1XVAABAtM4mGTp5yBq4dGDAbvWetjgvfJXswhcmqE+lDj/kTPyAAAB5H0rD40N1u5Ct455sh4SicbHTGsXcRSt/adeHVl3zylNpWDsFbeon7VI5fGGmWLAKmCJ5ARU1Mgfwg0pfsXDgHTky6XOeXnNw630z9muBE4NMUiESOQm/RAsphMR/DEIMRaCgjhaE2diVdVAm15JjRXV9JN5gAp58Y1ecPcWR2lMcgAMHBFMX60bpbgjySha94Hwb0kR2SKIFkPQnuMljoQxutTDAyh55eE2sHf9ZOAVZkpKQu8NkaWy7adx/1QefezNbngX9c2yYml133Al4oGrLWYA3fnbod2Y6F1oeG5As5ZIW/O8k7Rf+3i9a+DS1i+KbgETHQGxOkQSpNPUmwJjtzDJQ1xFMmKkxgwUtXenfyrzDDPU6EQloWK2PmyTD/hSKHLpkLyzYp95gadzDiS8RlOnNw/uP8vfMPSrXYGZSKXvHvlrQxKOjnF7FrheauwwRPjM0yYTftPs3jNkZwCTl+Ewn6NdLur927SeGyAB3gHCjHenje+3hU1jsn/mwfwLJwSMT7V0rbXV6I0NYhjQy2Ajj+7ev/NSvRdeneeYTU3iHoO6nIhWHBLVExWafu59B6hhsm261kvXw718eiUcL+1X1eZ5WApplCuXGQV7L6DZxlQPanRJy7BZZQmFwEUoMCnx9mGbOKmNbeCADx3vwKY5nrbTDAAAAm0Cccv5a3jS2QiICCzCyA0Ot3U7VT1F3d+B3cHcmv8DaCwDODb8IadnsiVK+dfbPLn3ne+lm8d9yqhh6bLi6KNDb6yiWrjWnd4Irnnh3amMwik00vdyQKYvdsaSEJqtVLmtcQABAtM4mGTp5yBq4dGDAbvWetjgvfJXswhcmqE+lDj/kTPyAAAB5Do/eww+G709VPQwkxd0tRFyJh97Wcb5uSGs+4fK9O+5CTf5rDQSO3ueWLRF4ytRzd3QjK6+8FlXsJQM5n5pGLUNNWpUlimk2MmPaLehC9uGBfQzoTfQof+U8CBXkTTnRi0IeAYMq8eiuEnNR/oOJjpjuwgZH4gue/sSDF8FyhFU4SwF/WdjLg0FgmZzRlqABNXeE8vOofydEMYgUMPd8qxjimAGhkYlBUNjlme4BUdA2AqndMttpc3y9ILTobaGSnjgWfq9Ztw/n72scPI11T+YMaaXd33dacNPx+pVzcgqi358PT8WQ6U3n+1be8mhF8VGEO7/5zLFHECRCv06erER8ChTZvr4rb8Y0xRCz/patllLqvWZkGSmotmsi9qAptgG/XkozOZIqmBuM2AuQTwaePyuJzelc5xD51OlkQRahV6+ok3CokckwtOXtC6dzq4dmh03Uj5ZeKj8IgITDPN6jCf5TwLmXSuEGl5W/xmrEUeNlrthlJm7Cdd1NpLn3RZNCgSS4+Pw9cpY6fj/mF8yR0erf9Tkrxr7FXzSe/UWkfeB3aQPulP4U3nM7vJIz9DBcJxtdozfqHchZ/K+VnaW/7IlNhvu3Cwk+N3D9sUwf/uHQuE/QSsYZ0fjUCnB1UgJMjho5Sd4CHLNoCFroNj71YtnpdXjUQAAAm0D5ITdM1U28+6/LU++Jw/UTMOefScVULkEyaojkyJK574Dc96zie3HtMN0ahALfOg5yn2z2zZpwqsLk9mpT23GD8AYR55RcvLHGIjJTubtuMINy7ZBgbZmisPDt5DvHVKj1wABAtM4mGTp5yBq4dGDAbvWetjgvfJXswhcmqE+lDj/kTPyAAAB5B9Wn5rfJ8LS81DIkZj6By39KZPYLoNSpR+VEZsLaSEo/HTMG43Q/gG/YjZMQHBEZwleE1H35P3EuDlWOriEQxveH7ihmHVSDfj8R+6xo/263QCLqtg9djSFPW7h6QRx5JBM+WABcmIZQrAvMDe1q7F8VOGRDMf8tW/7sySMFn9pQ7735kasw8iNsGPX9gVNcncSuh8hmgWGzwciUU/Y5SYmQvl0Oc15G5/kFhIA9nDVfZR4sMBRB9ApYbnNYsxtH12wWhTo04hPEGfzsqKK10muLy+qpo3VBhX24HPTBAvYm68f0UVD+a0cZWmgYKypmMqApJ87RnPvXbE3rmKepJM8u02O4X1OBlfDZBrTsbCbMxeniS6bzE6VPE62jOW6GIuyV6+NQS3PZTuTWG/p7T5n2EC/Pf/CvGLq41gQDU9VT2aCbHkbr9C0klVJfUwqdE/51zLmcY8wpx3P+OS+lrIjxQzOpWSKQfsNyt1DhKpKb5Y1wWrUGm6s0sBEG7FQK2SmWMhpjB36ZRdmtQ8/mvh20KELR6W+ocGosR20TXdGINzJEnobbTkkGNz2sqzePvL7Ql5Utc/GCaZYC2yIvJEGBOSBVtKvwqTOaMOFTaCIx4R5f3X17umkMD1YCvir39cREkU=",
"retrieval_kits": ["gANDYgMKitDPd/QttLGy+s7Oacnm8pfbl3Qs2UD3IS1d9wF3awJsXnjFq7OkRQE45DV4+Ma2lDSJ5SeKEBqJK5GdPMB6CRwJ1hX7Y5SYgzpZtr/Z5/S3DHgVKn+8fWX92FaqEXIGcQBjYnVpbHRpbnMKc2V0CnEBXXEChXEDUnEEhnEFLg=="],
"alice_verifying_key": "02d3389864e9e7206ae1d18301bbd67ad8e0bdf257b3085c9aa13e9438ff9133f2",
"bob_encrypting_key": "03d41cb7aa2df98cb9fb1591b5556363862a367faae6d0e4874a860321141788cb",
"bob_verifying_key": "039c19e5d44b016af126d89488c4ae5599e0fde9ea30047754d1fe173d05eee468",
"policy_encrypting_key": "02cdb2cec70b568c0624b72450c2043836aa831b06b196a50db461e87acddb791e"}'
Example Response
^^^^^^^^^^^^^^^^
.. code::
Status: 200 OK
.. code:: json
{
"result": {
"retrieval_results": [
{
"cfrags": {
"0xd41c057fd1c78805AAC12B0A94a405c0461A6FBb": "Alvyx0r4IXvOWppw8jzbdx/8lIhL36ZAhbvNcTfo4KC6AqUxu6iP9gOVSaiehZAAQ89ho9MIGyDYdJIjg/dRkR1DuNX9qLnhAsg+qJvGcPpEXHNG0L2WHxe+AUNqtOSnwiEDegcnRTgUFyR4gfs6/M49/t8iXuXJcT6Szcwtx2JlZtACpa4KPLa5hFgI67rkiZQTqzn/aLPEzdD1zhhUyaHpJXoDfXLdpQmyEl8aI7ZOsBLh6PtPlx86/cvU0NOsR8wIoYUDe7BiAijbjo4VtcYrfvzu9CWRiWb0TQQJO6v47am/RPUD6NTr5+S/m+EvGK22L7XWtMHw7X2M380i4z2X1jxeYZaLmtuJJLAQL61kEIFv/1afCVDe+odbZ0Wivq3EiQzd0UcYRcvhIyGJdBksGv4GjfXSNNl6OCn1ny1Cn056juxGQs3yxzQZvfEN0UAOsI5IcTvOh3/kBNGfJGH+Qfv/CKc=",
"0x68E527780872cda0216Ba0d8fBD58b67a5D5e351": "AvGBNjTE1WrgQLkDP0ViipGoSjlaq0Plge6szUOasYsnAnB7Q0OKN52h3kyEax8bTFA8uqQ1mg8/X+ccRnda7bjyQu3Oep16gNGkNItWo0Eb7XC8ZDnAJMe6VrQMeq4l6EQDegcnRTgUFyR4gfs6/M49/t8iXuXJcT6Szcwtx2JlZtADcS7sUWM293AkLyacmHcj/ohsWrhSTqyyV8oCzVeCR9ICLqSTeEjoYyBhRseKvU+OObMv+Vi9kW68SEbHJFZhpHgC1UsJjSTGH1hpBxYUpQcaFU4O+nafk1NIQcEfDY9xKLYD2FAkkVF0OcSaeSNCcgWmBnDYY1n9lnQbF4gvumFoO91+19DjGTa/lY0e/GWI0HrZ3D7Qe8uMUD5LZIth9RHdVgT8WFrVd7Wg47/ieMPbW/zNJ0jKgnlmgcUH4v+VSvvqWCL3cqm83psyABURpMntldLubCBgTrK8vCHP/C0Aduo="
}
}
]
},
"version": "6.1.0"
}
.. _nucypher-ts-library:
nucypher-ts
===========
`nucypher-ts <https://github.com/nucypher/nucypher-ts>`_ is a typescript middleware layer implementation of the ``nucypher`` python library. It abstracts
the cryptography layer and PRE network protocol to provide PRE functionality in web applications.

122
docs/source/architecture/character.rst
View File

@ -1,122 +0,0 @@
.. _character-concepts:
Character Concepts
==================
NuCypher's API is written as characters within a cryptological narrative/archetype, each fulfilling a particular
role.
* **Alice**: *"The Data Owner"* - retains full control over the data encrypted for her and determines whom to share the data with
* **Enrico**: *"The Encryptor"* - a data source that encrypts data on behalf of Alice
* **Bob**: *"The Data Recipient"* - the data recipient that Alice intends to share data with
* **Ursula**: *"The Proxy in PRE"* - the PRE node on the Threshold Network that stands ready to re-encrypt data in exchange for payment in fees and token rewards; they enforce the access policy created by Alice
.. _Umbral: https://github.com/nucypher/umbral-doc/blob/master/umbral-doc.pdf
.. raw:: html
<div>
<div style="position:relative;padding-top:56.25%;">
<iframe style="position:absolute;top:0;left:0;width:100%;height:100%;" src="https://www.youtube-nocookie.com/embed/SXn1zShgVI8?rel=0&controls=1&modestbranding=1" frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</div>
</div>
<br/>
Character Actions
-----------------
Alice::Grant
^^^^^^^^^^^^
.. image:: ../.static/img/alice_grant.svg
:target: ../.static/img/alice_grant.svg
Alice has data that she wants to share and she wants to classify/categorize
her data according to how she intends to share it. These subsets of data would have their own set of permissions - within NuCypher
this concept is called a `label`. Alice uses this `label` to categorize data and she creates an asymmetric encryption key
for Enrico characters based on the `label`. For example, Alice may use different `labels` and different Enricos for
health data, personal data, and work-related data. Essentially, `labels` are a way to categorize data for sharing - you
can think of file system folders as being somewhat analogous to `labels`. Alice can delegate access permissions to
the encrypted data classified under a `label` to any recipient she sees fit.
The same encryption key can be used by Enrico even though multiple policies for the data can be created
for different Bobs. Enrico, therefore, only has to encrypt data using the provided encryption key
and data can later be re-encrypted for all Bobs who have been granted access.
When Alice wants to share this information with Bob, she can create a
policy in the PRE Application running on the Threshold Network to grant access to him. To grant access to Bob, Alice must:
#. Create a re-encryption key based on the asymmetric private key and Bob's public key
#. Determine `n` Ursulas from the Threshold Network to use in the policy
#. Configure the conditions of the policy, e.g. *expiration time, m-of-n threshold values*
#. Deploy the policy to the blockchain and escrow associated policy fees
#. Create a `treasure map`, encrypted for Bob that contains the list of `n` Ursulas in the policy,
and the `n` re-encryption key fragments (`kFrags`), each encrypted for a different Ursula in
the policy.
.. note::
Bob can decrypt the encrypted treasure map, but since each re-encryption fragment is encrypted
for a specific Ursula, Bob never has access to any re-encryption fragment in plaintext form.
Enrico::Encrypt
^^^^^^^^^^^^^^^
.. image:: ../.static/img/enrico_encrypt.svg
:target: ../.static/img/enrico_encrypt.svg
The Ursulas uses the Umbral_ threshold proxy re-encryption scheme which employs a key encapsulation mechanism (KEM)/data
encapsulation mechanism (DEM). In this approach, an ephemeral symmetric key is used to encrypt the data, and the
symmetric key is encrypted using an asymmetric encryption key. The encrypted data (the DEM portion) and the
encrypted symmetric key (the KEM portion, called a `capsule`) are stored together.
Even though different blocks of newly generated bulk data may use different symmetric keys, the same asymmetric
encryption key provided by Alice is used to encrypt the symmetric key. How and when Enrico uses a new symmetric key
is up to the user of the Enrico API.
Bob::Retrieve
^^^^^^^^^^^^^
.. image:: ../.static/img/bob_retrieve.svg
:target: ../.static/img/bob_retrieve.svg
When Bob wants to access the data, he must first obtain the encrypted data and `capsule` from encrypted storage.
However, this data is currently encrypted and inaccessible to Bob.
To gain access, Bob must request re-encryption of the `capsule` by the `n` Ursulas that participated in the policy.
Remember that when Alice granted access to Bob, she created a `treasure map` that contained
this list of `n` Ursulas in the policy, and the associated encrypted re-encryption key fragments (`kFrags`) for Bob to
give to the Ursulas for the re-encryption operation. Therefore, Bob sends his `capsule` and the relevant encrypted
`kFrag` to the various Ursulas in the Threshold Network associated with the policy. Those Ursulas
will decrypt the encrypted `kFrag` and use it to perform a partial re-encryption operation on the `capsule` to
produce a corresponding ciphertext fragment, `cFrag`. In the same way a `kFrag` is a fragment of a key, a `cFrag`
is a fragment of ciphertext. The `cFrag` is returned to Bob, who collects `cFrags` until he obtains a threshold, `m`,
number of `cFrags`. Bob attaches `m` received `cFrags` to the original `capsule` to obtain the fully re-encrypted
`capsule` that is now encrypted under his public key. Note that the generation of a complete re-encrypted `capsule`
is possible from a smaller number of `cFrags` than the number of `kFrags` included in the `treasure map`
(m-of-n threshold scheme). Bob can now decrypt the `capsule` to obtain the symmetric key originally used to
encrypt the bulk data.
Once Bob has the symmetric key, he can use it to decrypt the bulk data. This process can be repeated as more data is
shared with Bob that is associated with the `label` for the policy.
Ultimately, because of the KEM/DEM approach, only the `capsule` needs to be re-encrypted for Bob.
Subsequently, the size of the actual bulk data is irrelevant - whether 1KB or 1GB the re-encryption operation only
needs to be performed on the fixed size `capsule`, which is simply an encrypted symmetric key.
Ursula::Reencrypt
^^^^^^^^^^^^^^^^^
.. image:: ../.static/img/ursula_reencrypt.svg
:target: ../.static/img/ursula_reencrypt.svg
Having received an encrypted `kFrag` and a `capsule` from Bob as part of the re-encryption request,
Ursula can now partially re-encrypt data for Bob. Ursulas decrypt the encrypted `kFrag` using their private key, and
use it to perform a re-encryption operation on the `capsule` to return a corresponding `cFrag`. Bob will
require `m` of these interactions with `m` different Ursulas to obtain a fully re-encrypted `capsule`.

74
docs/source/architecture/contracts.rst
View File

@ -1,74 +0,0 @@
.. _contracts:
Ethereum Contracts
==================
Contract Listing
----------------
* ``NuCypherToken`` ERC20 token contract
* ``StakingEscrow`` Legacy staking contract
* ``Adjudicator`` Manages :doc:`the slashing protocol </architecture/slashing>`
* ``Upgradeable`` Base contract for :doc:`upgrading </architecture/upgradeable_proxy_contracts>`
* ``Dispatcher`` Proxy to other contracts and provides upgrading of the ``StakingEscrow`` contract
* ``SimplePREApplication`` Interim application contract for Threshold network
* ``SubscriptionManager`` Holds a policy's fee and distributes them
Deployment Procedure
--------------------
This section provides a step-by-step guide of how NuCypher contracts are deployed.
#. Deploy ``NuCypherToken`` with all future supply tokens
#. Deploy stub for ``StakingEscrow`` with a dispatcher targeting it
#. Deploy Threshold network contracts
#. Deploy ``StakingEscrow`` and retarget its dispatcher by using the ``upgrade(address)`` function
#. Deploy ``SimplePREApplication`` contract
#. Deploy ``SubscriptionManager`` contract
Alice's Contract Interaction
----------------------------
Alice Authors a Blockchain Policy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Alice uses a network of Ursula staking providers to deploy policies.
In order to take advantage of the network, Alice chooses staking providers and deploys policies with fees for those staking providers.
Alice can choose stakers by herself ("handpicked") or select from the result of ``SimplePREApplication.getActiveStakingProviders(uint256, uint256)`` method - This is known as ("sampling").
``getActiveStakingProviders`` parameters are:
* Start index in stakers array
* Maximum number of stakers
This method will return only active staking providers.
In order to place the fee for a policy, Alice calls the method ``SubscriptionManager.createPolicy(bytes16, address, uint16, uint32, uint32)``\ ,
specifying the policy ID (off-chain generation), the policy owner (could be zero address), the number of nodes, the start and the end timestamp of the policy.
Payment should be added to the transaction in ETH and the amount is ``feeRate * duration * numberOfNodes``\ , where ``duration`` is ``endTimestamp - startTimestamp``.
Staking Provider's Contract Interaction
---------------------------------------
The Staking Provider Bonds to an Operator ("Ursula")
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The staking provider must specify an operator who will make a confirmation and sign on behalf of this staking provider by calling the ``SimplePREApplication.bondOperator(address, address)`` method.
Bonding a new operator is allowed no more than once within ``SimplePREApplication.minOperatorSeconds()``.
Only the operator can make a confirmation.
Ursula Makes a Confirmation
^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to make a address confirmation, operators call ``SimplePREApplication.confirmOperatorAddress()``.
Contracts Versioning
--------------------
Upgradeable contracts, such as ``StakingEscrow``\, have their version specified in contract doc inside @dev.
Version format is ``|vi.j.k|``\ , where ``i`` - major version, ``j`` - minor version, ``k`` - patch, for example ``|v1.2.3|``\ :
* Different major versions mean different forks and they are not upgradeable
* Minor versions relate to any signatures or state changes inside contract, contracts are upgradeable between minor versions, but have different ABI and follows different agent layers
* Patches involve changes inside function(s) with signature(s) untouched. All patches with a common minor version can be upgraded from one to another without other changes

35
docs/source/architecture/slashing.rst
View File

@ -1,35 +0,0 @@
.. _slashing-protocol:
The Slashing Protocol
=====================
The slashing protocol is a preventative mechanism that disincentivizes certain staker actions, whether deliberate or unintentional, that may negatively impact service quality or network health. If prohibited actions (‘violations’) are attributably detected at any moment, the protocol responds by irreversibly forfeiting (‘slashing’) a portion of the offending staker’s collateral (‘stake’).
At network genesis, the protocol will be able to detect and attribute instances of incorrect re-encryptions returned by Ursulas. The staker controlling the incorrectly re-encrypting Ursula will have their stake reduced by a nominal sum of NU tokens.
Violations
----------
In response to an access request by Bob, Ursula must generate a re-encrypted ciphertext that perfectly corresponds to the associated sharing policy (i.e. precisely what Alice intended Bob to receive). If the ciphertext is invalid in this regard, then Ursula is deemed to be incorrectly re-encrypting. Each instance of incorrect re-encryption is an official violation and is individually punished.
There are other ways stakers can compromise service quality and network health, such as extended periods of downtime or ignoring access requests. Unlike incorrect re-encryptions, these actions are not yet reliably attributable. Punishing non-attributable actions may result in unacceptable outcomes or introduce perverse incentives, thus these actions are not yet defined as violations by the slashing protocol. 

Detection
----------
Incorrect re-encryptions are detectable by Bob, who can then send a proof to the protocol to confirm the violation. This is enabled by a bespoke zero-knowledge correctness verification mechanism, which follows these steps:
1. When Alice creates a kFrag, it includes components to help Ursula prove the correctness of each re-encryption she performs. The kFrag’s secret component is used to perform the re-encryption operation. The kFrag also comprises public components, including a point commitment on the value of the secret component.
2. When Ursula receives the kFrag, she checks its validity – that the point commitment on the secret component is correct. This ensures that she doesn’t incorrectly re-encrypt due to Alice’s error (or attack).
3. Bob makes a re-encryption request by presenting a capsule to Ursula, and she responds with a cFrag. This contains the payload (a re-encrypted ciphertext) and a non-interactive zero knowledge proofs of knowledge (NIZK).
4. Bob checks the validity of the cFrag using the NIZK. He verifies that the point commitment corresponds to the ciphertext. He also checks that the cFrag was generated using his capsule, by verifying that it was created with the correct public key.
5. If any of the verifications fail, then Bob supplies the ciphertext and NIZK to the :ref:`Adjudicator contract <contracts>`. The contract examines Bob's claim by checking whether the NIZK proof for the ciphertext fails, leveraging `optimized ECC algorithms <https://github.com/nucypher/numerology>`_.
6. If the invalidity of the cFrag is confirmed by the Adjudicator contract, the delivery of a faulty cFrag to Bob is ruled to be an official protocol violation. A penalty is computed and the owner of the offending Ursula has their stake immediately slashed by the penalty amount.
.. image:: ../.static/img/correctness_verification_schematic.svg
:target: ../.static/img/correctness_verification_schematic.svg
Penalties
---------
TBD

83
docs/source/architecture/upgradeable_proxy_contracts.rst
View File

@ -1,83 +0,0 @@
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.
Approach A
----------
One simple way to achieve this is to create a new contract, copy the original storage values to the new contract, then self-destruct (mark as deleted) the old contract.
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
Approach B
----------
A more convenient way is to use a proxy contract with an interface where each method redirects to the *target* contract.
This option is advantageous because the client uses one address most of the time but also has its own methods.
.. important::
If updates to the proxy contract's methods are made, then the client will need to change proxy address also.
Approach C
----------
Another way is using a fallback function in the proxy contract - this function will execute on any request, redirecting the request to the target and returning the resulting value (using opcodes).
This is similar to the previous option, but this proxy doesn't have interface methods, only a fallback function, so there is no need to change the proxy address if contract methods are changed.
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).
* Proxy contracts (Dispatcher) hold storage (not in the contract itself). While upgrading storage, values must be the same or equivalent (see below).
Interaction scheme
------------------
.. image:: ../.static/img/Dispatcher.png
:target: ../.static/img/Dispatcher.png
``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
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``.
``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,
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.
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.

283
docs/source/conf.py
View File

@ -1,283 +0,0 @@
# -*- coding: utf-8 -*-
"""
This file is part of nucypher.
nucypher is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
nucypher is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with nucypher. If not, see <https://www.gnu.org/licenses/>.
"""
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import doctest
import os
import sys
from pathlib import Path
sys.path.insert(0, os.path.abspath("../.."))
# -- Project information -----------------------------------------------------
project = "NuCypher"
copyright = "2023, NuCypher"
author = "NuCypher"
# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = '7.0.0-rc.4'
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.napoleon',
'sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinx.ext.doctest',
'sphinx.ext.mathjax',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['.templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
source_suffix = '.rst'
# The main toctree document.
main_doc = 'index'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
html_theme_options = {
'logo_only': True,
}
html_logo = '.static/img/nucypher_logo.svg'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['.static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'NuCypherdoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(main_doc, 'NuCypher.tex', 'NuCypher Documentation',
'NuCypher', 'manual'),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(main_doc, 'nucypher', 'NuCypher Documentation',
[author], 1)
]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(
main_doc,
"NuCypher",
"NuCypher Documentation",
author,
"NuCypher",
"A threshold access control application to empower privacy in decentralized systems.",
"Miscellaneous",
),
]
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
#
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
# -- Intersphinx configuration ------------------------------------------------
intersphinx_mapping = {
"python": ("https://docs.python.org/3.8", None),
"pyUbmbral": ("http://pyumbral.readthedocs.io/en/latest/", None),
"web3py": ("https://web3py.readthedocs.io/en/latest/", None),
}
# -- Autodoc configuration ----------------------------------------
def remove_module_license(app, what, name, obj, options, lines):
if what == "module":
del lines[:]
def run_apidoc(_):
"""# sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …]"""
from sphinx.ext import apidoc
source_dir = Path(__file__).parent.resolve()
nucypher_module_dir = source_dir.parent.parent
# Command: sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN …]
apidoc_command = []
# ---- execution options/paths ----
apidoc_command.extend(['-fME',
'-t', f'{source_dir / "apidoc"}',
'-o', f'{source_dir / "api"}',
'-H', 'Python API',
f'{nucypher_module_dir}'])
# ---- exclusion patterns (*must be last to be added*) ----
# general patterns
apidoc_command.extend([
'*conftest*',
])
# files/folders relative to `nucypher` project directory (results in required absolute paths)
exclusion_items = [
"setup.py",
"tests",
"scripts",
Path("nucypher", "utilities"),
Path("nucypher", "cli"),
]
for exclusion_item in exclusion_items:
apidoc_command.append(f'{nucypher_module_dir / exclusion_item}')
# ---- execute command ----
apidoc.main(apidoc_command)
def setup(app):
app.add_css_file('style.css')
app.connect("autodoc-process-docstring", remove_module_license)
app.connect('builder-inited', run_apidoc)
add_module_names = False
autodoc_member_order = "bysource"
# -- Doctest configuration ----------------------------------------
doctest_default_flags = (0
| doctest.DONT_ACCEPT_TRUE_FOR_1
| doctest.ELLIPSIS
| doctest.IGNORE_EXCEPTION_DETAIL
| doctest.NORMALIZE_WHITESPACE
)

73
docs/source/glossary.rst
View File

@ -1,73 +0,0 @@
Glossary
========
.. _Umbral: https://github.com/nucypher/umbral-doc/blob/master/umbral-doc.pdf
.. glossary::
Alice
*"The Data Owner"* :term:`Character` - retains full control over the data encrypted for her and determines whom to share the data with.
Bob
*"The Data Recipient"* :term:`Character` - the data recipient that :term:`Alice` intends to share data with.
Capsule
Encrypted symmetric key (:term:`KEM`) that is eventually re-encrypted.
cFrag
A fragment of ciphertext that is a partial re-encryption produced by a :term:`kFrag` operation on a :term:`Capsule`.
Character
A common term for any entity fulfilling a particular role in our cryptographic narrative.
DEM
Data encapsulation mechanism - data encrypted with a symmetric key.
Enrico
*"The Encryptor"* :term:`Character` - a data source that encrypts data on behalf of :term:`Alice` and produces a :term:`MessageKit`.
KEM
Key encapsulation mechanism - a symmetric key encrypted with an asymmetric key
kFrag
A fragment of a :term:`Re-encryption Key`.
Label
A title for a classification/categorization of data according to how it is intended to be shared.
MessageKit
The ciphertext (data encrypted with a symmetric key) and the :term:`Capsule` (encrypted symmetric key) that are stored together.
NU
The Legacy NuCypher token used by nodes for staking.
NuNit
1 NU = 10\ :sup:`18` NuNits.
PKE
Public-key encryption.
Porter
A web service that is the conduit between applications (platform-agnostic) and the PRE nodes on the Threshold network, that
performs ``nucypher`` protocol operations on behalf of Alice and Bob.
PRE
Proxy re-encryption.
Re-encryption Key
A key that facilitates the transformation of ciphertext from one encryption key to another.
Stamp
The public key for a :term:`Character`'s signing key pair.
Treasure Map
The locations of :term:`Ursulas<Ursula>` and associated encrypted :term:`kFrags<kFrag>` for a policy. :term:`Bob` will use the treasure map to determine which :term:`Ursulas<Ursula>` to contact to re-encrypt the data :term:`Alice` has shared with him.
Umbral
NuCypher's threshold proxy re-encryption scheme - it takes standard :term:`PRE` and increases security and performance. See Umbral_.
Ursula
*"The Proxy in PRE"* :term:`Character` - the PRE node on the Threshold Network that stands ready to re-encrypt data in exchange for payment in fees and token rewards; they enforce the access policy created by :term:`Alice`.
Operator
An account that is actively doing work in the network as an :term:`Ursula` node. An Operator is bonded to, and performs work on behalf of, a Staking Provider.

178
docs/source/index.rst
View File

@ -1,178 +0,0 @@
.. _Umbral: https://github.com/nucypher/pyUmbral
.. image:: ./.static/img/threshold_logo_purple.png
:target: ./.static/img/threshold_logo_purple.png
`Welcome <https://blog.threshold.network/threshold-launch/>`_ to the Threshold Network!
Introduction
=============
The `NuCypher Network <https://www.nucypher.com/>`_ has merged with the
`KEEP Network <https://keep.network/>`_ to form the `Threshold Network <https://threshold.network/>`_!
The Threshold Network powers user sovereignty on the public blockchain. It provides a decentralized
network of nodes that perform threshold cryptography operations as a service to ensure full control over
your digital assets.
.. raw:: html
<div>
<div style="position:relative;padding-top:56.25%;">
<iframe style="position:absolute;top:0;left:0;width:100%;height:100%;" src="https://www.youtube-nocookie.com/embed/8MzE_FG67Z8?rel=0&controls=1&modestbranding=1" frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</div>
</div>
<br/>
Proxy Re-Encryption (PRE) Application
=====================================
The NuCypher Network proxy re-encryption (PRE) service is now the PRE Application on the Threshold Network.
The PRE Application is the first of many *threshold cryptography*-based applications
to be hosted on the Threshold Network. PRE is an end-to-end encryption protocol that is a more scalable, more flexible form of
`public-key encryption <https://en.wikipedia.org/wiki/Public-key_cryptography>`_ and enables a group of proxy
entities to transform encrypted data from one public key to another, without the power to decrypt the data or gain access to any
private keys. PRE equips developers, applications and end-users with **secrets management** and **dynamic access control** capabilities.
This service is provided by a decentralized array of nodes on the Threshold Network, each running the same PRE client software.
Private data, wherever stored, remains private, confidential
and encrypted while maintaining the ability to share that data with trusted parties.
.. attention::
In order to run a PRE node on Threshold, ``nucypher`` v6.0.0 or above will be required.
See `releases <https://pypi.org/project/nucypher/#history>`_ for the latest version.
How does it Work?
-----------------
.. image:: ./.static/img/nucypher_overview.svg
:target: ./.static/img/nucypher_overview.svg
1. Alice, the data owner, grants access to her encrypted data to
anyone she wants by creating a policy and uploading it to
the PRE Application on the Threshold Network.
2. Alice gets information about the group of ``n`` PRE nodes (Ursulas) associated
with the policy, which are nodes on the Threshold network providing the PRE service. Each :term:`Ursula` provides their encrypting key, and Alice creates
``n`` re-encryption key shares (:term:`kFrag`), each of which is encrypted with a different Ursula's encrypting key.
The Ursulas in the group stand ready to re-encrypt data in exchange for payment in fees and token rewards.
The list of Ursulas and their associated encrypted re-encryption key shares are stored in a :term:`Treasure Map`. Alice
subsequently encrypts the treasure map for Bob. The treasure map provides Bob the requisite information and cryptographic material to successfully request the Threshold network to re-encrypt the data shared by Alice – such that he can decrypt it with his private key.
3. Each policy created by Alice has an associated encryption key, which can be used
by any entity (Enrico) to encrypt data on Alice's behalf.
This entity could be an IoT device in her car, a collaborator assigned
the task of writing data to her policy, or even a third-party creating
data that belongs to her – for example, a lab analyzing medical tests.
The resulting encrypted data can be uploaded to IPFS, Swarm, S3,
or any other storage layer.
4. Bob, a data recipient, uses the treasure map to determine the list of Ursulas to contact and the associated
re-encryption key share to send to Ursula for the re-encryption operation. Bob obtains the encrypted data from the
storage layer and sends a re-encryption request to the relevant Ursulas on the Threshold network. If the policy is
satisfied, Ursula decrypts the provided re-encryption key share and re-encrypts the data to Bob's public key. Bob
can subsequently decrypt the data with his private key.
5. Ursulas earn fees and token rewards for being available to perform re-encryption operations.
More detailed information:
- :ref:`character-concepts`
- GitHub https://www.github.com/nucypher/nucypher
- Website https://www.nucypher.com/
Whitepapers
-----------
**Original Network**
https://github.com/nucypher/whitepaper/blob/master/whitepaper.pdf
*"NuCypher - A proxy re-encryption network to empower privacy in decentralized systems"*
*by Michael Egorov, David Nuñez, and MacLane Wilkison - NuCypher*
**Cryptography**
https://github.com/nucypher/umbral-doc/blob/master/umbral-doc.pdf
*"Umbral A Threshold Proxy Re-Encryption Scheme"*
*by David Nuñez - NuCypher*
.. toctree::
:maxdepth: 1
:caption: Threshold
threshold/threshold_overview
.. toctree::
:maxdepth: 1
:caption: PRE Application
pre_application/overview
pre_application/node_requirements
pre_application/running_a_node
pre_application/cloud_node_management
pre_application/best_practices
pre_application/node_providers
.. toctree::
:maxdepth: 1
:caption: Application Development
application_development/getting_started
application_development/web_development
.. toctree::
:maxdepth: 1
:caption: References
references/installation
references/cli_reference
references/environment_variables
references/network_events
.. toctree::
:maxdepth: 1
:caption: Architecture
architecture/character
architecture/contracts
architecture/upgradeable_proxy_contracts
architecture/slashing
.. TODO perhaps categorize architecture section
.. toctree::
:maxdepth: 1
:caption: APIS
api/modules
.. toctree::
:maxdepth: 1
:caption: Support
release_notes/releases
support/contribution
support/community
support/troubleshooting
support/faq
glossary
Indices and Tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

61
docs/source/pre_application/best_practices.rst
View File

@ -1,61 +0,0 @@
=======================
Node/Operator Diligence
=======================
.. attention::
This best practices document is a work-in-progress and is not comprehensive.
Operators can demonstrate their vested interest in the success of the network by adhering to
the following core areas of responsibility (in order of importance):
1. Keystore Diligence
---------------------
Requires that private keys used by the PRE node are backed up and can be restored.
Keystore diligence an be exercised by:
- Keeping an offline record of the mnemonic recovery phrase.
- Backing up the worker's keystores (both ethereum and nucypher).
- Using a password manager to generate and store a strong password when one is required.
.. note::
The default location of the nucypher PRE node keystore files can be located by
running a nucypher command:
.. code::
$ nucypher --config-path
Encrypted PRE Node keys can be found in the ``keystore`` directory:
.. code-block:: bash
/home/user/.local/share/nucypher
├── ursula.json
├── keystore
│ ├── 1621399628-e76f101f35846f18d80bfda5c61e9ec2.priv
└── ...
2. Runtime Diligence
--------------------
Requires active and security-conscious participation in the network.
A PRE node that is unreachable or otherwise invalid will be unable to accept new
policies, and miss out on inflation rewards.
It is **not necessary (and potentially risky)** to hold NU/T tokens on an Operator's
account for any reason.
Runtime Diligence an be exercised by:
- Secure the node's keystore used on the deployment host.
- Maintain high uptime; keep downtime brief when required by updates or reconfiguration.
- Update when new versions are available.
..
TODO: separate section on backups and data (#2285)

118
docs/source/pre_application/cloud_node_management.rst
View File

@ -1,118 +0,0 @@
.. _managing-cloud-nodes:
===============================
PRE Node Deployment Automation
===============================
.. note::
Previously this functionality was provided by the ``nucypher cloudworkers`` CLI command.
However, that command has been deprecated and analogous functionality is now provided
via `nucypher-ops <https://github.com/nucypher/nucypher-ops>`_.
In this tutorial we're going to setup a Threshold PRE node using a remote cloud provider (Digital Ocean, AWS, and more in the future).
The PRE node will run via a Docker container.
.. note::
By default, ``nucypher-ops`` uses a Docker container restart policy of ``unless-stopped``.
This ensures that the Docker container will be automatically restarted if it exited,
except if the container was stopped via an appropriate command. See `Docker Restart Policies <https://docs.docker.com/engine/reference/run/#restart-policies---restart>`_
for more information.
This example will demonstrate how to deploy to Digital Ocean. There are a few pre-requisites before we can get started.
First, we need to create accounts on `Digital Ocean <https://cloud.digitalocean.com/>`_ and `Infura <https://infura.io>`_.
Also ensure that your local environment has python 3.8 or later installed.
Launch Remote Node
-------------------
.. important::
nucypher-ops requires python 3.8 or later.
Locally, we will install `NuCypher Ops <https://github.com/nucypher/nucypher-ops>`_ to handle the heavy lifting of setting up a node.
.. code-block:: bash
$ pip install nucypher-ops
Now NuCypher Ops is installed we can create a droplet on Digital Ocean:
.. code-block:: bash
nucypher-ops nodes create
Follow the interactive prompts to select the Digital Ocean provider.
After this command completes you will see a new droplet in your Digital Ocean dashboard.
Now we can deploy the PRE Node:
.. code-block:: bash
nucypher-ops ursula deploy
Follow the prompts to enter your ethereum and polygon provider URIs.
This should produce a lot of log messages as the ansible playbooks install all the requirements and setup the node.
The final output should be similar to:
.. code-block:: bash
some relevant info:
config file: "/SOME_PATH/nucypher-ops/configs/mainnet/nucypher/mainnet-nucypher.json"
inventory file: /SOME_PATH/nucypher-ops/configs/mainnet-nucypher-2022-03-25.ansible_inventory.yml
If you like, you can run the same playbook directly in ansible with the following:
ansible-playbook -i "/SOME_PATH/nucypher-ops/configs/mainnet-nucypher-2022-03-25.ansible_inventory.yml" "src/playbooks/setup_remote_workers.yml"
You may wish to ssh into your running hosts:
ssh root@123.456.789.xxx
*** Local backups containing sensitive data may have been created. ***
Backup data can be found here: /SOME_PATH//nucypher-ops/configs/mainnet/nucypher/remote_worker_backups/
This tells us the location of several config files and helpfully prints the IP address of our newly created node (you can also see this on the Digital Ocean dashboard).
Let's ``ssh`` into it and look at the logs:
.. code-block:: bash
$ ssh root@123.456.789.xxx
root@nucypher-mainnet-1:~#
root@nucypher-mainnet-1:~# sudo docker logs --follow ursula
...
! Operator 0x06E11400xxxxxxxxxxxxxxxxxxxxxxxxxxxx1Fc0 is not funded with ETH
! Operator 0x06E11400xxxxxxxxxxxxxxxxxxxxxxxxxxxx1Fc0 is not bonded to a staking provider
...
These lines will print repeatedly until the Operator is funded with some mainnet ETH and bonded to a staking provider.
Stake and Bond
--------------
If you have not already done so you'll need to establish a stake on the `Threshold
Dashboard <https://dashboard.threshold.network/overview/network>`_.
After you've established your stake, proceed to the
`PRE node bonding dashboard <https://stake.nucypher.network/manage/operator>`_ to bond your node's
Operator address to your stake.
Monitor Remote Node
-------------------
Send a small amount of ETH to your Operator address so it can perform the initial confirmation transaction which signals that your
node is open for business. Once you've funded the Operator address and bonded to the stake, view the node's logs.
It will automatically detect both completed actions.
After funding and bonding the node will resume startup displaying the following logs:
.. code-block:: bash
Broadcasting CONFIRMOPERATORADDRESS Transaction (0.00416485444 ETH @ 88.58 gwei)
TXHASH 0x3329exxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx5ec9a6
✓ Work Tracking
✓ Start Operator Bonded Tracker
✓ Rest Server https://123.456.789.000:9151
Working ~ Keep Ursula Online!
You can view the status of your node by visiting ``https://<YOUR_NODE_IP>:9151/status``
That's all!

35
docs/source/pre_application/node_providers.rst
View File

@ -1,35 +0,0 @@
.. _node-providers:
=================
Staking Providers
=================
You can delegate running a PRE node to one of the *node-as-a-service* Staking Providers listed below.
.. warning::
Staking Providers have not been vetted or endorsed by the core development team.
Use your own judgement when selecting a provider.
* `Ankr <https://www.ankr.com>`_
* Email: sales@ankr.com
* `Coinbase Cloud <https://www.coinbase.com/cloud>`_
* Email: cloud-sales@coinbase.com
* `DELIGHT <https://delightlabs.io>`_
* Email: contact@delightlabs.io
* `Figment <https://figment.io/>`_
* Email: support@figment.io
* Discord: ``@claymenzel#0569``
* Telegram: ``@claymenzel``
* `InfStones <https://infstones.com/>`_
* Email: sales@infstones.com
* Telegram: https://t.me/infstones
* WeChat: ``@InfStones``
* `P2P Validator <https://p2p.org>`_
* Email: am@p2p.org
* Telegram: ``@P2Pstaking``
* `Staked <https://staked.us/>`_
* Email: staked@staked.us
* Telegram: ``@staked_official``
More detailed profile information about each Staking Provider is available `here <https://github.com/nucypher/validator-profiles>`_.

110
docs/source/pre_application/node_requirements.rst
View File

@ -1,110 +0,0 @@
.. _node-requirements:
Node Requirements
=================
Minimum System Requirements
---------------------------
* Debian/Ubuntu (Recommended)
* 20GB storage
* 4GB RAM
* x86 architecture
* Static IP address
* Exposed TCP port 9151
Nodes can be run on cloud infrastructure - for example, a
`Digital Ocean 4GB Basic Droplet <https://www.digitalocean.com/pricing/>`_
satisfies the requirements listed above.
The above requirements only apply if you intend to run a node yourself.
Alternatively, a :ref:`staking provider<node-providers>` can run a node on your behalf.
PRE Node Configuration Requirements
-----------------------------------
Ethereum Node Provider URI
++++++++++++++++++++++++++
The PRE node will need to execute an initial transaction to confirm its
operation on startup, and therefore requires access to an
`ethereum node <https://web3py.readthedocs.io/en/stable/node.html>`_
(either a local or remote ethereum node) to broadcast the transaction. Remote
ethereum providers include Infura, Alchemy etc. and an HTTPS URI will need to
be configured (``https://<URI>``), whereas a local full node would entail running
`geth <https://geth.ethereum.org/>`_ locally and configured using the
IPC URI (``ipc://<PATH TO IPC FILE>``).
This value is specified via the ``--eth-provider`` CLI parameter.
It is worth noting that running a local ethereum node is quite the undertaking,
and has its own
`additional requirements <https://docs.ethhub.io/using-ethereum/running-an-ethereum-node/>`_.
Polygon Node Provider URI
+++++++++++++++++++++++++
As of ``nucypher`` v6.0.0, policy management occurs on the `Polygon <https://polygon.technology/>`_ layer 2 side-chain
by default. In order to validate the payment of policies before responding to service required, PRE nodes will need to
make requests to the Polygon side-chain. Much like an Ethereum provider endpoint, the PRE node will need
to configure a Polygon RPC endpoint URI e.g. (``https://<URI>``) for the node to use. This value is specified via
the ``--payment-provider`` CLI parameter. Infrastructure providers such as
`Infura <https://blog.infura.io/polygon-now-available/>`_, provide Polygon endpoints.
.. _operator-address-setup:
Operator Software Ethereum Account
++++++++++++++++++++++++++++++++++
A software wallet is recommended for the PRE node operator's ethereum account
since the account needs to remain unlocked to execute an automated transaction
when the node first starts.
.. caution::
- Operator accounts **do not** need NU/KEEP/T tokens for any reason; do not keep NU/KEEP/T in the
operator account.
- Do not store large amounts of ETH in the operator account; only enough to pay gas fees. Nodes
only need to execute a single transaction on the first start which costs ~100K gas at
a gas price of 146 gwei, this would be ~0.015 ETH). There are no subsequent transactions on restarts.
- Store the operator account password in a password manager
To create a new ethereum software account using the ``geth`` CLI
(more information `here <https://geth.ethereum.org/>`_):
.. code::
geth account new
- Never share your ethereum account password.
- Do not forget your ethereum account password.
- Secure your ethereum account password in a password manager.
This command will add a new account to your local keystore.
PRE Node Operator Transaction Signer
++++++++++++++++++++++++++++++++++++
In conjunction with an Ethereum node provider for broadcasting to the
Ethereum blockchain, the node also needs to configure a transaction signer
for signing messages to be broadcasted.
This separation of a transaction signer from an Ethereum node allows pre-signed
transactions to be sent to an external (possibly remote) ethereum node and is
particularly desirable when interacting with an untrusted ethereum node.
Local ethereum keystore signing can be configured for the operator software
account. Local keystore signing utilizes `eth-account <https://github.com/ethereum/eth-account/>`_
to sign ethereum transactions using local ethereum keystore files. By default
on Linux, the default local keystore directory path is ``~/.ethereum/keystore``.
The local keystore signer can be specified during initialization using the
following URI format, ``--signer`` CLI parameter and ``keystore://<PATH TO LOCAL KEYSTORE>`` as the
value, eg. ``--signer keystore:///root/.ethereum/keystore``.
.. note::
The expectation is that the operator account is part of the local ethereum keystore.

108
docs/source/pre_application/overview.rst
View File

@ -1,108 +0,0 @@
.. _pre-overview:
.. _Threshold Dashboard: https://dashboard.threshold.network/staking
Application Overview
====================
All Threshold Network Stakers (legacy KEEP, legacy NU, liquid T) are able to participate
in the PRE application. Threshold Staking can be performed and managed via
the `Threshold Dashboard`_.
.. note::
The current minimum stake for running a PRE node is (or equivalent to) 40,000 T but is tunable via governance.
.. attention::
As part of the migration to the Threshold Network, there will eventually be a new version of the
PRE Application, which will require some new setup steps and other steps to be repeated, such as
bonding an operator. At that time, there will be a related announcement on `Discord <https://discord.gg/threshold>`_.
.. _stake-initialization:
Stake Initialization
--------------------
To be eligible to run a PRE node, there must be a stake on Threshold. This stake can take the following forms:
* Legacy NU stake migrated to T from the `NuCypher Dashboard <https://stake.nucypher.network/manage>`_.
* Legacy KEEP stake migrated to T from the `Keep Dashboard <https://dashboard.keep.network/applications/threshold>`_.
* T stake using liquid T created on the `Threshold Dashboard`_.
Once the stake is created, a PRE node can be set up to run on the Threshold Network.
Here is a summary of the overall process:
.. image:: ../.static/img/staking_initialization_process.svg
:target: ../.static/img/staking_initialization_process.svg
Staking Roles
-------------
For more information about the roles associated with the Threshold Staking contract,
see `here <https://github.com/threshold-network/solidity-contracts/blob/main/docs/rfc-1-staking-contract.adoc>`_.
The PRE Application operations are divided into two roles:
* `Staking Provider`_
* `Operator`_
Staking Provider
++++++++++++++++
The Staking Provider is a party authorized to operate in the network on behalf of a
given stake owner - it can be the owner itself for self-hosting. The staking provider handles
the everyday operations on the delegated stake without actually owning the staked tokens. A
staking provider cannot transfer delegated staked tokens, but the staking provider’s misbehavior may
result in slashing tokens and thus the entire staked amount is indeed at stake. A Staking Provider
can be specified on the `Threshold Dashboard`_
Operator
++++++++
The Operator (aka "Ursula") is the node, and associated Ethereum address, that provides PRE application service.
It is the :ref:`bonded <bond-operator>` delegate of a Staking Provider and an active network node, performing PRE work on behalf
of a Staking Provider. Nodes must remain online to provide uninterrupted services on-demand.
.. note::
In the traditional NuCypher Network parlance, ``Worker`` can be used interchangeably
with the new Threshold Network ``Operator`` term.
Staking Provider Strategies & Responsibilities
++++++++++++++++++++++++++++++++++++++++++++++
In order to provide the PRE service and receive rewards, there are three options for running a PRE node:
* **Node Delegation**: Delegate running a PRE client to one of the participating *node-as-a-service* :ref:`Staking Providers <node-providers>`. In this
case, the setup, operation, and monitoring is outsourced, and stakers need only check in occasionally to ensure the provider is handling things as expected.
* **Self-Managed, Manual**: :ref:`Run <running-a-node>` your own PRE node and retain full purview and customization control over the machine(s), installation, dependencies and configuration. In this case, stakers are entirely responsible for setup, operation, and monitoring
of the PRE client.
* **Self-Managed, Automated**: Run your own PRE node on either Digital Ocean or AWS, leveraging :ref:`automation tools <managing-cloud-nodes>` that speed up and simplify the installation process. In this case too, stakers are entirely responsible for setup, operation, and monitoring of the PRE client.
Note that setting up a PRE node from scratch is non-trivial, but is typically inexpensive and unburdensome to maintain.
PRE end-users expect and require an on-demand service, wherein their *grant*, *revoke* and *re-encryption* requests are answered reliably, correctly, and without interruption.
Hence the most critical responsibility for stakers is ensuring that their PRE node remains online **at all times**. If this is not certain using a local machine, it is highly recommended to use cloud infrastructure instead.
Staker Subsidization (Rewards)
------------------------------
Stakers who have successfully set up their PRE node (confirmed and activated via an on-chain transaction) are eligible to receive rewards, denominated in the native T token.
The sum received will be proportional to one's relative stake size and the duration of time the staker has been active, but independent of the staking rate – i.e. issuance will be computed to target
a `minimum yield <https://forum.threshold.network/t/threshold-network-reward-mechanisms-proposal-i-stable-yield-for-non-institutional-staker-welfare/82>`_.
The target yield and subsequent issuance (total number of tokens distributed monthly to stakers) will be determined by the Threshold Council, and will ramp up over the genesis era of the Threshold Network.
.. important::
During the genesis era of Threshold Network, to avoid prejudicing against new stakers who have never run a PRE node previously, the first 1-2 months can be considered a *"grace period"* in which
all stakers will receive the full month's rewards, regardless of which day they commenced staking.

559
docs/source/pre_application/running_a_node.rst
View File

@ -1,559 +0,0 @@
.. _running-a-node:
==================
Running a PRE Node
==================
.. attention::
In order to run a PRE node on Threshold, ``nucypher`` v6.0.0 or above will be required.
See `releases <https://pypi.org/project/nucypher/#history>`_ for the latest version.
.. note::
NuCypher maintains a separate self-contained CLI that automates the initialization
and management of PRE nodes deployed on cloud infrastructure. This CLI leverages
automation tools such as Ansible and Docker to simplify the setup and management
of nodes running in the cloud (*under active development and currently limited to
testnet automation*). See :ref:`managing-cloud-nodes`.
After :ref:`staking on Threshold <stake-initialization>`, and finding a server that meets the :ref:`requirements <node-requirements>`, running a PRE node entails the following:
#. :ref:`install-nucypher`
#. :ref:`bond-operator`
#. :ref:`configure-and-run-node`
#. :ref:`qualify-node`
#. :ref:`manage-node`
.. _install-nucypher:
Install ``nucypher``
====================
See ``nucypher`` :doc:`installation reference</references/installation>`. There is the option
of using Docker (recommended) or a local installation.
.. _bond-operator:
Bond Operator
=============
The Staking Provider must be bonded to an :ref:`Operator address<operator-address-setup>`. This
should be performed by the Staking Provider via the ``nucypher bond`` command (directly or as part of a Docker command). Run
``nucypher bond --help`` for usage. The Operator address is the ETH account that will be used when running the Ursula node.
.. attention::
This command should **only** be executed by the Staking Provider account. This would be the same as the stake owner account
for self-managed nodes, or the *node-as-a-service* :ref:`provider <node-providers>` for node delegation.
.. important::
Once the Operator address is bonded, it cannot be changed for 24 hours.
via UI
------
* Navigate to https://stake.nucypher.network/manage/bond
* Connect with the Staking Provider account to execute the bond operation
* Enter the Operator address to bond
* Click *"Bond Operator"*
via Docker
----------
.. code:: bash
.. code:: bash
$ docker run -it \
-v ~/.local/share/nucypher:/root/.local/share/nucypher \
-v ~/.ethereum/:/root/.ethereum \
nucypher/nucypher:latest \
nucypher bond \
--signer <ETH KEYSTORE URI> \
--network <NETWORK NAME> \
--eth-provider <L1 PROVIDER URI> \
--staking-provider <STAKING PROVIDER ADDRESS> \
--operator-address <OPERATOR ADDRESS>
Are you sure you want to bond staking provider 0x... to operator 0x...? [y/N]: y
Enter ethereum account password (0x...):
Bonding operator 0x...
Broadcasting BONDOPERATOR Transaction ...
TXHASH 0x...
OK | 0x...
Block #14114221 | 0x...
See https://etherscan.io/tx/0x...
Replace the following values with your own:
* ``<ETH KEYSTORE URI>`` - The local ethereum keystore (e.g. ``keystore:///root/.ethereum/keystore`` for mainnet)
* ``<NETWORK NAME>`` - The name of the PRE network (mainnet, tapir, or lynx)
* ``<L1 PROVIDER URI>`` - The URI of a local or hosted ethereum node (infura/geth, e.g. ``https://infura.io/…``)
* ``<STAKING PROVIDER ADDRESS>`` - the ethereum address of the staking provider
* ``<OPERATOR ADDRESS>`` - the address of the operator to bond
via Local Installation
----------------------
.. code:: bash
(nucypher)$ nucypher bond --signer <ETH KEYSTORE URI> --network <NETWORK NAME> --eth-provider <L1 PROVIDER URI> --staking-provider <STAKING PROVIDER ADDRESS> --operator-address <OPERATOR ADDRESS>
Are you sure you want to bond staking provider 0x... to operator 0x...? [y/N]: y
Enter ethereum account password (0x...):
Bonding operator 0x...
Broadcasting BONDOPERATOR Transaction ...
TXHASH 0x...
OK | 0x...
Block #14114221 | 0x...
See https://etherscan.io/tx/0x...
Replace the following values with your own:
* ``<ETH KEYSTORE URI>`` - The local ethereum keystore (e.g. ``keystore:///home/<user>/.ethereum/keystore`` for mainnet)
* ``<NETWORK NAME>`` - The name of the PRE network (mainnet, tapir, or lynx)
* ``<L1 PROVIDER URI>`` - The URI of a local or hosted ethereum node (infura/geth, e.g. ``https://infura.io/…``)
* ``<STAKING PROVIDER ADDRESS>`` - the ethereum address of the staking provider
* ``<OPERATOR ADDRESS>`` - the address of the operator to bond
.. _configure-and-run-node:
Configure and Run a PRE Node
============================
Node management commands are issued via the ``nucypher ursula`` CLI (directly or as part of a Docker command). For more information
on that command you can run ``nucypher ursula –help``.
Initializing the PRE node configuration entails:
- Creation of a nucypher-specific keystore to store private encryption keys used
by the node, which will be protected by a user-specified password.
.. important::
This is not to be confused with an ethereum keystore - which stores ethereum account private keys.
- Creation of a persistent node configuration file called ``ursula.json``. This file will be written to disk and contains the various runtime configurations for the node.
All PRE node configuration information will be stored in ``/home/user/.local/share/nucypher/`` by default.
.. _run-ursula-with-docker:
Run Node via Docker (Recommended)
---------------------------------
This section is specific to :ref:`Docker installations <docker-installation>` of ``nucypher``. The Docker commands will ensure that configuration
information in the local ``/home/user/.local/share/nucypher/`` is used by the Docker container.
Export Node Environment Variables
+++++++++++++++++++++++++++++++++
These environment variables are used to better simplify the Docker installation process.
.. code:: bash
# Password used for creation / update of nucypher keystore
$ export NUCYPHER_KEYSTORE_PASSWORD=<YOUR NUCYPHER KEYSTORE PASSWORD>
# Password used to unlock node eth account
$ export NUCYPHER_OPERATOR_ETH_PASSWORD=<YOUR OPERATOR ETH ACCOUNT PASSWORD>
Initialize Node Configuration
+++++++++++++++++++++++++++++
This step creates and stores the PRE node configuration, and only needs to be run once.
.. code:: bash
$ docker run -it --rm \
--name ursula \
-v ~/.local/share/nucypher:/root/.local/share/nucypher \
-v ~/.ethereum/:/root/.ethereum \
-p 9151:9151 \
-e NUCYPHER_KEYSTORE_PASSWORD \
nucypher/nucypher:latest \
nucypher ursula init \
--signer <ETH KEYSTORE URI> \
--eth-provider <L1 PROVIDER URI> \
--network <L1 NETWORK NAME> \
--payment-provider <L2 PROVIDER URI> \
--payment-network <L2 NETWORK NAME> \
--operator-address <OPERATOR ADDRESS> \
--max-gas-price <GWEI>
Replace the following values with your own:
* ``<ETH KEYSTORE URI>`` - The local ethereum keystore (e.g. ``keystore:///root/.ethereum/keystore`` for mainnet)
* ``<L1 PROVIDER URI>`` - The URI of a local or hosted ethereum node (infura/geth, e.g. ``https://infura.io/…``)
* ``<L1 NETWORK NAME>`` - The name of the PRE network (mainnet, tapir, or lynx)
* ``<L2 PROVIDER URI>`` - The URI of a local or hosted level-two node (infura/bor)
* ``<L2 NETWORK NAME>`` - The name of a payment network (polygon or mumbai)
* ``<OPERATOR ADDRESS>`` - The local ETH address to be used by the Ursula node (the one that was bonded)
* ``<GWEI>`` (*Optional*) - The maximum price of gas to spend on any transaction
Launch the Node
+++++++++++++++
This step starts the PRE node.
.. code:: bash
$ docker run -d --rm \
--name ursula \
--restart on-failure \
-v ~/.local/share/nucypher:/root/.local/share/nucypher \
-v ~/.ethereum/:/root/.ethereum \
-p 9151:9151 \
-e NUCYPHER_KEYSTORE_PASSWORD \
-e NUCYPHER_OPERATOR_ETH_PASSWORD \
nucypher/nucypher:latest \
nucypher ursula run
.. note::
Setting the ``--restart`` parameter to ``on-failure`` ensures that the Docker
container will be automatically restarted if the application exited unexpectedly (e.g. an application crash).
See `Docker Restart Policies <https://docs.docker.com/engine/reference/run/#restart-policies---restart>`_
for more information.
View Node Logs
++++++++++++++
.. code:: bash
$ docker logs -f ursula
Upgrade the Node To a Newer Version
+++++++++++++++++++++++++++++++++++
.. code:: bash
# stop docker container
$ docker stop ursula
# pull latest docker image
$ docker pull nucypher/nucypher:latest
# start node (same aforementioned run command)
$ docker run …
Run Node without Docker
-----------------------
Instead of using Docker, PRE nodes can be run using a :ref:`local installation<local-installation>` of ``nucypher``.
Run Node via systemd (Alternate)
++++++++++++++++++++++++++++++++
The node can be run as a `systemd <https://en.wikipedia.org/wiki/Systemd>`_ service.
Configure the node
~~~~~~~~~~~~~~~~~~
.. code:: bash
$(nucypher) nucypher ursula init \
--signer <ETH KEYSTORE URI> \
--eth-provider <L1 PROVIDER URI> \
--network <L1 NETWORK NAME> \
--payment-provider <L2 PROVIDER URI> \
--payment-network <L2 NETWORK NAME> \
--operator-address <OPERATOR ADDRESS> \
--max-gas-price <GWEI>
Replace the following values with your own:
* ``<ETH KEYSTORE URI>`` - The local ethereum keystore (e.g. ``keystore:///home/<user>/.ethereum/keystore`` for mainnet)
* ``<L1 PROVIDER URI>`` - The URI of a local or hosted ethereum node (infura/geth, e.g. ``https://infura.io/…``)
* ``<L1 NETWORK NAME>`` - The name of the PRE network (mainnet, tapir, or lynx)
* ``<L2 PROVIDER URI>`` - The URI of a local or hosted level-two node (infura/bor)
* ``<L2 NETWORK NAME>`` - The name of a payment network (polygon or mumbai)
* ``<OPERATOR ADDRESS>`` - The local ETH address to be used by the Ursula node (the one that was bonded)
* ``<GWEI>`` (*Optional*) - The maximum price of gas to spend on any transaction
Create Node Service Template
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create a file named ``ursula.service`` in ``/etc/systemd/system``, and add this template to it
.. code:: bash
[Unit]
Description="Ursula, a PRE Node."
[Service]
User=<YOUR USERNAME>
Type=simple
Restart=on-failure
Environment="NUCYPHER_OPERATOR_ETH_PASSWORD=<YOUR OPERATOR ADDRESS PASSWORD>"
Environment="NUCYPHER_KEYSTORE_PASSWORD=<YOUR PASSWORD>"
ExecStart=<VIRTUALENV PATH>/bin/nucypher ursula run
[Install]
WantedBy=multi-user.target
Replace the following values with your own:
- ``<YOUR USER>`` - The host system’s username to run the process with (best practice is to use a dedicated user)
- ``<YOUR OPERATOR ADDRESS PASSWORD>`` - Operator’s ETH account password
- ``<YOUR PASSWORD>`` - ``nucypher`` keystore password
- ``<VIRTUALENV PATH>`` - The absolute path to the python virtual environment containing the ``nucypher`` executable.
Run ``pipenv –venv`` within the virtual environment to get the virtual environment path.
.. note::
Setting the ``Restart`` option to ``on-failure``, ensures that the systemd service
will be automatically restarted if it exited with a non-zero exit code, except if
the container was stopped using the ``systemctl stop`` command. See
`Systemd Restart <https://www.freedesktop.org/software/systemd/man/systemd.service.html#Restart=>`_
for more information.
Enable Node Service
~~~~~~~~~~~~~~~~~~~
.. code:: bash
$ sudo systemctl enable ursula
Run Node Service
~~~~~~~~~~~~~~~~
.. code:: bash
$ sudo systemctl start ursula
Check Node Service Status
~~~~~~~~~~~~~~~~~~~~~~~~~
.. code:: bash
# Application Logs
$ tail -f ~/.local/share/nucypher/nucypher.log
# Systemd status
$ systemctl status ursula
# Systemd Logs
$ journalctl -f -t ursula
Restart Node Service
~~~~~~~~~~~~~~~~~~~~
.. code:: bash
$ sudo systemctl restart ursula
Run Node Manually
+++++++++++++++++
Configure the Node
~~~~~~~~~~~~~~~~~~
If you’d like to use another own method of running the Node's process in the
background,, here is how to run Ursula using the CLI directly.
First initialize a Node configuration:
.. code:: bash
$(nucypher) nucypher ursula init \
--signer <ETH KEYSTORE URI> \
--eth-provider <L1 PROVIDER URI> \
--network <L1 NETWORK NAME> \
--payment-provider <L2 PROVIDER URI> \
--payment-network <L2 NETWORK NAME> \
--operator-address <OPERATOR ADDRESS> \
--max-gas-price <GWEI>
Replace the following values with your own:
* ``<ETH KEYSTORE URI>`` - The local ethereum keystore (e.g. ``keystore:///home/<user>/.ethereum/keystore`` for mainnet)
* ``<L1 PROVIDER URI>`` - The URI of a local or hosted ethereum node (infura/geth, e.g. ``https://infura.io/…``)
* ``<L1 NETWORK NAME>`` - The name of the PRE network (mainnet, tapir, or lynx)
* ``<L2 PROVIDER URI>`` - The URI of a local or hosted level-two node (infura/bor)
* ``<L2 NETWORK NAME>`` - The name of a payment network (polygon or mumbai)
* ``<OPERATOR ADDRESS>`` - The local ETH address to be used by the Ursula node (the one that was bonded)
* ``<GWEI>`` (*Optional*) - The maximum price of gas to spend on any transaction
Run the Node
.. code:: bash
$ nucypher ursula run
.. _qualify-node:
Qualify Node
============
Nodes must be fully qualified: funded with ETH and bonded to an operator address,
in order to fully start. Nodes that are launched before qualification will
pause until they have a balance greater than 0 ETH, and are bonded to an
Operator address. Once both of these requirements are met, the node will
automatically continue startup.
Waiting for qualification:
.. code:: bash
Defaulting to Ursula configuration file: '/root/.local/share/nucypher/ursula.json'
Authenticating Ursula
Starting services
ⓘ Operator startup is paused. Waiting for bonding and funding ...
ⓘ Operator startup is paused. Waiting for bonding and funding ...
ⓘ Operator startup is paused. Waiting for bonding and funding …
Continuing startup after funding and bonding:
.. code:: bash
...
ⓘ Operator startup is paused. Waiting for bonding and funding ...
✓ Operator is funded with 0.641160744670608582 ETH
✓ Operator 0x2507beC003324d1Ec7F42Cc03B95d213D2E0b238 is bonded to staking provider 0x4F29cC79B52DCc97db059B0E11730F9BE98F1959
✓ Operator already confirmed. Not starting worktracker.
...
✓ Rest Server https://1.2.3.4:9151
Working ~ Keep Ursula Online!
.. _manage-node:
Node Management
===============
Update Node Configuration
-------------------------
These configuration settings will be stored in an ursula configuration file, ``ursula.json``, stored
in ``/home/user/.local/share/nucypher`` by default.
All node configuration values can be modified using the config command, ``nucypher ursula config``
.. code:: bash
$ nucypher ursula config --<OPTION> <NEW VALUE>
# Usage
$ nucypher ursula config –help
# Update the max gas price setting
$ nucypher ursula config --max-gas-price <GWEI>
# Change the Ethereum provider to use
nucypher ursula config --eth-provider <ETH PROVIDER URI>
# Accept payments for service using the SubscriptionManager contract on polygon/mumbai
nucypher ursula config --payment-method SubscriptionManager --payment-network mumbai
# View the current configuration
nucypher ursula config
#
# Non-default configuration file path
#
# View the current configuration of a non-default configuration file path
nucypher ursula config --config-file <CONFIG PATH>
# Update the max gas price setting of a non-default configuration file path
nucypher ursula config --config-file <CONFIG PATH> --eth-provider <ETH PROVIDER URI>
.. important::
The node must be restarted for any configuration changes to take effect.
Node Status
-----------
Node Logs
+++++++++
A reliable way to check the status of a node is to view the logs.
* View logs for a Docker-launched Ursula:
.. code:: bash
$ docker logs -f ursula
* View logs for a systemd or CLI-launched Ursula:
.. code:: bash
# Systemd Logs
journalctl -f -t ursula
# Application Logs
tail -f ~/.local/share/nucypher/nucypher.log
Node Status Page
++++++++++++++++
Once the node is running, you can view its public status page at ``https://<node_ip>:9151/status``.
.. image:: ../.static/img/Annotated-Ursula-Status-Webpage-v2.svg
:target: ../.static/img/Annotated-Ursula-Status-Webpage-v2.svg
- *Nickname Icon* - A visual representation of the node's nickname words and colors
- *Staking Provider Nickname* - A nickname/codename for the node derived from the Staking Provider address
- *Staking Provider Address* - The Staking Provider address this node is bonded to
- *Client Version* - The version of nucypher this node is running
- *Network Name* - The network this node is running on (mainnet, lynx, or tapir).
- *Peer Count* - The total number of peers this node has discovered.
- *Fleet State Checksum* - A checksum representing all currently known peers
- *Fleet State Icon* - A visual representation of the fleet state's checksum word and color
- *Fleet State History* - The most recent historical fleet states known by this node, sorted from most recent to oldest
- *Peer Nickname* - The nickname of a peer derived from it's Staking Provider address
- *Peer Fleet State* - The current fleet state of a peer node
- *Peer Staking Provider Address* - The Staking Provider address of a peer
- *Verified Nodes* - The collection of nodes that have been and validated by this node (valid metadata and staking status)
- *Unverified Nodes* - The collection of nodes that have not been contacted or validated by this node

164
docs/source/references/cli_reference.rst
View File

@ -1,164 +0,0 @@
==============
CLI Reference
==============
Ursula
------
"Ursula the Untrusted" PRE Re-encryption node management commands.
.. code:: bash
(nucypher)$ nucypher ursula ACTION [OPTIONS]
**Ursula Command Actions**
+--------------------------+---------------------------------------------------------------------+
| Action | Description |
+==========================+=====================================================================+
| ``init`` | Create a brand new persistent Ursula. |
+--------------------------+---------------------------------------------------------------------+
| ``config`` | View and optionally update an existing Ursula's configuration. |
+--------------------------+---------------------------------------------------------------------+
| ``destroy`` | Delete existing Ursula's configuration. |
+--------------------------+---------------------------------------------------------------------+
| ``forget`` | Delete all stored peer metadata. |
+--------------------------+---------------------------------------------------------------------+
| ``save-metadata`` | Manually write node metadata to disk without running. |
+--------------------------+---------------------------------------------------------------------+
| ``run`` | Start Ursula. |
+--------------------------+---------------------------------------------------------------------+
Bond
----
Bond an Operator to a Staking Provider. The Staking Provider must be authorized to use the PREApplication.
.. code:: bash
(nucypher)$ nucypher bond [OPTIONS]
Unbond
------
Unbonds an operator from an authorized Staking Provider.
.. code:: bash
(nucypher)$ nucypher unbond [OPTIONS]
Enrico
-------
"Enrico the Encryptor" management commands.
.. code:: bash
(nucypher)$ nucypher enrico ACTION [OPTIONS]
**Enrico Command Actions**
+--------------------------+-------------------------------------------------------------------------------+
| Action | Description |
+==========================+===============================================================================+
| ``encrypt`` | Encrypt a message under a given policy public key. |
+--------------------------+-------------------------------------------------------------------------------+
| ``run`` | Start Enrico's HTTP controller. |
+--------------------------+-------------------------------------------------------------------------------+
Status
------
Echo a snapshot of live PRE Application metadata.
.. code:: bash
(nucypher)$ nucypher status ACTION [OPTIONS]
**Status Command Actions**
+--------------------------+---------------------------------------------------------------------+
| Action | Description |
+==========================+=====================================================================+
| ``events`` | Show events associated to PRE Application contracts. |
+--------------------------+---------------------------------------------------------------------+
Alice
-----
"Alice the Policy Authority" management commands.
.. code:: bash
(nucypher)$ nucypher alice ACTION [OPTIONS]
**Alice Command Actions**
+--------------------------+-------------------------------------------------------------------------------+
| Action | Description |
+==========================+===============================================================================+
| ``init`` | Create a brand new persistent Alice. |
+--------------------------+-------------------------------------------------------------------------------+
| ``config`` | View and optionally update an existing Alice's configuration. |
+--------------------------+-------------------------------------------------------------------------------+
| ``destroy`` | Delete existing Alice's configuration. |
+--------------------------+-------------------------------------------------------------------------------+
| ``decrypt`` | Decrypt data encrypted using an Alice's policy encrypting key |
+--------------------------+-------------------------------------------------------------------------------+
| ``derive-policy-pubkey`` | Derive a policy public key from a policy label. |
+--------------------------+-------------------------------------------------------------------------------+
| ``grant`` | Create and enact an access policy for some Bob. |
+--------------------------+-------------------------------------------------------------------------------+
| ``make-card`` | Create a character card file for public key sharing. |
+--------------------------+-------------------------------------------------------------------------------+
| ``public-keys`` | Obtain Alice's public verification and encryption. |
+--------------------------+-------------------------------------------------------------------------------+
| ``revoke`` | Revoke a policy. |
+--------------------------+-------------------------------------------------------------------------------+
| ``run`` | Start Alice's HTTP controller. |
+--------------------------+-------------------------------------------------------------------------------+
Bob
---
"Bob the Data Recipient" management commands.
.. code:: bash
(nucypher)$ nucypher bob ACTION [OPTIONS]
**Bob Command Actions**
+--------------------------+-------------------------------------------------------------------------------+
| Action | Description |
+==========================+===============================================================================+
| ``init`` | Create a brand new persistent Bob. |
+--------------------------+-------------------------------------------------------------------------------+
| ``config`` | View and optionally update an existing Bob's configuration. |
+--------------------------+-------------------------------------------------------------------------------+
| ``destroy`` | Delete existing Bob's configuration. |
+--------------------------+-------------------------------------------------------------------------------+
| ``retrieve`` | Obtain plaintext from encrypted data, if access was granted. |
+--------------------------+-------------------------------------------------------------------------------+
| ``make-card`` | Create a character card file for public key sharing. |
+--------------------------+-------------------------------------------------------------------------------+
| ``public-keys`` | Obtain Bob's public verification and encryption. |
+--------------------------+-------------------------------------------------------------------------------+
| ``run`` | Start Bob's HTTP controller. |
+--------------------------+-------------------------------------------------------------------------------+

51
docs/source/references/environment_variables.rst
View File

@ -1,51 +0,0 @@
Environment Variables
=====================
Environment variables are used for configuration in various areas of the codebase to facilitate automation. The
constants for these variables are available in ``nucypher.config.constants``.
Where applicable, values are evaluated in the following order of precedence:
#. CLI parameter
#. Environment variable
#. Configuration file
#. Optional default in code
General
-------
* `NUCYPHER_KEYSTORE_PASSWORD`
Password for the `nucypher` Keystore.
* `NUCYPHER_ETH_PROVIDER_URI`
Default Web3 node provider URI.
* `NUCYPHER_STAKING_PROVIDERS_PAGINATION_SIZE`
Default pagination size for the maximum number of active staking providers to retrieve from PREApplication in
one contract call.
* `NUCYPHER_STAKING_PROVIDERS_PAGINATION_SIZE_LIGHT_NODE`
Default pagination size for the maximum number of active staking providers to retrieve from PREApplication in
one contract call when a light node provider is being used.
* `NUCYPHER_STAKING_PROVIDER_ETH_PASSWORD`
Password for a staking provider's Keystore.
Alice
-----
* `NUCYPHER_ALICE_ETH_PASSWORD`
Password for Ethereum account used by Alice.
Bob
----
* `NUCYPHER_BOB_ETH_PASSWORD`
Password for Ethereum account used by Bob.
Ursula (Operator)
-----------------
* `NUCYPHER_OPERATOR_ADDRESS`
Ethereum account used by Ursula.
* `NUCYPHER_OPERATOR_ETH_PASSWORD`
Password for Ethereum account used by Ursula (Operator).

93
docs/source/references/installation.rst
View File

@ -1,93 +0,0 @@
Installation Reference
======================
``nucypher`` can be run either from a docker container or via local installation. Running ``nucypher``
via a docker container simplifies the installation process and negates the need for a local installation.
.. _docker-installation:
Docker Installation and Update
------------------------------
#. Install `Docker <https://docs.docker.com/install/>`_
#. *Optional* Depending on the setup you want, post install instructions, additional
docker configuration is available `here <https://docs.docker.com/engine/install/linux-postinstall/>`_.
#. Get the latest nucypher image:
.. code:: bash
docker pull nucypher/nucypher:latest
.. _local-installation:
Local Installation
------------------
``nucypher`` supports Python 3.8, 3.9, 3.10, and 3.11. If you don’t already have it, install `Python <https://www.python.org/downloads/>`_.
In order to isolate global system dependencies from nucypher-specific dependencies, we *highly* recommend
using ``python-virtualenv`` to install ``nucypher`` inside a dedicated virtual environment.
For full documentation on virtualenv see: https://virtualenv.pypa.io/en/latest/:
#. Create a Virtual Environment
Create a virtual environment in a folder somewhere on your machine.This virtual
environment is a self-contained directory tree that will contain a python
installation for a particular version of Python, and various installed packages needed to run the node.
.. code-block:: bash
$ python -m venv /your/path/nucypher-venv
...
#. Activate the newly created virtual environment:
.. code-block:: bash
$ source /your/path/nucypher-venv/bin/activate
...
(nucypher-venv)$
A successfully activated virtual environment is indicated by ``(nucypher-venv)$`` prepended to your console's prompt
.. note::
From now on, if you need to execute any ``nucypher`` commands you should do so within the activated virtual environment.
#. Install/Update the ``nucypher`` package
.. code-block:: bash
(nucypher-venv)$ pip3 install -U nucypher
#. Verify Installation
Before continuing, verify that your ``nucypher`` installation and entry points are functional.
Activate your virtual environment, if not activated already:
.. code-block:: bash
$ source /your/path/nucypher-venv/bin/activate
Next, verify ``nucypher`` is importable. No response is successful, silence is golden:
.. code-block:: bash
(nucypher-venv)$ python -c "import nucypher"
Then, run the ``nucypher --help`` command:
.. code-block:: bash
(nucypher-venv)$ nucypher --help
...
If successful you will see a list of possible usage options (\ ``--version``\ , ``--config-path``\ , ``--logging-path``\ , etc.) and
commands (\ ``status``\ , ``ursula``\ , etc.).

83
docs/source/references/network_events.rst
View File

@ -1,83 +0,0 @@
PRE Application Events
======================
When there is an interaction with PRE Application smart contracts, various on-chain events are emitted. These events are
queryable via the ``nucypher status events``
CLI command, and allows for any PRE Application event to be queried.
Querying Events
---------------
Since the number of events returned may be large, by default the query is limited to events within block numbers for the
current period. However, this is configurable using the ``--from-block`` option.
.. important::
Depending on the Ethereum provider being used, the number of results a query is allowed to return may be limited.
For example, on Infura this limit is currently 10,000.
For a full list of CLI options, run:
.. code::
$ nucypher status events --help
Event Filters
-------------
To aid with query limits and more specific queries, events can be filtered using the ``--event-filter``
option. Multiple ``--event-filter`` options can be defined, but note that only properties classified
as ``indexed`` in the event's solidity definition can be used as a filter.
The event filter can be defined as follows, ``--event-filter <PARAMETER_NAME>=<FILTER_VALUE>``.
Legacy Events
-------------
To query for events related to the NuCypher Network prior to the merge to Threshold Network,
e.g. ``CommitmentMade`` or ``Minted``, use the ``--legacy`` flag.
For example, to view all of the legacy NuCypher Network commitments ever made by the node associated with a specific Staker run:
.. code::
$ nucypher status events --legacy --eth-provider <ETH PROVIDER URI> --contract-name StakingEscrow --event-name CommitmentMade --event-filter staker=<STAKING_ADDRESS> --from-block 0
Reading Latest Chaindata...
Retrieving events from block 0 to latest
--------- StakingEscrow Events ---------
CommitmentMade:
- (EventRecord) staker: <STAKER_ADDRESS>, period: 18551, value: 1234567890123456789012, block_number: 11057641
- (EventRecord) staker: <STAKER_ADDRESS>, period: 18552, value: 1234567890123456789012, block_number: 11063640
- (EventRecord) staker: <STAKER_ADDRESS>, period: 18553, value: 1234567890123456789012, block_number: 11070103
- (EventRecord) staker: <STAKER_ADDRESS>, period: 18554, value: 1234567890123456789012, block_number: 11076964
...
CSV Output
----------
CLI output can be cumbersome when trying to generate insights and correlate different events. Instead, the event
data can be written to a CSV file using either of the following command-line options:
* ``--csv`` - flag to write event information to default CSV files in the current directory with default filenames
* ``--csv-file <FILEPATH>`` - write event information to a specific CSV file at the provided filepath
.. note::
If there were no events found, a CSV file is not written to.
.. important::
When using the ``--csv-file`` option, since different events can have different
properties, the ``--event-name`` and ``--contract-name`` options must be specified. If querying for multiple
events at the same time i.e. running the command without ``--event-name``, the ``--csv`` option should be used
to generate separate default filenames for the different events.

704
docs/source/release_notes/releases.rst
View File

@ -1,704 +0,0 @@
========
Releases
========
.. towncrier release notes start
v6.1.0 (2022-05-10)
-------------------
Features
~~~~~~~~
- SSL Certificate fetching and Porter optimizations
- Middleware should try cached SSL certification for a node first, and then if the requests fails, fetch the node's up-to-date SSL cert
- Short-circuit WorkerPool background execution once sufficient successful executions occur
- Don't limit WorkerPool size; this has consequences when smaller samples of ursulas are performed; allow threadpool to be flexible by using default min/max
- Return more comprehensive error information for failed WorkerPool execution (`#2908 <https://github.com/nucypher/nucypher/issues/2908>`__)
Bugfixes
~~~~~~~~
- Fix Porter sampling check that ensures Ursula is reachable to be more comprehensive; previously an unreachable Ursula could still be deemed as reachable. (`#2888 <https://github.com/nucypher/nucypher/issues/2888>`__)
- Only print relevant network options when running `nucypher ursula init` (`#2917 <https://github.com/nucypher/nucypher/issues/2917>`__)
- Retrieve contract registries from the ``development`` branch on GitHub instead of ``main``. (`#2924 <https://github.com/nucypher/nucypher/issues/2924>`__)
- Properly support event retrieval for the PREApplication contract.
Remove invalid support for SubscriptionManager contract - proper support will be
added in a future release. (`#2934 <https://github.com/nucypher/nucypher/issues/2934>`__)
Improved Documentation
~~~~~~~~~~~~~~~~~~~~~~
- Remove references to ``cloudworkers`` CLI command, and update bond operator to reference UI. (`#2896 <https://github.com/nucypher/nucypher/issues/2896>`__)
- Updated examples and demos for usage on polygon/mainnet. (`#2897 <https://github.com/nucypher/nucypher/issues/2897>`__)
- Updates to nucypher-ops guides for mainnet usage (`#2916 <https://github.com/nucypher/nucypher/issues/2916>`__)
Misc
~~~~
- Dependency updates - Tests target the london fork. (`#2837 <https://github.com/nucypher/nucypher/issues/2837>`__)
- Creation of 'oryx' PRE testnet on Ropsten. (`#2893 <https://github.com/nucypher/nucypher/issues/2893>`__)
- Add more color to cli output (`#2909 <https://github.com/nucypher/nucypher/issues/2909>`__)
- Add a pre-commit hook and github action for `Darker <https://github.com/akaihola/darker>`_ to ensure all future changes conform to black and isort. (`#2921 <https://github.com/nucypher/nucypher/issues/2921>`__)
- Bump ``nucypher-core`` dependency to 0.2 (`#2927 <https://github.com/nucypher/nucypher/issues/2927>`__)
- Show error message when ``--prometheus`` flag is used since functionality not currently supported. Prometheus
monitoring functionality will be revamped in a subsequent release. (`#2929 <https://github.com/nucypher/nucypher/issues/2929>`__)
- Removes [docs] pip extra (`#2932 <https://github.com/nucypher/nucypher/issues/2932>`__)
v6.0.0 (2022-04-01)
-------------------
Features
~~~~~~~~
- Introduction of NuCypher Porter - a web-based service that performs ``nucypher`` protocol operations on behalf of applications for cross-platform functionality. (`#2664 <https://github.com/nucypher/nucypher/issues/2664>`__)
- Ursula no longer stores KFrags, instead Alice encrypts them inside the treasure map. Allow the KFrag generator and policy publisher to be different entities. (`#2687 <https://github.com/nucypher/nucypher/issues/2687>`__)
- Characters use mnemonic seed words to derive deterministic keystore, taking the place of the "keyring". (`#2701 <https://github.com/nucypher/nucypher/issues/2701>`__)
- Simplifies the retrieval protocol (see `#259 <https://github.com/nucypher/nucypher/issues/259>`_ for the discussion). ``PolicyMessageKit`` is renamed to ``MessageKit``. ``Bob.retrieve()`` is renamed to ``retrieve_and_decrypt()``, and its signature is simplified: it only requires the treasure map, Alice's verifying key, and the policy encrypting key. A lower-level ``Bob.retrieve()`` is added that does not decrypt, but only attempts to retrieve the capsule frags. (`#2730 <https://github.com/nucypher/nucypher/issues/2730>`__)
- Allow importing of secret key material for power derivations. (`#2742 <https://github.com/nucypher/nucypher/issues/2742>`__)
- Uniform versioning of bytes serializable protocol entities. (`#2767 <https://github.com/nucypher/nucypher/issues/2767>`__)
- Modify Porter REST endpoint from ``/exec_work_order`` to ``/retrieve_cfrags`` and modify request parameters for retrieval of re-encrypted data.
Update Bob ``/retrieve_and_decrypt`` REST endpoint to accept a list of message kits instead of only one - to match updated ``Bob.retrieve_and_decrypt`` Python API. (`#2768 <https://github.com/nucypher/nucypher/issues/2768>`__)
- Update WorkerPool error messages returned by Porter API. (`#2772 <https://github.com/nucypher/nucypher/issues/2772>`__)
- Adds ansible build/deploy for Monitor (status.nucypher.network) (`#2801 <https://github.com/nucypher/nucypher/issues/2801>`__)
- Extend brand size in ``Versioned`` to 4 bytes (`#2805 <https://github.com/nucypher/nucypher/issues/2805>`__)
- CORS, NGINX support for Porter:
- Added opt-in CORS origins support to Porter; no origins allowed by default when running Porter directly.
- Provided docker-compose execution for Porter to run behind an NGINX reverse proxy server - all origins allowed by default for CORS, but can be customized. NGINX allows for the potential for more complex infrastructure configurations. (`#2807 <https://github.com/nucypher/nucypher/issues/2807>`__)
- (`#2809 <https://github.com/nucypher/nucypher/issues/2809>`__)
- Halting NU inflation, now refund in WorkLock is possible without work (claim still needed) (`#2822 <https://github.com/nucypher/nucypher/issues/2822>`__)
- Updates to integrate NuCypher into Threshold Network (`#2824 <https://github.com/nucypher/nucypher/issues/2824>`__)
- Integrate StakingEscrow with Threshold Network's TokenStaking (`#2825 <https://github.com/nucypher/nucypher/issues/2825>`__)
- Removes snapshots logic from ``StakingEscrow`` (`#2831 <https://github.com/nucypher/nucypher/issues/2831>`__)
- Switched to Rust implementation of the protocol types (``nucypher-core``). Correspondingly, API has been simplified, and type requirements have been made more strict. (`#2832 <https://github.com/nucypher/nucypher/issues/2832>`__)
- Simple PRE application contract (`#2838 <https://github.com/nucypher/nucypher/issues/2838>`__)
- Renames operator to staking provider and worker to operator (`#2851 <https://github.com/nucypher/nucypher/issues/2851>`__)
- Modifies Ursulas for usage as Operators on the Threshold Network's PRE Application. (`#2857 <https://github.com/nucypher/nucypher/issues/2857>`__)
- - Full support of policy payments sumitted to polygon in demos and top-level APIs.
- Improved certificate handling for network requests.
- Prioritizes in-memory node storage for all node runtimes. (`#2873 <https://github.com/nucypher/nucypher/issues/2873>`__)
- Updated nucypher-core to 0.1 (`#2883 <https://github.com/nucypher/nucypher/issues/2883>`__)
- Proactively shut down Ursula if it is no longer bonded to any staking provider. (`#2886 <https://github.com/nucypher/nucypher/issues/2886>`__)
- Include polygon/matic contract registry for mainnet. (`#2894 <https://github.com/nucypher/nucypher/issues/2894>`__)
Bugfixes
~~~~~~~~
- (`#2727 <https://github.com/nucypher/nucypher/issues/2727>`__)
- Cloudworkers: ignore errors on stopping of ursula containers (`#2728 <https://github.com/nucypher/nucypher/issues/2728>`__)
- Fixed a problem with node metadata being stored to a file with an incorrect name (`#2748 <https://github.com/nucypher/nucypher/issues/2748>`__)
- Fixed failing transactions when gas price used is not an integer. (`#2753 <https://github.com/nucypher/nucypher/issues/2753>`__)
- Stop writing bytes to log file which causes exceptions - instead write the hex representation. (`#2762 <https://github.com/nucypher/nucypher/issues/2762>`__)
- ``StakingEscrow.partition_stakers_by_activity()`` no longer includes stakers with expired stakes in the ``missing_stakers`` value returned, thereby no longer overstating the number of inactive stakers. (`#2764 <https://github.com/nucypher/nucypher/issues/2764>`__)
- force pull latest tagged image on external geth deployment (`#2766 <https://github.com/nucypher/nucypher/issues/2766>`__)
- Minor memory improvement when collecting staker/worker metrics for prometheus. (`#2785 <https://github.com/nucypher/nucypher/issues/2785>`__)
- Fix bug when generating file for output of events from status & stake cli commands. (`#2786 <https://github.com/nucypher/nucypher/issues/2786>`__)
- Only use public data to generate keystore IDs and filenames. (`#2800 <https://github.com/nucypher/nucypher/issues/2800>`__)
- Fixed WebController bug caused by Path object for TLS/certificate path provided to Hendrix instead of a string. (`#2807 <https://github.com/nucypher/nucypher/issues/2807>`__)
- Avoid crashing the learning loop if there is a problem in the metadata returned by seed nodes. (`#2815 <https://github.com/nucypher/nucypher/issues/2815>`__)
- Fixed a missing timestamp error when a node's status is requested before it participated in metadata exchange. (`#2819 <https://github.com/nucypher/nucypher/issues/2819>`__)
- Fixed a memory leak in Ursula: removed some teacher statistics accumulated over time, and limited the amount of old fleet states stored. (`#2820 <https://github.com/nucypher/nucypher/issues/2820>`__)
- Fixed some occurrences of the old term for ``shares`` (``n``) (`#2829 <https://github.com/nucypher/nucypher/issues/2829>`__)
- Fix an incorrect usage of node object in ``FleetSensor``. (`#2877 <https://github.com/nucypher/nucypher/issues/2877>`__)
- Fix runaway WorkTracker task that ensures operator confirmed transaction occurs but continues running and making web3 requests even after operator already confirmed. (`#2886 <https://github.com/nucypher/nucypher/issues/2886>`__)
Improved Documentation
~~~~~~~~~~~~~~~~~~~~~~
- Document how worker period commitment works. (`#2776 <https://github.com/nucypher/nucypher/issues/2776>`__)
- Update documentation to reflect new TreasureMap con KFrags design. (`#2833 <https://github.com/nucypher/nucypher/issues/2833>`__)
- Overhaul NuCypher documentation to accommodate the new PRE Application / Threshold Network paradigm. (`#2870 <https://github.com/nucypher/nucypher/issues/2870>`__)
- Add documentation about bonding an operator to a staking provider. (`#2874 <https://github.com/nucypher/nucypher/issues/2874>`__)
- Embed Threshold Network videos within docs. (`#2882 <https://github.com/nucypher/nucypher/issues/2882>`__)
Deprecations and Removals
~~~~~~~~~~~~~~~~~~~~~~~~~
- Renames enviorment variable `NUCYPHER_KEYRING_PASSWORD` to `NUCYPHER_KEYSTORE_PASSWORD` (`#2701 <https://github.com/nucypher/nucypher/issues/2701>`__)
- ``m`` and ``n`` parameters can no longer be used in character control and Python API; ``--m`` and ``--n`` are no longer supported by the CLI (``-m`` and ``-n`` still are; the long versions are now ``--threshold`` and ``--shares``) (`#2774 <https://github.com/nucypher/nucypher/issues/2774>`__)
- Removal of treasure map storage functionality and supporting publication APIs from the decentralized network.
Encrypted treasure maps must be obtained from side channels instead of Ursulas on the network (unless cached). (`#2780 <https://github.com/nucypher/nucypher/issues/2780>`__)
- Remove an unused method of ``Amonia`` (deprecated since we do not store the treasure map on Ursulas anymore) (`#2804 <https://github.com/nucypher/nucypher/issues/2804>`__)
- Removes the Arrangement API for Alice/Ursula negotiations. Use a simple livliness check during grant-time. (`#2808 <https://github.com/nucypher/nucypher/issues/2808>`__)
- Retires and removes eth/token faucet. (`#2848 <https://github.com/nucypher/nucypher/issues/2848>`__)
- Remove NuCypher DAO specific code since we are now the Threshold DAO. (`#2864 <https://github.com/nucypher/nucypher/issues/2864>`__)
- Removes 'cloudworkers' CLI command in favor of nucypher-ops. (`#2895 <https://github.com/nucypher/nucypher/issues/2895>`__)
Misc
~~~~
- Switch to PyUmbral 0.2 and adjust its usage according to the changed API. (`#2612 <https://github.com/nucypher/nucypher/issues/2612>`__)
- Add disclaimers to ``nucypher stake increase`` and ``nucypher stake merge`` CLI operations to provide warning about
potential reduced rewards for the first period after stake increase due to a known bug, and the workaround. (`#2693 <https://github.com/nucypher/nucypher/issues/2693>`__)
- Added a more informative error message for ``WorkerPool`` exceptions. (`#2744 <https://github.com/nucypher/nucypher/issues/2744>`__)
- Separated Alice and Publisher roles internally and in relevant public APIs (`#2745 <https://github.com/nucypher/nucypher/issues/2745>`__)
- TreasureMap split into TreasureMap and EncryptedTreasureMap; external methods of Bob and Porter now take the latter, with the parameter named 'encrypted_treasure_map'. SignedTreasureMap is merged with TreasureMap. (`#2773 <https://github.com/nucypher/nucypher/issues/2773>`__)
- Changed the names of ``m`` and ``n`` parameters to ``threshold`` and ``shares`` throughout the API. (`#2774 <https://github.com/nucypher/nucypher/issues/2774>`__)
- Extends policy probationary period until October 31st, 2021. No policies may be created on the network beyond this date. (`#2779 <https://github.com/nucypher/nucypher/issues/2779>`__)
- Umbral dependency bumped to v0.3.0 (`#2798 <https://github.com/nucypher/nucypher/issues/2798>`__)
- Extracting protocol logic into an underlying layer and preparing to move it to Rust. Involves multiple ABI changes (in ``Arrangement``, ``MessageKit``, ``RevocationOrder``, ``EncryptedTreasureMap``, node metadata). In particular, old node metadata will be backward incompatible with the current version, since it now shares the versoning logic with other protocol objects. (`#2802 <https://github.com/nucypher/nucypher/issues/2802>`__)
- Move some cryptographic operations inside the Rust extension. Remove dependency on `umbral` and `coincurve`. (`#2850 <https://github.com/nucypher/nucypher/issues/2850>`__)
- Extend policy probationary period to 2022-6-16T23:59:59.0Z. (`#2873 <https://github.com/nucypher/nucypher/issues/2873>`__)
v5.3.3 (2021-11-24)
-------------------
Bugfixes
~~~~~~~~
- Fixed a memory leak in Ursula; removed some teacher statistics accumulated over time. (`#2826 <https://github.com/nucypher/nucypher/issues/2826>`__)
v5.3.2 (2021-10-15)
-------------------
Bugfixes
~~~~~~~~
- Regenerate Ursula TLS certificates if the become invalid, e.g. become expired. (`#2810 <https://github.com/nucypher/nucypher/issues/2810>`__)
Misc
~~~~
- Extend policy probationary period until December 31st, 2021. No policies may be created on the network that extend beyond this date. (`#2810 <https://github.com/nucypher/nucypher/issues/2810>`__)
v5.3.1 (2021-08-12)
-------------------
Bugfixes
~~~~~~~~
- **Hotfix** - removed Etherchain as a datafeed for now since its format was modified and caused the gas price calculation to fail. (`#2769 <https://github.com/nucypher/nucypher/issues/2769>`__)
v5.3.0 (2021-06-17)
-------------------
Features
~~~~~~~~
- PolicyManager: creating multiple policies in one tx (`#2619 <https://github.com/nucypher/nucypher/issues/2619>`__)
- Adds a new CLI command to show past and present staking rewards, "stake rewards show". (`#2634 <https://github.com/nucypher/nucypher/issues/2634>`__)
- Adds "https://closest-seed.nucypher.network" and "https://mainnet.nucypher.network" as a fallback teacher nodes for mainnet. (`#2657 <https://github.com/nucypher/nucypher/issues/2657>`__)
- Whitespaces in character nicknames are now implicitly replaced with an underscore ("_"). (`#2672 <https://github.com/nucypher/nucypher/issues/2672>`__)
- Added timestamp and date columns to csv output of "nucypher status events" command. (`#2680 <https://github.com/nucypher/nucypher/issues/2680>`__)
- Ursula will now check for active stakes on startup. (`#2688 <https://github.com/nucypher/nucypher/issues/2688>`__)
- Add sub-stake boost information to staking CLI. (`#2690 <https://github.com/nucypher/nucypher/issues/2690>`__)
Bugfixes
~~~~~~~~
- Fixed issues where failing transactions would result in incorrect token allowance and prevent creation of new stakes. (`#2673 <https://github.com/nucypher/nucypher/issues/2673>`__)
- examples/run_demo_ursula_fleet.py - Clean up each DB on shutdown. (`#2681 <https://github.com/nucypher/nucypher/issues/2681>`__)
- Fix a performance regression in ``FleetSensor`` where nodes were matured prematurely (pun not intended) (`#2709 <https://github.com/nucypher/nucypher/issues/2709>`__)
Improved Documentation
~~~~~~~~~~~~~~~~~~~~~~
- Include annotated description of the worker status page. (`#2665 <https://github.com/nucypher/nucypher/issues/2665>`__)
- Update service fee pricing to reflect correct per period rate since periods are now 7-days. (`#2677 <https://github.com/nucypher/nucypher/issues/2677>`__)
- Add documentation about calculation of staking rewards. (`#2690 <https://github.com/nucypher/nucypher/issues/2690>`__)
Deprecations and Removals
~~~~~~~~~~~~~~~~~~~~~~~~~
- Moves "stake collect-reward" to "stake rewards withdraw" command. (`#2634 <https://github.com/nucypher/nucypher/issues/2634>`__)
- Remove IndisputableEvidence (`#2699 <https://github.com/nucypher/nucypher/issues/2699>`__)
Misc
~~~~
- Registry for NuCypher DAO entities. (`#2426 <https://github.com/nucypher/nucypher/issues/2426>`__)
- Added code used to generate the DAO Proposal #1, for reference purposes. (`#2616 <https://github.com/nucypher/nucypher/issues/2616>`__)
- Improves password collection hints while running ``init`` commands. (`#2662 <https://github.com/nucypher/nucypher/issues/2662>`__)
- Extend policy probationary period until August 31st, 2021. No policies may be created on the network beyond this date. (`#2716 <https://github.com/nucypher/nucypher/issues/2716>`__)
v5.2.0 (2021-04-26)
-------------------
Features
~~~~~~~~
- CLI option --duration-periods renamed to --payment-periods. (`#2650 <https://github.com/nucypher/nucypher/issues/2650>`__)
Bugfixes
~~~~~~~~
- Fixed inability to update ursula configuration file due to the keyring not being instantiated - updated logic no longer needs keyring to be instantiated. (`#2660 <https://github.com/nucypher/nucypher/issues/2660>`__)
Misc
~~~~
- Extends policy probationary period until May 31st, 2021. No policies may be created on the network beyond this date. (`#2656 <https://github.com/nucypher/nucypher/issues/2656>`__)
v5.1.0 (2021-04-15)
-------------------
Features
~~~~~~~~
- Improve UX for character CLI when there are multiple configuration files:
- If there are multiple possible character configuration files prompt the user to choose
- If there is only one character configuration file, even if not the default filename, use lone configuration without prompting and print to CLI. (`#2617 <https://github.com/nucypher/nucypher/issues/2617>`__)
Bugfixes
~~~~~~~~
- Ensure that correct configuration filepath is displayed when initializing characters, and add hint about
using ``--config-file <FILE>`` for subsequent CLI commands if non-default filepath used. (`#2617 <https://github.com/nucypher/nucypher/issues/2617>`__)
v5.0.2 (2021-04-14)
-------------------
Bugfixes
~~~~~~~~
- Fixed incorrect use of genesis value for ``seconds_per_period`` when estimating block number based on period number - applies to prometheus metrics collection and ``nucypher status events``. (`#2646 <https://github.com/nucypher/nucypher/issues/2646>`__)
v5.0.1 (2021-04-14)
-------------------
No significant changes.
v5.0.0 (2021-04-14)
-------------------
Features
~~~~~~~~
- Increase period duration in contracts and handle migration of current stakes to new format. (`#2549 <https://github.com/nucypher/nucypher/issues/2549>`__)
- DAO proposal #1: Improve staker P/L by increasing period duration. (`#2594 <https://github.com/nucypher/nucypher/issues/2594>`__)
- Refinements for pool staking contract (`#2596 <https://github.com/nucypher/nucypher/issues/2596>`__)
- New standalone geth fullnode ansible playbook. (`#2624 <https://github.com/nucypher/nucypher/issues/2624>`__)
Bugfixes
~~~~~~~~
- Accommodate migrated period duration in CLI UX. (`#2614 <https://github.com/nucypher/nucypher/issues/2614>`__)
- cloudworkers more throughoughly cleans up diskspace before updates. (`#2618 <https://github.com/nucypher/nucypher/issues/2618>`__)
- Bob now accepts provider_uri as an optional parameter (`#2626 <https://github.com/nucypher/nucypher/issues/2626>`__)
- Add a default gas limit multiplier of 1.15 for all outgoing ETH transactions (`#2637 <https://github.com/nucypher/nucypher/issues/2637>`__)
Improved Documentation
~~~~~~~~~~~~~~~~~~~~~~
- Document staking smart contract API and the base staking pool implementation (``PoolingStakingContractV2``). (`#2597 <https://github.com/nucypher/nucypher/issues/2597>`__)
Misc
~~~~
- Change filepath delimiter to dot (".") in Card Storage API (`#2628 <https://github.com/nucypher/nucypher/issues/2628>`__)
- Use constant for loopback address across the codebase. (`#2629 <https://github.com/nucypher/nucypher/issues/2629>`__)
v4.8.2 (2021-03-25)
-------------------
Bugfixes
~~~~~~~~
- Fixes ethereum account selection with ambiguous source in CLI. (`#2615 <https://github.com/nucypher/nucypher/issues/2615>`__)
v4.8.1 (2021-03-24)
-------------------
Bugfixes
~~~~~~~~
- Add ``balance_eth``, ``balance_nu``, ``missing_commitments`` and ``last_committed_period`` to the ``/status`` REST endpoint. (`#2611 <https://github.com/nucypher/nucypher/issues/2611>`__)
v4.8.0 (2021-03-23)
-------------------
Features
~~~~~~~~
- Expanded features for staker and status CLI:
- Support substake inspection via `nucypher status stakers --substakes`.
- Automated transaction series for inactive substake removal.
- Display unlocked NU amount from stakers status.
- Handle replacement of stuck withdraw transactions with --replace. (`#2528 <https://github.com/nucypher/nucypher/issues/2528>`__)
- Support extended period migration by nodes via work tracker. (`#2607 <https://github.com/nucypher/nucypher/issues/2607>`__)
Bugfixes
~~~~~~~~
- Improved import error feedback and default ssh key path in cloudworkers. (`#2598 <https://github.com/nucypher/nucypher/issues/2598>`__)
- Support geth 1.10.x - Remove chainID from transaction payloads. (`#2603 <https://github.com/nucypher/nucypher/issues/2603>`__)
Improved Documentation
~~~~~~~~~~~~~~~~~~~~~~
- Document minimum approval and support requirements for NuCypher DAO. (`#2599 <https://github.com/nucypher/nucypher/issues/2599>`__)
Deprecations and Removals
~~~~~~~~~~~~~~~~~~~~~~~~~
- Deprecate worker IP address as environment variable (``NUCYPHER_WORKER_IP_ADDRESS``). (`#2583 <https://github.com/nucypher/nucypher/issues/2583>`__)
Misc
~~~~
- Adjust ``Ursula.status_info()`` API to make it easier for ``nucypher-monitor`` to collect data. (`#2574 <https://github.com/nucypher/nucypher/issues/2574>`__)
v4.7.1 (2021-03-02)
-------------------
Bugfixes
~~~~~~~~
- Fixed missing domain parameter causing Ursulas to fail on startup when prometheus is enabled. (`#2589 <https://github.com/nucypher/nucypher/issues/2589>`__)
v4.7.0 (2021-03-02)
-------------------
Features
~~~~~~~~
- New preferable base pooling contract (`#2544 <https://github.com/nucypher/nucypher/issues/2544>`__)
- The output of `nucypher stake events` can be written to a csv file for simpler staker accounting. (`#2548 <https://github.com/nucypher/nucypher/issues/2548>`__)
- Simplifies CLI usage with optional interactive collection of all CLI parameters used during grant, encrypt, and retrieve. (`#2551 <https://github.com/nucypher/nucypher/issues/2551>`__)
- Improved status codes and error messages for various PRE http endpoints (`#2562 <https://github.com/nucypher/nucypher/issues/2562>`__)
- `nucypher status events` can now use event filters and be output to a csv file for simpler accounting. (`#2573 <https://github.com/nucypher/nucypher/issues/2573>`__)
Bugfixes
~~~~~~~~
- Properly handles public TLS certificate restoration; Simplify Ursula construction. (`#2536 <https://github.com/nucypher/nucypher/issues/2536>`__)
- Update the call to ``estimateGas()`` according to the new ``web3`` API (`#2543 <https://github.com/nucypher/nucypher/issues/2543>`__)
- Ensure remote ethereum provider connection is automatically established with characters. Fixes default keyring filepath generation. (`#2550 <https://github.com/nucypher/nucypher/issues/2550>`__)
- Cache Alice's transacting power for later activation. (`#2555 <https://github.com/nucypher/nucypher/issues/2555>`__)
- Prevent process hanging in the cases when the main thread finishes before the treasure map publisher (`#2557 <https://github.com/nucypher/nucypher/issues/2557>`__)
Improved Documentation
~~~~~~~~~~~~~~~~~~~~~~
- Documentation overhaul with focus on staking node operation (`#2463 <https://github.com/nucypher/nucypher/issues/2463>`__)
- Expands Alice grant example using the python API. (`#2554 <https://github.com/nucypher/nucypher/issues/2554>`__)
Deprecations and Removals
~~~~~~~~~~~~~~~~~~~~~~~~~
- Deprecated StakingEscrow features to reduce code size: batch deposits, testContract flag, locking reStake.
Deployment of StakingEscrow is split in two steps: initial step with stub and final step after all contracts. (`#2518 <https://github.com/nucypher/nucypher/issues/2518>`__)
Misc
~~~~
- Refactor FleetSensor; add "/status/?omit_known_nodes=true" argument; prevent internal constants from leaking into the status page. (`#2352 <https://github.com/nucypher/nucypher/issues/2352>`__)
- WorkLock prometheus metrics are only collected on mainnet. (`#2546 <https://github.com/nucypher/nucypher/issues/2546>`__)
- Sister demo for Finnegan's wake for use on lynx/goerli testnet.
Alice and Bob API cleanup compelled by EthDenver 2021. (`#2560 <https://github.com/nucypher/nucypher/issues/2560>`__)
- Rework internal transaction signing API for improved thread saftey. (`#2572 <https://github.com/nucypher/nucypher/issues/2572>`__)
- new seed URL for mainnet seeds.nucypher.network
cloudworkers CLI updates (`#2576 <https://github.com/nucypher/nucypher/issues/2576>`__)
- Extends probationary period for policy creation in the network to 2021-04-30 23:59:59 UTC. (`#2585 <https://github.com/nucypher/nucypher/issues/2585>`__)
v4.6.0 (2021-01-26)
-------------------
Misc
~~~~
- Introduces the Lynx testnet, a more stable environment to learn how to use NuCypher and integrate it into other apps. (`#2537 <https://github.com/nucypher/nucypher/issues/2537>`__)
v4.5.4 (2021-01-22)
-------------------
Bugfixes
~~~~~~~~
- Fix wrong usage of net_version to identify the EthereumClient client chain. (`#2484 <https://github.com/nucypher/nucypher/issues/2484>`__)
- Use eth_chainId instead of net_version to maintain compatibility with geth. (`#2533 <https://github.com/nucypher/nucypher/issues/2533>`__)
- Fixed infinite loop during learning when timing out but known nodes exceeds target. (`#2534 <https://github.com/nucypher/nucypher/issues/2534>`__)
v4.5.3 (2021-01-18)
-------------------
Bugfixes
~~~~~~~~
- Ensure minimum number of available peers for fleet-sourced IP determination and better handling of default teacher unavailability scenarios on startup (`#2527 <https://github.com/nucypher/nucypher/issues/2527>`__)
v4.5.2 (2021-01-15)
-------------------
No significant changes.
v4.5.1 (2021-01-15)
-------------------
No significant changes.
v4.5.0 (2021-01-14)
-------------------
Features
~~~~~~~~
- Compare Ursula IP address with configuration values on startup to help ensure node availability. (`#2462 <https://github.com/nucypher/nucypher/issues/2462>`__)
- Arrangement proposals and policy enactment are performed in parallel, with more nodes being considered as some of the requests fail. This improves granting reliability. (`#2482 <https://github.com/nucypher/nucypher/issues/2482>`__)
Bugfixes
~~~~~~~~
- More logging added for arrangement proposal failures, and more suitable exceptions thrown. (`#2479 <https://github.com/nucypher/nucypher/issues/2479>`__)
- Ignore pending Ethereum transactions for purposes of gas estimation. (`#2486 <https://github.com/nucypher/nucypher/issues/2486>`__)
- Fix rtd build after #2477 (`#2489 <https://github.com/nucypher/nucypher/issues/2489>`__)
- (`#2491 <https://github.com/nucypher/nucypher/issues/2491>`__, `#2498 <https://github.com/nucypher/nucypher/issues/2498>`__)
- Fix rtd build after #2477 and #2489 (`#2492 <https://github.com/nucypher/nucypher/issues/2492>`__)
- cloudworkers bugfixes, cli args refactor and new "cloudworkers stop" feature. (`#2494 <https://github.com/nucypher/nucypher/issues/2494>`__)
- Gentler handling of unsigned stamps from stranger Ursulas on status endpoint (`#2515 <https://github.com/nucypher/nucypher/issues/2515>`__)
- Restore the re-raising behavior in ``BlockchainInterface._handle_failed_transaction()`` (`#2521 <https://github.com/nucypher/nucypher/issues/2521>`__)
Improved Documentation
~~~~~~~~~~~~~~~~~~~~~~
- Auto docs generation for smart contracts (`#2477 <https://github.com/nucypher/nucypher/issues/2477>`__)
- Add pricing protocol & economics paper to main repo readme and docs homepage. (`#2520 <https://github.com/nucypher/nucypher/issues/2520>`__)
Deprecations and Removals
~~~~~~~~~~~~~~~~~~~~~~~~~
- (`#2470 <https://github.com/nucypher/nucypher/issues/2470>`__)
- Deprecated manual worker commitments using the CLI. (`#2507 <https://github.com/nucypher/nucypher/issues/2507>`__)
Misc
~~~~
- Relock dependencies and update relock script. (`#2440 <https://github.com/nucypher/nucypher/issues/2440>`__)
- Fixed failing readthedocs build due to dependency mismatches in docs requirements. (`#2496 <https://github.com/nucypher/nucypher/issues/2496>`__)
- (`#2499 <https://github.com/nucypher/nucypher/issues/2499>`__)
- Ensure that documentation dependencies are updated when standard/development dependencies are updated. (`#2510 <https://github.com/nucypher/nucypher/issues/2510>`__)
v4.4.0 (2020-12-24)
-------------------
Features
~~~~~~~~
- Introduces "Character Cards" a serializable identity abstraction and 'nucypher contacts' CLI to support. (`#2115 <https://github.com/nucypher/nucypher/issues/2115>`__)
- - nucypher cloudworkers now contains a complete and comprehensive set of features for easily managing, backing up and restoring one to many workers (`#2365 <https://github.com/nucypher/nucypher/issues/2365>`__)
- New composite gas strategy that uses the median from three different gas price oracles
(currently, Etherchain, Upvest and gas-oracle.zoltu.io),
which behaves more robustly against sporadic errors in the oracles (e.g., spikes, stuck feeds). (`#2420 <https://github.com/nucypher/nucypher/issues/2420>`__)
- Improve gas strategy selection: Infura users now can choose between ``slow``, ``medium`` and ``fast``, and a maximum gas price can be configured with --max-gas-price. (`#2445 <https://github.com/nucypher/nucypher/issues/2445>`__)
Bugfixes
~~~~~~~~
- Slowly try more and more nodes if some of the initial draft for a policy were inaccessible. (`#2416 <https://github.com/nucypher/nucypher/issues/2416>`__)
- Fix bad cli handling in several cloudworkers commands, improved envvar handling. (`#2475 <https://github.com/nucypher/nucypher/issues/2475>`__)
Misc
~~~~
- (`#2244 <https://github.com/nucypher/nucypher/issues/2244>`__, `#2483 <https://github.com/nucypher/nucypher/issues/2483>`__)
- Solidity compilation refinements (`#2461 <https://github.com/nucypher/nucypher/issues/2461>`__)
- Deprecates internally managed geth process management (`#2466 <https://github.com/nucypher/nucypher/issues/2466>`__)
- Include checksum and IP addresses in exception messages for `Rejected`. (`#2467 <https://github.com/nucypher/nucypher/issues/2467>`__)
- Deprecates managed ethereum client syncing and stale interface methods (`#2468 <https://github.com/nucypher/nucypher/issues/2468>`__)
- Improves console messages for stakeholder CLI initialization and worker startup. (`#2474 <https://github.com/nucypher/nucypher/issues/2474>`__)
- Introduce a template to describe Pull Requests. (`#2476 <https://github.com/nucypher/nucypher/issues/2476>`__)
v4.3.0 (2020-12-08)
-------------------
Features
~~~~~~~~
- Introduces shorthand options for --bob-verifying-key (-bvk), --bob-encrypting-key (-bek) and alice verifying key (-avk) for CLI commands. (`#2459 <https://github.com/nucypher/nucypher/issues/2459>`__)
- Complete interactive collection of policy parameters via alice grant CLI. (`#2460 <https://github.com/nucypher/nucypher/issues/2460>`__)
Bugfixes
~~~~~~~~
- Corrected minimum stake value for --min-stake CLI option (`#2371 <https://github.com/nucypher/nucypher/issues/2371>`__)
Misc
~~~~
- Introduces a probationary period for policy creation in the network, until 2021-02-28 23:59:59 UTC. (`#2431 <https://github.com/nucypher/nucypher/issues/2431>`__)
- Supplies `AccessDenied` exception class for better incorrect password handling. (`#2451 <https://github.com/nucypher/nucypher/issues/2451>`__)
- Maintain compatibility with python 3.6 (removes re.Pattern annotations) (`#2458 <https://github.com/nucypher/nucypher/issues/2458>`__)
v4.2.1 (2020-12-04)
-------------------
Bugfixes
~~~~~~~~
- Removes tests import from constants module causing pip installed versions to crash. (`#2452 <https://github.com/nucypher/nucypher/issues/2452>`__)
v4.2.0 (2020-12-03)
-------------------
Features
~~~~~~~~
- Improve user experience when removing unused substakes (CLI and docs). (`#2450 <https://github.com/nucypher/nucypher/issues/2450>`__)
Bugfixes
~~~~~~~~
- Fix bug in deployer logic while transferring ownership of StakingInterfaceRouter (`#2369 <https://github.com/nucypher/nucypher/issues/2369>`__)
- Allow arbitrary decimal precision when entering NU amounts to nucypher CLI. (`#2441 <https://github.com/nucypher/nucypher/issues/2441>`__)
Improved Documentation
~~~~~~~~~~~~~~~~~~~~~~
- Document usage of hardware wallets for signing. (`#2346 <https://github.com/nucypher/nucypher/issues/2346>`__)
- Improvements to the staking guide: extending description of winddown command, other minor corrections. (`#2434 <https://github.com/nucypher/nucypher/issues/2434>`__)
Misc
~~~~
- Rework internal solidity compiler usage to implement "Standard JSON Compile". (`#2439 <https://github.com/nucypher/nucypher/issues/2439>`__)
- Introduces `--config-path` and `--logging-path` CLI flags displaying default nucypher directories (`#2446 <https://github.com/nucypher/nucypher/issues/2446>`__)
v4.1.2 (2020-11-09)
-------------------
Features
~~~~~~~~
- Added support for a user-provided gas price to the ``nucypher stake`` command, using ``--gas-price GWEI``. (`#2425 <https://github.com/nucypher/nucypher/issues/2425>`__)
Bugfixes
~~~~~~~~
- Correct CLI problems when setting the min fee rate. Also, simplifies usage by expressing rates in GWEI. (`#2390 <https://github.com/nucypher/nucypher/issues/2390>`__)
- Tone-down learning logging messages even more (see issue #1712). Fixes some CLI and exception messages. (`#2395 <https://github.com/nucypher/nucypher/issues/2395>`__)
- Fixes logical bug in ``WorkTracker`` to ensure commitment transactions can only be issued once per period. (`#2406 <https://github.com/nucypher/nucypher/issues/2406>`__)
- Removes leftover imports of Twisted Logger, using instead our shim (Closes #2404). Also, changes NuCypher Logger behavior to always escape curly braces. (`#2412 <https://github.com/nucypher/nucypher/issues/2412>`__)
- Now ``BlockchainInterface.gas_strategy`` always has a value; previously it was possible to pass ``None`` via the constructor (e.g. if the config file had an explicit ``"null"`` value). (`#2421 <https://github.com/nucypher/nucypher/issues/2421>`__)
- Take advantage of the changes in PR#2410 by retrying worker commitments on failure (`#2422 <https://github.com/nucypher/nucypher/issues/2422>`__)
- Domain "leakage", or nodes saving metadata about nodes from other domains (but never being able to verify them) was still possible because domain-checking only occurred in the high-level APIs (and not, for example, when checking metadata POSTed to the node_metadata_exchange endpoint). This fixes that (fixes #2417).
Additionally, domains are no longer separated into "serving" or "learning". Each Learner instance now has exactly one domain, and it is called domain. (`#2423 <https://github.com/nucypher/nucypher/issues/2423>`__)
Misc
~~~~
- Updates contract registry after upgrade of StakingEscrow to v5.5.1, at behest of the DAO (proposal #0). (`#2402 <https://github.com/nucypher/nucypher/issues/2402>`__)
- Improved newsfragments README file to clarify release note entry naming convention. (`#2415 <https://github.com/nucypher/nucypher/issues/2415>`__)
v4.1.1 (2020-10-29)
-------------------
Features
~~~~~~~~
- Add CLI functionality for the removal of unused (inactive) sub-stakes. Depending on the staker's sub-stake configuration, this command can reduce the associated worker's gas costs when making commitments. (`#2384 <https://github.com/nucypher/nucypher/issues/2384>`__)
Bugfixes
~~~~~~~~
- Automatically restart Ursula worker task on failure. (`#2410 <https://github.com/nucypher/nucypher/issues/2410>`__)
Improved Documentation
~~~~~~~~~~~~~~~~~~~~~~
- Update global fee range documentation, including genesis values. (`#2363 <https://github.com/nucypher/nucypher/issues/2363>`__)
Misc
~~~~
- Update Ursula network grant availability script for mainnet usage. (`#2383 <https://github.com/nucypher/nucypher/issues/2383>`__)
- GitHub Action to ensure that each pull request into main makes an associated release note entry. (`#2396 <https://github.com/nucypher/nucypher/issues/2396>`__)
v4.1.0 (2020-10-19)
-------------------
Bugfixes
~~~~~~~~
- Temporary workaround for lack of single attribute for the value of "domain" in sprouts and mature nodes. (`#2356 <https://github.com/nucypher/nucypher/issues/2356>`__)
- Show the correct fleet state on Ursula status page. (`#2368 <https://github.com/nucypher/nucypher/issues/2368>`__)
- Don't crash when handling failed transaction; reduce network learning messages. (`#2375 <https://github.com/nucypher/nucypher/issues/2375>`__)
- Reduce the greediness of prometheus metrics collection. (`#2376 <https://github.com/nucypher/nucypher/issues/2376>`__)
- Ensure minimum NU stake is allowed instead of stake creation failing for not enough tokens. (`#2377 <https://github.com/nucypher/nucypher/issues/2377>`__)
- Fixes to status page based on reworked design done in PR #2351. (`#2378 <https://github.com/nucypher/nucypher/issues/2378>`__)
- Track pending Ursula commitment transactions due to slower gas strategies. (`#2389 <https://github.com/nucypher/nucypher/issues/2389>`__)
v4.0.1 (2020-10-14)
-------------------
Misc
~~~~
- Set default teacher uri for mainnet. (`#2367 <https://github.com/nucypher/nucypher/issues/2382>`__)
v4.0.0 (2020-10-14)
-------------------
**🚀 Mainnet Launch 🚀**

18
docs/source/support/community.rst
View File

@ -1,18 +0,0 @@
=========
Community
=========
.. image:: ../.static/img/nu_support.png
Bugs & Feature Requests
-----------------------
You can file bug reports or feature requests on our `GitHub Issue Tracker <https://github.com/nucypher/nucypher/issues>`_,
and they will be addressed appropriately.
Sufficient information should be provided to resolve the issue. Please also add *Labels* to the issue
that characterise its nature. The full list of *Labels* are available `here <https://github.com/nucypher/nucypher/issues/labels>`_.
Contact Us
----------
You can join our `Discord <https://discord.gg/Threshold>`_ to chat with us.

355
docs/source/support/contribution.rst
View File

@ -1,355 +0,0 @@
.. _contribution-guide:
Contributing
============
.. image:: https://cdn-images-1.medium.com/max/800/1*J31AEMsTP6o_E5QOohn0Hw.png
:target: https://cdn-images-1.medium.com/max/800/1*J31AEMsTP6o_E5QOohn0Hw.png
Development Installation
------------------------
Additional dependencies and setup steps are required to perform a "developer installation".
You do not need to perform these steps unless you intend to contribute a code or documentation change to
the nucypher codebase.
Before continuing, ensure you have ``git`` installed (\ `Git Documentation <https://git-scm.com/doc>`_\ ).
.. _acquire_codebase:
Acquire NuCypher Codebase
^^^^^^^^^^^^^^^^^^^^^^^^^
.. _`NuCypher GitHub`: https://github.com/nucypher/nucypher
In order to contribute new code or documentation changes, you will need a local copy
of the source code which is located on the `NuCypher GitHub`_.
.. note::
NuCypher uses ``git`` for version control. Be sure you have it installed.
Here is the recommended procedure for acquiring the code in preparation for
contributing proposed changes:
1. Use GitHub to fork the ``nucypher/nucypher`` repository
2. Clone your fork's repository to your local machine
.. code-block:: bash
$ git clone https://github.com/<YOUR-GITHUB-USERNAME>/nucypher.git
3. Change directory to ``nucypher``
.. code-block:: bash
$ cd nucypher
4. Add ``nucypher/nucypher`` as an upstream remote
.. code-block:: bash
$ git remote add upstream https://github.com/nucypher/nucypher.git
5. Update your remote tracking branches
.. code-block:: bash
$ git remote update
Ensure Rust is Installed
^^^^^^^^^^^^^^^^^^^^^^^^^
Instruction for installing Rust can be found (\ `here <https://rustup.rs/>`_\ ).
After acquiring a local copy of the application code and installing rust, you will need to
install the project dependencies, we recommend using either ``pip`` or ``pipenv``.
Pip Development Installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Alternately, you can install the development dependencies with pip:
.. code-block:: bash
$ pip3 install -e .[dev]
Running the Tests
-----------------
.. note::
A development installation including the solidity compiler is required to run 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`_.
To run the tests, use the following commands:
.. code:: bash
(nucypher)$ pytest -s tests/unit
(nucypher)$ pytest -s tests/integration
Optionally, to run the full, slow, verbose test suite run:
.. code:: bash
(nucypher)$ pytest
Setup Commit & Push Hooks
--------------------------
`Pre-commit <https://pre-commit.com/>`_ and pre-push are used for quality control to identify and prevent the inclusion of problematic code changes. They may prevent a commit that will fail
if passed along to CI servers or make small formatting changes directly to source code files.
If it's not already installed in your virtual environment, install pre-commit:
.. code:: bash
(nucypher)$ pip install pre-commit
To enable pre-commit checks:
.. code:: bash
(nucypher)$ pre-commit install
To enable pre-push checks:
.. code:: bash
(nucypher)$ pre-commit install -t pre-push
For convenience, here is a one-liner to enable both:
.. code:: bash
(nucypher)$ pre-commit install && pre-commit install -t pre-push
Making a Commit
---------------
NuCypher takes pride in its commit history.
When making a commit that you intend to contribute, keep your commit descriptive and succinct.
Commit messages are best written in full sentences that make an attempt to accurately
describe what effect the changeset represents in the simplest form. (It takes practice!)
Imagine you are the one reviewing the code, commit-by-commit as a means of understanding
the thinking behind the PRs history. Does your commit history tell an honest and accurate story?
We understand that different code authors have different development preferences, and others
are first-time contributors to open source, so feel free to join our `Discord <https://discord.gg/7rmXa3S>`_ and let us know
how we can best support the submission of your proposed changes.
Opening a Pull Request
----------------------
When considering including commits as part of a pull request into ``nucypher/nucypher``,
we *highly* recommend opening the pull request early, before it is finished with
the mark "[WIP]" prepended to the title. We understand PRs marked "WIP" to be subject to change,
history rewrites, and CI failures. Generally we will not review a WIP PR until the "[WIP]" marker
has been removed from the PR title, however, this does give other contributors an opportunity
to provide early feedback and assists in facilitating an iterative contribution process.
Pull Request Conflicts
----------------------
As an effort to preserve authorship and a cohesive commit history, we prefer if proposed contributions
are rebased over ``main`` (or appropriate branch) when a merge conflict arises,
instead of making a merge commit back into the contributors fork.
Generally speaking the preferred process of doing so is with an `interactive rebase`:
.. important::
Be certain you do not have uncommitted changes before continuing.
1. Update your remote tracking branches
.. code-block:: bash
$ git remote update
... (some upstream changes are reported)
2. Initiate an interactive rebase over ``nucypher/nucypher@main``
.. note::
This example specifies the remote name ``upstream`` for the NuCypher organizational repository as
used in the `Acquire NuCypher Codebase`_ section.
.. code-block:: bash
$ git rebase -i upstream/main
... (edit & save rebase TODO list)
3. Resolve Conflicts
.. code-block:: bash
$ git status
... (resolve local conflict)
$ git add path/to/resolved/conflict/file.py
$ git rebase --continue
... ( repeat as needed )
4. Push Rebased History
After resolving all conflicts, you will need to force push to your fork's repository, since the commits
are rewritten.
.. warning::
Force pushing will override any changes on the remote you push to, proceed with caution.
.. code-block:: bash
$ git push origin my-branch -f
Building Documentation
----------------------
.. note::
``sphinx`` and ``sphinx_rtd_theme`` are non-standard dependencies that can be installed
by running ``pip install -e . -r docs-requirements.txt`` 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.
However, you may want to build the documentation html locally for development.
To build the project dependencies locally on Linux:
.. code:: bash
(nucypher)$ make docs
or on MacOS:
.. code:: bash
(nucypher)$ make mac-docs
If the build is successful, the resulting local documentation homepage, ``nucypher/docs/build/html/index.html``, will
be automatically opened in the web browser.
.. note::
If you would rather not have the homepage automatically opened, then run ``make build-docs`` instead.
Building Docker
---------------
Docker builds are automated as part of the publication workflow 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:
*Docker Compose:*
.. code:: bash
(nucypher)$ docker-compose -f deploy/docker/docker-compose.yml build .
Release Cycle
-------------
Versioning
^^^^^^^^^^
The versioning scheme used is inspired by `semantic versioning 2.0 <https://semver.org/>`_, but adds development stage and release candidate tags. The basic idea:
- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backwards compatible manner
- PATCH version when you make backwards compatible bug fixes
Two additional tags are used: ``-dev`` and ``-rc.x`` (i.e. ``v1.2.3-dev`` or ``v4.5.6-rc.0``)
Upstream Branches
^^^^^^^^^^^^^^^^^
- ``main`` is the stable and released version published to PyPI and docker cloud (``v6.0.0``).
- ``development`` is the default upstream base branch containing new changes ahead of ``main`` and tagged with ``-dev`` (``v6.1.0-dev``).
Major/Minor Release Cycle
^^^^^^^^^^^^^^^^^^^^^^^^^
- New pull requests are made into ``development``.
- When a commit from ``development`` is selected as a release candidate the version tag is changed from ``-dev`` to ``rc.0`` (``v6.1.0-rc.0``). Selecting a release candidate implies a feature freeze.
- The release candidate is deployed to beta testers, staging, and testnet environments for QA.
- If the candidate is suitable, it is tagged, merged into ``main``, and published:
- All version tags are removed (``v6.1.0-dev`` -> ``v6.1.0``)
- A new upstream git version tag is pushed (triggering publication on CI) (``v6.1.0``)
- ``development`` is merged into ``main``
- `development` version is bumped and the `-dev` tag is appended (``v6.2.0-dev`` or ``v7.0.0-dev``)
Release Blockers
^^^^^^^^^^^^^^^^
Sometimes changes are needed to fix a release blocker after a release candidate has already been selected. Normally the best course of action is to open a pull request into ``development``.
- Merge the pull request into ``development``
- Bump the release candidate's development number (``v7.0.0-rc.0`` -> ``v7.0.0-rc.1``)
- Redeploy beta testing environments, experimental nodes, staging, testnets, etc.
- Rinse & repeat until a suitable release candidate is found.
In the event that a release blocker's fix introduces unexpected backwards incompatibility during a minor release, bump the major version instead skipping directly to ``-rc.0``.
Patches (bugfixes, security patches, "hotfixes")
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sometimes urgent changes need to be made outside of a planned minor or major release. If the required changes are backwards compatible open a pull request into ``main``. Once the changes are reviewed and merged, ``development`` must be rebased over ``main``
- Pull request is merged into ``main``
- The version's patch number is bumped (``v6.1.0`` -> ``v6.1.1``)
- A new upstream tag is pushed, triggering the publication build on CI (``v6.1.1``)
- ``development`` is rebased over ``main``, amending the existing bumpversion commit with the new patch (this will be a merge conflict).
- Rinse & repeat
Release Automation
--------------------
.. note::
This process uses ``towncrier`` and ``bumpversion``, which can be installed by running ``pip install -e .[deploy]`` or ``pip install towncrier bumpversion``.
Also note that it requires you have git commit signing properly configured.
.. important::
Ensure your local tree is based on ``main`` and has no uncommitted changes.
1. Decide what part of the version to bump.
The version string follows the format ``{major}.{minor}.{patch}-{stage}.{devnum}``,
so the options are ``major``, ``minor``, ``patch``, ``stage``, or ``devnum``.
We usually issue new releases increasing the ``patch`` version.
2. Use the ``make release`` script, specifying the version increment with the ``bump`` parameter.
For example, for a new ``patch`` release, we would do:
.. code:: bash
(nucypher)$ make release bump=patch
3. The previous step triggers the publication webhooks.
Monitor the triggered deployment build for manual approval.

372
docs/source/support/faq.rst
View File

@ -1,372 +0,0 @@
==========================
Frequently Asked Questions
==========================
The answers in the FAQ regularly reference the network characters "**Alice**," "**Bob**," "**Ursula**," and "**Enrico**." For a more in-depth introduction to each character, head over to :ref:`character-concepts`.
**Alice** is the *data owner*. She wants to share some data with **Bob**, *the data recipient*.
**Enrico** *encrypts data on behalf of Alice* to produce the ciphertext (more specifically a MessageKit). In many cases (though not all!), **Enrico** is controlled by **Alice**.
**Ursula** serves as the "*proxy*" in this proxy re-encryption scheme and *re-encrypts the ciphertext encrypted under Alice's key to a ciphertext that will be decryptable under Bob's key*.
General
-------
Q: How do I know if the PRE Application is a good fit for my use case?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A centralized approach to access control means users are forced to trust the system(s) with the plaintext version of
their private data, and usually are given little insight into who exactly they are trusting. The PRE Application’s decentralized
access control system offers developers, and their users, a departure from this opaque and trust-dependent paradigm.
When integrated, ``nucypher`` enables end-to-end encrypted data sharing workflows within applications – but
crucially, without sacrificing scalability, redundancy or performance – and applicable to data payloads of
any form, size, structure, sensitivity or production cadence. Users enjoy the same sharing powers they
currently take for granted but are **not** obliged to trust the developers of the application or
third-party access control services (e.g. centralized servers or key management systems) with their data.
Q: How is PRE different from more traditional public key infrastructure (PKI)?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For an in-depth analysis of this topic, see our blog post entitled "`Three things that NuCypher's "Ursula" can do that vanilla public-key cryptography can't <https://blog.nucypher.com/why-use-nucyphers-ursula-instead-of-traditional-public-key-cryptography/>`_".
Q: If a dApp utilizes the PRE Application, is there an ETH gas fee associated with each re-encryption of encrypted data?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There is a gas fee associated with granting and revoking policies, but re-encryption does not involve an on-chain transaction so there is no gas fee.
Previously, policy management occurred on Ethereum mainnet. As of nucypher 6.0, policy management occurs on the Polygon sidechain
by default and results in lower gas fees.
Q: How much trust do we place in Ursula, the proxy?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Ursulas are “semi-trusted” in the sense that Alice must trust Ursula to revoke a policy once it expires or if instructed to do so (by Alice). Alice and Bob also trust Ursula to be responsive and perform the re-encryption correctly so that Bob can access the data.
Importantly, Ursulas are not trusted with access to any underlying plaintext or private keys.
Q: How do we verify that Ursula has performed the re-encryption correctly?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Every time Ursula produces a re-encryption result, she computes a zero-knowledge proof that proves that the re-encryption she just performed is correct,
without disclosing any kind of secret information. This correctness proof is publicly verifiable, so if
someone detects incorrect re-encryptions coming from an Ursula, these faulty proofs can be sent to a smart contract that will slash the stake
associated with that Ursula. However, in a normal scenario, with Ursula working correctly, there’s no need for correctness proofs to be
submitted on-chain.
Q: How much trust do we place in Enrico?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Enrico is often (not always!) controlled by Alice. Enrico must be trusted to perform the encryption correctly and to not disclose the secret key.
However, these things are out of our (cryptographic) control. Additionally, Alice can decrypt (and thus read) anything encrypted by Enrico.
Q: Where are Bobs’ requests handled?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Bobs' requests are handled off-chain.
Q: Why are Bobs' requests handled off-chain?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It allows for a very small/lightweight Bob.
Q: Why can't my users reuse their Ethereum wallet keys when creating a sharing policy?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Avoiding key reuse is a strong defense-in-depth measure against cryptographic and software flaws. While it is
possible to use your ETH keys in ``nucypher``, we strongly advise against such a practice. It is best to keep these
sets of keys separate.
Q: How can I get help integrating nucypher into my application?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See :doc:`/application_development/getting_started`. To chat directly with our team, please join our `Discord <https://discord.gg/Threshold>`_.
Q: How do I integrate nucypher if my application is not written in Python?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Nucypher also provides web integration. See :ref:`web-development`.
Q: Are there testnets that I can use?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is subject to near-term changes as we stabilize the new release across testnet nodes.
Running a Node
--------------
*These are questions related to running a PRE node on the Threshold Network.*
Q: What kind of token is T?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
T is an implementation of the ERC20 standard deployed onto the Ethereum blockchain.
Q: How many Ursulas per period collect Inflation rewards (T)?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Every Ursula that is “online” and “available” will receive a cut based on the
size of their stake proportional to the overall T staked in the network.
Q: What are the recommended server specifications for running a PRE Application node?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See :ref:`node-requirements`.
Q: How do I set up a network node?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See :ref:`running-a-node`.
Q: Is there a guide for Windows?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Our guide is intended for Linux - we do not officially support Windows.
Q: How computationally expensive is the re-encryption operation?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A re-encryption operation is very lightweight (in the order of milliseconds) and is comparable to computing an ECDSA signature.
Q: Where is my Ursula config path?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Default configuration and logging paths can be displayed using the command line:
Configuration path - ``nucypher --config-path``
Default logging path - ``nucypher --logging-path``
On Ubuntu/Debian the default Ursula configuration path is``$HOME/.local/share/nucypher/ursula.json``.
However, if you have more than one Ursula configuration, the filename will include the checksum address:``$HOME/.local/share/nucypher/ursula-0xdeadbeef.json``.
To inspect the config path for configuration files run ``ls $(nucypher --config-path)``.
Q: What is the difference between Standard Installation and Development Installation?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Development Installation is only needed for developing with ``nucypher``. You don't need to use
it unless you plan to make changes to the codebase. If you are simply staking/running a node, you
only need the Standard Installation
Q: How do I know that my node is set up correctly?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is **ONLY** a heuristic to ensure that your node is running correctly, it doesn't guarantee your node is setup correctly:
#. Ensure that your Ursula node is up and running (logs/terminal):
.. code::
Starting Ursula on xxx.xxx.xxx.xxx:9151
Connecting to <NETWORK>
Working ~ Keep Ursula Online!
#. Ensure that your node uses the correct IP address and can be accessed via port 9151 from an outside
connection eg. cell phone, another computer etc. by navigating to ``https://<node_ip>:9151/status``
Q: What's the best way to run an Ursula node in the background?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using docker :ref:`Docker <run-ursula-with-docker>`
Q: When installing on Docker, what do I input for <NETWORK NAME>?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use ``mainnet`` if you want to interact with the PRE Application network, otherwise use the relevant testnet.
Q: How can I check for currently available staking rewards?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On the `Threshold Dashboard UI <https://dashboard.threshold.network>`_.
Q: What is a fleet state?
~~~~~~~~~~~~~~~~~~~~~~~~~
A symbol that represents your node's view of the network. It is just a
graphic checksum, so a minor change in the fleet (e.g., a new node joins, a node disappears, etc.)
will produce a completely different fleet state symbol. A node can have a
different fleet state than others, which may indicate that a different number of peers are accessible from
that node's global position, network configuration, etc.
Q: Why do I get ``NET::ERR_CERT_INVALID`` when loading the Ursula node status page?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The status page uses a self-signed certificate, but browsers don’t like it.
You can usually proceed to the page anyway. If not, try using a different browser.
Q: What types of Ethereum web3 node providers do you support?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* IPC Socket-based JSON-RPC server e.g. ``ipc:///home/<username>/.ethereum/geth.ipc``
* HTTP(S)-based JSON-RPC server e.g. ``http://<host>``, ``https://<host>``
* Websocket(Secure)-based JSON-RPC server e.g. ``ws://<host>:8080``, ``wss://<host>:8080``
Q: How does my node choose what price to use for transactions? Can I control this?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When sending a transaction, your node automatically chooses the gas price
using a `gas strategy <https://web3py.readthedocs.io/en/stable/gas_price.html>`_.
We currently offer three types of gas strategies,
based on the approximate confirmation time:
- ``slow``: Confirmation expected within **one hour**.
- ``medium``: Confirmation expected within **five minutes**.
- ``fast``: Confirmation expected within **one minute**.
Note that the times are an approximation, and the confirmation time may vary
when gas prices experience more volatility.
In such situations, transactions may not be mined within the expected time.
However, your node keeps track of the transactions and is capable of automatically
sending replacement transactions to adjust to a scenario with new prices.
In any case, we recommend that you monitor your node to be sure that the
transactions are being sent and confirmed correctly.
You can set a gas strategy using the Ursula configuration command.
For example, the following command sets the ``medium`` gas strategy:
.. code:: bash
(nucypher)$ nucypher ursula config --gas-strategy medium
There's an additional, advanced control mechanism for limiting the maximum
gas price that your node can spend. The ``--max-gas-price`` flag can be used to configure the limit in `gwei`.
This is complementary to the gas strategy that you may have configured.
.. code:: bash
(nucypher)$ nucypher ursula config --max-gas-price 50
.. warning::
If you set a maximum limit and gas prices remain higher
than that limit, it's possible that your node will not get
the transaction included in the blockchain.
.. warning::
The maximum gas price limit is an experimental feature and may be changed
or removed in the future.
Threshold Network Merger
------------------------
*Questions related to the merger with the Keep Network to launch the Threshold Network* (More info `here <https://blog.threshold.network/threshold-launch/>`_).
Q: What are the benefits of the network merger between NU and Keep?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See `Twitter thread <https://twitter.com/NuCypher/status/1478478558280527885?s=20&t=sUDMynarfjnLv8blAxR5Yw>`_.
Q: What is the Threshold Network website
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
https://threshold.network
Q: Is this NuCypher Discord server still in use?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The community has migrated to the `Threshold Discord <https://discord.gg/Threshold>`_ and the NuCypher Discord server has been set to read-only.
Q: What is the T token address?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
T is the work token for the Threshold Network. See https://etherscan.io/address/0xcdf7028ceab81fa0c6971208e83fa7872994bee5.
Q: How do I see my T tokens in my Metamask wallet?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Input the T token address, ``0xCdF7028ceAB81fA0C6971208e83fa7872994beE5``, in your wallet.
Q: How do you upgrade NU to T?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Via the `Threshold Dashboard <https://dashboard.threshold.network/upgrade/NU>`_.
Q: How do you downgrade T to NU?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can downgrade T back to NU through the smart contract directly.
However, ONLY to the original upgrade address can perform the downgrade, and only to the maximum of the original amount
that was upgraded (downgrading is not fungible).
Q: Is it possible to upgrade KEEP -> T then downgrade T -> NU?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
T can only be converted back to the original wrapped token.
Q: What is the NU → T VendingMachine address?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
https://etherscan.io/address/0x1cca7e410ee41739792ea0a24e00349dd247680e
Q: What is the NU to T conversion ratio?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1 NU = 3.259242493160746 T.
Q: Will the conversion rate be fixed regardless of NU and T price?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Yes. The vending machine is perpetual and the ratio is static.
Q: Will KEEP / NU be delisted in favor of T?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The token to participate in staking and governance will be T. NU and KEEP held on exchanges
will be subject to exchanges' terms for the upgrade. We can not speculate on when CEXs will
list or delist specific assets but the ultimate goal is for everyone who owns NU or KEEP
to eventually upgrade to T so that they can participate in the Threshold Network.
Q: How do I use the Vending Machine contract directly?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the `Vending Machine Documentation <https://github.com/threshold-network/solidity-contracts/blob/main/docs/rfc-2-vending-machine.adoc>`_.
Q: How do I stake T?
~~~~~~~~~~~~~~~~~~~~
Via the `Threshold Dashboard Staking UI <https://dashboard.threshold.network/staking>`_.
Q: What happens if my stake is/was locked?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unless a stake is subject to vesting associated with a legal agreement (e.g. SAFT 2 purchaser, team etc.) it will be immediately withdrawable. These Stakers can:
#. Withdraw any existing unlocked stake: https://stake.nucypher.network/manage/withdraw
#. Upgrade the unlocked NU to T: https://dashboard.threshold.network/upgrade/nu
#. Stake the upgraded T: https://dashboard.threshold.network/staking
For **locked** stakes, an adapter will allow these stakes to operate nodes on the Threshold Network and receive T token rewards. These Stakers can
migrate existing locked stakes from NU to Threshold via https://stake.nucypher.network/manage/stake. Once these stakes expire and the locked tokens become unlocked / liquid,
they can be upgraded to T and staked as T.
Q: Is there a minimum stake size?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The current minimum stake size for running a PRE node is 40,000 T but is tunable via governance.
Q: What happened to the existing NU contracts after the merge?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
They continue to exist on the Ethereum mainnet but most of the functionality is disabled.
Q: When was NU inflation halted?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Thursday, December 30th after the execution
of NuCypher DAO proposal `#2 <https://client.aragon.org/#/nucypherdao/0x61950d573c741ca10ee6815de11bcbe7e60a0f10/vote/2/>`_
Q: Can I still withdraw my ETH from WorkLock?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is withdrawable. The ``StakingEscrow`` contract still contains the code needed for anyone who still has ETH locked in Worklock.

81
docs/source/support/troubleshooting.rst
View File

@ -1,81 +0,0 @@
===============
Troubleshooting
===============
ValueError: {'code': -32000, 'message': 'no suitable peers available'}
----------------------------------------------------------------------
This is a Geth error and not related to ``nucypher``. You are probably running a light node that needs
full nodes willing to serve information to it, but no such nodes were found (a frequent problem on the Ethereum testnets).
nucypher.blockchain.eth.interfaces.ConnectionFailed: Connection Failed, is IPC enabled
--------------------------------------------------------------------------------------
The provider URI may be incorrect.
For example: if the scheme is ``ipc://`` then the path should be appended as is to the end ``ipc:///home/…``
i.e. **THREE** slashes not two.
Validation error: 'code': -32000, 'message': 'gas required exceeds allowance (8000000) or always failing transaction
--------------------------------------------------------------------------------------------------------------------
This is a generic exception thrown by Geth meaning "Transaction Failed".
This error can be caused by a variety of reasons. Each time ``require()`` fails to validate a condition in a contract
without a corresponding check in the ``nucypher`` client itself, this error is raised. Over time, as we update the
client, this generic error will become extinct.
builtins.ValueError: {'code': -32000, 'message': 'insufficient funds for gas * price + value'}
----------------------------------------------------------------------------------------------
The Ursula node does not have enough ETH to pay for transaction gas. Ensure that your operator address has ETH.
Warning! Error encountered during contract execution [Out of gas]
-----------------------------------------------------------------
The Ursula node does not have enough ETH to pay for transaction gas; ensure that your operator address has ETH.
RuntimeError: Click will abort further execution because Python 3 was configured to use ASCII as encoding for the environment
-----------------------------------------------------------------------------------------------------------------------------
Try setting the following environment variables:
.. code::
export LC_ALL=en_US.utf-8
export LANG=en_US.utf-8
builtins.FileNotFoundError: [Errno 2] No such file or directory: '/<path>/.cache/nucypher/log/nucypher.log.20191227'
--------------------------------------------------------------------------------------------------------------------
This is an artifact of upgrading Ursula - remove the directory ``<path>/.cache/nucypher/log`` and restart Ursula.
web3.exceptions.BadFunctionCallOutput: Could not transact with/call contract function, is contract deployed correctly and chain synced?
---------------------------------------------------------------------------------------------------------------------------------------
This error usually means your blockchain data is not synced.
If using Geth, ensure that Geth is fully synced. You can use the ``--exitwhensynced`` flag which causes Geth
to exit once fully synced.
When using parity in light mode, this is raised when the light node cannot satisfy the call/transaction, e.g. not
enough full nodes are serving requests.
ValueError: {'code': -32000, 'message': 'could not decrypt key with given password'}
------------------------------------------------------------------------------------
Potential reasons:
#. You may be using the wrong password for your ethereum account.
#. You may be using the wrong ethereum account.
#. If trying to collect rewards, this is a `known bug <https://github.com/nucypher/nucypher/issues/1657>`_ in our
code - rerun the command without the ``--staking-address`` option.

47
docs/source/threshold/threshold_overview.rst
View File

@ -1,47 +0,0 @@
.. _threshold_overview:
Legacy NuCypher Stakes
----------------------
As part of the merger to the Threshold Network, if you have an existing legacy NU stake,
you can now withdraw it (and then upgrade the liquid tokens to T and stake). If you are
subject to a vesting agreement, your unvested stake will not be immediately withdrawable
but you can still stake it in Threshold!
Both options are available from the `NU dashboard <https://stake.nucypher.network/manage>`_:
* `Withdraw available NU <https://stake.nucypher.network/manage/withdraw>`_
* `Stake unvested NU on Threshold <https://stake.nucypher.network/manage/stake>`_
Upgrading to T
--------------
The Threshold Network Token (`T <https://etherscan.io/address/0xCdF7028ceAB81fA0C6971208e83fa7872994beE5>`_) is
the work token for staking on the Threshold Network, and
allows for participation in `DAO governance <https://blog.threshold.network/thresholds-governance-structure-and-the-upcoming-council-elections/>`_.
The `Threshold Network Dashboard <https://dashboard.threshold.network/upgrade.>`_ can be used to upgrade from NU to T.
The upgrade from NU to T is also available via directly interacting with the vending machine smart contracts
deployed on mainnet. The NU -> T vending machine contract address is https://etherscan.io/address/0x1CCA7E410eE41739792eA0A24e00349Dd247680e.
.. note::
1 NU = 3.259242493160745 T
.. important::
The vending machine contract uses a static conversion ratios and remain available indefinitely, so
please be safe, take your time, and confirm everything!
T Supply Details
----------------
* 10B initial supply
* 4.5B allocated to NU holders
* 4.5B allocated to KEEP holders
* 1B allocated to Threshold DAO