Skip to content

Commit 299f7cc

Browse files
EmpieichOEmpieichO
authored
Merge pull request 0xPolygon#86 from 0xPolygon/empieichO-docs-review
Update PoS docs - added new section
2 parents 57f99f9 + 74e4149 commit 299f7cc

File tree

15 files changed

+1113
-4
lines changed

15 files changed

+1113
-4
lines changed

‎docs/img/pos/staking_manager.png‎

231 KB
Loading

‎docs/miden/architecture/state.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
giThe state of the Miden rollup describes the current condition of all accounts and note states. It describes what is currently the case. With its state model, using concurrent off-chain state, Polygon Miden aims to realize private transactions, and execution and state bloat minimization.
1+
The state of the Miden rollup describes the current condition of all accounts and note states. It describes what is currently the case. With its state model, using concurrent off-chain state, Polygon Miden aims to realize private transactions, and execution and state bloat minimization.
22

33
Privacy is realized from a UTXO-like state model consisting of notes and nullifiers combined with off-chain execution using zero-knowledge proofs. Execution bloat happens when transactions get re-executed by all participants of the network. State bloat describes the ever growing state stored in blockchain nodes. Polygon Miden addresses these challenges via its state model that enables concurrent off-chain execution and off-chain storage.
44

‎docs/pos/how-to/operating/validator-node/index.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
# Operating a Polygon Validator Node
2-
31
Operating as a validator on the Polygon Network involves playing a pivotal role in validating transactions within the blockchain. This guide provides details on how to run a Validator Node (including Sentry and Validator components) on the Polygon Network, the responsibilities involved, and the technical and operational aspects to consider.
42

53
## Eligibility and responsibilities

‎docs/pos/how-to/operating/validator-node/rewards.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
In Polygon, validators stake their MATIC tokens as collateral to work for the security of the network, and in exchange for their service, earn rewards.
2+
3+
To leverage Polygon's economics, you should either become a validator or a delegator.
4+
5+
To be a validator, you need to **run a full validator** node and stake MATIC.
6+
7+
Also check the [Validator Responsibilities](/pos/design/validator/responsibilities) page.
8+
9+
To be a delegator, you only need to **delegate MATIC to a validator**
10+
11+
## What is the incentive?
12+
13+
Polygon allocates 12% of its total supply of 10 billion tokens to fund the staking rewards. This is to ensure that the network is seeded well enough until transaction fees gain traction. These rewards are primarily meant to jump-start the network, while the protocol in the long run is intended to sustain itself on the basis of transaction fees.
14+
15+
**Validator Rewards = Staking Rewards + Transaction Fees**
16+
17+
This is allocated in a way to ensure gradual decoupling of staking rewards from being the dominant component of the validator rewards.
18+
19+
|Year|Target Stake (30% of circulating supply)|Reward Rate for 30% Bonding|Reward Pool|
20+
|---|---|---|---|
21+
|First|1,977,909,431|20%|312,917,369|
22+
|Second|2,556,580,023|12%|275,625,675|
23+
|Third|2,890,642,855|9%|246,933,140|
24+
|Fourth|2,951,934,048|7%|204,303,976|
25+
|Fifth|2,996,518,749|5%|148,615,670 + **11,604,170**|
26+
27+
Below is a sample snapshot of the expected annual rewards for the first 5 years considering staked supply ranging from 5% to 40% at 5% interval
28+
29+
|% of circulating supply staked|5%|10%|15%|20%|25%|30%|35%|40%|
30+
|---|---|---|---|---|---|---|---|---|
31+
|Annual reward for year|
32+
|First|120%|60%|40%|30%|24%|20%|17.14%|15%|
33+
|Second|72%|36%|24%|18%|14.4%|12%|10.29%|9%|
34+
|Third|54%|27%|18%|13.5%|10.8%|9%|7.71%|6.75%|
35+
|Fourth|42%|21%|14%|10.5%|8.4%|7%|6%|5.25%|
36+
|Fifth|30%|15%|10%|7.5%|6%|5%|4.29%|3.75%|
37+
38+
## Who gets the incentives?
39+
40+
Stakers running validator nodes and stakers delegating their tokens toward a validator that they prefer.
41+
42+
Validators have the option to charge a commission on the reward earned by delegators.
43+
44+
The funds belonging to all stakers are locked in a contract deployed on the Ethereum mainnet.
45+
46+
No validator holds custody over delegator tokens.
47+
48+
## Staking rewards
49+
50+
The yearly incentive is absolute — irrespective of the overall stake or the target bonding rate in the network, the incentive amount is given out as a reward to all signers periodically.
51+
52+
In Polygon, there is an additional element of committing periodic checkpoints to the Ethereum mainnet. This is a major part of the validator responsibilities and they are incentivized to perform this activity. This constitutes a cost to the validator which is unique to a Layer 2 solution such as Polygon. We strive to accommodate this cost in the validator staking reward payout mechanism as a bonus to be paid to the proposer, who is responsible for committing the checkpoint. Rewards minus the bonus is to be shared among all stakers, proposer and signers, proportionally.
53+
54+
## Encouraging the proposer to include all signatures
55+
56+
To avail the bonus completely, the proposer must include all signatures in the checkpoint. Because the protocol desires ⅔ +1 weight of the total stake, the checkpoint is accepted even with 80% votes. However, in this case, the proposer gets only 80% of the calculated bonus.
57+
58+
## Transaction fees
59+
60+
Each block producer at Bor is given a certain percentage of the transaction fees collected in each block. The selection of producers for any given span is also dependent on the validator’s ratio in the overall stake. The remaining transaction fees flow through the same funnel as the rewards which get shared among all validators working at the Heimdall layer.

