White Papers

bright bulb clear dark

V – 0.3

In those white papers, I will explain how Coco works and provide all the information required to build it. I am assuming that you read and familiar with the below articles, if not please do so before continue reading.

First, I will describe the structure and the encoding of the components in the system, and then I will show the flow that will demonstrate the connection between them.

System structure

drawing 1

The system is built from Pools and Wallets, each Pool can have an unlimited amount of Wallets connected to it, each Wallet communicates with only one Pool.

  • The Pool is responsible for the creation of blocks, and broadcasting transactions. Pool maintain the system model in a database that has all the information of the blockchain, such as Wallets balances, automated smart contract and more.
  • The wallet is the client side program, it’s responsible for the creation of Wallet public and private keys, making transactions and mine coins. It communicates with the Pool to fetch Wallet balance, broadcast a transaction or submit a block.

Wallet address

When a user starts the wallet application for the first time, it generates a public and a private key, where the public key is user Wallet address. It uses Curve25519 because of its fast processing speed and relatively small signature size, only 64 bytes.

Block encoding

Block encoding is used to exchange blocks between Pools and to save block as files for backup purposes.

Base types


Integers are 4 bytes Big-endian of data where the first 2 bits of the first byte are used to represent the byte length of the integer.

2 bits encoding Byte length Values range
00 1 0 – 64
01 2 64 – 16,384
10 3 16,384 – 4,194,304
11 4 4,194,304 – 1,073,741,824

Micro Integer

Used to encode small values. The values multiplied by 100,000,000, rounded using Floor and encoded into an Integer as described above. Only values smaller than 10.73741824 can be encoded.


32 bytes computed using SHA-256


64 bytes signature computed with Curve-25519

Block Structure

  1. Header
  2. Lists
  3. Footer

Header Structure

  1. Block id – Incremental Integer value starting from 94
  2. Core version UUID – 16 bytes universally unique integer
  3. Pool domain address
    1. Domain byte length Integer
    2. UTF-8 formatted domain address
  4. Transaction fees – 8 bytes floating point value the total transaction fees
  5. Smart contract fees – 8 bytes floating point value the total smart contract fees
  6. Reward – Integer block reward
  7. Reward id – Integer, the wallet id to where 99% of the Reward, transaction fees, and smart contract fees will be sent
  8. Leadership reward id – Integer, the wallet id of the leadership organization where 1% of the Reward, transaction fees, and smart contract fees will be sent
  9. Smart contract execution – Hash
  10. Previous block – Hash of the previous block


  1. Footer hash – Hash, header and lists hash, step 1 in the mining process
  2. Job Id – 16 bytes – A blob value that the pool generates to prevent mining collisions between the miners of the pool
  3. Mined date – 8-byte integer, milliseconds epoch time
  4. Blob – 8 byte of random data that the miners use to manipulate the block hash
  5. Block hash – Hash, the hash of this block

Lists structure

Each list has the below structure

  • Type – Integer list type
  • Block id – Integer block id
  • Features – 1 Byte feature bitmask
  • Count – Integer, number of items in the list
  • Items body

Prior to the first list, there will be an Integer that will indicate how many lists there are in this block. The value can also be 0. This integer is considered to be part of the lists.

List types

The possible values for list types

  1. 1 to 1 Transactions
  2. 1 to many Transactions with the same balance
  3. 1 to many Transactions with a different balance
  4. Smart Contracts
  5. Smart Contracts applications
  6. Trusts
  7. Trusted party: Balance update
  8. List group
  9. Addresses list

List features

The possible values for list features

  1. Microtransaction: If “on” the coin transactions amount will be encoded with Micro Integer. If “off” the amount will be 8 bytes floating point.
  2. Default transaction fee: If “on” the transaction fees will be the Pool hardcoded value and will not appear in the transaction if “off” the transaction fees will be encoded with Micro Integer
  3. Trusted signature: If “on” the signature will be omitted, only valid in Lists group

1 to 1 transaction

  • Sender signature
  • Sender id, integer
  • Receiver id, Integer
  • Amount as specified in the feature bitmask
  • Transaction fees as specified in the future bitmask

1 to many transactions with same balance

  1. Sender signature
  2. Sender id – Integer
  3. Receivers count – Integer
  4. Receivers – Each is
    1. Receiver id –  Integer
  5. Amount as specified in the feature bitmask
  6. Transaction fees as specified in the feature bitmask

1 to many transactions with a different balance

  1. Sender signature
  2. Sender id – Integer
  3. Receivers count – Integer
  4. Receivers – Each is
    1. Receiver id –  Integer
    2. Amount
  5. Transaction fees as specified in the feature bitmask

Smart Contracts

  • CreatorId – Integer wallet id of the contract creator
  • Contract hash – Byte Array hash value of the contract
  • Model data – Fixed Byte Array
  • Model script – Fixed Byte Array. UTF-8 JS contract script
  • Creator signature

