System upgrades
Compare system contract versions and run the guided upgrade workflow from the dApp.
DALP includes a system upgrade surface for keeping deployed system contracts in sync with the latest implementations available for the active network.
Operators use this workflow when the platform reports that system components need an upgrade. DALP compares the active system with the network directory, shows the components that differ, then runs a guided upgrade with live progress.
Completed steps stay applied
System upgrades can include on-chain transactions. Closing the dialog or retrying after a failure does not roll back completed steps. Review the comparison before you start.
Who can run upgrades
The system upgrade page is visible in platform settings, but the upgrade action is available only to accounts with the required system-management permission. The API accepts callers that are platform admins or wallets with the system manager or admin role on the indexed system.
If your account does not have permission, the page shows that system management is unavailable and does not offer the upgrade action.
What the comparison shows
Before an upgrade starts, DALP compares the active system address with the expected implementations from the directory for the active network.
The comparison groups components by area, including core system components, identity, per-token infrastructure, compliance, registries, token factories, add-ons, and compliance modules. Each row shows whether the component is already up to date or has a newer implementation available. Factory rows can also show how many deployed tokens are affected.
Components that exist in the directory but are not installed on the active system are tracked separately from upgradeable components. Installing new factory, add-on, or compliance module types is handled by the dedicated management pages, not by the system upgrade workflow.
Run an upgrade
Review the comparison
Open the system upgrade page and review the summary. You can hide or show up-to-date components and search for a specific component name.
If all components are current, the page reports that the system is up to date and the upgrade button is disabled.
Start the guided upgrade
Select Upgrade all when the summary shows upgradeable components. The dialog lists the number of system contracts that will be upgraded and the number of deployed tokens affected by factory upgrades.
The confirmation step requires you to confirm before DALP submits the upgrade workflow.
Monitor live progress
After the workflow starts, the dialog switches to a progress view. DALP streams the migration tree and step updates until the workflow completes or fails.
Keep the dialog open while the upgrade is running. If you refresh or reopen the dialog during an in-flight upgrade, DALP checks for an active migration for the current organization and reconnects to the live progress stream.
Review the result
When the upgrade succeeds, close the dialog. DALP refreshes the comparison so the page reflects the updated system state.
If the upgrade fails, the dialog shows the failed state and the reason reported by the workflow. Correct the underlying issue, then retry from the dialog.
Retry behavior
Retrying a failed system upgrade is safe. DALP reuses the comparison as the source of truth and the workflow skips steps that are already complete or no longer need action.
When another upgrade is already running for the organization, DALP reconnects the user to the active migration instead of starting a second one. If DALP cannot confirm or reset the previous workflow state, the platform refuses to start a new run and returns a retryable error.
Migration progress is scoped to the active organization. A caller can subscribe only to the migration that belongs to the caller's organization.
Troubleshooting
| Symptom | What it means | What to do |
|---|---|---|
| The page says system management is unavailable | The account does not have the required system-management permission. | Use an admin or system-manager account, or ask an admin to grant access. |
| The comparison cannot run because the system address is missing | DALP cannot resolve the active deployed system for the organization. | Deploy a system or configure the active system address, then retry the comparison. |
| The comparison cannot run because the directory address is missing | The active network configuration does not include the directory contract address. | Set the directory contract address for the active network, then retry. |
| Start returns that another migration is in progress | DALP found an active upgrade for the organization. | Reopen the dialog to reconnect to progress, or wait for the active run to finish. |
| The upgrade fails after some steps complete | The failed step stopped the workflow, but completed steps remain applied. | Fix the underlying issue shown in the dialog, then retry the upgrade. |