ARC-0006: Program Upgradability

[d0cd]

---

arc: 6
title: Program Upgradability
authors: @ProvableHQ
discussion: link
topic: Protocol
status: Draft
created: 2025-04-16

Abstract

As the Aleo ecosystem matures, it is apparent that applications will need to be upgraded over their lifetime. The Aleo Virtual Machine (AVM) provides a method for program-driven upgrades. This method, while sound, has properties that may be undesirable for some applications. This proposal offers a new method for program upgrades that seeks to be timely and cost-effective, while preventing fragmentation of application state.

Goals

We propose a system for program upgrades with the following properties:

1. Upgrades should be (relatively) cheap for application users.
2. Upgrades should be atomic.
3. Upgrades should take effect immediately.
4. Upgrades should preserve the interface of a program.
   • An upgrade can:
     • change logic in a function or finalize
     • define new structs, records, or mappings but cannot modify or remove existing ones.
     • add new functions and closures
   • An upgrade cannot:
     • change a function’s input and output interface
     • change a finalize’s input interface
     • change logic in a closure. This is because a change in a closure would invalidate all dependent proving and verifying keys.
     • change existing structs, records, or mappings
5. Upgrades can be rejected by dependent applications.
6. Developers must be able to ossify their programs.

Program Component	Delete	Modify	Add
import	❌	❌	✅
struct	❌	❌	✅
record	❌	❌	✅
mapping	❌	❌	✅
closure	❌	❌	✅
function	❌	✅ (logic)	✅
finalize	❌	✅ (logic)	✅
constructor	❌	❌	❌

Design

At a high-level, our proposed design introduces constructors and operands so that users can programmatically define upgrades with the above design goals in mind.

Operands

The Aleo Virtual Machine will support the following new operands:

• <PROGRAM_ID>/checksum
• <PROGRAM_ID>/edition
• <PROGRAM_ID>/program_owner

These specific operands can only be used in off-chain AND on-chain contexts.

Checksum

• The checksum is defined as the SHA3-256 hash of the program string.
• It is available in the finalize scope.
• It is a [u8; 32u32] and is optionally declared in a Deployment transaction.
• Before a defined migration height, the protocol will require that the checksum is NOT defined in a Deployment.
• After a defined migration height, the protocol will require that the checksum is defined in a Deployment.

Edition

• The edition denotes the version of a program.
• It is available in the finalize scope.
• It is a u16 literal and is explicitly declared in a Deployment transaction.
• An edition must be 0 when a program is first deployed and must be incremented by 1 on each upgrade.

Program Owner

• The program_owner is the address that deployed the program.
• It is available in the finalize scope.
• It is an address and is optionally declared in a Deployment transaction.
• Before a defined migration height, the protocol will require that the program_owner is NOT defined in a Deployment.
• After a defined migration height, the protocol will require that the program_owner is defined in a Deployment.

Constructors

Programs can define constructors which are immutable (they cannot be upgraded) sequences of code that are always run on-chain as part of a deployment or upgrade. Here is an example:

program foo.aleo;
...
constructor:
  assert.eq foo.aleo/edition 0u16;

In this example, the constructor checks that its edition is always zero, ensuring that the program cannot be upgraded.

Additionally, constructors have the following rules:

• If a constructor halts, then the deployment or upgrade will fail.
• A program without a constructor is NOT upgradable.
• A program WITH a constructor is upgradable.
• Programs deployed after program upgradability is supported must all have constructors.

A core idea of this design is to allow developers to define rich instantiation and upgrade logic that suits their needs. Refer to the Usage section for more examples.

Verifying a Deployment

To support upgrades, deployments are checked using the additional rules:

• Before upgradability is enabled:
  • the deployment edition is zero.
  • the deployment checksum is None
  • the deployment owner is None
  • the deployment program does NOT use constructor or any of the new operands.
• After upgradability is enabled:
  • The deployment checksum is Some and that it matches the program.
  • The deployment owner is Some and that it matches the transaction
  • The program contains a constructor
• If the edition is zero (N::EDITION), then check that:
  • the program does not exist in the DB or in-memory Process
• Otherwise, check that:
  • the program does exist in the DB and in-memory Process
  • the new edition increments the old edition by 1
  • the upgraded code is well-formed and does not violate any of the upgrade rules
  • the existing program has a constructor.

Changes to the VM and DB

In order to ensure that upgrades are correct and preserve existing state, we also require that:

• The deployment storage store all versions of the programs.
• When an upgrade is deployed, the VM/DB should use the same program state (mappings, records, etc.) as before. If an upgrade defines additional state (mappings), it should be initialized and added to the same scope.
• A call should resolve to the latest version of the program.

Cost

A constructor uses the same cost model as on-chain execution, with a multiplier. Currently, this multiplier is set to 100.

Implementation

The tracking issue for the implementation can be found here.

