Skip to main content
Version: v1

DApp updatability

This guide explains updatability in the Midnight Network and shows how to update a deployed contract's maintenance authority.

Overview​

Updating code in a decentralized environment is challenging because producing an update typically requires a centralized process, which attackers can exploit maliciously. However, DApp developers often need ways to change deployed contracts, and Midnight provides this through Contract Maintenance Authorities (CMAs).

By default, an empty maintenance authority prevents any user from updating the contract. At deploy time, the deployer can nominate public keys and set a signature threshold that determines how many keys must sign an update to enable contract updatability.

This mechanism lets you decentralize update authority to a group requiring joint approval, or grant control to a single owner.

warning

While Midnight does not require you to nominate a CMA for your deployed contract, we strongly advise DApp authors to understand the trade-offs before making this decision.

Why should you care?​

Even if you are familiar with updatability in other blockchain ecosystems, Midnight has an important difference that might affect what you choose for your DApp. Most blockchains guarantee that deployed contracts run indefinitely as deployed, reducing the need for updatability.

Midnight differs because contracts are in part zero-knowledge proofs. Breaking updates to the proof system – including security updates – may require contracts to update to the new proof system. This means the system might disable old contracts after upgrades.

This is especially true before mainnet launch. During this period, there is no support for older proof system versions. There will be a support policy at or before mainnet launch.

With appropriate notice, support will be removed for old contract deployments. Updatable contracts can migrate to new versions, but non-upgradable contracts cannot. For the complete version overview, refer to the release compatibility matrix.

danger

Non-upgradable contracts should let users withdraw their funds within a week to prevent loss of user funds. Upgradable contracts should commit to upgrade timelines or provide a path to withdraw funds if you do not upgrade the contract.

Currently, Midnight's APIs support only single-user authorities, although the underlying system can handle arbitrary party configurations.

Capabilities of a maintenance authority​

A Contract Maintenance Authority (CMA) performs various privileged actions to change a contract after deployment. These actions use a 'verifier key version', which combines the proving system version and the onchain runtime version. Contracts support multiple active verifier key versions simultaneously, with keys registered for each version. This enables transitions between versions and may provide long-term support for some verifier key versions in the future.

A CMA can perform the following privileged actions:

  • Change the CMA associated with this contract. The new CMA succeeds the current one, letting you relinquish control.
  • Remove a verifier key (of a specific version) from the contract. The contract rejects future transactions that attempt to use this operation with the removed verifier key version. The key with that version must exist before removal.
  • Add a new verifier key of a specific version. This adds new functionality to a contract or re-exports existing functionality with a new verifier key version. A key with that version must not already exist; if it does, remove it first.
info

Removing and re-adding a verifier key lets you change the implementation of a circuit, modifying its behavior. Be aware that this is a very powerful capability!

Maintenance authorities make changes by signing a sequence of these single updates into a combined maintenance update. Currently, maintenance updates take effect immediately, although future releases may refine this functionality.

Operate a maintenance authority​

Operating a maintenance authority requires a DApp developer to:

  • Generate and store key pairs for the authority.
  • Modify deployment to add the authority.
  • Provide an interface for the authority to produce and sign updates.

You can specify the initial contract authority by providing a value for signingKey in the DeployContractOptions. Generate the initial signing key using sampleSigningKey. You can reuse the same CMA across multiple contracts by specifying the same signing key for different deployments.

You can update a deployed contract's circuits using the DeployedContract object's circuitMaintenanceTx property, which contains one CircuitMaintenanceTxInterface for each circuit defined on the contract. Use insertVerifierKey to add new verifier keys and removeVerifierKey to remove existing ones.

Similarly, you can update a deployed contract's maintenance authority using the DeployedContract's contractMaintenanceTx property.

Example​

The following example demonstrates how to insert a new verifier key for a deployed contract's circuit, where foo represents the circuit name you want to update.

import { findDeployedContract } from '@midnight-ntwrk/midnight-js-contracts';

// Find the deployed contract
const deployedContract = await findDeployedContract({
  contractAddress: '0x1234567890abcdef',
});

// Insert a new verifier key for the 'foo' circuit
await deployedContract.foo.insertVerifierKey(newVerifierKey);

Next steps​

Now you understand how to update a deployed contract's maintenance authority. Check out the following resources to learn more about building DApps on the Midnight network: