add kavadist spec

x/kavadist/spec/01_concepts.md

@@ -0,0 +1,3 @@
+# Concepts
+
+The minting mechanism in this module is designed to allow governance to determine a set of inflationary periods and the APR rate of inflation for each period. This module mints coins each block according to the schedule such that after 1 year the APR inflation worth of coins will have been minted. Governance can alter the APR inflation using a parameter change proposal. Parameter change proposals that change the APR will take effect in the block after they pass.

x/kavadist/spec/02_state.md

@@ -0,0 +1,30 @@
+# State
+
+## Parameters and Genesis State
+
+`Parameters` define the rate at which inflationary coins are minted and for how long inflationary periods last.
+
+```go
+// Params governance parameters for kavadist module
+type Params struct {
+	Active  bool    `json:"active" yaml:"active"`
+	Periods Periods `json:"periods" yaml:"periods"`
+}
+
+// Period stores the specified start and end dates, and the inflation, expressed as a decimal representing the yearly APR of tokens that will be minted during that period
+type Period struct {
+	Start     time.Time `json:"start" yaml:"start"`         // example "2020-03-01T15:20:00Z"
+	End       time.Time `json:"end" yaml:"end"`             // example "2020-06-01T15:20:00Z"
+	Inflation sdk.Dec   `json:"inflation" yaml:"inflation"` // example "1.000000003022265980"  - 10% inflation
+}
+```
+
+`GenesisState` defines the state that must be persisted when the blockchain stops/restarts in order for normal function of the kavadist module to resume.
+
+```go
+// GenesisState is the state that must be provided at genesis.
+type GenesisState struct {
+	Params            Params    `json:"params" yaml:"params"`
+	PreviousBlockTime time.Time `json:"previous_block_time" yaml:"previous_block_time"`
+}
+```

x/kavadist/spec/03_messages.md

@@ -0,0 +1,3 @@
+# Messages
+
+There are no messages in the kavadist module. All state transitions are controlled by parameters, which can be updated via parameter change proposals.

x/kavadist/spec/04_events.md

@@ -0,0 +1,10 @@
+# Events
+
+The `x/kavadist` module emits the following events:
+
+## BeginBlock
+
+| Type                 | Attribute Key       | Attribute Value |
+|----------------------|---------------------|-----------------|
+| kavadist             | kava_dist_inflation | {amount}        |
+| kavadist             | kava_dist_status    | "inactive"      |

x/kavadist/spec/05_params.md

@@ -0,0 +1,15 @@
+# Parameters
+
+The kavadist module has the following parameters:
+
+| Key        | Type           | Example       | Description                                      |
+|------------|----------------|---------------|--------------------------------------------------|
+| Periods    | array (Period) | [{see below}] | array of params for each inflationary period     |
+
+Each `Period` has the following parameters
+
+| Key        | Type               | Example                  | Description                                                    |
+|------------|--------------------|--------------------------|----------------------------------------------------------------|
+| Start      | time.Time          | "2020-03-01T15:20:00Z"   | the time when the period will start                            |
+| End        | time.Time          | "2020-06-01T15:20:00Z"   | the time when the period will end                              |
+| Inflation  | sdk.Dec            | "1.000000003022265980"   | the per-second inflation for the period                        |

x/kavadist/spec/06_begin_block.md

@@ -0,0 +1,12 @@
+# Begin Block
+
+At the start of each block, the inflationary coins for the ongoing period, if any, are minted. The logic is as follows:
+
+```go
+  func BeginBlocker(ctx sdk.Context, k Keeper) {
+    err := k.MintPeriodInflation(ctx)
+    if err != nil {
+      panic(err)
+    }
+  }
+```

x/kavadist/spec/README.md

@@ -0,0 +1,13 @@
+# `kavadist`
+
+<!-- TOC -->
+1. **[Concepts](01_concepts.md)**
+2. **[State](02_state.md)**
+3. **[Messages](03_messages.md)**
+4. **[Events](04_events.md)**
+5. **[Params](05_params.md)**
+6. **[BeginBlock](06_begin_block.md)**
+
+## Abstract
+
+`x/kavadist` is an implementation of a Cosmos SDK Module that allows for governance controlled minting of coins into a module account. Coins are minted during inflationary periods, which each period have a governance specified APR and duration. This module does not provide functionality for spending or distributing the minted coins.