Security & Compliance

Protocol

The protocol must ensure that:

• existing programs are valid and not upgradable.
• an upgrade does not break an existing program’s interface.
• an edition is always incremented by 1.
• prior editions are present but invalid.
• cyclic programs do not create issues.
• users should have a way of explicitly opting in to a program upgrade before executing.

Application

Upgrades are a powerful mechanism for improving program usability and management. However, mutability fundamentally introduces new risks for users and dependent applications.

Mutable applications can be modified in malicious ways. For example, a developer can modify program logic to introduce a vulnerability or freeze the function. They could even introduce a new function to drain funds.

In the general case, there is not much a user can do. Users should validate that applications are written correctly and build trust in developers. Developers can demonstrate good intent to users by relying on governance mechanisms or restrictions to what an upgrade can do. Developers can use the upgrade mechanism to “ossify” a program by setting the authority to a “null” value, like the zero address. Ultimately, these are only mitigations and the burden falls on the user to do due-diligence.

Dependent programs have some defenses available to them. In Usage, we detail a mechanism where upgrades must be explicitly approved. This allows developers to fix dependent programs and issue a migration when a dependent makes a divergent change. It is worth noting that protocols like Sui do not atomically apply upgrades; the dependent application defaults to the old logic until the developer issues an upgrade. This option, while mitigating risks of malicious upgrades, prevents security patches or critical features from being applied immediately, which can be an issue.

Developers also need to be mindful of the fact that constructors are immutable. This means that a bug in the constructor logic cannot be fixed by rolling out a new upgrade. Developers should take special care and perform security audits.

The protocol provides some application security by requiring that all executions contains signatures over the checksums of the programs they intend to execute. This reduces the likelihood that a malicious developer front-runs an execution with an upgrade that a user did not know about.

Audits

Audits have been completed and their findings are addressed in this PR: ProvableHQ/snarkVM#2758.
The reports will be made public.

Usage

In this section, we detail how constructors and metadata declarations can be used to implement a variety of upgrades.

Not Upgradable

Goal. Define a program that cannot be upgraded.

program foo.aleo;
... // A program without a constructor cannot be upgraded.

program foo.aleo;
...
constructor:
  assert.eq foo.aleo/edition 0u16; // Upgrades will be rejected as their editions will always be nonzero.

Anyone Can Upgrade

Goal. Define a program that anyone can upgrade.

program foo.aleo;
...
constructor: 
  assert.eq true true: 
...

Fix Dependency

Goal. Require that a dependent program is on a specific version.
Important. If using this pattern, we recommend you make your program upgradable, in case your function is locked due to a dependency upgrade.

Remove Upgradability

Goal. Allow a developer to lock a program from future upgrades.
Important. Note that this pattern can be generalized to support ‘toggle-able’ upgrades.

program foo.aleo;
...
mapping locked: // Once an entry is set, assuming that there is no code that removes it, the program will be locked from future upgrades.
    key as boolean;
    value as boolean;
...
constructor:
    contains locked[true] into r0;
    assert.eq r0 false;
...

Admin-Driven Upgrades

Goal. Define a program that only an authorized admin can upgrade.

Important. Note that the admin account can NEVER be changed. This pattern should be used IFF the private key associated with the admin is properly secured.

program foo.aleo;
...
constructor:
    assert.eq program_owner <ADMIN_ADDRESS>; // You can add any number of admin addresses.
...

Content-Locked Upgrades

Goal. Define a program that can only be upgraded to a program with some specific contents.
This helps ensure that an upgrade has some pre-determined logic.

program foo.aleo;
...
mapping expected:
    key as boolean;
    value as u128;
...
constructor:
    branch.eq foo.aleo/edition 0u16 to end;
    get expected[true] into r0; // Assume that there was some mechanism to set the expected value.
    assert.eq foo.aleo/checksum r0;
    position end;
...

Configurable Admin-Driven Upgrades

Goal. Define a program that only an authorized admin can upgrade, with the option to swap admins and declare programs upfront.
This pattern combines the ideas behind Content-Locked Upgrades with the notion of an administrator.

program foo.aleo;
...
mapping admin:
    key as boolean.public;
    value as address.public;
...
mapping expected:
    key as boolean;
    value as [u8; 32u32];
...
constructor:
    branch.neq foo.aleo/edition 0u16 to rest;
    set aleo1... into admin[true]; // Set the admin.
    branch.eq true true to end;
    position rest;
    get expected[true] into r0; 
    assert.eq foo.aleo/checksum r0; // Check that the checksum matches.
    position end;
...
function set_expected:
    input r0 as [u8; 32u32].public;
    async set_expected self.caller r0 into r1;
    output r1 as foo.aleo/set_expected.future;