‎docs/pos/reference/commands.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
This guide provides a curated list of common commands and Polygon-specific operations essential for node operators. Whether you're setting up a full node, validator node or troubleshooting, these commands will assist you in managing your Polygon PoS environment effectively.
2+
3+
## Frequently used commands for Bor & Heimdall
4+
### Bor
5+
6+
To execute Bor IPC commands, use the following syntax:
7+
8+
```bash
9+
bor attach .bor/data/bor.ipc <command>
10+
```
11+
12+
| IPC Command | RPC Command | Description |
13+
| ----------- | ----------- | ----------- |
14+
| `admin.peers.length` | `curl -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "net_peerCount", "params": [], "id": 74}' localhost:8545` | Retrieves the number of peers connected to the node. |
15+
| `admin.nodeInfo` | | Provides detailed information about the node. |
16+
| `eth.syncing` | `curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "eth_syncing","params": []}' localhost:8545` | Indicates whether the node is syncing (`true`) or not (`false`). |
17+
| `eth.syncing.highestBlock - eth.syncing.currentBlock` | | Compares the current block of your node to the highest block. |
18+
| `eth.blockNumber` | `curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "eth_blockNumber","params": []}' localhost:8545` | Returns the latest block number processed by the node. |
19+
| `debug.setHead("0x"+((eth.getBlock('latest').number) - 1000).toString(16))` | | Rewinds the blockchain to 1000 blocks prior. |
20+
| `admin.nodeInfo.enode` | | Retrieves the public enode URL of the node. |
21+
| `eth.syncing.currentBlock * 100 / eth.syncing.highestBlock` | | Calculates the remaining percentage for block synchronization. |
22+
| `eth.getBlock("latest").number` | `curl http://YourIP:8545 -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0", "id":1, "method":"bor_getSigners", "params":["0x98b3ea"]}'` | Queries the height of the latest Bor block. |
23+
| | `curl http://YourIP:8545 -X POST -H "Content-Type: application/json" --data '{"method":"eth_chainId","params":[],"id":1,"jsonrpc":"2.0"}'` | Retrieves the `chainID`. |
24+
25+
### Heimdall
26+
27+
| Command | Description |
28+
| ------- | ----------- |
29+
| `curl localhost:26657/net_info?` | Returns the number of connected peers using `jq .result.n_peers`. |
30+
| `curl -s localhost:26657/status` | Retrieves Heimdall's current block height using `jq .result.sync_info.latest_block_height`. |
31+
| `curl localhost:26657/net_info` | Queries the node using its moniker with `grep moniker`. |
32+
| `curl -s localhost:26657/status` | Checks if Heimdall is in sync using `jq .result.sync_info.catching_up`. |
33+
| `curl -s localhost:26657/status` | Verifies Heimdall's sync status using `jq .result \| jq .sync_info`. |
34+
| `heimdalld unsafe-reset-all` | Resets the database in case of issues. |
35+
| `curl localhost:26657/status` | Provides comprehensive information about Heimdall. |
36+
37+
38+
## Node management commands
39+
40+
| Description | Command |
41+
| ------------------------------------- | ---------------------------------------------- |
42+
| **Locate Heimdall genesis file** | `$CONFIGPATH/heimdall/config/genesis.json` |
43+
| **Locate heimdall-config.toml** | `/etc/heimdall/config/heimdall-config.toml` |
44+
| **Locate config.toml** | `/etc/heimdall/config/config.toml` |
45+
| **Locate heimdall-seeds.txt** | `$CONFIGPATH/heimdall/heimdall-seeds.txt` |
46+
| **Start Heimdall** | `$ sudo service heimdalld start` |
47+
| **Start Heimdall rest-server** | `$ sudo service heimdalld-rest-server start` |
48+
| **Start Heimdall bridge-server** | `$ sudo service heimdalld-bridge start` |
49+
| **Locate Bor genesis file** | `$CONFIGPATH/bor/genesis.json` |
50+
| **Start Bor** | `sudo service bor start` |
51+
| **Retrieve Heimdall logs** | `/var/log/matic-logs/` |
52+
| **Check Heimdall logs** | `tail -f heimdalld.log` |
53+
| **Check Heimdall rest-server logs** | `tail -f heimdalld-rest-server.log` |
54+
| **Check Heimdall bridge logs** | `tail -f heimdalld-bridge.log` |
55+
| **Check Bor logs** | `tail -f bor.log` |
56+
57+
## Useful configuration commands
58+
59+
### Sync status of Heimdall
60+
61+
To check if Heimdall is synced, run:
62+
63+
```bash
64+
curl http://localhost:26657/status
65+
```
66+
67+
### Latest block height on Heimdall
68+
69+
To check the latest block height on Heimdall, run:
70+
71+
```bash
72+
curl localhost:26657/status
73+
```
74+
75+
### Latest block height on Bor
76+
77+
To check the latest block height on Bor, use:
78+
79+
```bash
80+
curl http://<your ip>:8545 -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0", "id":1, "method":"bor_getSigners", "params":["0x98b3ea"]}'
81+
```
82+
83+
### Cleanup: deleting remnants of Heimdall and Bor
84+
85+
**For Linux package:**
86+
87+
```bash
88+
sudo dpkg -i matic-bor
89+
sudo rm -rf /etc/bor
90+
```
91+
92+
**For Binaries:**
93+
94+
```bash
95+
sudo rm -rf /etc/bor
96+
sudo rm /etc/heimdall
97+
```
98+
99+
### Terminate Bor process
100+
101+
**For Linux:**
102+
103+
```bash
104+
ps -aux | grep bor
105+
sudo kill -9 <PID>
106+
```
107+
108+
**For Binaries:**
109+
110+
```bash
111+
cd CS-2003/bor
112+
bash stop.sh
113+
```
114+
115+
### Retrieve latest peer details
116+
117+
To retrieve the latest peer details, run:
118+
119+
```bash
120+
bor attach bor.ipc
121+
admin.peers.forEach(function(value){
122+
console.log(value.enode+',')
123+
})
124+
exit
125+
```
126+
127+
### Stop Heimdall and Bor services
128+
129+
**For Linux packages:**
130+
131+
```bash
132+
sudo service heimdalld stop
133+
sudo service bor stop
134+
```
135+
136+
**For binaries:**
137+
138+
```bash
139+
pkill heimdalld
140+
pkill heimdalld-bridge
141+
cd CS-2001/bor
142+
bash stop.sh
143+
```
144+
145+
### Remove Heimdall and Bor directories
146+
147+
**For Linux packages:**
148+
149+
```bash
150+
sudo rm -rf /etc/heimdall/*
151+
sudo rm -rf /etc/bor/*
152+
```
153+
154+
**For binaries:**
155+
156+
```bash
157+
sudo rm -rf /var/lib/heimdalld/
158+
sudo rm -rf /var/lib/bor
159+
```

