Skip to content

Commit f296e2e

Browse files
alejandro99soalejandro99so
authored
Merge pull request #3206 from ava-labs/permissionless-l1s-necessary-precompiles
`Permissionless L1s`: Necessary Precompiles
2 parents 63fbd20 + 6b59abe commit f296e2e

File tree

8 files changed

+231
-2
lines changed

8 files changed

+231
-2
lines changed

‎content/academy/permissionless-l1s/02-proof-of-stake/01-introduction.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ authors: [nicolasarnedo]
66
icon: Book
77
---
88

9+
## The Transformation: Two Pieces of the Puzzle
10+
11+
Converting from PoA to PoS isn't about replacing your entire blockchain—it's about strategically combining two concepts you may have already learned in separate courses:
12+
13+
![Proof of Stake Architecture](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/PoS.png)
14+
915
## Proof of Stake as Sybil Protection
1016

1117
Proof of Stake (PoS) is fundamentally a **Sybil protection mechanism** that secures blockchain networks by preventing malicious actors from gaining control through the creation of multiple fake identities. Sybil protection mechanisms serve three critical functions:

‎content/academy/permissionless-l1s/03-transformation-requirements/01-introduction.mdx‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: Native Token Staking Blockchain
3+
description: Precompile contracts necessary for a Permissionless L1 implementation
4+
updated: 2025-03-13
5+
authors: [nicolasarnedo]
6+
icon: Book
7+
---
8+
9+
## From Proof of Authority to Proof of Stake
10+
11+
Now that we've covered how Proof of Stake serves as a Sybil protection mechanism that enables permissionless participation in an L1, the next question is: How do we actually transform an existing permissioned L1 using [Proof of Authority](/academy/permissioned-l1s/proof-of-authority/proof-of-authority) into a permissionless L1 with Proof of Stake?
12+
13+
In the previous section on [staking token selection](/academy/permissionless-l1s/proof-of-stake/staking-token), we learned that the staking token can either be the native token or a separate ERC20 token. **For this course, we will focus on building a permissionless L1 where the native token is also the staking token**—the most common and straightforward implementation that creates unified token economics.
14+
15+
### 1. Opening Validator Management (From Permissioned L1s)
16+
17+
In the [Permissioned L1s course](/academy/permissioned-l1s), we learned about the [Validator Manager Contract](/academy/permissioned-l1s/proof-of-authority/validator-manager-contract)—specifically how PoA restricts validator control to a single owner address. The contract hierarchy showed us:
18+
19+
- **PoA Model**: Only the owner can call `initiateValidatorRegistration()`, `initiateValidatorRemoval()`, and `initiateValidatorWeightUpdate()`
20+
- **Centralized Control**: One account (EOA or multi-sig) acts as the gatekeeper
21+
22+
To enable PoS, we need to **open these functions to the public**—but with economic requirements instead of permission requirements.
23+
24+
### 2. Adding Token Economics (From L1 Native Tokenomics)
25+
26+
In the [L1 Native Tokenomics course](/academy/l1-native-tokenomics), we learned about [custom native tokens](/academy/l1-native-tokenomics/custom-tokens/introduction) and that [native tokens and staking tokens can be different](/academy/l1-native-tokenomics/custom-tokens/native-vs-staking). We also explored the [Native Minter Precompile](/academy/l1-native-tokenomics/native-minter/introduction) for managing token supply.
27+
28+
Now we need to integrate these token economics with validator management to create the economic security model that defines PoS.
29+
30+
## The Transformation Requirements
31+
32+
To enable native token staking on our L1, we'll need to configure specific precompiles:
33+
34+
### Required: Native Minter Precompile
35+
36+
When using the native token for staking, the **Native Minter Precompile is mandatory**. It enables the minting of staking rewards for validators.
37+
38+
> If we're using an ERC20 token for staking instead, we don't need the Native Minter—the ERC20 token just needs to be mintable.
39+
40+
### Recommended: Reward Manager Precompile
41+
42+
The **Reward Manager Precompile is optional but highly recommended**. It automates reward distribution based on validator performance and participation.
43+
44+
If we choose not to enable the Reward Manager, transaction fees will simply be burned rather than distributed as rewards.
45+
46+
## Next Steps
47+
48+
In the following sections, we'll explore why these precompiles are necessary and how to configure them for our permissionless L1.

