Place market/limit order with metadata.

[Rajwanshi1]

trafficstars

Description

Proposed change: Add new struct MatchedOrderMetadata<BaseAsset, QuoteAsset> & return from place order functions to provide on-chain info about orders being matched & parties involved in trade.

Use cases this change can enable:

1. Third party protocols, using deepbook as liquidity layer, can add custom asserts & policies on matched orders in same txn(revert if matched orders doesn't fullfill custom policies & checks). This approach provides a hook for protocols to add custom functions over matched orders in their respective packages with no changes in deepbook.
2. Deepbook currently doesn't support slippage/min_buy amount checks. Returning matched orders from place order can allow protocols like KriyaDEX to provide slippage control in Pro-trading. (revert PTB when matched order price > allowed slippage).
3. KriyaDEX is building a perp-dex using deepbook as matching engine(in audit). For all such margining protocols dealing with leverage, it's essential to have on-chain information about matched orders(parties involved, price & size) to deterministically settle trades with protocol's clearing house.

Scenario(for perp-dex use case):

1. Attacker configures 2 wallets (w1/w2) in BTC market.
2. w1 places 10x short order at a very low price (say $100/BTC).
3. w2 places 10x long order to match with w1 in the same PTB.
4. After order matching, w2 is instantly at a high profit(mark price being $35k for BTC) while w1 is in a huge loss & banckrupt.
5. w2 waits until there is some liquidity in deepbook & closes it's position with someone else while realising the profits & withdraws.
6. w1 is instantly bankrupt with a loss to insurance fund.
7. This induces bad debt to the system & margin protocol's insurance fund can be drained.

How returning matched orders prevents this attack? Third party margin protocols can enforce checks on the matched orders price. If matched order price is deviated by say x%, txns can be reverted which will prevent order matching at highly deviated price(wrt mark_price) in low liquidity environments. This scenario is analogous to slippage in spot deepbook pools.

Changes & Upgradeability:

1. private funcs match_ask/match_bid now also returns vector<OrderFilled> - back compatible
2. added new public funcs with metadata - place_market_order_with_metadata, place_limit_order_with_metadata, swap_exact_base_for_quote_with_metadata, swap_exact_quote_for_base_with_metadata. - back compatible

Test Plan

How did you test the new or updated feature? Added unit tests for all the changes.

---

If your changes are not user-facing and not a breaking change, you can skip the following section. Otherwise, please indicate what changed, and then add to the Release Notes section as highlighted during the release process.

Type of Change (Check all that apply)

• [ ] protocol change
• [ ] user-visible impact
• [ ] breaking change for a client SDKs
• [ ] breaking change for FNs (FN binary must upgrade)
• [ ] breaking change for validators or node operators (must upgrade binaries)
• [ ] breaking change for on-chain data layout
• [ ] necessitate either a data wipe or data migration

Release notes

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
mysten-ui	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 12, 2024 6:39am
sui-typescript-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 12, 2024 6:39am

3 Ignored Deployments

Name	Status	Preview	Comments	Updated (UTC)
explorer	⬜️ Ignored (Inspect)	Visit Preview		Jan 12, 2024 6:39am
multisig-toolkit	⬜️ Ignored (Inspect)	Visit Preview		Jan 12, 2024 6:39am
sui-kiosk	⬜️ Ignored (Inspect)	Visit Preview		Jan 12, 2024 6:39am

[dariorussi]

I see that some of the concern/questions I had are addressed in the next commit!

[vercel[bot]]

@Rajwanshi is attempting to deploy a commit to the Sui Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[Rajwanshi1]

Hi @dariorussi , let me know if these changes are good to go or something is required from our end.

[dariorussi]

closing this PR as https://github.com/MystenLabs/sui/pull/15275 contains all changes and has been merged