Filling out protocol docs

SUMMARY.md

@@ -38,8 +38,8 @@
 
 ## Protocol
 
-* [How does the protocol work?](protocol/how-does-the-protocol-work.md)
+* [Overview](protocol/overview.md)
 * [Validators](protocol/validators.md)
 * [Gravity Bridge](protocol/gravity-bridge.md)
 * [Steward](protocol/steward.md)
-* [Auction module and participation](protocol/auction-module-and-participation.md)
+* [Fee Auctions](protocol/fee-auctions.md)

protocol/overview.md

@@ -0,0 +1,36 @@
+# Sommelier Protocol Overview
+
+Sommelier is a platform for running arbitrary strategies expressed through special smart contract vaults called Cellars. Sommelier can run Cellars on many different chains, and any user can deposit to a Cellar and provide capital for the strategy to utilize and share in the its performance. Cellars may accrue fees, flat or performance-based, for strategists and the Sommelier protocol. Fees earned by the Sommelier protocol are converted to SOMM tokens and distributed to Sommelier stakers.
+
+The Sommelier protocol is architected to minimized trust and maintain decentralization at every step: 
+
+- Strategists do not have direct control over Cellar contracts, but instead must express call data recommendations for the Sommelier chain to evaluate and sign itself
+- Only a limited set of functions are exposed to strategists through the strategist API to minimize their ability to act maliciously 
+- Users interact directly with the Cellar contracts on their respective chains to deposit and withdraw and thus do not have to expose their funds to a bridge 
+- Sommelier validators have granular control over which strategists they are willing to accept call data from for each Cellar, creating a marketplace for strategies
+- Relaying of contract calls from the Sommelier chain the the actual Cellar contract is permissionless 
+- Governance, made up of SOMM stakers, controls the addition of new Cellars, which blockchains they can run on, authorization of strategists, and all other chain-specific aspects of the protocol.
+
+## Components
+
+To accomplish these features requires a somewhat complex architecture, the components of which are:
+
+- *Cellar smart contracts*: The actual vault contracts existing on their respective blockchains
+- *Bridges*: An in-house Gravity bridge fork and [Axelar General Message Passing](https://docs.axelar.dev/dev/general-message-passing/overview) are leveraged for relaying contract calls to Cellars
+- *The Sommelier blockchain*: The Cosmos SDK chain at the heart of the system with the sole authority to originate contract calls to Cellars.
+- *Steward*: A sidercar process run by validators that exposes the strategist API to strategists, a Cellar call authentication and authorization layer
+
+Additionally strategists may coordinate with the Sommelier team to run peripheral smart contracts that interact with the frontend for things like Cellar share staking incentives. 
+
+## Strategy Computation
+
+Sommelier puts no restrictions on the systems use to make decisions about Cellar rebalancing recommendations. Strategists may use their own alpha by running arbitrary computations based on real-time market data to make the recommended Cellar calls via the strategist API.
+
+This architecture enables vaults that are far superior to the typical static vault which rebalances deposits to the same allocation regardless of market conditions.
+
+## More Information
+
+- [Strategist Onboarding]()
+- [Validator Onboarding]()
+
+[other protocol outline links]()

protocol/steward.md

@@ -1,29 +1,36 @@
 # Steward
 
-Steward provides the interface strategists use to manage Cellar contracts. Each validator runs their own instance of the Steward process and receives contract call data over an authenticated connection. After confirming the caller's authorization to interact with the target contract, Steward submits the call to the Sommelier chain. A quorum of these submissions must occur on chain in order for any call to be finally executed on the target contract. This model allows strategists to have access to contract functionality necessary to manage investment while preventing a malicious or compromised strategist from having direct access to user funds. 
+Steward exposes the Strategist API, an interface strategists use to manage Cellar contracts. Each validator runs their own instance of the Steward process and receives contract call data over an authenticated connection. After confirming the caller's authorization to interact with the target contract, Steward submits the call to the Sommelier chain. A quorum of these submissions must occur on chain in order for any call to be finally executed on the target contract. This model allows strategists to have access to contract functionality necessary to manage Cellar positions while preventing a malicious or compromised strategist from having direct access to user funds. 
 
 Documentation for the current version of steward can be found here:
 
-[https://github.com/PeggyJV/steward/tree/3.x-main/docs](https://github.com/PeggyJV/steward/tree/3.x-main/docs)
+[https://github.com/PeggyJV/steward/tree/main/docs](https://github.com/PeggyJV/steward/tree/main/docs)
 
 ### Deployment
 
-Unlike most chains, Sommelier requires a server API sidecar process (Steward) to be accessible from the internet. Communications to Steward are protected using mutually-authenticated TLS. During our bootstrapping phase, Steward has a harcoded certificate authority to allow Seven Seas client certificates, though the protocol will be expanded to allow new strategist integrators via governance in the v7 upgrade, which will also include an authorization layer mapping specific strategist integrators with the cellar addresses for which they have been approved. For validators, they must create their own self-signed CA and server certificates by following the instructions in the "steward-registry" repo and adding their data via pull request:
+For a detailed guide to deploying steward for a validator node, please see the [Steward for Validators](https://github.com/PeggyJV/steward/blob/main/docs/02-StewardForValidators.md) documentation.
 
-[https://github.com/PeggyJV/steward-registry](https://github.com/PeggyJV/steward-registry)
+### Strategist API
 
-The v7 upgrade will also provide a method for handling this on-chain and will remove the necessity of the registry.
+Steward defines an [API using protobuf](https://github.com/PeggyJV/steward/blob/main/proto/steward/v4/steward.proto) of Cellar functionality available to strategists. The API is exposed as a gRPC interface. It does not accept raw encoded Ethereum calls, but rather accepts the parameters of function calls and handles the encoding itself, to ensure only authorized functions and in some cases bounded values are used. Existing Sommelier cellars are built using a specific architecture developed by a team of smart contract developers the protocol team has coordinated with, but any new cellar architecture approved by governance can be supported. However, due to the nature of how the API permissions and encodes cellar calls, code updates to Steward and a subsequent validator update of the Steward process is necessary before a new cellar architecture will be functional.
 
-The Steward server process must be on a publicly available port, the default of which is 5734, but can be changed as necessary. The fully qualified URL and port number to access your steward instance should be included in your steward-registry pull request.
+### Steward Registry (Pubsub module)
 
-### API
+The Sommelier chain runs the `x/pubsub` module which acts as a registry of strategists (Publishers), steward instances (Subscribers), and subscriptions. Subscriptions are the mapping between a strategist's registered intent to publish call data for a particular Cellar (subscription ID) and a steward's desire to receive call data from a particular strategist. 
 
-Steward's API is a GRPC interface which exposes a defined subset of contract functionality as protobufs. It does not accept raw encoded Ethereum calls, but rather accepts the parameters of function calls and handles the encoding itself, to ensure only authorized functions and in some cases bounded values are used. Existing Sommelier cellars are built using a specific architecture developed by a team of smart contract developers the protocol team has coordinated with, but any new cellar architecture approved by governance can be supported. However, due to the nature of how the API permissions and encodes cellar calls, code updates to Steward and a subsequent validator update of the Steward process is necessary before a new cellar architecture will be functional.
+The pubsub module define a number of entities that represent the different participants and their intentions in the Sommelier protocol:
 
-### Strategists
+`Publisher` - Represents a Strategist. Contains the domain from which they will submit contract calls, their self-signed Certificate Authority, and the somm address representing their on-chain identity.
 
-Strategists must submit calls to each validator's Steward instance using the defined GRPC API. In order for a call to be made to an Ethereum cellar, these updates must be sent to the Steward instance's of a consensus power of validators. The current architecture defines a periodic voting window every 10 blocks, and the strategist should submit their calls at the beginning of this window to allow for some latency. A call that reverts will remain in the gravity module until it times out, and depending on the revert being either transient or permanent, it may be retried at any time until it times out. The current timeout period is expected to be roughly 12 hours. The v7 upgrade will modify some of these requirements, and rather than timing submissions during voting windows, calls will execute at a height specified by the strategist.
+`Subscriber` - Represents a steward instance. Contains the endpoint of the Steward server that Publishers make calls to, its self-signed Certificate Authority, and its somm address.  
 
-The list of Steward endpoints for each validator can be found in the steward-registry:
+`PublisherIntent` - Represents a Cellar for a which a strategist intends to submit calls. Defines a "subscription ID" which is the chain ID where the Cellar resides and the contract address of the cellar concatenated with a ':' (e.g. "42161:0xC47bB288178Ea40bF520a91826a3DEE9e0DbFA4C" is RY ETH on Arbitrum).
+
+`SubscriberIntent` - Represents an a steward's intent to listen to a Publisher for calls to a particular Cellar.
+
+`DefaultSubscriptions` - Represents the default publisher stewards should accept calls from for a particular Cellar. Strategists use Default Subscritions in combination with SubscriberIntents to get an accurate list of steward server endpoints to which they should publish calls.
+
+Publishers who create the original Cellar approval proposal for a particular Cellar are the "default" publisher, and all steward instances will automatically trust this Publisher for that particular Cellar. However, it is entirely possible for enough consensus power to configure their steward to listen to an alternative strategist for any number of Cellars.
+
+New or migrating validators must [add or update a Subscriber](https://github.com/PeggyJV/steward/blob/main/docs/05-PubsubForValidators.md#registering-steward-as-a-subscriber) on chain so that their steward instance is reachable.
 
-[https://github.com/PeggyJV/steward-registry](https://github.com/PeggyJV/steward-registry)

protocol/validators.md

@@ -31,9 +31,9 @@ Steward can be found here:\
 
 With documentation found here:\
 \
-[https://github.com/PeggyJV/steward/tree/3.x-main/docs](https://github.com/PeggyJV/steward/tree/3.x-main/docs)
+[https://github.com/PeggyJV/steward/tree/main/docs](https://github.com/PeggyJV/steward/tree/main/docs)
 
-#### Strategist server
+#### Strategist API server
 
 Strategists do not need to run code on-chain -- they can use machine learning, big data, or any other number of systems, and then submit their update recommendations based on their proprietary technology and algorithms. In order to make this possible, each validator must run a strategist server by which a strategist can communicate their update recommendations for approval by the validator set. The reference implementation of this server is called Steward, which by default takes these recommendations at face value and executes them.
 
@@ -50,7 +50,7 @@ Steward can be found here:\
 
 With documentation found here:\
 \
-[https://github.com/PeggyJV/steward/tree/3.x-main/docs](https://github.com/PeggyJV/steward/tree/3.x-main/docs)
+[https://github.com/PeggyJV/steward/tree/main/docs](https://github.com/PeggyJV/steward/tree/main/docs)
 
 ### Slashing
 
@@ -60,9 +60,9 @@ During the testing, bootstrapping, and proof of concept phases of the Sommelier
 
 ### Communication channels
 
-Telegram channel: how to get an invite link here?
+Telegram channel:
+[https://t.me/+wLi1PfO7SjE0MTZh](https://t.me/+wLi1PfO7SjE0MTZh)
 
-Discord server:\
-\
+Discord server:
 [https://discord.com/invite/ZcAYgSBxvY](https://discord.com/invite/ZcAYgSBxvY)