precompile-genesis-and-upgrades
Use when the agent needs to activate, deactivate, or reconfigure Avalanche L1 precompiles — at genesis vs later via a network upgrade.json — and the operational steps to roll an upgrade across validat
SKILL.mdskills/precompile-genesis-and-upgrades/SKILL.md
GitHubPrecompile Activation: Genesis vs Network Upgrade
Overview
Subnet-EVM precompiles ([[subnet-evm-precompiles]]) can be turned on at genesis or activated/deactivated/reconfigured later via a coordinated network upgrade. Choosing correctly matters because genesis config is baked in, while upgrades require all validators to apply the same change at the same activation timestamp.
Option A — Activate at genesis
Put the precompile's *Config block in genesis.json with blockTimestamp: 0 and the initial roles. Simplest for new chains; chosen via avalanche blockchain create ([[create-avalanche-l1]]).
"txAllowListConfig": { "blockTimestamp": 0, "adminAddresses": ["0xAdmin"] }
Option B — Activate/deactivate via network upgrade
Use an upgrade.json that schedules a precompile change at a future blockTimestamp. Every node must run the same upgrade.json before that timestamp.
{
"precompileUpgrades": [
{
"txAllowListConfig": {
"blockTimestamp": 1735689600,
"adminAddresses": ["0xAdmin"]
}
},
{
"txAllowListConfig": { "blockTimestamp": 1735693200 } // empty body after = disable
}
]
}
Rules:
- Ordering: upgrades are applied in increasing
blockTimestamporder. - To enable: provide the config with roles. To disable: schedule a later entry with an empty/disabling config.
- Consistency: all validators must have the same upgrade file; mismatches cause them to disagree and stall.
Operational rollout (network upgrade)
- Author/modify
upgrade.jsonwith ablockTimestampsafely in the future. - Distribute it to every validator's chain-config directory.
- Restart nodes so they load the upgrade.
- Verify each validator reads the same config; confirm activation after the timestamp passes; test the new precompile behavior.
When to use which
- New chain / known requirements → genesis.
- Live chain / new requirement, recovering from a lost admin, or rotating policy → network upgrade.
Common Pitfalls
- Past or too-soon timestamp. Set
blockTimestampcomfortably in the future so all validators upgrade in time. - Partial rollout. If some validators lack the upgrade, the network forks/stalls.
- Disabling syntax. Deactivation is a later scheduled entry, not deletion of the original.
AI Agent Prompt
"Act as an L1 operator. Write an
upgrade.jsonto activate the Transaction AllowList at a future timestamp on a live L1, then describe the validator rollout and verification steps."
References
See references/README.md (builders-hub docs/avalanche-l1s/upgrade/precompile-upgrades, academy access-restriction network-upgrade modules).