Update Staking Documentation (#76)

Author: google-labs-jules[bot]

docs/staking/README.md

@@ -1,10 +1,9 @@
 [PHPCoin Docs](../) > Staking
 
-
 ---
 
 # Staking
 
-This section explains how to stake your PHPCoin holdings.
+This section explains how to stake your PHPCoin holdings to earn rewards and support the network.
 
-* [How to Stake](./how-to-stake.md)
+*   [How to Stake](./how-to-stake.md) - A guide on how to start staking your PHPCoin, including technical details about the Proof-of-Stake algorithm, rewards, and requirements.

docs/staking/how-to-stake.md

@@ -1,25 +1,76 @@
 [PHPCoin Docs](../) > [Staking](./) > How to Stake
 
-
 ---
 
 # How to Stake
 
-Staking is the process of holding PHPcoin in a wallet to support the operations of the blockchain network. In return for staking, you receive rewards in the form of new PHPcoin.
+## Introduction
+
+Staking is the process of holding PHPCoin in your wallet to support the blockchain network. In return for holding coins, you receive rewards in the form of new PHPCoin.
 
 ## How Staking Works
 
-PHPcoin uses a Proof-of-Stake (PoS) consensus algorithm, which means that anyone who holds PHPcoin can participate in the process of creating new blocks and validating transactions.
+PHPcoin uses a Proof-of-Stake (PoS) system to reward coin holders. Unlike miners or block generators, **stakers do not create or validate blocks**. Instead, for each block created, the network automatically chooses a "stake winner" from all eligible participants to receive a reward.
 
-To be eligible for staking rewards, you need to meet the following requirements:
+To be eligible for staking rewards, you must meet the network's minimum balance and coin maturity requirements.
 
-*   **Minimum Balance:** You must have a minimum balance of PHPcoin in your wallet. You can check the current minimum balance by calling the `/api.php?q=nodeInfo` API endpoint.
-*   **Maturity:** Your coins must have reached a certain maturity, which means they must have been held in your wallet for a certain number of blocks. You can check the current maturity requirement by calling the `/api.php?q=nodeInfo` API endpoint.
+## How to Start Staking
 
-If you meet these requirements, your wallet will automatically be entered into a lottery to create the next block. If your wallet is chosen, you will receive a reward in the form of new PHPcoin.
+To become eligible for staking rewards, you must first send a special "stake" transaction. This is a one-time action that flags your address as a staking participant.
 
-## How to Start Staking
+1.  **Open a terminal or command prompt.**
+2.  **Navigate to the directory where your PHPcoin wallet is located.**
+3.  **Run the following command:**
+
+    ```bash
+    php cli/wallet.php send <your-address> 0 "stake"
+    ```
+
+    Replace `<your-address>` with your own wallet address. The `0` is the amount to send (this special transaction is free), and `"stake"` is the message that activates your address for staking.
+
+## Staking Requirements
+
+### Current Requirements (Block 1,000,001+)
+
+For the current mainnet (at over 1,250,000 blocks), the requirements are simple and fixed:
+
+*   **Coin Maturity:** **60 blocks**. Your coins must be held for at least 60 blocks before they are eligible.
+*   **Minimum Balance:** **160,000 PHPCoin**. You must hold at least this amount to be eligible.
+
+### Historical Requirements
+
+The staking requirements have changed during the blockchain's history.
+
+*   **Before block 290,000:**
+    *   Coin Maturity: 600 blocks
+    *   Minimum Balance: 100 PHPCoin
+*   **Block 290,001 - 1,000,000:**
+    *   Coin Maturity: 60 blocks
+    *   Minimum Balance: Increased in stages, from 30,000 to 140,000 PHPCoin.
+
+---
+
+## Technical Details
+
+### 1. Activating an Address for Staking
+
+An address is recognized as a staking address after it has been the destination of a transaction with the message `"stake"`.
+
+*   **Code Reference:** The `getAddressTypes` function in `include/class/Block.php`.
+
+### 2. Code References for Requirements
+
+*   **Maturity:** The `getStakingMaturity()` function in `include/class/Blockchain.php` controls this value. The change from 600 to 60 blocks is triggered by the `UPDATE_11_STAKING_MATURITY_REDUCE` constant (value: `290000`) in `include/coinspec.inc.php`.
+*   **Minimum Balance:** The `getStakingMinBalance()` function in `include/class/Blockchain.php` controls this value. The change from a fixed 100 PHPCoin to a dynamic value is triggered by the `UPDATE_12_STAKING_DYNAMIC_THRESHOLD` constant (value: `290000`) in `include/coinspec.inc.php`. The specific amounts are derived from the `REWARD_SCHEME` constant in `include/rewards.inc.php`.
+
+### 3. Stake Winner Selection
+
+For each block, a single stake winner is selected from all eligible accounts based on a `weight`.
+
+*   **Code Reference:** The `getStakeWinner` function in `include/class/Account.php` calculates this `weight` using the formula: `(current_block_height - last_transaction_height) * account_balance`. The account with the highest weight wins.
+
+### 4. Staking Rewards
 
-To start staking, you simply need to hold PHPcoin in your wallet. There is no need to perform any special actions or run any special software.
+The reward amount is determined by the block height.
 
-As long as your wallet is running and connected to the network, you will be eligible to receive staking rewards.
+*   **Code Reference:** The `reward` function in `include/class/Block.php` reads the reward structure from the `REWARD_SCHEME` constant in `include/rewards.inc.php`.