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 |
Generate a consensus command based on the consensus contract state and the input public key. |
||
GetConsensusExtraData |
Generate consensus extra data when a block is generated. |
||
GenerateConsensusTransactions |
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 |
Before executing the block, verify that the consensus information in the block header is correct. |
||
ValidateConsensusAfterExecution |
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 |
Time limit of mining next block. |
||
hint |
Context of Hint is diverse according to the consensus protocol we choose, so we use bytes. |
||
arranged_mining_time |
The time of arrange mining. |
||
mining_due_time |
The expiration time of mining. |
acs4.TransactionList
Field |
Type |
Description |
Label |
---|---|---|---|
transactions |
Consensus system transactions. |
repeated |
acs4.ValidationResult
Field |
Type |
Description |
Label |
---|---|---|---|
success |
Is successful. |
||
message |
The error message. |
||
is_re_trigger |
Whether to trigger mining again. |
aelf.Address
Field |
Type |
Description |
Label |
---|---|---|---|
value |
aelf.BinaryMerkleTree
Field |
Type |
Description |
Label |
---|---|---|---|
nodes |
The leaf nodes. |
repeated |
|
root |
The root node hash. |
||
leaf_count |
The count of leaf node. |
aelf.Hash
Field |
Type |
Description |
Label |
---|---|---|---|
value |
aelf.LogEvent
Field |
Type |
Description |
Label |
---|---|---|---|
address |
The contract address. |
||
name |
The name of the log event. |
||
indexed |
The indexed data, used to calculate bloom. |
repeated |
|
non_indexed |
The non indexed data. |
aelf.MerklePath
Field |
Type |
Description |
Label |
---|---|---|---|
merkle_path_nodes |
The merkle path nodes. |
repeated |
aelf.MerklePathNode
Field |
Type |
Description |
Label |
---|---|---|---|
hash |
The node hash. |
||
is_left_child_node |
Whether it is a left child node. |
aelf.SInt32Value
Field |
Type |
Description |
Label |
---|---|---|---|
value |
aelf.SInt64Value
Field |
Type |
Description |
Label |
---|---|---|---|
value |
aelf.ScopedStatePath
Field |
Type |
Description |
Label |
---|---|---|---|
address |
The scope address, which will be the contract address. |
||
path |
The path of contract state. |
aelf.SmartContractRegistration
Field |
Type |
Description |
Label |
---|---|---|---|
category |
The category of contract code(0: C#). |
||
code |
The byte array of the contract code. |
||
code_hash |
The hash of the contract code. |
||
is_system_contract |
Whether it is a system contract. |
||
version |
The version of the current contract. |
aelf.StatePath
Field |
Type |
Description |
Label |
---|---|---|---|
parts |
The partial path of the state path. |
repeated |
aelf.Transaction
Field |
Type |
Description |
Label |
---|---|---|---|
from |
The address of the sender of the transaction. |
||
to |
The address of the contract when calling a contract. |
||
ref_block_number |
The height of the referenced block hash. |
||
ref_block_prefix |
The first four bytes of the referenced block hash. |
||
method_name |
The name of a method in the smart contract at the To address. |
||
params |
The parameters to pass to the smart contract method. |
||
signature |
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 |
The changed states. |
repeated |
|
reads |
The read states. |
repeated |
|
deletes |
The deleted states. |
repeated |
aelf.TransactionExecutingStateSet.DeletesEntry
Field |
Type |
Description |
Label |
---|---|---|---|
key |
|||
value |
aelf.TransactionExecutingStateSet.ReadsEntry
Field |
Type |
Description |
Label |
---|---|---|---|
key |
|||
value |
aelf.TransactionExecutingStateSet.WritesEntry
Field |
Type |
Description |
Label |
---|---|---|---|
key |
|||
value |
aelf.TransactionResult
Field |
Type |
Description |
Label |
---|---|---|---|
transaction_id |
The transaction id. |
||
status |
The transaction result status. |
||
logs |
The log events. |
repeated |
|
bloom |
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 |
The return value of the transaction execution. |
||
block_number |
The height of the block hat packages the transaction. |
||
block_hash |
The hash of the block hat packages the transaction. |
||
error |
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 |
---|---|---|---|
|
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) . |
EventData event is thrown;
data fails and the consensus needs to be triggered again (The IsReTrigger field of the ValidationResult type is true); |
|
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. |
|
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. |
|
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. |
|
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.