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

aelf.Transaction

acs2.ResourceInfo

Gets the resource information that the transaction execution depends on.

Types

acs2.ResourceInfo

Field

Type

Description

Label

write_paths

aelf.ScopedStatePath

The state path that depends on when writing.

repeated

read_paths

aelf.ScopedStatePath

The state path that depends on when reading.

repeated

non_parallelizable

bool

Whether the transaction is not executed in parallel.

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

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.