Commission and Governance
You can change most node parameters using StorageNodeCap, and the storage node automatically updates them based on the values in the node configuration. However, contract upgrades and withdrawing the storage node commission use separate authorization. This ensures that the hot wallet on the storage node does not need authorization for these operations.
You should designate secure wallets for these operations that you do not store on the storage node machines.
You can update the entities authorized for governance (contract upgrade) and commission operations, and then perform these operations.
How to update the commission receiver and governance authorization
You can either designate an arbitrary object for governance and commission operations, or designate an address to be authorized.
After you set the authorization, only the authorized entity can change it again. Only set authorization to addresses or objects that you control. Make sure they remain accessible.
To set the authorization to receive the commission and perform governance operations, you can use the walrus binary in your CLI or the node operations web interface.
Use the CLI
The following assumes that you have the walrus binary correctly set up and are 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 configuration that are not in the standard locations, use the --wallet and --config command line arguments.
The authorized entities for commission and governance are independent, and you do not need to set them 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 app, connect your wallet, and select your node 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.
Verify onchain
You can verify that you set the authorization correctly by looking up your node StakingPool object on Suiscan. The object ID is your node ID. Check the Commission receiver and Governance authorized fields to confirm they match the addresses or objects you configured.
How to collect commission
You can collect your commission using the CLI or the web interface.
Use the CLI
Make sure that you configure walrus 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
Go to the operator panel on the staking app, connect your wallet, and select your node through the drop-down menu or by pasting your node ID. Then select Collect Commission and follow the steps to send the transaction.
How to manage contract upgrades
Walrus manages contract upgrades through a quorum-based voting system. This ensures that upgrades only apply after sufficient consensus among node operators. The process requires computing a digest of the proposed upgrade and voting on it.
When someone proposes a contract upgrade, 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. The branch contains the proposed change in either the testnet-contracts/walrus or the mainnet-contracts/walrus directory, depending on whether the upgrade targets Testnet or Mainnet contracts.
The vote needs to complete within 1 epoch. Otherwise, the committee changes and you need to repeat the vote.
To vote for an upgrade, complete the following steps.
Compute the upgrade digest
You should compute the package digest of the package to upgrade. You must use the same compiler version and specify the correct Sui network. If you use a standard Walrus configuration, walrus selects the Sui network automatically when you specify the Walrus network using the --context flag. 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
Use 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 through the web interface is the easiest method and also allows you to use any wallet your browser supports (for example, hardware wallets).
To vote through the web interface:
-
Go to the operator panel on the staking app.
-
Connect your wallet and select your node.
-
Navigate to the Vote on Upgrade section.
-
Paste the Base64 package digest from the previous step.
-
Follow the prompts to submit your vote.
Vote on upgrades using the CLI
To vote on an upgrade using the CLI, ensure that you configure your walrus binary 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 is ready for finalization. The proposer usually does this using a programmable transaction block (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, a call to the migrate function in the init module of the walrus package migrates the system and staking objects to the new version. You can perform the upgrade and migration using the walrus-deploy binary.
Command syntax for collecting commission
The --node-id flag belongs to the collect-commission subcommand, the same as for the other node-admin subcommands. Place it after the subcommand name:
walrus node-admin collect-commission --node-id $NODE_ID
Quorum threshold for contract upgrades
Votes count by shard weight, not by number of operators. Each node votes with a weight equal to the number of shards it holds in the current committee. A proposal reaches quorum when the nodes that voted for it hold 2f + 1 of the shards, which is more than 2/3 of all shards. Exactly 2/3 is not enough. A quorum guarantees that a majority of honest nodes by weight supports the upgrade and that byzantine nodes alone cannot block it.
Repeat a vote in a new epoch
You do not need a new proposal when a vote does not finish within the epoch. Run the same vote-for-upgrade command again in the new epoch. The first vote for the digest in the new epoch resets the proposal to the current epoch and clears all earlier votes, so every operator must vote again. The upgrade can only be authorized in the same epoch in which the proposal reaches quorum.