docs: quickstart

QUICKSTART.md

@@ -0,0 +1,184 @@
+# Getting Started
+
+## 1. First Time
+
+1. Ensure all dependencies are installed - 
+```bash
+make setup-deps
+```
+
+2. Ensure Kubernetes is enabled in Docker
+
+<img src="./docker-desktop-kubernetes.png" width="480px"></img>
+
+3. If on Mac silicon, ensure Rosetta emulation is enabled.
+
+4. Install Hermes, ensure it's in PATH (separate from Starship, but necessary for this demo)
+
+```bash
+# assumes rust is installed
+cargo install ibc-relayer-cli --bin hermes --locked
+
+# confirm hermes is installed
+hermes version
+> hermes v1.8.0+39036d1
+```
+[More detailed hermes install instructions](https://hermes.informal.systems/quick-start/installation.html#install-via-cargo)
+
+
+## 2. Start Starship Service
+```bash
+# start the service with helm
+helm install -f configs/starship.yaml starship-getting-started starship/devnet --version 0.1.48
+```
+
+```bash
+# ensure the pods started
+watch kubectl get pods
+```
+
+```bash
+# forward ports
+make port-forward
+```
+
+## 3. Start Agoric Chain
+
+```bash
+cd ~/agoric-sdk/packages/cosmic-swingset
+make scenario2-setup scenario2-run-chain
+```
+
+## 4. Fund Relayer
+```bash
+cd ~/agoric-sdk/packages/cosmic-swingset
+make ACCT_ADDR=agoric1gtkg0g6x8lqc734ht3qe2sdkrfugpdp2h7fuu0 FUNDS=2000000ubld fund-acct
+```
+
+## 5. Add keys to hermes
+```bash
+hermes keys add --chain agoriclocal --mnemonic-file keys/user-1.key
+hermes keys add --chain osmosis-test --mnemonic-file keys/osmosis-1.key
+```
+
+## 6. Add clients, connection, and start Hermes
+```bash
+# create clients
+hermes --config ./config.toml create client --host-chain agoriclocal --reference-chain osmosis-test
+hermes --config ./config.toml create client --host-chain osmosis-test --reference-chain agoriclocal
+# create connection between them
+hermes --config ./config.toml create connection --a-chain agoriclocal --b-chain osmosis-test
+# when successful, start client
+hermes --config ./config.toml start
+```
+
+<details>
+  <summary>Example Output</summary>
+
+  ```bash
+  $ hermes --config ./config.toml create client --host-chain agoriclocal --reference-chain osmosis-test
+  SUCCESS CreateClient(
+      CreateClient(
+          Attributes {
+              client_id: ClientId(
+                  "07-tendermint-0",
+              ),
+              client_type: Tendermint,
+              consensus_height: Height {
+                  revision: 0,
+                  height: 148,
+              },
+          },
+      ),
+  )
+  ```
+  ```bash
+  $ hermes --config ./config.toml create client --host-chain osmosis-test --reference-chain agoriclocal
+  SUCCESS CreateClient(
+      CreateClient(
+          Attributes {
+              client_id: ClientId(
+                  "07-tendermint-1",
+              ),
+              client_type: Tendermint,
+              consensus_height: Height {
+                  revision: 0,
+                  height: 27,
+              },
+          },
+      ),
+  )
+  ```
+  ```bash
+  $ hermes create connection --a-chain agoriclocal --b-chain osmosis-test
+  INFO ThreadId(01) 🥂 agoriclocal => OpenInitConnection(OpenInit { Attributes { connection_id: connection-0, client_id: 07-tendermint-1, counterparty_connection_id: None, counterparty_client_id: 07-tendermint-2 } }) at height 0-30
+  INFO ThreadId(01) 🥂 osmosis-test => OpenTryConnection(OpenTry { Attributes { connection_id: connection-1, client_id: 07-tendermint-2, counterparty_connection_id: connection-0, counterparty_client_id: 07-tendermint-1 } }) at height 0-185
+  INFO ThreadId(01) 🥂 agoriclocal => OpenAckConnection(OpenAck { Attributes { connection_id: connection-0, client_id: 07-tendermint-1, counterparty_connection_id: connection-1, counterparty_client_id: 07-tendermint-2 } }) at height 0-34
+  INFO ThreadId(01) 🥂 osmosis-test => OpenConfirmConnection(OpenConfirm { Attributes { connection_id: connection-1, client_id: 07-tendermint-2, counterparty_connection_id: connection-0, counterparty_client_id: 07-tendermint-1 } }) at height 0-203
+  INFO ThreadId(01) connection handshake already finished for Connection { delay_period: 0ns, a_side: ConnectionSide { chain: BaseChainHandle { chain_id: agoriclocal }, client_id: 07-tendermint-1, connection_id: connection-0 }, b_side: ConnectionSide { chain: BaseChainHandle { chain_id: osmosis-test }, client_id: 07-tendermint-2, connection_id: connection-1 } }
+  SUCCESS Connection {
+      delay_period: 0ns,
+      a_side: ConnectionSide {
+          chain: BaseChainHandle {
+              chain_id: ChainId {
+                  id: "agoriclocal",
+                  version: 0,
+              },
+              runtime_sender: Sender { .. },
+          },
+          client_id: ClientId(
+              "07-tendermint-1",
+          ),
+          connection_id: Some(
+              ConnectionId(
+                  "connection-0", // controllerConnectionId
+              ),
+          ),
+      },
+      b_side: ConnectionSide {
+          chain: BaseChainHandle {
+              chain_id: ChainId {
+                  id: "osmosis-test",
+                  version: 0,
+              },
+              runtime_sender: Sender { .. },
+          },
+          client_id: ClientId(
+              "07-tendermint-2",
+          ),
+          connection_id: Some(
+              ConnectionId(
+                  "connection-1", // hostConnectionId
+              ),
+          ),
+      },
+  }
+  ```
+</details>
+
+## 7. Start ag-solo + REPL 
+```bash
+cd ~/agoric-sdk/packages/cosmic-swingset
+make scenario2-run-client
+```
+
+## 8. Create Account in REPL
+```bash
+agoric open --repl
+
+# in REPL:
+E(home.agoricNames).lookup('instance', 'stakeAtom')
+E(home.zoe).getPublicFacet(history[n])
+pf = history[n]
+E(pf).provideAccount()
+```
+
+
+## Stop Starship Service
+```bash
+helm delete starship-getting-started
+make stop-forward
+
+# or, in one step:
+make stop
+```

config.toml

@@ -0,0 +1,133 @@
+# The global section has parameters that apply globally to the relayer operation.
+[global]
+# Specify the verbosity for the relayer logging output. Default: 'info'
+# Valid options are 'error', 'warn', 'info', 'debug', 'trace'.
+log_level = 'info'
+# Specify the mode to be used by the relayer. [Required]
+[mode]
+# Specify the client mode.
+[mode.clients]
+# Whether or not to enable the client workers. [Required]
+enabled = true
+# Whether or not to enable periodic refresh of clients. [Default: true]
+# This feature only applies to clients that underlie an open channel.
+# For Tendermint clients, the frequency at which Hermes refreshes them is 2/3 of their
+# trusting period (e.g., refresh every ~9 days if the trusting period is 14 days).
+# Note: Even if this is disabled, clients will be refreshed automatically if
+#      there is activity on a connection or channel they are involved with.
+refresh = true
+# Whether or not to enable misbehaviour detection for clients. [Default: false]
+misbehaviour = true
+# Specify the connections mode.
+[mode.connections]
+# Whether or not to enable the connection workers for handshake completion. [Required]
+enabled = true
+# Specify the channels mode.
+[mode.channels]
+# Whether or not to enable the channel workers for handshake completion. [Required]
+enabled = true
+# Specify the packets mode.
+[mode.packets]
+# Whether or not to enable the packet workers. [Required]
+enabled = true
+# Parametrize the periodic packet clearing feature.
+# Interval (in number of blocks) at which pending packets
+# should be periodically cleared. A value of '0' will disable
+# periodic packet clearing. [Default: 100]
+clear_interval = 100
+# Whether or not to clear packets on start. [Default: false]
+clear_on_start = true
+# Toggle the transaction confirmation mechanism.
+# The tx confirmation mechanism periodically queries the `/tx_search` RPC
+# endpoint to check that previously-submitted transactions
+# (to any chain in this config file) have been successfully delivered.
+# If they have not been, and `clear_interval = 0`, then those packets are
+# queued up for re-submission.
+# Experimental feature. Affects telemetry if set to false.
+# [Default: true]
+tx_confirmation = true
+# The REST section defines parameters for Hermes' built-in RESTful API.
+# https://hermes.informal.systems/rest.html
+[rest]
+# Whether or not to enable the REST service. Default: false
+enabled = true
+# Specify the IPv4/6 host over which the built-in HTTP server will serve the RESTful
+# API requests. Default: 127.0.0.1
+host =  '127.0.0.1'
+# Specify the port over which the built-in HTTP server will serve the restful API
+# requests. Default: 3000
+port = 3000
+# The telemetry section defines parameters for Hermes' built-in telemetry capabilities.
+# https://hermes.informal.systems/telemetry.html
+[telemetry]
+# Whether or not to enable the telemetry service. Default: false
+enabled = true
+# Specify the IPv4/6 host over which the built-in HTTP server will serve the metrics
+# gathered by the telemetry service. Default: 127.0.0.1
+host = '127.0.0.1'
+# Specify the port over which the built-in HTTP server will serve the metrics gathered
+# by the telemetry service. Default: 3001
+port = 3001
+
+# [[chains]]
+# id = "gaia-test"
+# key_name = "gaia-1"
+# rpc_addr = "http://localhost:26654"
+# grpc_addr = "http://localhost:9092"
+# event_source = { mode = 'push', url = "ws://localhost:26654/websocket", batch_delay = '500ms' }
+# account_prefix = "cosmos"
+# default_gas = 500000000
+# max_gas = 1000000000
+# rpc_timeout = "10s"
+# store_prefix = "ibc"
+# gas_multiplier = 2
+# max_msg_num = 30
+# max_tx_size = 2097152
+# clock_drift = "5s"
+# max_block_time = "30s"
+# trusting_period = "24h"
+# trust_threshold = { numerator = '1', denominator = '3' }
+# address_type = { derivation = 'cosmos' }
+# gas_price = { price = 0.25, denom = "uatom" }
+
+[[chains]]
+id = 'agoriclocal'
+rpc_addr = 'http://localhost:26657'
+grpc_addr = 'http://localhost:9090'
+event_source = { mode = 'push', url = 'ws://localhost:26657/websocket', batch_delay = '500ms' }
+rpc_timeout = '15s'
+account_prefix = 'agoric'
+key_name = 'user1'
+address_type = { derivation = 'cosmos' }
+store_prefix = 'ibc'
+default_gas = 2000000
+max_gas = 10000000
+gas_price = { price = 0.00, denom = 'ubld' }
+gas_multiplier = 1.1
+max_msg_num = 25
+max_tx_size = 180000
+clock_drift = '15s'
+max_block_time = '15s'
+trusting_period = '14days'
+trust_threshold = { numerator = '1', denominator = '3' }
+
+[[chains]]
+id = "osmosis-test"
+key_name = "osmosis-1"
+rpc_addr = "http://localhost:26655"
+grpc_addr = "http://localhost:9093"
+event_source = { mode = 'push', url = "ws://localhost:26655/websocket", batch_delay = '500ms' }
+account_prefix = "osmo"
+default_gas = 500000000
+max_gas = 1000000000
+rpc_timeout = "10s"
+store_prefix = "ibc"
+gas_multiplier = 2
+max_msg_num = 30
+max_tx_size = 2097152
+clock_drift = "5s"
+max_block_time = "30s"
+trusting_period = "24h"
+trust_threshold = { numerator = '1', denominator = '3' }
+address_type = { derivation = 'cosmos' }
+gas_price = { price = 0.025, denom = "uosmo" }

configs/starship.yaml

@@ -1,17 +1,29 @@
 chains:
   - name: osmosis-test
     type: osmosis
+    image: ghcr.io/cosmology-tech/starship/osmosis:v21.0.0@sha256:233a6fc5218f74f85abfda8d7219fedb54112fbc8933d4170d1db39b603d1583
     numValidators: 1
+    genesis:
+      app_state:
+        staking:
+          params:
+            unbonding_time: "48h"
     faucet:
       enabled: true
     ports:
-      rest: 1313
-      rpc: 26653
-      grpc: 9091
-      faucet: 8082
+      rest: 1315
+      rpc: 26655
+      grpc: 9093
+      faucet: 8084
   - name: gaia-test
     type: cosmos
+    image: ghcr.io/cosmology-tech/starship/gaia:v14.0.0@sha256:e63e49b328737e62c432158d7619e04b91f925403c89148ed4c594a305a78c83
     numValidators: 1
+    genesis:
+      app_state:
+        staking:
+          params:
+            unbonding_time: "48h"
     faucet:
       enabled: true
     ports:

keys/gaia-1.key

@@ -0,0 +1 @@
+pen quit web pill hunt hobby tonight base wine black era cereal veteran trouble december method diet orbit copper nephew into badge olympic repair

keys/user1.key

@@ -0,0 +1 @@
+canal hundred icon during alone fresh vacant insect hungry advice sponsor wave boil drift bracket dwarf together unknown island dizzy trust leisure balcony blood