Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
393 lines (286 sloc) 12.4 KB

Keoken

Technical specification (Draft)

Version 0.1

Bitprim Argentina SRL

dev@bitprim.org

Document Versioning

Version Date Reviewer
0.1 2018-Jul-26 Bitprim Project Inc.

Introduction

This document defines the transaction types supported by the Keoken Protocol.

Keoken Protocol is built over any cryptocurrency compatible with the Bitcoin scripting language. Specifically Keoken needs for OP_RETURN (0x6a) operation code. Right now Keoken could be implemented, over Bitcoin Cash (BCH), Bitcoin (BTC) and Litecoin (LTC), but it is not limited to them. The cryptocurrency where Keoken is implemented is called Transport Currency or Transport Coin (from here on we can call it only Transport).

Keoken Transportation

Keoken needs to be transported on an existing cryptocurrency with Bitcoin compatible scripting language that supports the OP_RETURN (0x6a) operation code.

The transportation protocol is defined in the following way:

Keoken Transportation Protocol

  • The first 6 bytes are fixed and always the same. hex: 6a0400004b50.
  • The next byte or bytes represent the size of the Keoken data part, and it's encoded in the following way:
First Byte Extra Bytes Description
dec: 04 to 75
hex: 04 to 4b
- There are no extra bytes. The size of the data part is represented by the value of the first byte.
dec: 76
hex: 4c
OP_PUSHDATA1
1 There is one (1) extra byte after the first byte. The size of the data part is represented by the value of that extra byte.
dec: 77
hex: 4d
OP_PUSHDATA2
2 There are two (2) extra bytes after the first byte. The size of the data part is represented by the value of those extra bytes in little endian order.
dec: 78
hex: 4e
OP_PUSHDATA4
4 There are four (4) extra bytes after the first byte. The size of the data part is represented by the value of those extra bytes in little endian order.

So the data size could be represented using 1, 2, 3 or 5 bytes.

  • After the data size, N more bytes must follow, where N is equal to the value of the data size part. Those N bytes represent the Keoken Transaction Data, that is independent of the transport protocol and will be described below.

Keoken Transactions

Keoken Transactions are valid transactions of the Transport Coin, so it must follow the same rules as the Transport Coin plus new rules added by the Keoken Protocol.
There are several types of Keoken Transactions (and new types may be created in the future), each type has its own set of rules and there are a set of general rules that has to be followed by all the Keoken transaction types.

A valid Transport coin transaction will be considered a valid Keoken transaction if it complies with the following general rules:

  1. There is at least one output that complies with the format described above in the Keoken Transportation section.

The Keoken Protocol always uses the first Keoken-Transportation-Compliant output found.
Succeeding Keoken-Transportation-Compliant outputs will be ignored by Keoken.

The other outputs whose scripts contain an OP_RETURN opcode but do not comply with the Keoken-Transportation rules will be ignored by Keoken, although could be valid outputs in the Transport Coin.

Transaction Types

Transactions Format

Keoken transactions have the following common header:

Field Name Data Type Description
Version 16-bit unsigned integer, big-endian format. Keoken protocol version. Right now it is 0 (zero) for all the transaction types. Future revisions of this specification may change it.
Type 16-bit unsigned integer, big-endian format. Integer representing the transaction type.
Specific Data N bytes. Dynamic data, specific to the transaction type.

Transactions that fail to follow this format will be ignored by the Keoken protocol.

Transaction Types Specification

Create Asset

This transaction is used to create new assets.

Format:

Field Name Data Type Data Range Description
Version 16-bit unsigned integer, big-endian format. Fixed value: 0x00 Keoken protocol version.
Type 16-bit unsigned integer, big-endian format. Fixed value: 0x00 Transaction type: create asset.
Name Null-terminated ASCII string. Min string size: 2 bytes, 1 real char plus the null char (\0). Max string size: 33 bytes, 32 real chars plus the null char (\0). Name of the asset.
Amount 64-bit two's complement signed integer, big-endian format. Greater than 0 (zero). Initial amount of tokens.

If the value of the fields are out of the specified ranges or the transaction doesn’t comply the validations detailed below, the transaction will be considered an Invalid Keoken Transaction, even if it is a valid transaction in the Transport Coin. Therefore it will not be executed by the Keoken Interpreter.

Every asset has a unique ID generated by Keoken. The first available Keoken asset ID starts in 1 (one) and increments in one for every new asset.

Here is a list of specific rules and validations for the create asset transaction type:

  1. The address related to the first input will be the asset’s owner. If the first input has no related address, the transaction will be considered an Invalid Keoken Transaction. The rest of the inputs will be ignored by the Keoken protocol, although could be valid inputs in the Transport Coin.

  2. Asset Name must be non empty and null-terminated ASCII encoded string, with a max size of 32 bytes + 1 byte for the null character.

  3. Amount must be greater than 0 (Zero).

Send Tokens

This transaction is used to send tokens from a source Transport coin address to a target Transport Coin address.

Format:

Field Name Data Type Data Range Description
Version 16-bit unsigned integer, big-endian format. Fixed value: 0x00 Keoken protocol version.
Type 16-bit unsigned integer, big-endian format. Fixed value: 0x01 Transaction type: send tokens.
AssetId 32-bit unsigned integer, big-endian format. Greater or equal than 1 (one) Id of the asset. It has to be created using "Create Asset" transaction.
Amount 64-bit two's complement signed integer, big-endian format. Greater than 0 (zero). Amount of tokens to transfer.

