Documentation update

docs/design/bootstrapping.md

@@ -0,0 +1,22 @@
+# Bootstrapping
+
+This document describes the bootstrapping process for the Gravity bridge.
+
+We assume the act of upgrading the Cosmos-based binary to have gravity module is already complete,
+as approaches to that are discussed in many other places. Here we focus on the _activation_ step.
+
+The [Gravity.sol](/solidity/contracts/Gravity.sol) contract can be initialized with the validator set from an active chain or from a Genesis file.
+
+In a potentially contentious deployment scenario there may be an unlimited number of Gravity contracts deployed on Ethereum, each attempting to present themselves as the 'actual contract'.
+
+In order to decide which contract is valid a governance vote setting the [bridge_ethereum_address](/docs/design/paramaters.md##bridge_ethereum_address) should be held. Once again in a contentious deployment scenario there may be many such votes going on in parallel.
+
+During the voting process the validator set on the chain in question may change significantly. During the voting phase validators must run their `Ethereum Signer` but not their `Ethereum oracle` as there is no defined contract to relay events from.
+
+It is the responsibility of each contract deployer to run at least one `relayer` directed at their contract. This will take the signatures produced by the `Ethereum Signer` and keep the validator set up to date during the voting period.
+
+The `Ethereum oracle` implementation in this repo _should_, but does not currently (May 4th 2021), refer to the `bridge_ethereum_address` governance parameter and disable the `Ethereum oracle` functionality automatically until it is set.
+
+It is very important that validators must run their `Ethereum Signer` from the moment the chain starts, as the Gravity module will be producing validator set updates and they will be subject to [slashing](/spec/slashing-spec.md) immediately.
+
+Once the voting process is complete and the definitive Gravity contract address is set as a parameter bootstrapping is complete.

docs/design/ethereum-signing.md

@@ -0,0 +1,26 @@
+# Ethereum signing
+
+As outlined in the [overview](/docs/design/overview.md) the [Gravity.sol](/solidity/contracts/Gravity.sol) contract acts as a weighted powers multisig for the funds sorted in the bridge. Effectively producing a situation where the validator set of the Cosmos chain owns all the funds in the bridge in a multisig that replicates their stake weighted voting power on Cosmos.
+
+## Delegate Addresses
+
+This document outlines the Ethereum signatures, all contract calls on [Gravity.sol](/solidity/contracts/Gravity.sol) accept an array of signatures provided by a validator set stored in the contract.
+
+Validators make these signatures with their `Delegate Ethereum address` this is an Ethereum address set by the validator using the [SetOrchestratorAddress](/docs/design/messages.md/###SetOrchestratorAddress) message. The validator signs over this Ethereum address, as well as a Cosmos address for [oracle](/docs/design/oracle.md) operations and submits it to the chain to register these addresses for use in the Ethereum signer and oracle subsystems.
+
+The `Delegate Ethereum address` then represents that validator on the Ethereum blockchain and will be added as a signing member of the multisig with a weighted voting power as close as possible to the Cosmos voting power.
+
+## Signing flow
+
+Validators run an external process called an `Ethereum Signer` this process is required because we can not yet insert this sort of simple signature logic into CosmosSdk based chains without significant modification to Tendermint. This may be possible in the future with [modifications to Tendermint](https://github.com/tendermint/tendermint/issues/6066).
+
+It should be noted that both [GRAVSLASH-02](/spec/slashing-spec.md) and [GRAVSLASH-03](/spec/slashing-spec.md) could be eliminated with no loss of security if it where possible to perform the Ethereum signatures inside the consensus code. This is a pretty limited feature addition to Tendermint that would make Gravity far less prone to slashing.
+
+Until such a change is provided the signing flow works as follows.
+
+1. The Gravity module produces a `ValidatorSetRequest`, `BatchRequest`, or `LogicCallRequest`. These requests are placed into the store and act as coordination points for signatures
+1. `Ethereum Signer` processes query these requests and perform a signature with the `Delegate Ethereum Address`
+1. The `Ethereum Signer` submits the signature as a [transaction](/docs/design/ethereum-signing.md##Ethereum-Signer-Message)
+1. The Gravity module verifies that the signature is made with the correct key and over the correct data before storing it
+1. `Relayers` now query these signatures and assemble them into an Ethereum contract call to submit to [Gravity.sol](/solidity/contracts/Gravity.sol)
+1. The message is submitted and executed on the Ethereum chain

docs/design/incentives.md

@@ -0,0 +1,23 @@
+# Incentives
+
+This document covers all the incentivization systems in Gravity bridge.
+
+## Validators
+
+Currently validators in Gravity have only one carrot. The extra activity brought to the chain by a functioning bridge.
+
+There are on the other hand a lot of negative incentives (sticks) that the validators must watch out for. These are outlined in the [slashing spec](/spec/slashing-spec.md).
+
+One negative incentive that is not covered under slashing is the cost of submitting oracle submissions and signatures. Currently these operations are not incentivized, but still cost the validators fees to submit. This isn't an issue considering the low activity on most Cosmos based chains at the moment. But an active Ethereum bridge and dex may change that issue very quickly.
+
+Some positive incentives for correctly participating in the operation of the bridge should be under consideration. In addition to eliminating the fees for mandatory submissions.
+
+## Relaying rewards
+
+Relaying rewards cover all messages that need to be submitted to Ethereum from Cosmos. This includes Validator set updates, transaction batches, and arbitrary logic calls. Keep in mind that these messages cost a variable amount of money based on wildly changing Ethereum gas prices and it's not unreasonable for a single batch to cost over a million gas.
+
+A major design decision for our relayer rewards was to always issue them on the Ethereum chain. This has downsides, namely some strange behavior in the case of validator set update rewards.
+
+But the upsides are undeniable, because the Ethereum messages pay `msg.sender` any existing bot in the Ethereum ecosystem will pick them up and try to submit them. This makes the relaying market much more competitive and less prone to cabal like behavior.
+
+For a detailed look at how exactly all rewards are paid out see the [minting and locking](/docs/design/mint-lock.md##Relaying-rewards) design documentation.

docs/design/messages.md

@@ -0,0 +1,89 @@
+# Gravity messages
+
+This is a reference document for Gravity message types. For code reference and exact
+arguments see the [proto definitions](/module/proto/gravity/v1/msgs.proto)
+
+## User messages
+
+These are messages sent on the Cosmos side of the bridge by users. See [minting and locking](/docs/design/mint-lock.md) for a more
+detailed summary of the entire deposit and withdraw process.
+
+### SendToEth
+
+SendToEth allows the user to specify a Ethereum destination, a token to send to Ethereum and a fee denominated in that same token
+to pay the relayer. Note that this transaction will contain two fees. One fee amount to submit to the Cosmos chain, that can be paid
+in any token and one fee amount for the Ethereum relayer that must be paid in the same token that is being bridged.
+
+### CancelSendToEth
+
+CancelSendToEth allows a user to retrieve a transaction that is in the batch pool but has not yet been packaged into a transaction batch
+by a relayer running [RequestBatch](/docs/design/messages.md/###RequestBatch). For more details on this process see the [batch creation spec](/spec/batch-creation-spec.md)
+
+## Relayer Messages
+
+These are messages run by relayers. Relayers are unpermissioned and simply work to move things from Cosmos to Ethereum.
+
+### RequestBatch
+
+Relayers use `QueryPendingSendToEth` in [query.proto](/module/proto/gravity/v1/query.proto) to query the potential fees for a batch of each
+token type. When they find a batch that they wish to relay they send in a RequestBatch message and the Gravity module creates a batch.
+
+This then triggers the Ethereum Signers to send in ConfirmBatch messages, which the signatures required to submit the batch to the Ethereum chain.
+
+At this point any relayer can package these signatures up into a transaction and send them to Ethereum.
+
+As noted above this message is unpermissioned and it is safe to allow anyone to call this message at any time thanks to the rules described in the [batch creation spec](/spec/batch-creation-spec.md)
+
+## Oracle Messages
+
+All validators run two processes in addition to their Cosmos node. An Ethereum oracle and Ethereum signer, these are bundled into a single Orchestrator binary for ease of use.
+for further reference on this process see the [design overview](/docs/design/overview.md), [oracle design](/docs/design/oracle.md), and [minting and locking](/docs/design/mint-lock.md)
+
+The oracle observes the Ethereum chain for events from the [Gravity.sol](/solidity/contracts/Gravity.sol) contract before submitting them as messages to the Cosmos chain.
+
+### DepositClaim
+
+claim representing a `SendToCosmosEvent` from [Gravity.sol](/solidity/contracts/Gravity.sol). When this passes the oracle vote tokens will be issued to a Cosmos account.
+
+### WithdrawClaim
+
+claim representing a `TransactionBatchExecutedEvent` from [Gravity.sol](/solidity/contracts/Gravity.sol). When this passes the oracle vote the batch in state is cleaned up and tokens are burned/locked.
+
+### ValsetUpdateClaim
+
+claim representing a `ValsetUpdatedEvent` from [Gravity.sol](/solidity/contracts/Gravity.sol). When this passes the oracle vote reward amounts are tallied and minted.
+
+### ERC20DeployedClaim
+
+claim representing a `ERC20DeployedEvent` from [Gravity.sol](/solidity/contracts/Gravity.sol). When this passes the oracle vote it is checked for accuracy and adopted or rejected as the ERC20 representation of a Cosmos asset
+
+### LogicCallExecutedClaim
+
+claim representing a `LogicCallEvent` from [Gravity.sol](/solidity/contracts/Gravity.sol). When this passes the oracle vote the logic call in state is cleaned up and tokens are burned/locked.
+
+## Ethereum Signer messages
+
+All validators run two processes in addition to their Cosmos node. An Ethereum oracle and Ethereum signer, these are bundled into a single Orchestrator binary for ease of use.
+for further reference on this process see the [design overview](/docs/design/overview.md), [eth signer design](/docs/design/ethereum-signing.md), and [minting and locking](/docs/design/mint-lock.md)
+
+The Ethereum signer watches several [query endpoints](/module/proto/gravity/v1/query.proto) and it's only job is to submit a signature for anything that appears on those endpoints. For this reason the validator must provide a secure RPC to a Cosmos node following chain consensus. Or they risk being tricked into signing the wrong thing.
+
+### ConfirmBatch
+
+Submits an Ethereum signature over a batche appearing in the `LastPendingBatchRequestByAddr` query
+
+### ConfirmLogicCall
+
+Submits an Ethereum signature over a batche appearing in the `LastPendingLogicCallByAddr` query
+
+### ValsetConfirm
+
+Submits an Ethereum signature over a batche appearing in the `LastPendingValsetRequestByAddr` query
+
+## Validator Messages
+
+These are messages sent directly using the validators message key.
+
+### SetOrchestratorAddress
+
+This message sets the Orchestrator delegate keys described in the [design overview](/docs/design/overview.md)