System upgrade comparison API

Before an operator upgrades a deployed system, one question has to be answered with evidence: what exactly will change, and is the system ready for it? This endpoint answers it. It compares every component installed on your system against the network directory, the on-chain registry that records the latest approved implementations for the active network, and returns the difference as a structured, per-component report. You read it, confirm the change set, and only then start the upgrade. That review step gives an operations or audit team a concrete record of what an upgrade touches before anything changes on chain.

The surface is read-only. It reports the current state of your system against the directory and changes nothing. To act on the result, see Upgrade operations and compatibility, which covers starting a migration and streaming its progress.

Endpoint

The response is a single comparison object, not a paginated collection. The active organisation and system context bound the read, as described in Organization and system scope. The comparison covers the active system only.

Reading the comparison is a system-management operation. The caller must be a platform administrator or hold the system manager or admin role on the indexed system.

Response fields

The response has two parts: a summary that totals the work across the whole system, and groups that break the components down by category so you can see what changes and where.

Summary

Component

Each component in a group describes one part of the system and how its deployed state compares to the directory.

The factory-layer and instance-layer address pairs (factoryDeployedAddress / factoryDirectoryAddress and instanceDeployedAddress / instanceDirectoryAddress) accompany factory-backed components so you can read both the current and expected addresses at each layer.

Component status

The status field tells you what an upgrade would do to each component.

For factory-backed components, instanceImplementationStatus can carry a fourth value, unknown. It means the directory records an expected instance implementation, but a live read of the factory's current implementation failed, so the platform cannot confirm the two are in sync. Treat unknown as a signal to retry the comparison rather than as a confirmed match.

Authority-blocked work

Some upgrade work cannot proceed on a re-run alone because the acting admin lacks the role authority to grant the permissions the step needs. The comparison reports this separately in skippedForAuthority so it is never mistaken for ordinary pending work.

A non-zero count means re-running the migration will not clear those items. An admin with the required granting authority has to act first.

Compare deployed components against the directory

GET /api/v2/system/migration/compare returns the summary and the grouped components in one read.

curl "https://your-platform.example.com/api/v2/system/migration/compare" \
  -H "x-api-key: YOUR_API_KEY"

{
  "systemAddress": "0x1111111111111111111111111111111111111111",
  "directoryAddress": "0x2222222222222222222222222222222222222222",
  "summary": {
    "totalComponents": 24,
    "upToDate": 20,
    "updateAvailable": 2,
    "pendingInstall": 1,
    "pendingHiddenSync": 0,
    "totalAffectedTokens": 12
  },
  "groups": [
    {
      "id": "core",
      "label": "Core System",
      "components": [
        {
          "key": "SYSTEM",
          "label": "System Proxy",
          "group": "core",
          "status": "up-to-date",
          "deployedAddress": "0x3333333333333333333333333333333333333333",
          "directoryAddress": "0x3333333333333333333333333333333333333333"
        }
      ]
    },
    {
      "id": "tokenFactories",
      "label": "Token Factories",
      "components": [
        {
          "key": "bond",
          "label": "Bond Factory",
          "group": "tokenFactories",
          "status": "update-available",
          "deployedAddress": "0x4444444444444444444444444444444444444444",
          "directoryAddress": "0x5555555555555555555555555555555555555555",
          "affectedTokenCount": 12
        }
      ]
    }
  ]
}

The example shows a system that is mostly current: twenty components match the directory, two installed components have an upgrade available, and one new component is ready to install. The bond factory upgrade affects twelve tokens, which matches totalAffectedTokens.

Errors

For the full error model and how to read the why and fix fields, see Error reference. Both errors are transient configuration or indexing states rather than problems with the comparison itself, so a retry usually clears them once the underlying state settles.

When to use it

The comparison is the safe first step of any upgrade. Read it when you need to:

• Confirm the exact change set before starting an upgrade, so the migration holds no surprises.
• Audit how far a deployed system has drifted from the latest implementations on its network.
• Identify which components need an upgrade, which are new installs, and how many tokens each factory upgrade affects.
• Catch work that an admin cannot clear without additional role authority, by reading skippedForAuthority before a migration run.
• Build an operator view that shows upgrade readiness across the system, grouped by component category.

To start and track the upgrade itself, see Upgrade operations and compatibility. To understand how the active organisation and system bound every read, see Organization and system scope.