feat: add liquid module spec (#1484)

* feat: add liquid module spec

* add codeblock languages for syntax highlighting

---------

Co-authored-by: Robert Pirtle <astropirtle@gmail.com>

x/liquid/spec/01_concepts.md

@@ -0,0 +1,7 @@
+<!--
+order: 1
+-->
+
+# 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. 

x/liquid/spec/02_state.md

@@ -0,0 +1,16 @@
+<!--
+order: 2
+-->
+
+# 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. 

x/liquid/spec/03_messages.md

@@ -0,0 +1,79 @@
+<!--
+order: 3
+-->
+
+# 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"
+}
+```

x/liquid/spec/04_events.md

@@ -0,0 +1,25 @@
+<!--
+order: 4
+-->
+
+# 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}`|

x/liquid/spec/05_params.md

@@ -0,0 +1,7 @@
+<!--
+order: 5
+-->
+
+# Parameters
+
+The liquid module has no parameters.