The Transaction type

Table of contents
Deploy
Version1

A transaction is an tagged-union type whose variants represent atomic units of work that can be sent to the node for execution.

Currently it consists of two possible variants:

• Deploy
• Version1

Deploy

The Transaction::Deploy variant is equivalent to the 1.x Deploy.

Serializing a Transaction of variant Deploy:

• The first byte is a 0
• Next bytes are binary representation of a Deploy

Version1

Transaction::Version1 is the new way that work can be proposed to a node. It's nature is more amorphic than Transaction::Deploy. This type of Transaction uses a self-describing binary serialization scheme (comparing to other Binary Serialization Standard types). The self-describing scheme is called Calltable serialization in this document. In general, the layout of this new style of transaction is "tagged-union" oriented. An in-depth description of how this self-describing standard works is in the calltable serialization document. In the scope of this documentation, for abbreviation, we will call these "tagged-unions". Tagged unions are data structures that can define very different internal fields depending on which variant is currently being used. For serialization we denote the variant (effectively - "which variant of the union was created for this instance of the union type") and serialize it alongside the fields. This "variant marking" is stored as a one byte unsigned number and will be referred to in this document as variant discriminator. The terms serialization_index and variant discriminator (which we use in this document) are also explained in the calltable serialization document also.

Serializing a Transaction of variant Version1:

• The first byte is a 1
• Next bytes are binary representation of a TransactionV1

TransactionV1

TransactionV1 (serialized using calltable scheme) consists of:

• hash - hash calculated over binary serialization of payload. It's serialization_index is 0. In the sense of binary serialization it is a Digest
• payload- of type TransactionV1Payload, contains all the actual data that the transaction sends to node. It's serialization_index is 1
• approvals - collection of Approvals being signatures over hash. It's serialization_index is 2

TransactionV1Payload

TransactionV1Payload (serialized using calltable scheme) consists of:

• initiator_addr - of type InitiatorAddr identifies the initiator of this Transaction. It's serialization_index is 0
• timestamp - Timestamp identifying the self-declared time of creation for this transaction. It's serialization_index is 1
• ttl - TimeDiff self-declared period in which the transaction should be included in a block and executed. It's serialization_index is 2
• chain_name - String identifying the network name on which this transaction should be executed. It's serialization_index is 3
• pricing_mode - PricingMode declaration of how the transaction should be payed for. It's serialization_index is 4
• fields - please see v1.payload.fields section. It's serialization_index is 5

InitiatorAddr

InitiatorAddr (serialized using calltable scheme) consists of:

• in variant InitiatorAddr::PublicKey
  • variant discriminator of value 0
  • PublicKey serialized under serialization key 1
• in variant InitiatorAddr::AccountHash
  • variant discriminator of value 1
  • AccountHash serialized under serialization key 1

PricingMode

PricingMode (serialized using calltable scheme) consists of:

• in variant PaymentLimited
  • variant discriminator of value 0
  • field payment_amount of type u64 (8 bytes unsigned number) with serialization index 1
  • field gas_price_tolerance of type u8 (1 bytes unsigned number) with serialization index 2
  • field standard_payment of type bool with serialization index 3
• in variant Fixed
  • variant discriminator of value 1
  • field additional_computation_factor of type u8 (1 bytes unsigned number) with serialization index 1
  • field gas_price_tolerance of type u8 (1 bytes unsigned number) with serialization index 2
• in variant Prepaid
  • variant discriminator of value 2
  • field receipt of type Digest with serialization index 1

Version1.payload.fields

This is an amorphous data holder. It is serialized as a map of key u16 and value Byte. By u16 we understand an unsigned 2 byte number (see numeric). Byte a collection of bytes. The invariants for this field are:

• keys (first tuple entries) are unique
• the collection is ordered ascending by first element of the tuple (u16)

Breaking the above invariants will cause the node to reject the the transaction as malformed.

