Skip to main content

Upgrade Process

Locale Network provides upgrade process templates that City Chains can adopt for managing protocol changes. These are not built-in systems—each community configures upgrade governance according to their security requirements and decentralization goals.

Upgrade Templates

The upgrade processes described here are templates. Each City Chain implements upgrade governance according to their community's requirements for security, speed, and decentralization.

Upgrade Types​

Parameter Changes​

Adjustments to existing protocol values:

ExamplesRisk LevelTypical Process
Gas limitsLowCouncil vote
Fee percentagesLowCommunity vote
Timelock durationsMediumSupermajority vote
Quorum thresholdsMediumSupermajority vote

Contract Upgrades​

Changes to smart contract logic:

ExamplesRisk LevelTypical Process
Bug fixesMediumCouncil + short timelock
Feature additionsMediumCommunity vote + timelock
Core logic changesHighSupermajority + long timelock
Proxy updatesHighSupermajority + audit

Infrastructure Changes​

Updates to underlying systems:

ExamplesRisk LevelTypical Process
Sequencer updatesMediumCouncil decision
Node softwareMediumCoordinated rollout
Bridge contractsHighSupermajority + audit
L1 contract changesCriticalFull governance + audit

Governance Process​

Standard Upgrade Flow​

Upgrade Governance Flow
1
Proposal Submitted
Community member initiates upgrade
2
Discussion Period
7 days for community review
3
Voting
Token-weighted, 5-day window
4
Timelock
48-hour delay before execution
Executed
Upgrade applied on-chain

Proposal Requirements​

RequirementDescription
Technical SpecificationDetailed description of changes
Code ChangesDiff or implementation details
Security AnalysisRisk assessment and mitigations
Testing ResultsTestnet deployment and testing
Rollback PlanHow to revert if issues arise

Voting Requirements​

Upgrade TypeQuorumThresholdVoting Period
Parameter4%50%3 days
Minor Upgrade6%60%5 days
Major Upgrade10%66%7 days
Critical Change15%75%14 days

Timelock System​

Purpose​

Timelocks provide a delay between vote approval and execution:

BenefitDescription
Review PeriodTime to catch issues
Exit WindowUsers can exit before changes
Challenge PeriodGuardian can cancel malicious upgrades
TransparencyAll changes visible before effect

Timelock Durations​

Change TypeTimelockReasoning
Parameter Adjustment24-48 hoursLow risk, faster iteration
Contract Upgrade7 daysStandard security window
Core Protocol Change14 daysMaximum review time
Emergency Fix4-24 hoursBalance speed and security

Emergency Procedures​

Guardian Powers​

For early-stage City Chains, a Guardian multi-sig can:

ActionRequirementUse Case
Pause Contracts2-of-5Active exploit
Emergency Upgrade4-of-5Critical vulnerability
Cancel Proposal3-of-5Malicious upgrade detected
Reduce Timelock4-of-5Urgent fix needed

Emergency Process​

  1. Detection — Identify critical issue
  2. Assessment — Guardian evaluates severity
  3. Pause — If needed, pause affected contracts
  4. Fix Development — Create and test patch
  5. Fast-Track Vote — Shortened voting period
  6. Expedited Execution — Reduced timelock
  7. Post-Mortem — Document incident and response

Pause Functionality​

Pause LevelEffectAuthority
PartialSpecific functions disabled2-of-5 Guardian
FullAll non-essential operations paused3-of-5 Guardian
EmergencyComplete protocol pause4-of-5 Guardian

Upgrade Patterns​

Proxy Upgrades​

Upgradeable contracts using proxy pattern:

ComponentDescription
Proxy ContractFixed address, delegates calls
ImplementationContains logic, can be upgraded
AdminGovernance-controlled upgrade authority
StoragePreserved across upgrades

Modular Upgrades​

Separate contracts for different functions:

AdvantageDescription
Isolated RiskChange one module without affecting others
Easier TestingTest modules independently
Parallel DevelopmentMultiple upgrades simultaneously
Gradual RolloutUpgrade modules one at a time

Feature Flags​

Enable/disable features without code changes:

Use CaseDescription
Gradual RolloutEnable for subset of users
Quick DisableTurn off problematic features
A/B TestingCompare different implementations
Emergency Kill SwitchInstant feature shutdown

Security Considerations​

Audit Requirements​

Upgrade TypeAudit Requirement
Parameter ChangeInternal review
Minor FeatureInternal + external review
Major UpgradeFull external audit
Core ProtocolMultiple independent audits

Testing Requirements​

Test TypeDescriptionWhen Required
Unit TestsIndividual function testsAll changes
Integration TestsCross-contract interactionsFeature changes
Fork TestsSimulate on mainnet stateMajor upgrades
Testnet DeployFull environment testingAll upgrades

Risk Assessment​

Risk CategoryConsiderations
TechnicalCode bugs, unexpected interactions
EconomicToken value impact, treasury effects
SecurityNew attack vectors, permission changes
OperationalUpgrade execution, rollback ability

Decentralization Path​

Upgrade Authority Evolution​

PhaseUpgrade AuthorityGuardian Role
LaunchGuardian + lite governanceFull emergency powers
GrowthCommunity vote + Guardian vetoEmergency only
MatureFull community governanceExpired or minimal
DecentralizedToken holder governanceNone

Reducing Guardian Powers​

MilestoneAction
6 monthsRemove parameter change authority
12 monthsRemove non-emergency upgrade authority
18 monthsRemove veto power
24 monthsGuardian sunsets completely

Implementation Guide​

Setting Up Upgrade Governance​

  1. Deploy Timelock — Configure delay periods
  2. Deploy Governor — Set voting parameters
  3. Configure Proxies — Point to timelock as admin
  4. Set Up Guardian — Initialize multi-sig
  5. Test Upgrades — Simulate on testnet
  6. Document Process — Clear upgrade procedures

Upgrade Checklist​

StepAction
☐Write technical specification
☐Complete code changes
☐Run all tests
☐Deploy to testnet
☐Conduct security review
☐Submit governance proposal
☐Community discussion period
☐Voting period
☐Timelock waiting period
☐Execute upgrade
☐Monitor for issues
☐Document completion

Learn More​