Skip to main content

Upgrading Configurations

How to roll out new facet versions to token configurations — the ResolverProxy (Diamond) side of upgrades. This is what changes a token's behaviour without redeploying it.

Which upgrade is this?

This page covers upgrading token configurations (Equity, Bond, …). To upgrade the BLR or Factory implementation behind their proxies, see Upgrading infrastructure. The Architecture page explains why these are different.

The model​

Recall the three-level versioning:

  1. Deploy improved facet(s).
  2. registerBusinessLogics in the BLR — this bumps the shared latest version so all facets stay mutually consistent.
  3. Create a new configuration version for the asset type, referencing the new facets.
  4. Move each token you want onto the new version with an explicit updateConfigVersion transaction (called by the token's DEFAULT_ADMIN_ROLE).

No token is ever redeployed — a token's proxy bytecode never changes. Only the configuration version it resolves against changes.

How tokens move between versions​

A token is always pinned to a specific configuration version — there is no automatic tracking of the latest. To move a token, its DEFAULT_ADMIN_ROLE calls updateConfigVersion (or updateConfig / updateResolver) on the token. These are instant, single-transaction operations with no on-chain timelock, so the controlling account should be a multisig.

Running an upgrade​

The upgrade:configs workflow (scripts/cli/upgradeConfigurations.ts) deploys the new facets, registers them, and creates new configuration versions.

BLR_ADDRESS=0x4363684B8a679EaBA17701F421Ddf71D6870A011 \
  npm run upgrade:configs:hedera:testnet

Aliases exist per network (upgrade:configs:local, :hedera:previewnet, :hedera:mainnet), and npm run upgrade:testnet is shorthand for upgrade:configs:hedera:testnet.

Environment variables​

Configured in .env (see the Upgrade workflow section of .env.example):

VariableRequiredMeaning
BLR_ADDRESSYesThe existing BusinessLogicResolver to upgrade.
PROXY_ADDRESSESNoComma-separated ResolverProxy token addresses to move to the new version. Empty = create the version but don't move any token.
CONFIGURATIONSNoWhich configurations to (re)create: equity, bond, or both (default).
USE_TIMETRAVELNoInclude TimeTravel facet variants (testing only).
BATCH_SIZENoFacets processed per transaction.

Selective upgrades​

Upgrade only equities, leaving bonds untouched:

BLR_ADDRESS=0x... CONFIGURATIONS=equity npm run upgrade:configs:hedera:testnet

Multi-environment rollout​

Each environment keeps its own configuration versions. Roll out in order, validating between stages:

BLR_ADDRESS=0xTestnetBLR...    npm run upgrade:configs:hedera:testnet
BLR_ADDRESS=0xPreviewnetBLR... npm run upgrade:configs:hedera:previewnet
BLR_ADDRESS=0xMainnetBLR...    npm run upgrade:configs:hedera:mainnet

Upgrades are checkpointed and resumable — see Checkpoints & recovery.

Verify​

Confirm a token now resolves against the new version:

const proxy = await ethers.getContractAt("ResolverProxy", "<TOKEN_ADDRESS>");
// Inspect the proxy's configuration id/version getters, or call an upgraded function
// and confirm the new behaviour.

You can also confirm the BLR's latest version advanced:

const blr = await ethers.getContractAt("BusinessLogicResolver", "<BLR_PROXY_ADDRESS>");
await blr.getLatestVersion("<resolver key>"); // should reflect the new version

Rollback​

Because previous configuration versions remain registered, rollback is "move the affected tokens back to the previous version" (via updateConfigVersion) rather than a redeploy. Always validate on testnet before touching production.

Pre-upgrade checklist​

  • New facets compiled, registry and hashes regenerated (npm run ats:contracts:build).
  • Storage changes are append-only (see Repository structure).
  • Upgrade tested end-to-end on testnet with a freshly deployed token.
  • BLR_ADDRESS (and PROXY_ADDRESSES if moving tokens) confirmed for the target network.
  • Admin role on affected tokens held by the intended multisig/governance account.