This field is design in this amorphous way to facilitate the possibility of reshaping (adding, removing) fields in the future while keeping the byte serialization structure compatible. First tuple entries of this collection discern internal fields, second tuple entries are Binary Serialization Standard compliant serializations of data.

Currently the "keys" (first tuple entries) of the fields map are interpreted as:

• payload with key 0: an instance of TransactionArgs
• payload with key 1: an instance of TransactionTarget
• payload with key 2: an instance of TransactionEntryPoint
• payload with key 3: an instance of TransactionScheduling

TransactionTarget

TransactionTarget (serialized using calltable scheme) consists of:

• in variant Native
  • variant discriminator of value 0
• in variant Stored
  • variant discriminator of value 1
  • field id of type TransactionInvocationTarget with serialization index 1
  • field runtime of type TransactionRuntimeParams with serialization index 2
• in variant Session
  • variant discriminator of value 2
  • field is_install_upgrade of type bool with serialization index 1
  • field module_bytes of type Bytes with serialization index 2
  • field runtime of type TransactionRuntimeParams with serialization index 2

TransactionInvocationTarget

TransactionInvocationTarget (serialized using calltable scheme) consists of:

• in variant ByHash
  • variant discriminator of value 0
  • HashAddr with serialization index 1
• in variant ByName
  • variant discriminator of value 1
  • String with serialization index 1
• in variant ByPackageHash
  • variant discriminator of value 2
  • field addr which is a 32 bytes hash digest with serialization index 1
  • field version of type Option<u32> (option of 4 bytes unsigned number) with serialization index 2
  • field protocol_version_major of type u32 (4 bytes unsigned number). It's serialization index is 3. This field is not mandatory - in fact in the reference rust implementation it is defined as Option<u32>. If it is present it should be serialized as u32 under index 3. But if it's not present, there will be no entry for it at all (both in the calltable section of TransactionInvocationTarget or payload)
• in variant ByPackageName
  • variant discriminator of value 3
  • field name of type String with serialization index 1
  • field version of type Option<u32> (option of 4 bytes unsigned number) with serialization index 2
  • field protocol_version_major of type u32 (4 bytes unsigned number). It's serialization index is 3. This field is not mandatory - in fact in the reference rust implementation it is defined as Option<u32>. If it is present it should be serialized as u32 under index 3. But if it's not present, there will be no entry for it at all (both in the calltable section of TransactionInvocationTarget or payload)

TransactionRuntimeParams

TransactionRuntimeParams (serialized using calltable scheme) consists of:

• in variant VmCasperV1:
  • variant discriminator of value 0
• in variant VmCasperV2:
  • variant discriminator of value 1
  • field transferred_value of type u64 (8 bytes unsigned number) with serialization index 1
  • field seed of type Option<[u8; 32]> (option of 32 bytes Byte array) with serialization index 2

TransactionEntryPoint

TransactionEntryPoint (serialized using calltable scheme) consists of:

• in variant Call:
  • variant discriminator of value 0
• in variant Custom:
  • variant discriminator of value 1
  • String with serialization index 1
• in variant Transfer:
  • variant discriminator of value 2
• in variant AddBid:
  • variant discriminator of value 3
• in variant WithdrawBid:
  • variant discriminator of value 4
• in variant Delegate:
  • variant discriminator of value 5
• in variant Undelegate:
  • variant discriminator of value 6
• in variant Redelegate:
  • variant discriminator of value 7
• in variant ActivateBid:
  • variant discriminator of value 8
• in variant ChangeBidPublicKey
  • variant discriminator of value 9
• in variant AddReservations:
  • variant discriminator of value 10
• in variant CancelReservations:
  • variant discriminator of value 11
• in variant Burn:
  • variant discriminator of value 12

TransactionScheduling

TransactionScheduling (serialized using calltable scheme) consists of:

• in variant Standard:
  • variant discriminator of value 0

Serialization example

Please see this document to see an in-depth step-by-step example of deserializing a transaction

Deserialization example

Please see this document to see an in-depth step-by-step example of deserializing a transaction