sig-locked-single-deposit-colored

--- title: sig-locked-single-deposit-colored tags: RFC, draft --- + Feature name: `sig-locked-single-deposit-colored` + Start date: 2020-07-14 + RFC PR: [iotaledger/protocol-rfcs#0000](https://github.com/iotaledger/protocol-rfcs/pull/0) # Summary This RFC introduces colored coins to the IOTA protocol by the addition of a new `Output Type` for the `Output` of a `Signed Transaction Payload` defined in https://hackmd.io/1KwmdoqAT4-J7yuuas6ZUQ. It allows IOTA tokens to be unlocked by a signature while marking them with a certain "color". # Motivation Colored coins are tokens that are marked to represent and manage real world assets. This opens up a whole new range of use cases as assets managed by IOTA tokens are secure, transparent and immutable. They are very generic and can virtually represent any kind of asset: with colored coins, one can prove ownership of stocks, bonds, real estate, precious metals, currencies, other crypto-currencies... # Detailed design This new locking mechanism, `SigLockedSingleDepositColored (OutputType = SIG_LOCK_COLORED)` can be seen as an extension of `SigLockedSingleDeposit (OutputType = SIG_LOCK)` as they share a similar layout and the same unlock type based on signatures, the `Signature Unlock Block`. However, it does not replace `SigLockedSingleDeposit` as it is still needed to move uncolored token. The main implication of this addition is that when previously a balance was just an amount, it is now a combination of an amount and its corresponding color. ``` ColoredBalance = {amount: uint64, color: Color} ``` Where a color is simply a sequence of bytes that can be handled by the user with the help of commands and which is retained when being transferred. ``` Color = Array<byte>[32] ``` ## Layout The layout is straightforward and very similar to the `SigLockedSingleDeposit` layout. Two new fields are added to manage the color of tokens. <table> <tr> <td>Name</td> <td>Type</td> <td>Description</td> </tr> <tr> <td>Output Type</td> <td>varint</td> <td> Set to value 1 to denote a SigLockedSingleDepositColored. </td> </tr> <tr> <td>Address (oneOf)</td> <td colspan="2"> <details> <summary>WOTS Address</summary> <table> <tr> <td>Name</td> <td>Type</td> <td>Description</td> </tr> <tr> <td>Address Type</td> <td>varint</td> <td> Set to value 0 to denote a WOTS Address. </td> </tr> <tr> <td>Address</td> <td>ByteArray[49]</td> <td>The T5B1 encoded WOTS address.</td> </tr> </table> </details> <details> <summary>Ed25519 Address</summary> <table> <tr> <td>Name</td> <td>Type</td> <td>Description</td> </tr> <tr> <td>Address Type</td> <td>varint</td> <td> Set to value 1 to denote an Ed25519 Address. </td> </tr> <tr> <td>Address</td> <td>ByteArray[32]</td> <td>The raw bytes of the Ed25519 address which is a BLAKE2b-256 hash of the Ed25519 public key.</td> </tr> </table> </details> </td> </tr> <tr> <td>Amount</td> <td>uint64</td> <td>The amount of tokens to deposit with this SigLockedSingleDepositColored output.</td> </tr> <tr> <td>Operation</td> <td>varint</td> <td>The color operation to apply on the tokens.</td> </tr> <tr> <td>Color</td> <td>Array<bytes>[32]</td> <td>Optional color depending on the operation.</td> </tr> </table> ## Operations The currently available color operations are: - `MINT` - Type = `0`; - Used to create (or "mint") new colored coins; - Sets the color of the tokens to the Transaction ID; - Only works on un-colored tokens; - Does not require the color field; - `MOVE` - Type = `1`; - Simply moves tokens of a given color; - Only one color can be moved per output; - Requires the color field; - `UNCOLOR` - Type = `2`; - Resets the color of the tokens; - Requires the color field; ## Validation All validations rules of `Message`, `Signed Transaction` and `Signature Unlock Block` are still relevant. In addition, a transaction is valid, if it only spends colors in the amounts that were available in the used inputs. ### Syntactic Validation All of the following assertions must be true: - `Output Type` field should be `1` to denote `SigLockedSingleDepositColored`; - `Address` field should follow the same validation rules as in `SigLockedSingleDeposit`; - `Address Type` field must either be `0` or `1` to denote a `WOTS` address or an `Ed25519` address; - If `WOTS`, `Address` field bytes must be valid T5B1 bytes; - `Amount` field must be > 0; - `Operation` field must be either `0`, `1` or `2` to denote operation `MINT`, `MOVE` or `UNCOLOR`; - `Color` field must not be present on a `MINT` operation; - `Color` field must be present on a `MOVE` or `UNCOLOR` operation; ### Semantic Validation - For `MOVE`, the total amount of tokens per color in the inputs must exactly match the total tokens per color on the outputs; # Drawbacks - Necessarily comes with increased complexity by adding new logic; - Affects not only IOTA nodes but also clients and wallets; - Requires more disk space; # Rationale and alternatives Colored coins are not a core protocol feature but still a nice feature to have for real world use cases and adoption. It is then not mandatory and added to the IOTA protocol with a new output type. # Unresolved questions - Are there any more validation rules that comes with the introduction of colored coins ? - How does `UNCOLOR` works with inputs with different colors ? - Can we move colored tokens with `SigLockedSingleDeposit` ?