mirror of
https://github.com/0glabs/0g-chain.git
synced 2024-12-24 23:35:19 +00:00
update swap spec: add msgs, state, events (#966)
This commit is contained in:
Kevin Davis
GitHub
parent
911f9f59d6
commit
2bbdcbb365
@ -30,6 +30,33 @@ type AllowedPools []AllowedPool
|
||||
```go
|
||||
// GenesisState is the state that must be provided at genesis.
|
||||
type GenesisState struct {
|
||||
Params Params `json:"params" yaml:"params"`
|
||||
Params Params `json:"params" yaml:"params"`
|
||||
PoolRecords `json:"pool_records" yaml:"pool_records"`
|
||||
ShareRecords `json:"share_records" yaml:"share_records"`
|
||||
}
|
||||
|
||||
// PoolRecord represents the state of a liquidity pool
|
||||
// and is used to store the state of a denominated pool
|
||||
type PoolRecord struct {
|
||||
// primary key
|
||||
PoolID string `json:"pool_id" yaml:"pool_id"`
|
||||
ReservesA sdk.Coin `json:"reserves_a" yaml:"reserves_a"`
|
||||
ReservesB sdk.Coin `json:"reserves_b" yaml:"reserves_b"`
|
||||
TotalShares sdk.Int `json:"total_shares" yaml:"total_shares"`
|
||||
}
|
||||
|
||||
// PoolRecords is a slice of PoolRecord
|
||||
type PoolRecords []PoolRecord
|
||||
|
||||
// ShareRecord stores the shares owned for a depositor and pool
|
||||
type ShareRecord struct {
|
||||
// primary key
|
||||
Depositor sdk.AccAddress `json:"depositor" yaml:"depositor"`
|
||||
// secondary / sort key
|
||||
PoolID string `json:"pool_id" yaml:"pool_id"`
|
||||
SharesOwned sdk.Int `json:"shares_owned" yaml:"shares_owned"`
|
||||
}
|
||||
|
||||
// ShareRecords is a slice of ShareRecord
|
||||
type ShareRecords []ShareRecord
|
||||
```
|
||||
|
||||
@ -3,3 +3,63 @@ order: 3
|
||||
-->
|
||||
|
||||
# Messages
|
||||
|
||||
|
||||
MsgDeposit adds liquidity to a pool:
|
||||
|
||||
```go
|
||||
// MsgDeposit deposits liquidity into a pool
|
||||
type MsgDeposit struct {
|
||||
Depositor sdk.AccAddress `json:"depositor" yaml:"depositor"`
|
||||
TokenA sdk.Coin `json:"token_a" yaml:"token_a"`
|
||||
TokenB sdk.Coin `json:"token_b" yaml:"token_b"`
|
||||
Slippage sdk.Dec `json:"slippage" yaml:"slippage"`
|
||||
Deadline int64 `json:"deadline" yaml:"deadline"`
|
||||
}
|
||||
```
|
||||
|
||||
The first deposit to a pool results in a `PoolRecord` being created. For each deposit, a `ShareRecord` is created or updated, depending on if the depositor has an existing deposit. The deposited tokens are converted to shares. For the first deposit to a pool, shares are equal to the geometric mean of the deposited amount. For example, depositing 200 TokenA and 100 TokenB will create `sqrt(100 * 200) = 141` shares. For subsequent deposits, shares are issued equal to the current conversion between tokens and shares in that pool.
|
||||
|
||||
MsgWithdraw removes liquidity from a pool:
|
||||
|
||||
```go
|
||||
// MsgWithdraw deposits liquidity into a pool
|
||||
type MsgWithdraw struct {
|
||||
From sdk.AccAddress `json:"from" yaml:"from"`
|
||||
Shares sdk.Int `json:"shares" yaml:"shares"`
|
||||
MinTokenA sdk.Coin `json:"min_token_a" yaml:"min_token_a"`
|
||||
MinTokenB sdk.Coin `json:"min_token_b" yaml:"min_token_b"`
|
||||
Deadline int64 `json:"deadline" yaml:"deadline"`
|
||||
}
|
||||
```
|
||||
When withdrawing from a pool, the user specifies the amount of shares they want to withdraw, as well as the minimum amount of tokenA and tokenB that they must receive for the transaction to succeed. When withdrawing, the `ShareRecord` of the user will be decremented by the corresponding amount of shares, or deleted in the case that all liquidity has been withdrawn. If all shares of a pool have been withdrawn from a pool, the `PoolRecord` will be deleted.
|
||||
|
||||
MsgSwapExactForTokens trades an exact amount of input tokens for a variable amount of output tokens, with a specified maximum slippage tolerance.
|
||||
|
||||
```go
|
||||
// MsgSwapExactForTokens trades an exact coinA for coinB
|
||||
type MsgSwapExactForTokens struct {
|
||||
Requester sdk.AccAddress `json:"requester" yaml:"requester"`
|
||||
ExactTokenA sdk.Coin `json:"exact_token_a" yaml:"exact_token_a"`
|
||||
TokenB sdk.Coin `json:"token_b" yaml:"token_b"`
|
||||
Slippage sdk.Dec `json:"slippage" yaml:"slippage"`
|
||||
Deadline int64 `json:"deadline" yaml:"deadline"`
|
||||
}
|
||||
```
|
||||
|
||||
When trading exact inputs for variable outputs, the swap fee is removed from TokenA and added to the pool, then slippage is calculated based on the actual amount of TokenB received compared to the desired amount of TokenB. If the realized slippage of the trade is greater than the specified slippage tolerance, the transaction fails.
|
||||
|
||||
MsgSwapForExactTokens trades a variable amount of input tokens for an exact amount of output tokens, with a specified maximum slippage tolerance.
|
||||
|
||||
```go
|
||||
// MsgSwapForExactTokens trades coinA for an exact coinB
|
||||
type MsgSwapForExactTokens struct {
|
||||
Requester sdk.AccAddress `json:"requester" yaml:"requester"`
|
||||
TokenA sdk.Coin `json:"token_a" yaml:"token_a"`
|
||||
ExactTokenB sdk.Coin `json:"exact_token_b" yaml:"exact_token_b"`
|
||||
Slippage sdk.Dec `json:"slippage" yaml:"slippage"`
|
||||
Deadline int64 `json:"deadline" yaml:"deadline"`
|
||||
}
|
||||
```
|
||||
|
||||
When trading variable inputs for exact outputs, the fee swap fee is removed from TokenA and added to the pool, then slippage is calculated based on the actual amount of TokenA required to acquire the exact TokenB amount versus the desired TokenA required. If the realized slippage of the trade is greater than the specified slippage tolerance, the transaction fails.
|
||||
|
||||
@ -7,3 +7,53 @@ order: 4
|
||||
The swap module emits the following events:
|
||||
|
||||
## Handlers
|
||||
|
||||
### MsgDeposit
|
||||
|
||||
| Type | Attribute Key | Attribute Value |
|
||||
| ------------ | ------------- | --------------------- |
|
||||
| message | module | swap |
|
||||
| message | sender | `{sender address}` |
|
||||
| swap_deposit | pool_id | `{poolID}` |
|
||||
| swap_deposit | depositor | `{depositor address}` |
|
||||
| swap_deposit | amount | `{amount}` |
|
||||
| swap_deposit | shares | `{shares}` |
|
||||
|
||||
### MsgWithdraw
|
||||
|
||||
| Type | Attribute Key | Attribute Value |
|
||||
| ------------- | ------------- | --------------------- |
|
||||
| message | module | swap |
|
||||
| message | sender | `{sender address}` |
|
||||
| swap_withdraw | pool_id | `{poolID}` |
|
||||
| swap_withdraw | owner | `{owner address}` |
|
||||
| swap_withdraw | amount | `{amount}` |
|
||||
| swap_withdraw | shares | `{shares}` |
|
||||
|
||||
|
||||
### MsgSwapExactForTokens
|
||||
|
||||
| Type | Attribute Key | Attribute Value |
|
||||
| ------------- | ------------- | ------------------------ |
|
||||
| message | module | swap |
|
||||
| message | sender | `{sender address}` |
|
||||
| swap_trade | pool_id | `{poolID}` |
|
||||
| swap_trade | requester | `{requester address}` |
|
||||
| swap_trade | swap_input | `{input amount}` |
|
||||
| swap_trade | swap_output | `{output amount}` |
|
||||
| swap_trade | fee_paid | `{fee amount}` |
|
||||
| swap_trade | exact | `{exact trade direction}`|
|
||||
|
||||
|
||||
### MsgSwapForExactTokens
|
||||
|
||||
| Type | Attribute Key | Attribute Value |
|
||||
| ------------- | ------------- | ------------------------ |
|
||||
| message | module | swap |
|
||||
| message | sender | `{sender address}` |
|
||||
| swap_trade | pool_id | `{poolID}` |
|
||||
| swap_trade | requester | `{requester address}` |
|
||||
| swap_trade | swap_input | `{input amount}` |
|
||||
| swap_trade | swap_output | `{output amount}` |
|
||||
| swap_trade | fee_paid | `{fee amount}` |
|
||||
| swap_trade | exact | `{exact trade direction}`|
|
||||
|
||||
Loading…
Reference in New Issue
Block a user