From 67582bd2a8dbe4792dc3252452b6519e695a7ae4 Mon Sep 17 00:00:00 2001 From: Karl Wuest Date: Mon, 14 Oct 2024 16:09:28 -0600 Subject: [PATCH] feat: added overview of staking --- docs/usage/stake.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/usage/stake.md b/docs/usage/stake.md index 133025c1..f92d4628 100644 --- a/docs/usage/stake.md +++ b/docs/usage/stake.md @@ -1,4 +1,30 @@ -# Stake and Unstake +# Staking + +In Walrus, anyone can delegate stake to storage nodes and, by doing so, influence, which storage +nodes get selected for the committee in future epochs, and how many shards these nodes will hold. +Shards are assigned to storage nodes every epoch, roughly proportional to the amount of stake +that was delegated to them. By staking with a storage node, users also earn rewards, as they +will receive a share of the storage fees. + +Since moving shards from one storage node to another requires transferring a lot of data and +storage nodes potentially need to expand their storage capacity, the selection of the committee +for the next epoch is done ahead of time, in the middle of the previous epoch. This provides +sufficient time to storage node operators to provision additional resources, if needed. + +For stake to affect the shard distribution in epoch `e` and become "active", it must be staked +before the committee for this epoch has been selected, meaning that it has to be staked before +the midpoint of epoch `e - 1`. If it is staked after that point in time, it will only influence +the committee selection for epoch `e + 1` and thus only become active, and accrue rewards, in +that epoch. + +Unstaking has a similar delay: because unstaking funds only has an effect on the committee in +the next committee selection, the stake will remain active until that committee takes over. +This means that, to unstake at the start of epoch `e`, the user needs to "request withdrawal" +before the midpoint of epoch `e - 1`. Otherwise, i.e., if the user unstakes after this point, +the stake will remain active, and continue to accrue rewards, throughout epoch `e`, and the +balance and rewards will be available to withdraw at the start of epoch `e + 1`. + +## How to stake