Skip to content

Fix smart contracts release process docs #2139

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
martinvol wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Fix smart contracts release process docs #2139

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 29 additions & 27 deletions contribute-to-celo/release-process/smart-contracts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@ sidebarTitle: "Smart Contracts"
og:description: Details of the release process for updating smart contracts on the Celo platform.
---

export const N = "N";

Details of the release process for updating smart contracts on the Celo platform.

<Warning>
Expand Down Expand Up @@ -44,7 +42,7 @@ Mixin contracts and libraries are considered part of the contracts that consume

### Initialize Data

Whenever Celo Core Contracts need to be re-initialized, their initialization arguments should be checked into version control under `packages/what-is-celo/about-celo-l1/protocol/releaseData/initializationData/release${N}.json`.
Whenever Celo Core Contracts need to be re-initialized, their initialization arguments should be checked into version control under `packages/protocol/releaseData/initializationData/release${N}.json`.

### Release management in Git/Github

Expand All @@ -55,13 +53,13 @@ Github branches/tags and Github releases are used to coordinate past and ongoing
1. A new release branch is created `release/core-contracts/${N}` with the contracts to be audited.
2. The latest commit on the release branch is tagged with `core-contracts.v${N}.pre-audit`.
3. On Github, a pre-release Github release should be created pointing at the latest tag on the release branch.
4. On master branch, `.circleci/config.yml` should be edited so that the variable `RELEASE_TAG` points to the tag `celo-core-contracts-v${N}.pre-audit` so that all future changes to master are versioned against the new release.
4. On master branch, `.github/workflows/celo-monorepo.yml` should be edited so that the variable `RELEASE_TAG` points to the tag `celo-core-contracts-v${N}.pre-audit` so that all future changes to master are versioned against the new release.
5. Ongoing audit responses/fixes should continue to go into `release/celo-core-contracts/${N}`.

#### After a completed release process:

1. The release branch should be merged into `master` with a merge commit (instead of the usual squash merge strategy).
2. On master branch, `.circleci/config.yml` should be edited so that the variable `RELEASE_TAG` points to the tag `core-contracts.v${N}`
2. On master branch, `.github/workflows/celo-monorepo.yml` should be edited so that the variable `RELEASE_TAG` points to the tag `core-contracts.v${N}`

## Release Process

Expand Down Expand Up @@ -90,13 +88,14 @@ yarn tags:view

```bash
# Run from `packages/protocol` in the celo-monorepo
PREVIOUS_RELEASE="core-contracts.v${N-1}"
NETWORK=${"baklava"|"alfajores"|"mainnet"}
N=15 # release number
PREVIOUS_RELEASE="core-contracts.v$((N-1))"
NETWORK= # "mainnet" or "celo-sepolia"
# A -f boolean flag can be provided to use a forno full node to connect to the provided network
yarn release:verify-deployed -n $NETWORK -b $PREVIOUS_RELEASE -f
```

A `libraries.json` file is written to disk only necessary for `release:make` that describes linked library addresses.
A `$NETWORK-$PREVIOUS_RELEASE-libraries.json` file is written to disk that describes linked library addresses. This file is required by `release:make`.

### Check Backward Compatibility

Expand Down Expand Up @@ -124,11 +123,12 @@ check for it.
The script generates a detailed report on version changes in JSON format.

```bash
PREVIOUS_RELEASE="core-contracts.v${N-1}"
RELEASE_CANDIDATE="core-contracts.v${N}"
yarn release:check-versions -a $PREVIOUS_RELEASE -b $RELEASE_CANDIDATE -r "report.json"
yarn release:check-versions -a $PREVIOUS_RELEASE -b $RELEASE_CANDIDATE
```

The report is written to `report-$PREVIOUS_RELEASE-$RELEASE_CANDIDATE.json`.

This should be used in tandem with `release:verify-deployed -b $PREVIOUS_RELEASE -n $NETWORK` to ensure the compatibility checks compare the release candidate to what is actually active on the network.

### Deploy the release candidate
Expand All @@ -137,11 +137,13 @@ Use the following script to build and deploy a candidate release. This takes as
STORAGE updates are adopted by deploying a new proxy/implementation pair. This script outputs a JSON contract upgrade governance proposal.

```bash
NETWORK=${"baklava"|"alfajores"|"mainnet"}
NETWORK= # "mainnet" or "celo-sepolia"
RELEASE_CANDIDATE="core-contracts.v${N}"
yarn release:make -b $RELEASE_CANDIDATE -n $NETWORK -r "report.json" -i "releaseData/initializationData/release${N}.json" -p "proposal.json" -l "libraries.json"
yarn release:make -b $RELEASE_CANDIDATE -n $NETWORK -r "report-$PREVIOUS_RELEASE-$RELEASE_CANDIDATE.json" -i "releaseData/initializationData/release${N}.json" -l "$NETWORK-$PREVIOUS_RELEASE-libraries.json" -k $PRIVATE_KEY
```

The proposal is written to `proposal-$NETWORK-$RELEASE_CANDIDATE.json`.

The proposal encodes STORAGE updates by repointing the Registry to the new proxy. Storage compatible upgrades are encoded by repointing the existing proxy's implementation.

### Submit Upgrade Proposal
Expand All @@ -150,7 +152,7 @@ Submit the autogenerated upgrade proposal to the Governance contract for review

