From f2d35224ae7da129827743f019f57b24849aadfa Mon Sep 17 00:00:00 2001 From: mpoke Date: Tue, 27 Jun 2023 18:56:28 +0200 Subject: [PATCH 1/5] refactor gaia ADRs --- CONTRIBUTING.md | 9 ++ docs/architecture/PROCESS.md | 56 +++++++++ docs/architecture/README.md | 59 +++++++++ docs/architecture/adr-template.md | 58 +++++++++ docs/readiness/README.md | 112 ------------------ docs/readiness/adr-001-interchain-accounts.md | 101 ---------------- docs/readiness/template.md | 95 --------------- 7 files changed, 182 insertions(+), 308 deletions(-) create mode 100644 docs/architecture/PROCESS.md create mode 100644 docs/architecture/README.md create mode 100644 docs/architecture/adr-template.md delete mode 100644 docs/readiness/README.md delete mode 100644 docs/readiness/adr-001-interchain-accounts.md delete mode 100644 docs/readiness/template.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b17ad3bca62..e729811d4dc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,6 +6,7 @@ - [Ease of reviewing](#ease-of-reviewing) - [Workflow](#workflow) - [Project Board](#project-board) + - [Architecture Decision Records (ADR)](#architecture-decision-records-adr) - [Development Procedure](#development-procedure) - [Testing](#testing) - [Pull Requests](#pull-requests) @@ -99,6 +100,14 @@ We use self-organizing principles to coordinate and collaborate across organizat The developers work in sprints, which are available in a [GitHub Project](https://github.com/orgs/cosmos/projects/28/views/2). +## Architecture Decision Records (ADR) + +When proposing an architecture decision for Gaia, please start by opening an [issue](https://github.com/cosmos/gaia/issues/new/choose) or a [discussion](https://github.com/cosmos/gaia/discussions/new) with a summary of the proposal. Once the proposal has been discussed and there is rough alignment on a high-level approach to the design, you may either start development, or write an ADR. + +If your architecture decision is a simple change, you may contribute directly without writing an ADR. However, if you are proposing a significant change, please include a corresponding ADR. + +To create an ADR, follow the [template](./docs/architecture/adr-template.md) and [doc](./docs/architecture/README.md). If you would like to see examples of how these are written, please refer to the current [ADRs](https://github.com/cosmos/gaia/tree/main/docs/architecture). + ## Development Procedure `main` must be stable, include only completed features and never fail `make lint`, `make run-tests`, or `make build/install`. diff --git a/docs/architecture/PROCESS.md b/docs/architecture/PROCESS.md new file mode 100644 index 00000000000..6e9daf9f243 --- /dev/null +++ b/docs/architecture/PROCESS.md @@ -0,0 +1,56 @@ +# ADR Creation Process + +1. Copy the `adr-template.md` file. Use the following filename pattern: `adr-next_number-title.md` +2. Create a draft Pull Request if you want to get an early feedback. +3. Make sure the context and a solution is clear and well documented. +4. Add an entry to a list in the README file [Table of Contents](./README.md#adr-table-of-contents). +5. Create a Pull Request to propose a new ADR. + +## ADR life cycle + +ADR creation is an **iterative** process. Instead of trying to solve all decisions in a single ADR pull request, we MUST firstly understand the problem and collect feedback through a GitHub Issue. + +1. Every proposal SHOULD start with a new GitHub Issue or be a result of existing Issues. The Issue should contain just a brief proposal summary. + +2. Once the motivation is validated, a GitHub Pull Request (PR) is created with a new document based on the `adr-template.md`. + +3. An ADR doesn't have to arrive to `main` with an _accepted_ status in a single PR. If the motivation is clear and the solution is sound, we SHOULD be able to merge it and keep a _proposed_ status. It's preferable to have an iterative approach rather than long, not merged Pull Requests. + +4. If a _proposed_ ADR is merged, then it should clearly document outstanding issues either in ADR document notes or in a GitHub Issue. + +5. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer to merge it with a _rejected_ status. The only time the ADR SHOULD NOT be merged is if the author abandons it. + +6. Merged ADRs SHOULD NOT be pruned. + +### ADR status + +Status has two components: + +```text +{CONSENSUS STATUS} {IMPLEMENTATION STATUS} +``` + +IMPLEMENTATION STATUS is either `Implemented` or `Not Implemented`. + +#### Consensus Status + +```text +DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEDED by ADR-xxx + \ | + \ | + v v + ABANDONED +``` + +* `DRAFT`: [optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form. +* `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreed yet. +* `LAST CALL `: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze. +* `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design. +* `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so. +* `SUPERSEEDED by ADR-xxx`: ADR which has been superseded by a new ADR. +* `ABANDONED`: the ADR is no longer pursued by the original authors. + +## Language used in ADR + +* The context/background should be written in the present tense. +* Avoid using a first, personal form. diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 00000000000..d14bf762c53 --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,59 @@ + + +# Architecture Decision Records (ADR) + +This is a location to record all high-level architecture decisions for new feature and module proposals in the Cosmos Hub. + +An Architectural Decision (**AD**) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. +An Architecturally Significant Requirement (**ASR**) is a requirement that has a measurable effect on a software system’s architecture and quality. +An Architectural Decision Record (**ADR**) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM). + +You can read more about the ADR concept in this [blog post](https://product.reverb.com/documenting-architecture-decisions-the-reverb-way-a3563bb24bd0#.78xhdix6t). + +## Rationale + +ADRs are intended to be the primary mechanism for proposing new feature designs and new processes, for collecting community input on an issue, and for documenting the design decisions. +An ADR should provide: + +- Context on the relevant goals and the current state +- Proposed changes to achieve the goals +- Summary of pros and cons +- References +- Changelog + +Note the distinction between an ADR and a spec. The ADR provides the context, intuition, reasoning, and +justification for a change in architecture, or for the architecture of something +new. The spec is much more compressed and streamlined summary of everything as +it stands today. + +If recorded decisions turned out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match. + +## Creating new ADR + +Read about the [PROCESS](./PROCESS.md). + +### Use RFC 2119 Keywords + +When writing ADRs, follow the same best practices for writing RFCs. +When writing RFCs, key words are used to signify the requirements in the specification. +These words are often capitalized: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. +They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + +## ADR Table of Contents + +### Accepted + +- n/a + +### Proposed + +- n/a + +### Draft + +- n/a diff --git a/docs/architecture/adr-template.md b/docs/architecture/adr-template.md new file mode 100644 index 00000000000..95e5a5886e6 --- /dev/null +++ b/docs/architecture/adr-template.md @@ -0,0 +1,58 @@ + + +# ADR {ADR-NUMBER}: {TITLE} + +## Changelog + +- {date}: {changelog} + +## Status + +{DRAFT | PROPOSED} Not Implemented + +> Please have a look at the [PROCESS](./PROCESS.md#adr-status) page. +> Use DRAFT if the ADR is in a draft stage (draft PR) or PROPOSED if it's in review. + +## Abstract + +> "If you can't explain it simply, you don't understand it well enough." Provide +> a simplified and layman-accessible explanation of the ADR. +> A short (~200 word) description of the issue being addressed. + +## Context + +> This section contains all the context one needs to understand the current state, and why there is a problem. +> It should be as succinct as possible and introduce the high level idea behind the solution. +> The language in this section is value-neutral. It is simply describing facts. + +## Decision + +> This section explains all of the details of the proposed solution, including implementation details. +It should also describe affects / corollary items that may need to be changed as a part of this. +If the proposed change will be large, please also indicate a way to do the change to maximize ease of review. +(e.g. the optimal split of things to do between separate PR's) + +## Consequences + +> This section describes the consequences, after applying the decision. +> All consequences should be summarized here, not just the "positive" ones. + +### Positive + +> {positive consequences} + +### Negative + +> {negative consequences} + +### Neutral + +> {neutral consequences} + +## References + +> Are there any relevant PR comments, issues that led up to this, or articles referrenced for why we made the given design choice? If so link them here! + +* {reference link} diff --git a/docs/readiness/README.md b/docs/readiness/README.md deleted file mode 100644 index 98d8e19ac72..00000000000 --- a/docs/readiness/README.md +++ /dev/null @@ -1,112 +0,0 @@ - - -# Architecture Decision Records (ADR) - -This is a location to record all high-level architecture decisions for new feature and module proposals in the Cosmos Hub. - -An Architectural Decision (**AD**) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. -An Architecturally Significant Requirement (**ASR**) is a requirement that has a measurable effect on a software system’s architecture and quality. -An Architectural Decision Record (**ADR**) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM). - -You can read more about the ADR concept in this [blog post](https://product.reverb.com/documenting-architecture-decisions-the-reverb-way-a3563bb24bd0#.78xhdix6t). - -## Rationale - -ADRs are intended to be the primary mechanism for proposing new feature designs and new processes, for collecting community input on an issue, and for documenting the design decisions. -An ADR should provide: - -- Context on the relevant goals and the current state -- Proposed changes to achieve the goals -- Summary of pros and cons -- References -- Changelog - -Note the distinction between an ADR and a spec. The ADR provides the context, intuition, reasoning, and -justification for a change in architecture, or for the architecture of something -new. The spec is much more compressed and streamlined summary of everything as -it stands today. - -If recorded decisions turned out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match. - -## Creating new ADR - -### Process - -1. Copy the `template.md` file. Use the following filename pattern: `adr-next_number-title.md` -2. Link the ADR in the related feature epic -3. Create a draft Pull Request if you want to get early feedback. -4. Make sure the context and a solution is clear and well documented. -5. Add an entry to a list in the README file [Table of Contents](#adr-table-of-contents). -6. Create a Pull Request to publish the ADR proposal. - -### Life cycle - -ADR creation is an **iterative** process. Rather than solving all decisions in a single PR, it's best to first understand the problem and then solicit feedback through Github Issues. - -1. Every proposal should start with a new GitHub Issue and be linked to the corresponding Feature Epic. The Issue should contain a brief proposal summary. - -2. Once the motivation is validated, a GitHub Pull Request (PR) is created with a new document based on the `template.md`. - -3. An ADR doesn't have to arrive to `master` with an `accepted` status in a single PR. If the motivation is clear and the solution is sound, we should be able to merge it and keep a `proposed` status. - -4. If a `proposed` ADR is merged, then it should clearly document outstanding issues in the Feature Epic. - -5. The PR should always be merged. In the case of a faulty ADR, it's still preferable to merge it with a `rejected` status. The only time the ADR should not be merged is if the author abandons it. - -6. Merged ADRs **should not** be pruned. - -### Status - -Status has two components: - -``` -{CONSENSUS STATUS} {IMPLEMENTATION STATUS} -``` - -IMPLEMENTATION STATUS is either `Implemented` or `Not Implemented`. - -#### Consensus Status - -``` -DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEDED by ADR-xxx - \ | - \ | - v v - ABANDONED -``` - -- `DRAFT`: [optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form. -- `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreed yet. -- `LAST CALL `: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos Hub maintainers) has been reached and we still want to give it a time to let the community react or analyze. -- `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design. -- `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so. -- `SUPERSEEDED by ADR-xxx`: ADR which has been superseded by a new ADR. -- `ABANDONED`: the ADR is no longer pursued by the original authors. - -### Language used in ADR - -- The context/background should be written in the present tense. -- Avoid using a first, personal form. - -**Use RFC 2119 Keywords** - -When writing ADRs, follow the same best practices for writing RFCs. When writing RFCs, key words are used to signify the requirements in the specification. These words are often capitalized: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). - -## ADR Table of Contents - -### Accepted - -- n/a - -### Proposed - -- n/a - -### Draft - -- [ADR 001: Interchain Accounts](./adr-001-interchain-accounts.md) diff --git a/docs/readiness/adr-001-interchain-accounts.md b/docs/readiness/adr-001-interchain-accounts.md deleted file mode 100644 index c73c97c5d71..00000000000 --- a/docs/readiness/adr-001-interchain-accounts.md +++ /dev/null @@ -1,101 +0,0 @@ - - ---- - -ADR: 001 -Title: Interchain Accounts -Status: Draft Implements -Category: Feature -Author: Sean King & Damian Nolan -Created: 2022-01-19 -Mdified: 2022-01-19 -Requires: Cosmos-SDK, go-ibc -Required-By: mauth -Implements: Interchain Accounts ---- - -# ADR 001: Interchain Accounts - -## Changelog - -- 2022-02-04: added content -- 2022-01-19: init - -## Abstract - -This is the Core Interchain Accounts Module. It allows the Cosmos Hub to act as a host chain with interchain accounts that are controlled by external IBC connected "Controller" blockchains. Candidate chains include Umee, Quicksilver, Sommelier. It is also a necessary component for a Authentication Module that allows the Cosmos Hub to act as a Controller chain as well. This will be recorded in a separate ADR. - -## Rationale - -This allows the Hub to participate in advanced cross-chain defi operations, like Liquid Staking and various protocol controlled value applications. - -## Desired Outcome - -The hub can be used trustlessly as a host chain in the configuration of Interchain Accounts. - -## Consequences - -There has been preliminary work done to understand if this increases any security feature of the Cosmos Hub. One thought was that this capability is similar to contract to contract interactions which are possible on virtual machine blockchains like EVM chains. Those interactions introduced a new attack vector, called a re-entrancy bug, which was the culprit of "The DAO hack on Ethereum". We believe there is no risk of these kinds of attacks with Interchain Accounts because they require the interactions to be atomic and Interchain Accounts are asynchronous. - -#### Backwards Compatibility - -This is the first of its kind. - -#### Forward Compatibility - -There are future releases of Interchain Accounts which are expected to be backwards compatible. - -## Technical Specification - -[ICS-27 Spec](https://github.com/cosmos/ibc/blob/master/spec/app/ics-027-interchain-accounts/README.md) - -## Development - -- Integration requirements - - Development has occured in [IBC-go](https://github.com/cosmos/ibc-go) and progress tracked on the project board there. -- Testing (Simulations, Core Team Testing, Partner Testing) - - Simulations and Core Team tested this module -- Audits (Internal Dev review, Third-party review, Bug Bounty) - - An internal audit, an audit from Informal Systems, and an audit from Trail of Bits all took place with fixes made to all findings. -- Networks (Testnets, Productionnets, Mainnets) - - Testnets - -## Governance [optional] - -- **Needs Signaling Proposal** -- Core Community Governance - - N/A -- Steering Community - - N/A. Possibly Aditya Srinpal, Sean King, Bez? -- Timelines & Roadmap - - Expected to be released as part of IBC 3.0 in Feb 2022 (currently in [beta release](https://github.com/cosmos/ibc-go/releases/tag/v3.0.0-beta1)) - -## Project Integrations [optional] - -- Gaia Integrations - - [PR](https://github.com/cosmos/gaia/pull/1150) -- Integration Partner - - IBC Team - -#### Downstream User Impact Report - -(Needs to be created) - -#### Upstream Partner Impact Report - -(Needs to be created) - -#### Inter-module Dependence Report - -(Needs to be created) - -## Support - -[Documentation](https://ibc.cosmos.network/main/apps/interchain-accounts/overview.html) - -## Additional Research & References - -- [Why Interchain Accounts Change Everything for Cosmos Interoperability](https://medium.com/chainapsis/why-interchain-accounts-change-everything-for-cosmos-interoperability-59c19032bf11) -- [Interchain Account Auth Module Demo Repo](https://github.com/cosmos/interchain-accounts) diff --git a/docs/readiness/template.md b/docs/readiness/template.md deleted file mode 100644 index e7f148a2b98..00000000000 --- a/docs/readiness/template.md +++ /dev/null @@ -1,95 +0,0 @@ - - ---- - -ADR: (number) -Title: (short title) -Status: (current ADR status) -Category: (Module or Feature) -Author: (primary & additional authors) -Created: (creation date) -Mdified: (modification date) -Requires: (optional list of downstream ADRs) -Required-By: (optional list of upstream ADRs) -Implements: (optional list of component ADRs) ---- - -# ADR {ADR-NUMBER}: {TITLE} - -## Changelog - -- {date}: {changelog} - -## Abstract - -> "If you can't explain it simply, you don't understand it well enough." Provide a short (~200 word) high level description of the issue being addressed and rationale for such. - -## Rationale - -> Describe the context and rationale for proposing a new feature or module. The language in this section is value-neutral and should clearly explain the problem and motivation that the proposal aims to resolve. - -## Desired Outcome - -> Provides succinct answers to the issues documented above. Response should include desired characteristics / properties of feature/protocol, and effects if properties are violated. - -## Consequences - -> This section describes the resulting context, after applying the decision (positive, neutral, and negative). - -#### Backwards Compatibility - -> Discussion of compatibility or lack thereof with previous standards. - -#### Forward Compatibility - -> Discussion of compatibility or lack thereof with expected future standards. - -## Technical Specification - -> Details main technical standard, may include some of the following: syntax, semantics, sub-protocols, algorithms, data structures, etc. - -## Development - -> Documents the following for readiness/deployment milestones - -- Integration requirements (CLI) -- Testing (Simulations, Core Team Testing, Partner Testing) -- Audits (Internal Dev review, Third-party review, Bug Bounty) -- Networks (Testnets, Productionnets, Mainnets) - -### Backwards Compatibility - -> Discussion of compatibility or lack thereof with expected future standards. - -## Governance [optional] - -> If relevant, will include: - -- Linked Hub Governance proposal -- Core Community Governance -- Steering Community -- Timelines & Roadmap - -## Project Integrations [optional] - -> Document internal and/or external integration partners - -- Gaia Integrations -- Integration Partner -- IBC Readiness - -#### Downstream User Impact Report - -#### Upstream Partner Impact Report - -#### Inter-module Dependence - -## Support - -> Includes additional technical, marketing, educational, etc support - -## Additional Research & References - -> Additional links or sections to address From d976bdc22d251c9e63727e9bab75ab06f84b687c Mon Sep 17 00:00:00 2001 From: mpoke Date: Wed, 28 Jun 2023 15:08:45 +0200 Subject: [PATCH 2/5] apply review suggestions --- docs/architecture/PROCESS.md | 8 ++++---- docs/architecture/README.md | 5 +++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/architecture/PROCESS.md b/docs/architecture/PROCESS.md index 6e9daf9f243..4daa72980c8 100644 --- a/docs/architecture/PROCESS.md +++ b/docs/architecture/PROCESS.md @@ -1,8 +1,8 @@ # ADR Creation Process 1. Copy the `adr-template.md` file. Use the following filename pattern: `adr-next_number-title.md` -2. Create a draft Pull Request if you want to get an early feedback. -3. Make sure the context and a solution is clear and well documented. +2. Create a draft Pull Request and solicit input from the stewarding team, if you want to get an early feedback. +3. Make sure that the problem, the context and a recommended solution is clear and well documented. Be sure to document alternate solution spaces and give reasons why they have been discarded. 4. Add an entry to a list in the README file [Table of Contents](./README.md#adr-table-of-contents). 5. Create a Pull Request to propose a new ADR. @@ -18,9 +18,9 @@ ADR creation is an **iterative** process. Instead of trying to solve all decisio 4. If a _proposed_ ADR is merged, then it should clearly document outstanding issues either in ADR document notes or in a GitHub Issue. -5. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer to merge it with a _rejected_ status. The only time the ADR SHOULD NOT be merged is if the author abandons it. +5. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer to merge it with a _rejected_ status. The only time the ADR SHOULD NOT be merged is if the author abandons it. -6. Merged ADRs SHOULD NOT be pruned. +6. Merged ADRs SHOULD NOT be deleted. ### ADR status diff --git a/docs/architecture/README.md b/docs/architecture/README.md index d14bf762c53..34ac0612939 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -13,7 +13,7 @@ An Architectural Decision (**AD**) is a software design choice that addresses a An Architecturally Significant Requirement (**ASR**) is a requirement that has a measurable effect on a software system’s architecture and quality. An Architectural Decision Record (**ADR**) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM). -You can read more about the ADR concept in this [blog post](https://product.reverb.com/documenting-architecture-decisions-the-reverb-way-a3563bb24bd0#.78xhdix6t). +You can read more about the ADR concept [here](https://adr.github.io/). ## Rationale @@ -23,6 +23,7 @@ An ADR should provide: - Context on the relevant goals and the current state - Proposed changes to achieve the goals - Summary of pros and cons +- Discarded solution spaces and why they were discarded - References - Changelog @@ -31,7 +32,7 @@ justification for a change in architecture, or for the architecture of something new. The spec is much more compressed and streamlined summary of everything as it stands today. -If recorded decisions turned out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match. +If recorded decisions turn out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match. ## Creating new ADR From f8dcf09bc7e63007f34c09398edf989ed3f0df28 Mon Sep 17 00:00:00 2001 From: mpoke Date: Wed, 28 Jun 2023 15:13:05 +0200 Subject: [PATCH 3/5] add mermaid graph --- docs/architecture/PROCESS.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/architecture/PROCESS.md b/docs/architecture/PROCESS.md index 4daa72980c8..fa73a995a16 100644 --- a/docs/architecture/PROCESS.md +++ b/docs/architecture/PROCESS.md @@ -34,12 +34,13 @@ IMPLEMENTATION STATUS is either `Implemented` or `Not Implemented`. #### Consensus Status -```text -DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEDED by ADR-xxx - \ | - \ | - v v - ABANDONED +```mermaid +flowchart TD + A[DRAFT] --> B[PROPOSED] + B --> C[LAST CALL YYYY-MM-DD] + B --> D[ABANDONED] + C --> E[ACCEPTED or REJECTED] + E --> F[SUPERSEDED by ADR-xxx] ``` * `DRAFT`: [optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form. From 9f3e3000001202f03a8f76bfb3b71cba16dc833a Mon Sep 17 00:00:00 2001 From: mpoke Date: Wed, 28 Jun 2023 15:21:06 +0200 Subject: [PATCH 4/5] add ADR-001 back as rejected --- docs/architecture/README.md | 4 + .../adr-001-interchain-accounts.md | 94 +++++++++++++++++++ 2 files changed, 98 insertions(+) create mode 100644 docs/architecture/adr-001-interchain-accounts.md diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 34ac0612939..ebf8f04afb3 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -58,3 +58,7 @@ They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.o ### Draft - n/a + +### Rejected + +- [ADR 001: Interchain Accounts](./adr-001-interchain-accounts.md) diff --git a/docs/architecture/adr-001-interchain-accounts.md b/docs/architecture/adr-001-interchain-accounts.md new file mode 100644 index 00000000000..30f0b57abf3 --- /dev/null +++ b/docs/architecture/adr-001-interchain-accounts.md @@ -0,0 +1,94 @@ + + +# ADR 001: Interchain Accounts + +## Changelog + +- 2022-02-04: added content +- 2022-01-19: init +- 2023-06-28: mark as rejected + +## Status + +REJECTED Not Implemented + +**Reason:** The IBC team decided to integrate this functionality directly into their codebase and maintain it, because multiple users require it. + +## Abstract + +This is the Core Interchain Accounts Module. It allows the Cosmos Hub to act as a host chain with interchain accounts that are controlled by external IBC connected "Controller" blockchains. Candidate chains include Umee, Quicksilver, Sommelier. It is also a necessary component for a Authentication Module that allows the Cosmos Hub to act as a Controller chain as well. This will be recorded in a separate ADR. + +## Rationale + +This allows the Hub to participate in advanced cross-chain defi operations, like Liquid Staking and various protocol controlled value applications. + +## Desired Outcome + +The hub can be used trustlessly as a host chain in the configuration of Interchain Accounts. + +## Consequences + +There has been preliminary work done to understand if this increases any security feature of the Cosmos Hub. One thought was that this capability is similar to contract to contract interactions which are possible on virtual machine blockchains like EVM chains. Those interactions introduced a new attack vector, called a re-entrancy bug, which was the culprit of "The DAO hack on Ethereum". We believe there is no risk of these kinds of attacks with Interchain Accounts because they require the interactions to be atomic and Interchain Accounts are asynchronous. + +#### Backwards Compatibility + +This is the first of its kind. + +#### Forward Compatibility + +There are future releases of Interchain Accounts which are expected to be backwards compatible. + +## Technical Specification + +[ICS-27 Spec](https://github.com/cosmos/ibc/blob/master/spec/app/ics-027-interchain-accounts/README.md) + +## Development + +- Integration requirements + - Development has occured in [IBC-go](https://github.com/cosmos/ibc-go) and progress tracked on the project board there. +- Testing (Simulations, Core Team Testing, Partner Testing) + - Simulations and Core Team tested this module +- Audits (Internal Dev review, Third-party review, Bug Bounty) + - An internal audit, an audit from Informal Systems, and an audit from Trail of Bits all took place with fixes made to all findings. +- Networks (Testnets, Productionnets, Mainnets) + - Testnets + +## Governance [optional] + +- **Needs Signaling Proposal** +- Core Community Governance + - N/A +- Steering Community + - N/A. Possibly Aditya Srinpal, Sean King, Bez? +- Timelines & Roadmap + - Expected to be released as part of IBC 3.0 in Feb 2022 (currently in [beta release](https://github.com/cosmos/ibc-go/releases/tag/v3.0.0-beta1)) + +## Project Integrations [optional] + +- Gaia Integrations + - [PR](https://github.com/cosmos/gaia/pull/1150) +- Integration Partner + - IBC Team + +#### Downstream User Impact Report + +(Needs to be created) + +#### Upstream Partner Impact Report + +(Needs to be created) + +#### Inter-module Dependence Report + +(Needs to be created) + +## Support + +[Documentation](https://ibc.cosmos.network/main/apps/interchain-accounts/overview.html) + +## Additional Research & References + +- [Why Interchain Accounts Change Everything for Cosmos Interoperability](https://medium.com/chainapsis/why-interchain-accounts-change-everything-for-cosmos-interoperability-59c19032bf11) +- [Interchain Account Auth Module Demo Repo](https://github.com/cosmos/interchain-accounts) \ No newline at end of file From 17687795f8e4626898dee457695c1c4be7588ea2 Mon Sep 17 00:00:00 2001 From: mpoke Date: Tue, 25 Jul 2023 13:41:58 +0200 Subject: [PATCH 5/5] fix typo --- docs/architecture/PROCESS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture/PROCESS.md b/docs/architecture/PROCESS.md index fa73a995a16..a547cc29186 100644 --- a/docs/architecture/PROCESS.md +++ b/docs/architecture/PROCESS.md @@ -44,7 +44,7 @@ flowchart TD ``` * `DRAFT`: [optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form. -* `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreed yet. +* `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreement yet. * `LAST CALL `: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze. * `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design. * `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so.