From 7bd6c8244377257423d83ee0fbf39c56871befc5 Mon Sep 17 00:00:00 2001 From: Ki <85928898+170210@users.noreply.github.com> Date: Mon, 24 Jun 2024 16:43:30 +0900 Subject: [PATCH] docs: correct spec docs of fswap module (#1419) * docs: correct spec docs of fswap module Signed-off-by: 170210 * chore: correct comment of storeKey Signed-off-by: 170210 * chore: update CHANGLOG.md Signed-off-by: 170210 * fix: fix for comment Signed-off-by: 170210 * chore: fix format Signed-off-by: 170210 * fix: fix for comment Signed-off-by: 170210 * fixup: fix for comment Signed-off-by: 170210 * fixup: fix for comment Signed-off-by: 170210 * fixup: fix for comment Signed-off-by: 170210 * fixup: fix for comment Signed-off-by: 170210 --------- Signed-off-by: 170210 --- CHANGELOG.md | 1 + x/fswap/keeper/keys.go | 2 +- x/fswap/spec/01_concepts.md | 63 +++++++++++++++++++++++++++++++++++++ x/fswap/spec/02_state.md | 21 +++++++++++++ x/fswap/spec/03_events.md | 8 +++++ x/fswap/spec/README.md | 16 ---------- 6 files changed, 94 insertions(+), 17 deletions(-) create mode 100644 x/fswap/spec/01_concepts.md create mode 100644 x/fswap/spec/02_state.md create mode 100644 x/fswap/spec/03_events.md delete mode 100644 x/fswap/spec/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 697867f8bb..728a192f4b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -122,3 +122,4 @@ Ref: https://keepachangelog.com/en/1.0.0/ * (docs) [\#1083](https://github.com/Finschia/finschia-sdk/pull/1083) Add detailed explanation about default events * (x/token,collection) [#1201](https://github.com/Finschia/finschia-sdk/pull/1201) Deprecate legacy features on x/token,collection * (build) [\#1393](https://github.com/Finschia/finschia-sdk/pull/1393) add current directory as suffix for docker container +* (docs) [\#1419](https://github.com/Finschia/finschia-sdk/pull/1419) correct spec docs of fswap module diff --git a/x/fswap/keeper/keys.go b/x/fswap/keeper/keys.go index e9a4652926..6bdedffd8d 100644 --- a/x/fswap/keeper/keys.go +++ b/x/fswap/keeper/keys.go @@ -6,7 +6,7 @@ var ( swappedKeyPrefix = []byte{0x03} ) -// swapKey key(prefix + fromDenom + toDenom) +// swapKey key(prefix + (lengthPrefixed+)fromDenom + (lengthPrefixed+)toDenom) func swapKey(fromDenom, toDenom string) []byte { denoms := combineDenoms(fromDenom, toDenom) return append(swapPrefix, denoms...) diff --git a/x/fswap/spec/01_concepts.md b/x/fswap/spec/01_concepts.md new file mode 100644 index 0000000000..8a1076f7cd --- /dev/null +++ b/x/fswap/spec/01_concepts.md @@ -0,0 +1,63 @@ + + +# Concepts + +## Swap + + +The `x/fswap` module defines a `Swap` type in which a coin is allowed to be swapped into another coin on the chain. +You could find detailed information in the [Protobuf reference](../../../proto/lbm/fswap/v1/fswap.proto#L9-L16) + +```go +type Swap struct { + FromDenom string + ToDenom string + AmountCapForToDenom sdk.Int + SwapRate sdk.Dec +} +``` + +Anyone could use one of the following two transcations to swap `FromDedenom` to `ToDenom`. +1. `simd tx fswap swap [from] [from_coin_amount] [to_denom]` + - this transcation could swap a specified amount of `from_denom` via [`MsgSwap`](../../../proto/lbm/fswap/v1/tx.proto#L17-L24) +2. `simd tx fswap swap-all [from_address] [from_denom] [to_denom]` + - this transcation could swap all of `from_denom` under `from_address` via [`MsgSwapAll`](../../../proto/lbm/fswap/v1/tx.proto#L28-L33) + +When the swap is triggered, the following event will occur: +1. `from_denom` will be sent from `from_address` to `x/fswap` module +2. `x/fswap` module will burn `from_denom` +3. `x/fswap` module will mint `to_denom` as amount as `from_denom * swapRate` +4. these `to_denom` will sent to `from_address` +5. `EventSwapCoins` will be emitted + +## Config + +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. + +```go +type Config struct { + MaxSwaps int + UpdateAllowed bool +} +``` + +## MsgSetSwap + +Other modules can include `MsgSetSwap` in their proposals to set `Swap`. If the proposal passes, the `Swap` can be used on chain. + +`ToDenomMetadata` is [`Metadata`](../../bank/types/bank.pb.go#L325) in `x/bank` module, and it MUST meet these [limitations](../../bank/types/metadata.go#L11). +In addition, `ToDenomMetadata` should also meet the following two additional constraints by x/swap. +1. `Base` should be consistent with `ToDenom` in `Swap` ([valiation](../types/msgs.go#L121-L123)) +2. It cannot override existing denom metadata ([valiation](../keeper/keeper.go#L169)) + +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). + +```go +type MsgSetSwap struct { + Authority string + Swap Swap + ToDenomMetadata bank.Metadata +} +``` diff --git a/x/fswap/spec/02_state.md b/x/fswap/spec/02_state.md new file mode 100644 index 0000000000..12d44e3faf --- /dev/null +++ b/x/fswap/spec/02_state.md @@ -0,0 +1,21 @@ + + +# State + +The `x/fswap` module keeps state of three primary objects, Swap, SwapStats and Swapped. + +## Swap + +- Swap: `0x01 + (lengthPrefixed+)fromDenom + (lengthPrefixed+)toDenom` + + +## SwapStats + +- SwapStats: `0x02` + +## Swapped + +- Swapped: `0x03 + (lengthPrefixed+)fromDenom + (lengthPrefixed+)toDenom` + diff --git a/x/fswap/spec/03_events.md b/x/fswap/spec/03_events.md new file mode 100644 index 0000000000..73ae3f6047 --- /dev/null +++ b/x/fswap/spec/03_events.md @@ -0,0 +1,8 @@ + + +# Events + +The fswap module emits proto events defined in [the Protobuf reference](../../../docs/core/proto-docs.md#lbm/fswap/v1/event.proto). +`MsgSetSwap` is emitted through the `x/foundation` module. \ No newline at end of file diff --git a/x/fswap/spec/README.md b/x/fswap/spec/README.md deleted file mode 100644 index ee7423f27c..0000000000 --- a/x/fswap/spec/README.md +++ /dev/null @@ -1,16 +0,0 @@ -``` -make build -make install -zsh init_node.sh sim 1 -``` - -open the `./.simapp/simapp0/config/genesis.json` change the value of `voting_params.voting_period` to `10s` -``` -simd start --home ~/.simapp/simapp0 -simd tx gov submit-proposal swap-init --title "test" --description "test" --from link146asaycmtydq45kxc8evntqfgepagygelel00h --from-denom "cony" --to-denom "PDT" --swap-rate 123 --amount-limit 1000 --deposit 10000000stake --chain-id=sim --keyring-backend=test --gas-prices 1000stake --gas 10000000 --gas-adjustment 1.5 --home ~/.simapp/simapp0 -b block -y -simd tx gov vote 1 yes --from link146asaycmtydq45kxc8evntqfgepagygelel00h --chain-id=sim --keyring-backend=test --home ~/.simapp/simapp0 -b block -y -``` - -``` -simd query fswap swapped --chain-id=sim -``` \ No newline at end of file