# System upgrade comparison API Source: https://docs.settlemint.com/docs/api-reference/reference/system-upgrade-comparison Read your system's upgrade readiness through the DALP Platform API. Compare every deployed component against the network directory, see which differ, and confirm what an upgrade will change before you run it. 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](/docs/api-reference/reference/operational-integration-patterns#upgrade-operations-and-compatibility), which covers starting a migration and streaming its progress. ## Endpoint [#endpoint] | Endpoint | Use it for | | -------------------------------------- | --------------------------------------------------------------------------------------------------- | | `GET /api/v2/system/migration/compare` | Compare the active system's deployed components against the network directory, grouped by category. | 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](/docs/api-reference/reference/organization-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 [#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 [#summary] | Field | Type | Description | | --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- | | `systemAddress` | string | The system contract address that was compared. | | `directoryAddress` | string | The directory contract address used as the reference for the latest implementations. | | `totalComponents` | number | The number of components considered in the comparison. | | `upToDate` | number | Components whose deployed implementation already matches the directory. | | `updateAvailable` | number | Installed components whose implementation differs from the directory. The upgrade workflow acts on these. | | `pendingInstall` | number | Components present in the directory but not yet installed on this system. The upgrade workflow installs these. | | `pendingHiddenSync` | number | Hidden infrastructure components the workflow installs or updates silently. Counted so a sync-only upgrade still has a trigger. | | `totalAffectedTokens` | number | The total number of tokens affected across all factory-backed components that need an upgrade. | ### Component [#component] Each component in a group describes one part of the system and how its deployed state compares to the directory. | Field | Type | Description | | ------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` | string | The directory key or type identifier for this component, such as `SYSTEM`, `COMPLIANCE`, or `bond`. | | `label` | string | A human-readable name, such as `System Proxy` or `Bond Factory`. | | `group` | string | The logical category, such as `core`, `identity`, `compliance`, `tokenFactories`, `addons`, or `complianceModules`. | | `status` | string | The component's overall state: `up-to-date`, `update-available`, or `new`. See [Component status](#component-status). | | `deployedAddress` | string or `null` | The implementation address currently deployed for this component, or `null` when nothing is deployed. | | `directoryAddress` | string or `null` | The implementation address the directory expects, or `null` when the component is not registered there. | | `isExperimental` | boolean | Whether the component is an experimental directory type. Experimental components are surfaced but excluded from a bulk upgrade unless the operator opts in. | | `affectedTokenCount` | number | For a factory-backed component, the number of tokens its upgrade affects. | | `factoryImplementationStatus` | string | For a factory-backed component, registry-layer drift between the installed factory and the directory. Absent for singleton components. | | `instanceImplementationStatus` | string | For a factory-backed component, drift in the implementation that factory-deployed proxies delegate to. Can also be `unknown` when a live read of the factory implementation failed. | | `skippedForAuthority` | object | Work this admin cannot clear by re-running the migration without additional role authority. See [Authority-blocked work](#authority-blocked-work). | 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 [#component-status] The `status` field tells you what an upgrade would do to each component. | Status | Meaning | What an upgrade does | | ------------------ | ------------------------------------------------------------------------------ | -------------------- | | `up-to-date` | The deployed implementation already matches the directory. | Nothing. | | `update-available` | The component is installed, but its implementation differs from the directory. | Upgrade in place. | | `new` | The component exists in the directory but is not yet installed on this system. | Install. | 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 [#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. | Field | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------------------ | | `count` | number | The number of items blocked because the acting admin lacks granting authority. | | `tokenAddresses` | array | The affected token addresses, when the blocked work maps to specific tokens. | 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 [#compare-deployed-components-against-the-directory] `GET /api/v2/system/migration/compare` returns the summary and the grouped components in one read. ```bash curl "https://your-platform.example.com/api/v2/system/migration/compare" \ -H "x-api-key: YOUR_API_KEY" ``` ```json { "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 [#errors] | Status | Error | When it happens | | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `DALP-0450` | The directory contract address is not configured for the active network, so there is no reference to compare against. Set the directory address in the network configuration, then retry. | | `404` | `DALP-0451` | The directory address is configured, but the indexer has not yet produced the directory record needed for comparison. Retry once indexing catches up. | For the full error model and how to read the `why` and `fix` fields, see [Error reference](/docs/api-reference/errors). 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 [#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](/docs/api-reference/reference/operational-integration-patterns#upgrade-operations-and-compatibility). To understand how the active organisation and system bound every read, see [Organization and system scope](/docs/api-reference/reference/organization-system-scope).