System upgrades
Compare system contract versions and run the guided upgrade workflow from the Console.
Use the system upgrade surface to keep deployed contracts in sync with the latest implementations available for your active network. System upgrades compare what is currently deployed against the available implementations, then run guided on-chain changes.
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.
Upgradeability answer for governance review
DALP uses upgradeable EVM contracts for system upgrades and for asset infrastructure that is deployed through upgradeable factories. The system proxy uses an ERC-1967 implementation slot with a UUPS implementation, and the workflow calls upgradeToAndCall when the active implementation differs from the network directory. Asset tokens use factory-directed proxies: each token proxy keeps the token address stable and delegates to the token implementation selected by its asset factory. Immutable contracts, when present, are remediated by replacement and governed migration rather than by changing the old implementation.
DALP does not use Transparent Proxy, ERC-2535 Diamond, or EIP-1967 Beacon for the system upgrade workflow. Asset token proxies do not store their own implementation address in an ERC-1967 slot; for asset-token upgrades, the migration workflow updates the affected factory's token implementation and existing proxies route subsequent calls through it.
The upgrade authority is not one fixed DALP address across all environments. The authority is the account that currently holds the relevant on-chain role in the deployed environment. For the system proxy, the authorised account must hold SYSTEM_MANAGER_ROLE in the system access manager. Directory implementation changes are governed by the directory administrator role. Access manager upgrades are authorised by DEFAULT_ADMIN_ROLE or SYSTEM_MANAGER_ROLE. Token-level operation and administration roles stay separate from system-level roles and must be reviewed per asset.
DALP does not add a mandatory on-chain timelock to the system upgrade workflow. If an environment requires a time delay, the operator enforces it through its governance approval path or custody policy, such as a timelocked account. The public upgrade surface submits the upgrade only after the authorised caller confirms.
Storage compatibility review happens before an implementation is accepted for upgrade. This review compares ABI and storage layout and treats removed functions, selector changes, storage reordering, removed storage, unsafe type changes, and unsafe appended storage as breaking findings. The on-chain workflow then preserves state by upgrading the implementation pointer and running versioned migration calls instead of redeploying the same proxy address.
If an upgrade fails or corrupts investor-facing state, completed on-chain transactions remain part of the environment history. The remediation path is operational: stop further upgrade attempts, preserve the failed step and transaction evidence, and compare pre-upgrade and post-upgrade investor state. Then restore through a governed correction when the existing contract can still operate, or deploy replacement contracts and migrate investors through the immutable-contract transition path when it cannot. DALP does not automatically rewind chain state after a submitted upgrade transaction completes. You must initiate remediation manually.
For immutable contracts, remediation is migration rather than implementation replacement. Preserve the old contract and its event history, deploy replacement contracts, rebuild investor eligibility and policy state, then move balances through governed lifecycle steps such as mint, burn, transfer, or redemption according to the asset's legal and operating process.
Who can run upgrades
The system upgrade page is visible in platform settings, but you can run an upgrade only if your account has 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 show the upgrade option.
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: core system, identity, per-token infrastructure, compliance, registries, token factories, add-ons, and compliance modules. Each row shows whether the installed component matches the directory or has a newer implementation available. Factory rows also show how many deployed tokens are affected.
Each component row shows one status badge so you can read its state at a glance:
| Badge | Meaning |
|---|---|
| Up to date | The installed implementation matches the expected implementation in the directory. |
| New version | A newer implementation is available in the directory. The upgrade workflow can move this component. |
| New | The component is recognised but not yet installed. The upgrade workflow can register and install new factory, add-on, and compliance module types. For other component types, use the dedicated management page. |
| Unknown | DALP could not read the component's current implementation, so it cannot confirm the component is current. |
A factory-backed component is two layers: the factory and the instance implementation it deploys. The row badge is the combined state, set to the worse of the two layers, so one component never shows two competing answers. If DALP cannot read the instance layer, the row reports Unknown instead of claiming the component is current, even when the factory layer reads as up to date. An Unknown row is advisory. The upgrade workflow does not act on it, so resolve the read problem and re-run the comparison rather than treating it as a pending upgrade.
Expand a row's Details to see the layer breakdown. For a factory-backed component, Details shows a Factory line and an Instance line, each with its own status badge and its Current and Latest implementation addresses. Single-implementation components show one Current and Latest pair.
The upgrade workflow acts on installed components whose implementation address differs from the directory. It also registers new factory, add-on, and compliance module types that the comparison marks as New, so the bulk action can install them in the same pass. For other component types, use the dedicated management page.
Price Feeds in the comparison
The comparison includes a Price Feeds component under the Pricing group when the system has tokens that were issued with an on-chain base-price claim but still need a price feed.
When some tokens still need a feed, the Price Feeds component shows as needing an update, the same as any other drifted component, and the upgrade action stays enabled. Running the migration then creates the missing feeds through the automatic price-feed backfill. When every eligible token already has a feed, the Price Feeds component reads as up to date.
The Price Feeds component appears only on a system that already has the data feeds infrastructure installed and has feed-eligible tokens. A system with no feed-eligible tokens, or without an indexed feeds directory, does not show the row. In that case, install the data feeds addon first if you need feeds, then re-run the comparison.
What changes during an upgrade
DALP token and system contracts are upgradeable where they are deployed behind proxies. The system upgrade path uses UUPS-compatible implementations and the ERC-1967 implementation slot. Token addresses stay stable because asset proxies continue to use the token factory's selected implementation.
The upgrade authority is deployment-specific. No universal public address applies to every DALP environment. For a system proxy upgrade, the transaction must come from an account that the system recognises as a system manager. For directory implementation changes, the transaction must come from a directory administrator. The evidence pack should record the exact executing wallet address, the on-chain role that authorised it, and the approval or custody record that allowed that wallet to act.
DALP does not enforce a protocol-level mandatory timelock before a system or token implementation change executes. If an environment requires a time delay, enforce that delay in the external governance, custody, or change-approval process before the authorised wallet submits the on-chain transaction. Preserve the delay evidence with the upgrade authorization record.
Storage layout compatibility is a release gate, not a button in the upgrade dialog. Review the new implementation's storage layout before you register its address in the directory or use it for a proxy upgrade. Use OpenZeppelin upgrade validation or an equivalent compiler storage-layout comparison. Preserve the validation output, the approved implementation address, and the approver sign-off with the directory update evidence.
Automatic price-feed backfill for older tokens
Tokens created before DALP moved to per-token price feeds were issued with an on-chain base-price claim but have no price feed, so they show no price in portfolio and reporting views. Upgrading an existing system repairs this for you. As part of the migration, DALP backfills the missing feeds so older assets start resolving a price without any manual feed setup.
The backfill runs only on a system that already has the data feeds infrastructure installed. During the upgrade it:
- Ensures the organization's price-feed trust state so the organization can publish signed values for the price topic.
- Ensures the global exchange-rate feeds exist for the organization's reporting currencies and for the currencies of the tokens being backfilled, creating only the ones that are missing.
- Creates a per-token price feed for each existing token that has no feed yet but still carries a base-price claim, seeding the feed from the value and currency recorded in that claim.
After the upgrade, those tokens resolve a price through the same indexed feed path as tokens created with a feed. The seeded value is the price the asset was issued with. Update it through the normal feed workflow when you have a current value. See Set a token price and the Data feeds overview.
The backfill is best-effort and does not block the upgrade. A feed that cannot be created, for example because a token's claim cannot be decoded, is skipped and the rest of the migration still completes. The step is also safe to re-run: an upgrade that runs again does not create duplicate feeds, and a token that already has a resolved price through a feed is left as is. A token that has a feed address but no seeded value yet is still selected and the backfill submits the seeded claim value to that feed.
For the feeds to land, the account that runs the upgrade must hold the feeds and identity-management permissions on the system. An admin account self-grants the missing permissions during the run. A delegated system-manager account that cannot self-grant them sees the backfill skip cleanly while the rest of the upgrade proceeds. Re-run the upgrade from an admin account to complete the backfill.
| Token before the upgrade | What the backfill does |
|---|---|
| Has a base-price claim and no feed | Creates a per-token feed seeded from the claim value, so the token resolves a price. |
| Already has a price feed | Leaves the existing feed unchanged. |
| Has no base-price claim | Skips the token. There is no recorded price to seed a feed from. |
| Belongs to a system without the feeds infrastructure | Skips the backfill for the whole system. Install the data feeds addon, then re-run. |
Storage collision and initialization controls
Direct answer
DALP protects upgradeable proxy contracts by treating storage layout, initializer state, implementation selection, and upgrade evidence as approval gates before an implementation is used. Upgradeable implementations must preserve the existing storage layout, prevent repeat initialization or migration, and keep the same deployed proxy address when the upgrade is safe.
When a contract is not upgradeable, DALP does not patch it in place. Operators use a governed replacement and migration path instead.
DALP mechanism
For system upgrades, DALP separates these controls:
| Control | What it prevents | What to verify |
|---|---|---|
| Storage layout comparison | A new implementation overwriting existing proxy state | Compare the old and new storage layouts before registering the implementation |
| Storage-slot regression coverage | A future release shifting selectors, events, errors, or declared storage | Keep automated regression checks for ABI and storage-layout consistency across approved upgrades |
| Disabled implementation initialization | A standalone implementation contract being initialized outside the proxy | Confirm upgradeable implementation constructors disable direct initialization, and initialize only through the proxy context |
| Versioned initializer or migration guard | A migration step running twice or clobbering state from an earlier version | Confirm the migration uses the expected version and records the post-migration version |
| Role-gated upgrade call | An implementation change submitted by the wrong account | Confirm the executing wallet holds the required system-management or directory-administration role |
Upgradeable implementations use initializer and migration guards rather than relying on constructor execution through the proxy. Implementation constructors are used to disable direct initialization on the implementation contract itself. The proxy upgrade or migration path then initializes or migrates state in the proxy context, where the stored state actually lives.
For implementations that use storage gaps or namespaced storage, append-only fields still need review. A newly appended field reads as its default value on already deployed proxies. If the field becomes part of an initialization or migration guard, review the legacy state as well as the new code path so the guard does not become weaker after upgrade.
The workflow uses the directory as the expected implementation source for the active network. It upgrades the system proxy to the directory's current SYSTEM implementation when the ERC-1967 slot differs, then calls the system migration with the active directory address. When the migration call reaches a contract already at the expected version, the contract reverts with its reinitializer guard. The workflow treats that revert as an idempotent skip and continues.
The directory is the governance boundary for implementation selection. A directory upgrade can register a new SYSTEM implementation, registry implementations, identity factory implementation, advanced accounts infrastructure, token factory implementations, add-ons, compliance modules, and chain-of-trust registries. The upgrade workflow reads those directory pointers and uses only those addresses.
Sub-components use their own migration path. DALP probes each deployed sub-component for the migration interface and calls migrate(bytes) only when the component supports it. Order matters: compliance registry migration runs before system compliance migration.
Asset tokens keep their deployed token addresses. For installed token factories, DALP reconciles the factory implementation first, then updates that factory's token implementation. Existing asset proxies delegate future calls through the factory's updated token implementation. No investor state changes: the token address, OnchainID identity, role assignments, holder balances, and compliance attachments stay as they are.
Deployment and evidence boundary
Before approving a proxy upgrade, preserve the storage-layout validation result, automated ABI and storage-slot regression result, implementation-initialization review, upgrade authority, and post-migration state checks. If a third-party smart contract audit is part of the deployment evidence, the audit scope should state whether proxy upgrade scenarios were reviewed. Storage-collision paths, initializer guards, migration steps, and implementation-selection logic are all upgrade-specific concerns that an audit of the initial deployment does not cover.
If an environment uses an immutable contract, DALP cannot patch that contract in place. Remediate by deploying replacement contracts, rebuilding the required identity and compliance configuration, and moving investor balances through governed lifecycle steps according to the asset's operating process. Preserve the old token address and event history as the audit record.
Related public references
Use this page as the public reference for upgrade mechanics, storage-collision controls, initialization controls, and evidence capture. For token-level role handover after an upgrade or operator transition, see Change asset administrator roles.
Governance evidence to capture
Treat a system upgrade as a governed change, not only as a contract transaction. Capture the evidence that lets you prove which implementation was selected, who authorized it, and what state remained stable after the migration.
| Evidence | Why it matters |
|---|---|
| Component comparison before the upgrade | Shows which active components differed from the network directory before the run |
| Proxy pattern and implementation slot | Shows the UUPS-compatible implementation and ERC-1967 slot value before and after the upgrade |
| Directory implementation pointers | Shows the expected implementation addresses used by the workflow |
| Upgrade authority address and role | Shows the exact wallet, system-manager or directory-admin role, and approval path that allowed the change |
| Timelock or approval-delay evidence | Shows the required external delay when the environment's governance process requires one |
| Storage-layout and initializer validation | Shows the approved implementation passed OpenZeppelin validation or an equivalent storage-layout comparison, and that versioned initializer or migration guards were reviewed |
| Implementation initialization review | Shows implementation constructors disable direct initialization and that initialization runs only in the proxy context |
| ABI and storage-slot regression result | Shows automated checks did not detect unsafe selector, event, error, or storage-layout drift across the upgrade |
| Third-party audit scope | Shows whether an independent contract audit reviewed proxy upgrade scenarios, including storage collision, initializer, migration, and implementation-selection paths |
| Completed transaction hashes | Ties each on-chain upgrade or migration step to the selected network |
| Post-migration version and wiring checks | Shows that system, registry, interface, role, and token-readability checks pass after the run |
| Role and owner state after the upgrade | Shows which accounts can administer or upgrade the environment after the change |
Include the failed step and retry state when your upgrade stops before completion. Completed transactions remain part of the environment history even when a later step fails.
Rollback and remediation
An on-chain upgrade is not automatically rolled back by the DALP upgrade dialog. If an upgrade fails after one or more transactions complete, preserve the failed step, current proxy implementation, migration version, role state, and token samples before you proceed.
If the new implementation is wrong but state remains readable, register the previously approved implementation in the directory, run the guided workflow again, and repeat post-migration checks. Treat this as a new governed change with your own authorization record.
If investor state is corrupted or cannot be read safely, do not rely on a blind proxy rollback as your recovery plan. Freeze further operations through the environment's incident process, preserve the affected state, deploy replacement contracts if needed, rebuild the required identity and compliance configuration, and move balances through governed lifecycle steps according to the asset's legal and operating process. The old token address and events remain the historical record.
Plan for exit and control portability
DALP supports control portability by keeping the on-chain asset attached to the deployed EVM contracts. During a handover, role assignments, compliance configuration, investor identity links, token balances, and transaction history all remain in place. A handover changes the operator and the authorised accounts, not the token address, when the active contracts are upgradeable and stay on the same network.
Before a control handover, export or record the evidence the successor operator needs to run the environment without relying on your account:
| Evidence area | What to preserve |
|---|---|
| Network and contracts | Active chain ID, system address, directory address, asset token addresses, factories, modules, and implementation addresses |
| Permissions | System and token role holders, including admin, system manager, governance, custodian, emergency, and supply-management roles |
| Compliance policy | Compliance modules, module parameters, trusted issuers, claim topics, country allowlists or denylists, investor limits, and holds |
| Investor registry | Wallet-to-OnchainID registry mappings, jurisdiction values, active identity claims, claim issuers, and off-chain verifier evidence |
| Upgrade state | Latest component comparison, completed upgrade transactions, pending migration step, failed step, and retry state |
| Operations | Indexer checkpoints, monitoring settings, custody policy, transaction records, approval history, and retry history |
Use the comparison page as your starting point for handover checks. It shows whether the active system matches the expected directory for the network and identifies components that still need an upgrade. If an upgrade is required before handover, complete it or record the failed step and retry state before you transfer operational responsibility.
For upgradeable contracts, transfer control by granting the successor accounts the required system and asset roles, confirming they can run the comparison and controlled operations, then revoking the outgoing operator's roles. Token-level roles (admin, governance, custodian, emergency, supply-management) are managed per asset. System-level roles are managed separately. See Change asset administrator roles for token-level role changes.
For immutable contracts, preserve the old contracts as the audit record and move to replacement contracts by deployment and transition, not by changing the old implementation. Configure the replacement environment with the same policy intent and register investor wallet-to-OnchainID mappings. Issue or import the required trusted-issuer claims, then move balances through governed lifecycle steps such as mint, burn, transfer, or redemption according to the asset's legal and operating process. The old token address and its event history remain the historical record.
Control portability does not move chain state between networks. For a testnet-to-mainnet move, deploy or attach a separate production environment on the production EVM network, then configure it with the required roles, compliance policy, investor registry mappings, indexing setup, and monitoring. Testnet state remains on the test network.
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. Note that a system whose contracts are all current can still report outstanding work when tokens need a price feed. In that case the comparison shows a Price Feeds component that needs an update, and the upgrade button stays enabled so you can run the backfill.
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.
When you upgrade an existing system, the migration includes an automatic price-feed backfill for older tokens. See Automatic price-feed backfill for older tokens for what it does and when it applies.
The progress stream survives a brief network drop on its own. If the connection glitches mid-upgrade, the dialog shows a connection-lost, reconnecting indicator, keeps the progress you have already seen on screen, and re-opens the stream in the background with backoff. A transient drop is not treated as a failed upgrade. When the connection returns, the stream replays the full migration tree and resumes live updates from the current state. A short outage during a multi-minute upgrade is expected and self-heals.
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.
The dialog reports a connection failure only when the link stays down past repeated reconnect attempts. The on-chain workflow keeps running while you are disconnected, so reopen the dialog once the network is stable to rejoin the live stream and see the current state.
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 required.
When another upgrade is already running for your organization, DALP reconnects you 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 is missing 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. |
| The dialog reports it lost connection to the upgrade stream | The connection stayed down past repeated automatic reconnect attempts. The on-chain workflow keeps running. | Restore a stable network connection, then reopen the dialog to rejoin the live progress stream and see the current state. |
Related
Testnet to mainnet
Move a validated DALP environment from a test EVM network to a production EVM network without treating testnet chain state as production state.
How to monitor platform and blockchain service health
Monitor platform status from the Console and API, and inspect chain RPC and indexer health from the API or CLI.