ACS4 - Consensus Standard

ACS4 is used to customize consensus mechanisms.

Interface

If you want to customize the consensus mechanism, you need to implement the following five interfaces:

Methods

Method Name	Request Type	Response Type	Description
GetConsensusCommand	google.protobuf.BytesValue	acs4.ConsensusCommand	Generate a consensus command based on the consensus contract state and the input public key.
GetConsensusExtraData	google.protobuf.BytesValue	google.protobuf.BytesValue	Generate consensus extra data when a block is generated.
GenerateConsensusTransactions	google.protobuf.BytesValue	acs4.TransactionList	Generate consensus system transactions when a block is generated. Each block will contain only one consensus transaction, which is used to write the latest consensus information to the State database.
ValidateConsensusBeforeExecution	google.protobuf.BytesValue	acs4.ValidationResult	Before executing the block, verify that the consensus information in the block header is correct.
ValidateConsensusAfterExecution	google.protobuf.BytesValue	acs4.ValidationResult	After executing the block, verify that the state information written to the consensus is correct.

Types

acs4.ConsensusCommand

Field	Type	Description	Label
limit_milliseconds_of_mining_block	int32	Time limit of mining next block.
hint	bytes	Context of Hint is diverse according to the consensus protocol we choose, so we use bytes.
arranged_mining_time	google.protobuf.Timestamp	The time of arrange mining.
mining_due_time	google.protobuf.Timestamp	The expiration time of mining.

acs4.TransactionList

Field	Type	Description	Label
transactions	aelf.Transaction	Consensus system transactions.	repeated

acs4.ValidationResult

Field	Type	Description	Label
success	bool	Is successful.
message	string	The error message.
is_re_trigger	bool	Whether to trigger mining again.

aelf.Address

Field	Type	Description	Label
value	bytes

aelf.BinaryMerkleTree

Field	Type	Description	Label
nodes	Hash	The leaf nodes.	repeated
root	Hash	The root node hash.
leaf_count	int32	The count of leaf node.

aelf.Hash

Field	Type	Description	Label
value	bytes

aelf.LogEvent

Field	Type	Description	Label
address	Address	The contract address.
name	string	The name of the log event.
indexed	bytes	The indexed data, used to calculate bloom.	repeated
non_indexed	bytes	The non indexed data.

aelf.MerklePath

Field	Type	Description	Label
merkle_path_nodes	MerklePathNode	The merkle path nodes.	repeated

aelf.MerklePathNode

Field	Type	Description	Label
hash	Hash	The node hash.
is_left_child_node	bool	Whether it is a left child node.

aelf.SInt32Value

Field	Type	Description	Label
value	sint32

aelf.SInt64Value

Field	Type	Description	Label
value	sint64

aelf.ScopedStatePath

Field	Type	Description	Label
address	Address	The scope address, which will be the contract address.
path	StatePath	The path of contract state.

aelf.SmartContractRegistration

