NuCypher staking operations are divided into two roles “Staker” and “Worker” - This Guide is for Stakers.
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:
Hosted or Remote Ethereum Node (Infura, Geth, etc.)
Hardware or Software Wallet (Trezor, Ledger, Keyfile)
At least 15,000 NU
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.
Obtain and secure NU
nucypheron Staker’s system (pip Installation Reference and docker are supported)
Configure nucypher CLI for staking (3. Configure nucypher for staking)
Bond a Worker to your Staker using the worker’s ethereum address (see 6. Bond a worker)
Manage active stakes (Stake Management)
Once NU is locked in the staking escrow contract, a worker node must be run to unlock it. Worker’s make periodic automated commitments which spend ~200k gas each transaction. Be sure to consider this operational cost when locking NU.
If you are running an Ibex testnet node, testnet tokens can be obtained by joining the
Discord server and typing
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>
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>
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.
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.
The default location for the clef IPC file is
$ 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 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 <SIGNER URI> --provider <PROVIDER>
If you are using NuCypher’s Ibex testnet, passing the network name is required
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.
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 24 hours costing ~200k gas.
(nucypher)$ nucypher stake create Account -- ------------------------------------------ 0 0x63e478bc474eBb6c31568ff131cCd95C24bfD552 1 0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f 2 0x45D33d1Ff0A7E696556f36DE697E5C92C2CCcFaE Select index of staking account : 1 Selected 1: 0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f Enter stake value in NU (15000 NU - 30000 NU) : 30000 Enter stake duration (30 - 47103) : 30 ══════════════════════════════ STAGED STAKE ══════════════════════════════ Staking address: 0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f ~ Chain -> ID # <CHAIN_ID> ~ Value -> 30000 NU (30000000000000000000000 NuNits) ~ Duration -> 30 Days (30 Periods) ~ Enactment -> Jun 19 20:00 EDT (period #18433) ~ Expiration -> Jul 19 20:00 EDT (period #18463) ═════════════════════════════════════════════════════════════════════════ * Ursula Node Operator Notice * ------------------------------- By agreeing to stake 30000 NU (30000000000000000000000 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 0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f for the duration of the stake(s) (30 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 violation of re-encryption work orders will result in the loss of staked tokens as described in the NuCypher slashing protocol. 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
You will need to confirm two transactions here.
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 <NETWORK_NAME> ═══════════════════════════════ Staker 0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f ════ Worker NO_WORKER_BONDED ════ -------------- ----------------------------------- Status Never Made a Commitment (New Stake) Restaking Yes (Unlocked) Winding Down No Unclaimed Fees 0 ETH Min fee rate 0 ETH -------------- ----------------------------------- ╒═══════╤══════════╤═════════════╤═════════════╤═══════════════╕ │ Idx │ Value │ Remaining │ Enactment │ Termination │ ╞═══════╪══════════╪═════════════╪═════════════╪═══════════════╡ │ 0 │ 30000 NU │ 31 │ Jun 19 2020 │ Jul 19 2020 │ ╘═══════╧══════════╧═════════════╧═════════════╧═══════════════╛
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.
Stakers accounts without a worker bonded 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.
The Worker cannot be changed for a minimum of 2 periods (48 hours) once bonded.
(nucypher)$ nucypher stake bond-worker Account -- ------------------------------------------ 0 0x63e478bc474eBb6c31568ff131cCd95C24bfD552 1 0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f 2 0x45D33d1Ff0A7E696556f36DE697E5C92C2CCcFaE Select index of staking account : 1 Selected 1: 0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f Enter worker address: 0x45D33d1Ff0A7E696556f36DE697E5C92C2CCcFaE Commit to bonding worker 0x45D33d1Ff0A7E696556f36DE697E5C92C2CCcFaE to staker 0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f for a minimum of 2 periods? [y/N]: y
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) "0x45D33d1Ff0A7E696556f36DE697E5C92C2CCcFaE"
After this step, you’re finished with the Staker, and you can proceed to Running a Worker.