‎content/academy/permissionless-l1s/03-transformation-requirements/02-native-minter.mdx‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: Native Minter with PoS
3+
description: How the Native Minter precompile enables staking rewards
4+
updated: 2025-03-13
5+
authors: [nicolasarnedo]
6+
icon: BookOpen
7+
---
8+
9+
The **Native Minter Precompile** is essential for native token staking because it allows the staking manager contract to mint new tokens as rewards for validators and delegators. Without this capability, there would be no way to programmatically reward validators for securing the network.
10+
11+
The `NativeTokenStakingManager` contract mints rewards by calling the `INativeMinter` precompile at address `0x0200000000000000000000000000000000000001`.
12+
13+
## Setup Requirements
14+
15+
**The `NativeTokenStakingManager` contract must be granted admin privileges on the Native Minter precompile** to mint rewards. Without these privileges, the staking manager cannot mint rewards and reward distribution will fail.
16+
17+
For this course, we will activate the Native Minter precompile in the genesis configuration. Since the staking manager contract is deployed after the L1 is created, we'll add its address to the precompile's allowlist in later chapters once the contract address is known.
18+
19+
Note that precompile can also be added to a chain after deployment through a network upgrade, but this will be covered in another course.
20+
21+
## Reward Minting Flow
22+
23+
The reward minting flow involves multiple contracts working together to distribute rewards to validators and delegators:
24+
25+
<Mermaid
26+
chart="sequenceDiagram
27+
participant VD as Validator/Delegator
28+
participant SM as StakingManager<br/>(Parent Contract)
29+
participant NTSM as NativeTokenStakingManager
30+
participant NM as NativeMinter Precompile<br/>(0x0200...0001)
31+
participant RR as Reward Recipient
32+
33+
note over NTSM,NM: Setup Requirement
34+
note over NTSM,NM: NativeTokenStakingManager must be<br/>granted admin privileges on precompile
35+
36+
note over VD,RR: Validator Reward Distribution
37+
VD->>SM: completeValidatorRemoval()
38+
SM->>SM: _withdrawValidationRewards()
39+
SM->>NTSM: _reward(recipient, amount)
40+
NTSM->>NM: mintNativeCoin(recipient, amount)
41+
NM->>RR: Native tokens minted
42+
43+
note over VD,RR: Delegator Reward Distribution
44+
VD->>SM: completeDelegatorRemoval()
45+
SM->>SM: _withdrawDelegationRewards()
46+
note over SM: Calculate rewards minus<br/>delegation fees
47+
SM->>NTSM: _reward(recipient, delegatorRewards)
48+
NTSM->>NM: mintNativeCoin(recipient, amount)
49+
NM->>RR: Native tokens minted
50+
51+
52+
"
53+
/>
54+
55+
## The _reward() Function
56+
57+
The core reward minting happens through the `_reward()` internal function in `NativeTokenStakingManager`:
58+
59+
```solidity
60+
function _reward(address account, uint256 amount) internal override {
61+
nativeMinter.mintNativeCoin(account, amount);
62+
}
63+
```
64+
65+
This simple function wraps the Native Minter precompile's `mintNativeCoin(address addr, uint256 amount)` function, which performs the actual token minting at the protocol level.

