upgrade the code of system contract XDCValidator #422

gzliudan · 2024-02-06T06:29:56Z

gzliudan
Feb 6, 2024
Collaborator

Upgrade contract XDCValidator in place

This document explains how to upgrade the contract's code in place while keeping the contract's data untouched. We take the system contract XDCValidator as an example.

1. download the solidity compiler

The code of contract XDCValidator uses solidity ^0.4.21, but the below explorer pages show us that the contract XDCValidator is using solidity v0.4.24.

So I choose solidity v0.4.26 for the new contract. This is the latest version in branch v0.4.x. It can be downloaded from https://github.com/ethereum/solidity/releases/.

cd ${HOME}/XDPoSChain/contracts/validator/contract
wget https://github.com/ethereum/solidity/releases/download/v0.4.26/solc-static-linux
chmod +x solc-static-linux
./solc-static-linux --version

2. prepare the new contract

Make a new file contracts/validator/contract/XDCValidatorV2.sol based on the existing contract XDCValidator, such as:

pragma solidity =0.4.26;

import "./libs/SafeMath.sol";

contract XDCValidator {
    using SafeMath for uint256;
    // ...

    // I added the below code just for demo
    uint256 internal age;

    function getAge() external view returns(uint256) {
        return age;
    }

    function setAge(uint256 age_) external {
        age = age_;
    }
}

Notice: the contract name in the file is still XDCValidator, not XDCValidatorV2

3. update bindings

Use abigen and solc-static-linux to update the bindings.

# generate abigen
cd ${HOME}/XDPoSChain/
make all

# update validator.go
cd ${HOME}/XDPoSChain/contracts/validator/contract
${HOME}/XDPoSChain/build/bin/abigen -solc ./solc-static-linux -sol XDCValidatorV2.sol -pkg=contract -out=validator.go

4. get the code of new contract

The variable XDCValidatorBin in the file validator.go is the bytecode to deploy contract. It is not the runtime bytecode of the contract. And it can not be used to upgrade the contract's code. There are many ways to get the real bytecode. Here we get it by genesis.

# compile the new validator.go
cd ${HOME}/XDPoSChain/
make all

# create a new genesis and save it to a json file
cd build/bin/
./puppeth

The puppeth will extract the runtime bytecode of XDCValidatorV2 and save to the genesis. We can get it by the key alloc.0000000000000000000000000000000000000088.code in the genesis file, then paste it into the file common/constants.go:

const XDCValidatorV2Code = "0x6080..."

5. modify golang code

Modify the file consensus/XDPoS/XDPoS.go:

func UpgradeXDCValidtor1(statedb *state.StateDB) {
 log.Info("poc", "MasternodeVotingSMC", common.MasternodeVotingSMC, "step", 1)
 addr := common.HexToAddress(common.MasternodeVotingSMC)
 // upgrade code
 statedb.SetCode(addr, common.FromHex(common.XDCValidatorV2Code))
 log.Info("poc", "MasternodeVotingSMC", common.MasternodeVotingSMC, "step", 2)
}

func UpgradeXDCValidtor2(statedb *state.StateDB) {
 log.Info("poc", "MasternodeVotingSMC", common.MasternodeVotingSMC, "step", 3)
 addr := common.HexToAddress(common.MasternodeVotingSMC)
 // set age to 2
 key := common.HexToHash("0x0000000000000000000000000000000000000000000000000000000000000010")
 value := common.HexToHash("0x0000000000000000000000000000000000000000000000000000000000000002")
 statedb.SetState(addr, key, value)
 log.Info("poc", "MasternodeVotingSMC", common.MasternodeVotingSMC, "step", 4)
}

func (x *XDPoS) Finalize(chain consensus.ChainReader, header *types.Header, state *state.StateDB, parentState *state.StateDB, txs []*types.Transaction, uncles []*types.Header, receipts []*types.Receipt) (*types.Block, error) {
 number := header.Number.Uint64()
 log.Info("poc", "fun", "Finalize", "number", number)
 if number == 30 {
  UpgradeXDCValidtor1(state)
 }
 if number == 60 {
  UpgradeXDCValidtor2(state)
 }
 switch x.config.BlockConsensusVersion(header.Number, header.Extra, ExtraFieldCheck) {
 case params.ConsensusEngineVersion2:
  return x.EngineV2.Finalize(chain, header, state, parentState, txs, uncles, receipts)
 default: // Default "v1"
  return x.EngineV1.Finalize(chain, header, state, parentState, txs, uncles, receipts)
 }
}

Notice: the above code works fine in my private network, but it is not good for production system.

6. upgrade nodes

Recompile the code

# generate abigen
cd ${HOME}/XDPoSChain/
make all

Restart all nodes with new binary XDC.

7. test the code

7.1 test function getAge

I use curl and eth_call to do tests.

RPC="http://localhost:8545/"

curl -s -X POST -H "Content-Type: application/json" ${RPC} -d '{
  "jsonrpc": "2.0",
  "id": 8001,
  "method": "eth_call",
  "params": [
    {
      "to": "0x0000000000000000000000000000000000000088",
      "data": "0x967e6e65"
    },
    "latest"
  ]
}' | jq

"0x967e6e65" is the selector of function getAge(). According to my test code, the above command:

7.1.1 before block number 30

returns "execution reverted" because the old code has no function getAge.

7.1.2 between block number 30 and 60

returns "0x0000000000000000000000000000000000000000000000000000000000000000" because the new code has function getAge() and the value in slot 16(age) is 0.

7.1.3 after block number 60

returns "0x0000000000000000000000000000000000000000000000000000000000000002" because the new code has function getAge() and the value in slot 16(age) was set to 2.

7.2 test function setAge

Use Remix and MetaMask to call the function setAge. Then use remix to call the function getAge and verify the value of age.

