Merge branch 'marius/ccv' of github.com:cosmos/ibc into marius/ccv

cosmos · Jun 23, 2022 · 7ea1ce6 · 7ea1ce6
2 parents 6187e04 + f1b1040
commit 7ea1ce6
Show file tree

Hide file tree

Showing 19 changed files with 2,375 additions and 344 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -1,4 +1,4 @@
 # Default owners for repository
-# 2/3 quorum required for merge
+# 2/n quorum required for merge
 
-*       @mpoke @adityasripal @cwgoes
+*       @mpoke @adityasripal @cwgoes @colin-axner
diff --git a/README.md b/README.md
@@ -8,21 +8,7 @@ This repository is the canonical location for development and documentation of t
 
 It shall be used to consolidate design rationale, protocol semantics, and encoding descriptions for IBC, including both the core transport, authentication, & ordering layer (IBC/TAO) and the application layers describing packet encoding & processing semantics (IBC/APP).
 
-Contributions are welcome.
-
-## Standardisation
-
-Please see [ICS 1](spec/ics-001-ics-standard/README.md) for a description of what a standard entails.
-
-To propose a new standard, [open an issue](https://github.com/cosmos/ics/issues/new).
-
-To start a new standardisation document, copy the [template](spec/ics-template.md) and open a PR.
-
-See [PROCESS.md](meta/PROCESS.md) for a description of the standardisation process.
-
-See [STANDARDS_COMMITTEE.md](meta/STANDARDS_COMMITTEE.md) for the membership of the core standardisation committee.
-
-See [CONTRIBUTING.md](meta/CONTRIBUTING.md) for contribution guidelines.
+Contributions are welcome. See [CONTRIBUTING.md](meta/CONTRIBUTING.md) for contribution guidelines.
 
 See [ROADMAP.md](meta/ROADMAP.md) for a public up-to-date version of our roadmap.
 
@@ -55,6 +41,7 @@ All standards at or past the "Draft" stage are listed here in order of their ICS
 | --------------------------------------------------------------- | -------------------------- | ----- |
 | [6](spec/client/ics-006-solo-machine-client/README.md)          | Solo Machine Client        | Candidate |
 | [7](spec/client/ics-007-tendermint-client/README.md)            | Tendermint Client          | Candidate |
+| [8](spec/client/ics-008-wasm-client/README.md)                  | Wasm Client                | Draft |
 | [9](spec/client/ics-009-loopback-client/README.md)              | Loopback Client            | Candidate |
 | [10](spec/client/ics-010-grandpa-client/README.md)              | GRANDPA Client             | Draft |
 

diff --git a/meta/CONTRIBUTING.md b/meta/CONTRIBUTING.md
@@ -1,8 +1,61 @@
-## Contribution Guidelines
+# Contribution Guidelines
 
 Thanks for your interest in contributing to IBC! Contributions are always welcome. 
 
-- Feel free to open an issue to raise a question, explain a concern, or discuss a possible future feature, protocol change, or standard.
-- If you would like to propose a new standard for inclusion in the IBC standards, please see [PROCESS.md](./PROCESS.md) for a detailed description of the standardisation process.
+Contributing to this repo can mean many things such as participating in discussion or proposing changes. To ensure a smooth workflow for all contributors, the general procedure for contributing has been established:
+
+- Feel free to [open](https://github.com/cosmos/ibc/issues/new) an issue to raise a question, explain a concern, or discuss a possible future feature, protocol change, or standard.
+  - Make sure first that the issue does not already [exist](https://github.com/cosmos/ibc/issues).
+  - Participate in thoughtful discussion on the issue.
+
+- If you would like to contribute in fixing / closing an issue:
+  - If the issue is a proposal, ensure that the proposal has been accepted.
+  - Ensure that nobody else has already begun working on this issue. If they have, make sure to contact them to collaborate.
+  - If nobody has been assigned for the issue and you would like to work on it, make a comment on the issue to inform the community of your intentions to begin work.
+  - Follow standard Github best practices: fork the repo, branch from the HEAD of `master`, make some commits, and submit a PR to `master`. 
+    For more details, see the [Pull Requests](#pull-requests) section below. 
+  - Be sure to submit the PR early in `Draft` mode, even if it's incomplete as this indicates to the community you're working on something and allows them to provide comments at an early stage.
+  - When the PR is complete it can be marked `Ready for Review`.
+
+- If you would like to propose a new standard for inclusion in the IBC standards, please take a look at [PROCESS.md](./PROCESS.md) for a detailed description of the standardisation process.
+  - To start a new standardisation document, copy the [template](../spec/ics-template.md) and open a PR.
 
 If you have any questions, you can usually find some IBC team members on the [Cosmos Discord](https://discord.gg/rPFPxVJmUZ).
+
+## Pull Requests
+
+To accommodate review process we suggest that PRs are categorically broken up.
+Each PR should address only a single issue and **a single standard**. 
+The PR name should be prefixed by the standard number, 
+e.g., `ICS4: Some improvements` should contain only changes to [ICS 4](../spec/core/ics-004-channel-and-packet-semantics/README.md).
+If fixing an issue requires changes to multiple standards, create multiple PRs and mention the inter-dependencies.
+
+### Process for reviewing PRs
+
+All PRs require an approval from at least two members of the [standardisation committee](./STANDARDS_COMMITTEE.md) before merge. 
+The PRs submitted by one of the members of the standardisation committee require an approval from only one other member before merge. 
+When reviewing PRs please use the following review explanations:
+- `Approval` through the GH UI means that you understand all the changes proposed in the PR. In addition:
+  - You must also think through anything which ought to be included but is not.
+  - You must think through any potential security issues or incentive-compatibility flaws introduced by the changes.
+  - The changes must be consistent with the other IBC standards, especially the [core IBC standards](../README.md#core). 
+  - The modified standard must be consistent with the description from [ICS 1](../spec/ics-001-ics-standard/README.md).
+- If you are only making "surface level" reviews, submit any notes as `Comments` without adding a review.
+
+### PR Targeting
+
+Ensure that you base and target your PR on the `master` branch.
+
+### Development Procedure
+
+- The latest state of development is on `master`.
+- Create a development branch either on `github.com/cosmos/ibc` or your fork (using `git remote add fork`).
+  - To ensure a clear ownership of branches on the ibc repo, branches must be named with the convention `{moniker}/{issue#}-branch-name`
+- Before submitting a pull request, begin `git rebase` on top of `master`. 
+  **Since standards cannot be compiled, make sure that the changes in your PR remains consistent with the new commits on the `master` branch**.
+
+### Pull Merge Procedure
+
+- Ensure all github requirements pass.
+- Squash and merge pull request.
+
diff --git a/meta/PROCESS.md b/meta/PROCESS.md
@@ -20,11 +20,14 @@ IBC standardisation will follow an adaptation of the [TC 39](https://tc39.github
 - _**Entrance Criteria**_:
   * Prose outlining the problem or need and the general shape of a solution in a PR to a `./spec/{area}/ics-{{ .Spec.Number }}-{{ .Spec.Name }}/README.md` file in this repository.
     This file should contain:
-    1. List of expected projects & users within the Cosmos ecosystem who might make use of the specification along with any particular requirements they have
-    1. Discussion of key algorithms, abstractions, and semantics
-    1. High-level application interface outline, where applicable
-    1. Identification of potential design trade-offs and implementation challenges/complexity
-    See [ICS 1](../spec/ics-001-ics-standard) for a more detailed description of standard requirements.
+    - List of expected projects & users within the Cosmos ecosystem who might make use of the specification along with any particular requirements they have
+    - Discussion of key algorithms, abstractions, and semantics
+    - High-level application interface outline, where applicable
+    - Identification of potential design trade-offs and implementation challenges/complexity
+
+    For a more detailed description of standard requirements, see [ICS 1](../spec/ics-001-ics-standard).
+
+    For more details on submitting a PR, take a look at the [Pull Requests](./CONTRIBUTING.md#pull-requests) section in the contribution guidelines.
   * Identified `author(s)` who will advance the proposal in the header of the standard file
   * Any additional reference documentation or media in the `./spec/ics-{{ .Spec.Number }}-{{ .Spec.Name }}` directory
   * The specification team expects that this proposal will be finalised and eventually included in the IBC standard set.

diff --git a/meta/ROADMAP.md b/meta/ROADMAP.md
@@ -1,20 +1,19 @@
 # Roadmap IBC specs
 
-_Lastest update: November 18th, 2021_
+_Lastest update: April 6th, 2022_
 
 This document endeavours to inform the wider IBC community about plans and priorities for the specification work of IBC. This roadmap should be read as a high-level guide, rather than a commitment to schedules and deliverables. The degree of specificity is inversely proportional to the timeline. We will update this document periodically to reflect the status and plans.
 
 This roadmap reflects the major activities that the [standards committee](STANDARDS_COMMITTEE.md) is engaged with in the coming quarters. It is, by no means, a thorough reflection of all the specification work that is happening in the broad ecosystem, as many other parties work as well in specs that eventually end up in this repository.
 
-## Q4 - 2021
+## Q2 - 2022
 
-- Update the Interchain Accounts ([ICS27](https://github.com/cosmos/ibc/blob/master/spec/app/ics-027-interchain-accounts/README.md)) and Relayer Incentivisation ([ICS29](https://github.com/cosmos/ibc/tree/master/spec/app/ics-029-fee-payment)) specifications to align them with the ibc-go implementation.
-- The function `NegotiateAppVersion` has been [added to the app module interface in ibc-go](https://github.com/cosmos/ibc-go/pull/384) as part of the Interchain Accounts work. This change is not reflected yet in the [ICS05](https://github.com/cosmos/ibc/blob/master/spec/core/ics-005-port-allocation/README.md) specification. An update is needed to describe its semantics beyond the Interchain Accounts use case.
-- Review [IRISnet](https://www.irisnet.org)'s [ICS721](https://github.com/cosmos/ibc/pull/615) specification proposal for NFT transfers.
-- Rough draft of channel upgrade process (potentially connection as well).
-
-## Q1 - 2022
-
-- Possibly finalize the review and merge of [ICS721](https://github.com/cosmos/ibc/pull/615) (NFT tranfers) specification.
-- Continue review and advisory work on [Informal Systems](https://informal.systems)' [specification proposal for cross-chain validation](https://github.com/cosmos/ibc/pull/563).
-- Begin a re-write of IBC specifications to make them easier to understand to qualified developers trying to implement IBC in other ecosystems. This will most likely be a multi-quarter effort.
+- Work on general readability improvements and inconsistency fixes in some of the specs ([ICS02](https://github.com/cosmos/ibc/blob/master/spec/core/ics-002-client-semantics/README.md), [ICS06](https://github.com/cosmos/ibc/blob/master/spec/client/ics-006-solo-machine-client/README.md), [ICS07](https://github.com/cosmos/ibc/blob/master/spec/client/ics-007-tendermint-client/README.md)). This is a first step on the long-term plan to make the specs easier to understand to qualified developers.
+- The [connection](https://github.com/cosmos/ibc/pull/621) and [channel](https://github.com/cosmos/ibc/pull/677) upgradability specs have been merged, but they need some small fixes. The spec team will also help with the planning of the implementation of channel upgradability in [ibc-go](https://github.com/cosmos/ibc-go).
+- Finish writing the spec for [ordered channels that support timeouts](https://github.com/cosmos/ibc/pull/636).
+- Start writing the spec to support state trees without absence proofs.
+- The implementation of [ICS29](https://github.com/cosmos/ibc/tree/master/spec/app/ics-029-fee-payment) in ibc-go will be finished in Q2 and the spec might need some updates to reflect the latest status.
+- Finish [ICS28](https://github.com/cosmos/ibc/pull/666) (Cross-chain validation) spec.
+- Review and possibly merge [ICS721](https://github.com/cosmos/ibc/pull/615) spec for NFT transfers.
+- Review and possibly merge the spec for [IBC queries](https://github.com/cosmos/ibc/pull/647).
+- Write and add to the repository a high level overview of what IBC is. This can be used as an entry point for newcomers to IBC to understand its general principles.
diff --git a/meta/STANDARDS_COMMITTEE.md b/meta/STANDARDS_COMMITTEE.md
@@ -3,6 +3,6 @@
 Currently, the core standardisation committee consists of:
 - Aditya Sripal (@adityasripal)
 - Christopher Goes (@cwgoes)
-- Zarko Milosevic (@milosevic)
+- Marius Poke (@mpoke)
 
 A two-of-three quorum is needed to approve pull requests to this repository.
diff --git a/spec/app/ics-020-fungible-token-transfer/README.md b/spec/app/ics-020-fungible-token-transfer/README.md
@@ -38,14 +38,14 @@ Only one packet data type is required: `FungibleTokenPacketData`, which specifie
 
 ```typescript
 interface FungibleTokenPacketData {
-  denomination: string
+  denom: string
   amount: uint256
   sender: string
   receiver: string
 }
 ```
 
-As tokens are sent across chains using the ICS 20 protocol, they begin to accrue a record of channels for which they have been transferred across. This information is encoded into the `denomination` field. 
+As tokens are sent across chains using the ICS 20 protocol, they begin to accrue a record of channels for which they have been transferred across. This information is encoded into the `denom` field. 
 
 The ics20 token denominations are represented the form `{ics20Port}/{ics20Channel}/{denom}`, where `ics20Port` and `ics20Channel` are an ics20 port and channel on the current chain for which the funds exist. The prefixed port and channel pair indicate which channel the funds were previously sent through. If `{denom}` contains `/`, then it must also be in the ics20 form which indicates that this token has a multi-hop record. Note that this requires that the `/` (slash character) is prohibited in non-IBC token denomination names.
 
@@ -58,7 +58,7 @@ type FungibleTokenPacketAcknowledgement = FungibleTokenPacketSuccess | FungibleT
 
 interface FungibleTokenPacketSuccess {
   // This is binary 0x01 base64 encoded
-  success: "AQ=="
+  result: "AQ=="
 }
 
 interface FungibleTokenPacketError {
@@ -159,10 +159,11 @@ function onChanOpenTry(
 function onChanOpenAck(
   portIdentifier: Identifier,
   channelIdentifier: Identifier,
-  version: string) {
+  counterpartyChannelIdentifier: Identifier,
+  counterpartyVersion: string) {
   // port has already been validated
-  // assert that version is "ics20-1"
-  abortTransactionUnless(version === "ics20-1")
+  // assert that counterparty selected version is "ics20-1"
+  abortTransactionUnless(counterpartyVersion === "ics20-1")
 }
 ```
 
@@ -178,7 +179,8 @@ function onChanOpenConfirm(
 function onChanCloseInit(
   portIdentifier: Identifier,
   channelIdentifier: Identifier) {
-  // no action necessary
+    // always abort transaction
+    abortTransactionUnless(FALSE)
 }
 ```
 
@@ -201,35 +203,43 @@ In plain English, between chains `A` and `B`:
   an acknowledgement of failure is preferable to aborting the transaction since it more easily enables the sending chain
   to take appropriate action based on the nature of the failure.
 
-`createOutgoingPacket` must be called by a transaction handler in the module which performs appropriate signature checks, specific to the account owner on the host state machine.
+`sendFungibleTokens` must be called by a transaction handler in the module which performs appropriate signature checks, specific to the account owner on the host state machine.
 
 ```typescript
-function createOutgoingPacket(
+function sendFungibleTokens(
   denomination: string,
   amount: uint256,
   sender: string,
   receiver: string,
-  source: boolean,
-  destPort: string,
-  destChannel: string,
   sourcePort: string,
   sourceChannel: string,
   timeoutHeight: Height,
   timeoutTimestamp: uint64) {
-  prefix = "{sourcePort}/{sourceChannel}/"
-  // we are the source if the denomination is not prefixed
-  source = denomination.slice(0, len(prefix)) !== prefix
-  if source {
-    // determine escrow account
-    escrowAccount = channelEscrowAddresses[sourceChannel]
-    // escrow source tokens (assumed to fail if balance insufficient)
-    bank.TransferCoins(sender, escrowAccount, denomination, amount)
-  } else {
-    // receiver is source chain, burn vouchers
-    bank.BurnCoins(sender, denomination, amount)
-  }
-  FungibleTokenPacketData data = FungibleTokenPacketData{denomination, amount, sender, receiver}
-  handler.sendPacket(Packet{timeoutHeight, timeoutTimestamp, destPort, destChannel, sourcePort, sourceChannel, data}, getCapability("port"))
+    prefix = "{sourcePort}/{sourceChannel}/"
+    // we are the source if the denomination is not prefixed
+    source = denomination.slice(0, len(prefix)) !== prefix
+    if source {
+      // determine escrow account
+      escrowAccount = channelEscrowAddresses[sourceChannel]
+      // escrow source tokens (assumed to fail if balance insufficient)
+      bank.TransferCoins(sender, escrowAccount, denomination, amount)
+    } else {
+      // receiver is source chain, burn vouchers
+      bank.BurnCoins(sender, denomination, amount)
+    }
+
+    // create FungibleTokenPacket data
+    data = FungibleTokenPacketData{denomination, amount, sender, receiver}
+
+    // send packet using the interface defined in ICS4
+    handler.sendPacket(
+      getCapability("port"),
+      sourcePort,
+      sourceChannel,
+      timeoutHeight,
+      timeoutTimestamp,
+      data
+    )
 }
 ```
 
@@ -242,18 +252,18 @@ function onRecvPacket(packet: Packet) {
   FungibleTokenPacketAcknowledgement ack = FungibleTokenPacketAcknowledgement{true, null}
   prefix = "{packet.sourcePort}/{packet.sourceChannel}/"
   // we are the source if the packets were prefixed by the sending chain
-  source = data.denomination.slice(0, len(prefix)) === prefix
+  source = data.denom.slice(0, len(prefix)) === prefix
   if source {
     // receiver is source chain: unescrow tokens
     // determine escrow account
     escrowAccount = channelEscrowAddresses[packet.destChannel]
     // unescrow tokens to receiver (assumed to fail if balance insufficient)
-    err = bank.TransferCoins(escrowAccount, data.receiver, data.denomination.slice(len(prefix)), data.amount)
+    err = bank.TransferCoins(escrowAccount, data.receiver, data.denom.slice(len(prefix)), data.amount)
     if (err !== nil)
       ack = FungibleTokenPacketAcknowledgement{false, "transfer coins failed"}
   } else {
     prefix = "{packet.destPort}/{packet.destChannel}/"
-    prefixedDenomination = prefix + data.denomination
+    prefixedDenomination = prefix + data.denom
     // sender was source, mint vouchers to receiver (assumed to fail if balance insufficient)
     err = bank.MintCoins(data.receiver, prefixedDenomination, data.amount)
     if (err !== nil)
@@ -291,14 +301,14 @@ function refundTokens(packet: Packet) {
   FungibleTokenPacketData data = packet.data
   prefix = "{packet.sourcePort}/{packet.sourceChannel}/"
   // we are the source if the denomination is not prefixed
-  source = denomination.slice(0, len(prefix)) !== prefix
+  source = data.denom.slice(0, len(prefix)) !== prefix
   if source {
     // sender was source chain, unescrow tokens back to sender
     escrowAccount = channelEscrowAddresses[packet.srcChannel]
-    bank.TransferCoins(escrowAccount, data.sender, data.denomination, data.amount)
+    bank.TransferCoins(escrowAccount, data.sender, data.denom, data.amount)
   } else {
     // receiver was source chain, mint vouchers back to sender
-    bank.MintCoins(data.sender, denomination, data.amount)
+    bank.MintCoins(data.sender, data.denom, data.amount)
   }
 }
 ```