Introduction

The Tokenized protocol features a complete messaging suite for all types of messaging including general purpose private and public messaging, as well as commercial, financial and legal messaging in accordance with a variety of established Electronic Data Interchange (EDI) standards. They are also used to allow smart contracts to share information and orchestrate multiple signature transactions, such as atomic swaps.

Available Messages

Public Message

Generic public message or public announcement. Sent to an address(es). Can be used for an official issuer announcement.

Message Code 0002
Field Type Description
Timestamp Timestamp Timestamp in nanoseconds for when the message sender creates the transaction.
Subject varchar The subject / topic of the message.
Regarding Outpoint The output of the message that this message is regarding (responding to).
PublicMessage Document Tokenized Ltd. announces product launch.
Attachments Document[0] Documents attached to the message.

Private Message

Generic private message. Sent to another address(es). Encryption is to be used.

Message Code 0003
Field Type Description
Timestamp Timestamp Timestamp in nanoseconds for when the message sender creates the transaction.
Subject varchar The subject / topic of the message.
Regarding Outpoint The output of the message that this message is regarding (responding to).
PrivateMessage Document Tokenized Ltd announces product launch.
Attachments Document[0] Documents attached to the message.

Reverted Tx

A message that contains a bitcoin transaction that was accepted by the network or an agent and then invalidated by a reorg, or zero conf double spend. This serves as on chain evidence of the sending party's signatures and approval for the given transaction.

Message Code 0004
Field Type Description
Timestamp Timestamp Timestamp in nanoseconds for when the message sender creates the transaction.
Transaction varbin Serialized bitcoin transaction that was reverted/invalidated after being accepted.

Offer

A message that contains all of the details required for an agreement to be formed. Sent to an address(es). The Offer should have all, or nearly all, of the details required for the receiving party to accept the offer. The Offer shall be in the form of a partially formed Bitcoin transaction with all of the relevent details (offer, consideration, offeror's payment/receipt details, etc.). The Offer message is different to a Signature Request message in that it is missing the offeree's payment/receipt details (eg. UTXOs). If the Offer message is well received by the offeree, then the offeree can add their relevent details (eg. inputs/outputs) and sign the transaction. If an additional signature is required from the offeror at this point, then the partially-signed transaction can be sent to the offeror by way of a Signature Request message.

Message Code 1001
Field Type Description
Timestamp Timestamp Timestamp in nanoseconds for when the message sender created the offer.
Payload varbin Serialized Bitcoin transaction. The transaction needs data added by another party upon acceptance of offer.

Signature Request

Partially-signed transactions (Tokenized actions, Bitcoin, Multisig, Threshold Signatures, etc.) can be passed around on-chain to the parties (including Smart Contracts) that still have to sign the transaction.

Message Code 1002
Field Type Description
Timestamp Timestamp Timestamp in nanoseconds for when the message sender creates the transaction.
Payload varbin Full serialized bitcoin tx with multiple inputs from different wallets/users.

Settlement Request

A message that contains a multi-contract settlement that needs settlement data added by another contract. Sent to another contract to request data be added.

Message Code 1003
Field Type Description
Timestamp Timestamp Timestamp in nanoseconds for when the message sender creates the transaction.
TransferTxId TxId Tx Id of the transfer request transaction that triggered this message.
ContractFees TargetAddress[0] Contract fees (in bitcoin) and addresses(PKHs) where fees should be paid. Added by each contract as settlement data is added.
Settlement varbin Serialized settlement OP_RETURN that needs data added by another contract.

Output Metadata

Metadata associated with the output. Aka Transaction details. It is used to describe the purpose of the transaction and add other relevant information. Often encrypted (DH, RSA) to make it private for one or more parties. DH for b2b where multiple parties can see the description. RSA or the like for descriptions only visible to one of the transacting parties. Optional

Message Code 1004
Field Type Description
OutputDescription varchar A Description that accompanies the output. A transaction description. Can be NULL Example: eg. Invoice 3024, Pay Mike back for camping.
Tags uint[0] Predefined values for describing the output.
CustomTags OutputTag[0] Free form text fields for describing the output. Groceries, Moomba Gas Compressor Project, Cash Register 3, Fitness, Entertainment, Special, VIP Section, North Carolina Store, Waitress: Cindy Smith, etc.

Initiate Relationship

A message used to initiate a new relationship between 2 or more parties. The M1 container specifies the sender tx input and requested participant tx outputs. If there are more than 2 parties the encryption secret provided in the envelope protocol is used as the base encryption secret. If there are only 2 parties, then the ECDH secret of each key pair is used to encrypt each message.

Message Code 2001
Field Type Description
Type uint(1) The type or purposed of the relationship. 0 - Conversation (direct messages), 1 - Channel (entity/business to entity/business)
Seed varbin The seed used to derive keys for the relationship.
Flag varbin The flag can optionally be used to identify messages in the relationship so that all members don't have to be tagged in each message. It isn't needed for two party relationships, but is recommended for relationships with more members. It will be included in it's own op return for all message transactions. It is recommended to be a random 20 byte value similar to public key hashes. The flag will be the Payload of an Envelope protocol message with a Payload Protocol ID of "F". If this value is not specified then there must be an output to the next key in the relationship chain for every member in the group.
EncryptionType uint(1) Type of encryption used for messages within the relationship. 0 - Encryption keys embedded in envelope protocol. 1 - Encryption key embedded in this message is used as base key for future messages. Used for relationships with more than 2 members so the encryption key doesn't have to be encrypted to each member in every message.
ProofOfIdentityType ProofOfIdentityType The type/format of the sender's proof of identity.
ProofOfIdentity varbin Sender's proof of identity.
ChannelParties ChannelParty[0] Information about the entities in the channel. Not included if this is not a channel initiation. These represent the companies in a channel. A channel is recommended to have 2 entities and several individual members per party. The individual members can discuss terms while the parties are used for official actions.

Pending Accept Relationship

A pending accept to a relationship that provides information about a requested participant.

Message Code 2002
Field Type Description
ProofOfIdentityType ProofOfIdentityType The type/format of the sender's proof of identity.
ProofOfIdentity varbin Sender's proof of identity.

Accept Relationship

Accept a relationship.

Message Code 2003
Field Type Description
ProofOfIdentityType ProofOfIdentityType The type/format of the sender's proof of identity.
ProofOfIdentity varbin Sender's proof of identity.

Relationship Amendment

Amend a relationship. Add/Remove members. Modify permissions. This is encrypted with the current base encryption secret, but can provide a new base encryption secret that starts after this message.

Message Code 2004
Field Type Description
Seed varbin The new seed used to derive keys for the relationship after this message.
BaseEncryptionSecret varbin The new base encryption secret used to derive encryption secrets for the relationship after this message. Each time a message is sent, the current seed hash is added to the base encryption secret and that value is used to encrypt the message.
AddMemberIndexes uint(4) Indexes to the outputs of the members that are being added to the group.
DropMemberIndexes uint(4) Indexes to the outputs of the members that are being removed from the group.

Initiate Thread

Start a thread from within a conversation or channel.

Message Code 2005
Field Type Description
Flag varbin The flag is required to identify messages in the thread so that all members don't have to be tagged in each message. It is recommended to be a random 20 byte value similar to public key hashes. The flag will be the Payload of an Envelope protocol message with a Payload Protocol ID of "F"
Seed varbin The seed used to derive keys for the thread. If this value is not specified, then the original seed value from the parent conversation or channel is used.