stake-contract: Add docs comments #3304
Conversation
moCello
force-pushed
the
mocello/3303-stake_docs
branch
2 times, most recently
from
c218dd7 to
569dc6e
Compare
moCello
force-pushed
the
mocello/3303-stake_docs
branch
2 times, most recently
from
466393d to
4ad5d16
Compare
moCello
force-pushed
the
mocello/3303-stake_docs
branch
from
4ad5d16 to
fcbaa2e
Compare
| //! rewards and penalties. | ||
| //! | ||
| //! For a detailed explanation of staking mechanisms refer to the | ||
| //! [Dusk Whitepaper](https://dusk-cms.ams3.digitaloceanspaces.com/Dusk_Whitepaper_2024_4db72f92a1.pdf) |
There was a problem hiding this comment.
Not sure I would link the whitepaper to be honest... it's not that it's much more detailed than the docs and having a link to digitaloceanspaces feels a bit awkward to be.
There was a problem hiding this comment.
Is there a more suitable link to the docs?
There was a problem hiding this comment.
I would simply leave the one below (docs.dusk.network). But you can also add a link to https://github.com/dusk-network/dusk-protocol
|
|
||
| /// Contract keeping track of each public key's stake. | ||
| /// Represents the main state structure for staking operations. | ||
| /// Tracks active stakes, burnt amounts, and configurations. |
There was a problem hiding this comment.
There is actually only one stake per provisioner.
I guess this structure is obsolete and we don't update it because it would be a breaking change. But maybe we could add a note somewhere.
@herr-seppia can you confirm this?
| /// has a maturation period, after which it is considered valid and the key | ||
| /// eligible to participate in the consensus. | ||
| /// A caller can stake Dusk, and have it attached to a provisioner's account | ||
| /// public key. This stake has a maturation period of minimal one [`EPOCH`], |
There was a problem hiding this comment.
To be precise, the maturation period corresponds to the number of blocks until the end of the epoch in which the stake occurred, plus an entire extra epoch.
Put simply, if a stake is created in epoch X, it becomes eligible at the beginning of the epoch X+2.
| /// Rewards may be received by a public key regardless of whether they have a | ||
| /// valid stake. | ||
| /// # Fields | ||
| /// - `burnt_amount`: Total amount of tokens burnt due to penalties or other |
There was a problem hiding this comment.
I would avoid using token here, given it meaning at the application layer
| &self.config | ||
| } | ||
|
|
||
| /// Configures the [`StakeState`] with a new staking configuration. |
There was a problem hiding this comment.
| /// Configures the [`StakeState`] with a new staking configuration. | |
| /// Updates the configuration of a [`StakeState`]. |
just a suggestion
|
|
||
| /// Gets a mutable reference to the stake of a given `keys`. | ||
| /// | ||
| /// If said stake doesn't exist, a default one is inserted and a mutable |
There was a problem hiding this comment.
Bit weird to start with this sentence. Can we add a one-liner descriptor like for other methods?
| /// Distributes rewards to multiple stakeholders. | ||
| /// | ||
| /// # Parameters | ||
| /// - `rewards`: A vector of reward details. |
There was a problem hiding this comment.
| /// - `rewards`: A vector of reward details. | |
| /// - `rewards`: A vector with the rewards to assign. |
| } | ||
|
|
||
| /// Slash the given `to_slash` amount from an `account`'s reward | ||
| /// Penalizes a given account by slashing a specified amount. |
There was a problem hiding this comment.
Locks a given amount from a stake as a penalization.
This is also known as "soft" slash
| } | ||
|
|
||
| /// Slash the given `to_slash` amount from an `account`'s stake. | ||
| /// Performs a severe penalty by slashing a specified amount of stake from |
There was a problem hiding this comment.
Burns the specified amount from a given slash as penalty for a hard fault
| } | ||
|
|
||
| /// Sets the burnt amount | ||
| /// Sets the total amount of burnt tokens within the staking state. Burnt |
There was a problem hiding this comment.
As before, I'd rather not use token in this context. I'd say coins, or simply DUSK
Resolves #3303