DESIGN: Implement a high-level rust api

[dpaiton]

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]

Related to #30 where we suggest a higher-level API for the calculate_targeted_* functions.

[wakamex]

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]

related to #37

#35