‎content/academy/permissionless-l1s/03-transformation-requirements/03-reward-manger.mdx‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: Reward Manager
3+
description: How the Reward Manager calculates and distributes staking rewards
4+
updated: 2025-03-13
5+
authors: [nicolasarnedo]
6+
icon: BookOpen
7+
---
8+
9+
The **Reward Manager** is an **optional but highly recommended component** that automates the calculation and distribution of staking rewards. While the Native Minter precompile handles the actual token minting, the Reward Manager determines *how much* each validator and delegator should receive based on their staking duration, stake amount, and network parameters.
10+
11+
Without the Reward Manager enabled, rewards are set to zero—validators receive only their original stake back when they unstake, no reward UTXOs are created, and transaction fees are burned rather than distributed. This eliminates economic incentives for validators beyond minimal transaction fee revenue, significantly weakening the security model of Proof of Stake and reducing decentralization.
12+
13+
## How the Reward Manager Works
14+
15+
The reward system operates through a **proposal-commit/abort mechanism** on the P-Chain. When a validator's or delegator's staking period ends, the system automatically calculates and distributes their rewards.
16+
17+
<Mermaid
18+
chart="sequenceDiagram
19+
participant BB as Block Builder
20+
participant RV as RewardValidatorTx
21+
participant PE as Proposal Executor
22+
participant RC as Reward Calculator
23+
participant PS as P-Chain State
24+
participant V as Validator
25+
participant D as Delegator
26+
27+
note over BB,D: Validator end time reached
28+
BB->>RV: Create RewardValidatorTx
29+
RV->>PE: Execute as proposal
30+
PE->>RC: Get staker to reward
31+
RC->>PE: Calculate reward based on duration, weight, supply
32+
PE->>PS: Return potential reward
33+
alt Commit Path
34+
PE->>PS: Create reward UTXO (if reward > 0)
35+
PE->>PS: Create delegatee reward UTXO (if accumulated)
36+
PE->>PS: Remove from current validators
37+
PS-->>V: Stake + Validation Reward
38+
PS-->>D: Accumulated Delegation Fees
39+
else Abort Path
40+
PE->>PS: Return staked tokens only
41+
PE->>PS: Decrease supply by potential reward
42+
PE->>PS: Return accumulated delegatee rewards
43+
PS-->>V: Stake only (no validation reward)
44+
PS-->>D: Accumulated Delegation Fees
45+
end
46+
47+
note over BB,D: When delegator ends
48+
BB->>RV: Split reward between delegator/delegatee
49+
RV->>PE: Create delegator reward UTXO
50+
alt Post-Cortina
51+
PE->>PS: Accumulate delegatee share
52+
else Pre-Cortina
53+
PE->>PS: Create delegatee reward UTXO immediately
54+
end
55+
PS-->>D: When delegator ends
56+
"
57+
/>
58+
59+
## Reward Calculation
60+
61+
When a validator's or delegator's staking period ends, the system calculates rewards using the `reward.Calculator` which considers:
62+
63+
1. **Staking Duration**: How long tokens were staked
64+
2. **Stake Amount**: The weight of the validator (own stake + delegated stake)
65+
3. **Current Supply**: The total token supply affects reward rate
66+
4. **Network Parameters**: Configured reward rates and caps
67+
68+
The calculation follows this general formula:
69+
70+
```
71+
reward = (stake_amount × staking_duration × reward_rate) / supply_factor
72+
```
73+
74+
The reward rate typically decreases as supply increases, creating controlled inflation.
75+
76+
## Reward Distribution Process
77+
78+
### 1. Block Building
79+
80+
When a staker's end time is reached, the **Block Builder** creates a `RewardValidatorTx` transaction. This transaction proposes to:
81+
- Remove the validator/delegator from the active set
82+
- Calculate their earned rewards
83+
- Return their stake plus rewards
84+
85+
### 2. Execution Phase
86+
87+
The `RewardValidatorTx` is executed as a **proposal transaction** by the Proposal Executor:
88+
89+
- The Reward Calculator computes the potential reward amount
90+
- The P-Chain State is queried for staker information
91+
- A reward UTXO is prepared (if reward > 0)
92+
93+
### 3. Commit or Abort
94+
95+
The transaction can follow two paths:
96+
97+
#### Commit Path (Normal Operation)
98+
- Validator receives: Original stake + validation rewards
99+
- Delegators receive: Their share of rewards (minus delegation fees)
100+
- Delegation fees are either:
101+
- **Post-Cortina**: Accumulated for the validator to claim later
102+
- **Pre-Cortina**: Paid immediately to the validator
103+
104+
#### Abort Path (Network Issues)
105+
- Validator receives: Only their original stake (no rewards)
106+
- Potential rewards are burned (supply decreased)
107+
- Accumulated delegation fees are still returned
108+
- This protects the network from rewarding validators during unstable periods

‎content/academy/permissionless-l1s/06-staking-contract/03-staking-contract-post-etna.mdx‎ renamed to ‎content/academy/permissionless-l1s/05-staking-manager-contract/03-staking-contract-post-etna.mdx‎

File renamed without changes.

‎content/academy/permissionless-l1s/07-staking-manager-operations/04-register-validators.mdx‎ renamed to ‎content/academy/permissionless-l1s/06-staking-manager-operations/04-register-validators.mdx‎

File renamed without changes.

‎content/academy/permissionless-l1s/index.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ If you just completed these recently, you can go ahead and skip the [Review chap
3232
This comprehensive course will walk you through:
3333

3434
- **Proof of Stake** - Understanding PoS consensus, staking token selection, and liquid staking considerations
35-
- **Necessary Precompiles** - Native Minter and Reward Manager precompiles for tokenomics
36-
- **Basic Setup** - Deploying Validator Manager Contract, upgrading proxy, and initializing validator configuration
35+
- **Transformation Requirements** - Basic precmpoiles (Native Minter and Reward Manager) needed to transform your L1 into a permissionless network
36+
- **Basic Setup**(*optional*) - Deploying Validator Manager Contract, upgrading proxy, and initializing validator configuration
3737
- **Staking Manager Setup** - Deploying and configuring staking managers for native token staking
3838
- **Staking Manager Operations** - Adding, changing weights, removing validators, and handling delegation
3939
- **Node Licenses** - Understanding validator licensing and real-world examples

‎content/academy/permissionless-l1s/meta.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
"...01-review",
99
"---Proof of Stake---",
1010
"...02-proof-of-stake",
11+
"---Transformation Requirements---",
12+
"...03-transformation-requirements",
1113
"---More coming soon...---"
1214
]
1315
}

0 commit comments

Comments
 (0)