feat:v4 docs (#249)

* Update configuration reference

* Initial pubsub for validators doc

* Typos

* Review fixes

* A word

* Add real default values to reference config

docs/00-TableOfContents.md

@@ -17,3 +17,4 @@
         - [Create or import an Ethereum key](./03-TheOrchestrator.md#create-or-import-ethereum-key)
         - [Create or import a Cosmos key](./03-TheOrchestrator.md#create-or-import-cosmos-key)
         - [Configuration](./03-TheOrchestrator.md#configuration)
+4. [Pubsub for Validators](./05-PubsubForValidators.md)

docs/01-Configuration.md

@@ -218,7 +218,68 @@ The name of the key in `keystore` used for delegate signing by both Steward and
 delegate_key = ""
 ```
 
-### [metrics] table
+### `[cork]` table
+
+Config related to steward's interaction with the x/cork and x/axelarcork modules.
+
+#### `cache_refresh_period`
+
+Type: integer
+
+Steward's approved cellar cache refresh period in seconds.
+
+```
+[cork]
+cache_refresh_period = 3600
+```
+
+#### `proposal_poll_period`
+
+Type: integer
+
+How frequently (in seconds) steward should query the chain for approved scheduled cork proposals that must be submitted to the chain.
+
+```
+[cork]
+proposal_poll_period = 300
+```
+
+#### `max_scheduling_retries`
+
+Type: integer
+
+How many times steward should try to submit a scheduled cork proposal that errored during processing. 
+
+```
+[cork]
+max_scheduling_retries = 3
+```
+
+### `[pubsub]` table
+
+#### `cache_refresh_period`
+
+Type: integer
+
+How often steward's publisher trust data cache should be refreshed
+
+```
+[pubsub]
+cache_refresh_period = 3600
+```
+
+#### `publisher_domain_block_list`
+
+Type: string array
+
+Publisher domains that steward should reject calls from. Primarily used in emergency situations.
+
+```
+[pubsub]
+publisher_domain_block_list = ["compromised-publisher.example.com"]
+```
+
+### `[metrics]` table
 
 Config related to the Orchestrator metrics server
 
@@ -233,7 +294,7 @@ The server endpoint for monitoring Orchestrator metrics
 listen_addr = "127.0.0.1:3000"
 ```
 
-### [server] table
+### `[server]` table
 
 Config related to the Steward server
 
@@ -248,19 +309,6 @@ The IP address at which the Steward server will run
 address = "0.0.0.0"
 ```
 
-#### `client_ca_cert_path`
-
-Type: string
-
-The path to the trusted CA used to sign the Strategy Provider's client certificate
-
-> :warning: Please leave this value unset for now as it defaults to the Seven Seas CA internally
-
-```
-[server]
-client_ca_cert_path = ""
-```
-
 #### `port`
 
 Type: integer
@@ -294,6 +342,107 @@ The path to the PKCS8-formatted key used to generate the server certificate
 server_key_path = ""
 ```
 
+### `[simulate]` table
+
+#### `use_tls`
+
+Type: boolean
+
+Whether to require TLS for calls in simulate mode
+
+```
+[simulate]
+use_tls = false
+```
+
+#### `network_id`
+
+Type: string
+
+The EVM network ID of the target Ethereum network
+
+```
+[simulate]
+network_id = "1"
+```
+
+#### `tenderly_access_key`
+
+Type: string
+
+Tenderly access key for to use the API for running simulations
+
+```
+[simulate]
+tenderly_access_key = ""
+```
+
+#### `tenderly_project_name`
+
+Type: string
+
+Tenderly project name
+
+```
+[simulate]
+tenderly_project_name = "my_project"
+```
+
+#### `tenderly_username`
+
+Type: string
+
+Tenderly username
+
+```
+[simulate]
+tenderly_username = "myuser"
+```
+
+#### `gravity_address`
+
+Type: string
+
+Address of the gravity contract on the target network
+
+```
+[simulate]
+gravity_address = ""
+```
+
+#### `server_cert_path`
+
+Type: string
+
+Path to the server certificate to use if `use_tls` is `true`
+
+```
+[simulate]
+server_cert_path = ""
+```
+
+#### `server_key_path`
+
+Type: string
+
+Path to the server key used to create the server cert if `use_tls` is `true`
+
+```
+[simulate]
+server_cert_path = ""
+```
+
+#### `client_ca_cert_path`
+
+Type: string
+
+Path to the client certificate authority for use if `use_tls` is `true`
+
+```
+[simulate]
+client_ca_cert_path = ""
+```
+
 ## Complete Example config.toml
 
 This example will not work as is, you'll need to supply your own values.
@@ -321,11 +470,20 @@ key_derivation_path = "m/44'/60'/0'/0/0"
 rpc = "http://localhost:8545"
 
 [gravity]
-contract = "0x0000000000000000000000000000000000000000"
+contract = "0x69592e6f9d21989a043646fe8225da2600e5a0f7"
 fees_denom = "usomm"
 
 [keys]
-delegate_key = "mykey"
+delegate_key = "orchestrator"
+
+[cork]
+cache_refresh_period = 60
+proposal_poll_period = 300
+max_scheduling_retries = 3
+
+[pubsub]
+cache_refresh_period = 3600
+publisher_domain_block_list = [] 
 
 [metrics]
 listen_addr = "127.0.0.1:3000"
@@ -336,4 +494,16 @@ address = "0.0.0.0"
 port = 5734
 server_cert_path = "/server/cert/path"
 server_key_path = "/server/key/path"
+
+# Meant for use by strategists for development and testing
+[simulate]
+use_tls = false
+network_id = "1"
+tenderly_access_key = ""
+tenderly_project_name = ""
+tenderly_username = ""
+gravity_address = ""
+server_cert_path = ""
+server_key_path = ""
+client_ca_cert_path = ""
 ```

docs/02-StewardForValidators.md

@@ -2,10 +2,10 @@
 
 Steward is a side-car process that connects the Sommelier chain to the outside world. It provides an API for Strategy Providers to update Cellars through the Sommelier validator set based on off-chain calculations. Additionally, it subsumes the functionality of [gorc](https://github.com/PeggyJV/gravity-bridge/tree/main/orchestrator/gorc) for managing the [Gravity bridge Orchestrator](https://github.com/PeggyJV/gravity-bridge/tree/main/orchestrator), and provides developer tools and features for developing and testing Cellars.
 
-Steward runs on every Validator in the Sommelier Validator set. It runs a server to which Strategy Providers (SPs) send requests whenever they determine that the market has changed enough to warrant an update to the Cellar position. The request payload contains everything needed to make a *cork*: a signed combination of a cellar address and an ABI encoded contract call. When Steward receives a submission from the SP, it validates the target cellar address, builds a cork, signs it with the delegate key, and submits it to the [Cork module](https://github.com/PeggyJV/sommelier/tree/main/x/cork) on chain, where it will be bridged to the target Cellar contract if a consensus of validators submit the same cork.
+Steward runs on every Validator in the Sommelier Validator set. It runs a server to which Strategy Providers (SPs) send requests whenever they determine that the market has changed enough to warrant an update to the Cellar position. The request payload contains everything needed to make a *cork*: a signed combination of a chain ID, cellar ID (contract address), and an ABI encoded contract call. When Steward receives a request, it attempts to establish two-way trust via TLS 1.3 to verify that it is from an SP. It then validates that the SP is the trusted Publisher for updates to the target cellar address. Finally, steward builds a cork, signs it with the configured delegate key, and submits it to the either the [x/cork module](https://github.com/PeggyJV/sommelier/tree/main/x/cork) or [x/axelarcork module](https://github.com/PeggyJV/sommelier/tree/main/x/axelarcork) on chain depending on whether the Cellar is on Ethereum or another EVM chain respectively, where it will then be relayed to the target Cellar contract if a consensus of validators submit the same cork.
 
 
-> :bulb:  Steward authorizes function calls both by only supporting certain Cellar functions in its API, and by validating the target cellar before forwarding a call.
+> :bulb:  Steward authenticates via TLS 1.3 and authorizes via the (x/pubsub module)[https://github.com/peggyjv/sommelier/tree/main/x/pubsub] all requests to prevent malicious actors from controlling Cellars. Additionally, the Steward API limits the capabilities SPs have to functionality related to managing Cellar funds. They cannot execute withdrawals. 
 
 ## Quickstart
 
@@ -30,13 +30,13 @@ A few of the necessary fields required in this config TOML file are covered in t
 - [ ] On-disk key store containing a [delegate key](./02-StewardForValidators.md#cosmos-delegate-key) in this key store for Steward and Orchestrator to share. This can be generated with Steward, or you may have already done this step with `gorc` in the past. If that's the case you can just use the delegate key you’ve already created.
 - [ ] TLS 1.3 [server CA and certificate signed with said CA](./04-GeneratingCertificates.md)
 - [ ] [TOML config file](./01-Configuration.md#complete-example-configtoml) containing the above values
-- [ ] Add your Steward info (endpoint and CA) to the [Steward registry repository](https://github.com/peggyjv/steward-registry#steward-registry)
+- [ ] [Create a Subscriber](./05-PubsubForValidators.md#registering-steward-as-a-subscriber) on chain representing your steward's identity. *If your steward was in the Steward Registry before the v7 upgrade, it has already been included as a subscriber in the migration*.
 
 ### TLS Certificates
 
 Before SPs can establish a connection with your `steward` server, you will need to generate a CA, a TLS certificate signed by this CA, and the SP's client CA. These certificates must be TLS 1.3 compliant. For detailed steps please see the [Generating Certificates](./04-GeneratingCertificates.md) document.
 
-The paths to the generated certificates and the key used to create your signed server certificate must be configured in the `[server]` table of your [config file](./01-Configuration.md#server-table). Starting out, Seven Seas will be the sole SP, and Steward will use our client CA cert by default. This CA cert can be found in the `tls/` directory of this repo. There is no need to set the `client_ca_cert_path` configuration field at this time as it will default to the Seven Seas CA.
+The paths to the generated certificates and the key used to create your signed server certificate must be configured in the `[server]` table of your [config file](./01-Configuration.md#server-table). 
 
 ### Cosmos Delegate Key
 
@@ -52,4 +52,4 @@ The Cosmos delegate key generated (called "orchestrator" in the Sommelier docs)
 
 Other important configuration fields like your Sommelier node's endpoint are also required so that Steward knows where to send corks. Here is an [example configuration](./01-Configuration.md#complete-example-configtoml) you can use to get your config file started. Most of the fields have sensible defaults; you can use the [configuration reference](./01-Configuration.md#reference) to determine which fields you don't need to explicity set if you wish.
 
-Once your keys, certs, and config file are ready, and your Sommelier node is running, refer to the [Quickstart section](#quickstart) above to start Steward!
+Once your keys, certs, and config file are ready, you have [created a Subscriber](./05-PubsubForValidators.md#registering-steward-as-a-subscriber) on the x/pubsub module, and your Sommelier node is running, refer to the [Quickstart section](#quickstart) above to start Steward!

docs/05-PubsubForValidators.md

@@ -0,0 +1,75 @@
+# The x/pubsub Module for Validators
+
+Before Sommelier v7, the Steward Registry was used to record the CA and server endpoint of all steward processes. This database was then used by Strategy Providers (SPs) to send requests to each steward instance. 
+
+The Steward Registry has been deprecated in favor of a (mostly) generalized pubslisher/subscriber registry Cosmos SDK module, [x/pubsub](https://github.com/peggyjv/sommelier/tree/main/x/pubsub).
+
+For more information on x/pubsub itself, please refer to the [protocol documentation]()
+
+## Registering Steward as a Subscriber
+
+A `Subscriber` is an entity representing the identity of your steward instance. It contains your Sommelier delegate (orchestrator) address, server Certificate Authority, and the Steward server endpoint to which Strategy Providers (publishers) will send requests. 
+
+### Prerequisites
+
+- The latest `sommelier` binary release
+- Key, CA, and self-signed certificate generated using the steps in [the previous doc](./04-GeneratingCertificates.md).
+- Your  delegate (orchestrator) Sommelier address registered on the gravity module
+- A domain and port that will or already points to your steward server
+- Firewall configured to allow requests to the former
+
+### Steps
+
+A subscriber can be created using the following CLI command
+
+```bash
+sommelier tx pubsub add-subscriber <subscriber_address> [<ca_cert_file>] [<push_url>]
+```
+
+Where `subscriber_address` is your delegate (orchestrator) address, and `push_url` is your steward server endpoint including domain and port. The transaction must be signed by your delegate key.
+
+For example:
+
+```bash
+sommelier tx pubsub add-subscriber somm15yudhpkj8ztxrq29nr69qt79c9gmzrq5qtaqh0 server_ca.crt steward.example.com:5734
+```
+
+Note that even though the CA file and push URL args are "optional" in the command, they are *required* in order to facilitate Cellar calls from strategists.
+
+To update an existing subscriber, such as to replace an expired CA cert or change domains, simply run the same command for your delegate address with the new CA file and/or push URL. 
+
+If a subscriber needs to be altogether replaced, such as if a change in keys occurs, the old subscriber can be removed using the counterpart to the previous command:
+
+```bash
+sommelier tx pubsub remove-subscriber <subscriber_address>
+```
+
+Once again, the signer of the transaction must match the `subscriber_address` argument.
+
+## Overriding Default Subscriptions
+
+For convenience, default subscriptions exist in x/pubsub that map Cellar IDs to their agreed upon "default" publisher. Steward will load these subscriptions into its Publisher Trust Cache automatically once configured. It is possible that Sommelier participants may choose to delegate managing authority to a different publisher for a particular Cellar. This can be accomplished by creating a `SubscriberIntent`, whereby a validator registers their intent to receive requests for the target Cellar from an alternative publisher. Steward will override any default subscriptions in its cache with the respective subscriber intents registered by the owning validator.
+
+To create a subscriber intent use the following command:
+
+```bash
+sommelier tx pubsub add-subscriber-intent <subscription_id> <subscriber_address> <publisher_domain> 
+```
+
+Where subscription ID is the concatenated Chain ID and checksum contract address of the Cellar with a colon (:) inbetween. 
+
+For example, in order to subscribe to an alternative publisher for a Cellar 0x97e6e0a40a3d02f12d1cec30ebfbae04e37c119e on Arbitrum (chain ID 42161):
+
+```bash
+sommelier tx pubsub add-subscriber-intent 42161:0x97e6e0a40a3d02f12d1cec30ebfbae04e37c119e somm15yudhpkj8ztxrq29nr69qt79c9gmzrq5qtaqh0 alternative-strategist.example.com
+```
+
+Steward will now ignore function calls from the default publisher for the Arbitrum cellar at the provided contract address, and instead only process calls from the registered Publisher who owns the domain "alternative-strategist.example.com".
+
+Note that subscriber intents can only be added for permitted publishers. The domain provided must belong to a publisher that has been added on chain via a governance proposal.
+
+See the protocol docs for more details on the different entities in x/pubsub.
+
+## Blocking a Publisher
+
+In certain cases such as if a publisher's keys are compromised or the publisher has become malicious it is desirable to "block" requests from the publisher's domain. Simply add the publisher's registered domain to Steward's [publisher domain block list](https://github.com/PeggyJV/steward/blob/collin/v4-docs/docs/01-Configuration.md#publisher_domain_block_list)