9.2 订单匹配引擎 (Orders Matching Engine)

https://github.com/compolabs/spark/tree/master/services/matcher

版本警告 (Version warning)

The master branch contains the latest work-in-progress version of the Spark smart contract. It hasn't been audited and may contain severe security issues or may not work at all.

主分支( master branch)包含Spark智能合约的最新工作进程版本。它没有经过审计，可能包含严重的安全问题，也可能根本无法工作。

关于 (About)

This repository contains a program that matches orders on the Fuel Network, allowing users to trade cryptocurrencies with each other. Limit order itself is a data structure created off-chain.

这个资源库包含了一个在Fuel网络上匹配订单的程序，用户相互之间可以进行加密货币交易。限价单本身是一个在链外创建的数据结构。

The matching engine works by using a smart contract that calculates the prices of different orders and then matches them based on those prices. Users create limit orders, which are a way to specify a buying or selling price for a cryptocurrency. The matching engine then matches the buy and sell orders with the best possible price. Once matched, the orders are executed by transferring cryptocurrency from one user to another, according to the agreed upon price. The program includes various test cases to ensure its proper functioning.

匹配引擎通过使用一个智能合约，来计算不同订单的价格，然后根据这些价格进行匹配。用户创建限价单，这是一种为加密货币指定买卖出价的方式。匹配引擎之后以最好的价格匹配买卖订单。一旦匹配，订单就会根据商定的价格，将加密货币从一个用户转移到另一个用户。该程序包括各种测试案例，确保其正常运作。

The architecture of the Spark Order Matching Engine is based on a smart contract that uses a matching function to calculate the prices of the assets being traded. The engine also calculates the lowest price of an order and transfers the assets accordingly

Spark订单匹配引擎的架构是基于智能合约，使用匹配功能来计算被交易资产的价格。该引擎还计算出订单的最低价格，并相应地转移资产。

To explain the process, let us consider a few examples: 为了解释这个过程，让我们考虑几个例子：

Example 1: If there are two orders, Order0 and Order1, where Order0 is for 20k USDT for 1 BTC at a price of 0.00005 and Order1 is for 0.51 BTC for 10k USDT at a price of 0.000051. The engine calculates that the order with the lowest price is Order0, and transfers 10k USDT from Order0 to Order1, and 0.5 BTC from Order1 to Order0. The remaining 0.01 BTC is transferred to the owner of Order1.

例子1： 如果有两个订单，订单0和订单1，其中订单0是20k USDT换1 BTC，价格为0.00005，订单1是0.51 BTC换10k USDT，价格为0.000051。引擎计算出价格最低的订单是订单0，并将10k USDT从订单0转移到订单1，0.5 BTC从订单1转移到订单0。剩余的0.01 BTC被转移给订单1的所有者。

Example 2: If Order0 is for 10k USDT for 0.5 BTC at a price of 0.00005 and Order1 is for 1.02 BTC for 20k USDT at a price of 0.000051. The engine calculates that the order with the lowest price is Order0, and transfers 10k USDT from Order0 to Order1, and 0.5 BTC from Order1 to Order0. The remaining 0.01 BTC is transferred to the owner of Order1.

例子2： 如果订单0是10k USDT换0.5 BTC，价格为0.00005，订单1是1.02 BTC换20k USDT，价格为0.000051。引擎计算出价格最低的订单是订单0，并将10k USDT从订单0转移到订单1，0.5 BTC从订单1转移到订单0。剩余的0.01 BTC被转移给订单1的所有者。

The engine also includes a set of test cases to ensure that the orders are matched correctly.

该引擎还包括一套测试案例，确保订单的匹配正确。

订单匹配引擎架构 (Order Matching Engine Architecture)

智能合约match_orders功能逻辑 (Smart contract match_orders function logic)

价格的计算(Prices calculation)

price_0 = asset1 / asset0
price_1 = asset0 / asset1

  • order0 is the order with the lowest price price_a <= price_b order0是具有最低价格的订单price_a <= price_b

  • if orders have the same price, then order0 is the order from the first argument 如果订单有相同的价格，那么订单0就是第一个参数中的订单

