Nucypher Documentation Release 5.3.1
Total Page:16
File Type:pdf, Size:1020Kb
NuCypher Documentation Release 5.3.1 NuCypher Sep 22, 2021 STAKING 1 How does NuCypher work? 3 2 Whitepapers 5 3 Indices and Tables 307 Python Module Index 309 Index 311 i ii NuCypher Documentation, Release 5.3.1 The NuCypher network is a decentralized network of nodes that perform threshold cryptography operations serving users with secrets management and dynamic access control. nucypher is the python library and CLI for interacting with the decentralized threshold cryptography network. STAKING 1 NuCypher Documentation, Release 5.3.1 2 STAKING CHAPTER ONE HOW DOES NUCYPHER WORK? 1. Alice, the data owner, grants access to her encrypted data to anyone she wants by creating a policy and uploading it to the NuCypher network. 2. A group of Ursulas, which are nodes on the NuCypher network, receive information about the policy, called a PolicyArrangement that include a re-encryption key share. The Ursulas stand ready to re-encrypt data in exchange for payment in fees and token rewards. Thanks to the use of proxy re-encryption, Ursulas and the storage layer never have access to Alice’s plaintext data. 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, obtains the encrypted data from the storage layer and sends an access request to the NuCypher network. If the policy is satisfied, the data is re-encrypted to his public key and he can decrypt it with his private key. 5. Ursulas earn fees and token rewards for performing re-encryption operations. More detailed information: • GitHub https://www.github.com/nucypher/nucypher • Website https://www.nucypher.com/ 3 NuCypher Documentation, Release 5.3.1 4 Chapter 1. How does NuCypher work? CHAPTER TWO WHITEPAPERS 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 Economics https://github.com/nucypher/whitepaper/blob/master/economics/staking_protocol/NuCypher_Staking_ Protocol_Economics.pdf “NuCypher Network: Staking Protocol & Economics” by Michael Egorov, MacLane Wilkison, Arjun Hassard - NuCypher https://github.com/nucypher/whitepaper/blob/master/economics/pricing_protocol/NuCypher_Network_ _Pricing_Protocol_Economics.pdf “NuCypher Network: Pricing Protocol & Economics” by Arjun Hassard - 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 2.1 Stakers and Workers NuCypher staking operations are divided into two roles - “Staker” and “Worker”. The Staker can be thought of as a fiduciary administrator that holds NU and collects rewards. The Worker is bonded to a Staker and performs work on behalf of the Staker. 2.1.1 Staker Overview A nucypher staker is a holder of NU and manager of one or more stakes. NU is an ERC-20 token that underpins the network. Stakes are initiated by locking NU into the “Staking Escrow “ contract for a fixed duration of time. Staked NU earns two income streams: inflation rewards (NU) and policy fees (ETH). Staked NU gradually unlocks with each completed period (7 days), depending on re-stake and wind-down configuration options. Active network participation (work) is delegated to a Worker node through bonding. There is a 1:1 relationship between the roles; One Staker to one Worker. A Staker controls a single Ethereum account and may have multiple substakes, but only ever has one Worker bonded at a time. To ensure the integrity of the network and its service quality, staked NU can be slashed due to misbehaviour, deliberate or unintentional, by the corresponding worker. 5 NuCypher Documentation, Release 5.3.1 2.1.2 Worker Overview Worker - (aka “Ursula”) Active network participant who carries out threshold cryptography operations. The Worker is the bonded delegate of a Staker and an active network node, performing work on behalf of a Staker. Workers must remain online to provide uninterrupted services on-demand, signalling their availability with a commit- ment transaction before the start of each period (every 7 days), which costs approximately 200k gas. 2.1.3 Staker and Worker Delegation There are several strategies for running and maintaining a stake: • Delegate custody of NU and work to a third-party custodian (Staker Delegation). • Delegate work via a staking pool or Node-as-a-Service provider (Worker Delegation). • Control the Staker yourself and run your own worker (Self Directed). Here is a simple heuristic to help decide on a course of action: 2.2 Stake Initialization NuCypher staking operations are divided into two roles “Staker” and “Worker” - This Guide is for Stakers. 2.2.1 Staking Requirements The staking CLI itself is lightweight and can be run on commodity hardware. While there are no specific minimum system constraints, there are some basic requirements for stakers: 1. Hosted or Remote Ethereum Node (Infura, Geth, etc.) 2. Hardware or Software Wallet (Trezor, Ledger, Keyfile) 3. At least 15,000 NU 4. Small amount of ether to pay for transaction gas Using a hardware wallet is highly recommended. They are ideal for stakers since they hold NU and temporary access to private keys is required during stake management, while providing a higher standard of security than software wallets or keyfiles. 2.2.2 Staking Procedure 1. Obtain and secure NU 2. Install nucypher on Staker’s system (pip Installation Reference and docker are supported) 3. Configure nucypher CLI for staking (3. Configure nucypher for staking) 4. Bond a Worker to your Staker using the worker’s ethereum address (see 6. Bond a worker) 5. Manage active stakes (Stake Management) 6 Chapter 2. Whitepapers NuCypher Documentation, Release 5.3.1 Caution: Once NU is locked in the staking escrow contract, a worker node must be run to unlock it. Worker’s make periodic automated commitments (every 7 days) which cost at least ~200k gas, depending on how many sub-stakes you have. Be sure to consider this operational cost when locking NU. Note: If you are running an Ibex testnet node, testnet tokens can be obtained by joining the Discord server and typing .getfunded <YOUR_STAKER_ETH_ADDRESS> in the #testnet-faucet channel. 1. Establish an Ethereum Provider Staking transactions can be broadcasted using either a local or remote ethereum node. For general background information about choosing a node technology and operation, see https://web3py.readthedocs. io/en/stable/node.html. 2. Select Transaction Signer By default, all transaction and message signing requests are forwarded to the configured ethereum provider. When using an external ethereum provider (e.g. Infura, Alchemy, other hosted/remote node), a local transaction signer must be configured in addition to the broadcasting node. This can be a hardware wallet, software wallet, or clef. For more detailed information see Transaction Signing $ nucypher <COMMAND> <ACTION> --signer <SIGNER_URI> Note: For hardware wallets, only trezor is currently supported by the CLI directly. Ledger functionality can be achieved through clef. Trezor Signer (Recommended) $ nucypher <COMMAND> <ACTION> --signer trezor Keystore File Signer $ nucypher <COMMAND> <ACTION> --signer keystore://<ABSOLUTE PATH TO KEYFILE> Danger: The Keystore signer is not safe to use for mainnet Staker operations (An exception can be made for testnets). For staking operations use a hardware wallet. 2.2. Stake Initialization 7 NuCypher Documentation, Release 5.3.1 Clef Signer Clef can be used as an external transaction signer with nucypher and supports both hardware (ledger & trezor) and software wallets. See Signing with Clef for setting up Clef. By default, all requests to the clef signer require manual confirmation. This includes not only transactions but also more innocuous requests such as listing the accounts that the signer is handling. This means, for example, that a command like nucypher stake accounts will first ask for user confirmation in the clef CLI before showing the Staker accounts. You can automate this confirmation by using Clef Rules. Note: The default location for the clef IPC file is /home/<username>/.clef/clef.ipc (on MacOS, / Users/<username>/Library/Signer/clef.ipc) $ nucypher <COMMAND> <ACTION> --signer clef://<CLEF IPC PATH> --hw-wallet # Create a new stakeholder with clef as the default signer $ nucypher stake init-stakeholder --signer clef:///home/<username>/.clef/clef.ipc ... # Update an existing configuration with clef as the default signer $ nucypher stake config --signer clef:///home/<username>/.clef/clef.ipc # Set clef ,!as the default signer # Create a new stake using inline signer and provider values $ nucypher stake create --signer clef:///home/<username>/.clef/clef.ipc --provider ~/. ,!ethereum/geth.ipc 3. Configure nucypher for staking Before initiating a stake, a setup step is required to configure nucypher for staking. This will create a JSON configu- ration file (~/.local/share/nucypher/stakeholder.json) containing editable configuration values. No new keys or secrets are created in this step, it is just for configuration. (nucypher)$ nucypher stake init-stakeholder --signer <SIGNER URI> --provider ,!<PROVIDER> Note: If you are using NuCypher’s Ibex testnet, passing the network name is required --network ibex. 4. Create a new stake Once you have configured nucypher for staking, you can proceed with stake initiation. This operation will transfer NU to nucypher’s staking escrow contract, locking it for the commitment period. Caution: Before proceeding it is important to know that the worker must spend ETH to unlock staked NU. Once tokens are locked, the only way for them to become unlocked is by running a bonded Worker node.