Staking branch (#1360)

* First staking draft

* deleted some of the procedures outdated content

* Refined and updated all staking and delegation-related docs.

* Deleted unnecessary sentence in entering-staking.adoc

* Deleted some of the prerequisites in the procedures

Author: dor-starkware

components/Starknet/modules/staking/pages/architecture.adoc

@@ -1,5 +1,5 @@
 [id="staking_architecture"]
-= Staking Architecture (WIP) 🚧
+= Staking Architecture
 
 Staking on Starknet is designed to enhance network security and decentralization by allowing users to stake their STRK tokens directly or delegate them to other validators. The architecture is modular, with different contracts handling specific responsibilities to ensure flexibility, security, and ease of upgrades. For more details on the staking architecture, visit the following link: https://github.com/starkware-libs/starknet-staking[Starknet Staking Repository].
 

components/Starknet/modules/staking/pages/claiming-rewards.adoc

@@ -1,5 +1,5 @@
 [id="claiming-rewards"]
-= Claiming Rewards (WIP) 🚧
+= Claiming Rewards
 
 :description: How to claim your staking rewards on Starknet by directly interacting with the staking or delegation pooling contracts.
 

components/Starknet/modules/staking/pages/delegating-stake.adoc

@@ -1,5 +1,5 @@
 [id="delegating-stake"]
-= Delegating Stake (WIP) 🚧
+= Delegating Stake
 
 :description: How to delegate your stake to a validator on Starknet by interacting directly with the staking and delegation pooling contracts.
 

components/Starknet/modules/staking/pages/entering-staking.adoc

@@ -1,5 +1,5 @@
 [id="entering-staking"]
-= Becoming a Validator (WIP) 🚧
+= Becoming a Validator
 
 :description: How to enter the staking protocol on Starknet by interacting directly with the staking contract.
 
@@ -38,5 +38,7 @@ on Starknet for the transfer of tokens from your address to the staking contract
 
 .Secured hardware wallets:
 Ledger hardware wallet is supported through:
-* link:https://braavos.app/wallet-features/ledger-on-braavos/[Braavos] wallet
-* link:https://www.argent.xyz/blog/how-to-use-your-hardware-wallet-with-argent/[Argent] wallet
+
+* link:https://braavos.app/wallet-features/ledger-on-braavos/[Braavos wallet]
+
+* link:https://www.argent.xyz/blog/how-to-use-your-hardware-wallet-with-argent/[Argent wallet]

components/Starknet/modules/staking/pages/exiting-staking.adoc

@@ -1,5 +1,5 @@
 [id="exiting-staking"]
-= Exiting the Staking Protocol (WIP) 🚧
+= Exiting the Staking Protocol
 
 :description: How to exit the staking protocol on Starknet by unstaking as a validator or undelegating as a delegator through direct interaction with the staking or delegation pooling contracts.
 
@@ -40,7 +40,7 @@ Ensure that enough time has passed since signaling your unstake intent. If the w
 
 == Undelegating as a Delegator
 
-Delegators can undelegate their stake from a validator's delegation pool by following a similar process.
+Delegators can undelegate part or all of their stake from a validator's delegation pool by following a similar process. The `amount` parameter determines how much of the stake will be undelegated, and it must be less than or equal to the total delegated amount.
 
 .Prerequisites
 
@@ -53,15 +53,16 @@ Delegators can undelegate their stake from a validator's delegation pool by foll
 1. **Signal Undelegation Intent:**
 . Using a Starknet block explorer, navigate to the delegation pooling contract.
 . In the contract interface, locate and select the `exit_delegation_pool_intent` function.
-. Submit the transaction to initiate the undelegation process. This will record the undelegation intent, pause rewards collection, and set a waiting period.
+. Enter the `amount` parameter, which determines the size of the undelegation. The amount must be less than or equal to your total delegated amount.
+. Submit the transaction to initiate the undelegation process. This will record the undelegation intent for the specified amount, pause rewards collection, and set a waiting period.
 
 2. **Finalize Undelegation:**
 . After the waiting period has passed, return to the delegation pooling contract.
 . In the contract interface, locate and select the `exit_delegation_pool_action` function.
 . Enter the following parameters:
 +
 * In *`pool_member`*, enter the delegator's address.
-. Submit the transaction to finalize the undelegation process and transfer the undelegated STRK tokens back to the delegator's account.
+. Submit the transaction to finalize the undelegation process and transfer the undelegated STRK tokens (based on the amount previously specified) back to the delegator's account.
 
 [NOTE]
 ====
@@ -70,7 +71,7 @@ Any address can initiate the `exit_delegation_pool_action` function once the wai
 
 [NOTE]
 ====
-Ensure that enough time has passed since signaling your undelegation intent. If the waiting period has not expired, the `exit_delegation_pool_action` function will fail.
+Ensure that enough time has passed since signaling your undelegation intent. If the waiting period has not expired, the `exit_delegation_pool_action` function will fail. Additionally, ensure the `amount` provided in the initial intent matches the intended undelegation size.
 ====
 
 == Additional Notes

components/Starknet/modules/staking/pages/handling_staking_events.adoc

@@ -1,5 +1,5 @@
 [id="increasing-stake"]
-= Increasing Stake (WIP) 🚧
+= Increasing Stake
 
 :description: How to increase your stake on Starknet by interacting directly with the staking or delegation pooling contracts.
 

components/Starknet/modules/staking/pages/increasing-staking.adoc

@@ -1,9 +1,9 @@
 [id="managing-staking-and-delegation-operations"]
-= Managing Staking and Delegation Operations (WIP) 🚧
+= Managing Staking and Delegation Operations
 
 :description: How validators and delegators can manage staking and delegation settings on Starknet by interacting directly with the staking and delegation pooling contracts.
 
-This guide outlines how both **validators** and **delegators** can manage various aspects of their staking and delegation activities on Starknet. Validators can perform operations such as opening delegation pools, updating commission rates, and changing operational and reward addresses. Delegators can manage their participation by changing their reward addresses associated with delegation pools.
+This guide outlines how both validators and delegators can manage various aspects of their staking and delegation activities on Starknet. Validators can perform operations such as opening delegation pools and updating commission rates. Delegators can manage their participation by changing their reward addresses associated with delegation pools.
 
 == Managing Staking Operations as a Validator
 
@@ -42,7 +42,11 @@ Validators can update the commission rate of their delegation pool using the `up
 * **`commission`**: Enter the new commission rate, which must be equal to or less than the current rate, expressed as a percentage with precision (where 10000 represents 100%). For example, to set a 5% commission, enter `500`.
 . Submit the transaction to update the commission rate.
 
-=== Changing the Operational Address
+== Address Management
+
+Both validators and delegators can update their associated addresses within their staking and delegation contracts. This section outlines how to change the operational and reward addresses.
+
+=== Changing the Operational Address (Validators)
 
 Validators can change their operational address by interacting with the `change_operational_address` function.
 
@@ -55,28 +59,16 @@ Validators can change their operational address by interacting with the `change_
 * **`operational_address`**: Enter the new operational address.
 . Submit the transaction to update the operational address.
 
-=== Changing the Reward Address
+=== Changing the Reward Address (Validators and Delegators)
 
-Validators can update the reward address associated with their staking contract using the `change_reward_address` function.
+Both validators and delegators can update their reward address using the `change_reward_address` function.
 
 .Procedure
 
-. Using a Starknet block explorer, navigate to the **staking contract**.
-. In the contract interface, locate and select the `change_reward_address` function.
-. Enter the following parameter:
+. Using a Starknet block explorer, navigate to the appropriate contract:
 +
-* **`reward_address`**: Enter the new reward address.
-. Submit the transaction to change the reward address.
-
-== Managing Delegation Settings as a Delegator
-
-=== Changing the Reward Address
-
-Delegators can change their reward address by interacting with the `change_reward_address` function in the delegation pooling contract.
-
-.Procedure
-
-. Using a Starknet block explorer, navigate to the delegation pooling contract associated with your delegation.
+* For validators: Navigate to the **staking contract**.
+* For delegators: Navigate to the **delegation pooling contract**.
 . In the contract interface, locate and select the `change_reward_address` function.
 . Enter the following parameter:
 +
@@ -85,4 +77,4 @@ Delegators can change their reward address by interacting with the `change_rewar
 
 == Additional Information
 
-For more information on how the staking and delegation pooling systems work, refer to the xref:architecture.adoc#staking-contract[Staking Contract Architecture].
+For more information on how the staking and delegation pooling systems work, refer to the xref:architecture.adoc#staking-contract[Staking Contract Architecture].

components/Starknet/modules/staking/pages/managing-staking-and-delegation-operations.adoc

@@ -1,5 +1,5 @@
 [id="staking_overview"]
-= Staking Overview (WIP) 🚧
+= Staking Overview
 
 
 
@@ -28,8 +28,8 @@ STRK tokens never leave the Starknet protocol during these operations.
 
 The staking protocol features two main options:
 
-* _Staking_: Users can stake any amount of STRK, with a minimum threshold set at 20,000 STRK. Validators are expected to run full nodes and eventually handle additional responsibilities as the protocol evolves.
-* _Stake Delegation_: Users can delegate their STRK to validators without running their own nodes. Delegators share in the rewards earned by the validators they choose.
+* _Staking_: Users can stake any amount of STRK, with a minimum threshold set at 20,000 STRK. Validators are expected to run full nodes and eventually handle additional responsibilities as the protocol evolves. Validators can choose whether to allow delegation.
+* _Stake Delegation_: Users can delegate their STRK to validators without running their own nodes, if the validator allows delegation. Delegators share in the rewards earned by the validators they choose.
 
 Validators and delegators can both unstake their funds, subject to network-defined latencies for security.
 
@@ -67,8 +67,8 @@ For the first stage, stem:[C] is proposed to be 1.6%.
 
 === Latencies
 
-* **Current Version**: Immediate entry and exit from the staking protocol. However, funds are subject to a 21-day security lockup after withdrawal.
-* **Future Versions**: Introduction of epochs to determine entry/exit latencies and continued 21-day lockup after withdrawal.
+* **Current Version**: Immediate entry and exit from the staking protocol. However, funds are subject to a 21-day security lockup after signaling unstake intent.
+* **Future Versions**: Introduction of epochs to determine entry/exit latencies and continued 21-day lockup after signaling unstake intent.
 
 [NOTE]
 ====
@@ -82,6 +82,6 @@ The proposed economic parameters are:
 * **Minimum STRK for Staking:** 20,000 STRK
 * **Withdrawal Security Lockup:** 21 days
 * **Minting Curve Yearly Inflation Cap (stem:[C]):** 1.6% (see link:https://community.starknet.io/t/staking-on-starknet-voting-proposal/114442/[here] for the relevant voting proposal)
-* **Commission Policy Parameter (stem:[CP]):** Set by the validator (0 - 1)
+* **Commission Policy Parameter (stem:[CP]):** Set by the validator (0 - 1), and can only be lowered once set.
 
 These values are our proposed starting points for this version of the protocol. As part of the rationale behind this version, they are subject to change and may be adjusted to better suit the protocol’s needs under the proper governance procedures.

components/Starknet/modules/staking/pages/overview.adoc

@@ -0,0 +1,49 @@
+[id="staking-events-and-read-functions"]
+= Staking Events and Read Functions
+
+:description: How to manage and respond to events emitted by the Starknet staking protocol.
+
+Staking events provide critical information about changes in the staking process, such as balance updates, delegation pool creation, and exit intents. Read functions allow you to query important staking details. For a complete list of events and read functions, including keys and data, please refer to the official Starknet staking repository (link:https://github.com/starkware-libs/starknet-staking[Starknet Staking Repo]) and the spec file (link:https://github.com/starkware-libs/starknet-staking/blob/main/docs/spec.md[spec.md]).
+
+== Staking Events
+
+Staking events provide a way to track the state and actions of the staking process in real time. The following are the relevant events:
+
+- `StakeBalanceChanged`: Emitted when a staker’s balance changes, either through direct staking or delegation.
+- `NewDelegationPool`: Emitted when a new delegation pool is created by a validator, marking the pool’s deployment.
+- `StakerExitIntent`: Emitted when a staker signals their intent to unstake, setting a future timestamp for exit.
+- `StakerRewardAddressChanged`: Emitted when a staker changes their reward address.
+- `OperationalAddressChanged`: Emitted when a staker changes their operational address.
+- `GlobalIndexUpdated`: Emitted when the global index used to calculate staking rewards is updated.
+- `NewStaker`: Emitted when a new staker joins the protocol and locks their tokens in the staking contract.
+- `CommissionChanged`: Emitted when a validator updates the commission rate for their delegation pool.
+- `StakerRewardClaimed`: Emitted when a staker or delegation pool claims their rewards.
+- `DeleteStaker`: Emitted when a staker is removed from the protocol.
+- `RewardsSuppliedToDelegationPool`: Emitted when rewards are supplied to a validator's delegation pool.
+- `Paused`: Emitted when the staking contract is paused.
+- `Unpaused`: Emitted when the staking contract is unpaused.
+
+These events help to track changes and facilitate automations or actions based on the state of the staking contract.
+
+== Read Functions
+
+These read functions allow you to query essential information from the staking contract. Use these functions to retrieve details about stakers, staking parameters, and the total amount staked.
+
+.Procedure
+
+. Using a Starknet block explorer, navigate to the staking.
+. In the contract interface, locate and select the relevant read function.
+. Enter the required parameters (if applicable).
+. Submit the query to retrieve the requested information.
+
+The following read functions are available:
+
+- `state_of`: Retrieves the staking details of a given staker, including their balance and reward address.
+  Enter the following parameter:
+  * `staker_address` - The address of the staker whose details you want to query.
+
+- `contract_parameters`: Retrieves the parameters of the staking contract, including the minimum stake amount and the reward supplier contract.
+
+- `get_total_stake`: Returns the total amount of STRK tokens currently staked in the protocol.
+
+- `is_paused`: Checks whether the staking contract is currently paused.