Omni Core Incident Report March 2020

On 2020-02-25 an Omni Core integrator, Antoine Le Calvez from Coin Metrics made us aware of a potential issue with Omni Core through responsible disclosure. After further inspection, we believed Omni Core v0.6 and later versions were affected by a potential replay of transactions after a block reorganization. The developer was provided a bounty for reporting the issue promptly and responsibly to the Omni Layer team. 

When a block reorganization occurs, the internal state of Omni Core is rolled back and the effects of the affected block or blocks are reverted. Omni Core then tries to catch up and scans for new transactions. When a new block is found or a longer chain is connected, the new transactions are processed.

However, we believe that due to an optimization of the locking code in Omni Core in an update from v0.5 to v0.6 multiple events may occur simultaneously, resulting in a faulty state:

  1. A block is orphaned
  2. Omni Layer transactions from the orphaned block are rolled back and an older state is restored
  3. A new block arrives and is registered
  4. Omni Core scans and executes new transactions up to the current chain tip, in case there is a gap between the old restored state and the current chain
  5. The transactions from the new block are processed

The correct order would be:

  1. Omni Layer transactions are reverted
  2. An older state is restored
  3. If the state is too old, Omni Core catches up and reparses the old transactions
  4. A new block arrives or a longer chain connects
  5. The new transactions are processed

In this edge case the new block is registered before Omni Core scans for potential transactions in the gap between the old state and the new chain tip. This leads to the transactions from the newly connected block getting executed, even though they will be executed again when the new block is processed in the regular way. The end result is that the effect of some transactions may be executed twice by the parsing engine of individual clients, depending on the order in which the blocks were received. 

Note: No new money is created out of thin air and all rules for sending tokens are still in place. For example: when A had a balance of 10 tokens and sent 10 tokens to B, then the second execution of the transaction would simply be considered as invalid and A still ends up with 0 tokens and B with 10 tokens.

However, if the second execution of the transaction was valid, for example if A had started with a balance of 100 tokens, then it’s effect would be applied twice, potentially moving more tokens than the sender originally intended.

Conclusion: The reach of this issue is difficult to determine. The local state may vary from node to node as it depends on which block the local node saw first during a block reorganization. This edge case was patched and released in Omni Core v0.8 and all future releases. Users of Omni Core versions prior to v0.6 and users of the OmniExplorer API were not affected.

Additionally, specific instructions for integrators on how to validate their local nodes data were included in the release notes of the upgrade and a previously planned protocol level upgrade (Feature ID 15: Activate trading of any token on the distributed exchange) was used to ensure affected clients were not subjected to further possible errors. 

The developers have not been made aware of any balance discrepancies resulting in loss of funds by users. The upgrade proceeded successfully and all running clients share the correct consensus state.

Omni Core Incident Report March 2020

Trading against Bitcoin on the Omni distributed exchange using Omni Core

This guide is based off the knowledge base article available on the Omni Core wiki. In the future for up to date information and procedures please always reference the knowledge base.

This guide provides some basic instructions on how to interact with the Bitcoin markets on the distributed exchange of the Omni Layer protocol using Omni Core.

Prerequisites: A fully synchronized Omni Core Client v0.8+, an address holding bitcoins and some basic knowledge of using the command line interface of Omni Core. For selling tokens, you also need the tokens you wish to post for sale on the address holding the bitcoins.

Table of contents:

Selling: Posting a new sell offer

In order to create a new sell offer you need to use the command omni_senddexsell, which can be used to place, update or cancel a sell offer on the distributed exchange. Any token can be traded against Bitcoin and the distributed exchange is not limited to trading of Omni or Test Omni.

For example this command:

$ omnicore-cli "omni_senddexsell" "123sellerswalletaddress45689abc" 1 "10" "0.75" 25 "0.00005" 1

Will create a new sell offer:

  • From the address 123sellerswalletaddress45689abc
  • For token ID #1 (Omni tokens)
  • Selling "10" token ID #1 (Omni tokens)
  • Requesting a total of "0.75" bitcoins for all
  • Allowing a payment window of 25 blocks. This is the length of time a buyer has to send payment after sending their “accept transaction”.
  • Requires the buyers payment transaction to have a minimum miner fee of "0.00005" BTC
  • Action 1 = Create new offer

Note: An Address can only have one active sell offer at a time, regardless of the token ID being sold. Attempts to post additional sales from the same address will be invalid.