‎docs/pos/reference/commit-chain-multisigs.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
2+
## Purpose and capabilities
3+
4+
The primary role of multi-signature wallets (multisigs) is to facilitate contract upgrades during the early stages of development. As these contracts become more robust, Polygon plans to:
5+
6+
- Transition from multisigs to governance-controlled proxies.
7+
- Implement timelocks for added security.
8+
- Phase out multisigs entirely in the long term.
9+
10+
**It's important to note that the existing multisigs do not have the capability to censor transactions, including bridge transactions.**
11+
12+
## Active multi-signature wallets
13+
14+
### Ethereum chain multisigs
15+
16+
| Multisig Address | **5/9 Multisig**<br/>`0xFa7D2a996aC6350f4b56C043112Da0366a59b74c` |
17+
|:----------------:|---------------------------------------------------------------------|
18+
| Purpose | To upgrade PoS and staking contracts on Ethereum. |
19+
| Chain | Ethereum |
20+
| Rights | - Update staking contracts for optimizations and upgrades.<br/>- Address unexpected bugs in PoS contracts. |
21+
| Signatories | Quickswap, Curve, Polygon, Horizon Games, Cometh |
22+
23+
### Polygon commitchain multisigs
24+
25+
| Multisig Address | **5/8 Multisig**<br/>`0x355b8E02e7F5301E6fac9b7cAc1D6D9c86C0343f` |
26+
|:----------------:|---------------------------------------------------------------------|
27+
| Purpose | To update custom ChildERC20s on Polygon Commitchain. |
28+
| Chain | Polygon Commitchain |
29+
| Rights | Ability to upgrade custom child contracts. |
30+
| Signatories | Quickswap, Curve, Polygon, Horizon Games, Cometh |
31+
32+
### Custom child ERC20s mapping
33+
34+
| Multisig Address | **4/8 Multisig**<br/>`0x424bDE99FCfB68c5a1218fd3215caFfD031f19C4` |
35+
|:----------------:|---------------------------------------------------------------------|
36+
| Purpose | To enable the mapping of custom ChildERC20s with Mainnet contracts. |
37+
| Chain | Ethereum |
38+
| Rights | Limited to mapping; no access to Child tokens or deposit/withdrawal rights. |
39+
| Signatories | Polygon |
40+
41+
### Permissionless mapping
42+
43+
| Multisig Address | **Permissionless Mapping of Standard ChildERC20 Tokens (No Multisig Required)** |
44+
|:----------------:|--------------------------------------------------------------------------------|
45+
| Purpose | FxPortal supports permissionless token mapping of standard ChildERC20 for any ERC20 token on Ethereum. |
46+
| Chain | Permissionless |
47+
| Rights | Permissionless |
48+
| Signatories | Permissionless |
49+
50+
<sub>*Plans are underway to transition these functions to governance. We are currently exploring options such as Aave's governance contracts and Compound’s timelock contracts.</sub>

