Set of OOB ISIs

Owned by Nikita Puzankov
Last updated: Aug 16, 2021 by Egor Ivkov
2 min read
Status

DECIDED

Stakeholders
武宮誠 Yuriy Vinogradov Egor Ivkov 
Outcome
Due date
Owner
Nikita Puzankov 

Background

We should declare the initial set of OOB (Out-Of-the-Box) Iroha Special Instructions for Hyperledger Iroha 2.0.0 release.

Problem

Iroha whitepaper, current implementation and users' expectations are different in terms of out-of-the-box Iroha Special Instructions set.

To have some expected result in Iroha 2.0.0 we need to define the stable set of these instructions. Part of this work was made in Iroha Special Instructions DSL, here we will focus on instructions set, not how they work and how to use them.

Solution 

The good solution will be to define taxonomy and ontology on some full set of Iroha Special Instructions, had a strong agreement on categories and naming, with an ability to modify resulting set with small changes.

Use this agreement to update the White Paper, build current implementation and align users' expectations. 

Decisions

Split out-of-the-box instructions into the following categories:

  • Domain related
    • Register/Unregister<Identifiable>
    • Mint/Burn<Id, Value>
    • Transfer<Id, Value, Id>
  • Math
    • Integer
      • Add/Substract<EvaluatesTo<u32>, EvaluatesTo<u32>>
      • Multiply/Divide<EvaluatesTo<u32>, EvaluatesTo<u32>>
      • RaiseTo<EvaluatesTo<u32>, EvaluatesTo<u32>>
      • Mod<EvaluatesTo<u32>, EvaluatesTo<u32>>
    • Comparison:
      • Equate<Value, Value>
      • Greater/Less<EvaluatesTo<u32>, EvaluatesTo<u32>>
    • Bool
      • Not<EvaluatesTo<bool>>
      • And/Or<EvaluatesTo<bool>, EvaluatesTo<bool>>
  • Compositions
    • Sequence<Vec<Instruction>>
    • Pair<Instruction, Instruction>
    • If<EvaluatesTo<bool>, Instruction, Option<Instruction>>
  • Vectors
    • Contains<EvaluatesTo<Vec<Value>>, EvaluatesTo<Value>>
    • ContainsAny/ContainsAll<EvaluatesTo<Vec<Value>>, EvaluatesTo<Vec<Value>>>
  • Variables
    • Where<Value, BTreeMap<String, Value>>
    • ContextValue<String>
  • Queries
    • Execute<Query>
  • Misc
    • Fail<String>

Provide a set of possible domain-related instructions:

  • Register/Unregister
    • Register or unregister Domain in Peer
    • Register or unregister Account in Domain
    • Register or unregister Asset Definition in Domain
    • Register or unregister Peer Id in Peer 
    • Register or unregister Signatory in Account
  • Mint
    • Mint or burn value to or from an Asset 
  • Fees
    • Register or unregister TransactionFee (e.g., fixed, percentage, DEX-swapped)


Provide a set of tools for DeFi:

  • Register DEX
    • Register or unregister DEX (DEXManager) in Domain
  • Register Liquidity Source
    • Register or unregister XYK Pool in DEX
    • Register or unregister Order Book in DEX
  • Set liquidity fees
    • Register or unregister LiquidityFee (e.g., buy back and burn, pool share, etc.)


Provide a set of tools for Digital Identity (https://ieeexplore.ieee.org/abstract/document/8377927/):

Alternatives 

  • Do not have categories and generic instructions using a plain set of instructions like "AddDomain, RegisterAccount" - as cons we can point out naming and extensibility problems
  • Do not have granularity and differences between register, mint, add - as cons we can point out different business-related meanings for similar actions and to a wide set of options in one bucket

Concerns 

  • A too big or too small set of out-of-the-box instructions can be hard to maintain or not sufficient for users needs
  • Iroha 1 users can struggle from the new naming

Assumptions - document any assumption that you made

  • We did not make a final decision about "Iroha Modules" related instructions (DEX, Bridge, Permissions, etc.) and their inclusion into out-of-the-box set yet

Risks 

  • Set will be incomplete from the users' perspective `[5;2]`
  • We missed some categories `[2;7]`

Additional Information