docs: dev-info, architecture and more (#68)

README.md

@@ -15,75 +15,13 @@ You can find project information and contribute to the project here: https://dor
 ## Current status
 The project is under development and is not yet ready for production use.
 
-## Interchain Attestation
+For a more detailed roadmap, see the [GitHub project board](https://github.com/orgs/cosmos/projects/35)
 
-Interchain Attestation enables IBC connectivity (with no intermediary chains) with any chain where you can't/don't have a light client.
+## Documentation
 
-Interchain Attestation solves the problem where you can't, for whatever reason, trust the counterparty with a "normal" light client. 
-Instead, it allows a chain's validators to attest to the state of the counterparty - moving the security to someone you already trust.
+The documentation contains information about the project, how to build and test it, as well as how to use it.
 
-![No IBC for you.png](docs/images/No%20IBC%20for%20you.png)
-
-This enables any chain to connect with IBC, as long as it can implement the IBC protocol (e.g. smart contracts), 
-and the validators using Interchain Attestation are attesting to the state of the counterparty IBC implementation.
-
-![Attestion enables IBC.png](docs/static/img/attestation-enables-ibc.png)
-
-Interchain Attestion is based on using validators with existing economic security to attest to the state of the counterparty chain.
-We move the security assumption over to the receiving validator set (e.g. Cosmos Hub/Osmosis/whatever), away from the one we can't trust (like a single sequencer).
-
-![Attest.png](docs/images/Attest.png)
-
-In addition, the Attestation light client is based on attesting to IBC packets, rather than full state.
-This makes it much easier to implement new chains and support consensus algorithms that doesn't (yet?) have a light client implementation.
-
-The Attestation light client verifies the signatures of the attestors (validators) and stores the packet commitments to be able to verify the packet later.
-
-![Packet commitments.png](docs/images/Packet%20commitments.png)
-
-Not all scenarios warrant all validators running a full node and attesting to every chain it connects to, 
-so Interchain Attestation also has a config module that allows for configurable security requirements.
-
-The architecture is using a combination of a sidecar process, ABCI++ Vote Extensions, and a light client to enable the attestation process.
-
-![High level architecture.png](docs/static/img/architecture.png)
-
-A talk about the project can be found here: https://www.youtube.com/watch?v=loNyUjSgR8M
-
-## Development
-
-### Prerequisites
-
-TODO: Add rest of prerequisites
-
-* Just
-* Go
-* Docker (for e2e tests)
-* golangci-lint
-
-### Testing
-
-Each module has a unit test suite that can be run with `make test`.
-
-You can also run all unit tests with for all modules with `just test-unit`.
-
-In addition, there is an e2e test suite that can be run using `just test-e2e`.
-The recipe takes an optional argument for which image-versions (docker tag) to use (e.g. `just test-e2e latest`).
-If no argument is provided, it will default to `local` and also build the docker images locally with the local tag.
-
-### Linting
-
-You can lint all modules with `just lint`.
-
-### Proto generation
-
-If you make changes to the proto files, you need to regenerate the go code with `just proto-gen` (or `make proto-gen` in the module directories).
-
-### Running locally
-
-You can spin up a local testnet using `make serve` (under `testing/`. This spins up two chains, configures a sidecar process, and sets up an IBC connection with clients, connections and channels.
-
-To stop all the processes, run `make kill-all`.
+You can find the documentation here: [Interchain Attestation Documentation](https://interchain-attestation.io)
 
 ## Background
 

core/Makefile

@@ -8,11 +8,8 @@ export GO111MODULE = on
 ###                                  Build                                  ###
 ###############################################################################
 
-build-sidecar:
-	go build -mod=readonly -o build/ ./sidecar
-
-install-sidecar:
-	go install -mod=readonly ./sidecar
+build:
+	go build -mod=readonly ./...
 
 ###############################################################################
 ###                               	Utilities                               ###
@@ -43,8 +40,7 @@ proto-all: proto-format proto-lint proto-gen
 
 proto-gen:
 	@echo "Generating Protobuf files"
-	@$(protoImage) sh ./scripts/protocgen.sh
-	@go mod tidy
+	$(protoImage) ls -la#@go mod tidy
 
 proto-format:
 	@$(protoImage) find ./ -name "*.proto" -exec clang-format -i {} \;

docs/docs/architecture/architecture.md

@@ -1,30 +1,10 @@
 ---
 sidebar_position: 2
+title: Architecture
 ---
 
 # Architecture
 
-Interchain Attestation is composed of a few different components that work together to let validators safely attest to the state of a counterparty chain. 
-The main components, in "chronological order" are:
-* Attestation Config Module
-  * Validators register their signing keys
-  * Chains/clients are registered for attestation with configuration details 
-* Attestation Sidecar
-  * Validators run a sidecar that reads counterparty chain information, and generates signed attestations
-  * The sidecar also hosts a GRPC server that can be queried for attestations (used by the chain node to fetch attestations during vote extensions)
-* Vote Extensions
-  * Uses the ABCI++ interface with vote extensions to fetch attestations from the sidecar
-  * Attestations are aggregated from all the validators, and sent to the light client for verification and client updates
-* Attestation Light Client
-  * The IBC light client that uses the attestation data to enable IBC connections
-  * The light client verifies the attestations and updates the client state and consensus state with packet commitments
-* Testing
-  * In addition there are some development tools used to test the system: interchaintest and some simapps integrated with the above components
-
-![architecture.png](../../static/img/architecture.png)
-
-## Flow
-
-TODO: Add a diagram
-
+This section desribes the architecture, modules and flow of Interchain Attestation.
 
+A good place to start is the [System Architecture and Flow page](./system-architecture-and-flow).

docs/docs/architecture/attestation-data.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # Attestation Data

docs/docs/architecture/configmodule.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 ---
 
 # Attestation Config Module

docs/docs/architecture/light-client.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # Attestation Light Client

docs/docs/architecture/sidecar.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # Attestation Sidecar

docs/docs/architecture/system-architecture-and-flow.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 1
+---
+
+# System Architecture and Flow
+
+## Component Overview
+
+Interchain Attestation is composed of a few different components that work together to let validators safely attest to the state of a counterparty chain.
+The main components, in "chronological order" are:
+* Attestation Config Module
+    * Validators register their signing keys
+    * Chains/clients are registered for attestation with configuration details
+* Attestation Sidecar
+    * Validators run a sidecar that reads counterparty chain information, and generates signed attestations
+    * The sidecar also hosts a GRPC server that can be queried for attestations (used by the chain node to fetch attestations during vote extensions)
+* Vote Extensions
+    * Uses the ABCI++ interface with vote extensions to fetch attestations from the sidecar
+    * Attestations are aggregated from all the validators, and sent to the light client for verification and client updates
+* Attestation Light Client
+    * The IBC light client that uses the attestation data to enable IBC connections
+    * The light client verifies the attestations and updates the client state and consensus state with packet commitments
+* Testing
+    * In addition, there are some development tools used to test the system: interchaintest and some simapps integrated with the above components
+
+![architecture.png](../../static/img/architecture.png)
+
+## Flow
+
+### Before packets can flow
+
+A few things need to happen before packets can flow between chains:
+1. The Attestation Light Client, Vote Extensions and Attestation Config Module is integrated with the chain
+    * To learn more about how to integrate into your chain, see the [Integration Guide](../integration-guide) 
+2. Clients are created on both chains, and registered with the Attestation Config Module
+    * ⚠️For v1, pre-Eureka, we also need to create connections and channels. 
+    * In v2, only IBC Eureka is supported, and connections and channels are finally a thing of the past.
+3. Validators are registered with their attestation signing keys on the Attestation Config Module
+4. Sufficient Validators have signed up to attest to the counterparty chain (if the configuration requires it)
+5. Validators have configured and started up their Attestation Sidecar process
+
+### Normal operation
+
+At this point, we have clients on both chains, and validators who are expected to attest to the counterparty chain.
+
+The flow of the system for the client to get updated is as follows:
+1. The sidecar process reads all configured counterparty chain states, generates attestations, signs them and stores them in the sidecar database
+2. The ABCI++ Vote Extensions query the sidecar for the latest attestations
+3. The Vote Extensions aggregate the attestations from all the validators, and send them to the light client
+4. The light client verifies the attestations, and updates the client state and consensus state with the packet commitments
+
+We now have a light client that can verify packet commitments, and IBC can flow between the chains.
+
+TODO: Add a diagram
+
+TODO: Write about relaying

docs/docs/architecture/vote-extensions.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # Vote Extensions

docs/docs/developing/building.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 2
+---
+
+# Building
+
+## Building all the modules
+
+To build all the modules, you can use the following command:
+
+```bash
+$ just build
+```
+
+## Linting
+
+To lint all the modules, you can use the following command:
+
+```bash
+$ just lint
+```
+
+## Proto
+
+To generate go code for all the proto files, you can use the following command:
+
+```bash
+$ just proto-gen
+```
+
+## Docker images (used for testing)
+
+There is a set of docker images used for the e2e tests. To build these images, you can use the following command:
+
+```bash
+$ just build-docker-images
+```
+
+## Simapps
+
+If you want to build and install the simapp binaries locally, you can use the following command:
+
+```bash
+just install-simapps
+```
+
+## Running locally
+
+There is a command that spins up a local test environment with the following components:
+* Simapp (Cosmos SDK chain with Interchain Attestion integrated)
+* Rollupsimapp (Rollkit rollup)
+* Mock DA service (for the rollup)
+* Sidecar
+* Configuration
+  * Light clients
+  * Connections
+  * Channels
+  * Validator registered and wired up to Interchain Attestation
+
+To run this environment, you can use the following command:
+```bash
+just serve
+```

docs/docs/developing/developing.md

@@ -4,4 +4,8 @@ sidebar_position: 5
 
 # Developing
 
-TODO: Document how to set up a development environment, how to run tests, etc.
+To get started developing, take a look at the [prerequisites](prerequisites.md) you need to have installed.
+
+Then, you can build the project by following the [building](building.md) instructions.
+
+Once you have built the project, you can run the tests by following the [testing](testing.md) instructions.

docs/docs/developing/prerequisites.md

@@ -0,0 +1,12 @@
+---
+sidebar_position: 1
+---
+
+# Prerequisites
+
+The main prerequisites for developing Interchain Attestation are:
+* Just
+* Go
+* Docker (for e2e tests)
+* golangci-lint
+* make (still, but it is being phased out for just)

docs/docs/developing/testing.md

@@ -1,7 +1,24 @@
 ---
-sidebar_position: 1
+sidebar_position: 3
 ---
 
 # Testing
 
-TODO: Document the test setup, how to run them, etc
+## Unit tests
+
+To run all unit tests for all modules, you can use the following command:
+
+```bash
+$ just test-unit
+```
+
+## End-to-end tests
+
+To run all end-to-end tests for all modules, you can use the following command:
+
+```bash
+$ just test-e2e
+```
+
+The recipe takes an optional argument for which image-versions (docker tag) to use (e.g. `just test-e2e latest`).
+If no argument is provided, it will default to `local` and also build the docker images locally with the local tag.

docs/docs/integration-manual/integration-manual.md → docs/docs/integration-guide/integration-guide.md

@@ -2,6 +2,6 @@
 sidebar_position: 3
 ---
 
-# Integration Manual
+# Integration Guide
 
 TODO: Document how to integrate with a chain, how to register chains etc.

docs/docs/intro.md

@@ -12,4 +12,22 @@ Ethereum, Solana, and more.
 The system enables any chain to connect with IBC, as long as it can implement the IBC protocol (e.g. smart contracts),
 and the validators using Interchain Attestation are attesting to the state of the counterparty IBC implementation.
 
-![Attestation enables IBC](../static/img/attestation-enables-ibc.png)
+![Attestation enables IBC](../static/img/attestation-enables-ibc.png)
+
+## How it works
+
+High level, Interchain Attestation uses the validators to attest to the state of the counterparty chain. The validators
+are running a sidecar process, and a full node of the counterparty chain. The sidecar process reads the state of the
+counterparty chain, and the full node validates the state of the counterparty chain. The validators then sign the
+attestation, and the attestation is fetched, validated and aggregated by the node binary using ABCI++ Vote Extensions.
+
+![How it works on a high level](../static/img/attest.png)
+
+To dive deeper into how everything works, see the [architecture](./architecture) pages.
+
+A talk about the project from Modular Summit (this was before the name change from Pessimistic Validation to Interchain Attestation) can be found here:
+<iframe width="560" height="315" src="https://www.youtube.com/embed/loNyUjSgR8M?si=7fs9pqlKhuP7gHVx" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+TODO: Use cases (maybe a separate page?)
+
+TODO: Links to other pages (for validators, for chain developers, etc.)

docs/docs/roadmap.md

@@ -0,0 +1,12 @@
+---
+sidebar_position: 6
+---
+
+# Roadmap
+
+The current roadmap is split into two versions, with distinct support IBC Classic and IBC Eureka.
+
+* v1: IBC Classic
+* v2: IBC Eureka
+
+For a more detailed roadmap, see the [GitHub project board](https://github.com/orgs/cosmos/projects/35)