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>
This commit is contained in:
Kevin Davis 2023-03-06 17:32:52 -07:00 committed by GitHub
parent 2fe8890a63
commit 9e7686673e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 134 additions and 0 deletions

View File

@ -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.

16
x/liquid/spec/02_state.md Normal file
View File

@ -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.

View File

@ -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"
}
```

View File

@ -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}`|

View File

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