document: deploy procedure (#712)

* document: deploy procedure

* document: link to docs folder in README

* Docs Changes

* document: update link to agent-operations doc

Co-authored-by: Conner Swann <me@connerswann.me>

README.md

@@ -23,7 +23,7 @@ In other words, Optics is designed to prioritize:
   cryptography.
 - Ease of use: Simple interface for maintaining xApp connections.
 
-You can read more about Optics' architecture [at Celo's main documentation site](https://docs.celo.org/celo-codebase/protocol/optics).
+You can read more about Optics' architecture [at Celo's main documentation site](https://docs.celo.org/celo-codebase/protocol/optics) or [within the docs folder of this repository](./docs/README.md).
 
 ## Integrating with Optics
 
@@ -97,6 +97,7 @@ Note: In the event you need to bypass the pre-commit hooks, pass the
    ```
 
 2. Setup your `.env` files
+
    ```bash
    cd typescript/optics-deploy
    touch .env && cat .env.example > .env
@@ -105,6 +106,7 @@ Note: In the event you need to bypass the pre-commit hooks, pass the
    cd ../optics-xapps
    touch .env && cat .env.example > .env
    ```
+
    Then, add values to the keys in the newly created `.env` files.
 
 3. Install jq
@@ -136,10 +138,10 @@ Note: In the event you need to bypass the pre-commit hooks, pass the
 
 There exists a docker build for the agent binaries. These docker images are used for deploying the agents in a production environment.
 
-```
-$ cd rust
-$ ./build.sh <image_tag>
-$ ./release.sh <image_tag>
+```bash
+cd rust
+./build.sh <image_tag>
+./release.sh <image_tag>
 ```
 
 # What is Optics?
@@ -208,4 +210,24 @@ The timeout on new updates to the replica serves two purposes:
 2. It gives message recipients a chance to opt-out of message processing for
    the update. If an incorrect update is published, recipients always have the
    information necessary to take defensive measures before any messages can be
-   processed.
+   processed.\
+
+## Deploy Procedure
+
+The contract addresses of each deploy can be found in `rust/config`. The latest
+deploy will be at `rust/config/[latest timestamp]` with bridge contracts within
+that same folder under `/bridge/[latest timestamp]`.
+
+The agents are setup to point at 2 environments at a time: `deployment` and
+`staging`.
+
+When agents are deployed to point at a new environment, they cease to point at
+the old ones. We **do not** continue to operate off-chain agents on old contract
+deploys. Contracts not supported by the agents will cease to function (i.e.
+messages will not be relayed between chains).
+
+Off-chain agents are **not** automatically re-deployed when new contract deploys
+are merged. Auto-redeploys will be implemented at some future date.
+
+The Optics team will maintain a document [here](./docs/agents/agent-operations)
+that will specify the contracts supported by the rust agents.

docs/README.md

@@ -1,5 +1,21 @@
 # Optics: OPTimistic Interchain Communication
 
+## Table of Contents
+
+- [Frequently Asked Questions](./faq.md)
+- [Architecture](./architecture.md)
+- [Upgrade Setup](./upgrade-setup.md)
+- [Versioning](./versioning.md)
+- **xApps**
+  - [Developing xApps](./xapps/developing.md)
+  - [Token Bridge xApp](./xapps/token-bridge.md)
+- **Governance**
+  - [Cross-Chain Governance](./governance/cross-chain-governance.md)
+- **Agents**
+  - [Agent Operations](./agents/agent-operations.md)
+- [Failure Cases](./failure-cases.md)
+- [Contributing To This Repo](./contributing.md)
+
 ## What is Optics?
 
 Optics is a new design for radically cheaper cross-chain communication *without header verification.* We expect operating Optics to cut 90% of costs compared to a traditional header relay.

docs/agents/agent-operations.md

@@ -17,6 +17,10 @@ Purpose: Allows us to test changes to contracts and agents. *Bugs should be foun
 - Agent Deployments: Automatic, continuous deployment
 - Contract Deployments: Automatic, with human intervention required for updating the **upgradeBeacon**.
 
+**Current Dev Contract Deployment:**
+
+[1630513764971](../rust/config/1630513764971/)
+
 ### Staging
 
 Purpose: Allows us to test the full-stack integration, specifically surrounding the KMS access control and federated secret management. *Issues with process should be found here.*
@@ -28,6 +32,10 @@ Purpose: Allows us to test the full-stack integration, specifically surrounding
 - Agent Deployments: Determined by whoever is running the agents
 - Contract Deployments: Automatic, with human intervention required for updating the **upgradeBeacon**.
 
+**Current Staging Contract Deployment:**
+
+[1629743021549](../rust/config/1629743021549/)
+
 ### Production
 
 Purpose: Where the magic happens, **things should not break here.** 
@@ -39,6 +47,10 @@ Purpose: Where the magic happens, **things should not break here.**
 - Agent Deployments: Determined by whoever is running the agents
 - Contract Deployments: ***Manual*** - Existing tooling can be used, but deploys will be gated and require approval as contract deployments are expensive on Mainnet.
 
+**Current Production Contract Deployment:**
+
+[Not Deployed](#)
+
 ## Key Material
 
 Keys for Staging and Production environments will be stored in AWS KMS, which is a highly flexible solution in terms of granting access. It guarantees nobody will ever have access to the key material itself, while still allowing granular permissions over access to remote signing. 

docs/architecture.md

@@ -2,7 +2,7 @@
 
 ## Components
 
-![Optics Architecture Diagram](./images/Optics-Architecture.svg)
+![Optics Architecture Diagram](./images/Optics-Architecture.png)
 
 Optics has several logical components: