Skip to content

Commit bf159b2

Browse files
navillanuevanavillanueva
committed
precompile workflows
1 parent 2d96ec7 commit bf159b2

File tree

3 files changed

+168
-13
lines changed

3 files changed

+168
-13
lines changed

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

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,13 @@ icon: Book
88

99
## From Proof of Authority to Proof of Stake
1010

11-
Now that we've covered how Proof of Stake serves as a Sybil protection mechanism that enables permissionless participation in your 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?
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?
1212

13-
In the previous section on [staking token selection](/academy/permissionless-l1s/proof-of-stake/staking-token), we learned that your staking token can either be your 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.
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.
1414

1515
### 1. Opening Validator Management (From Permissioned L1s)
1616

17-
In the [Permissioned L1s course](/academy/permissioned-l1s), you 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:
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:
1818

1919
- **PoA Model**: Only the owner can call `initiateValidatorRegistration()`, `initiateValidatorRemoval()`, and `initiateValidatorWeightUpdate()`
2020
- **Centralized Control**: One account (EOA or multi-sig) acts as the gatekeeper
@@ -23,26 +23,26 @@ To enable PoS, we need to **open these functions to the public**—but with econ
2323

2424
### 2. Adding Token Economics (From L1 Native Tokenomics)
2525

26-
In the [L1 Native Tokenomics course](/academy/l1-native-tokenomics), you 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). You also explored the [Native Minter Precompile](/academy/l1-native-tokenomics/native-minter/introduction) for managing token supply.
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.
2727

2828
Now we need to integrate these token economics with validator management to create the economic security model that defines PoS.
2929

3030
## The Transformation Requirements
3131

32-
To enable native token staking on your L1, you'll need to configure specific precompiles:
32+
To enable native token staking on our L1, we'll need to configure specific precompiles:
3333

3434
### Required: Native Minter Precompile
3535

36-
When using your native token for staking, the **Native Minter Precompile is mandatory**. It enables the minting of staking rewards for validators.
36+
When using the native token for staking, the **Native Minter Precompile is mandatory**. It enables the minting of staking rewards for validators.
3737

38-
> **Note**: If you're using an ERC20 token for staking instead, you don't need the Native Minter—the ERC20 token just needs to be mintable.
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.
3939
4040
### Recommended: Reward Manager Precompile
4141

4242
The **Reward Manager Precompile is optional but highly recommended**. It automates reward distribution based on validator performance and participation.
4343

44-
If you choose not to enable the Reward Manager, transaction fees will simply be burned rather than distributed as rewards.
44+
If we choose not to enable the Reward Manager, transaction fees will simply be burned rather than distributed as rewards.
4545

4646
## Next Steps
4747

48-
In the following sections, we'll explore why these precompiles are necessary and how to configure them for your permissionless L1.
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: 58 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,65 @@
11
---
22
title: Native Minter with PoS
3-
description: A review of Proof of Stake on Avalanche
3+
description: How the Native Minter precompile enables staking rewards
44
updated: 2025-03-13
55
authors: [nicolasarnedo]
66
icon: BookOpen
77
---
88

9-
blabla
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: 101 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,108 @@
11
---
22
title: Reward Manager
3-
description: A review of Proof of Stake on Avalanche
3+
description: How the Reward Manager calculates and distributes staking rewards
44
updated: 2025-03-13
55
authors: [nicolasarnedo]
66
icon: BookOpen
77
---
88

9-
blabla
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

0 commit comments

Comments
 (0)