Merge pull request #7 from nomic-io/update-docs

Update docs

src/00-02-validating.md

@@ -53,15 +53,6 @@ nomic declare \
 
 ### 2. Run your Bitcoin signer
 
-The funds in the Bitcoin bridge are held in a large multisig controlled by the Nomic validators. If you are a validator with a significant amount of voting power, it is very important that you run a signer.
-
-You can run the signer with:
-```bash
-nomic signer
-```
-
-This will automatically generate a Bitcoin extended private key and store it at `~/.nomic-stakenet-3/signer/xpriv` (or `~/.nomic-testnet-4d/signer/xpriv` on testnet). It will also prompt you to submit your public key to the network so you can be added to the multisig. **KEEP THIS KEY SAFE** - similar to your validator private key, it is important to be mindful of this key so that it is never lost or stolen.
-
-Leave this process running, it will automatically sign Bitcoin transactions that the network wants to create.
-
-In the future, we hope for the community to come up with alternative types of signers which provide for extra security, by e.g. airgapping keys, using HSMs, or prompting the user for an encryption key.
+The funds in the Bitcoin bridge are held in a large multisig controlled by the
+Nomic validators. If you are a validator with a significant amount of voting
+power, it is very important that you [run a signer.](./00-04-signer.md)

src/00-04-bitcoin-signer.md

@@ -0,0 +1,44 @@
+# Bitcoin Signer
+
+The funds in the Bitcoin bridge are held in a large multisig controlled by the Nomic validators. If you are a validator with a significant amount of voting power, it is very important that you run a signer.
+
+You can run the signer with:
+
+```
+nomic signer
+```
+
+This will automatically generate a Bitcoin extended private key and store it at `~/.nomic-stakenet-3/signer/xpriv`. It will also prompt you to submit your public key to the network so you can be added to the multisig. **KEEP THIS KEY SAFE** - similar to your validator private key, it is important to be mindful of this key so that it is never lost or stolen.
+
+Leave this process running, it will automatically sign Bitcoin transactions that the network wants to create.
+
+In the future, we hope for the community to come up with alternative types of signers which provide for extra security, by e.g. airgapping keys, using HSMs, or prompting the user for an encryption key.
+
+### Circuit Breaker
+
+The signer process will automatically halt signing if, over the past 24 hours,
+the signatory set has changed too much, or if too much Bitcoin is being
+withdrawn from the bridge.
+
+These parameters are tunable:
+
+```
+nomic signer
+
+        --max-sigset-change-rate <MAX_SIGSET_CHANGE_RATE>
+            Limits the maximum allowed signatory set change within 24 hours
+
+            The Total Variation Distance between a day-old signatory set and the newly-proposed
+            signatory set may not exceed this value
+
+            [default: 0.04]
+
+        --max-withdrawal-rate <MAX_WITHDRAWAL_RATE>
+            Limits the fraction of the total reserve that may be withdrawn within the trailing
+            24-hour period
+
+            [default: 0.04]
+```
+
+Tweaking these parameters is a decision that requires careful thought. A future
+release will integrate these circuit breaker checks into the protocol itself.

src/00-05-ibc-relayer

