Skip to content

Latest commit

 

History

History
130 lines (93 loc) · 5.92 KB

eip-0029.md

File metadata and controls

130 lines (93 loc) · 5.92 KB
Raw

Ergo Box Attachments

  • Author: MrStahlfelge, aslesarenko
  • Status: Proposed
  • Version: 1.0
  • Created: 18-Feb-2022
  • License: CC0
  • Forking: not needed

Motivation

Historically, most payment systems provide a way to set a "purpose" field, used to display a short message from payment issuers to payment receivers. In the "state of the art" fintech practice sending money is converging with instant messaging platforms, where money can be sent among other messages i.e. directly in the chat.

Ergo platform allows easily send assets stored in a box in so that all network participants can read the contents of the box. However, there is no standard way to attach additional data so that all participants can recognize and parse it.

This EIP describes a data format for one of the optional registers of Ergo boxes that can be used to store an attachment to the box. In the simplest form, an attachment is a short text message, but the proposed standard can also include more complex content types.

Technically each attachment is a valid value of ErgoScript data type with additional conventions on its structure according to this standard, thus not changes are necessary in the protocol and existing apps.

Attachments can be set and read by supporting wallet applications and dApps and can be shown by Ergo Explorer and Wallet applications according to content type.

More over, since registers are available from ErgoScript, attachments can be parsed and used in spending conditions.

Ergo boxes background

A box can contain up to 10 registers of arbitrary ErgoScript type. Registers 0 to 3 are reserved and mandatory, registers 4 to 9 are optional and can be used as input for scripts or are used for token minting (see EIP-4).

Registers must be densely packed. It is not possible to use register 9 without adding register 4 to 8. However, if necessary registers of Unit type can be added to fill the empty slot with only 1 byte per register of overhead.

A box cannot be more than 4 kbytes of serialized bytes.

Ergo Attachment register

This standard specify that a particular register number 9 to be used as an Attachment register. To differentiate an Attachment from any regular non-empty register (i.g. used by contract) the Attachment register can be identified by magic bytes in its content and by the type. This is to simplify development of contracts so that contracts can use registers as necessary.

Any Ergo box can hold an Attachment if the register 9 is free i.e. it is not used (or expected) by contracts. If necessary registers of Unit type can be added to fill the empty registers up to register 9 (this is to satisfy the densly packed requirement on registers).

To support identification of Attachment register in a box, this standard requires any attachment register to have the following structure formed by nested pairs:

(magicBytes, (contentType, contentData))

This data value has the following type:

(Coll[Byte], (Int, Coll[Byte]))

This is a structure of two nested pairs, where:

  • magicBytes - the fixed bytes 50, 52, 50. Together with the encoding prefix for Tuple and Coll, the complete hex encoded register value will always start with 3c0e400e03505250. This prefix can be used to recognize this register as an attachment
  • contentType - is the type code from the table below
  • contentData - is the serialized bytes of the attachment

Attachment Content Type

The following table defines all standardized types of Attachment content:

Type Code Type Name Description
0 undefined Content type is not defined
1 multi attachment The contentData contains multiple attachments
2 plain-text UTF-8 text message
3 free code next free code to be used for new types

Undefined content type

When attachment register has undefined content type (for whatever reason) it should be ignored and handled as if there is no register at all. The same behavior is expected when the content type is not supported by the application.

Multi-attachments

This content type allows to attach an arbitrary collection of Attachments to the box.

When contentType = 1 then contentData contains serialized bytes of an ErgoScript collection Coll((contentType, contentData), ..., (contentType, contentData)) which have Coll[(Int, Coll[Byte])] type.

In this case the serialization format of contentData is the same as ErgoValue of this type (see Appkit for reference implementation).

Each item in the collection is an attachment of the corresponding content type. Thus, the collection can store attachments of different types.

Text Message attachment

When contentType = 2 then contentData contains serialized bytes of UTF-8 plain text message.

Examples

Purpose message Register hex representation
"Your loan January" 3c0e400e035052500411596f7572206c6f616e204a616e75617279
"Order NFT #32" 3c0e400e03505250040d4f72646572204e465420233332

As described, an attachment is stored in a register of a box. A transaction can have multiple outgoing boxes, hence it can have multiple attachments. This is desired behaviour: in Ergo's UTXO model, a single transaction can be used to send ERG and tokens to multiple recipients. Using this design, every recipient's box can have its own attachment.

Issuing applications

dApps and wallet applications using attachments should make their users aware of the fact that any attachment is public for everyone and can't be deleted. The applications should restrict the serialized size of the attachment so that the total box size is less then 4KiB.