search

delvtech / hyperdrive-rs

Rust SDK for the Hyperdrive AMM.
https://docs.rs/crate/hyperdrive-math/latest
Apache License 2.0
3 stars 0 forks source link

DESIGN: Implement a high-level rust api #63

Open dpaiton opened 7 months ago

dpaiton commented 7 months ago

We would like to establish a high-level Rust API. I will update the current proposal here, people should feel free to comment to suggest changes. Reacts would be helpful for those who agree with any opinion expressed.

API state space

We have 8 hyperdrive actions:

  1. open long
  2. close long
  3. open short
  4. close short
  5. add liquidity
  6. remove liquidity
  7. redeem withdraw shares
  8. checkpoint

We have 3 hyperdrive units:

  1. base
  2. shares
  3. bonds

We have 2 hyperdrive entities:

  1. user (wallet)
    • generally communicates in "base" and "bonds"
  2. pool (reserves)
    • generally communicates in "shares" and "bonds"

We have 3 typical actions:

  1. preview a trade from a user's perspective
    • output is deltas to be applied to user's wallet
  2. preview a trade from pool's perspective
    • output is deltas to be applied to a pool's reserves
  3. "action"
    • actually performs the trade & updates state

Function signatures

We should establish a single convention for how to name functions.

Data structures

Output signatures could have a unified Result data structure that always contains every value (even if it's sometimes zero). e.g. result.pool.share_delta vs result.user.base_delta

dpaiton commented 7 months ago

Related to https://github.com/delvtech/hyperdrive-rs/issues/30 where we suggest a higher-level API for the calculate_targeted_* functions.

wakamex commented 7 months ago
I like returning deltas in an object that specifies entity and unit. For now I'm listing every item, but for a high level API it makes sense to group some of these (like combining curve and flat fees). Maybe not show fees at all? Entity Base Bonds Shares
user -100 104.95 -100
pool 99.9952 -104.955 99.9952
user_curve_fee 0.0475964 0 0.00475964
user_flat_fee 0 0 0
lp_curve_fee 0.0428367 0 0.0428367
lp_flat_fee 0 0 0
governance_fee 0.00475964 0 0.00475964
governance_flat 0 0 0

really explicit parsing of the return object makes it hard to footgun:

result = function(...)
result.user_or_pool.deltas_or_fees.unit ...

I like enabling user-facing functions to take either unit as input:

  1. open long with bonds as input predict_trade_test.py#L111
  2. open short with base as input predict_trade_test.py#L128

maybe instead of saying we have 3 action types, we could simplify to we have 2 action types (calc and execute) with the additional permutation of perspective being a choice (user or pool). this choice can be applied to any amount passed in: user_bond_amount or pool_bond_amount instead of bond_amount.

dpaiton commented 7 months ago

related to https://github.com/delvtech/hyperdrive-rs/issues/37

https://github.com/delvtech/hyperdrive-rs/issues/35