Smart Contracts Application

  • Applicant wallet id, Integer
  • Contract Id, Integer
  • Applicant signature


  • Sender id, Integer
  • Trusted party wallet id, Integer
  • Termination hours time, Integer. A value of zero indicates to start termination
  • Sender signature

Trusted party: Balance update

  • Trusted party id – Integer
  • Updates – Each is
    • Id – Integer
    • Balance as specified in the feature bitmask
  • Trusted party signature

List Group

  • Trusted party id
  • Lists  – From the lists above
  • Trusted party signature

Addresses list

  • Public key wallet address

Wallet transaction encoding

The wallet uses a simpler encoding structure. The pool will convert it to block encoding structure in such way that it’s possible to convert it back to wallet encoding structure. The validation of wallet signature needs to be done using wallet encoding structure.

  • Amount – 8 bytes floating point value
  • Block hash – The Hash value of the last known block. Using the hash value over the blockId makes it impossible to make future transactions and extend the transaction termination time.
  • Sender public key – 32 bytes, the Pool will replace it with wallet id, so the Wallet does not need to maintain addresses database.
  • Receivers list count – Integer number of the receivers
  • For each receiver
    • Receiver wallet public key – 32 bytes
    • Amount – 8 bytes Floating point value the amount sent to that receiver
  • Transaction fees – 8 bytes floating point value, fee amount for this transaction
  • Signature – 64 bytes

Mining process

This is a step by step process to compute the block hash

  1. Compute SHA-256 of the Header and the Lists
    1. Compute SHA-256 of each of the lists
      1. Compute a chain hash of all the items.  H(...H(H(H(H(i_1), H(i_2)), H(i_3)), H(i_4)),...H(i_n)) where H is the SHA-256 function and i_n are the items from 1 to n
    2. Compute SHA-256 of all those lists concatenation based on the order appeared in the block, which is up to you.
    3. Comput SHA-256 of the header SHA-256 hash the lists hash
  2. Generate job id 16 bytes
  3. Concatenate the results from step 1 and 2 and compute SHA-256 of them
  4. Concatenate the current timestamp(8 bytes milliseconds epoch time) with the result from 3 and compute SHA-256 of them
  5. Compute SHA-256 of the blob
  6. Take the result of 5, the 32 bytes array and sum every 4 bytes to one, so you get 8 bytes. Convert it to Java long typedrawing 2
  7. Use the previous result(Step 6) to pre-seed a Java.Util.Random and computes random.nextInteger(5)
  8. Use the previous result(Step 7) to select a hashing algorithm from the list below and use it to compute the blob hash(Same 8 bytes blob used in step 5)
    1. MD5
    2. SHA-1
    3. SHA-384
    4. SHA-512
    5. MD5
  9. Concatenate the result from step 4,5 and 8 and compute SHA-256 from them
  10. If the result from step 9 is smaller than your selected share-difficulty submit it to the pool. Go back to step 4 and try a different blob

Mining Flow

  1. Wallet/Miner selects its share difficulty
  2. Wallet/Miner request a mining job from the Pull, the Miner, provides its Wallet address.
  3. The Pull generates a JobId. It will be used later to reward the Miner.
  4. The Pull completes steps 1 to 4 of the Mining process.
  5. The Pull sends the Miner the result of step 4 along with JobId and pulls difficulty.
  6. The Miner continue the mining process from step IV, each time it solves the block with difficulty provided by the Pool, it performs step 6
  7. The Miner submits to the Pool a solution of the block under the Pool difficulty, it sends JobId, blob and Mining Time.
  8. The Pool calculates the block hash based on the data received from the Miner.
    • If the hash indeed solves the block under Pools difficulty, it adds one reward point to the Miner
    • If the hash solves the block under the block difficulty, the Pull submits a new block and share the reward with all the miners based on the reward points. The Pool also keeps some of the rewards as a service fee for the miners.
  9. The Pool responds to the miner with the same response as in step 3 to keep the miner up to date with the new blocks that been discovered by the system.

To summarize it, the Miner will continuously keep mining and periodically send hash solutions to the Pool, for each such solution the Pool will reward the miner and when the solution is good enough also to solve the block, the Pool will submit new block.

Each time the Miner is communicating with the Pool, it will be updated with the most recent block data so it will mine the right block.

Also, note that in case the Miner had pending reward points from the Pool, but another Pool solved the block, the reward points will be lost, Miners only get a reward for the blocks they solve.

Joining Royal Network flow

In case a new pool would like to join the Royal Network, let’s call it Pool A, it must first mine a block on its own. To help those Pools, the Pools provide a protocol where the new Pool sends its domain to some other Pool, let’s call it Pool B, Pool B replies than with a hash code of step one in the mining process where the domain address is Pool A domain.

The incentive for B to implement this protocol is that it keeps its wallet id as the reward address for the block A will mine.

Block validation flow

Once a block was discovered, or once a new block was received it will go through the below process of validation.

In the below validation tests “new block” refers to the block that been tested and “Current block” refers to the last block in the blockchain.