Selling: Updating an existing sell offer

Just like posting a new sale, the same command is also be used to update an existing sell order with new information. Say you decide you want to change an offer, e.g. the number of coins you are offering for sale, or change the asking price.

Simply replace the action = 1 with action = 2 and send the new transaction with the new details.

For example this command:

$ omnicore-cli "omni_senddexsell" "123sellerswalletaddress45689abc" 1 "5" "0.5" 25 "0.00005" 2

Will update our previous sell offer:

  • From the address 123sellerswalletaddress45689abc
  • For token ID #1 (Omni tokens)
  • Selling "5" token ID #1 (Omni tokens) – Updated Parameter
  • Requesting a total of "0.5" bitcoins for all – Updated Parameter
  • Allowing a payment window of 25 blocks
  • Requires the buyers payment transaction to have a minimum miner fee of "0.00005" BTC
  • Action 2 = Update offer

Note that while the portion of an offer which has been accepted can’t be changed, sending an update message still has an effect, in that it affects any coins which have not been accepted, and it affects accepted coins, if the buyer fails to send payment.

Selling: Canceling your existing sell offer

Just like posting a new sale, the same command is also be used to cancel an existing sell order.

To cancel an offer, simply replace the action = 1 with action = 3 and use the same token ID to explicitly specify the offer to cancel. The fields amount for saleamount of bitcoins desiredpayment window and minimum miner fee are irrelevant and can be set to 0.

For example this command:

$ omnicore-cli "omni_senddexsell" "123sellerswalletaddress45689abc" 1 "0" "0" 25 "0.00005" 3

Will cancel our previous sell offer:

  • From the address 123sellerswalletaddress45689abc
  • For token ID #1 (Omni tokens)
  • Selling "0" token ID #1 (Omni tokens) – irrelevant for this action type
  • Requesting a total of "0" bitcoins for all – irrelevant for this action type
  • Allowing a payment window of 25 blocks – irrelevant for this action type
  • Requires the buyers payment transaction to have a minimum miner fee of "0.00005" BTC irrelevant for this action type
  • Action 3 = Cancel offer

Buying: Viewing available offers

You can view the complete list of available offers using the omni_getactivedexsells command.

For example:

$ omnicore-cli "omni_getactivedexsells"
[
  {
    "txid" : "OriginalSaleTransactionID",
    "propertyid" : 1,                  
    "seller" : "123sellerswalletaddress45689abc",
    "amountavailable" : "2",  
    "bitcoindesired" : "0.5",
    "unitprice" : "0.1" ,    
    "timelimit" : 25,
    "minimumfee" : "0.00005",    
    "amountaccepted" : "3.0",
    "accepts": [
    ]
  },
 ...,
 {
    "txid": "6a99305e39fb2874498a5503de7d191ff447472b19cad0be0e1ee3a8d0a57cb4",
    "propertyid": 2,
    "seller": "1rM1oMEFMfhPBo4kRaf2CMXf9XQCHyYWi",
    "amountavailable": "33.59857941",
    "bitcoindesired": "0.33937959",
    "unitprice": "0.01010101",
    "timelimit": 10,
    "minimumfee": "0.00010000",
    "amountaccepted": "0.00000000",
    "accepts": [
    ]
  }
]

In this output you can see the list of all current open offers and their available amounts and prices.

If there is a specific sellers address you wish to view, the command can filter the outputs using the sellers address.

Example:

omnicore-cli "omni_getactivedexsells" "123sellerswalletaddress45689abc"
[
  {
    "txid" : "OriginalSaleTransactionID",
    "propertyid" : 1,                  
    "seller" : "123sellerswalletaddress45689abc",
    "amountavailable" : "2",  
    "bitcoindesired" : "0.5",
    "unitprice" : "0.1" ,    
    "timelimit" : 25,
    "minimumfee" : "0.00005",    
    "amountaccepted" : "3.0",
    "accepts": [
    ]
  }

Buying: Accepting an offer

After viewing the list of available sell offers in the previous command if you wish to proceed with purchasing you must first send an accept transaction to the sellers address using the command omni_senddexaccept.

Purpose: The accept transaction, when confirmed on the blockchain, is validated to determine if the seller still has the amount of tokens you wish to purchase available.

If the seller does, then those tokens are reserved for the buyer for a period equal to the "timelimit" as specified by the sell offer. This time limit refers to the number of blocks in which the final payment must be received for the reserved funds to be released and transferred to the buyer.

For example this command:

$ omnicore-cli "omni_senddexaccept" "123buyerswalletaddress45689abc1" "123sellerswalletaddress45689abc" 1 "3.0"

Will:

  • Reserve for purchase for the address 123buyerswalletaddress45689abc1
  • From the seller "123sellerswalletaddress45689abc"
  • For token ID #1 (Omni Tokens)
  • "3.0" the amount of tokens to reserve

If the accept transaction is confirmed valid and the funds are reserved they will be visible in the accepts data element in the output from the omni_getactivedexsells “123sellerswalletaddress45689abc”.

Example:

$ omnicore-cli "omni_getactivedexsells" "123sellerswalletaddress45689abc"
[                                  // (array of JSON objects)
  {
    "txid" : "OriginalSaleTransactionID",
    "propertyid" : 1,                  
    "seller" : "123sellerswalletaddress45689abc",
    "amountavailable" : "2",  
    "bitcoindesired" : "0.5",
    "unitprice" : "0.1" ,    
    "timelimit" : 25,
    "minimumfee" : "0.00005",    
    "amountaccepted" : "3.0",
    "accepts": [                    
      {
        "buyer" : "123buyerswalletaddress45689abc1",               // (string) the Bitcoin address of the buyer
        "block" : 123456,                  // (number) the index of the block that contains the "accept" order
        "blocksleft" : 20,                 // (number) the number of blocks left to pay
        "amount" : "3.0"            // (string) the amount of tokens accepted and reserved
        "amounttopay" : "0.3"       // (string) the amount in bitcoins needed finalize the trade
      }
    ]
  }

Note: If after your transaction confirms you do not see an entry in the accepts field for your address then it means your accept transaction was not valid. Most likely this happened because the seller no longer had enough tokens remaining for sale that were unreserved. You can view the exact details using omni_gettransaction <your original accept transaction id/hash>

Buying: Paying for an offer

Note: It is highly recommend that a buyer only attempt to send the payment when there is a large number of blocks remaining for the payment to be accepted.

  • Due to the volatile nature of the Bitcoin blockchain, if a payment transaction gets delayed and doesn’t confirm until after the reserved funds "timelimit" has expired, the payment is lost and the funds remain with the seller. THERE IS NO UNDO in this situation.

Please proceed with caution!

Once your accept transaction has been confirmed and you see the amount of tokens you wish to buy are reserved for you, you can complete the purchase by using the omni_senddexpay command.

IMPORTANT Final payment MUST BE SENT USING THE omni_senddexpay command as sending payment from any other non Omni Layer supporting wallet or interface could result in a complete loss of funds.

For example:

$ omnicore-cli "omni_senddexsell" "123buyerswalletaddress45689abc1" "123sellerswalletaddress45689abc" 1 "0.3"

Will send a payment of "0.3" bitcoins, for the token #1 that the seller "123sellerswalletaddress45689abc" currently has reserved for the buyer "123buyerswalletaddress45689abc1"

Once the transaction confirms before the time limit expires the reserved funds will be released to the buyer and the sale is complete.

If the payment is not received (= confirmed on the blockchain) before the time limit expires, then the reserved funds are released back to the seller and available for someone else to purchase.

The Omniwallet interface guide will be released shortly after the next Omniwallet update.

Trading against Bitcoin on the Omni distributed exchange using Omni Core

Activation of trading any token on the distributed exchange

Dear Omni Layer users,

Beginning with Bitcoin block 627250, which is expected to be on or about 23rd April, 2020, a new version of the distributed exchange on the Omni Layer protocol goes live.

After the activation, it will be possible to trade any token for bitcoins, e. g. Omni, MaidSafeCoin, USD₮ or Agoras without any third party involved.

Omni Core 0.8.0+ users can use the new feature as soon as it is available and Omni Wallet users not in restricted jurisdictions will have access shortly thereafter through   https://www.omniwallet.org/

In order to take advantage of the new transaction processing improvements, please upgrade to Omni Core 0.8.1 … Please see: https://github.com/OmniLayer/omnicore/releases

To avoid any consensus divergences, for example when a user with an old version considers a transaction as valid, while it is actually invalid under new rules, Omni Core versions lower than 0.8.0 will go into a fail-safe state after the activation and will no longer be started without falling out of consensus with the network.

Activation of trading any token on the distributed exchange