UpdateZeroContract.sol

Overview

UpdateZeroContract.sol defines a smart contract designed to allow for self-upgradeability by updating its own code on the TON blockchain. This contract provides a method to replace its current code with new code, ensuring that the upgrade is authorized via public key verification. The contract also includes a method to retrieve its version information.

Contract: UpdateZeroContract

Purpose

UpdateZeroContract serves as a base contract enabling code upgrades via the updateCode function. It includes a constructor that accepts the incoming message and a version getter for identification purposes.

Constructor

constructor()

• Description: Called once during contract deployment. It calls tvm.accept() to accept the inbound external message and allow the constructor execution.

• Parameters: None

• Return: None

• Usage: Initializes the contract and accepts the deployment message.

Function: updateCode

function updateCode(TvmCell newcode, TvmCell cell) public view

• Description: Enables the contract to update its own code with a new version. This function requires the caller to prove ownership via the public key.

• Parameters:

  • newcode (TvmCell): The new compiled contract code to be deployed.

  • cell (TvmCell): A cell parameter passed to onCodeUpgrade to handle any data migration or initializations during code upgrade.

• Return: None

• Modifiers: public view

• Behavior:

  • Validates that the message sender's public key matches the contract’s public key (tvm.pubkey()). If not, it throws error code 100.

  • Uses tvm.setcode(newcode) to set the new contract code.

  • Calls tvm.setCurrentCode(newcode) to immediately switch the execution environment to the new code.

  • Calls the private method onCodeUpgrade(cell) for any upgrade-specific logic.

• Usage Example:

TvmCell new_code = /* compiled new contract code cell */;
TvmCell upgrade_data = /* optional upgrade data cell */;
updateCode(new_code, upgrade_data);

Function: onCodeUpgrade

function onCodeUpgrade(TvmCell cell) private pure

• Description: A placeholder hook that is called immediately after the contract code is updated. It is intended for any initialization or migration logic after the upgrade.

• Parameters:

  • cell (TvmCell): Data passed from updateCode to be processed during upgrade.

• Return: None

• Modifiers: private pure

• Implementation: Empty in this contract; designed to be overridden or extended in derived contracts.

• Usage: Override this function if additional processing is needed when upgrading.

Function: getVersion

function getVersion() external pure returns(string, string)

• Description: Returns the current version information of the contract.

• Parameters: None

• Return: Tuple of two strings:

  • Version number (e.g., "1.0.0")

  • Contract name (e.g., "UpdateZeroContract")

• Modifiers: external pure

• Usage Example:

(string version, string name) = contract.getVersion();

Implementation Details

• The contract uses the TON Virtual Machine (TVM) specific functions such as tvm.accept(), tvm.setcode(), and tvm.setCurrentCode() which are essential for managing message acceptance and dynamic code replacement.

• The updateCode function ensures security by requiring the message sender's public key to match the contract’s stored public key to prevent unauthorized upgrades.

• The upgrade process is atomic: the code is set, switched, and the upgrade hook is called in one transaction.

• The empty onCodeUpgrade function is designed for extensibility, allowing derived contracts to implement migration logic when the code changes.

Interaction with Other Components

• This contract primarily interacts with the TVM and blockchain runtime environment.

• It may be used as a base contract in a larger system where upgradeable contracts are required.

• updateCode expects properly formatted and compiled TvmCell code, which typically comes from off-chain compilation tools.

• The upgrade mechanism allows seamless integration with deployment pipelines and upgrade scripts managing contract lifecycle.

Visual Diagram of UpdateZeroContract Structure

classDiagram
class UpdateZeroContract {
+constructor()
+updateCode(newcode: TvmCell, cell: TvmCell)
-onCodeUpgrade(cell: TvmCell)
+getVersion() string[2]
}

This diagram illustrates the contract's methods, highlighting the public interface and the private upgrade hook.