Governance API

This document describes the API interfaces of the Ontology Governance Contract.

Users can use governance contract to apply to participate in the consensus node election, stake to vote for candidate nodes, exit the consensus node election, and so on. Staked ONT will generate rewards according to certain rules.

API

InitConfig

Function: Initializes the governance contract, only called during the creation of the genesis block (system method).

Method Name: "initConfig"

Parameters: None

Return Value: bool, error

RegisterCandidate

Function: Stakes a certain amount of ONT and consumes some extra ONG to apply to become a candidate node.

Method Name: "registerCandidate"

Parameters:

Index	Type	Description
0	String	Node public key
1	Address	Wallet address
2	Uint32	Amount of staked ONT
3	ByteArray	OntID of the caller
4	Uint64	Public key index of the caller

Return Value: bool, error

RegisterCandidateTransferFrom

Function: Stakes a certain amount of ONT and consumes some extra ONG to apply to become a candidate node, used for contract invocation.

Method Name: "registerCandidateTransferFrom"

Parameters:

Index	Type	Description
0	String	Node public key
1	Address	Wallet address
2	Uint32	Amount of staked ONT
3	ByteArray	OntID of the caller
4	Uint64	Public key index of the caller

Return Value: bool, error

QuitNode

Function: Node application to exit, entering the normal exit process. The wallet address must be the same as the one used for application.

Method Name: "quitNode"

Parameters:

Index	Type	Description
0	String	Node public key
1	Address	Wallet address

Return Value: bool, error

AuthorizeForPeer

Function: Vote for a node by staking ONT.

Method Name: "authorizeForPeer"

Parameters:

Index	Type	Description
0	Address	Wallet address
1	Array{String}	List of nodes to vote for
2	Array{Uint32}	Number of votes for each node

Return Value: bool, error

AuthorizeForPeerTransferFrom

Function: Vote for a node by staking ONT, used for contract invocation.

Method Name: "authorizeForPeerTransferFrom"

Parameters:

Index	Type	Description
0	Address	Wallet address
1	Array{String}	List of nodes to vote for
2	Array{Uint32}	Number of votes for each node

Return Value: bool, error

UnAuthorizeForPeer

Function: Revoke the vote by redeeming the staked ONT.

Method Name: "unAuthorizeForPeer"

Parameters:

Index	Type	Description
0	Address	Wallet address
1	Array{String}	List of nodes to revoke votes from
2	Array{Uint32}	Number of votes to revoke

Return Value: bool, error

Withdraw

Function: Withdraw staked ONT that is in an unfrozen state.

Method Name: "withdraw"

Parameters:

Index	Type	Description
0	Address	Wallet address
1	Array{String}	List of nodes to withdraw from
2	Uint32	Amount to withdraw

Return Value: bool, error

WithdrawOng

Function: Withdraw unbound ONG.

Method Name: "withdrawOng"

Parameters:

Index	Type	Description
0	Address	Wallet address

Return Value: bool, error

WithdrawFee

Function: Withdraw fee dividends.

Method Name: "withdrawFee"

Parameters:

Index	Type	Description
0	Address	Wallet address

Return Value: bool, error

CommitDpos

Function: Consensus switch based on the current voting results, system method.

Method Name: "commitDpos"

Parameters: None

Return Value: bool, error

ChangeMaxAuthorization

Function: Node modifies the maximum amount of ONT it can accept for authorization.

Method Name: "changeMaxAuthorization"

Parameters:

Index	Type	Description
0	String	Node public key
1	Address	Wallet address
2	Uint32	Maximum amount authorized

Return Value: bool, error

SetFeePercentage

Function: Allows a node to set its exclusive incentive percentage.

Method Name: "setFeePercentage"

Parameters:

Index	Type	Description
0	String	Node public key
1	Address	Wallet address
2	Uint32	Exclusive incentive percentage for node
3	Uint32	Exclusive incentive percentage for user

Returns: bool, error

AddInitPos

Function: Increases the initial position (initPos) of the node, can only be called by the node owner.

Method Name: "addInitPos"

Parameters:

Index	Type	Description
0	String	Node public key
1	Address	Wallet address
2	Uint32	Amount to increase in initPos

Returns: bool, error

ReduceInitPos

Function: Decreases the initial position (initPos) of the node. Can only be called by the node owner. The initPos cannot be lower than the committed value and must be at least one-tenth of the authorized amount.

Method Name: "reduceInitPos"

Parameters:

Index	Type	Description
0	String	Node public key
1	Address	Wallet address
2	Uint32	Amount to decrease in initPos

Returns: bool, error

GetPeerPool

Function: Retrieves detailed information about consensus nodes and candidate nodes.

Method Name: "getPeerPool"

Parameters: None

Returns: []byte, error

Serialized Return Values:

type PeerPoolListForVm struct {
	PeerPoolList []*PeerPoolItemForVm
}

