Deploy Celo core contract releases using Foundry tooling. Use when releasing contracts, testing releases on forks, generating governance proposals, or when user mentions release, deploy, upgrade contracts, CR14, CR15, make-release, or verify-deployed.
Instrucciones de origen · Vista previa de solo lectura
name
celo-release
description
Deploy Celo core contract releases using Foundry tooling. Use when releasing contracts, testing releases on forks, generating governance proposals, or when user mentions release, deploy, upgrade contracts, CR14, CR15, make-release, or verify-deployed.
Celo Core Contracts Release
Deploy and test Celo core contract releases using Foundry-based tooling.
Quick Reference
Step
Command
Output
1. Generate libraries.json
verify-deployed:foundry -b <PREVIOUS_TAG>
libraries.json
2. Generate report
check-versions:foundry -a <PREVIOUS_TAG> -b <NEW_BRANCH>
Deployer keys are stored in encrypted mnemonic files in the repo root:
Network
Mnemonic File
Encrypted File
Celo Sepolia
.env.mnemonic.celosepolia
N/A (manual)
Mainnet
.env.mnemonic.mainnet
.env.mnemonic.mainnet.enc
Decrypting Keys (cLabs employees)
# Decrypt all mnemonic files using GCP KMS
yarn keys:decrypt
Using Keys
Each mnemonic file exports DEPLOYER_PRIVATE_KEY. Source it before running release commands:
# For Celo Sepoliasource .env.mnemonic.celosepolia
# For Mainnetsource .env.mnemonic.mainnet
Then use $DEPLOYER_PRIVATE_KEY in release commands.
Release Workflow
Step 0: Confirm Release Parameters with User
IMPORTANT: Before executing any release commands, you MUST:
Query available tags and branches:
git tag -l 'core-contracts.*' | sort -V | tail -15
git branch -a | grep 'release/core-contracts'
Determine the release source using this priority order:
Tag priority (check in order, use first match):
Post-audit tag (if exists): core-contracts.vN.post-audit or core-contracts.vN.post_audit
Base tag: core-contracts.vN
Release branch: release/core-contracts/N (only if no tags exist)
Note: Not all releases have post-audit tags. If one exists, use it; otherwise use the base tag.
For the NEW release: Check for post-audit tag first, then base tag, then branch.
For the PREVIOUS release: Same logic - use post-audit tag if available, otherwise base tag.
Present a confirmation to the user with:
Previous release tag (for libraries.json): e.g., core-contracts.v14 or core-contracts.v14.post-audit
New release source: Following the priority above
Target network: e.g., celo-sepolia or celo
Use the AskQuestion tool to get explicit confirmation:
Option to confirm the proposed tags/branches
Option to specify different tag/branch
Only proceed with the release after user confirmation.
Example confirmation prompt (when post-audit tag exists):
I plan to release with the following parameters:
- Previous release tag: core-contracts.v14.post-audit
- New release tag: core-contracts.v15.post-audit
- Target network: celo-sepolia
Please confirm or specify different values.
Example confirmation prompt (when only base tag exists):
I plan to release with the following parameters:
- Previous release tag: core-contracts.v14
- New release tag: core-contracts.v15
- Target network: celo-sepolia
Please confirm or specify different values.
Example confirmation prompt (when only branch exists):
I plan to release with the following parameters:
- Previous release tag: core-contracts.v14
- New release branch: release/core-contracts/15 (no tag found)
- Target network: celo-sepolia
Please confirm or specify different values.
Step 1: Generate libraries.json
Verify the currently deployed release to get library addresses:
cd packages/protocol
# For Celo Sepolia
yarn release:verify-deployed:foundry -b core-contracts.v${PREVIOUS} -n celo-sepolia
# For Mainnet
yarn release:verify-deployed:foundry -b core-contracts.v${PREVIOUS} -n celo
# Check if file existscat ./releaseData/initializationData/release${NEW}.json
# If missing, create empty (valid if no new contracts)echo"{}" > ./releaseData/initializationData/release${NEW}.json
# First regenerate libraries.json for mainnet!
yarn release:verify-deployed:foundry -b core-contracts.v${PREVIOUS} -n celo
yarn release:make:foundry \
-b release/core-contracts/${NEW} \
-k $MAINNET_DEPLOYER_KEY \
-i ./releaseData/initializationData/release${NEW}.json \
-l ./libraries.json \
-n celo \
-p ./proposal-mainnet.json \
-r ./releaseData/versionReports/release${NEW}-report.json
Release Artifacts
Artifact
Location
Purpose
libraries.json
packages/protocol/
Library addresses (network-specific!)
Version report
releaseData/versionReports/releaseN-report.json
Contract changes & version deltas
Init data
releaseData/initializationData/releaseN.json
Constructor args for new contracts
Proposal
proposal-*.json
Governance transactions
Important: libraries.json is network-specific. Regenerate when switching between Celo Sepolia and Mainnet.
Determining Release Numbers
Priority: Always prefer git tags over branches. Post-audit tags are preferred over base tags.
# List existing tags (check these FIRST)
git tag -l 'core-contracts.*' | sort -V | tail -15
# List release branches (fallback if no tag exists)
git branch -a | grep 'release/core-contracts'
Tag priority (check in order, use first match):
core-contracts.vN.post-audit or core-contracts.vN.post_audit - Post-audit (if exists)
core-contracts.vN - Base tag
release/core-contracts/N - Branch (fallback only)
Note: Not all releases have post-audit tags. Use it if available, otherwise use the base tag.
Selection logic:
For NEW release: Check for post-audit tag first, then base tag, then branch
For PREVIOUS release: Same logic - use post-audit tag if available, otherwise base tag
Starting a Local Fork
Before testing on a local fork, start Anvil with the required parameters:
Note: The Etherscan V2 API uses a unified endpoint (api.etherscan.io) that works with a single API key for all supported chains including Celo.
Skip Verification
To skip verification (e.g., for testing or if you don't have an API key):
yarn release:make:foundry ... -s
Verification is automatically skipped when using a custom RPC URL (local forks).
Verification Troubleshooting
"Address is not a smart-contract": Block explorer hasn't indexed the contract yet. The script waits 30s initially, then automatically retries up to 6 times with logarithmic delays (5s, 10s, 20s, 40s, 60s max).
"Bytecode mismatch": Usually caused by wrong foundry profile. The script now automatically sets FOUNDRY_PROFILE based on contract source path.
Linked library errors: The script automatically detects and passes library addresses via --libraries flag for contracts that use linked libraries.
Common Issues
"libraries.json not found"
Run verify-deployed:foundry first with the previous release tag.
"Version mismatch detected"
Update getVersionNumber() in the contract to match expected version from the report.
"Deployment reverted" or "Out of gas" on Local Fork
Ensure Anvil is started with --code-size-limit 500000 --gas-limit 100000000.
