github.com/Finschia/finschia-sdk@v0.49.1/x/fswap/spec/01_concepts.md (about)

     1  <!--
     2  order: 1
     3  -->
     4  
     5  # Concepts
     6  
     7  ## Swap
     8  
     9  
    10  The `x/fswap` module defines a `Swap` type in which a coin is allowed to be swapped into another coin on the chain.
    11  You could find detailed information in the [Protobuf reference](../../../proto/lbm/fswap/v1/fswap.proto#L9-L16) 
    12  
    13  ```go
    14  type Swap struct {
    15    FromDenom             string
    16    ToDenom               string
    17    AmountCapForToDenom   sdk.Int
    18    SwapRate              sdk.Dec
    19  }
    20  ```
    21  
    22  Anyone could use one of the following two transcations to swap `FromDedenom` to `ToDenom`.
    23  1. `simd tx fswap swap [from] [from_coin_amount] [to_denom]`
    24      - this transcation could swap a specified amount of `from_denom` via [`MsgSwap`](../../../proto/lbm/fswap/v1/tx.proto#L17-L24)
    25  2. `simd tx fswap swap-all [from_address] [from_denom] [to_denom]`
    26      - this transcation could swap all of `from_denom` under `from_address` via [`MsgSwapAll`](../../../proto/lbm/fswap/v1/tx.proto#L28-L33)
    27  
    28  When the swap is triggered, the following event will occur:
    29  1. `from_denom` will be sent from `from_address` to `x/fswap` module
    30  2. `x/fswap` module will burn `from_denom`
    31  3. `x/fswap` module will mint `to_denom` as amount as `from_denom * swapRate`
    32  4. these `to_denom` will sent to `from_address`
    33  5. `EventSwapCoins` will be emitted
    34  
    35  ## Config
    36  
    37  The `x/fswap` module defines a `Config` type for managing the maximum number of Swaps allowed on chain through `MaxSwaps`. Additionally, `UpdateAllowed` specifies whether `Swap` can be modified.
    38  
    39  ```go
    40  type Config struct {
    41  	MaxSwaps      int
    42  	UpdateAllowed bool
    43  }
    44  ```
    45  
    46  ## MsgSetSwap
    47  
    48  Other modules can include `MsgSetSwap` in their proposals to set `Swap`. If the proposal passes, the `Swap` can be used on chain.
    49  
    50  `ToDenomMetadata` is [`Metadata`](../../bank/types/bank.pb.go#L325) in `x/bank` module, and it MUST meet these [limitations](../../bank/types/metadata.go#L11). 
    51  In addition, `ToDenomMetadata` should also meet the following two additional constraints by x/swap.
    52  1. `Base` should be consistent with `ToDenom` in `Swap` ([valiation](../types/msgs.go#L121-L123))
    53  2. It cannot override existing denom metadata ([valiation](../keeper/keeper.go#L169))
    54  
    55  The following example illustrates the use of `MsgSetSwap` within the `x/foundation` module. `Authority` is a spec in the `x/foundation` module, and you can get more information [here](../../foundation/README.md#L54).
    56  
    57  ```go
    58  type MsgSetSwap struct {
    59      Authority           string
    60      Swap                Swap
    61      ToDenomMetadata     bank.Metadata
    62  }
    63  ```