---
# System prepended metadata

title: sig-locked-single-deposit-colored
tags: [RFC, ' draft']

---

---
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><b>Name<b></td>
        <td><b>Type</b></td>
        <td><b>Description</b></td>
    </tr>
    <tr>
        <td>Output Type</td>
        <td>varint</td>
        <td>
            Set to <strong>value 1</strong> to denote a <i>SigLockedSingleDepositColored</i>.
        </td>
    </tr>
    <tr>
        <td>Address (oneOf)</td>
        <td colspan="2">
            <details>
                <summary>WOTS Address</summary>
                <table>
                    <tr>
                        <td><b>Name<b></td>
                        <td><b>Type</b></td>
                        <td><b>Description</b></td>
                    </tr>
                    <tr>
                        <td>Address Type</td>
                        <td>varint</td>
                        <td>
                            Set to <strong>value 0</strong> to denote a <i>WOTS Address</i>.
                        </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><b>Name<b></td>
                        <td><b>Type</b></td>
                        <td><b>Description</b></td>
                    </tr>
                    <tr>
                        <td>Address Type</td>
                        <td>varint</td>
                        <td>
                            Set to <strong>value 1</strong> to denote an <i>Ed25519 Address</i>.
                        </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 <i>SigLockedSingleDepositColored</i> 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` ?