Field	Type	Description	Label
category	sint32	The category of contract code(0: C#).
code	bytes	The byte array of the contract code.
code_hash	Hash	The hash of the contract code.
is_system_contract	bool	Whether it is a system contract.
version	int32	The version of the current contract.

aelf.StatePath

Field	Type	Description	Label
parts	string	The partial path of the state path.	repeated

aelf.Transaction

Field	Type	Description	Label
from	Address	The address of the sender of the transaction.
to	Address	The address of the contract when calling a contract.
ref_block_number	int64	The height of the referenced block hash.
ref_block_prefix	bytes	The first four bytes of the referenced block hash.
method_name	string	The name of a method in the smart contract at the To address.
params	bytes	The parameters to pass to the smart contract method.
signature	bytes	When signing a transaction it’s actually a subset of the fields: from/to and the target method as well as the parameter that were given. It also contains the reference block number and prefix.

aelf.TransactionExecutingStateSet

Field	Type	Description	Label
writes	TransactionExecutingStateSet.WritesEntry	The changed states.	repeated
reads	TransactionExecutingStateSet.ReadsEntry	The read states.	repeated
deletes	TransactionExecutingStateSet.DeletesEntry	The deleted states.	repeated

aelf.TransactionExecutingStateSet.DeletesEntry

Field	Type	Description	Label
key	string
value	bool

aelf.TransactionExecutingStateSet.ReadsEntry

Field	Type	Description	Label
key	string
value	bool

aelf.TransactionExecutingStateSet.WritesEntry

Field	Type	Description	Label
key	string
value	bytes

aelf.TransactionResult

Field	Type	Description	Label
transaction_id	Hash	The transaction id.
status	TransactionResultStatus	The transaction result status.
logs	LogEvent	The log events.	repeated
bloom	bytes	Bloom filter for transaction logs. A transaction log event can be defined in the contract and stored in the bloom filter after the transaction is executed. Through this filter, we can quickly search for and determine whether a log exists in the transaction result.
return_value	bytes	The return value of the transaction execution.
block_number	int64	The height of the block hat packages the transaction.
block_hash	Hash	The hash of the block hat packages the transaction.
error	string	Failed execution error message.

aelf.TransactionResultStatus

Name	Number	Description
NOT_EXISTED	0	The execution result of the transaction does not exist.
PENDING	1	The transaction is in the transaction pool waiting to be packaged.
FAILED	2	Transaction execution failed.
MINED	3	The transaction was successfully executed and successfully packaged into a block.
CONFLICT	4	When executed in parallel, there are conflicts with other transactions.
PENDING_VALIDATION	5	The transaction is waiting for validation.
NODE_VALIDATION_FAILED	6	Transaction validation failed.

Usage

The five interfaces defined in ACS4 basically correspond to the five methods of the IConsensusService interface in the AElf.Kernel.Consensus project:

ACS4	IConsensusService	Methodology	The Timing To Call
GetConsensusCommand	Task TriggerConsensusAsync (ChainContext chainContext);	When TriggerConsensusAsync is called, it will use the account configured by the node to call the GetConsensusCommand method of the consensus contract to obtain block information ConsensusCommand), and use it to (see IConsensusScheduler implementation) .	When the node is started; When the BestChainFound- EventData event is thrown; When the validation of consensus data fails and the consensus needs to be triggered again (The IsReTrigger field of the ValidationResult type is true);
GetConsensus- ExtraData	Task<byte[]> GetConsensus ExtraDataAsync(ChainContext chainContext);	When a node produces a block, it will generate block header information for the new block by IBlockExtraDataService. This service is implemented to traverse all IBlockExtraDataProvider implementations, and they generate binary array information into the ExtraData field of BlockHeader. The consensus block header information is provided by ConsensusExtraDataProvider, in which the GetConsensusExtraDataAsync of the IConsensusService in the consensus contract is called, and the GetConsensusExtraDataAsync method is implemented by calling the GetConsensusExtraData in the consensus contract.	At the time that the node produces a new block.
GenerateConsensus- Transactions	Task<List<Transaction>> GenerateConsensus- TransactionsAsync( ChainContext chainContext);	In the process of generating new blocks, a consensus transaction needs to be generated as one of the system transactions. The basic principle is the same as GetConsensusExtraData.	At the time that the node produces a new block.
ValidateConsensus- BeforeExecution	Task<bool> ValidateConsensus BeforeExecutionAsync( chainContext, byte[] consensusExtraData);	As long as the IBlockValidationProvider interface is implemented, a new block validator can be added. The consensus validator is ConsensusValidationProvider , where ValidateBlockBeforeExecuteAsync is implemented by calling the ValidateConsensusBeforeExecution method of the consensus contract.	At the time that the node produces a new block.
ValidateConsensus- AfterExecution	Task<bool> ValidateConsensus AfterExecutionAsync ( ChainContext chainContext, byte[] consensusExtraData);	The implementation of ValidateBlockAfterExecuteAsync in ConsensusValidationProvider is to call the ValidateConsensusAfterExecution in the consensus contract.	At the time that the node produces a new block.

Example

You can refer to the implementation of the AEDPoS contract.