Neo X System Contracts

Neo X system contracts are a set of build-in Solidity contracts with predefined addresses. They represent the governance and economic model of Neo X, which is fully decentralized and transparent.

These contracts are not deployed by transactions but allocated in the genesis file. The address setting of existing pre-compiled contracts is listed as below.

AddressContract

0x1212000000000000000000000000000000000000

GovProxyAdmin

0x1212000000000000000000000000000000000001

Governance Proxy

0x1212100000000000000000000000000000000001

Governance Implemention

0x1212000000000000000000000000000000000002

Policy Proxy

0x1212100000000000000000000000000000000002

Policy Implemention

0x1212000000000000000000000000000000000003

GovernanceReward Proxy

0x1212100000000000000000000000000000000003

GovernanceReward Implemention

0x1212000000000000000000000000000000000004

Bridge Proxy

0x1212100000000000000000000000000000000004

Bridge Implemention

0x1212000000000000000000000000000000000005

BridgeManagement Proxy

0x1212100000000000000000000000000000000005

BridgeManagement Implemention

GovernanceVote

GovernanceVote is a public "library" that is widely used in the system contract management especially upgrade.

Any contract inheriting GovernanceVote.sol can set up a consensus vote on method execution, by calling internal vote(bytes32 methodKey, bytes32 paramKey), which requires more than half of the current consensus votes for the same method call and the same calling parameters.

  1. More than half - the threshold value is 1/2 instead of 2/3;

  2. Current consensus - if an address is no longer a consensus member, its votes will not be counted;

  3. The same method and parameters - it means the majority votes for the same execution result.

GovProxyAdmin

GovProxyAdmin controls the upgrade of other pre-compiled system contracts, since all of their onlyOwner/onlyAdmin point to 0x1212000000000000000000000000000000000000.

This contract inherits GovernanceVote.sol so that it requires a 50% majority votes among current consensus to execute upgradeAndCall(...), which means more than half of the current consensus votes for the same contract implementation.

All of the upgradable Neo X system contracts use ERC1967Proxy and UUPSUpgradeable.

Governance

Governance is responsible for the election of consensus nodes and related reward distribution.

An election is, GAS holders vote for registered candidates and the Governance contract selects top 7 candidates as consensus nodes for the next epoch*.

*Epoch is a unit of measurement for blocks. Currently, 1 epoch on testnet is the equivalent of 60480 blocks, which is the storage value epochDuration may be retrieved by contract calls.

Candidate

An EOA account is allowed to become a candidate only after successful registration via Governance contract with required registration fee deposit staked. The following requirements should be met for successful registration:

  1. Registrant invokes registerCandidate(uint shareRate) of 0x1212000000000000000000000000000000000001 as message sender;

  2. Registrant is an EOA account and not yet a candidate;

  3. Put at least 1000 GAS deposit value along with the transaction as registration fee;

  4. Provide a shareRate ranges from 0 to 1000 in parameters, which is a distribution ratio in thousandths. It determines how many rewards of the total that voters can share, and can not be changed until the candidate exits;

  5. (optional) Withdraw past deposits if it has registered and exited before.

If all conditions are met, the new candidate will be added to the candidate list. Only registered candidates can receive votes to be elected as a consensus node.

A candidate can exit without any permission, but it requires 2 epochs to pass until the candidate is allowed to withdraw its registeration deposit. During this period, the candidate can't receive any votes or become a consensus node, but voters can revoke their votes and choose other candidates to share rewards.

Election

All GAS holders can vote and benefit from Neo X Governance, including EOA accounts and smart contracts. The following requirements should be met for a successful vote:

  1. Voter invokes vote(address candidateTo) of 0x1212000000000000000000000000000000000001 as message sender;

  2. Put at least 1 GAS vote value along with the transaction;

  3. The provided candidateTo address is listed in the current candidates;

  4. (optional) Revoke votes to other candidates if has voted before.

Neo X Governance doesn't allow voting for multiple candidates and doesn't distribute rewards to new voters until a new epoch begins. So be careful to revoke or change your vote target.

At the end of every election epoch, the 7 candidates with the highest amount of votes will be selected by Governance and become consensus nodes of the next epoch. However, this consensus set recalculation has two prerequisites:

  1. The size of candidate list is larger than 7;

  2. The amount of total valid votes is higher than 3,000,000 GAS.

Otherwise, the consensus nodes of the next epoch will be the following predefined stand-by members.

Testnet Stand-by Address

0xcbbeca26e89011e32ba25610520b20741b809007

0x4ea2a4697d40247c8be1f2b9ffa03a0e92dcbacc

0xd10f47396dc6c76ad53546158751582d3e2683ef

0xa51fe05b0183d01607bf48c1718d1168a1c11171

0x01b517b301bb143476da35bb4a1399500d925514

0x7976ad987d572377d39fb4bab86c80e08b6f8327

0xd711da2d8c71a801fc351163337656f1321343a0

Reward

Neo X Governance reward distribution is real-time. Once a candidate is selected as a consensus node, it automatically starts to receive GAS rewards via participation in the dBFT consensus.

The governance reward in Neo X is always distributed to two parts, the first part is distributed to consensus nodes and the second is distributed to voters according to the shareRate settings.

Consensus Node Distribution

Regardless of consensus leader and received vote amount, all of the transaction priority fees are equally divided among consensus nodes as block rewards. Unlike N3, other registered candidates receive no reward for the whole epoch.

$blockReward=totalNetworkTips/7$

In Neo X dBFT, the block coinbase address is always 0x1212000000000000000000000000000000000003, which means the rewards are first minted to GovReward contract and then transfered to Governance contract during OnPersist() system call execution in the start of every subsequent block.

Voter Distribution

If the shareRate of a consensus node is higher than 0, then blockReward will be split again between the consensus node and its voters.

Voter GAS reward is proportional to different shareRate settings and the voter's weight, i.e. the ratio of voter's votes to the overall number of candidate's votes.

The rewards for consensus nodes will be immediately sent to their addresses, but the reward settlement for voters obeys some other rules:

  1. The rewards after first vote but before the next epoch starts are unclaimable, which means a voter can't benefit without participanting and affecting any election;

  2. A voter has to send a calling (e.g. claimReward()) by itself to 0x1212000000000000000000000000000000000001 to receive claimable rewards;

  3. The rewards are claimed and transfered as well when the vote amount changes via vote(address candidateTo) or revokeVote().

There are several special cases of reward distribution:

  1. When consensus nodes are stand-by validators, they will not share any reward to the network;

  2. Voter rewards will not disappear if the voted candidate exits. However, it is possiable that a candidate exits and returns with a different shareRate after 2 epochs. It will affect your future benefits so voters are recommended to keep an eye on the voted candidate's activities.

Policy

Policy controls the global settings of Neo X protocol, which are forced on every honest node in the network.

The current Neo X Policy maintains following parameters. All these policies are both checked by honest consensus nodes locally and by dBFT globally.

NameParameterUsage

Address Blacklist

isBlackListed

Prevent blacklisted addresses to send transactions in Neo X network

Minimum Transaction Tip Cap

minGasTipCap

Force transaction senders to pay a minimum tip to Neo X Governance

Since all the policy setters adopt the needVote modifier, any policy change requires more than 1/2 of the current Neo X consensus nodes votes to be collected.

Bridge

Refer to the Bridge Contracts repository.

Last updated