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-unused

Remove unused/inactive stakes

collect-rewards

Collect earned staking rewards and/or policy fees

events

View blockchain events associated with a staker

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

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

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:

(nucypher)$ nucypher stake winddown --disable

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

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

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   │
╞═══════╪═════════════════════════════╪═════════════╪═════════════╪═══════════════╡
│   016437.841006996376688377 NU │         31  │ Jun 19 2020 │ Jul 22 2020   │
├───────┼─────────────────────────────┼─────────────┼─────────────┼───────────────┤
│   115000 NU                    │         51  │ Jun 19 2020 │ Aug 11 2020   │
╘═══════╧═════════════════════════════╧═════════════╧═════════════╧═══════════════╛

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

Merge

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    │
╞═══════╪═══════════════╪═════════════╪═════════════╪═══════════════╪═══════════╡
│     0123456.789 NU │          -4 │ Oct 15 2020 │ Nov 19 2020   │ INACTIVE  │
├───────┼───────────────┼─────────────┼─────────────┼───────────────┼───────────┤
│     1123456.789 NU │          27 │ Oct 15 2020 │ Dec 20 2020   │ DIVISIBLE │
├───────┼───────────────┼─────────────┼─────────────┼───────────────┼───────────┤

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

(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 --staking-reward and --policy-fee (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 that.

Note that you will need to confirm 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 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.

Note

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 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 modified 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 <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
  ...

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 <FILEPATH> - write event information to a CSV file at the provided filepath

For example,

$ 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