Creating or modifying upgrade.json

Hands-on exercise: Disable tx and contract deployer allowlists via upgrade.json with future timestamps.

Objectives

By the end of this exercise, you will be able to:

Create (or edit) upgrade.json in the correct chain config directory.
Add de-activation entries for txAllowListConfig and contractDeployerAllowListConfig.
Choose safe, future blockTimestamp values in increasing order.

Prerequisites

Before starting this exercise, ensure you have:

Completed the previous lesson and can access:
- ~/.avalanchego/configs/chains/<YOUR_BLOCKCHAIN_ID>/
Your Docker validator container shell open.

Instructions

Step 1: Choose future timestamps

In the validator container, compute two timestamps a few minutes in the future (they must be strictly increasing):

NOW=$(date +%s)
T1=$((NOW + 600))
T2=$((NOW + 601))
echo $T1
echo $T2

Step 2: Create `upgrade.json` next to `config.json`

Make sure you are in your chain config directory:

cd ~/.avalanchego/configs/chains/<YOUR_BLOCKCHAIN_ID>
ls

Create (or edit) upgrade.json so it disables both precompiles:

cat > upgrade.json << 'JSON'
{
  "precompileUpgrades": [
    {
      "txAllowListConfig": {
        "blockTimestamp": 1700000000,
        "disable": true
      }
    },
    {
      "contractDeployerAllowListConfig": {
        "blockTimestamp": 1700000001,
        "disable": true
      }
    }
  ]
}
JSON

Now replace the placeholder timestamps (1700000000 / 1700000001) with your values from Step 1.

The timestamps must be in the future relative to the chain head, and entries must be in increasing timestamp order. If you set a timestamp in the past, the node may fail on startup.

Step 3: Sanity check the file

Print the file to confirm it exists and looks correct:

cat upgrade.json

You should see both txAllowListConfig and contractDeployerAllowListConfig entries, each with "disable": true.

Expected Output

You should now have an upgrade.json file in your chain config directory with two disable entries.

upgrade.json created/updated

Verification

To verify you've completed this exercise successfully:

~/.avalanchego/configs/chains/<YOUR_BLOCKCHAIN_ID>/upgrade.json exists.
It contains two precompileUpgrades entries with "disable": true.

Troubleshooting

Issue: The node refuses to start after I added `upgrade.json`

Problem: You see errors on startup after adding the upgrade file.

Solution:

Ensure blockTimestamp values are in the future (increase them and try again).
Ensure the entries are in increasing order.
If an upgrade already activated, treat precompileUpgrades as append-only (don’t modify past entries).

Next Steps

Next, restart the Docker validator so AvalancheGo loads the new upgrade configuration.

On this page