EIP-29 Attachment

eip-0029.md

@@ -0,0 +1,130 @@
+# 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.