Block hash test

The test pass if and only if the new block hash is smaller then the new block difficulty

Mined date test

The test pass if and only if the tested date is before the current date and within one min of it. The current date was the date when the test started, or the connection with the peer who provided the new block was established.

Block id test:

  • if the new block id is smaller or equal to the current block id the test fails
  • If the new block id is greater by more than one, it can only happen when the new block was received from another Pool. The Pool will go into recovery mode. It will back up the database, drop it and rebuild it from the Pool who sent the block. If the recovery process fails, it will fail this test and restore the database from the backup.
  • If the new block is greater by one from the current block the test will pass.

Core version test

The core version is a hardcoded value. It is used to force hard forks into the system. The test pass if and only if, the new block value match this value.

Pool domain address test

A random Wallet – Pool protocol request is issued from this Pool to the provided domain, and the response is tested to be valid.

Reward test

The test pass if and only if the tested reward amount matches the expected amount

Reward id test

The test pass if and only if the reward Id is a registered wallet id save in the database

Previous block hash test

The test pass if and only if the new block Previous block hash equals to current block hash

Leadership reward id

The test pass if and only if the leadership reward id matches the hardcoded value

Transactions + Transactions fees test

The test pass if and only if the below conditions are true

  • All transaction signatures are unique and valid
  • There is no wallet with a negative balance in the system
  • The transaction fees in the new block match the expected value
  • The total amount of coins in the system wasn’t changed

Smart contracts + Smart contracts fees test

  • A file is created.
  • For each transaction made via smart contracts, one line is being written to the file, it contains the information of the amount being transferred, and it’s destination.
  • Then file Hash is being calculated using SHA-256.
  • The test pass if and only if the below conditions are true
  • Calculated hash value match Smart contract execution hash value
  • Smart contracts fees in the new block match the expected value
  • The total amount of coins in the system wasn’t changed

D.T.P flow

  • D.T.P publish its wallet and ask users to sent trust transactions to it with some minimum termination time.
  • Users sent trust transaction to D.T.P from their wallet app.
  • Periodically the D.T.P makes update transactions to match users balance in D.T.P to their balance in Coco.

In case D.T.P needs to make transactions to wallets that did not entrust it, it still can do it in an efficient way using the List Group transaction. The List Group transaction using the same encoding as done in the block and can contain multiple lists inside it, from any type, while the D.T.P only required providing just one signature, it’s own.

Transaction flow

  • Users feel in the transaction details as listed below
  • Full amount – Will be encoded as 8 bytes integer
  • One or several recipients wallet address
  • Fees: User can either specify a nondefault fee amount or leave it blank to use default fees
  • The wallet send a prepare transaction request to the pool
  • The pool calculate transaction fees and validate the transaction, in case the transaction is valid the pool respond with the full transaction details otherwise it sends the reason why the transaction was invalid
  • The wallet presents to the user the entire transaction with the exact mining fees
  • The user can choose to approve or discard the transaction, in case the user accepts it the wallet submit the transaction to the Pool
  • The pool validate the transaction and broadcast it to the other Pools
  • Eventually one of the Pools mine the transaction to the block
  • In case of no pool mine the transaction it will expire after six blocks

Smart contract flow

I will use an example to explain this flow.

A seller created an online game and would like to offer a subscription plan for his users. For the first trial month, the users will pay one coin and be starting from the second month they will pay ten coins every month.


  1. Seller writes down the terms and services and the script of the contract in a text file.
  2. Seller calculate SHA-256 of the file
  3. The seller sends the script, the contract hash, and his wallet Id to the Pool
  4. The Pool share the contact with other Pools, and eventually, it’s been mined as part of a block
  5. The user receives from the seller a link to the contract, where he can download it online
  6. The user downloads the contract from his Wallet.
  7. The wallet compile and replace the script with its compiled version, and then it computes SHA-256 of the contract
  8. The user reviews the contract and hit the apply button
  9. The wallet uses the calculated hash as the contract id and sends an apply command to the Pull
  10. The Pool validates the contract and broadcasts it to other Pools. Eventually, the contract is being added to the blockchain.

Block reward flow

The block reward is calculated as follow:

250 – floor(block Id / 3188)

The reward starts from 250 coins and every 3188 blocks the reward is reduced by one coin until it reaches 0. The first block id starts with 94. It makes the total number of the coins in the system to 100,000,000 coins.

After the reward reaches 0, the formula will be changed to the one below:

min(Total lost coins, 50)

Every block reward will be 50 coins until the lost coins are consumed.

The lost coins are coins collected with the below process:

Five years from the genesis block and every three years afterward, the process will run and delete all the lost wallets. A lost wallet is a wallet that hasn’t made any transaction and is not registered to any D.T.P, or the D.T.P that it registered to did not made any transaction in the past three years as well.

The balance from the lost coins will become part of the block reward as detailed above.

Missing topics

  • Smart contracts script
  • Background of the leadership organization


Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.