System upgrades

DALP includes a system upgrade surface for keeping deployed system contracts in sync with the latest implementations available for the active network.

System upgrades compare the active DALP deployment with available implementations before running guided on-chain changes.

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.

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, Beacon, or Diamond EIP-2535 for the system upgrade workflow. Asset token proxies also do not store their own implementation address in an ERC-1967 slot. For asset-token implementation upgrades, the migration workflow updates the affected factory's token implementation, then existing token proxies route subsequent calls through that implementation.

The upgrade authority is not one fixed DALP address across all environments. It is the address 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 before execution, the operator must enforce it through its governance approval path, custody policy, or a timelocked account that holds the required role. The public upgrade surface submits the upgrade only after the authorised caller confirms the guided workflow.

Storage compatibility review happens before an implementation is accepted for upgrade. The compatibility review compares ABI and storage layout for upgradeable contracts and treats removed functions, selector changes, storage reordering, removed storage, unsafe type changes, and unsafe appended storage as breaking findings before implementation acceptance. 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 rollback path is operational remediation: stop further upgrade attempts, preserve the failed step and transaction evidence, compare pre-upgrade and post-upgrade investor state, restore by a governed corrective action when the existing contract can still operate, or deploy replacement contracts and migrate investors through the immutable-contract transition path when the existing contract cannot be safely used. DALP does not automatically rewind chain state after a submitted upgrade transaction completes.

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 actions 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 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 installed component is already up to date or has a newer implementation available. Factory rows can also show how many deployed tokens are affected.

The upgrade workflow acts on installed components whose implementation address differs from the directory. New factory, add-on, or compliance module types are installed from their dedicated management pages, not from the system upgrade workflow.

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. There is no universal public address that 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 its address is registered in the directory or used for a proxy upgrade. Use OpenZeppelin upgrade validation or an equivalent compiler storage-layout comparison for upgradeable implementations. Preserve the validation output, the approved implementation address, and the approver sign-off with the directory update evidence.

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 that contract in place; operators use a governed replacement and migration path instead.

DALP mechanism

For system upgrades, DALP separates these controls:

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. DALP then calls the system migration with the active directory address. If the migration call reaches a contract that is already at the expected version, the contract reverts with its reinitializer guard and the workflow treats that already-migrated response as an idempotent skip.

The directory is the governance boundary for implementation selection. A directory upgrade can register a new SYSTEM implementation, registry implementations, identity factory implementation, account abstraction infrastructure, token factory implementations, add-ons, compliance modules, and chain-of-trust registries. The system upgrade workflow reads those directory pointers. The workflow does not invent implementation addresses during the user-initiated upgrade.

Sub-components use their own migration path. DALP reconciles registered implementation pointers. DALP probes whether each deployed sub-component supports the migration interface and calls migrate(bytes) only when the component supports that interface. Compliance registry migration runs before system compliance migration, because system compliance migration depends on the registry's type-based module records.

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. The token address, OnchainID identity, role assignments, balances, and compliance attachments remain in place.

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, including storage collision, initializer, migration, and implementation-selection paths. Do not treat an audit of only the initial deployment as proof that later upgrade scenarios were reviewed.

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 actions 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 an operator or auditor prove which implementation was selected, who authorized the change, and what state remained stable after the migration.

Include the failed step and retry state when an 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 taking another action.

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 that as a new governed change with its own authorization record.

If investor state is corrupted or cannot be read safely, do not rely on a blind proxy rollback as the 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 actions 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, its roles, compliance configuration, investor identity links, balances, and transaction history attached to the deployed EVM contracts. A handover changes the operator and the authorised accounts. It does not require changing the token address when the active contracts are upgradeable and stay on the same network.

Before a control handover, export or record the evidence another operator needs to run the environment without relying on the previous operator's account:

Use the comparison page as the starting point for handover checks. The page shows whether the active system matches the expected directory for the network. It also 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 transferring 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 admin, governance, custodian, emergency, and supply-management roles are managed per asset. System-level roles are managed separately from asset roles. 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, register investor wallet-to-OnchainID mappings, issue or import the required trusted-issuer claims, and move balances through governed lifecycle actions 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 production roles, custody, compliance policy, investor registry mappings, indexing, and monitoring there. Testnet balances, transactions, identity registry entries, and indexed history remain on the test network.

Run an upgrade

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

Related

• Operations guides
• Blockchain monitoring
• Asset deployment architecture