‎docs/pos/reference/contracts/delegation.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
Polygon supports delegation via validator shares. By using this design, it is easier to distribute rewards and slash with scale (thousands of delegators) on Ethereum contracts without much computation.
2+
3+
Delegators delegate by purchasing shares of a finite pool from validators. Each validator will have their own validator share token. Let's call these fungible tokens `VATIC` for a validator `A`. As soon as a user delegates to a validator `A`, they will be issued `VATIC` based on an exchange rate of `MATIC/VATIC` pair. As users accrue value the exchange rate indicates that they can now withdraw more `MATIC` for each `VATIC` and when users get slashed, users withdraw less `MATIC` for their `VATIC`.
4+
5+
Note that `MATIC` is a staking token. A delegator needs to have `MATIC` tokens to participate in the delegation.
6+
7+
Initially, a delegator `D` buys tokens from validator `A` specific pool when `1 MATIC per 1 VATIC`.
8+
9+
When a validator gets rewarded with more `MATIC` tokens, new tokens are added to the pool. Let's say with the current pool of `100 MATIC` tokens, `10 MATIC` rewards are added to the pool. But since the total supply of `VATIC` tokens didn't change due to rewards, the exchange rate becomes `1 MATIC per 0.9 VATIC`. Now, delegator `D` gets more `MATIC` for the same shares.
10+
11+
`VATIC`: Validator specific minted validator share tokens (ERC20 tokens)
12+
13+
## Technical specification
14+
15+
```solidity
16+
uint256 public validatorId; // Delegation contract for validator
17+
uint256 public validatorRewards; // accumulated rewards for validator
18+
uint256 public commissionRate; // validator's cut %
19+
uint256 public validatorDelegatorRatio = 10; // to be implemented/used
20+
21+
uint256 public totalStake;
22+
uint256 public rewards; // rewards for pool of delegation stake
23+
uint256 public activeAmount; // # of tokens delegated which are part of active stake
24+
```
25+
26+
Exchange rate is calculated as below:
27+
28+
```js
29+
ExchangeRate = (totalDelegatedPower + delegatorRewardPool) / totalDelegatorShares
30+
```
31+
32+
## Methods and variables
33+
34+
### buyVoucher
35+
36+
```js
37+
function buyVoucher(uint256 _amount) public;
38+
```
39+
40+
- Transfer the `_amount` to stakeManager and update the timeline data structure for active stake.
41+
- `updateValidatorState` is used to update timeline DS.
42+
- `Mint` delegation shares using current `exchangeRate` for `_amount`.
43+
- `amountStaked` is used to keep track of active stake of each delegator in order to calculate liquid rewards.
44+
45+
### sellVoucher
46+
47+
```js
48+
function sellVoucher() public;
49+
```
50+
51+
- Using current `exchangeRate` and number of shares to calculate total amount (active stake + rewards).
52+
- `unBond` active stake from validator and transfer rewards to delegator, if any.
53+
- Must remove active stake from timeline using `updateValidatorState` in stakeManger.
54+
- `delegators` mapping is used to keep track of stake in withdrawal period.
55+
56+
### withdrawRewards
57+
58+
```js
59+
function withdrawRewards() public;
60+
```
61+
62+
- For a delegator, calculate the rewards and transfer, and depending upon `exchangeRate` burn count of shares.
63+
- Example: if a delegator owns 100 shares and exchange rate is 200 so rewards are 100 tokens, transfer 100 tokens to delegator. Remaining stake is 100 so using exchange rate 200, now it is worth 50 shares. So burn 50 shares. Delegator now has 50 shares worth 100 tokens (which he initially staked / delegated).
64+
65+
### reStake
66+
67+
Restake can work in two ways: delegator can buy more shares using `buyVoucher` or reStake rewards.
68+
69+
```js
70+
function reStake() public;
71+
```
72+
73+
Above function is used to reStake rewards. The number of shares aren’t affected because `exchangeRate` is the same; so just the rewards are moved into active stake for both validator share contract and stakeManager timeline.
74+
75+
`getLiquidRewards` is used for calculating accumulated rewards i.e., delegator owns 100 share and exchange rate is 200, so rewards are 100 tokens. Move 100 tokens into active stake, since exchange rate is still same number of share will also remain same. Only difference is that now 200 tokens are considered into active stake and can't be withdrawn immediately (not a part of liquid rewards).
76+
77+
Purpose of reStaking is that since delegator's validator has now more active stake and they will earn more rewards for that so will the delegator.
78+
79+
### unStakeClaimTokens
80+
81+
```js
82+
function unStakeClaimTokens()
83+
```
84+
85+
Once withdrawal period is over, delegators who've sold their shares can claim their MATIC tokens. Must transfer tokens to user.
86+
87+
### updateCommissionRate
88+
89+
```js
90+
function updateCommissionRate(uint256 newCommissionRate)
91+
external
92+
onlyValidator
93+
```
94+
95+
- Updates commission % for the validator.
96+
97+
### updateRewards
98+
99+
```js
100+
function updateRewards(uint256 reward, uint256 checkpointStakePower, uint256 validatorStake)
101+
external
102+
onlyOwner
103+
returns (uint256)
104+
```
105+
106+
When a validator gets rewards for submitting checkpoint, this function is called for disbursements of rewards between validator and delegators.

0 commit comments

Comments
 (0)