Nucypher Documentation Release 5.3.1

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 satisﬁed, 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 ﬁduciary 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 commitment 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. Conﬁgure nucypher CLI for staking (3. Conﬁgure 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 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 conﬁgured ethereum provider. When using an external ethereum provider (e.g. Infura, Alchemy, other hosted/remote node), a local transaction signer must be conﬁgured in addition to the broadcasting node. This can be a hardware wallet, software wallet, or clef. For more detailed information see Transaction Signing

$ nucypher --signer

Note: For hardware wallets, only trezor is currently supported by the CLI directly. Ledger functionality can be achieved through clef.

Trezor Signer (Recommended)

$ nucypher --signer trezor

Keystore File Signer

$ nucypher --signer keystore://

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 ﬁle is /home//.clef/clef.ipc (on MacOS, / Users//Library/Signer/clef.ipc)

$ nucypher --signer clef:// --hw-wallet

# Create a new stakeholder with clef as the default signer $ nucypher stake init-stakeholder --signer clef:///home//.clef/clef.ipc ...

# Update an existing configuration with clef as the default signer $ nucypher stake config --signer clef:///home//.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//.clef/clef.ipc --provider ~/.

˓→ethereum/geth.ipc

3. Conﬁgure nucypher for staking

Before initiating a stake, a setup step is required to configure nucypher for staking. This will create a JSON configuration 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 --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 conﬁgured 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. Currently, Worker nodes must perform one automated transaction every 7 days costing ~200k gas.

8 Chapter 2. Whitepapers NuCypher Documentation, Release 5.3.1

(nucypher)$ nucypher stake create Enter ethereum account password(0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf): Enter stake value in NU(15000NU- 45000NU)[45000]: 45000 Enter stake duration(4- 62863)[52]:4

STAGED STAKE

Staking address: 0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf ~ Chain -> ID # ~ Value -> 45000NU(45000000000000000000000 NuNits) ~ Duration -> 28 Days(4 Periods) ~ Enactment -> Mar 24 2021 17:00 PDT(period #2673) ~ Expiration -> Apr 21 2021 17:00 PDT(period #2677)

* Ursula Node Operator Notice * ------

By agreeing to stake 45000NU(45000000000000000000000 NuNits):

- Staked tokens will be locked for the stake duration.

- You are obligated to maintain a networked and available Ursula-Worker node bonded to the staker address 0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf for the

˓→duration of the stake(s)(4 periods).

- Agree to allow NuCypher network users to carry out uninterrupted re-encryption work orders at-will without interference.

Failure to keep your node online or fulfill re-encryption work orders will result in loss of staked NU as described in the NuCypher slashing protocol: https://docs.nucypher.com/en/latest/architecture/slashing.html.

Keeping your Ursula node online during the staking period and successfully producing correct re-encryption work orders will result in rewards paid out in ethers retro-actively and on-demand.

Accept ursula node operator obligation?[y/N]: y Publish staged stake to the blockchain?[y/N]: y Broadcasting APPROVEANDCALL Transaction(0.0821491982 ETH @ 261.575 gwei) TXHASH 0xf4fc7d6b674c83e4fd99fef64e194b7455fc4438a639e2973b09f09f3493ad10 Waiting 600 seconds for receipt

Stake initialization transaction was successful. ...

StakingEscrow address: 0x40Ca356d8180Ddc21C82263F9EbCeaAc6Cad7250

View your stakes by running 'nucypher stake list' or set your Ursula worker node address by running 'nucypher stake bond-worker'.

See https://docs.nucypher.com/en/latest/staking/running_a_worker.html

You will need to conﬁrm two transactions here.

2.2. Stake Initialization 9 NuCypher Documentation, Release 5.3.1

5. List existing stakes

Once you have created one or more stakes, you can view all active stakes for connected wallets:

(nucypher)$ nucypher stake list

Network Staker 0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf Worker not bonded ------Status Never Made a Commitment(New Stake) Restaking Yes Winding Down No Snapshots Yes Unclaimed Fees0 ETH Min fee rate 50 gwei ------

Slot Value Remaining Enactment Termination Boost Status

0 45000NU 5 Mar 24 2021 Apr 21 2021 1.10x DIVISIBLE

Caution: If the Worker in the list is shown as NO_WORKER_BONDED, it means that you haven’t yet bonded a Worker node to your Staker. Your staking account will be highlighted in red.

6. Bond a Worker

After initiating a stake, the staker must delegate access to a work address through bonding. There is a 1:1 relationship between the roles: A Staker may have multiple substakes but only ever has one Worker at a time.

Important: The Worker cannot be changed for a minimum of 2 periods (14 days) once bonded.

(nucypher)$ nucypher stake bond-worker Enter ethereum account password(0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf): Enter worker address: 0x6cf78fE4bD2a6573046d17f72f4C20462124Aa10 Commit to bonding worker 0x6cf78fE4bD2a6573046d17f72f4C20462124Aa10 to staker

˓→0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf for a minimum of2 periods?[y/N]: y ... This worker can be replaced or detached after period #2674 (2021-04-01 00:00:00+00:00)

Note: The worker’s address must be EIP-55 checksum valid, however, geth shows addresses in the lowercase normalized format. You can convert the normalized address to checksum format on etherscan or using the geth console:

$ geth attach ~/.ethereum/geth.ipc > eth.accounts ["0x63e478bc474ebb6c31568ff131ccd95c24bfd552",

˓→"0x270b3f8af5ba2b79ea3bd6a6efc7ecab056d3e3f",

˓→"0x45d33d1ff0a7e696556f36de697e5c92c2cccfae"] > web3.toChecksumAddress(eth.accounts[2]) "0x45D33d1Ff0A7E696556f36DE697E5C92C2CCcFaE"

10 Chapter 2. Whitepapers NuCypher Documentation, Release 5.3.1

After this step, you’re ﬁnished with the Staker, and you can proceed to Running a Worker.

2.3 Stake Management

Several administrative operations can be performed on active stakes:

Action Description restake Manage automatic reward re-staking prolong Prolong an existing stake’s duration winddown Manage winding down of stakes divide Create a new stake from part of an existing one increase Increase an existing stake’s value merge Merge two stakes into one remove-inactive Remove unused/inactive stakes rewards Preview and withdraw staking rewards events View blockchain events associated with a staker

2.3.1 Re-staking

As your Ursula performs work, all rewards are automatically added to your existing stake to optimize earnings. This feature, called re-staking, is enabled by default. To disable re-staking:

(nucypher)$ nucypher stake restake --disable

To enable re-staking again:

(nucypher)$ nucypher stake restake --enable

2.3.2 Prolong

Existing stakes can be extended by a number of periods as long as the resulting stake’s duration is not shorter than the minimum. To prolong an existing stake’s duration:

(nucypher)$ nucypher stake prolong --hw-wallet

Enter ethereum account password(0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf):

Network Staker 0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf Worker 0x6cf78fE4bD2a6573046d17f72f4C20462124Aa10 ------Status Never Made a Commitment(New Stake) Restaking Yes Winding Down No Snapshots Yes Unclaimed Fees0 ETH Min fee rate 50 gwei (continues on next page)

2.3. Stake Management 11 NuCypher Documentation, Release 5.3.1

(continued from previous page) ------

Slot Value Remaining Enactment Termination Boost Status

0 30000NU 5 Mar 24 2021 Apr 21 2021 1.10x DIVISIBLE

1 15000NU 9 Mar 24 2021 May 19 2021 1.17x EDITABLE

Select Stake(0,1):0 Enter number of periods to extend(1-62859):4 Publish stake extension of4 period(s) to the blockchain?[y/N]: y Broadcasting PROLONGSTAKE Transaction(0.012197658 ETH @ 274 gwei) TXHASH 0x049b98200c5949b75aa265ad4155f4ba02cb17a0309b16093bd7003c59fefb74 Waiting 600 seconds for receipt Successfully Prolonged Stake ...

Slot Value Remaining Enactment Termination Boost Status

0 30000NU 9 Mar 24 2021 May 19 2021 1.17x DIVISIBLE

1 15000NU 9 Mar 24 2021 May 19 2021 1.17x EDITABLE

2.3.3 Wind Down

The proportion of staking rewards received by a staker depends on the stake size and the remaining locked duration. When wind down is enabled, the locked duration decreases after each period which results in reduced staking yield. When disabled, the stake’s locked duration remains constant and improves staking yield. See Winding down for more information. Wind down is disabled by default.

Note: WorkLock participants have wind down enabled by default.

To start winding down an existing stake:

(nucypher)$ nucypher stake winddown --enable

To stop winding down:

12 Chapter 2. Whitepapers NuCypher Documentation, Release 5.3.1

(nucypher)$ nucypher stake winddown --disable

2.3.4 Snapshots

Taking snapshots is enabled by default. Snapshots must be enabled to participate in the DAO, but it has a slight cost in gas every time your staking balance changes. To stop taking snapshots:

(nucypher)$ nucypher stake snapshots --disable

To enable snapshots again:

(nucypher)$ nucypher stake snapshots --enable

2.3.5 Divide

Existing stakes can be divided into smaller sub-stakes, with different values and durations. Dividing a stake allows stakers to accommodate different liquidity needs since sub-stakes can have different durations. Therefore, a staker can liquidate a portion of their overall stake at an earlier time. To divide an existing stake:

(nucypher)$ nucypher stake divide --hw-wallet Enter ethereum account password(0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf): NOTE: Showing divisible stakes only

Slot Value Remaining Enactment Termination Boost Status

0 45000NU 5 Mar 24 2021 Apr 21 2021 1.10x DIVISIBLE

Select Stake(0):0 Enter target value(15000NU- 30000NU): 15000 Enter number of periods to extend:4

ORIGINAL STAKE

Staking address: 0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf ~ Original Stake: | - | 0xB548 |0| 45000 NU |4 periods | Mar 24 17:00 PDT - Apr

˓→21 17:00 PDT

STAGED STAKE

(continues on next page)

2.3. Stake Management 13 NuCypher Documentation, Release 5.3.1

(continued from previous page) Staking address: 0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf ~ Chain -> ID ~ Value -> 15000NU(15000000000000000000000 NuNits) ~ Duration -> 56 Days(8 Periods) ~ Enactment -> Mar 24 2021 17:00 PDT(period #2673) ~ Expiration -> May 19 2021 17:00 PDT(period #2681)

Publish stake division to the blockchain?[y/N]: y Broadcasting DIVIDESTAKE Transaction(0.019689812 ETH @ 273.5 gwei) TXHASH 0x641029fcfd4e263dc38774c5510f539f50c00004941ed0c4c737e53b67ade024 Waiting 600 seconds for receipt Successfully divided stake ...

Slot Value Remaining Enactment Termination Boost Status

0 30000NU 5 Mar 24 2021 Apr 21 2021 1.10x DIVISIBLE

1 15000NU 9 Mar 24 2021 May 19 2021 1.17x EDITABLE

2.3.6 Increase

Existing stakes can be increased by an amount of NU as long as the resulting staker’s locked value is not greater than the maximum. To increase an existing stake’s value:

(nucypher)$ nucypher stake increase --hw-wallet

2.3.7 Merge

Two stakes with the same ﬁnal period can be merged into one stake. This can help to decrease gas consumption in some operations. To merge two stakes:

(nucypher)$ nucypher stake merge --hw-wallet Enter ethereum account password(0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf):

Network Staker 0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf Worker 0x6cf78fE4bD2a6573046d17f72f4C20462124Aa10 (continues on next page)

14 Chapter 2. Whitepapers NuCypher Documentation, Release 5.3.1

(continued from previous page) ------Status Never Made a Commitment(New Stake) Restaking Yes Winding Down No Snapshots Yes Unclaimed Fees0 ETH Min fee rate 50 gwei ------

Slot Value Remaining Enactment Termination Boost Status

0 30000NU 9 Mar 24 2021 May 19 2021 1.17x DIVISIBLE

1 15000NU 9 Mar 24 2021 May 19 2021 1.17x EDITABLE

Select Stake(0,1):0 NOTE: Showing stakes with 2680 final period only

Slot Value Remaining Enactment Termination Boost Status

1 15000NU 9 Mar 24 2021 May 19 2021 1.17x EDITABLE

Select Stake(1):1 Publish merging of0 and1 stakes?[y/N]: y Broadcasting MERGESTAKE Transaction(0.013509688 ETH @ 278 gwei) TXHASH 0xef5ac787a22fc9a0a3e13a173e6e6db7603ec0be4473084d8b2b06a414328d62 Waiting 600 seconds for receipt Successfully Merged Stakes ...

Slot Value Remaining Enactment Termination Boost Status

0 45000NU 9 Mar 24 2021 May 19 2021 1.17x DIVISIBLE (continues on next page)

2.3. Stake Management 15 NuCypher Documentation, Release 5.3.1

(continued from previous page)

Note that some sub-stakes are inactive:[1] Run`nucypher stake list --all` to show all sub-stakes. Run`nucypher stake remove-inactive --all` to remove inactive sub-stakes; removal of

˓→inactive sub-stakes will reduce commitment gas costs.

2.3.8 Remove inactive sub-stake

When sub-stakes terminate, are merged or edited, there may be ‘unused’, inactive sub-stakes remaining on-chain. Con- tinued tracking of these unused sub-stakes adds unnecessary gas costs to node commitment operations. Consequently, removal of unused sub-stakes will reduce per period gas costs. Unused sub-stakes can be displayed by listing all sub-stakes and will be indicated by the INACTIVE status label.

(nucypher)$ nucypher stake list --all --hw-wallet Network Staker 0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf Worker 0x6cf78fE4bD2a6573046d17f72f4C20462124Aa10 ------Status Never Made a Commitment(New Stake) Restaking Yes Winding Down No Snapshots Yes Unclaimed Fees0 ETH Min fee rate 50 gwei ------

Slot Value Remaining Enactment Termination Boost Status

0 45000NU 9 Mar 24 2021 May 19 2021 1.17x DIVISIBLE

1 15000NU N/A Mar 24 2021 N/A N/A INACTIVE

To remove an unused sub-stake, run the following command and select the index of your INACTIVE sub-stake:

(nucypher)$ nucypher stake remove-inactive --hw-wallet Enter ethereum account password(0xB548378f13e9A2C7bEf66B890B46F2eD6Ed87fCf): Fetching inactive stakes

Slot Value Remaining Enactment Termination Boost Status

1 15000NU N/A Mar 24 2021 N/A N/A INACTIVE (continues on next page)

16 Chapter 2. Whitepapers NuCypher Documentation, Release 5.3.1

(continued from previous page)

Select Stake(1):1 Publish removal of1 stake?[y/N]: y Broadcasting REMOVEUNUSEDSUBSTAKE Transaction(0.012804726 ETH @ 288.2 gwei) TXHASH 0x942a70ee2adb5078fa6d8fa468f28d3e35386f90247035fdb5d19c34836200a0 Waiting 600 seconds for receipt Successfully Removed Stake ...

Slot Value Remaining Enactment Termination Boost Status

0 45000NU 9 Mar 24 2021 May 19 2021 1.17x DIVISIBLE

In order to make the operation as simple and cheap as possible, the removal algorithm simply relocates the last active sub-stake to the slot occupied by the currently inactive one, so you will notice a slight re-ordering of your sub-stakes. This is normal and doesn’t have any negative implications. For your convenience, run nucypher stake remove-inactive --all to remove all inactive sub-stakes using one CLI command to execute a series of removal transactions.

2.3.9 Collect Staker Rewards

NuCypher nodes earn two types of rewards: staking rewards (in NU) and policy fees (i.e., service fees in ETH). To collect these rewards use nucypher stake rewards withdraw with ﬂags --tokens and --fees (or even both). While staking rewards can only be collected to the original staker account, you can decide which account receives policy fees using the --withdraw-address ﬂag.

(nucypher)$ nucypher stake rewards withdraw --tokens --fees --staking-address

˓→0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f --hw-wallet Collecting 228.340621510864128225 NU from staking rewards... Confirm transaction WITHDRAW on hardware wallet...(500000 gwei @ 1000000000) Broadcasting WITHDRAW Transaction(500000 gwei @ 1000000000)... OK | 0x1c59af9353b016080fef9e93ddd03fde4260b6c282880db7b15fc0d4f28b2d34(124491 gas) Block #6728952 | 0xdadfef1767eb5bdc4bb4ad469a5f7aded44a87799dd2ee0edd6b6147951dbd3f See https://rinkeby.etherscan.io/tx/

˓→0x1c59af9353b016080fef9e93ddd03fde4260b6c282880db7b15fc0d4f28b2d34

Collecting1.0004E-13 ETH from policy fees... Confirm transaction WITHDRAW on hardware wallet...(42070 gwei @ 1000000000) (continues on next page)

2.3. Stake Management 17 NuCypher Documentation, Release 5.3.1

(continued from previous page) Broadcasting WITHDRAW Transaction(42070 gwei @ 1000000000)... OK | 0xba2afb864c24d783c5185429706c77a39e9053570de892a351dd86f7719fe58b(41656 gas) Block #6728953 | 0x1238f61e8adf8bf42e022f5182b692aca5ec5bf45c70871156ca540055daaa94 See https://rinkeby.etherscan.io/tx/

˓→0xba2afb864c24d783c5185429706c77a39e9053570de892a351dd86f7719fe58b

You can run nucypher stake accounts to verify that your staking compensation is indeed in your wallet. Use your favorite Ethereum wallet (MyCrypto or Metamask are suitable) to transfer out the compensation earned (NU tokens or ETH) after that. Note that you will need to conﬁrm two transactions if you collect both types of staking compensation if you use a hardware wallet.

Note: If you want to withdraw all tokens when all of them are unlocked - make sure to call nucypher stake mint ﬁrst to ensure the last reward is included

2.3.10 Query Staker Blockchain Events

As the Staker and its associated Worker interact with the StakingEscrow smart contract, various on-chain events are emitted. These events are outlined here, and are made accessible via the nucypher stake events CLI command.

Note: This command is limited to events from the StakingEscrow smart contract and the Staker address associated with the Staker’s conﬁguration ﬁle. For generic and network-wide event queries, see Network Events.

For simple Staker accounting, events such as CommitmentMade, Withdrawn, and Minted can be used. The output of each can be correlated using the period number. By default, the query is performed from block number 0 i.e. from the genesis of the blockchain. This can be modiﬁed using the --from-block option. For a full list of CLI options, run:

$ nucypher stake events --help

For example, to view all of the staking rewards received by the Staker thus far, run:

$ nucypher stake events --staking-address --provider -

˓→-event-name Minted

Reading Latest Chaindata... Retrieving events from block 0 to latest

------StakingEscrow Events ------

Minted: - (EventRecord) staker: , period: 18551, value:

˓→1234567890123456789012, block_number: 11070103 - (EventRecord) staker: , period: 18552, value:

˓→1234567890123456789012, block_number: 11076964 ...

18 Chapter 2. Whitepapers NuCypher Documentation, Release 5.3.1

1234567890123456789012 is in NuNits and equates to approximately 1234.57 NU (1 NU = 1018 NuNits). To view staking rewards received by the Staker from block number 11070000 to block number 11916688, run:

$ nucypher stake events --staking-address --provider -

˓→-event-name Minted --from-block 11070000 --to-block 11916688

Reading Latest Chaindata... Retrieving events from block 11070000 to 11916688

------StakingEscrow Events ------

Minted: - (EventRecord) staker: , period: 18551, value:

˓→1234567890123456789012, block_number: 11070103 - (EventRecord) staker: , period: 18552, value:

˓→1234567890123456789012, block_number: 11076964 ...

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.

To aid with management of this information, instead of outputting the information to the CLI, 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 a CSV file in the current directory with a default filename • --csv-file - write event information to a CSV file at the provided filepath For example,

$ nucypher stake events --staking-address --provider -

˓→-event-name Minted --csv

Reading Latest Chaindata... Retrieving events from block 0 to latest

------StakingEscrow Events ------

StakingEscrow::Minted events written to StakingEscrow_Minted_2021-02-09_15-23-25.csv

$ nucypher stake events --staking-address --provider -

˓→-event-name Minted --csv-file ~/Minted_Events.csv

Reading Latest Chaindata... Retrieving events from block 0 to latest

------StakingEscrow Events ------

StakingEscrow::Minted events written to //Minted_Events.csv

2.3. Stake Management 19 NuCypher Documentation, Release 5.3.1

2.4 Running a Worker

NuCypher staking operations are divided into two roles “Staker” and “Worker” - This Guide is for Workers.

2.4.1 Overview

Role in the Network

The Worker is the bonded delegate of a Staker and an active network node. Each staking account or “Staker” is bonded to exactly one Worker. Workers must remain online to provide uninterrupted re-encryption services to network users on-demand and perform periodic automated transactions to signal continued commitment to availability.

Core Components

Worker nodes have three core components: • Ethereum software wallet (keystore) • Local or hosted ethereum provider • Worker node; Local or cloud server

Minimum System Requirements

• Debian/Ubuntu (Recommended) • 20GB storage • 4GB RAM • x86 architecture • Static IP address • Exposed TCP port 9151 Workers can be run on cloud infrastructure – for example, Digital Ocean 4GB Basic Droplet satisﬁes requirements listed above.

2.4.2 1. Establish Ethereum Provider

Worker Ursula 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.

Note: Additional requirements are needed to run a local Ethereum node on the same system.

20 Chapter 2. Whitepapers NuCypher Documentation, Release 5.3.1

2.4.3 2. Establish Worker Ethereum Account

By default, all transaction and message signing requests are forwarded to the conﬁgured ethereum provider. When using a remote ethereum provider (e.g. Infura, Alchemy, other hosted node), a local transaction signer must be conﬁgured in addition to the broadcasting node. For workers this can be a software wallet, or clef. For more detailed information see Transaction Signing.

Caution: Stay safe handling ETH and NU: • Workers do not need NU for any reason; do not keep NU on the worker’s account. • Do not store large amounts of ETH on the worker; keep only enough to pay for gas fees. • Store the ethereum account password in a password manager when using a keystore.

Because worker nodes perform periodic automated transactions to signal continued commitment to providing service, The worker’s ethereum account must remain unlocked while the node is running. While there are several types of accounts workers can use, a software based wallet is the easiest.

Note: To create a new ethereum software account using the geth CLI 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.

2.4.4 3. Run Worker

Important: Before proceeding it is important to know that the worker must spend ETH to unlock staked NU. Periodic automated commitments are required to signal continued availability. Currently, Worker nodes must perform one commitment transaction every 7 days each costing ~200k gas. The --max-gas-price parameter is optional and can be used to set the maximum commitment gas price you are willing to spend. Workers will automatically retry and replace any previous commitment attempts. Too low of a gas price may result in missed commitments.

Run Worker with Docker (Recommended)

Setup Docker

1. Install Docker 2. (Optional) Follow these post install instructions: https://docs.docker.com/install/linux/linux-postinstall/ 3. Get the latest nucypher image: docker pull nucypher/nucypher:latest

2.4. Running a Worker 21 NuCypher Documentation, Release 5.3.1

Export Worker Environment Variables

# Passwords used for both creation and unlocking export NUCYPHER_KEYSTORE_PASSWORD= export NUCYPHER_WORKER_ETH_PASSWORD=

Initialize a new Wor