```bash
# resultant proposal ID should be communicated publicly
celocli governance:propose --deposit 100e18 --from $YOUR_ADDRESS --jsonTransactions "proposal.json" --descriptionURL https://github.com/celo-org/governance/blob/main/CGPs/cgp-0055.md
celocli governance:propose --deposit 100e18 --from $YOUR_ADDRESS --jsonTransactions "proposal-$NETWORK-$RELEASE_CANDIDATE.json" --descriptionURL https://github.com/celo-org/governance/blob/main/CGPs/cgp-0055.md
```

### Fetch Upgrade Proposal
Expand All @@ -171,7 +173,7 @@ Additionally, include `initialization_data.json` from the CGP if any of the cont

```bash
RELEASE_CANDIDATE="core-contracts.v${N}"
NETWORK=${"baklava"|"alfajores"|"mainnet"}
NETWORK= # "mainnet" or "celo-sepolia"
# A -f boolean flag can be provided to use a forno full node to connect to the provided network
yarn release:verify-release -p "upgrade_proposal.json" -b $RELEASE_CANDIDATE -n $NETWORK -f -i initialization_data.json
```
Expand All @@ -182,7 +184,7 @@ After a release executes via Governance, you can use `release:verify-deployed` a

```bash
RELEASE="core-contracts.v${N}"
NETWORK=${"baklava"|"alfajores"|"mainnet"}
NETWORK= # "mainnet" or "celo-sepolia"
yarn release:verify-deployed -n $NETWORK -b $RELEASE -f
```

Expand Down Expand Up @@ -218,7 +220,7 @@ After a successful release execution on a testnet, the resulting network state s
```
- Complete a round of attestation
- Redeem from Escrow
- Register a Vaildator
- Register a Validator
```bash
celocli validator:register --blsKey <hexString> --blsSignature <hexString> --ecdsaKey <hexString> --from <addr>
```
Expand All @@ -227,7 +229,7 @@ After a successful release execution on a testnet, the resulting network state s
```bash
celocli election:run
```
- Get a valildator slashed for downtime and ejected from the validator set
- Get a validator slashed for downtime and ejected from the validator set
- Propose a governance proposal and get it executed
```bash
celocli governance:propose --jsonTransactions <jsonFile> --deposit <number> --from <addr> --descriptionURL https://gist.github.com/yorhodes/46430eacb8ed2f73f7bf79bef9d58a33
Expand Down Expand Up @@ -345,14 +347,14 @@ Deploying a new contract release should occur with the following process. On-cha
<li>
On Tuesday: Run the{" "}
<a href="#release-process">smart contract release script</a>{" "}
in order to to deploy the contracts to Baklava as well as submit a
in order to to deploy the contracts to Celo Sepolia as well as submit a
governance proposal.
<ul>
<li>
Transition proposal through Baklava governance process.
Transition proposal through Celo Sepolia governance process.
</li>
<li>
Update your forum post with the Baklava <code>PROPOSAL_ID</code>,
Update your forum post with the Celo Sepolia <code>PROPOSAL_ID</code>,
updated timings (if any changes), and notify the community in the
Discord <code>#governance</code> channel.
</li>
Expand All @@ -365,17 +367,17 @@ Deploying a new contract release should occur with the following process. On-cha
<td>T+3w</td>
<td>
<ol>
<li>Confirm all contracts working as intended on Baklava.</li>
<li>Confirm all contracts working as intended on Celo Sepolia.</li>
<li>
Run the{" "}
<a href="#release-process">
smart contract release script
</a>{" "}
in order to to deploy the contracts to Alfajores as well as submit a
in order to to deploy the contracts to Celo Sepolia as well as submit a
governance proposal.
</li>
<li>
Update your forum post with the Alfajores <code>PROPOSAL_ID</code>,
Update your forum post with the Celo Sepolia <code>PROPOSAL_ID</code>,
updated timings (if any changes), and notify the community in the
Discord <code>#governance</code> channel.
</li>
Expand All @@ -386,7 +388,7 @@ Deploying a new contract release should occur with the following process. On-cha
<td>T+4w</td>
<td>
<ol>
<li>Confirm all contracts working as intended on Alfajores.</li>
<li>Confirm all contracts working as intended on Celo Sepolia.</li>
<li>
Confirm audit is complete and make the release notes and forum post
contain a link to it.
Expand Down Expand Up @@ -446,7 +448,7 @@ Deploying a new contract release should occur with the following process. On-cha
<code>Passed</code> or <code>Rejected</code>) and notify the
community in the Discord <code>#governance</code> channel.
</li>
<li>Change corresponding CGP status to EXCECUTED.</li>
<li>Change corresponding CGP status to EXECUTED.</li>
<li>
Merge the release branch into <code>master</code> with a merge
commit
Expand Down Expand Up @@ -476,9 +478,9 @@ Each smart contract release governance proposal should be accompanied by a [Gove
- Background information.
- Link to the release on Github.
- Link to the audit report(s).
- Anticipated timings for the Baklava and Alfajores testnets and Mainnet.
- Anticipated timings for the Celo Sepolia testnet and Mainnet.

It's recommended to post as early as possible and at minimum one week before the anticipated Baklava testnet governance proposal date.
It's recommended to post as early as possible and at minimum one week before the anticipated Celo Sepolia testnet governance proposal date.

Make sure to keep the post up to date. All updates (excluding fixing typos) should be communicated to the community in the [Discord](http://chat.celo.org/) `#governance` channel.

Expand Down