Skip to main content

2.3 Standard Payloads Layout

2.3.1 Introduction

Payloads may contain arbitrary data up to MAX_PAYLOAD_SIZE, which allows building additional protocols on top of the base protocol in the same way as TCP/IP allows to define additional protocols on top of its generic data segment.

Payloads may recursively contain other payloads, that enables the creation of higher-level protocols based on the same concepts of layers, as in traditional software and network architecture.

Payloads other than transactions are, by definition, always liked with a level of knowledge 3.

The Standard payload Layout specification depends on the following specification:

2.3.2 Payload Definition Guideline

Each payload shall be described by the uint32 payload type field. To separate user-defined payloads from essential core payloads and allow future extension of the protocol, the first four places (types 0-255) are reserved for core payload definitions, and all user-defined payloads that do not restrict this rule shall be discarded.

Additionally, all payloads shall start with the following fields, in the presented order (Table 2.3.1).

NameTypeDescription
Sizeuint32The size of the payload.
Payload Typeuint32The type of the payload.
Versionuint8The version of the payload.

Table 2.3.1: Required fields of a payload.

2.3.3 Parameters

The Table 2.3.2 presents the parameter list that each node must know. | Name | Description | Value | | -----| ------ | ----------- | |MAX_PAYLOAD_SIZE | The maximum allowed payload size in bytes. Determined by the difference between MAX_MESSAGE_SIZE (defined in Section 2.2 - Message Layout) and the total size of the remaining message fields. | 65157 |

Table 2.3.2: Standard Payload Layout parameters.

2.3.4 User-defined Payloads

A node may choose to interpret user-defined payloads by listening to its specific payload type (possibly via third-party code/software). If a node does not know a certain payload type, it simply treats it as arbitrary data.

2.3.5 Core Payloads

The core protocol defines several payloads that every node needs to interpret and process in order to participate in the network. All core payloads, along with their types, are listed in the Table 2.3.3.

Payload NamePayload Type
Pure datavalue 1
Transactionvalue 0
FPC statementvalue 2
dRNG Application Messagevalue 3
dRNG DKGvalue 4
dRNG Beaconvalue 5
dRNG Collective Beaconvalue 6
Salt Declarationvalue 7
Indexationvalue 8

Table 2.3.3: List of all core payloads with its corresponding types.*

2.3.5.1 Pure Data Payload

Pure data payloads allow to send unsigned messages (Table 2.3.4).

NameTypeDescription
Sizeuint32The size of the payload.
Payload Typeuint32Set to value 1 to denote a Data Payload.
Versionuint8The version of the payload.
DataByteArrayThe raw data payload.

Table 2.3.4: Pure data payload.

2.3.5.2 Transaction Payload

The ledger state is changed through transactions payloads or value transfers. More details on transactions could be found in Section 5.1 - UTXO specification. The detailed description of transaction payload's serialized form is presented in Table 2.3.5.

