Status

DECIDED

Stakeholders
Iurii Vinogradov Makoto Takemiya Egor Ivkov Vladislav Markushin 
Outcome

Iroha 2 will provide all functionality needed to support these scenarios.

Due date
Owner
Nikita Puzankov 

Background

DEX is planned to be implemented as Iroha 2.0 module.

Action items

Problem

Decentralized exchange provides an ability to transfer assets between accounts in exchange for other assets. Let's use a simple case as an example:

Peer to Peer Scenario

PlantUML diagram

@startuml
Buyer -> Iroha: Place Exchange Order(20XOR, 100USD)
Seller -> Iroha: Place Exchange Order(100USD, 20XOR)
Iroha -> Iroha: Transfer 20XOR from Seller to Buyer
alt Success:
  Iroha -> Iroha: Transfer 100USD from Buyer to Seller
end
@enduml

So Iroha should secure peer to peer exchanges across the ledger from malicious actions. In this case Iroha does a good job, the only thing it should check is an ability to transfer assets from and to accounts.

But there are more corner cases when we deal with exchanges via bridge:

Peer to Peer across Bridge Scenario

  • Cross blockchain rates should be taken into consideration
  • Iroha should prevent double spent of assets 
  • Additionally to transferring assets, Iroha should mint and de-mint them

Simple scenario:

PlantUML diagram

@startuml
Buyer -> Iroha: Place Exchange Order(20ETH, 1BTC)
Seller -> Iroha: Place Exchange Order(1BTC, 20ETH)
Iroha -> "BTC bridge": Mint 1BTC to Seller
alt Success:
  Iroha -> Iroha: Transfer 1BTC from Seller to Buyer
  alt Success:
    Iroha -> "ETH bridge": Mint 20ETH to Buyer
    alt Success:
      Iroha -> Iroha: Transfer 20ETH from Buyer to Seller
    end
  end
end
@enduml

Liquidity Pool Scenario

Liquidity Pools is another dimension in this set of scenarios for Decentralized Exchanges. Basically it can be used in pair with or without bridges, so let's take a more clean example without them. But let's not stick to an Exchange Pair and work with multi-currency liquidity:

PlantUML diagram

@startuml
"Liquidity Provider" -> Iroha: Register Exchange Liquidity [20XOR, 20ETH, 1BTC]
Seller -> Iroha: Place Exchange Order(1BTC, 20ETH)
Iroha -> "BTC bridge": Mint 1BTC to Seller
alt Success:
  Iroha -> Iroha: Transfer 1BTC from Seller to "Liquidity Provider"
  alt Success:
    Iroha -> Iroha: Transfer 20ETH from "Liquidity Provider" to Seller
  end
end
@enduml

From the high level perspective this scenario looks very similar with two previous because all of them are based on top of two Iroha functions:

  • Assets Transfer
  • Iroha Triggers

Resulting Behavior

Let's write all three scenarios as one feature description according to BDD with more details:

