Aztec client feature highlight: the update-checker

General
1

Aztec Client’s Update-checker Module – What It Is and Why It Matters

All credit goes to @alexghr who gave this update in the Sentinel channel.

This post is a quick overview of the update-checker module in the Aztec client — an important piece of infrastructure for maintaining node consistency and network health during rapid iterations.

What is the update-checker?

The update-checker is a background module in the Aztec client that enables global coordination of updates. It allows the protocol team to:

  • Push configuration changes to all nodes
  • Trigger shutdowns so that nodes can pull the latest image version
  • Apply hotfixes quickly
  • Coordinate node resets after a governance upgrade, especially when a new canonical rollup is published to the Registry

This module ensures that upgrades and fixes propagate smoothly without requiring manual intervention from every node operator.

Auto-Update Behavior & Best Practices

Recommended Defaults

  • Use the :latest tag for your Aztec image. It is continuously updated and stable.
  • The old alpha-testnet tag is deprecated and should not be used.
  • Keep the config-and-version default value for the update-checker.

Protocol Compatibility

We now run a test that prevents accidental protocol-breaking changes from being released without proper handling, which ensures updates remain safe and compatible.

Image Pulling in Different Environments

  • Aztec CLI (aztec start): Pulls the latest image on restart. imagePullPolicy: Always is enforced.
  • Kubernetes: Set imagePullPolicy: Always to always get the latest image.
  • Docker Compose: docker-compose does not respect pull policies on container restarts. To handle updates properly, add Watchtower to your stack. Also ensure you’re running with --auto-update config or --auto-update notify.

Configuring Auto-Update

You can control the update-checker via two environment variables:

  • AUTO_UPDATE: Controls the update behavior (disabled, notify, config, config-and-version). This is set in the clie via --auto-update
  • AUTO_UPDATE_URL: Specifies the remote URL to check for updates (typically defaults to our update endpoint)

AUTO_UPDATE Modes

  • disabled: Disables the update checker entirely.
  • notify: Prints a log message when a new version or rollup is detected, but takes no action.
  • config: Includes notify behavior and also applies remote config updates. If your node is following the canonical rollup and the rollup changes, the node shuts down. Restarting will wipe the local DB and sync from the new canonical rollup.
  • config-and-version: Includes config behavior, and also shuts down the node if the remote version differs from the local version.

Note: If you set the ROLLUP_VERSION manually (non-default), the node will not follow the canonical rollup and won’t shut down automatically on governance upgrades that deploy a new canonical rollup.

Let us know in Discord if you run into update issues or want help setting up a more resilient deployment flow.

6 Likes