diff --git a/README.md b/README.md index 3ff74c4..61d60dd 100644 --- a/README.md +++ b/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 diff --git a/core/Makefile b/core/Makefile index c2870c9..e3aec1a 100644 --- a/core/Makefile +++ b/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 {} \; diff --git a/docs/docs/architecture/architecture.md b/docs/docs/architecture/architecture.md index 420838b..e80357f 100644 --- a/docs/docs/architecture/architecture.md +++ b/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). diff --git a/docs/docs/architecture/attestation-data.md b/docs/docs/architecture/attestation-data.md index 76382d8..9c708c8 100644 --- a/docs/docs/architecture/attestation-data.md +++ b/docs/docs/architecture/attestation-data.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 --- # Attestation Data diff --git a/docs/docs/architecture/configmodule.md b/docs/docs/architecture/configmodule.md index f963f31..e431d3a 100644 --- a/docs/docs/architecture/configmodule.md +++ b/docs/docs/architecture/configmodule.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 2 --- # Attestation Config Module diff --git a/docs/docs/architecture/light-client.md b/docs/docs/architecture/light-client.md index e8a6375..6a8c3eb 100644 --- a/docs/docs/architecture/light-client.md +++ b/docs/docs/architecture/light-client.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 --- # Attestation Light Client diff --git a/docs/docs/architecture/sidecar.md b/docs/docs/architecture/sidecar.md index f04bdd0..d14d485 100644 --- a/docs/docs/architecture/sidecar.md +++ b/docs/docs/architecture/sidecar.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 --- # Attestation Sidecar diff --git a/docs/docs/architecture/system-architecture-and-flow.md b/docs/docs/architecture/system-architecture-and-flow.md new file mode 100644 index 0000000..0d054d9 --- /dev/null +++ b/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 diff --git a/docs/docs/architecture/vote-extensions.md b/docs/docs/architecture/vote-extensions.md index e48adea..0dc5605 100644 --- a/docs/docs/architecture/vote-extensions.md +++ b/docs/docs/architecture/vote-extensions.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 --- # Vote Extensions diff --git a/docs/docs/developing/building.md b/docs/docs/developing/building.md new file mode 100644 index 0000000..47af0fc --- /dev/null +++ b/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 +``` diff --git a/docs/docs/developing/developing.md b/docs/docs/developing/developing.md index 8b9ca65..8ab2a47 100644 --- a/docs/docs/developing/developing.md +++ b/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. \ No newline at end of file +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. diff --git a/docs/docs/developing/prerequisites.md b/docs/docs/developing/prerequisites.md new file mode 100644 index 0000000..a7dc51e --- /dev/null +++ b/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) diff --git a/docs/docs/developing/testing.md b/docs/docs/developing/testing.md index ff2565b..251c0ff 100644 --- a/docs/docs/developing/testing.md +++ b/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 \ No newline at end of file +## 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. diff --git a/docs/docs/integration-manual/integration-manual.md b/docs/docs/integration-guide/integration-guide.md similarity index 83% rename from docs/docs/integration-manual/integration-manual.md rename to docs/docs/integration-guide/integration-guide.md index e4a3e66..c54f495 100644 --- a/docs/docs/integration-manual/integration-manual.md +++ b/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. \ No newline at end of file diff --git a/docs/docs/intro.md b/docs/docs/intro.md index bf3643a..bf9ca45 100644 --- a/docs/docs/intro.md +++ b/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) \ No newline at end of file +![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: + + +TODO: Use cases (maybe a separate page?) + +TODO: Links to other pages (for validators, for chain developers, etc.) \ No newline at end of file diff --git a/docs/docs/roadmap.md b/docs/docs/roadmap.md new file mode 100644 index 0000000..4607139 --- /dev/null +++ b/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) diff --git a/docs/src/components/HomepageFeatures/index.js b/docs/src/components/HomepageFeatures/index.js deleted file mode 100644 index f54ddb2..0000000 --- a/docs/src/components/HomepageFeatures/index.js +++ /dev/null @@ -1,61 +0,0 @@ -import clsx from 'clsx'; -import Heading from '@theme/Heading'; -import styles from './styles.module.css'; - -const FeatureList = [ - { - title: 'TODO', - Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default, - description: ( - <> - TODO - - ), - }, - { - title: 'TODO', - Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default, - description: ( - <> - TODO - - ), - }, - { - title: 'TODO', - Svg: require('@site/static/img/undraw_docusaurus_react.svg').default, - description: ( - <> - TODO - - ), - }, -]; - -function Feature({Svg, title, description}) { - return ( -
-
- -
-
- {title} -

{description}