If order0_amount0 >= order1_amount1 如果 **`order0_amount0 >= order1_amount1 举例 (Examples)

  • a) Order0 : 20k USDT ➡️ 1 BTC | price: 0.00005 Order1: 0.51 BTC ➡️ 10k USDT | price: 0.000051 a) 订单0 : 20k USDT ➡️ 1 BTC | 价格: 0.00005 订单1 : 0.51 BTC ➡️ 10k USDT | 价格: 0.000051

  • b) Order0: 20k USDT ➡️ 1 BTC | price: 0.00005 Order1: 0.5 BTC ➡️ 10k USDT | price: 0.00005 b) 订单0 : 20k USDT ➡️ 1 BTC | 价格: 0.00005 订单1 : 0.5 BTC ➡️ 10k USDT | 价格: 0.00005

  • c) Order0: 20k USDT ➡️ 1 BTC | price: 0.00005 Order1: 1.02 BTC ➡️ 20k USDT | price: 0.000051 c) 订单0: 20k USDT ➡️ 1 BTC | 价格: 0.00005 订单1: 1.02 BTC ➡️ 20k USDT | 价格: 0.000051

  • d) Order0: 20k USDT ➡️ 1 BTC | price: 0.00005 Order1: 1 BTC ➡️ 20k USDT | price: 0.00005 订单0: 20k USDT ➡️ 1 BTC | 价格: 0.00005 订单1: 1 BTC ➡️ 20k USDT | 价格: 0.00005

​

order0_fulfill_percent = order1_amount1 / order0_amount0 * 100

a,b: order0_fulfill_percent = 10k / 20k * 100 = 50 %
c,d: order0_fulfill_percent = 20k / 20k * 100 = 100 %

转移 Transactions

  • Transfer order1_amount1 (a,b: 10k USDT; c,d: 20k USDT) from order0 to order1 将订单1_amount1 (a,b: 10k USDT; c,d: 20k USDT)从订单0转移到订单1

  • Transfer order0_fulfill_percent * order0_amount1 / 100 (a,b: 0.5 BTC; c,d: 1 BTC) from order1 to order0 将订单0_fulfill_percent * order0_amount1 / 100 (a,b: 0.5 BTC; c,d: 1 BTC) 从订单1转到订单0。

  • Transfer order1_amount0 - order0_fulfill_percent * order0_amount1 / 100 (a: 0.01 BTC; b: 0 BTC; c: 0.02 BTC; d: 0 BTC) from order1 to order1.owner 将订单1_amount0 - order0_fulfill_percent * order0_amount1 / 100 (a: 0.01 BTC; b: 0 BTC; c: 0.02 BTC; d: 0 BTC) 从订单1转移到订单1.owner

  • Order1 completed 订单1完成

  • if order0_amount0 == order1_amount1 order0 completed (c,d) 如果 order0_amount0 == order1_amount1 order0 则完成 (c,d)

If order0_amount0 < order1_amount1 如果 order0_amount0 < order1_amount1

举例 Examples

  • a) Order0: 10k USDT ➡️ 0.5 BTC | price: 0.00005 Order1: 1.02 BTC ➡️ 20k USDT | price: 0.000051 a) 订单0: 10k USDT ➡️ 0.5 BTC |价格：0.00005 订单1：1.02 BTC ➡️ 20k USDT |价格：0.000051

  • b) Order0: 10k USDT ➡️ 0.5 BTC | price: 0.00005 Order1: 1 BTC ➡️ 20k USDT | price: 0.00005 b) 订单0: 10k USDT ➡️ 0.5 BTC |价格：0.00005 订单1：1 BTC ➡️ 20k USDT |价格：0.00005

order1_fulfill_percent = order0_amount1 / order1_amount0 * 100

a,b: order1_fulfill_percent = 10k / 20k * 100 = 49 с хуем %

转机 Transactions

  • Transfer order0_amount0 (10k USDT) from order0 to order1 将 order0_amount0 (10k USDT) 从 订单0 转移到 订单1

  • Transfer order0_amount1 (0.5 BTC) from order1 to order0 将 order0_amount1 (0.5 BTC) 从 订单1 转移到 订单0

  • Transfer order1_amount0 * order1_fulfill_percent - order0_amount1 (a: 0.01 BTC, b: 0 BTC) from order1 to order1.owner 将 order1_amount0 * order1_fulfill_percent - order0_amount1 (a: 0.01 BTC, b: 0 BTC) 从 订单1 转移到 order1.owner

  • Order0 completed 订单0完成

测试用例 (Test cases)

正向测试用例 (Positive test cases)

Order a will be matched with order b, order c is needed to close biggest order to make sure the contract delivers exactly as expected.

订单a将与订单b匹配，订单c需要关闭最大的订单，以确合约完全按照预期交付。

  1. price_a < price_b && order_a_amount0 > order_b_amount1 Order a: 20k USDT ➡️ 1 BTC | price: 0.00005 Order b: 0.51 BTC ➡️ 10k USDT | price: 0.000051 price_a < price_b && order_a_amount0 > order_b_amount1 订单a：20k USDT ➡️ 1 BTC |价格：0.00005 订单 b：0.51 BTC ➡️ 10k USDT |价格：0.000051

  2. price_a < price_b && order_a_amount0 == order_b_amount1 Order a: 20k USDT ➡️ 1 BTC | price: 0.00005 Order b: 1.02 BTC ➡️ 20k USDT | price: 0.000051 price_a < price_b && order_a_amount0 == order_b_amount1 订单a：20k USDT ➡️ 1 BTC |价格：0.00005 订单 b：1.02 BTC ➡️ 20k USDT |价格：0.000051

  3. price_a < price_b && order_a_amount0 < order_b_amount1 Order a: 10k USDT ➡️ 0.5 BTC | price: 0.00005 Order b: 1.02 BTC ➡️ 20k USDT | price: 0.000051 price_a < price_b && order_a_amount0 < order_b_amount1 订单a：10k USDT ➡️ 0.5 BTC |价格：0.00005 订单 b：1.02 BTC ➡️ 20k USDT |价格：0.000051

  4. price_a == price_b && order_a_amount0 > order_b_amount1 Order a: 20k USDT ➡️ 1 BTC | price: 0.00005 Order b: 0.5 BTC ➡️ 10k USDT | price: 0.00005 price_a == price_b && order_a_amount0 > order_b_amount1 订单a：20k USDT ➡️ 1 BTC |价格：0.00005 订单 b：0.5 BTC ➡️ 10k USDT |价格：0.00005

  5. price_a == price_b && order_a_amount0 == order_b_amount1 Order a: 20k USDT ➡️ 1 BTC | price: 0.00005 Order b: 1 BTC ➡️ 20k USDT | price: 0.00005 price_a == price_b && order_a_amount0 == order_b_amount1 订单a：20k USDT ➡️ 1 BTC |价格：0.00005 订单 b：1 BTC ➡️ 20k USDT |价格：0.00005

  6. price_a == price_b && order_a_amount0 < order_b_amount1 Order a: 10k USDT ➡️ 0.5 BTC | price: 0.00005 Order b: 1 BTC ➡️ 20k USDT | price: 0.00005 price_a == price_b && order_a_amount0 < order_b_amount1 订单a：10k USDT ➡️ 0.5 BTC |价格：0.00005 订单 b：1 BTC ➡️ 20k USDT |价格：0.00005

负向测试案例 (Negative test cases)

  1. price_a > price_b && order_a_amount0 > order_b_amount1 Order a: 20k USDT ➡️ 1.02 BTC | price: 0.000051 Order b: 0.5 BTC ➡️ 10k USDT | price: 0.00005 price_a > price_b && order_a_amount0 > order_b_amount1 订单a：20k USDT ➡️ 1.02 BTC |价格：0.000051 订单 b：0.5 BTC ➡️ 10k USDT |价格：0.00005

  2. price_a > price_b && order_a_amount0 == order_b_amount1 Order a: 20k USDT ➡️ 1.02 BTC | price: 0.000051 Order b: 1 BTC ➡️ 20k USDT | price: 0.00005 price_a > price_b && order_a_amount0 == order_b_amount1 订单a：20k USDT ➡️ 1.02 BTC |价格：0.000051 订单 b：1 BTC ➡️ 20k USDT |价格：0.00005

  3. price_a > price_b && order_a_amount0 < order_b_amount1 Order a: 10k USDT ➡️ 0.51 BTC | price: 0.000051 Order b: 1 BTC ➡️ 20k USDT | price: 0.00005 price_a > price_b && order_a_amount0 < order_b_amount1 订单a：10k USDT ➡️ 0.51 BTC |价格：0.000051 订单 b：1 BTC ➡️ 20k USDT |价格：0.00005

  4. order_a.asset0 != order_b.asset1 Order a: 10k USDT ➡️ 0.51 BTC Order b: 1 BTC ➡️ 20k USDC order_a.asset0 != order_b.asset1 订单a：10k USDT ➡️ 0.51 BTC 订单b：1 BTC ➡️ 20k USDC

Previous9.1Spark限价单智能合约 (Spark Limit Orders Smart Contract)Next9.3 前端(Frontend)

Last updated