Feature: Decentralized Exchange

  Scenario: Buyer exchanges 20xor for 100usd
    Given Iroha Peer is up
    And Iroha DEX module enabled
    And Peer has Domain with name exchange
    And Peer has Account with name buyer and domain exchange
    And Peer has Account with name seller and domain exchange
    And Peer has Asset Definition with name xor and domain exchange
    And Peer has Asset Definition with name usd and domain exchange
    And buyer Account in domain exchange has 100 amount of Asset with definition usd in domain exchange
    And seller Account in domain exchange has 20 amount of Asset with definition xor in domain exchange
    When buyer Account places Exchange Order 20xor for 100usd
    And seller Account places Exchange Order 100usd for 20 xor
    Then Iroha transfer 20 amount of Asset with definition xor in domain exchange from seller account in domain exchange to buyer account in domain exchange
    And Iroha transfer 100 amount of Asset with definition usd in domain exchange from account buyer in domain exchange to seller account in domain exchange

  Scenario: Buyer exchanges 1btc for 20eth across bridges
    Given Iroha Peer is up
    And Iroha Bridge module enabled
    And Iroha DEX module enabled
    And Peer has Domain with name exchange
    And Peer has Account with name buyer and domain exchange
    And Peer has Account with name seller and domain exchange
    And Peer has Asset Definition with name btc and domain exchange
    And Peer has Asset Definition with name eth and domain exchange
    And Peer has Bridge with name btc and owner btc_owner
    And Peer has Bridge with name eth and owner eth_owner
    And eth Brdige has buyer Account in domain exchange registered
    And btc Brdige has seller Account in domain exchange registered
    When buyer Account places Exchange Order 20xor for 100usd
    And seller Account places Exchange Order 100usd for 20 xor
    Then Iroha mint 1 amount of Asset with definition btc in domain exchange to seller Account in domain exchange using btc Bridge
    And Iroha mint 20 amount of Asset with definition eth in domain exchange to buyer Account in domain exchange using eth Bridge
    And Iroha transfer 1 amount of Asset with definition btc in domain exchange from seller account in domain exchange to buyer account in domain exchange
    And Iroha transfer 20 amount of Asset with definition eth in domain exchange from buyer account in domain exchange to seller account in domain exchange

  Scenario: Buyer exchanges 20xor for 100usd
    Given Iroha Peer is up
    And Iroha DEX module enabled
    And Peer has Domain with name exchange
    And Peer has Account with name liquidity_provider and domain exchange
    And Peer has Account with name seller and domain exchange
    And Peer has Asset Definition with name xor and domain exchange
    And Peer has Asset Definition with name btc and domain exchange
    And Peer has Asset Definition with name eth and domain exchange
    And liquidity_provider Account in domain exchange has 1 amount of Asset with definition btc in domain exchange
    And liquidity_provider Account in domain exchange has 20 amount of Asset with definition eth in domain exchange
    And liquidity_provider Account in domain exchange has 20 amount of Asset with definition xor in domain exchange
    And seller Account in domain exchange has 20 amount of Asset with definition eth in domain exchange
    When liquidity_provider Account registers Exchange Liquidity 20xor and 20eth and 1btc
    And seller Account places Exchange Order 20eth for 1btc
    Then Iroha transfer 1 amount of Asset with definition btc in domain exchange from seller account in domain exchange to liquidity_provider account in domain exchange
    And Iroha transfer 20 amount of Asset with definition eth in domain exchange from liquidity_provider account in domain exchange to seller account in domain exchange

Solution

DEX realated entities could be represented via Iroha model (Domains, Assets and their definitions), while complex sequences of actions could be implemented via Iroha Special Instructions + Triggers.

Decisions

  • Introduce a new module "DEX" with a dependency on "Bridge" module with additional set of Iroha Special Instructions and Queries and new Abstractions like Order (Combination of a Trigger and Asset with a predefined Asset Definition)
  • Implement Use cases
  • Implement Iroha Special Instructions DSL

Alternatives

  • Provide out-of-the-box entities and instructions for DEX - breaks modular approach giving to much information about private API to DEX module and making it mandatory for all peers once it introduced to the ledger
  • Make World State View public API - removes possibility to improve internal processes without breaking back compatibility

Concerns

  • Users without deep knowledge of Iroha model and instructions may fail to implement this

Assumptions

  • Iroha modules need to be optional Iroha features
  • Iroha Special Instructions DSL is separated from execution implementations

Risks

  • Given functionality will not cover all corner cases `[3;8]`
  • Performance may be insufficient for DEX `[2;9]`

Additional Information


