ACS2 - Parallel Execution Standard
ACS2 is used to provide information for parallel execution of transactions.
Interface
A contract that inherits ACS2 only needs to implement one method:
Methods
Method Name |
Request Type |
Response Type |
Description |
---|---|---|---|
GetResourceInfo |
Gets the resource information that the transaction execution depends on. |
Types
acs2.ResourceInfo
Field |
Type |
Description |
Label |
---|---|---|---|
write_paths |
The state path that depends on when writing. |
repeated |
|
read_paths |
The state path that depends on when reading. |
repeated |
|
non_parallelizable |
Whether the transaction is not executed in parallel. |
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
AElf uses the key-value database to store data. For the data generated during the contract execution, a mechanism called State Path is used to determine the key of the data.
For example Token contract
defines a property,
public MappedState<Address, string, long> Balances { get; set; }
it can be used to access, modify balance.
Assuming that the address of the Token contract
is
Nmjj7noTpMqZ522j76SDsFLhiKkThv1u3d4TxqJMD8v89tWmE. If you want to
know the balance of the address
2EM5uV6bSJh6xJfZTUa1pZpYsYcCUAdPvZvFUJzMDJEx3rbioz, you can directly
use this key to access redis / ssdb to get its value.
Nmjj7noTpMqZ522j76SDsFLhiKkThv1u3d4TxqJMD8v89tWmE/Balances/2EM5uV6bSJh6xJfZTUa1pZpYsYcCUAdPvZvFUJzMDJEx3rbioz/ELF
On AElf, the implementation of parallel transaction execution is also
based on the key , developers need to provide a method may access to the
StatePath
, then the corresponding transactions will be properly
grouped before executing: if the two methods do not access the same
StatePath, then you can safely place them in different groups.
Attention: The transaction will be canceled and labeled to “can not be groupped” when the StatePath mismatchs the method.
If you are interested in the logic, you can view the code ITransactionGrouper, as well as IParallelTransactionExecutingService .
Implementation
Token contract, as an example, the core logic of method Transfer
is
to modify the balance of address. It accesses the balances property
mentioned above twice.
At this point, we need to notify ITransactionGrouper
via the
GetResourceInfo
method of the key of the ELF balance of address A
and address B:
var args = TransferInput.Parser.ParseFrom(txn.Params);
var resourceInfo = new ResourceInfo
{
Paths =
{
GetPath(nameof(TokenContractState.Balances), txn.From.ToString(), args.Symbol),
GetPath(nameof(TokenContractState.Balances), args.To.ToString(), args.Symbol),
}
};
return resourceInfo;
The GetPath
forms a ScopedStatePath
from several pieces of data
that make up the key:
private ScopedStatePath GetPath(params string[] parts)
{
return new ScopedStatePath
{
Address = Context.Self,
Path = new StatePath
{
Parts =
{
parts
}
}
}
}
Test
You can construct two transactions, and the transactions are passed
directly to an implementation instance of ITransactionGrouper
, and
the GroupAsync
method is used to see whether the two transactions
are parallel.
We prepare two stubs that implement the ACS2 contract with different addresses to simulate the Transfer:
var keyPair1 = SampleECKeyPairs.KeyPairs[0];
var acs2DemoContractStub1 = GetACS2DemoContractStub(keyPair1);
var keyPair2 = SampleECKeyPairs.KeyPairs[1];
var acs2DemoContractStub2 = GetACS2DemoContractStub(keyPair2);
Then take out some services and data needed for testing from Application:
var transactionGrouper = Application.ServiceProvider.GetRequiredService<ITransactionGrouper>();
var blockchainService = Application.ServiceProvider.GetRequiredService<IBlockchainService>();
var chain = await blockchainService.GetChainAsync();
Finally, check it via transactionGrouper:
// Situation can be parallel executed.
{
var groupedTransactions = await transactionGrouper.GroupAsync(new ChainContext
{
BlockHash = chain.BestChainHash,
BlockHeight = chain.BestChainHeight
}, new List<Transaction>
{
acs2DemoContractStub1.TransferCredits.GetTransaction(new TransferCreditsInput
{
To = Address.FromPublicKey(SampleECKeyPairs.KeyPairs[2].PublicKey),
Symbol = "ELF",
Amount = 1
}),
acs2DemoContractStub2.TransferCredits.GetTransaction(new TransferCreditsInput
{
To = Address.FromPublicKey(SampleECKeyPairs.KeyPairs[3].PublicKey),
Symbol = "ELF",
Amount = 1
}),
});
groupedTransactions.Parallelizables.Count.ShouldBe(2);
}
// Situation cannot.
{
var groupedTransactions = await transactionGrouper.GroupAsync(new ChainContext
{
BlockHash = chain.BestChainHash,
BlockHeight = chain.BestChainHeight
}, new List<Transaction>
{
acs2DemoContractStub1.TransferCredits.GetTransaction(new TransferCreditsInput
{
To = Address.FromPublicKey(SampleECKeyPairs.KeyPairs[2].PublicKey),
Symbol = "ELF",
Amount = 1
}),
acs2DemoContractStub2.TransferCredits.GetTransaction(new TransferCreditsInput
{
To = Address.FromPublicKey(SampleECKeyPairs.KeyPairs[2].PublicKey),
Symbol = "ELF",
Amount = 1
}),
});
groupedTransactions.Parallelizables.Count.ShouldBe(1);
}
Example
You can refer to the implementation of the MultiToken contract
for
GetResourceInfo
. Noting that for the ResourceInfo
provided by
the method Transfer
, you need to consider charging a transaction fee
in addition to the two keys mentioned in this article.