Clone this wiki locally
The new colored coins protocol defines a mini scripting language to efficiently encode the flow of assets from inputs to outputs. Each Transfers instruction is built out of 5 pieces of data (3 booleans and two integers):
|Skip||Boolean||1 bit||0 => Stay on input after processing
1 => skip to next input after processing
|Range *||Boolean||1 bit||0 => Output size is 5 bits and understood literally
1 => Output size is 13 bits and understood as specifying a range
|Percent||Boolean||1 bit||0 => Amount is understood literally
1 => Amount is understood as percent (1 byte)
|Output *||Integer||5 bits (Range=0)
13 bits (Range=1)
|Specific Output index between 0..31
(Range=1) Range of outputs between index 0 and the specified index (maximum 8191)
1-7 bytes (Percent=0)
1 Byte (Percent=1)
|Number of units to be transferred
Percent of units to be transferred
* In a Burn transaction case: Range = 0 and Output = 31 are interpreted as a burn instruction.
Decides whether the next instruction will be processed against that same input (skip = 0) or against the next input (skip = 1).
Decides whether the Output integer specifies the actual index of an output or the maximal index in a range of outputs (starting from index 0) as the target for the transfer instruction.
* Not yet supported in current version (0x02)
Decides whether the Amount integer should be understood as a number of units to be transferred (percent = 0) or as a percent of existing units to be transferred (percent = 1).
* Not yet supported in current version (0x02)
Specify the target output (or range of outputs) of the transfer.
- Range = 0: Make the transfer to the output of the specified index. Uses 5 bits, thus allowing to specify any output index between 0 and 31.
- Range = 1: Make the same transfer to all outputs up to the specified index.
Uses 13 bits, thus allowing to specify output ranges as big as 0-8191. Useful for Mass activities such as a sending a Christmas present coupon to all the employees in a company.
Specifies the amount of units (or percentage of units if percent = 1) to be transferred.
- Percent = 0: Amount is a signed integer encoded in our precision encoding scheme and requiring 1-7 bytes of memory, depending on the number.
- Percent = 1: The integer represents percents (with some precision after the decimal point).
Note on Memory Consumption
Note that the total memory requirement for encoding the Skip+Range+Percent+Output of each transfer instruction is exactly 1 or 2 bytes (depending on whether Range is 0 or 1). Therefore, each transfer instruction requires between 2 to 9 bytes, depending on the Amount.
The rules by which the colored coins software transfers assets between inputs and outputs when parsing transfer instructions are as follows:
- Begin with the first asset of the first input in the transaction (order is determined recursively)
- Transfer Instruction validation rules:
- The currently processed input must be an existing index.
- Output must indicate an existing index (irrelevant in burn case).
Amount must not exceed the amount of the currently processed asset, unless: the asset is aggregatable, a next asset with the same asset ID exists and with such amount which can satisfy the remaining instruction amount.
- In case of an invalid transfer instruction, all assets are sent to the last output.
- 0 move the specified amount of the currently processed asset to the output in the index specified in Output. The maximal index is 31.
- 1 move the specified amount of the currently processed asset to all outputs in the range of indices from 0 all the way to the index specified in Output. The maximal index is 8191.
All assets with remaining amounts are automatically transferred to the last output.
- A minimal dust amount in real satoshis is sent to each output for validity
- A transaction fee is left for miners to finance the processing of the transaction
- We have 3 assets of types
A, B, C
- The first input in our transaction has 10 units of asset
Aand 12 units of asset
- The second input has 100 units of asset
The following chain of instructions
0 0 0 0 3 0 0 0 1 7 0 0 1 1 50 1 0 0 2 3 0 1 0 49 2
0 0 0 0 3Transfer 3 units of asset
Afrom the first input to the first output (index 0). Stay on first input.
0 0 0 1 7Transfer the remaining 7 units of asset
Afrom the first input to the second output (index 1). Stay on first input.
0 0 1 1 50Transfer 6 units of asset
Bto second output. 6 units because 6 is 50% of 12 and we are now processing asset
Bbecause the previous instructions exhausted asset
Ain the first input. Stay on first input.
1 0 0 2 3Transfer 3 more units of asset
Bto the third output (index 2). Skip to second input.
0 1 0 49 2Transfer 2 units of asset
Cfrom the second input to each output, starting from the first output all the way to the 50th output (index 49).
- 3 units of asset
Bare implicitly transferred to the last output, since it had 12 units and only 9 were transferred explicitly.