PlatformVM Architecture

How the P-Chain manages validators, staking, and Avalanche L1 creation inside AvalancheGo.

PlatformVM (P-Chain) runs on Snowman++ and controls validators, staking rewards, Subnet/L1 membership, and chain creation. Source lives in vms/platformvm and its block/tx types in vms/platformvm/platform, where codec.go registers every type in the order that determines its wire TypeID.

At a glance:

  • Snowman++ engine drives PlatformVM block production; mempool feeds Standard and Proposal blocks.
  • Validator registry, Subnet/L1 membership, warp signing, and atomic UTXOs are persisted in the node database.
  • P-Chain APIs expose validator state, Subnet/chain creation, staking ops, and block fetch.

Note

Helicon activated on Mainnet on September 22, 2026 at 15:00 UTC.

Helicon does not deprecate or disable any existing transaction type. Current validators and delegators continue to work unchanged. It adds auto-renewed staking as an option and lowers the minimum Primary Network validator staking duration on Mainnet from two weeks to 48 hours. The delegator minimum stays two weeks. See Helicon Upgrade.

Responsibilities

  • Validator registry & staking: Tracks Primary Network validators and delegators, uptime, staking rewards, and validator fees. Since Helicon, a validation can renew at the end of each cycle and has no fixed end time (Figure 1). See Helicon Upgrade.
  • Subnet/L1 orchestration: Creates Subnets and chains (CreateSubnetTx, CreateChainTx), converts Subnets into L1s (ConvertSubnetToL1Tx), and maintains Subnet and L1 validator sets (including permissionless add/remove and warp-authorized L1 validator changes).
  • Warp messaging: Signs warp messages for cross-chain communication on Avalanche L1s.
  • Atomic transfers: Handles import/export of AVAX to/from other chains via shared memory.
Add validatorAddAutoRenewedValidatorTxThe stake starts its first cycle.RestakeautoCompoundRewardSharesOn commit, if nextPeriod is not 0,this share of the reward joins thestake, up to the maximum stake.A new cycle starts.Cycle endRewardAutoRenewedValidatorTxThe P-Chain commits if uptimein this cycle is 90% or more.If not, it aborts.PayoutThe rest of the reward goesto the rewards owners.ExitnextPeriod = 0An abort also exits here.The stake and the rewardscome back. An abort losesthis cycle's validation reward.Add validatorAddAutoRenewedValidatorTxThe stake starts its first cycle.RestakeautoCompoundRewardSharesOn commit, if nextPeriod is not 0,this share of the reward joins thestake, up to the maximum stake.A new cycle starts.Cycle endRewardAutoRenewedValidatorTxThe P-Chain commits if uptimein this cycle is 90% or more.If not, it aborts.PayoutThe rest of the reward goesto the rewards owners.ExitnextPeriod = 0An abort also exits here.The stake and the rewardscome back. An abort losesthis cycle's validation reward.
An auto-renewed validator stakes one cycle at a time. At each cycle end, the P-Chain restakes a share of the reward and starts the next cycle, or the validator exits. The hatched bands show a renewal.

Consensus & Blocks

  • Uses Snowman++ via the ProposerVM (stake-sampled single-proposer slots; no post-Durango open-building fallback).
  • Blocks are built by vms/platformvm/block/builder; the builder makes Standard and Proposal blocks, and a Proposal block has Commit/Abort options. Atomic blocks are invalid since Apricot Phase 5: import and export transactions go in Standard blocks.
  • The P-Chain does not support state sync: a new node bootstraps the full P-Chain. The node sets the P-Chain bootstrap peers (CustomBeacons in its ChainParameters) from --bootstrap-ids and --bootstrap-ips. If you set neither flag, the node samples the default bootstrappers of the network.

Key Transaction Types