@@ -0,0 +1,173 @@
+# IBC Relayer
+
+Running an IBC relayer for Nomic works mostly the same as with other Cosmos
+chains, but with a few caveats:
+
+1. Currently, Nomic is only compatible with
+   [Hermes](https://hermes.informal.systems) and does not support the ibc-go
+   relayer.
+2. Hermes must be configured with a custom proof spec. Please see the example
+   configuration below.
+
+## 1. Configure Hermes
+
+Here's an example Hermes configuration relaying between a local Nomic and
+Osmosis node:
+
+```toml
+# ~/.hermes/config.toml
+
+[[chains]]
+id = 'nomic-stakenet-3'
+rpc_addr = 'http://127.0.0.1:26657'
+event_source = { mode = 'pull' }
+grpc_addr = 'http://127.0.0.1:9001'
+rpc_timeout = '10s'
+account_prefix = 'nomic'
+key_name = 'testkey'
+store_prefix = 'ibc'
+max_gas = 40000000
+gas_price = { price = 0.001, denom = 'stake' }
+clock_drift = '20s'
+proof_specs = '''
+[
+  {
+    "inner_spec": {
+      "child_order": [
+        0,
+        1,
+        2
+      ],
+      "child_size": 32,
+      "empty_child": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+      "min_prefix_length": 1,
+      "max_prefix_length": 1,
+      "hash": 6
+    },
+    "leaf_spec": {
+      "hash": 6,
+      "prehash_key": 0,
+      "prehash_value": 0,
+      "length": 4,
+      "prefix": "AA"
+    },
+    "max_depth": 0,
+    "min_depth": 0
+  },
+  {
+    "inner_spec": {
+      "child_order": [
+        0
+      ],
+      "child_size": 32,
+      "empty_child": "",
+      "min_prefix_length": 0,
+      "max_prefix_length": 0,
+      "hash": 6
+    },
+    "leaf_spec": {
+      "hash": 6,
+      "prehash_key": 0,
+      "prehash_value": 0,
+      "length": 0,
+      "prefix": ""
+    },
+    "max_depth": 0,
+    "min_depth": 0
+  }
+]
+'''
+
+[[chains]]
+id = 'osmosis-1'
+rpc_addr = 'http://127.0.0.1:26757'
+grpc_addr = 'http://127.0.0.1:9090'
+websocket_addr = 'ws://127.0.0.1:26757/websocket'
+rpc_timeout = '10s'
+account_prefix = 'osmo'
+key_name = 'osmosis'
+address_type = { derivation = 'cosmos' }
+store_prefix = 'ibc'
+default_gas = 5000000
+max_gas = 15000000
+gas_price = { price = 0.0026, denom = 'uosmo' }
+gas_multiplier = 1.1
+max_msg_num = 20
+max_tx_size = 209715
+clock_drift = '20s'
+max_block_time = '10s'
+trusting_period = '10days'
+trust_threshold = { numerator = '1', denominator = '3' }
+[chains.packet_filter]
+policy = 'allow'
+list = [
+  ['transfer', 'channel-5555'], # nomic-stakenet-3
+]
+```
+
+The `proof_specs` and `event_source` fields for Nomic are the main differences
+to note for those otherwise familiar with IBC relaying with Hermes.
+
+Please refer to the [Hermes docs](https://hermes.informal.systems) for more
+information.
+
+## 2. Run gRPC server
+
+Nomic features a gRPC server to support IBC relaying, which implements only the
+minimum set of gRPC methods required by Hermes. The server does not run by
+default, and must be run in a separate process with:
+
+```bash
+# default port 9001
+nomic grpc
+```
+
+or:
+
+```bash
+nomic grpc <PORT>
+```
+
+## 3. Fund relayer with NBTC
+
+Fees for IBC transactions are paid with NBTC (1 sat per tx). After you've
+configured your relayer, you'll need to fund its Nomic account (`hermes keys
+list --chain nomic-stakenet-3` to see the address) with NBTC.
+
+## 4. (Optional) Relay operator keys
+
+To ensure that NBTC is recoverable by the remote chain's validator set in the
+event of an Emergency Disbursal, run:
+
+```bash
+nomic relay-op-keys <COUNTERPARTY-RPC> <CLIENT_ID>
+```
+
+This command may be re-run anytime to refresh the operator keys of the
+remote chain's validator set. If an Emergency Disbursal occurs on Nomic, a
+portion of the Bitcoin reserves equal to the NBTC held in channels backed by the
+specified client will become spendable by 2/3+ of the voting power of that network's top 30 validators.
+
+## Other notes
+
+Below are a couple other notes to keep in mind, given Nomic's custom IBC implementation.
+
+### Channel ports
+
+For channels supporting token transfers, the Nomic channel port **must**
+be `transfer`. ICS 20 is the only application-layer standard currently
+supported by Nomic:
+
+```bash
+hermes create channel --a-chain osmosis-1  --b-chain nomic-stakenet-3 --a-port transfer --b-port transfer --new-client-connection
+```
+
+### Manual clearing
+
+Typically, the main Hermes process (`hermes start`) will properly relay packets
+between Nomic and its counterparty. However, if it seems like an event has been
+missed by Hermes, packets can be manually cleared (bidirectionally) with:
+
+```bash
+hermes clear packets --chain nomic-stakenet-3 --port transfer --channel channel-1
+```

src/SUMMARY.md

@@ -3,7 +3,9 @@
 - [Nomic](./intro.md)
 
 - [Running a Node](./00-node.md)
-    - [Setup](./00-00-setup.md)
-    - [Upgrading](./00-01-upgrading.md)
-    - [Validating](./00-02-validating.md)
-    - [Bitcoin Relayer](./00-03-bitcoin-relayer.md)
+  - [Setup](./00-00-setup.md)
+  - [Upgrading](./00-01-upgrading.md)
+  - [Validating](./00-02-validating.md)
+  - [Bitcoin Relayer](./00-03-bitcoin-relayer.md)
+  - [Bitcoin Signer](./00-04-bitcoin-signer.md)
+  - [IBC Relayer](./00-05-ibc-relayer)