func (this *PeerPoolListForVm) Serialization(sink *common.ZeroCopySink) {
	sink.WriteUint32(uint32(len(this.PeerPoolList)))
	for _, v := range this.PeerPoolList {
		v.Serialization(sink)
	}
}

type PeerPoolItemForVm struct {
	Index       uint32         // Peer index
	PeerAddress common.Address // Peer address
	Address     common.Address // Peer owner
	Status      Status         // Peer status
	InitPos     uint64         // Initial position of peer
	TotalPos    uint64         // Total authorized position received by this peer
}

func (this *PeerPoolItemForVm) Serialization(sink *common.ZeroCopySink) {
	sink.WriteUint32(this.Index)
	this.PeerAddress.Serialization(sink)
	this.Address.Serialization(sink)
	this.Status.Serialization(sink)
	sink.WriteUint64(this.InitPos)
	sink.WriteUint64(this.TotalPos)
}

GetPeerInfo

Function: Retrieves detailed information about a node based on its address.

Method Name: "getPeerInfo"

Parameters:

Index	Type	Description
0	Address	Node address

Returns: []byte, error

Serialized Return Values:

type PeerPoolItemForVm struct {
	Index       uint32         // Peer index
	PeerAddress common.Address // Peer address
	Address     common.Address // Peer owner
	Status      Status         // Peer status
	InitPos     uint64         // Initial position of peer
	TotalPos    uint64         // Total authorized position received by this peer
}

func (this *PeerPoolItemForVm) Serialization(sink *common.ZeroCopySink) {
	sink.WriteUint32(this.Index)
	this.PeerAddress.Serialization(sink)
	this.Address.Serialization(sink)
	this.Status.Serialization(sink)
	sink.WriteUint64(this.InitPos)
	sink.WriteUint64(this.TotalPos)
}

GetPeerPoolByAddress

Function: Retrieves a list of detailed information about nodes based on the staking address.

Method Name: "getPeerPoolByAddress"

Parameters:

Index	Type	Description
0	Address	Node address

Returns: []byte, error

Serialized Return Values:

type PeerPoolListForVm struct {
	PeerPoolList []*PeerPoolItemForVm
}

func (this *PeerPoolListForVm) Serialization(sink *common.ZeroCopySink) {
	sink.WriteUint32(uint32(len(this.PeerPoolList)))
	for _, v := range this.PeerPoolList {
		v.Serialization(sink)
	}
}

type PeerPoolItemForVm struct {
	Index       uint32         // Peer index
	PeerAddress common.Address // Peer address
	Address     common.Address // Peer owner
	Status      Status         // Peer status
	InitPos     uint64         // Initial position of peer
	TotalPos    uint64         // Total authorized position received by this peer
}

func (this *PeerPoolItemForVm) Serialization(sink *common.ZeroCopySink) {
	sink.WriteUint32(this.Index)
	this.PeerAddress.Serialization(sink)
	this.Address.Serialization(sink)
	this.Status.Serialization(sink)
	sink.WriteUint64(this.InitPos)
	sink.WriteUint64(this.TotalPos)
}

GetAuthorizeInfo

Function: Retrieves authorization information for voting.

Method Name: "getAuthorizeInfo"

Parameters:

Index	Type	Description
0	String	Node public key
1	Address	Voter's address

Returns: []byte, error

Serialized Return Values:

type AuthorizeInfo struct {
	PeerPubkey           string
	Address              common.Address
	ConsensusPos         uint64 // Position deposited in consensus node
	CandidatePos         uint64 // Position deposited in candidate node
	NewPos               uint64 // Newly deposited position in consensus or candidate node, will be calculated in the next epoch, can be withdrawn at any time
	WithdrawConsensusPos uint64 // Unauthorized position from consensus, frozen until next-next epoch
	WithdrawCandidatePos uint64 // Unauthorized position from candidate, frozen until next epoch
	WithdrawUnfreezePos  uint64 // Unfrozen position, can be withdrawn at any time
}

func (this *AuthorizeInfo) Serialization(sink *common.ZeroCopySink) {
	sink.WriteString(this.PeerPubkey)
	this.Address.Serialization(sink)
	sink.WriteUint64(this.ConsensusPos)
	sink.WriteUint64(this.CandidatePos)
	sink.WriteUint64(this.NewPos)
	sink.WriteUint64(this.WithdrawConsensusPos)
	sink.WriteUint64(this.WithdrawCandidatePos)
	sink.WriteUint64(this.WithdrawUnfreezePos)
}

GetAddressFee

Function: Retrieves the reward amount for a user's address.

Method Name: "getAddressFee"

Parameters:

Index	Type	Description
0	Address	User address

Returns: []byte, error

Serialized Return Values:

type SplitFeeAddress struct { // Table records each address's ONG reward
	Address common.Address
	Amount  uint64
}

func (this *SplitFeeAddress) Serialization(sink *common.ZeroCopySink) {
	this.Address.Serialization(sink)
	sink.WriteUint64(this.Amount)
}