-
-
- ); -} - -export default function HomepageFeatures() { - return ( -
-
-
- {FeatureList.map((props, idx) => ( - - ))} -
-
-
- ); -} diff --git a/docs/src/components/HomepageFeatures/styles.module.css b/docs/src/components/HomepageFeatures/styles.module.css deleted file mode 100644 index b248eb2..0000000 --- a/docs/src/components/HomepageFeatures/styles.module.css +++ /dev/null @@ -1,11 +0,0 @@ -.features { - display: flex; - align-items: center; - padding: 2rem 0; - width: 100%; -} - -.featureSvg { - height: 200px; - width: 200px; -} diff --git a/docs/src/pages/index.js b/docs/src/pages/index.js index 32df515..128a3d1 100644 --- a/docs/src/pages/index.js +++ b/docs/src/pages/index.js @@ -1,21 +1,21 @@ import clsx from 'clsx'; -import Link from '@docusaurus/Link'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; import Layout from '@theme/Layout'; -import HomepageFeatures from '@site/src/components/HomepageFeatures'; +import Link from "@docusaurus/core/lib/client/exports/Link"; +import { useColorMode } from '@docusaurus/theme-common'; +import Heading from "@theme/Heading"; -import Heading from '@theme/Heading'; import styles from './index.module.css'; function HomepageHeader() { - const {siteConfig} = useDocusaurusContext(); + const { colorMode } = useColorMode(); + const LogoSvg = colorMode === 'dark' + ? require('@site/static/img/logo-with-name-and-tagline-dark.svg').default + : require('@site/static/img/logo-with-name-and-tagline.svg').default; return (
- - {siteConfig.title} - -

{siteConfig.tagline}

+
); @@ -29,7 +29,23 @@ export default function Home() { description="Interchain Attestation is a project to enable IBC everywhere.">
- +
+ Enabling IBC everywhere +

+ Interchain Attestation is a project to enable IBC everywhere. +
+ It enables IBC when a light client is not available, by letting the receiving chain attest to the sender chain. +

+
+
+ + Read more in the docs + +
+
+
); diff --git a/docs/src/pages/index.module.css b/docs/src/pages/index.module.css index 9f71a5d..3c4ecec 100644 --- a/docs/src/pages/index.module.css +++ b/docs/src/pages/index.module.css @@ -21,3 +21,19 @@ align-items: center; justify-content: center; } + +.logoSvg { + max-width: 100%; + width: 100%; + height: auto; + display: block; + margin: 0 auto; + object-fit: contain; +} + +.introSection { + text-align: center; + margin: 0 auto; + padding: 2rem 0; + width: 100%; +} \ No newline at end of file diff --git a/docs/src/pages/markdown-page.md b/docs/src/pages/markdown-page.md deleted file mode 100644 index 9756c5b..0000000 --- a/docs/src/pages/markdown-page.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Markdown page example ---- - -# Markdown page example - -You don't need React to write simple standalone pages. diff --git a/docs/images/Attest.png b/docs/static/img/attest.png similarity index 100% rename from docs/images/Attest.png rename to docs/static/img/attest.png diff --git a/docs/static/img/logo-with-name-and-tagline-dark.svg b/docs/static/img/logo-with-name-and-tagline-dark.svg new file mode 100644 index 0000000..d96e061 --- /dev/null +++ b/docs/static/img/logo-with-name-and-tagline-dark.svg @@ -0,0 +1,9 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/static/img/logo-with-name-and-tagline.svg b/docs/static/img/logo-with-name-and-tagline.svg new file mode 100644 index 0000000..d7a4b00 --- /dev/null +++ b/docs/static/img/logo-with-name-and-tagline.svg @@ -0,0 +1,9 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/static/img/undraw_docusaurus_mountain.svg b/docs/static/img/undraw_docusaurus_mountain.svg deleted file mode 100644 index af961c4..0000000 --- a/docs/static/img/undraw_docusaurus_mountain.svg +++ /dev/null @@ -1,171 +0,0 @@ - - Easy to Use - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/static/img/undraw_docusaurus_react.svg b/docs/static/img/undraw_docusaurus_react.svg deleted file mode 100644 index 94b5cf0..0000000 --- a/docs/static/img/undraw_docusaurus_react.svg +++ /dev/null @@ -1,170 +0,0 @@ - - Powered by React - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/static/img/undraw_docusaurus_tree.svg b/docs/static/img/undraw_docusaurus_tree.svg deleted file mode 100644 index d9161d3..0000000 --- a/docs/static/img/undraw_docusaurus_tree.svg +++ /dev/null @@ -1,40 +0,0 @@ - - Focus on What Matters - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/justfile b/justfile index 461a94c..6846b26 100644 --- a/justfile +++ b/justfile @@ -1,3 +1,11 @@ +build: + @echo "Building all the components" + cd core && make build + cd configmodule && make build + cd sidecar && make build + cd testing/simapp && make build + cd testing/rollupsimapp && make build + cd testing/interchaintest && go build ./... lint: @echo "Running golangci-lint in all packages" @@ -34,3 +42,11 @@ test-e2e image-version="local": build-docker-images: cd testing && make docker-images + +install-simapps: + @echo "Installing simapps" + cd testing && make install-simapps + +serve: + @echo "Spinning up a test environment" + cd testing && make serve