Staking branch (#1367)

* 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

* Update staking: Operator contract, allowance change, Sepolia addresses, and index update interval

Author: dor-starkware

components/Starknet/modules/cli/pages/starkli.adoc

@@ -3,7 +3,7 @@
 
 [WARNING]
 ====
-The Starknet CLI is deprecated. Instead, use xref:tools:devtools.adoc#starkli[StarkLi CLI].
+The Starknet CLI is deprecated. Instead, use link: https://docs.starknet.io/tools/devtools/overview/[StarkLi CLI].
 ====
 
 [id="basic_command_line_syntax"]

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

@@ -7,16 +7,17 @@ Staking on Starknet is designed to enhance network security and decentralization
 
 Staking is divided into several key components, each responsible for different aspects of the staking process.
 
-The following contracts handle the core functionalities of the staking system:
-
 .Contracts of the Staking Architecture
 [cols='1,8']
 |===
 | Contract
 | Description
 
+| Operator Contract
+| Acts as the access point for all interactions with the staking system, wrapping around the staking contract. It enforces access control and whitelisting, ensuring that only authorized users can perform staking operations.
+
 | Staking Contract
-| The central contract that manages the staking process. It handles direct staking, rewards distribution, and interactions with delegation pools. Validators interact with this contract to stake their tokens, claim rewards, and initiate unstaking.
+| The central contract that manages the staking process. It handles direct staking, rewards distribution, and interactions with delegation pools. Validators interact with this contract through the Operator contract to stake their tokens, claim rewards, and initiate unstaking.
 
 | Delegation Pooling Contract
 | This contract manages the delegation process, allowing delegators to assign their tokens to a validator for staking. The contract is responsible for tracking each delegator's share, calculating their rewards, and managing the delegation and unstaking processes.
@@ -45,36 +46,47 @@ The following data structures are stored within the contracts and play a crucial
 
 For more technical details, you can refer to the full staking specification document available in: https://github.com/starkware-libs/starknet-staking/blob/main/docs/spec.md[Staking Repository Spec].
 
-== Staking Contract
+== Operator Contract
 
-The staking contract is the core of the staking system. It manages the lifecycle of validators, from the initial stake to claiming rewards and unstaking. The contract ensures that the validator's tokens are securely locked and that rewards are distributed according to the minting curve.
+The operator contract serves as the first point of interaction for all users. It manages access control, ensuring that only authorized users can stake, claim rewards, and interact with the staking system. The operator contract forwards user requests to the relevant contracts (e.g., staking contract) and includes features such as whitelisting, which restricts access to specific users if activated.
 
 *Key Functions and Responsibilities*: +
-`stake`: Allows users to stake their STRK tokens directly into the contract. The function initializes the validator's information, locks the tokens, and optionally deploys a delegation pool if pooling is enabled. +
-`increase_stake`: Lets existing validators add more tokens to their stake. The contract recalculates rewards and updates the validator's information accordingly. +
-`unstake_intent`: Initiates the unstaking process by locking the validator's tokens for a specified exit period. No rewards are earned during this period. +
-`unstake_action`: Finalizes the unstaking process after the exit period has passed, releasing the staked tokens back to the validator. +
-`claim_rewards`: Calculates and transfers the validator's accumulated rewards to their designated reward address. +
+`stake`: Allows users to stake their STRK tokens, forwarding the request to the staking contract. +
+`increase_stake`: Lets existing stakers add more tokens to their stake. +
+`claim_rewards`: Facilitates the claiming of rewards for stakers and delegators. +
+`unstake_intent`: Initiates the unstaking process by signaling intent, which the staking contract processes. +
+`unstake_action`: Finalizes the unstaking process after the waiting period.
+
+== Staking Contract
+
+The staking contract is the core of the staking system. It manages the entire lifecycle of staking, from initial staking to claiming rewards and unstaking. The operator contract interacts with the staking contract to execute these functions.
+
+*Key Functions and Responsibilities (accessed via the Operator contract)*: +
+`stake`: Allows users to stake their STRK tokens. This is facilitated by the Operator contract and forwarded to the Staking contract. +
+`increase_stake`: Lets existing validators increase their stake, accessed through the Operator. +
+`unstake_intent`: Initiates the unstaking process, managed by the Operator contract, which interacts with the Staking contract to initiate and finalize the unstaking process. +
+`unstake_action`: Finalizes the unstaking process after the waiting period, returning tokens to the user through the Operator. +
+`claim_rewards`: Allows users to claim rewards, facilitated through the Operator contract.
 
 == Delegation Pooling Contract
 
-The delegation pooling contract enables users to delegate their tokens to a validator without having to manage the staking process themselves. This contract tracks each delegator's contribution, calculates their rewards, and manages the delegation lifecycle.
+The delegation pooling contract enables users to delegate their tokens through the Operator contract. All interactions, such as entering or exiting the pool, are forwarded to the appropriate contracts via the Operator. This contract tracks each delegator's contribution, calculates their rewards, and manages the delegation lifecycle.
 
 *Key Functions and Responsibilities*: +
 `enter_delegation_pool`: Allows users to delegate their tokens to the pool associated with a validator. This function transfers the tokens, updates the delegator's record, and integrates them into the validator's pool. +
 `add_to_delegation_pool`: Enables existing delegators to increase their delegation amount. The contract updates the pool's total and recalculates the member's rewards. +
 `exit_delegation_pool_intent`: Initiates the process for a delegator to exit the pool. Similar to validators, the delegator's funds are locked for a period before they can be withdrawn. +
 `exit_delegation_pool_action`: Finalizes the exit process for a delegator, returning their tokens and any unclaimed rewards. +
 `switch_delegation_pool`: Allows a delegator to transfer their delegated stake from one validator's pool to another, facilitating dynamic delegation strategies. +
-`claim_rewards`: Transfers the delegator's earned rewards to their specified reward address. +
+`claim_rewards`: Transfers the delegator's earned rewards to their specified reward address.
 
 == Reward Supplier Contract
 
 The reward supplier contract is responsible for calculating and supplying the staking rewards based on the minting curve. It ensures that the rewards are distributed fairly and in accordance with the protocol's economic parameters.
 
 *Key Functions and Responsibilities*: +
 `calculate_staking_rewards`: Computes the rewards based on the current staking rate and the minting curve, updating the staking contract with the amount to be distributed. +
-`claim_rewards`: Handles the transfer of rewards to the staking contract, ensuring that the correct amount is distributed to validators and delegators. +
+`claim_rewards`: Handles the transfer of rewards to the staking contract, ensuring that the correct amount is distributed to validators and delegators.
 
 == Minting Curve Contract
 
@@ -86,4 +98,4 @@ The minting curve contract defines the economic model that governs reward distri
 
 == Security and Upgradability
 
-The staking architecture on Starknet is designed with security and upgradability in mind. Each contract is modular, allowing for targeted upgrades and improvements without affecting the entire system. Access control mechanisms are in place to ensure that only authorized parties can make critical changes, further enhancing the security of the staking process.
+The staking architecture on Starknet is designed with security and upgradability in mind. Each contract is modular, allowing for targeted upgrades and improvements without affecting the entire system. The introduction of the Operator contract adds an extra layer of access control, ensuring only authorized users can interact with the staking system. Access control mechanisms are in place to ensure that only authorized parties can make critical changes, further enhancing the security of the staking process.

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

@@ -3,7 +3,7 @@
 
 :description: How to claim your staking rewards on Starknet by directly interacting with the staking or delegation pooling contracts.
 
-Staking rewards on Starknet accumulate over time as your staked STRK tokens contribute to network security. To claim these rewards, you need to interact with the staking contract (if you are a validator) or the specific delegation pooling contract associated with the validator you have staked with (if you are a delegator) and execute the appropriate functions.
+Staking rewards on Starknet accumulate over time as your staked STRK tokens contribute to network security. To claim these rewards, you need to interact with the operator contract (if you are a validator) or the specific delegation pooling contract associated with the validator you have staked with (if you are a delegator) and execute the appropriate functions.
 
 .Prerequisites
 
@@ -14,7 +14,7 @@ Staking rewards on Starknet accumulate over time as your staked STRK tokens cont
 
 . Using a Starknet block explorer, navigate to the appropriate contract:
 + 
-* For validators: Navigate to the staking contract.
+* For validators: Navigate to the operator contract.
 * For delegators: Navigate to the delegation pooling contract associated with the validator you have staked with.
 . In the contract interface, locate and select the `claim_rewards` function.
 . Enter the following parameters:

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

@@ -9,6 +9,7 @@ The delegation process includes joining a validator's delegation pool by interac
 
 .Procedure
 
+. Pre-approve the delegation pooling contract associated with the validator for the transfer of the requested amount of STRK tokens from your address.
 . Using a Starknet block explorer, navigate to the delegation pooling contract associated with the validator you want to delegate to.
 . In the contract interface, locate and select the `enter_delegation_pool` function.
 . Enter the following parameters:

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

@@ -18,14 +18,17 @@ For more information on what happens during the staking process, see xref:archit
 * Validators are expected to run full nodes in preparation for the following stages of the protocol. You can use any full node implementation you choose:
 ** link:https://github.com/NethermindEth/juno[Juno] by Nethermind - link:https://juno.nethermind.io/hardware-requirements/#recommended-requirements[Spec].
 ** link:https://github.com/eqlabs/pathfinder[Pathfinder] by EQLabs - https://github.com/eqlabs/pathfinder?tab=readme-ov-file#hardware-requirements[Spec].
+** link:https://github.com/madara-alliance/madara[Madara] by Madara Alliance - link:https://docs.madara.build/get-started/requirements[Spec].
 * A Starknet-compatible block explorer or CLI tool.
 * Sufficient STRK token balance in your wallet.
-* Pre-approval of the STRK ERC20 contract (link:https://starkscan.co/token/0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d[Starkscan], link:https://voyager.online/contract/0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d[Voyager]) 
-on Starknet for the transfer of tokens from your address to the staking contract.
 
 .Procedure
 
-. Using a Starknet block explorer, navigate to the staking contract. 
+. Pre-approve the STRK ERC20 contract for the transfer of tokens from your address to the staking contract (and *not* the operator contract):
++
+* Using a Starknet block explorer, navigate to the STRK ERC20 contract (link:https://starkscan.co/token/0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d[Starkscan], link:https://voyager.online/contract/0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d[Voyager]).
+* Approve the staking contract to transfer the specified amount of STRK tokens on your behalf.
+. Using a Starknet block explorer, navigate to the operator contract. 
 . In the contract interface, locate and select the `stake` function.
 . Enter the following parameters:
 +

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

@@ -16,12 +16,12 @@ Validators can unstake their STRK tokens, which involves pausing rewards and exi
 .Procedure
 
 1. **Signal Unstake Intent:**
-. Using a Starknet block explorer, navigate to the staking contract.
+. Using a Starknet block explorer, navigate to the operator contract.
 . In the contract interface, locate and select the `unstake_intent` function.
 . Submit the transaction to initiate the unstake process. This will record the unstake intent, pause rewards collection, and set a waiting period.
 
 2. **Finalize Unstake:**
-. After the waiting period has passed, return to the staking contract.
+. After the waiting period has passed, return to the operator contract.
 . In the contract interface, locate and select the `unstake_action` function.
 . Enter the following parameters:
 +

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

@@ -3,18 +3,20 @@
 
 :description: How to increase your stake on Starknet by interacting directly with the staking or delegation pooling contracts.
 
-The staking and pooling contracts allow validators and delegators to increase their existing stake. Validators use the `increase_stake` function, which is called from the staking contract, while delegators use the `add_to_delegation_pool` function, which is called from the delegation pooling contract. These functions add the specified amount of STRK tokens to the current stake, recalculate rewards before the staked amount is updated, and update the total staked amount.
+The staking and pooling contracts allow validators and delegators to increase their existing stake. Validators use the `increase_stake` function, which is called from the operator contract, while delegators use the `add_to_delegation_pool` function, which is called from the delegation pooling contract. These functions add the specified amount of STRK tokens to the current stake, recalculate rewards before the staked amount is updated, and update the total staked amount.
 
 .Prerequisites
 
 * Sufficient STRK token balance in your Starknet wallet.
-* The validator/delegator must have pre-approved the relevant contract (staking contract for validators, delegation pooling contract for delegators) to transfer the specified STRK amount from their account.
 * The validator/delegator must not be in an unstake/undelegate process.
 * The caller must be either the validator/delegator or their respective reward address.
 
 .Procedure
-
-. Using a Starknet block explorer, navigate to the relevant contract (staking contract for validators, delegation pooling contract for delegators).
+. Pre-approve the STRK ERC20 contract for the transfer of tokens from your address to the relevant contract:
++
+* Validators: Pre-approve the staking contract (and *not* the operator contract) for the transfer of tokens from your address.
+* Delegators: Pre-approve the delegation pooling contract for the transfer of tokens from your address.
+. Using a Starknet block explorer, navigate to the relevant contract (operator contract for validators, delegation pooling contract for delegators).
 . In the contract interface, locate and select the `increase_stake` function (for validators) or the `add_to_delegation_pool` function (for delegators).
 . Enter the following parameters:
 +

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

@@ -20,7 +20,7 @@ If a validator does not yet have a delegation pool, they can open one by calling
 
 .Procedure
 
-. Using a Starknet block explorer, navigate to the **staking contract**.
+. Using a Starknet block explorer, navigate to the operator contract.
 . In the contract interface, locate and select the `set_open_for_delegation` function.
 . Enter the following parameter:
 +
@@ -35,7 +35,7 @@ Validators can update the commission rate of their delegation pool using the `up
 
 .Procedure
 
-. Using a Starknet block explorer, navigate to the **staking contract**.
+. Using a Starknet block explorer, navigate to the operator contract.
 . In the contract interface, locate and select the `update_commission` function.
 . Enter the following parameter:
 +
@@ -52,7 +52,7 @@ Validators can change their operational address by interacting with the `change_
 
 .Procedure
 
-. Using a Starknet block explorer, navigate to the **staking contract**.
+. Using a Starknet block explorer, navigate to the operator contract.
 . In the contract interface, locate and select the `change_operational_address` function.
 . Enter the following parameter:
 +
@@ -67,8 +67,8 @@ Both validators and delegators can update their reward address using the `change
 
 . Using a Starknet block explorer, navigate to the appropriate contract:
 +
-* For validators: Navigate to the **staking contract**.
-* For delegators: Navigate to the **delegation pooling contract**.
+* For validators: Navigate to the operator 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:
 +

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

@@ -29,7 +29,6 @@ STRK tokens never leave the Starknet protocol during these operations.
 ** Staking Rewards.
 ** Karnot.
 
-
 === Overview
 
 The staking protocol features two main options:
@@ -91,3 +90,26 @@ The proposed economic parameters are:
 * **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.
+
+== Sepolia Testnet Parameters
+
+Below are the relevant contract addresses and parameters for interacting with the staking protocol on Sepolia testnet:
+
+=== Addresses
+
+* **L1:**
+  - Reward supplier address: 0xE58d25681B9d290D60e4d7f379a05d5BFD973fFB
+  - Mint manager address: 0x648D1B35a932F5189e7ff97b2F795E03734DE4ce
+
+* **L2:**
+  - Staking address: 0x03745ab04a431fc02871a139be6b93d9260b0ff3e779ad9c8b377183b23109f1
+  - Operator address: 0x04ce1719fd581433d59100cc3f00387c66866492253b4f3a08688828ed9f6832
+  - Minting curve address: 0x0351c67dc2d4653cbe457be59a035f80ff1e6f6939118dad1b7a94317a51a454
+  - Reward supplier address: 0x02ebbebb8ceb2e07f30a5088f5849afd4f908f04f3f9c97c694e5d83d2a7cc61
+
+=== Economic Parameters
+
+* **Minimum STRK for Staking:** 1 STRK
+* **Withdrawal Security Lockup:** 5 minutes
+* **Minting Curve Yearly Inflation Cap (stem:[C]):** 1.6
+* **Technical parameter for developers who want to deep dive:** The index update interval is set to a minimum of 1 minute on Sepolia, in contrast to the 24-hour interval used in production.