5 Comments

  1. Nikita Puzankov

    Buyer should place an order to exchange 20ETH that it has for 1BTC from some seller. This order placed as trigger and assets in Iroha.

    Seller may fulfill the order by minting 1BTC and transferring them to the buyer which will trigger a minting of 20ETH by buyer and transferring them to seller.

  2. Nikita Puzankov

    From Egor Ivkov

    I think for a fully functional DEX we should also provide a scenario with liquidity pools, not only p2p scenario.

  3. Iurii Vinogradov

    Nikita, Sorry but DEX is not related to Iroha2 team. Thank you for the nice diagrams, but you cannot give tasks about DEX.  There is a lot of needed functionality in Iroha2 core to be completed and to work on it - that is what for you. We already working on DEX in our fork.

    When we will be ready to merge it with original iroha2 you will be able to discuss implementation. But before that time Iroha2 should meet requirements defined in previous RFCs.

    You can ask for a call with me if you have questions and want to contribute.

  4. Iurii Vinogradov

    Comment from our team.
    We'd like to focus on the case with the Liquidity pool because it is closer to what we are interested in. Focus on this case gives more chances to cover most questions, So it is better to iroha2 concepts used as an implementation for this case from Iroha2 team.

    Our team also updated list of questions which we'd like to see covered in implementation example. Some requirements may depend on realization, but in general, it can be applied in all or in most cases.

    Also, requirements from Iroha Additional Requirements should be taken into account during implementation of the example case.

    Vladislav updated Asset-store data reading & writing RFC to make it more general. I will copy the text here to have everything in one place. The reader should focus on extracting general requirements for implementation and security.
    * Asset-store data reading & writing

    Consider a case of assets exchange with the following algorithm:

    1. Wait for an Asset transfer from an Account
    2. Get information about exchanging assets (base asset ID, target asset ID, exchange rate).
    3. Check that these assets exist and can be exchanged.
    4. Calculate the target currency amount passing the retrieved exchange rate to the mathematical instruction as an argument
    5. Make a transfer passing the calculated amount of the target currency, recipient account ID (that is, the user who made the transfer in step 1), and the target asset ID as an argument in the AssetTransfer ISI.

    Requirements for this case are the following:

    1. To have the ability to pass exchange-related data like 'exchanging asset ID' and etc. to the algorithm (from asset-store, for example).
    2. To be able to manipulate the given data. For example, to calculate the exchanged currency amount.
    3. To store new data. For example, to store the calculated amount.
    4. To load saved data and pass it as an argument for an ISI. E.g. passing the calculated amount to the `TransferAsset` ISI.
    5. To have a guarantee that all the stored data is consistent, so the user would not have to verify all the data by itself.

    Additional requirements for the algorithm:

    1. It should be persisted, so no one could change the order of the instructions.
    2. It should be guaranteed that the creator of the algorithm is not permitted to call these instructions by itself.

    Another list of requirements from my side written in a little bit different way and in Broader context. Some of the requirements a the same with Vladislav's version, others extend it. 

    1. If we combine complex ISI using core ISI and we need to pass an argument from one ISI to another
    (both inside complex ISI), how we can do it? For example, if we should send results of Math ISI to other
    ISI or Transfer result nd amount to other ISI.
    2. If the token can be minted to everyone, like a Pool token, but only if the specified function was executed(say and liquidity) how we can control that everyone can mint that asset, but only executing specified ISI.
    3. How we can guarantee, that we can give access to change storage only for a specified set of complex instructions or triggers. It should be not possible to write a new complex ISI, that will change this storage.
    For example, if this is a log of liquidity changes in a pool and we want only ISI which adds liquidity and others which removes liquidity can add this data. But everyone can add and remove liquidity, so we cannot use the user's authority here.
    4. We need to guarantee that only specified ISI can change the storage and users cannot change it themself.
    For example the same case with log data as from #3.
    5. How will the information from the asset-stores get to any other ISI? Same as custom validation requirement from new requirements RFC. These checks might be needed when we add/get data from storage or when we pass arguments from one function to another.
    6. How we can control who can write new complex ISI(or triggers or anything else) to work with specified storage and who cannot. Because seems that everyone can create their own complex ISI on the client-side and make changes


  5. Nikita Puzankov