Skip to main content

Commission and Governance

While most node parameters can be changed using StorageNodeCap and are automatically updated based on the values in the node configuration, authorization for contract upgrades and withdrawing the storage node's commission is handled separately to ensure that the hot wallet on the storage node does not need to be authorized for these operations.

All node operators are strongly recommended to designate secure wallets for these operations that are not stored on the storage node machines.

This page explains how to update the entities that are authorized for governance (contract upgrade) and commission operations and how these operations are performed.

Update the commission receiver and entity authorized for governance​

You can either designate an arbitrary object for governance and commission operations or designate an address to be authorized.

warning

After you set the authorization, only the authorized entity can change the authorization again. Only set authorization to addresses or objects that you control and make sure they remain accessible.

To set the authorization to receive the commission and perform governance operations, you can either use the walrus binary in your CLI, or you can use the node operations web interface.

Use the CLI​

The following assumes that you have the walrus binary correctly set up, using the wallet that is currently authorized to perform these operations. If this is the first time updating the authorized entities, this is the wallet that you used to set up the storage node. To specify a wallet and config that are not in the standard locations, you can specify them using the --wallet and --config command line arguments.

The authorized entities for commission and governance are independent and do not need to be set to the same address or object.

$ NODE_ID=            # Set this to your node ID.
$ COMMISSION_AUTHORIZED_ADDRESS= # Set this to a secure wallet address that you control.
$ GOVERNANCE_AUTHORIZED_ADDRESS= # Set this to a secure wallet address that you control.
$ walrus node-admin set-commission-authorized --node-id $NODE_ID --address $COMMISSION_AUTHORIZED_ADDRESS
$ walrus node-admin set-governance-authorized --node-id $NODE_ID --address $GOVERNANCE_AUTHORIZED_ADDRESS

Instead of specifying an authorized address using the --address flag, you can designate an arbitrary object as a capability using the --object flag:

$ NODE_ID=           # Set this to your node ID.
$ COMMISSION_AUTHORIZED_OBJECT= # Set this to the ID of an object that you own in a secure wallet.
$ GOVERNANCE_AUTHORIZED_OBJECT= # Set this to the ID of an object that you own in a secure wallet.
$ walrus node-admin set-commission-authorized --node-id $NODE_ID --object $COMMISSION_AUTHORIZED_OBJECT
$ walrus node-admin set-governance-authorized --node-id $NODE_ID --object $GOVERNANCE_AUTHORIZED_OBJECT

Use the web interface​

Go to the operator panel on the staking dApp, connect your wallet, and select your node either through the drop-down menu or by pasting your node ID. Then select Set Commission Receiver or Set Governance Authorized and follow the steps to send the transaction.

Collect commission​

To collect your commission, you can either use the CLI or the web interface.

Use the CLI​

To use the CLI, make sure that walrus is configured to use the authorized wallet and run the following command:

$ NODE_ID=           # Set this to your node ID.
$ walrus node-admin --node-id $NODE_ID collect-commission

Use the web interface​

To use the web interface, go to the operator panel on the staking dApp, connect your wallet and select your node either through the drop-down menu or by pasting your node ID. Then select Collect Commission and follow the steps to send the transaction.

Manage contract upgrades​

Contract upgrades in Walrus are managed through a quorum-based voting system. This ensures that upgrades are only applied after sufficient consensus among node operators. The process requires computing a digest of the proposed upgrade and voting on it.

When a contract upgrade is proposed, the proposer generally shares the code of the proposed upgrade with other node operators. For example, if the Walrus Foundation proposes an upgrade, it shares a specific commit hash in a branch on the Walrus GitHub Repository that contains the proposed change in either the testnet-contracts/walrus or the mainnet-contracts/walrus directory, depending on whether the Testnet or Mainnet contracts are being upgraded.

The vote needs to complete within 1 epoch, otherwise the committee changes and the vote needs to be repeated. To vote for an upgrade, complete the following steps.

Compute the upgrade digest​

Operators should compute the package digest of the package to upgrade. The same compiler version must be used and the correct Sui network must be specified. If you use a standard Walrus configuration, the Sui network is selected automatically when specifying the Walrus network using the --context flag and using the up-to-date walrus version ensures that the compiler version is consistent across all voters.

To compute the digest of a proposed upgrade, use the walrus node-admin command. Assuming that your current working directory is the root of the Walrus repository and you have checked out the correct commit, use the following command for Testnet upgrades:

$ walrus node-admin package-digest --package-path testnet-contracts/walrus --context testnet

And the following for Mainnet upgrades:

$ walrus node-admin package-digest --package-path mainnet-contracts/walrus --context mainnet

The command outputs a digest as hexadecimal and base64 that you can use to verify the proposal and vote on the upgrade.

Vote on upgrades using the web interface​

Voting on an upgrade using the web interface is the easiest way and also allows you to use any wallet supported by your browser (for example, hardware wallets). To vote through the web interface:

  1. Go to the operator panel on the staking dApp.
  2. Connect your wallet and select your node.
  3. Navigate to the Vote on Upgrade section.
  4. Paste the Base64 package digest from the previous step.
  5. Follow the prompts to submit your vote.

Vote on upgrades using the CLI​

To vote on an upgrade using the CLI, ensure that your walrus binary is configured with the authorized wallet, and that you are on the correct branch in the root directory of the Walrus repository.

Run the following for Testnet:

$ NODE_ID=   # Set this to your node ID.
$ PACKAGE_PATH=testnet-contracts/walrus
$ UPGRADE_MANAGER_OBJECT_ID=0xc768e475fd1527b7739884d7c3a3d1bc09ae422dfdba6b9ae94c1f128297283c
$ walrus node-admin vote-for-upgrade \
    --node-id $NODE_ID \
    --upgrade-manager-object-id $UPGRADE_MANAGER_OBJECT_ID \
    --package-path $PACKAGE_PATH \
    --context testnet

Run the following for Mainnet upgrades:

$ NODE_ID=   # Set this to your node ID.
$ PACKAGE_PATH=mainnet-contracts/walrus
$ UPGRADE_MANAGER_OBJECT_ID=0xc42868ad4861f22bd1bcd886ae1858d5c007458f647a49e502d44da8bbd17b51
$ walrus node-admin vote-for-upgrade \
    --node-id $NODE_ID \
    --upgrade-manager-object-id $UPGRADE_MANAGER_OBJECT_ID \
    --package-path $PACKAGE_PATH \
    --context mainnet

Complete the upgrade​

After a quorum of node operators has voted in favor of a proposal, the contract upgrade can be finalized. This is usually done by the proposer using a PTB that calls the respective functions to authorize, execute, and commit the upgrade. Then, depending on the upgrade, either at the start of the next epoch or immediately, the system and staking objects are migrated to the new version, by calling the migrate function in the init module of the walrus package. The upgrade and migration can both be performed using the walrus-deploy binary.