EOS.IO Transaction Structure - Developer's Log, Stardate 201707.9

k
EOS.IO Transaction Structure - Developer's Log, Stardate 201707.9
18 hours ago
dan68 in eos

Today I would like to take a moment to explain the current structure of an EOS.IO transaction so that developers can better understand the concurrency model. Below is a JSON representation of a transaction that will transfer currency from sam to alice. In this case, currency, sam, and alice are all account names; however, they are used in different ways.

{
"refBlockNum": "12",
"refBlockPrefix": "2792049106",
"expiration": "2015-05-15T14:29:01",
"scope": [
"alice",
"sam"
],
"messages": [
{
"code": "currency",
"type": "transfer",
"recipients": [
"sam",
"alice"
],
"authorization": [
{
"account": "sam",
"permission": "active"
}
],
"data": "a34a59dcc8000000c9251a0000000000501a00000000000008454f53000000000568656c6c6f"
}
],
"signatures": []
}
When serialized to binary with a single signature, this transaction is about 160 bytes in size which is slightly larger than a Steem transfer which is about 120 bytes or a BitShares transfer which is about 94 bytes. Much of the extra size comes from having to explicitly specify recipients, authorization, and scope which collectively add 51 bytes to the message.

TaPoS - Transactions as Proof of Stake
Those of you familiar with Steem & BitShares will recognize the first 3 fields of the transaction; they remain unchanged. These fields are used by TaPoS (Transactions as Proof of Stake) and ensure that this transaction can only be included after the referenced block and before the expiration.

Scope
The next field, "scope", is new to EOS.IO and specifies the range of data that may be read and/or written to. If a message attempts to read or write data outside of scope then the transaction will fail. Transactions can be processed in parallel so long as there is no overlap in their scope.

A key innovation of the EOS.IO software is that scope and code are two entirely separate concepts. You will notice that the currency contract is not referenced in the scope even though we are executing a transfer using the currency contract's code.

Messages
A transaction can have one or more messages that must be applied in order and atomically (all succeed or all fail). In this case there is exactly one message, so lets look closer at the message:

code:
Every message must specify which code it will be executing, in this case the currency contract's code will be executing resulting in the following method being called:

currency::apply_currency_transfer(data)
type:
The type field defines the type of message (and implicitly the format of data). From an object oriented programming perspective you could view type as a method "name" on the "currency" class. In this example the type is "transfer" and hence explains the naming of the method being called:

${namespace}::apply_${code}_${type}( data )
In case the "namespace" is the currency contract; however, this same method apply_currency_transfer may also be called in other namespaces.

recipients:
In addition to calling currency::apply_currency_transfer(data), the method apply_currency_transfer(data) will also be called for each recipient listed. For example, the following methods would be called sequentially in this order:

currency::apply_currency_transfer(data)
alice::apply_currency_transfer(data)
sam::apply_currency_transfer(data)

The notation account:: specifies the contract which implements the method. alice and sam may choose to not implement this method if they don't have any special logic to perform when currency::apply_currency_transfer is executed. However, if sam was an exchange, then sam would probably want to process deposits and withdraws when ever a currency transfer is made.

The person who generates the transaction can add any number of recipients (provided they all execute quickly enough). In addition some contracts can require that certain parties be notified. In the case of currency both the sender and receiver are required to be notified. You can see how this is specified in the currency contract.

) {
const auto& transfer = currentMe
...
}
authorization:
Each message may require authorization from one or more accounts. In Steem and BitShares the required authorization is implicitly defined based on the message type; however, with EOS.IO the message must explicitly define the authorization that is provided. The EOS.IO system will automatically verify that the transaction has been signed by all of the necessary signatures to grant the specified authorization.

In this case the message is indicating that it must be signed by sam's active permission level. The currency code will verify that sam's authorization was provided. You can view this check in the example currency contract.

void apply_curren() {
const auto& transfer = currentMessage<![DQmZWjRzX696igR6tq7QEgGfQeMdHVfJTgfWrqzzD8R9mVt_1680x8400.png](https://steemitimages.com/DQmZt2atGmNJJYTZadbqdj9CayEKB7aZok5BFuH3xqojdg9/DQmZWjRzX696igR6tq7QEgGfQeMdHVfJTgfWrq
r;
...
}
data:
Every contract can define it's own data format. Without the ABI the data can only be interpreted as a hexadecimal data; however, the currency contract defines the format of data to be a Transfer struct:

struct Transfer {
AccountName from;
AccountName to;
uint64_t amount = 0;
};
With this defini

{ "from" : "sam", "to": "alice", "amount": 100 }