Skip to content

Commit

Permalink
[docs] format and update docs from notion (#681)
Browse files Browse the repository at this point in the history 
* format: make pretty

* docs: update

* fix: doc images

* fix: remove link to notion docs, add Upgrade Setup doc
  • Loading branch information
@ErinHales
ErinHales authored Aug 31, 2021
1 parent d7fd9ce commit 84062f3
Show file tree
Hide file tree
Showing 16 changed files with 539 additions and 370 deletions.
248 changes: 129 additions & 119 deletions docs/agents/agent-operations.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
# Agent Operations

## Deployment Environments

There will exist several logical deployments of Optics to enable us to test new code/logic before releasing it to Mainnet. Each environment encompasses the various Home/Replica contracts deployed to many blockchains, as well as the agent deployments and their associated account secrets.
There will exist several logical deployments of Optics to enable us to test new code/logic before releasing it to Mainnet. Each environment encompasses the various Home/Replica contracts deployed to many blockchains, as well as the agent deployments and their associated account secrets.

The environments have various purposes and can be described as follows:
The environments have various purposes and can be described as follows:

### Development

Purpose: Allows us to test changes to contracts and agents. *Bugs should be found here.*
Purpose: Allows us to test changes to contracts and agents. *Bugs should be found here.*

- Deployed against testnets
- Agent Accounts: HexKeys stored in a secret manager for ease of rotation/access
Expand Down Expand Up @@ -45,161 +47,169 @@ At the outset, the Optics team will have full control over agent keys, and any c

### Provision KMS Keys

There exists a script in this repository (`rust/provision_kms_keys.py `) that facilitates KMS key provisioning for agent roles.
There exists a script in this repository (`rust/provision_kms_keys.py`) that facilitates KMS key provisioning for agent roles.

The script will produce a single set of keys per "environment." Where an __environment__ is a logical set of smart contract deployments. By default there are two environments configured, `staging` and `production` where `staging` is testnet deployments of the contracts and `production` corresponds to mainnet deployments.

The current strategy, in order to reduce complexity, is to use the same keys for transaction signing on both Celo and Ethereum networks. Should you desire, the key names to be provisioned can be modified such that the script creates unique keys per-network. Ex:
The current strategy, in order to reduce complexity, is to use the same keys for transaction signing on both Celo and Ethereum networks. Should you desire, the key names to be provisioned can be modified such that the script creates unique keys per-network. Ex:

```
```python
# Agent Keys
required_keys = [
"watcher-signer-alfajores",
"watcher-attestation-alfajores",
"watcher-signer-kovan",
"watcher-attestation-kovan",
"updater-signer-alfajores",
"updater-attestation-alfajores",
"updater-signer-kovan",
"updater-attestation-kovan",
"processor-signer-alfajores",
"processor-signer-kovan",
"relayer-signer-alfajores",
"relayer-signer-kovan"
"watcher-signer-alfajores",
"watcher-attestation-alfajores",
"watcher-signer-kovan",
"watcher-attestation-kovan",
"updater-signer-alfajores",
"updater-attestation-alfajores",
"updater-signer-kovan",
"updater-attestation-kovan",
"processor-signer-alfajores",
"processor-signer-kovan",
"relayer-signer-alfajores",
"relayer-signer-kovan"
]
```

#### Run the Key Provisioning Script
```

```bash
AWS_ACCESS_KEY_ID=accesskey AWS_SECRET_ACCESS_KEY=secretkey python3 provision_kms_keys.py
```

If the required keys are not present, the script will generate them. If they keys _are_ present, their information will be fetched and displayed non-destructively.

Upon successful operation, the script will output a table of the required keys, their ARNs, ETH addresses (for funding the accounts), and their regions.

#### Provision IAM Policies and Users
#### Provision IAM Policies and Users

This is an opinionated setup that works for most general agent operations use-cases. The same permissions boundaries can be achieved through different means, like using only [Key Policies](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)

Background Reading/Documentation:
- KMS Policy Conditions: https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.htm
- KMS Policy Examples: https://docs.aws.amazon.com/kms/latest/developerguide/customer-managed-policies.html
- CMK Alias Authorization: https://docs.aws.amazon.com/kms/latest/developerguide/alias-authorization.html
Background Reading/Documentation:

- [KMS Policy Conditions](https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.htm)
- [KMS Policy Examples](https://docs.aws.amazon.com/kms/latest/developerguide/customer-managed-policies.html)
- [CMK Alias Authorization](https://docs.aws.amazon.com/kms/latest/developerguide/alias-authorization.html)

The following sequence describes how to set up IAM policies staging and production deployments.
The following sequence describes how to set up IAM policies staging and production deployments.

- Create two users
- optics-signer-staging
- optics-signer-production
- kms-admin
- Save IAM credential CSV
- optics-signer-staging
- optics-signer-production
- kms-admin
- Save IAM credential CSV
- Create staging signer policies
- staging-processor-signer
- staging-relayer-signer
- staging-updater-signer
- staging-watcher-signer
- With the following policy, modified appropriately:
```
- staging-processor-signer
- staging-relayer-signer
- staging-updater-signer
- staging-watcher-signer
- With the following policy, modified appropriately:

```json
{
"Version": "2012-10-17",
"Statement": [
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "OpticsStagingPolicy",
"Effect": "Allow",
"Action": [
"kms:GetPublicKey",
"kms:Sign"
],
"Resource": "arn:aws:kms:*:11111111111:key/*",
"Condition": {
"ForAnyValue:StringLike": {
"kms:ResourceAliases": "alias/staging-processor*"
}
}
}
]
"Sid": "OpticsStagingPolicy",
"Effect": "Allow",
"Action": [
"kms:GetPublicKey",
"kms:Sign"
],
"Resource": "arn:aws:kms:*:11111111111:key/*",
"Condition": {
"ForAnyValue:StringLike": {
"kms:ResourceAliases": "alias/staging-processor*"
}
}
}
```
- production-processor-signer
- production-relayer-signer
- production-updater-signer
- production-watcher-signer
- With the following policy, modified appropriately:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "OpticsProductionPolicy",
"Effect": "Allow",
"Action": [
"kms:GetPublicKey",
"kms:Sign"
],
"Resource": "arn:aws:kms:*:11111111111:key/*",
"Condition": {
"ForAnyValue:StringLike": {
"kms:ResourceAliases": "alias/production-processor*"
}
}
}
]
}
```
- Create kms-admin policy
]
}
```

- production-processor-signer
- production-relayer-signer
- production-updater-signer
- production-watcher-signer
- With the following policy, modified appropriately:

```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "KMSAdminPolicy",
"Effect": "Allow",
"Action": [
"kms:DescribeCustomKeyStores",
"kms:ListKeys",
"kms:DeleteCustomKeyStore",
"kms:GenerateRandom",
"kms:UpdateCustomKeyStore",
"kms:ListAliases",
"kms:DisconnectCustomKeyStore",
"kms:CreateKey",
"kms:ConnectCustomKeyStore",
"kms:CreateCustomKeyStore"
],
"Resource": "*"
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": "kms:*",
"Resource": [
"arn:aws:kms:*:756467427867:alias/*",
"arn:aws:kms:*:756467427867:key/*"
]
"Version": "2012-10-17",
"Statement": [
{
"Sid": "OpticsProductionPolicy",
"Effect": "Allow",
"Action": [
"kms:GetPublicKey",
"kms:Sign"
],
"Resource": "arn:aws:kms:*:11111111111:key/*",
"Condition": {
"ForAnyValue:StringLike": {
"kms:ResourceAliases": "alias/production-processor*"
}
]
}
}
]
}
```

- Create kms-admin policy

```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "KMSAdminPolicy",
"Effect": "Allow",
"Action": [
"kms:DescribeCustomKeyStores",
"kms:ListKeys",
"kms:DeleteCustomKeyStore",
"kms:GenerateRandom",
"kms:UpdateCustomKeyStore",
"kms:ListAliases",
"kms:DisconnectCustomKeyStore",
"kms:CreateKey",
"kms:ConnectCustomKeyStore",
"kms:CreateCustomKeyStore"
],
"Resource": "*"
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": "kms:*",
"Resource": [
"arn:aws:kms:*:756467427867:alias/*",
"arn:aws:kms:*:756467427867:key/*"
]
}
]
}
```

- Create IAM groups
- staging-signer
- production-signer
- production-signer
- kms-admin
- Add previously created users to the corresponding groups
- optics-signer-staging -> staging-signer
- opticics-signer-production -> production-signer
- kms-admin -> kms-admin
- opticics-signer-production -> production-signer
- kms-admin -> kms-admin

## Funding Addresses

## Funding Addresses
Each agent should be configured with a unique wallet to be used to signing transactions and paying gas. This section describes the process of funding these signer wallets.
Each agent should be configured with a unique wallet to be used to signing transactions and paying gas. This section describes the process of funding these signer wallets.

Note: It is currently inadvisable to to run multiple Agent setups with the same set of Transaction Signers.
Note: It is currently inadvisable to to run multiple Agent setups with the same set of Transaction Signers.

### Steps
1. Generate KMS keys using instructions from the previous section.
2. Enumerate Signer Addresses via the table included as part of the output of `provision_kms_keys.py`, or via whatever method you used to generate keys.

1. Generate KMS keys using instructions from the previous section.
2. Enumerate Signer Addresses via the table included as part of the output of `provision_kms_keys.py`, or via whatever method you used to generate keys.
3. Send individual funding transactions to each address
- Note: 500 ETH should be sufficient for testnet addresses.
4. Edit deployment config to match new signers
5.
4. Edit deployment config to match new signers
18 changes: 10 additions & 8 deletions docs/architecture.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,12 @@

## Components

![https://s3-us-west-2.amazonaws.com/secure.notion-static.com/94390acd-d363-4abe-a3f6-c979f9e25a11/Optics-Architecture.svg](https://s3-us-west-2.amazonaws.com/secure.notion-static.com/94390acd-d363-4abe-a3f6-c979f9e25a11/Optics-Architecture.svg)
![Optics Architecture Diagram](./images/Optics-Architecture.svg)

Optics has several logical components:

- Home - The on-chain contract responsible for producing the message tree
- Replica - The on-chain contract responsible for replicating the message root on some other chain

- Updater - The off-chain participant responsible for submitting updates to the home chain
- Watcher - The off-chain participant responsible for observing a replica, and submitting fraud proofs to the home chain
- Relayer - The off-chain participant responsible for submitting updates to a replica
Expand All @@ -25,9 +24,10 @@ The home contract is responsible for managing production of the message tree and
3. Commit messages to the message tree
4. Maintain a queue of tree roots
5. Hold the updater bond
6. Slash on double-update proofs
7. Slash on improper update proofs
8. Future: manage updater rotation
6. Slash on double-update proofs (not implemented)
7. Slash on improper update proofs (not implemented)
8. Future: manage updater rotation/bond
9. Future: recover from `FAILED` state

#### Replica

Expand All @@ -40,7 +40,8 @@ The replica contract is responsible for managing optimistic replication and disp
5. Enforce the message format
6. Ensure messages are processed in order
7. Dispatch messages to their destination
8. Expose a "disconnect" feature
8. Expose a "disconnect" feature
9. Future: recover from `FAILED` state

### Off-chain (Agents)

Expand All @@ -50,7 +51,8 @@ The updater is responsible for signing attestations of new roots. It is an off-c

1. Observe the home chain contract
2. Sign attestations to new roots
3. Publish the signed attestation to the home chain
3. Publish the signed attestation to the home chain
4. Future: manage Updater bond

#### Watcher

Expand Down Expand Up @@ -81,4 +83,4 @@ The processor proves the validity of pending messages and sends them to end reci
3. Maintain local merkle tree with all leaves
4. Observe 1 or more replicas
5. Maintain list of messages corresponding to each leaf
6. Dispatch proven messages to end recipients
6. Dispatch proven messages to end recipients
Loading

0 comments on commit 84062f3

Please sign in to comment.