Introduction

The Tokenized Protocol provides a fairly simple system for defining message types, contents, and encoding. Using the methods described below everything is defined. Then code is generated to read and write those messages. Then smart agents and wallets can use that code to operate on the protocol.

Envelope

The Tokenized Protocol uses the envelope protocol to wrap and encode its messages. The envelope protocol provides a common method for Tokenized and other protocols to identify which protocol is being used, its version, and other meta data about a payload. It also enables a common method of encryption and providing MetaNet information. The envelope protocol is responsible for encoding the "header" data and the payload within an OP_RETURN payload.

The Tokenized Protocol uses the following fields of the envelope protocol to specify the message contained. The payload is then encoded using protobuf, which provides a common method of encoding binary and ascii fields within a predefined data structure.

Field Type Description
PayloadVersion uint(1) The version number that determines the structure of the action payload and field definitions.
PayloadIdentifier fixedchar(2) The Action Code that determines the expected contents of the action payload. Example: C1

Data Types

Each field in a protocol message is defined with a data type. Standard scalar types have a single value, these include primitive, alias types, and field types. Fields can also be defined as a list of one of those types.

Primitive Primitive types are the actual raw data types defined below. All of the other types are defined from primitive types.
Alias Alias types are references to other types. They can reference a primitive type that is used for a specific purpose. For example, an Address is a `varbin(small)`, but has a special encoding that is more strict than `varbin(small)`. They can also reference resource codes. For example, a `RejectionCode` is a code for an item in the rejection resource.
Field Field types are composites of other types. They have multiple fields within them that can be primitive, alias, or other field types.

Primitive Types

Type Description
int A signed integer. size is the number of bytes for the integer. Valid values for size are 1, 2, 4, 8.
uint An unsigned integer. size is the number of bytes for the integer. Valid values for size are 1, 2, 4, 8.
float A floating point number. size is the number of bytes for the float. Valid values for size are 4 and 8.
bool A boolean stored as 1 byte. Zero is false, non-zero is true.
bin Fixed length binary data. size is the length in bytes of the data.
varbin Variable length binary data. varSize defines the maximum size of the data as defined in Variable Sizes.
fixedchar Fixed length text data. The data is assumed to be UTF-8 unless the first two bytes are a valid UTF-16 BOM (Byte Order Method). size is the length in bytes of the data.
varchar Variable length text data. The data is assumed to be UTF-8 unless the first two bytes are a valid UTF-16 BOM (Byte Order Method). varSize defines the maximum size of the data as defined in Variable Sizes.

List Types

Fields within the Tokenized protocol can be defined as a list of a specified data type. This is done by adding a [] to the end of the type value. The maximum number of elements in a list are defined by listSize as defined in Variable Sizes.

Variable Sizes

Fields within the Tokenized protocol can be lists of objects or variable length objects. The maximum number of elements in a list are defined by listSize. The maximum size of a variable sized object are defined by varSize. The valid values for listSize and varSize are as follows. If no value is specified for listSize or varSize then tiny is used.

Value Description
tiny Defines a max size of 2^8^-1 or 255.
small Defines a max size of 2^16^-1 or 65,535.
medium Defines a max size of 2^32^-1 or 4,294,967,295.
large Defines a max size of 2^64^-1 or approximately 1.8x10^19^.