Several administrative operations can be performed on active stakes:
Manage automatic reward re-staking
Prolong an existing stake’s duration
Manage winding down of stakes
Create a new stake from part of an existing one
Increase an existing stake’s value
Merge two stakes into one
Remove unused/inactive stakes
Collect earned staking rewards and/or policy fees
View blockchain events associated with a staker
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
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
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.
WorkLock participants have wind down enabled by default.
To start winding down an existing stake:
(nucypher)$ nucypher stake winddown --enable
To stop winding down:
(nucypher)$ nucypher stake winddown --disable
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
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 Select Stake: 0 Enter target value (15000 NU - 16437.841006996376688377 NU): 15000 Enter number of periods to extend: 20 ══════════════════════════════ ORIGINAL STAKE ════════════════════════════ Staking address: 0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f ~ Original Stake: | - | 0x270b | 0x45D3 | 0 | 31437.841006996376688377 NU | 33 periods . | Jun 19 20:00 EDT - Jul 22 20:00 EDT ══════════════════════════════ STAGED STAKE ══════════════════════════════ Staking address: 0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f ~ Chain -> ID # 4 | Rinkeby ~ Value -> 15000 NU (15000000000000000000000 NuNits) ~ Duration -> 53 Days (53 Periods) ~ Enactment -> Jun 19 20:00 EDT (period #18433) ~ Expiration -> Aug 11 20:00 EDT (period #18486) ═════════════════════════════════════════════════════════════════════════ Publish stake division to the blockchain? [y/N]: y Enter password to unlock account 0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f: Confirm transaction DIVIDESTAKE on hardware wallet... (76058 gwei @ 1000000000) Broadcasting DIVIDESTAKE Transaction (76058 gwei @ 1000000000)... Successfully divided stake OK | 0x74ddd647de6eaca7ef0c485706ef526001d959a3c2eaa98699e087a7d259d08b (75349 gas) Block #6711982 | 0xd1c6d6df257ecd05632550565edb709ae577066a60ca433bc4d23de5fb332009 See https://rinkeby.etherscan.io/tx/0x74ddd647de6eaca7ef0c485706ef526001d959a3c2eaa98699e087a7d259d08b Network <NETWORK_NAME> ═══════════════════════════════ Staker 0x270b3f8af5ba2B79ea3Bd6a6Efc7ecAB056d3E3f ════ Worker 0x45D33d1Ff0A7E696556f36DE697E5C92C2CCcFaE ════ -------------- ---------------- Status Committed #18436 Restaking Yes (Unlocked) Winding Down No Unclaimed Fees 0 ETH Min fee rate 0 ETH -------------- ---------------- ╒═══════╤═════════════════════════════╤═════════════╤═════════════╤═══════════════╕ │ Idx │ Value │ Remaining │ Enactment │ Termination │ ╞═══════╪═════════════════════════════╪═════════════╪═════════════╪═══════════════╡ │ 0 │ 16437.841006996376688377 NU │ 31 │ Jun 19 2020 │ Jul 22 2020 │ ├───────┼─────────────────────────────┼─────────────┼─────────────┼───────────────┤ │ 1 │ 15000 NU │ 51 │ Jun 19 2020 │ Aug 11 2020 │ ╘═══════╧═════════════════════════════╧═════════════╧═════════════╧═══════════════╛
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
Two stakes with the same final 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
Remove unused sub-stake¶
When sub-stakes terminate, are merged or edited, there may be ‘unused’, inactive sub-stakes remaining on-chain. Continued tracking of these unused sub-stakes adds unnecessary gas costs to daily operations. Consequently, removal of unused sub-stakes will reduce daily 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 ... ╒═══════╤═══════════════╤═════════════╤═════════════╤═══════════════╤═══════════╕ │ Idx │ Value │ Remaining │ Enactment │ Termination │ Status │ ╞═══════╪═══════════════╪═════════════╪═════════════╪═══════════════╪═══════════╡ │ 0 │ 123456.789 NU │ -4 │ Oct 15 2020 │ Nov 19 2020 │ INACTIVE │ ├───────┼───────────────┼─────────────┼─────────────┼───────────────┼───────────┤ │ 1 │ 123456.789 NU │ 27 │ Oct 15 2020 │ Dec 20 2020 │ DIVISIBLE │ ├───────┼───────────────┼─────────────┼─────────────┼───────────────┼───────────┤
To remove an unused sub-stake, run the following command and select the index
(nucypher)$ nucypher stake remove-unused --hw-wallet
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.
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 collect-reward with flags
(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 <ETH_ADDRESS> flag.
(nucypher)$ nucypher stake collect-reward --staking-reward --policy-fee --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 Collecting 1.0004E-13 ETH from policy fees... Confirm transaction WITHDRAW on hardware wallet... (42070 gwei @ 1000000000) 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
Note that you will need to confirm two transactions if you collect both types of staking compensation if you use a hardware wallet.
If you want to withdraw all tokens when all of them are unlocked -
make sure to call
nucypher stake mint first to ensure the last reward is included
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.
This command is limited to events from the StakingEscrow smart contract and the Staker address associated with the Staker’s configuration file. For generic and network-wide event queries, see Network Events.
For simple Staker accounting, events such as
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 modified
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 <STAKER ADDRESS> --provider <PROVIDER URI> --event-name Minted Reading Latest Chaindata... Retrieving events from block 0 to latest --------- StakingEscrow Events --------- Minted: - (EventRecord) staker: <STAKER ADDRESS>, period: 18551, value: 1234567890123456789012, block_number: 11070103 - (EventRecord) staker: <STAKER ADDRESS>, period: 18552, value: 1234567890123456789012, block_number: 11076964 ...
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 <STAKER ADDRESS> --provider <PROVIDER URI> --event-name Minted --from-block 11070000 --to-block 11916688 Reading Latest Chaindata... Retrieving events from block 11070000 to 11916688 --------- StakingEscrow Events --------- Minted: - (EventRecord) staker: <STAKER ADDRESS>, period: 18551, value: 1234567890123456789012, block_number: 11070103 - (EventRecord) staker: <STAKER ADDRESS>, period: 18552, value: 1234567890123456789012, block_number: 11076964 ...
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 <FILEPATH>- write event information to a CSV file at the provided filepath
$ nucypher stake events --staking-address <STAKER ADDRESS> --provider <PROVIDER URI> --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 <STAKER ADDRESS> --provider <PROVIDER URI> --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 /<HOME DIRECTORY>/Minted_Events.csv