NameTypeDescription
Sizeuint32The size of the payload.
Payload Typeuint32Set to value 0 to denote a Transaction Payload.
Versionuint8The version of the payload.
Essence oneOf
Transaction Essence
Describes the essence data making up a transaction.
NameTypeDescription
Versionuint8The version number of the Transaction Essence.
TimestamptimeThe timestamp of the Transaction creation.
Access Mana Pledge nodeIDByteArray[32]The nodeID to which access mana of the Transaction is pledged.
Consensus Mana Pledge nodeIDByteArray32]The nodeID to which consensus mana of the Transaction is pledged.
Inputs Countuint16The amount of inputs proceeding.
Inputs anyOf
UTXO Input
Describes an input which references an unspent transaction output to consume.
NameTypeDescription
Input Typeuint8Set to value 0 to denote an UTXO Input.
Transaction IDByteArray[32]The BLAKE2b-256 hash of the transaction from which the UTXO comes from.
Transaction Output Indexuint16The index of the output on the referenced transaction to consume.
Outputs Countuint16The amount of outputs proceeding.
Outputs anyOf
SigLockedSingleOutput
Describes a deposit to a single address which is unlocked via a signature.
NameTypeDescription
Output Typeuint8Set to value 0 to denote a SigLockedSingleOutput.
Address oneOf
Ed25519 Address
NameTypeDescription
Address Typeuint8Set to value 0 to denote an Ed25519 Address.
AddressByteArray[32]The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key.
BLS Address
NameTypeDescription
Address Typeuint8Set to value 1 to denote a BLS Address.
AddressByteArray[49]The raw bytes of the BLS address which is a BLAKE2b-256 hash of the BLS public key.
Amountuint64The amount of tokens to deposit with this SigLockedSingleOutput output.
Payload Lengthuint32The length in bytes of the optional payload.
Payload optOneOf
Indexation Payload
Unlock Blocks Countuint16The count of unlock blocks proceeding. Must match count of specified inputs.
Unlock Blocks anyOf
Signature Unlock Block
Defines an unlock block containing signature(s) unlocking input(s).
NameTypeDescription
Unlock Typeuint8Set to value 0 to denote a Signature Unlock Block.
Signature oneOf
Ed25519 Signature
NameTypeDescription
Signature Typeuint8Set to value 1 to denote an Ed25519 Signature.
Public keyByteArray[32]The public key of the Ed25519 keypair which is used to verify the signature.
SignatureByteArray[64]The signature signing the serialized Transaction Essence.
BLS Signature
NameTypeDescription
Signature Typeuint8Set to value 1 to denote a BLS Signature.
SignatureByteArrayThe signature signing the serialized Transaction Essence.
Reference Unlock Block
References a previous unlock block in order to substitute the duplication of the same unlock block data for inputs which unlock through the same data.
NameTypeDescription
Unlock Typeuint8Set to value 1 to denote a Reference Unlock Block.
Referenceuint16Represents the index of a previous unlock block.

Table 2.3.5: Transaction payload.

2.3.5.3 FPC Statement

Opinions on conflicts of transactions and timestamps of the messages, mainly issued by high mana nodes. Details regarding FPC see Section 6.3 - Fast Probabilistic Consensus specification.

The Table 2.3.6 describes the entirety of a FPC statement's serialized form.

NameTypeDescription
Sizeuint32The size of the FPC statement payload.
Payload Typeuint32Set to 2 to denote a FPC statement Payload.
Versionuint8The version of the FPC statement payload.
Conflicts Countuint32The number of conflicts proceeding.
Conflicts optOneOf
Conflict
Describes a voting details in a given round for a transaction conflict.
NameTypeDescription
TransactionIDByteArray[32]The ID of the conflicting transaction.
Opinion
Represents the node's opinion value over the conflict in a given round.
NameTypeDescription
Valueuint8The node's opinion value in a given round.
Rounduint8The round number.
Timestamps Countuint32The number of timestamp voting proceeding.
Timestamps optOneOf
Timestamp
Describes the voting details over the timestamp for a given message and round.
NameTypeDescription
MessageIDByteArray[32]The ID of the message that contains the timestamp.
Opinion
Represents the node's opinion value over the conflict in a given round.
NameTypeDescription
Valueuint8The node's opinion value in a given round.
Rounduint8The round number.

Table 2.3.6: FPC statement.

2.3.5.4 dRNG Beacon Payloads

Messages that contain randomness (issued by the dRNG committee nodes). A single Beacon message is not sufficient to reveal the random number. Instead, sigThreshold or more Beacon messages are needed for the random number to be revealed. To recover the random number from the individual Beacon messages, all nodes in the network would need to perform Lagrange interpolation. To avoid that, the committee nodes produce a CollectiveBeacon, which contains a pre-computed random number (meaning that the committee nodes perform the Lagrange interpolation on their own). More information in Section 6.5 - Distributed Random Number Generator. The Table 2.3.7 describes the dRNG Beacon and CollectiveBeacon payload's serialized form.

