Merge PR #3656: Broken-Invar Tx - aka. Crisis module

* beginning thinking on issue * ... * working * working * working fee pool distribution * spek outline * spec update * gas refund calculations * simulation saved to ~/.gaiad/simulations/ * lean simulation output int * cleanup bank simulation messages * operation messges int * lint * move simulation to its own module * move simulation log code to log.go * logger overhaul int * distribution comments * fix compiling * cleanup modifications to x/distribution/keeper/allocation.go int int int * gov bug * result.IsOK() minimization * importExport typo bug * pending * address @alexanderbez comments * simple @cwgoes comments addressed * event logging unified approach * distr module name constant * implementing * compiles * gaia integration * proper constant fee removal * crisis genesis * go.sum update * ... * debugging * fix sum errors * missing err checks * working implementing CLI * remove query command * crisis expected keepers in other modules * crisis testing infrastructure * working * tests complete * modify handler to still panic if not enough pool coins, docs working * spec tags * docs complete * CL * assert invariants on a blockly basis gaiad functionality * gaiad CL * transaction details in runtime invariance panic * Apply suggestions from code review Co-Authored-By: rigelrozanski <rigel.rozanski@gmail.com> * sender tags * @mossid suggestions int * @cwgoes comments final * Apply suggestions from code review Co-Authored-By: rigelrozanski <rigel.rozanski@gmail.com> * bug seems fixed (#3998) * delete unused line in zero height export bug
2019-03-28 19:27:47 -04:00
parent b9e6df3851
commit df4394185e
48 changed files with 820 additions and 120 deletions
@@ -0,0 +1,14 @@
+# State
+
+## ConstantFee
+
+Due to the anticipated large gas cost requirement to verify an invariant (and
+potential to exceed the maximum allowable block gas limit) a constant fee is
+used instead of the standard gas consumption method. The constant fee is
+intended to be larger than the anticipated gas cost of running the invariant
+with the standard gas consumption method. 
+
+The ConstantFee param is held in the global params store. 
+
+ - Params: `mint/params -> amino(sdk.Coin)`
+
@@ -0,0 +1,25 @@
+# Messages
+
+In this section we describe the processing of the crisis messages and the
+corresponding updates to the state. 
+
+## MsgVerifyInvariant
+
+Blockchain invariants can be checked using the `MsgVerifyInvariant` message. 
+
+```golang
+type MsgVerifyInvariant struct {
+	Sender         sdk.AccAddress 
+	InvariantRoute string
+}
+```
+
+This message is expected to fail if: 
+ - the sender does not have enough coins for the constant fee
+ - the invariant route is not registered 
+
+This message checks the invariant provided, and if the invariant is broken it
+panics, halting the blockchain. If the invariant is broken, the constant fee is
+never deducted as the transaction is never committed to a block (equivalent to
+being refunded). However, if the invariant is not broken, the constant fee will
+not be refunded.
@@ -0,0 +1,13 @@
+# Tags
+
+The crisis module emits the following events/tags:
+
+## Handlers
+
+### MsgVerifyInvariance
+
+| Key       | Value               |
+|-----------|---------------------|
+| action    | verify_invariant    |
+| sender    | {message-sender}    |
+| invariant | {invariant-route}   |
@@ -0,0 +1,16 @@
+# Crisis
+
+## Overview
+
+The crisis module halts the blockchain under the circumstance that a blockchain 
+invariant is broken. Invariants can be registered with the application during the
+application initialization process. 
+
+## Contents
+
+1. **[State](01_state.md)**
+    - [ConstantFee](01_state.md#constantfee)
+2. **[Messages](02_messages.md)**
+    - [MsgVerifyInvariant](02_messages.md#msgverifyinvariant)
+3. **[Tags](03_tags.md)**
+    - [Handlers](03_tags.md#handlers)