finalize set_expected:
    input r0 as address.public; // The caller.
    input r1 as [u8; 32u32].public; // The expected checksum.
    get admin[true] into r2; // Get the admin.
    assert.eq r0 r2; // Check that the caller is an admin.
    set r1 into expected[true]; // Set the next expected upgrade.
...

Vote-Driven Upgrades

Goal. Define a program that can only be upgraded by an approving vote from a governance contract. \

import governor.aleo; // Assume `governer.aleo` has some logic for voting on upgrades. Accepted votes are recorded in a mapping `accepted` which contains an expected checksum.

program foo.aleo;
...
constructor:
    branch.eq foo.aleo/edition 0u16 to end;
    get governor.aleo/accepted[true] into r0;
    assert.eq foo.aleo/checksum r0;
    position end;

Time-Locked Upgrades

Goal. Define a program that can only be upgraded after a specific block height.

program foo.aleo;
...
constructor:
    gte block.height 10u32 into r0;
    assert.eq r0 true; // Upgrades can be made by anyone, only after block 10.
...

To Developers

• It is important to note that closures are NOT upgradable since they make up the verification keys of any function that calls them. Developers should only call external closures that they have verified the functionality of.
• We strongly recommend that production applications define a secure upgrade pathway. This will allow applications to stay up-to-date with future protocol changes that may affect the underlying circuits

To Reviewers

• Is there a usage of program upgrades this proposal does not cover?
• Does the upgrade model feel easy to use? Is it operationally safe?
• Should developers be allowed to mark functions as immutable? The current thinking is to defer this to future work, if developers ask for it.

[evanmarshall]

A couple of considerations.

1. I don't think existing programs should be potentially upgradeable. Before this ARC, it didn't matter which address deployed a program. This one time upgrade mechanism is a large security concern. For pondo & token_registry programs, I would have to audit which keys we used to deploy those programs and ensure they were handled safely at all points. I'm guessing not as before it wouldn't matter and it made sense to use disposable keys. I would make sure if there is a one-time upgrade that it's explicitly opt-in not based on the original owner address that deployed the program. There should absolutely be some manual process to verify the true owner.
2. Is the credits.aleo program going to be upgradeable through this mechanism?

[d0cd]

1. This is a fair consideration. We have option of considering other one-time mechanisms including, restricted updates to constructors that restrict upgradability. Another option is to allow a one-time upgrade with the new content agreed upon beforehand. This would require a lot more coordination by the ANF and community. It would be helpful to get an accurate risk assessment for the keys you used and for other community members to weigh in.
2. No, the credits program will not have a constructor or an owner.

[evanmarshall]

1. I used the address: aleo14ufp2emj0h2hxz5szczmh67sy6jt8wrhujd8q0758lwdl3dxcgzsnych8z. This is a hot key. We absolutely shouldn't allow it to do a one-time upgrade to programs like the token_registry.aleo or pondo_protocol.aleo. In general, I would advise against a one time upgrade as the rule and if there are exceptions, we can manually coordinate them.
2. It seems like the credits.aleo program could have a constructor that takes an array of signatures and then ensures any change has sufficient vote from the committee. This may help set future parameters like minimum delegated stake without requiring a migration in snarkVM

[zklimaleo]

Comments on the above:

1. I agree @evanmarshall viewpoint on disallowing one-time upgrade in existing programs, everyone has the same assumption on deployed programs are immutable. If applications wish to make changes, it can be explicitly requiring users to migrate to new program.

Other questions / comments:

1. Is program_owner involved in the process of upgrading a program? It doesn't seem so from the examples above.
2. How exactly to make a program upgrade such as what parameters are required for both modification or new addition, which endpoint to send request to. Would also be clearer if all inputs were explicitly defined as the constructor parameters (new program codes, current/next edition etc.)
3. Can constructor initializes mapping values? (Though the 100x fee multiplier may discourage this pattern.)
4. Does the constructor runs during first deployment, if yes the Time-Locked Upgrades example will fail deployment if specific block height is not reached.
5. Is branch.neq foo.aleo/edition 0u16 to end; in Content-Locked Upgrades and Vote-Driven Upgrades intended to disable rules for first deployment? It seems to be disabling rules for all future upgrades instead.
6. Isn't every upgrade will invalidate all dependent proving and verifying keys? If so closures should be upgradeable too. Any vulnerability in closure logic would still require an upgrade to fix. Without modifiability, unused or obsolete code could accumulate and taking up valuable space especially given the program size limits.

[d0cd]

1. Yes, program_owner can now be used as an operand when defining constructor logic. Fixed a typo in the Admin-Driven Upgrades example.
2. Constructors are immutable and cannot take parameters. Leo hopes provide users with a sane development flow to help them develop and manage upgrades.
3. Yes they can!
4. Good observation, the time-locked example could be updated to only check for editions > 0.
5. Yes, that's a typo.
6. That's a fair point, we should consider this.