GalaxySciTech · 2024-03-04T12:21:32Z

GalaxySciTech
Mar 4, 2024
Maintainer

How to upgrade the system smart contract

Authors: Galaxy(XDC Protocol Team), Dan Liu

1. Context

In some cases, we need to upgrade the contract, such as fix bug or add feature. The system smart contract is deployed at a specific address and performs special functions. It is impossible to upgrade the system smart contract through conventional methods. But how can we achieve it when needed? This article introduces how to upgrade a system contracts using XDCValiator as an example.

2. Methodology

After research, we find the function SetCode in StateDB can upgrade the contract's code. If there is no slot conflict between the new and old contracts, the seamless upgrade will be achieved by SetCode. Let's make a simple comparison:

advantages:

the contract's address is unchanged
the data of contract is keeped in place
all versions of code are saved in blockchain
third party does not need to change anything

shortcoming:

the upgrade is not a transaction, so it is not showed in any block

3. Detailed Operations

The current version of XDCValiator is v1 and the new version is v2. We propose the upgrade plan with the following steps:

1. identify the targets of v2
1. write codes for v2 in hardhat or other develop framework
1. write and pass all testcases in develop enviroment
1. write a script which backup all the data in XDCValiator
1. implement the upgrade code in XDPoSChain
1. write guide on how to test all functions in v2 on each network
1. test upgrade in private network
- 7.2 modify the variable ValidatorV2Block in the file common/constants.go
- 7.3 compile and restart XDC binary program
- 7.4 backup all data in XDCValiator to a file before upgrade by script
- 7.5 wait the blockchain to upgrade XDCValiator at time of ValidatorV2Block automatically
- 7.6 verify the code of XDCValiator is v2 after upgrade
- 7.7 backup all data in XDCValiator to a file after upgrade by script
- 7.8 compare and verify the data files
- 7.9 test all functions in v2 according to the docuement
1. upgrade XDCValiator to v2 in devnet
- 8.1 modify the variable ValidatorV2Block in the file common/constants/constants.go.devnet
- 8.2 compile and restart XDC binary program
- 8.3 backup all data in XDCValiator to a file before upgrade by script
- 8.4 wait the blockchain to upgrade XDCValiator at time of ValidatorV2Block automatically
- 8.5 verify the code of XDCValiator is v2 after upgrade
- 8.6 backup all data in XDCValiator to a file after upgrade by script
- 8.7 compare and verify the data files
- 8.8 test all functions in v2 according to the docuement
1. write and publish documents about XDCValiator v2 to all testnet users
1. upgrade XDCValiator to v2 in testnet
- 10.1 modify the variable ValidatorV2Block in the file common/constants/constants.go.testnet
- 10.2 ask all masternodes rebuild XDC from new the source code or docker image
- 10.3 backup all data in XDCValiator to a file before upgrade by script
- 10.4 wait the blockchain to upgrade XDCValiator at time of ValidatorV2Block automatically
- 10.5 verify the code of XDCValiator is v2 after upgrade
- 10.6 backup all data in XDCValiator to a file after upgrade by script
- 10.7 compare and verify the data files
- 10.8 test all functions in v2 according to the docuement
1. write and publish documents about XDCValiator v2 to all mainnet users
1. upgrade XDCValiator to v2 in mainnet
- 12.1 modify the variable ValidatorV2Block in the file common/constants.go
- 12.2 ask all masternodes rebuild XDC from new the source code or docker image
- 12.3 backup all data in XDCValiator to a file before upgrade by script
- 12.4 wait the blockchain to upgrade XDCValiator at time of ValidatorV2Block automatically
- 12.5 verify the code of XDCValiator is v2 after upgrade
- 12.6 backup all data in XDCValiator to a file after upgrade by script
- 12.7 compare and verify the data files
- 12.8 test all functions in v2 according to the docuement

4. Work schedule

We will work from the latest commit of dev-upgrade branch. Each PR will also be merged into the dev-upgrade branch.

In terms of role, Dan Liu and Gerui Wang and Liam will develop the code. Galaxy will provide test smart contracts. The protocol team will also provide infra support.

id	task	time	owner
3.1	identify targets	4 week	Galaxy
3.2	develop smart contract	1 week	Galaxy
3.3	develop testcases	1 week	Galaxy
3.4	write backup script	1 week	Galaxy
3.5	develop XDPoSChain	2-3 weeks	Dan Liu
3.6	write test guide	1 week	Galaxy
3.7	test in private network	1 week	Galaxy
3.8	upgrade devnet	1-2 weeks	Liam Lai
3.9	publish document for testnet
3.10	upgrade testnet
3.11	publish document for mainnet
3.12	upgrade mainnet

The expected total development time will be 8-11 weeks.

5. Test Strategy

test in develop environment
test in private network
test in devnet
test in testnet
test in mainnet

6. Future Work

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

upgrade the code of system contract XDCValidator #422

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 1 comment

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Select a reply

upgrade the code of system contract XDCValidator #422

gzliudan Feb 6, 2024 Collaborator

Upgrade contract XDCValidator in place

1. download the solidity compiler

2. prepare the new contract

3. update bindings

4. get the code of new contract

5. modify golang code

6. upgrade nodes

7. test the code

7.1 test function getAge

7.1.1 before block number 30

7.1.2 between block number 30 and 60

7.1.3 after block number 60

7.2 test function setAge

Replies: 1 comment

GalaxySciTech Mar 4, 2024 Maintainer

How to upgrade the system smart contract

1. Context

2. Methodology

3. Detailed Operations

4. Work schedule

5. Test Strategy

6. Future Work

gzliudan
Feb 6, 2024
Collaborator

GalaxySciTech
Mar 4, 2024
Maintainer