Skip to content

Commit

Permalink
fixup! chore: add upgrade guide for v.1.5
Browse files Browse the repository at this point in the history
Co-authored-by: Guilherme Dantas <[email protected]>
  • Loading branch information
marcelstanley and guidanoli authored Jul 7, 2024
1 parent f68869e commit 0f6237c
Showing 1 changed file with 9 additions and 9 deletions.
18 changes: 9 additions & 9 deletions docs/upgrade_to_1_5.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
<!-- markdownlint-disable MD028 -->
# Upgrade guide for Cartesi Rollups Node `v1.5.0`

Release `v1.5.0` brings a change in the way the Cartesi Rollups Node calculate epochs.
They are now calculated based on block numbers intead of timestamps.
Release `v1.5.0` brings a change in the way the Cartesi Rollups Node closes epochs.
They are now closed based on block numbers intead of timestamps.

> [!WARNING]
> This release contains a **BREAKING CHANGE** that fixes issue [#432](https://github.com/cartesi/rollups-node/issues/432), where epochs may be closed wrongly between restarts of the Cartesi Rollups Node, eventually triggering a `ClaimMismatch` error, which causes the Cartesi Rollups Node to abrubtly shut down.
Expand All @@ -12,7 +12,7 @@ They are now calculated based on block numbers intead of timestamps.
## What has changed

The way the Cartesi Rollups Node calculates epochs has changed starting on `v1.5.0`.
The way the Cartesi Rollups Node closes epochs has changed starting on `v1.5.0`.
This procedure is now based on the `CARTESI_EPOCH_LENGTH` environment variable instead of `CARTESI_EPOCH_DURATION`.

The value of `CARTESI_EPOCH_LENGTH` (blocks) may be derived from `CARTESI_EPOCH_DURATION` (seconds) as follows:
Expand All @@ -30,21 +30,21 @@ Check the [`CHANGELOG`](./CHANGELOG.md) and the [configuration](./docs/config.md

## How to upgrade

Application owners may decide to redeploy their applications, upgrading their instances of the Cartesi Rollups Node to release `v1.5.0`.
Application owners may decide to redeploy all necessary contracts and upgrade their instances of the Cartesi Rollups Node to release `v1.5.0`.
This is the simplest way to perform the upgrade.

In order to do so, just update the application configuration considering [what has changed](#what-has-changed) and upgrade the version of the Cartesi Rollups Node as usual.

> [!CAUTION]
> A redeployment will create a new instance of the application from scratch.
> All previous inputs, outputs and claims will remain associated to the previous application address, funds included.
> All previous inputs, outputs and claims will remain associated to the previous application address, including any funds locked in the application contract.
Alternatively, if the application owner wants to keep the application inputs, they may choose to replace the _History_ being used by the application's _Authority_ instead.
Alternatively, the _Authority_ owner may choose to replace the _History_ being used by the application's _Authority_ instead. This path allows inputs, outputs and locked funds to remain unchanged.
This process is a little bit more involved and is described in the next section.

> [!NOTE]
> A new _History_ will contain no claims.
> Once the Rollups Node is restarted with a new _History_, all previous claims will be submitted again, one-by-one, by the configured _Authority_, incurring in extra cost for the application owner.
> Once the Rollups Node is restarted with a new _History_, all previous claims will be submitted again, one-by-one, by the configured _Authority_, incurring in extra cost for the _Authority_ owner.
## Steps to replace an Application's _History_

Expand All @@ -65,9 +65,9 @@ First, the address of the new _History_ instance should be calculated.
> [!IMPORTANT]
> All commands below assume that the following environment variables have been previous defined:
>
> - `SALT`: salt to be used by the deterministic deployment functions
> - `SALT`: a random 32-byte value to be used by the deterministic deployment functions
> - `RPC_URL`: the RPC endpoint to be used
> - `MNEMONIC`: mnemonic phrase for the application owner's wallet (other wallet options may be used)
> - `MNEMONIC`: mnemonic phrase for the _Authority_ owner's wallet (other wallet options may be used)
> - `HISTORY_FACTORY_ADDRESS`: address of a valid _History Factory_ instance
> - `AUTHORITY_ADDRESS`: address of the _Authority_ instance being used by the application
Expand Down

0 comments on commit 0f6237c

Please sign in to comment.