NameTypeDescription
Sizeuint32The size of the payload.
Payload Typeuint32Set to 6 to denote a Collective Beacon payload or to 5 for Beacon payload.
Versionuint8The version of the payload.
InstanceIDuint32The identifier of the dRNG instance.
dRNG subpayload oneOf
TypeBeacon
Defines payload data for Beacon payload type.
NameTypeDescription
Rounduint64The round of the current beacon.
PartialPKByteArray[96]The public key of the issuer.
PartialSignatureByteArray[96]The collective signature of the current beacon.
TypeCollectiveBeacon
Defines payload data for CollectiveBeacon payload type.
NameTypeDescription
Rounduint64The round of the current beacon.
PrevSignatureByteArray[96]The collective signature of the previous beacon.
SignatureByteArray[96]The collective signature of the current beacon.
DistributedPKByteArray[48]The distributed public key.

Table 2.3.7 dRNG: beacon payload.

2.3.5.5 dRNG Application Message

A message used by a node to declare its willingness to participate in the committee selection process. Any node can issue an application message. However, low mana nodes are unlikely to be selected; hence, they can decide to not take part in sending application messages. The payload's serialized form is described in Table 2.3.8.

NameTypeDescription
Sizeuint32The size of the payload.
Payload Typeuint32Set to 3 to denote a Application Message payload.
Versionuint8The version of the payload.
InstanceIDuint32The identifier of the dRNG instance.

Table 2.3.8: dRNG application message payload.

2.3.5.6 dRNG DKG Payload

The Deal messages exchanged to produce a public/private collective key during the DKG phase (Table 2.3.9). The Deal messages are issued by the nodes that qualified for the dRNG committee participation .

NameTypeDescription
Sizeuint32The size of the payload.
Payload Typeuint32Set to 4 to denote a Deal Message payload.
Versionuint8The version of the payload.
InstanceIDuint32The identifier of the dRNG instance.
FromIndexuint32The index of the dealer.
ToIndexuint32The index of the verifier.
Deal oneOf
EncryptedDeal
An encrypted share struct.
NameTypeDescription
DhkeyByteArrayAn ephemeral Diffie-Hellman key.
NonceByteArrayThe nonce used in AES-GCM.
EncryptedShareByteArrayThe ciphertext of the share.
Thresholduint32The threshold of the secret sharing protocol (decided during committee selection).
CommitmentsByteArrayThe commitments of the polynomial used to derive the share.

Table 2.3.9: dRNG DKG payload.

2.3.5.7 Salt Declaration Payload

The salt declaration payload is used by nodes to declare their initial salt. In a salt declaration message, the declaring node includes the fields specified in Table 2.3.10.

NameTypeDescription
Sizeuint32The size of the payload.
Payload Typeuint32Set to 7 to denote a Salt declaration.
Versionuint8The version of the payload.
NodeIDuint32The declaring node ID (which may be different from the node ID of the issuer of the message).
Salt oneOf
Salt
The public salt of the requester defined.
NameTypeDescription
BytesByteArray The value of the salt.
ExpTimetimeThe expiration time of the salt.
TimestamptimeThe timestamp of the payload, which shall be close to the timestamp of its containing message.
SignaturetestThe node signature, that ensures all 'redeclarations' would be malicious.

Table 2.3.10: Salt declaration payload.

2.3.5.8 Indexations payload

Allows the addition of an index to the encapsulating message, as well as some arbitrary data. Nodes will expose an API that will enable the querying of messages by the index. Adding those capabilities may open nodes to DOS attack vectors:

  1. Proliferation of index keys that may blow up the node's DB
  2. Proliferation of messages associated with the same index

Node implementations may provide weak guarantees regarding the completion of indexes to address the above scenarios.

Besides the index, the payload will also have a data field. A message that has been attached to the Tangle has several useful properties: verifying that the content of the data did not change and determining the approximate time it was published by checking timestamps. If the payload will be incorporated under the signed transaction payload, the content will be signed as well.

The structure of the payload is presented in Table 2.3.11.

NameTypeDescription
Sizeuint32The size of the payload.
Payload Typeuint32Set to 8 to denote an Indexation payload.
Versionuint8The version of the payload.
IndexByteArrayThe index key of the message.
DataByteArrayData we are attaching.

Table 2.3.11: Indexations payload.

Note that index field should be 1 to 64 bytes long for the payload to be valid. The data may have a length of 0.