From 0f6237ca64c1a40bdc4ec6dd40c562ad988f1fed Mon Sep 17 00:00:00 2001 From: Marcel Moura Date: Sat, 6 Jul 2024 22:00:53 -0300 Subject: [PATCH] fixup! chore: add upgrade guide for v.1.5 Co-authored-by: Guilherme Dantas --- docs/upgrade_to_1_5.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/upgrade_to_1_5.md b/docs/upgrade_to_1_5.md index 93c6cbab3..3d637aa1a 100644 --- a/docs/upgrade_to_1_5.md +++ b/docs/upgrade_to_1_5.md @@ -1,8 +1,8 @@ # 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. @@ -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: @@ -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_ @@ -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