TransactionPurpose
AddValidatorTx, AddDelegatorTxDisabled since Durango (ACP-62). Issuing one is rejected outright, with ErrAddValidatorTxPostDurango / ErrAddDelegatorTxPostDurango. Use AddPermissionlessValidatorTx / AddPermissionlessDelegatorTx instead. The type IDs (0x0c, 0x0e) stay registered so nodes can replay pre-Durango history
AddSubnetValidatorTxAdd a validator to a Subnet (validator must also be on Primary). Permanently disabled on a Subnet once it has been converted with ConvertSubnetToL1Tx
AddPermissionlessValidatorTx / AddPermissionlessDelegatorTxValidate or delegate on the Primary Network. This is the current path for delegators and for fixed-term validators. They also work on a legacy permissionless Subnet, but TransformSubnetTx is rejected since Etna, so no new one can be created
RemoveSubnetValidatorTxRemove a validator from a permissioned Subnet
CreateSubnetTxCreate a new Subnet and owner controls
CreateChainTxLaunch a new blockchain (VM + genesis) on a Subnet
TransferSubnetOwnershipTxHand a Subnet's owner controls to a new owner (ACP-31)
ConvertSubnetToL1TxConvert a Subnet into an L1 with its initial validator set (ACP-77)
RegisterL1ValidatorTxAdd a validator to an L1, authorized by a warp message from the L1's validator manager
SetL1ValidatorWeightTxChange an L1 validator's weight (a weight of 0 removes the validator)
IncreaseL1ValidatorBalanceTxTop up an L1 validator's continuous-fee balance
DisableL1ValidatorTxDeactivate an L1 validator and reclaim its remaining balance
AddAutoRenewedValidatorTxJoin the Primary Network with a cycle duration (period) and auto-compound share instead of a fixed end time (ACP-236, Helicon)
SetAutoRenewedValidatorConfigTxChange an auto-renewed validator's cycle duration or auto-compound share. A period of 0 is how the validator exits after the current cycle (Helicon)
RewardAutoRenewedValidatorTxSettle rewards at a cycle boundary and start the next cycle. Issued by block builders, not by the operator (Helicon)
ImportTx / ExportTxMove AVAX to/from other chains via atomic UTXOs
RewardValidatorTxMint rewards after successful staking periods
TransformSubnetTxDisabled since Etna. Legacy Subnet transform, rejected with "TransformSubnetTx is not permitted post-Etna". Its type ID (0x18) stays registered for the same reason

Add a validator to an L1

An L1's validator manager contract decides who validates the L1, and the P-Chain records the result. Adding a validator takes one P-Chain transaction between two L1 transactions:

  1. On the L1, call initiateValidatorRegistration on the validator manager with the node's NodeID, BLS public key and weight. The contract emits a RegisterL1ValidatorMessage through the Warp precompile.
  2. Collect BLS signatures on that message from the L1 validators, until the signers hold at least 67% of the validator weight.
  3. On the P-Chain, issue RegisterL1ValidatorTx with the signed message and a balance for the continuous fee. The P-Chain records the validator.
  4. Collect the L1 validators' signatures on the P-Chain's L1ValidatorRegistrationMessage, which confirms the registration.
  5. On the L1, call completeValidatorRegistration. The signed message goes in the transaction's access list.

Add a Validator to an L1 explains each step, shows the SDK call that runs all of them, and lists the errors you can get. The Builder Console runs the same flow in the browser.

P-Chain APIs

  • Exposed at /ext/bc/P with namespaces such as platform.getBlock, platform.getCurrentValidators, platform.issueTx, platform.getSubnets, platform.getBlockchains. The full set is in the P-Chain API reference.
  • Helicon adds no new methods, but platform.getCurrentValidators gains three fields on auto-renewed validators: validatorAuthority, nextPeriod and autoCompoundRewardShares. They are absent on every other validator, so their presence identifies an auto-renewed validation.
  • Health and metrics are surfaced via the node-level /ext/health and /ext/metrics.

Configuration

The P-Chain reads its config from the file below. The P-Chain has no state sync and no pruning option. For every key, see the P-Chain config reference.

~/.avalanchego/configs/chains/P/config.json
{
  "checksums-enabled": false,
  "block-cache-size": 67108864
}
  • Chain aliases can be set in ~/.avalanchego/configs/chains/aliases.json (--chain-aliases-file). This file maps blockchain IDs to aliases.
  • Upgrade rules and Subnet parameters are read from the chain config and network upgrade settings (upgrade/).
  • Minimum staking durations can be overridden with --min-stake-duration (delegators, and validators before Helicon) and --helicon-min-stake-duration (validators from Helicon onwards). Both are read only on custom networks: on Mainnet and Fuji the node ignores them and uses the genesis values. Development networks commonly shorten them so validator lifecycle tests do not have to wait hours.

Developer Tips

  • When testing new Subnets/VMs, pass CreateChainTx genesis bytes and VM IDs via platform.issueTx.
  • No new permissionless (elastic) Subnet can be created: the P-Chain rejects TransformSubnetTx since Etna. To run a permissionless L1, convert the Subnet with ConvertSubnetToL1Tx and manage validators through the L1's validator manager.
  • Use platform.getBlock to inspect Proposal/Commit/Abort flow if debugging staking or Subnet/L1 updates.

Is this guide helpful?

Using HardHat

Learn how to verify a smart contract using Hardhat.

AVAX Staking for Professionals

A comprehensive guide to Avalanche staking for financial professionals who need to understand the mechanics, risks, and operational considerations without deep technical knowledge.

On this page

Responsibilities
Consensus & Blocks
Key Transaction Types
Add a validator to an L1
P-Chain APIs
Configuration
Developer Tips

Page Actions

Edit on GitHubReport Issue