Here is a list of specific rules and validations for the send tokens transaction type:

  1. The address related with the first input will be considered as the source address. If the first input has no related address, the transaction will be considered an Invalid Keoken Transaction. The rest of the inputs will be ignored by the Keoken protocol, although could be valid inputs in the Transport Coin.

  2. The first output with a different related address than the source address will be considered the target address of the Keoken transaction. If such an address does not exist, the transaction will be considered an Invalid Keoken Transaction. The rest of the outputs will be ignored by the Keoken protocol, although could be valid outputs in the Transport Coin.

  3. The Asset ID must exist. (It had to have been created with the Create Asset transaction).

  4. Amount must be greater than 0 (Zero).

  5. Amount must be less than or equal to the tokens available to the source address account.

Examples

Create Asset

Create a new Keoken Asset called: Bitprim with 1'000'000 Tokens.

The owner of the asset will be the wallet mgt5VsxNUroj9M2uQaTEwbc5am5LMh8F6v.

Create a transaction using the owner wallet as the first input. An output must be the OP_RETURN script with the Keoken message. All the satoshis coins minus the miner fee can be sent to any wallet in another output.

The UTXO data is:

  • output-point: aa699dc5ddf598a50dc2cb2cb2729629cb9d2d865df38e4367d13f81ef55f96e:0

  • amount: 49.9996 TBCH

  • output-script: dup hash160 [0ef6dfde07323619edd2440ca0a54d311df1ee8b] equalverify checksig

Transaction example:

  • 01000000016ef955ef813fd167438ef35d862d9dcb299672b22ccbc20da598f5ddc59d69aa000000006a473044022056f0511deaaf7485d7f17ec953ad7f6ede03a73c957f98629d290f890aee165602207f1f1a4c04eadeafcd3f4eacd0bb85a45803ef715bfc9a3375fed472212b67fb4121036735a1fe1b39fbe39e629a6dd680bf00b13aefe40d9f3bb6f863d2c4094ddd0effffffff02a007052a010000001976a9140ef6dfde07323619edd2440ca0a54d311df1ee8b88ac00000000000000001b6a0400004b5014000000004269747072696d0000000000000f424000000000

Important Data:

  • Vin Addr: mgt5VsxNUroj9M2uQaTEwbc5am5LMh8F6v

  • Vout1 Addr: mgt5VsxNUroj9M2uQaTEwbc5am5LMh8F6v

  • Vout2 Script: 6a0400004b5014000000004269747072696d0000000000000f4240

Script:

Hexa: Data
6a OP_RETURN
04 OP_PUSH_DATA
00004b50 Prefix = " KP"
14 OP_PUSH_DATA
0000 Keoken Version = 0
0000 Keoken Type = 0 (Create Asset)
4269747072696d00 Asset name = "Bitprim" (Null terminated)
00000000000f4240 Amount of tokens created = 1000000

Send Tokens

Send 100 Bitprim Tokens from mgt5VsxNUroj9M2uQaTEwbc5am5LMh8F6v (owner wallet) to mgAbyFPdhCtUnnbayot2cbqudHGkFS8CsB (destination wallet).

Create a transaction with three outputs:

  • First output: dust to the destination wallet.

  • Second output: utxo satoshis minus dust minus miner fee.

  • Third output: Keoken message.

The UTXO data is:

  • output-point: 2fcb4d3c432fbc14ec709b1592a0c3b121c22de7525b789071f6cff27126571e:0

  • amount: 49.9994 TBCH

  • output-script: dup hash160 [0ef6dfde07323619edd2440ca0a54d311df1ee8b] equalverify checksig

Transaction example:

  • 01000000011e572671f2cff67190785b52e72dc221b1c3a092159b70ec14bc2f433c4dcb2f000000006b48304502210084c05aa0d2a60f69045b46179cff207fde8003ea07a90a75d934ec35d6a46a3a02205b328724e736d9400b3f13ac6e0e49462048dfc2c9a7bd1be9944aa9baa455144121036735a1fe1b39fbe39e629a6dd680bf00b13aefe40d9f3bb6f863d2c4094ddd0effffffff03204e0000000000001976a914071ed73aa65c19f86c88a29a789210fafc8d675188ac606b042a010000001976a9140ef6dfde07323619edd2440ca0a54d311df1ee8b88ac0000000000000000176a0400004b50100000000100000002000000000000006400000000

Important Data:

  • Vin Addr: mgt5VsxNUroj9M2uQaTEwbc5am5LMh8F6v

  • Vout1 Addr: mgAbyFPdhCtUnnbayot2cbqudHGkFS8CsB

  • Vout2 Addr: mgt5VsxNUroj9M2uQaTEwbc5am5LMh8F6v

  • Vout3 Script: 6a0400004b501000000001000000020000000000000064

Hexa: Data
6a OP_RETURN
04 OP_PUSH_DATA
00004b50 Prefix = "\0\0KP"
10 OP_PUSH_DATA
0000 Keoken Version = 0
0001 Keoken Type = 1
00000002 Asset ID = 2
0000000000000064 Amount of tokens sent = 100