From 9e7686673e36fde0f88d88c0cca8488f62b807d0 Mon Sep 17 00:00:00 2001 From: Kevin Davis Date: Mon, 6 Mar 2023 17:32:52 -0700 Subject: [PATCH] feat: add liquid module spec (#1484) * feat: add liquid module spec * add codeblock languages for syntax highlighting --------- Co-authored-by: Robert Pirtle --- x/liquid/spec/01_concepts.md | 7 ++++ x/liquid/spec/02_state.md | 16 ++++++++ x/liquid/spec/03_messages.md | 79 ++++++++++++++++++++++++++++++++++++ x/liquid/spec/04_events.md | 25 ++++++++++++ x/liquid/spec/05_params.md | 7 ++++ 5 files changed, 134 insertions(+) create mode 100644 x/liquid/spec/01_concepts.md create mode 100644 x/liquid/spec/02_state.md create mode 100644 x/liquid/spec/03_messages.md create mode 100644 x/liquid/spec/04_events.md create mode 100644 x/liquid/spec/05_params.md diff --git a/x/liquid/spec/01_concepts.md b/x/liquid/spec/01_concepts.md new file mode 100644 index 00000000..e6798dc6 --- /dev/null +++ b/x/liquid/spec/01_concepts.md @@ -0,0 +1,7 @@ + + +# Concepts + +This module is responsible for the minting and burning of liquid staking receipt tokens, collectively referred to as `bkava`. Delegated kava can be converted to delegator-specific `bkava`. Ie, 100 KAVA delegated to validator `kavavaloper123` can be converted to 100 `bkava-kavavaloper123`. Similarly, 100 `bkava-kavavaloper123` can be converted back to a delegation of 100 KAVA to `kavavaloper123`. In this design, all validators can permissionlessly participate in liquid staking while users retain the delegator specific slashing risk and voting rights of their original validator. Note that because each `bkava` denom is validator specific, this module does not specify a fungibility mechanism for `bkava` denoms. \ No newline at end of file diff --git a/x/liquid/spec/02_state.md b/x/liquid/spec/02_state.md new file mode 100644 index 00000000..cff1c133 --- /dev/null +++ b/x/liquid/spec/02_state.md @@ -0,0 +1,16 @@ + + +# State + +## Module Account +The liquid module defines a module account with name `liquid` that has `Minter` and `Burner` module account permissions. The associated bech32 account address is `kava1gggszchqvw2l65my03mak6q5qfhz9cn2g0px29`. + +## Genesis state + +The liquid module does not require any module specific genesis state. + +## Store + +The liquid module does not store any module specific data. All `bkava` token receipts are minted directly to the delegators account, and the delegation object is transferred to the liquid module account. \ No newline at end of file diff --git a/x/liquid/spec/03_messages.md b/x/liquid/spec/03_messages.md new file mode 100644 index 00000000..e12b68c0 --- /dev/null +++ b/x/liquid/spec/03_messages.md @@ -0,0 +1,79 @@ + + +# Messages + +`bkava` is minted using `MsgMintDerivative`. + + +```go +// MsgMintDerivative defines the Msg/MintDerivative request type. +type MsgMintDerivative struct { + // sender is the owner of the delegation to be converted + Sender string `protobuf:"bytes,1,opt,name=sender,proto3" json:"sender,omitempty"` + // validator is the validator of the delegation to be converted + Validator string `protobuf:"bytes,2,opt,name=validator,proto3" json:"validator,omitempty"` + // amount is the quantity of staked assets to be converted + Amount types.Coin `protobuf:"bytes,3,opt,name=amount,proto3" json:"amount"` +} +``` + +### Actions + +* converts an existing delegation into bkava tokens +* delegation is transferred from the sender to a module account +* validator specific bkava are minted and sent to the sender + +### Example: + +```jsonc +{ + // user who owns the delegation + "sender": "kava10wlnqzyss4accfqmyxwx5jy5x9nfkwh6qm7n4t", + // validator the user has delegated to + "validator": "kavavaloper1ypjp0m04pyp73hwgtc0dgkx0e9rrydeckewa42", + // amount of staked ukava to be converted into bkava + "amount": { + "amount": "1000000000", + "denom": "ukava" + } +} +``` + +`bkava` can be burned using `MsgBurnDerivative`. + +```go +// MsgBurnDerivative defines the Msg/BurnDerivative request type. +type MsgBurnDerivative struct { + // sender is the owner of the derivatives to be converted + Sender string `protobuf:"bytes,1,opt,name=sender,proto3" json:"sender,omitempty"` + // validator is the validator of the derivatives to be converted + Validator string `protobuf:"bytes,2,opt,name=validator,proto3" json:"validator,omitempty"` + // amount is the quantity of derivatives to be converted + Amount types.Coin `protobuf:"bytes,3,opt,name=amount,proto3" json:"amount"` +} +``` + +### Actions + +* converts bkava tokens into a delegation +* bkava is burned +* a delegation equal to number of bkava is transferred to user + + +### Example + +```jsonc +{ + // user who owns the bkava + "sender": "kava10wlnqzyss4accfqmyxwx5jy5x9nfkwh6qm7n4t", + // the amount of bkava the user wants to convert back into normal staked kava + "amount": { + "amount": "1234000000", + "denom": "bkava-kavavaloper1ypjp0m04pyp73hwgtc0dgkx0e9rrydeckewa42" + }, + // the validator behind the bkava, this address must match the one embedded in the bkava denom above + "validator": "kavavaloper1ypjp0m04pyp73hwgtc0dgkx0e9rrydeckewa42" +} +``` diff --git a/x/liquid/spec/04_events.md b/x/liquid/spec/04_events.md new file mode 100644 index 00000000..07d7a086 --- /dev/null +++ b/x/liquid/spec/04_events.md @@ -0,0 +1,25 @@ + + +# Events + +The `x/liquid` module emits the following events: + +## MsgMintDerivative + +| Type | Attribute Key | Attribute Value | +| --------------- | ----------------- | ------------------ | +| mint_derivative | delegator | `{delegator address}` | +| mint_derivative | validator | `{validator address}` | +| mint_derivative | amount | `{amount}` | +| mint_derivative | shares_transferred| `{shares transferred}`| + +## MsgBurnDerivative + +| Type | Attribute Key | Attribute Value | +| --------------- | ----------------- | ------------------ | +| burn_derivative | delegator | `{delegator address}` | +| burn_derivative | validator | `{validator address}` | +| burn_derivative | amount | `{amount}` | +| burn_derivative | shares_transferred| `{shares transferred}`| \ No newline at end of file diff --git a/x/liquid/spec/05_params.md b/x/liquid/spec/05_params.md new file mode 100644 index 00000000..5df5c058 --- /dev/null +++ b/x/liquid/spec/05_params.md @@ -0,0 +1,7 @@ + + +# Parameters + +The liquid module has no parameters. \ No newline at end of file