docs: add stablestake module specs (#554)

x/stablestake/spec/01_concepts.md

@@ -0,0 +1,7 @@
+<!--
+order: 1
+-->
+
+# Concepts
+
+The `stablestake` module in the Elys Network extends the basic staking capabilities by providing functionalities for borrowing and lending, managing interest rates, and handling debt effectively. This module aims to ensure a stable and efficient staking environment within the network.

x/stablestake/spec/02_usage.md

@@ -0,0 +1,31 @@
+<!--
+order: 2
+-->
+
+# Usage
+
+## Commands
+
+### Querying Parameters
+
+```bash
+elysd query stablestake params
+```
+
+### Querying Borrow Ratio
+
+```bash
+elysd query stablestake borrow-ratio
+```
+
+### Bonding Tokens
+
+```bash
+elysd tx stablestake bond 1000000000000uusdc --from=treasury --keyring-backend=test --chain-id=elystestnet-1 --yes --gas=1000000
+```
+
+### Unbonding Tokens
+
+```bash
+elysd tx stablestake unbond 500000000000uusdc --from=treasury --keyring-backend=test --chain-id=elystestnet-1 --yes --gas=1000000
+```

x/stablestake/spec/03_keeper.md

@@ -0,0 +1,82 @@
+<!--
+order: 3
+-->
+
+# Keeper
+
+## Interest Rate Management
+
+The `stablestake` module's keeper handles the computation and updating of interest rates, ensuring they are adjusted based on the network's parameters and conditions.
+
+### BeginBlocker
+
+The `BeginBlocker` function is invoked at the beginning of each block. It checks if an epoch has passed, updates interest rates, and recalculates the stacked interest for all debts.
+
+```go
+func (k Keeper) BeginBlocker(ctx sdk.Context) {
+    // check if epoch has passed then execute
+    epochLength := k.GetEpochLength(ctx)
+    epochPosition := k.GetEpochPosition(ctx, epochLength)
+
+    if epochPosition == 0 { // if epoch has passed
+        params := k.GetParams(ctx)
+        rate := k.InterestRateComputation(ctx)
+        params.InterestRate = rate
+        k.SetParams(ctx, params)
+
+        debts := k.AllDebts(ctx)
+        for _, debt := range debts {
+            k.UpdateInterestStacked(ctx, debt)
+        }
+    }
+}
+```
+
+### Borrowing and Repaying
+
+The `Borrow` function allows a user to borrow tokens, while the `Repay` function allows a user to repay borrowed tokens, including any accrued interest.
+
+```go
+func (k Keeper) Borrow(ctx sdk.Context, addr sdk.AccAddress, amount sdk.Coin) error {
+    depositDenom := k.GetDepositDenom(ctx)
+    if depositDenom != amount.Denom {
+        return types.ErrInvalidBorrowDenom
+    }
+    debt := k.UpdateInterestStackedByAddress(ctx, addr)
+    debt.Borrowed = debt.Borrowed.Add(amount.Amount)
+    k.SetDebt(ctx, debt)
+    return k.bk.SendCoinsFromModuleToAccount(ctx, types.ModuleName, addr, sdk.Coins{amount})
+}
+
+func (k Keeper) Repay(ctx sdk.Context, addr sdk.AccAddress, amount sdk.Coin) error {
+    depositDenom := k.GetDepositDenom(ctx)
+    if depositDenom != amount.Denom {
+        return types.ErrInvalidBorrowDenom
+    }
+
+    err := k.bk.SendCoinsFromAccountToModule(ctx, addr, types.ModuleName, sdk.Coins{amount})
+    if err != nil {
+        return err
+    }
+
+    // calculate latest interest stacked
+    debt := k.UpdateInterestStackedByAddress(ctx, addr)
+
+    // repay interest
+    interestPayAmount := debt.InterestStacked.Sub(debt.InterestPaid)
+    if interestPayAmount.GT(amount.Amount) {
+        interestPayAmount = amount.Amount
+    }
+
+    // repay borrowed
+    repayAmount := amount.Amount.Sub(interestPayAmount)
+    debt.Borrowed = debt.Borrowed.Sub(repayAmount)
+
+    if !debt.Borrowed.IsPositive() {
+        k.DeleteDebt(ctx, debt)
+    } else {
+        k.SetDebt(ctx, debt)
+    }
+    return nil
+}
+```

x/stablestake/spec/04_protobuf_definitions.md

@@ -0,0 +1,197 @@
+<!--
+order: 4
+-->
+
+# Protobuf Definitions
+
+## Types
+
+### Debt
+
+The `Debt` message tracks the borrowed amount, interest paid, and interest stacked for a given address, along with timestamps for borrowing and last interest calculation.
+
+```proto
+message Debt {
+  string address = 1;
+  string borrowed = 2 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
+    (gogoproto.nullable) = false
+  ];
+  string interest_paid = 3 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
+    (gogoproto.nullable) = false
+  ];
+  string interest_stacked = 4 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
+    (gogoproto.nullable) = false
+  ];
+  uint64 borrow_time = 5;
+  uint64 last_interest_calc_time = 6;
+}
+```
+
+### Params
+
+The `Params` message defines the parameters for the `stablestake` module, including deposit denomination, redemption rate, epoch length, interest rates, and total value.
+
+```proto
+message Params {
+  option (gogoproto.goproto_stringer) = false;
+
+  string deposit_denom = 1;
+  string redemption_rate = 2 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
+    (gogoproto.nullable) = false
+  ];
+  int64 epoch_length = 3;
+  string interest_rate = 4 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
+    (gogoproto.nullable) = false
+  ];
+  string interest_rate_max = 5 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
+    (gogoproto.nullable) = false
+  ];
+  string interest_rate_min = 6 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
+    (gogoproto.nullable) = false
+  ];
+  string interest_rate_increase = 7 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
+    (gogoproto.nullable) = false
+  ];
+  string interest_rate_decrease = 8 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
+    (gogoproto.nullable) = false
+  ];
+  string health_gain_factor = 9 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
+    (gogoproto.nullable) = false
+  ];
+  string total_value = 10 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
+    (gogoproto.nullable) = false
+  ];
+}
+```
+
+### GenesisState
+
+The `GenesisState` message defines the initial state of the `stablestake` module at genesis.
+
+```proto
+message GenesisState {
+  Params params = 1 [(gogoproto.nullable) = false];
+}
+```
+
+## Messages
+
+### Msg Service
+
+The `Msg` service defines the transactions available in the `stablestake` module.
+
+```proto
+service Msg {
+  rpc Bond(MsgBond) returns (MsgBondResponse);
+  rpc Unbond(MsgUnbond) returns (MsgUnbondResponse);
+}
+```
+
+#### MsgBond
+
+This message allows a user to bond a specified amount of tokens.
+
+```proto
+message MsgBond {
+  string creator = 1;
+  string amount = 2 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
+    (gogoproto.nullable) = false
+  ];
+}
+
+message MsgBondResponse {}
+```
+
+#### MsgUnbond
+
+This message allows a user to unbond a specified amount of tokens.
+
+```proto
+message MsgUnbond {
+  string creator = 1;
+  string amount = 2 [
+    (gogoproto.customtype) = "github.com/cosmos
+
+/cosmos-sdk/types.Int",
+    (gogoproto.nullable) = false
+  ];
+}
+
+message MsgUnbondResponse {}
+```
+
+## Queries
+
+### Query Service
+
+The `Query` service defines the gRPC querier service for the `stablestake` module.
+
+```proto
+service Query {
+  rpc Params(QueryParamsRequest) returns (QueryParamsResponse) {
+    option (google.api.http).get = "/elys-network/elys/stablestake/params";
+  }
+  rpc BorrowRatio(QueryBorrowRatioRequest) returns (QueryBorrowRatioResponse) {
+    option (google.api.http).get = "/elys-network/elys/stablestake/borrow-ratio";
+  }
+}
+```
+
+#### QueryParamsRequest
+
+This message requests the parameters of the `stablestake` module.
+
+```proto
+message QueryParamsRequest {}
+```
+
+#### QueryParamsResponse
+
+This message responds with the parameters of the `stablestake` module.
+
+```proto
+message QueryParamsResponse {
+  Params params = 1 [(gogoproto.nullable) = false];
+}
+```
+
+#### QueryBorrowRatioRequest
+
+This message requests the borrow ratio in the `stablestake` module.
+
+```proto
+message QueryBorrowRatioRequest {}
+```
+
+#### QueryBorrowRatioResponse
+
+This message responds with the total deposits, total borrowings, and the borrow ratio in the `stablestake` module.
+
+```proto
+message QueryBorrowRatioResponse {
+  string total_deposit = 1 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
+    (gogoproto.nullable) = false
+  ];
+  string total_borrow = 2 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
+    (gogoproto.nullable) = false
+  ];
+  string borrow_ratio = 3 [
+    (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Dec",
+    (gogoproto.nullable) = false
+  ];
+}
+```