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.2 - Message Layout

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).

Name	Type	Description
Size	uint32	The size of the payload.
Payload Type	uint32	The type of the payload.
Version	uint8	The 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	Descripstion	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 Name	Payload Type
Pure data	value 1
Transaction	value 0
FPC statement	value 2
dRNG Application Message	value 3
dRNG DKG	value 4
dRNG Beacon	value 5
dRNG Collective Beacon	value 6
Salt Declaration	value 7
Indexation	value 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).

Name	Type	Description
Size	uint32	The size of the payload.
Payload Type	uint32	Set to value 1 to denote a Data Payload.
Version	uint8	The version of the payload.
Data	ByteArray	The 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.

Name	Type	Description
Size	uint32	The size of the payload.
Payload Type	uint32	Set to value 0 to denote a Transaction Payload.
Version	uint8	The version of the payload.
Essence oneOf	Transaction Essence Describes the essence data making up a transaction. Name Type Description Version uint8 The version number of the Transaction Essence. Timestamp time The timestamp of the Transaction creation. Access Mana Pledge nodeID ByteArray[32] The nodeID to which access mana of the Transaction is pledged. Consensus Mana Pledge nodeID ByteArray32] The nodeID to which consensus mana of the Transaction is pledged. Inputs Count uint16 The amount of inputs proceeding. Inputs anyOf UTXO Input Describes an input which references an unspent transaction output to consume. Name Type Description Input Type uint8 Set to value 0 to denote an UTXO Input. Transaction ID ByteArray[32] The BLAKE2b-256 hash of the transaction from which the UTXO comes from. Transaction Output Index uint16 The index of the output on the referenced transaction to consume. Outputs Count uint16 The amount of outputs proceeding. Outputs anyOf SigLockedSingleOutput Describes a deposit to a single address which is unlocked via a signature. Name Type Description Output Type uint8 Set to value 0 to denote a SigLockedSingleOutput. Address oneOf Ed25519 Address Name Type Description Address Type uint8 Set to value 0 to denote an Ed25519 Address. Address ByteArray[32] The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key. BLS Address Name Type Description Address Type uint8 Set to value 1 to denote a BLS Address. Address ByteArray[49] The raw bytes of the BLS address which is a BLAKE2b-256 hash of the BLS public key. Amount uint64 The amount of tokens to deposit with this SigLockedSingleOutput output. Payload Length uint32 The length in bytes of the optional payload. Payload optOneOf Indexation Payload
Unlock Blocks Count	uint16	The 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). Name Type Description Unlock Type uint8 Set to value 0 to denote a Signature Unlock Block. Signature oneOf Ed25519 Signature Name Type Description Signature Type uint8 Set to value 1 to denote an Ed25519 Signature. Public key ByteArray[32] The public key of the Ed25519 keypair which is used to verify the signature. Signature ByteArray[64] The signature signing the serialized Transaction Essence. BLS Signature Name Type Description Signature Type uint8 Set to value 1 to denote a BLS Signature. Signature ByteArray The 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. Name Type Description Unlock Type uint8 Set to value 1 to denote a Reference Unlock Block. Reference uint16 Represents 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.

Name	Type	Description
Size	uint32	The size of the FPC statement payload.
Payload Type	uint32	Set to 2 to denote a FPC statement Payload.
Version	uint8	The version of the FPC statement payload.
Conflicts Count	uint32	The number of conflicts proceeding.
Conflicts optOneOf	Conflict Describes a voting details in a given round for a transaction conflict. Name Type Description TransactionID ByteArray[32] The ID of the conflicting transaction. Opinion Represents the node's opinion value over the conflict in a given round. Name Type Description Value uint8 The node's opinion value in a given round. Round uint8 The round number.
Timestamps Count	uint32	The number of timestamp voting proceeding.
Timestamps optOneOf	Timestamp Describes the voting details over the timestamp for a given message and round. Name Type Description MessageID ByteArray[32] The ID of the message that contains the timestamp. Opinion Represents the node's opinion value over the conflict in a given round. Name Type Description Value uint8 The node's opinion value in a given round. Round uint8 The 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.

Name	Type	Description
Size	uint32	The size of the payload.
Payload Type	uint32	Set to 6 to denote a Collective Beacon payload or to 5 for Beacon payload.
Version	uint8	The version of the payload.
InstanceID	uint32	The identifier of the dRNG instance.
dRNG subpayload oneOf	TypeBeacon Defines payload data for Beacon payload type. Name Type Description Round uint64 The round of the current beacon. PartialPK ByteArray[96] The public key of the issuer. PartialSignature ByteArray[96] The collective signature of the current beacon. TypeCollectiveBeacon Defines payload data for CollectiveBeacon payload type. Name Type Description Round uint64 The round of the current beacon. PrevSignature ByteArray[96] The collective signature of the previous beacon. Signature ByteArray[96] The collective signature of the current beacon. DistributedPK ByteArray[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.

Name	Type	Description
Size	uint32	The size of the payload.
Payload Type	uint32	Set to 3 to denote a Application Message payload.
Version	uint8	The version of the payload.
InstanceID	uint32	The 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 .

Name	Type	Description
Size	uint32	The size of the payload.
Payload Type	uint32	Set to 4 to denote a Deal Message payload.
Version	uint8	The version of the payload.
InstanceID	uint32	The identifier of the dRNG instance.
FromIndex	uint32	The index of the dealer.
ToIndex	uint32	The index of the verifier.
Deal oneOf	EncryptedDeal An encrypted share struct. Name Type Description Dhkey ByteArray An ephemeral Diffie-Hellman key. Nonce ByteArray The nonce used in AES-GCM. EncryptedShare ByteArray The ciphertext of the share. Threshold uint32 The threshold of the secret sharing protocol (decided during committee selection). Commitments ByteArray The 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.

Name	Type	Description
Size	uint32	The size of the payload.
Payload Type	uint32	Set to 7 to denote a Salt declaration.
Version	uint8	The version of the payload.
NodeID	uint32	The 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. Name Type Description Bytes ByteArray The value of the salt. ExpTime time The expiration time of the salt.
Timestamp	time	The timestamp of the payload, which shall be close to the timestamp of its containing message.
Signature	test	The 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.

Name	Type	Description
Size	uint32	The size of the payload.
Payload Type	uint32	Set to 8 to denote an Indexation payload.
Version	uint8	The version of the payload.
Index	ByteArray	The index key of the message.
Data	ByteArray	Data 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.