ICS33: Multi-hop Channel Spec (#882)

* feat: add spec for multi-hop channels * chore: naming * chore: add notes on chain registry * Polymer/multihop (#1) * ICS20: Replace Metadata with Memo (#877) * memo string replacement * formatting Co-authored-by: Carlos Rodriguez <[email protected]> * ICS9: remove localhost client (#878) * remove localhost client * Update CHANGELOG.md * Update README.md * fix: update comment about channel state check in `sendPacket` (#865) * update comment * typo * remove comment Co-authored-by: Carlos Rodriguez <[email protected]> * ICS5: fix releasePort signature (#885) Signed-off-by: Jun Kimura <[email protected]> Signed-off-by: Jun Kimura <[email protected]> * ICS721: Add tokenData to PacketData (#876) * add tokenData to PacketData; improve TypeScript formatting * revert else style * extend 03-connection with a proof object for chains that can't introspect their own consensus state. (#839) * extend 03-connection with HostConsensusStateProof * make hostConsensusStateProof optional * ICS28: Reflect deferred unbonding completion in spec (#826) * call UnbondingCanComplete in EndBlock * update README * update ics23 link (#891) * update eli5 blog post link (#892) * ICS28: Sovereign to consumer chain transition (#840) * update CreateConsumerClient for sovereign chains * update InitGenesis for sovereign chains * establish CCV on ACK and handle preCCV completion * update Channel Uniqueness Correctness Reasoning * add pre-CCV module interface with staking * add clarifications * add overview TODO * fix pendingChanges bug * refactor proposal names (#855) * Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md Co-authored-by: Daniel T <[email protected]> * enable optimistic opening handshakes * remove ConsumerAdditionProposal.initialHeight * handle proposals in BeginBlock * pass consumer unbonding period via gov proposal * update channel init overview - wip * update overview * update modified date * add note re. the existing staking module Co-authored-by: Daniel T <[email protected]> * ICS28: VSCPackets should have timeout on provider (#858) * update CreateConsumerClient for sovereign chains * update InitGenesis for sovereign chains * establish CCV on ACK and handle preCCV completion * update Channel Uniqueness Correctness Reasoning * add pre-CCV module interface with staking * add clarifications * add overview TODO * fix pendingChanges bug * refactor proposal names * add VSC timeout * refactor proposal names (#855) * Update spec/app/ics-028-cross-chain-validation/system_model_and_properties.md Co-authored-by: Daniel T <[email protected]> * enable optimistic opening handshakes * remove ConsumerAdditionProposal.initialHeight * handle proposals in BeginBlock * pass consumer unbonding period via gov proposal * update channel init overview - wip * update overview * update modified date * ICS28: Channel initialization should have a timeout (#860) * add init timeout * fix typo * add note on timed out channel init * update vsc timeout as per implementation Co-authored-by: Daniel T <[email protected]> * add angbrav as code owner (#895) Co-authored-by: Carlos Rodriguez <[email protected]> * save progress * start adding proof generation logic and update graphical_proof.jpg * rm spec/.DS_Store Signed-off-by: Jun Kimura <[email protected]> Co-authored-by: Aditya <[email protected]> Co-authored-by: Carlos Rodriguez <[email protected]> Co-authored-by: Carlos Rodriguez <[email protected]> Co-authored-by: Jun Kimura <[email protected]> Co-authored-by: Haifeng Xi <[email protected]> Co-authored-by: Web3 Philosopher <[email protected]> Co-authored-by: Marius Poke <[email protected]> Co-authored-by: Daniel T <[email protected]> Co-authored-by: Carlos Rodriguez <[email protected]> * update to ics-033 * start updating channel spec for multihop; add diagram for relayer proof querying * chore: update spec history * chore: spacing * remove TODO comment; per PR feedback, connection proof not require for channel INIT * add comment to MultihopProof struct making the proof ordering more clear; update proof generation logic to not include the key which should be generated during verification * add verification proof pseudo code * add/update multihop proof verification logic * Update spec/core/ics-004-channel-and-packet-semantics/README.md Co-authored-by: Aditya <[email protected]> * Update spec/core/ics-033-multi-hop/README.md Co-authored-by: Aditya <[email protected]> * remove consState var to simplify consensusState update assignment * rename VerifyMultihopConsensusStateProof --> VerifyMultihopConsensusAndConnectionStateProofs to better reflect the function logic; further simplify the function logic and update comments * simplify multihop proof logic steps further * Ds/multihop (#4) update multi-hop diagrams and remove old diagrams * start updating multihop spec to include client state information in the proof * check consensus/connection proof lengths immediately * update spec with latest multihop solution * remove client state from multihop proofs * update spec with chanCloseFrozen; fix/update other parts of multihop spec * revise and update multihop spec details * add check to match client id in ConnectionEnd with client id in subsequent consensus state key * fix indentation * Update spec/core/ics-033-multi-hop/README.md Co-authored-by: Anca Zamfir <[email protected]> * Update spec/core/ics-033-multi-hop/README.md Co-authored-by: Anca Zamfir <[email protected]> * Update spec/core/ics-033-multi-hop/README.md Co-authored-by: Anca Zamfir <[email protected]> * Update spec/core/ics-004-channel-and-packet-semantics/README.md Co-authored-by: Anca Zamfir <[email protected]> * Update spec/core/ics-004-channel-and-packet-semantics/README.md Co-authored-by: Anca Zamfir <[email protected]> * Update spec/core/ics-004-channel-and-packet-semantics/README.md Co-authored-by: Anca Zamfir <[email protected]> * fix typo prevChain --> previousChain * add comments for connection and multihopConnectionEnd * Update spec/core/ics-003-connection-semantics/README.md Co-authored-by: Aditya <[email protected]> * add frozen channel proof generation logic * refactor getMaxDelayPeriod to return the time and block delay * use Identifier type instead of string for connectionHops array * cleanup proof gen pseudo code * check proof heights for consensus and connection states during multihop proof generation; use "proofHeight" instead of "keyHeight" for consistency * Update spec/core/ics-033-multi-hop/README.md Co-authored-by: Anca Zamfir <[email protected]> * cleanup multihop proof gen pseudo code * remove trailing whitespace; refactor multihop proof generation and add proof gen helper function descriptions * add extra info about connectionHops ordering; update proof ordering to match connectionHops (receiver --> sender) * clarify multi-hop proof verification now that proof ordering matches the connectionHops ordering (receiver --> sender) * address latest PR feedback * more pr feedback * address more multihop PR feedback * update multi-hop proof query/verification specs and add frozen channel proof logic * update multi-hop proof diagrams * wip address latest PR feedback * add more clarifying comments/explanations and incorporate more PR feedback --------- Signed-off-by: Jun Kimura <[email protected]> Co-authored-by: Derek <[email protected]> Co-authored-by: Aditya <[email protected]> Co-authored-by: Carlos Rodriguez <[email protected]> Co-authored-by: Carlos Rodriguez <[email protected]> Co-authored-by: Jun Kimura <[email protected]> Co-authored-by: Haifeng Xi <[email protected]> Co-authored-by: Web3 Philosopher <[email protected]> Co-authored-by: Marius Poke <[email protected]> Co-authored-by: Daniel T <[email protected]> Co-authored-by: Carlos Rodriguez <[email protected]> Co-authored-by: Anca Zamfir <[email protected]>
cosmos · Sep 14, 2023 · 727ae4c · 727ae4c
1 parent db5cee8
commit 727ae4c
Show file tree

Hide file tree

Showing 12 changed files with 1,083 additions and 154 deletions.
diff --git a/README.md b/README.md
@@ -39,6 +39,7 @@ All standards at or past the "Draft" stage are listed here in order of their ICS
 | [24](spec/core/ics-024-host-requirements/README.md)           | Host Requirements          | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | Protocol team |
 | [25](spec/core/ics-025-handler-interface/README.md)           | Handler Interface          | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | Protocol team |
 | [26](spec/core/ics-026-routing-module/README.md)              | Routing Module             | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | Protocol team |
+| [33](spec/core/ics-033-multi-hop/README.md)                   | Multi-hop Messaging        | Candidate | [ibc-go](https://github.com/cosmos/ibc-go) | Protocol team |
 
 ### Client
 

diff --git a/spec/.DS_Store b/spec/.DS_Store
diff --git a/spec/core/.DS_Store b/spec/core/.DS_Store
diff --git a/spec/core/ics-003-connection-semantics/README.md b/spec/core/ics-003-connection-semantics/README.md
@@ -258,11 +258,83 @@ function verifyNextSequenceRecv(
   return verifyMembership(clientState, height, connection.delayPeriodTime, connection.delayPeriodBlocks, proof, path, nextSequenceRecv)
 }
 
+function verifyMultihopMembership(
+  connection: ConnectionEnd, // the connection end corresponding to the receiving chain.
+  height: Height,
+  proof: MultihopProof,
+  connectionHops: Identifier[],
+  key: CommitmentPath,
+  value: bytes) {
+
+    // the connectionEnd corresponding to the end of the multi-hop channel path (sending/counterparty chain).
+    multihopConnectionEnd = abortTransactionUnless(getMultihopConnectionEnd(proof))
+    prefix = multihopConnectionEnd.GetCounterparty().GetPrefix()
+    client = queryClient(connection.clientIdentifier)
+    consensusState = queryConsensusState(connection.clientIdentifier, height)
+
+    abortTransactionUnless(client.Status() === "active")
+    abortTransactionUnless(client.GetLatestHeight() >= height)
+
+    // verify maximum delay period has passed
+    expectedTimePerBlock = queryMaxExpectedTimePerBlock()
+    delayPeriodTime = abortTransactionUnless(getMaximumDelayPeriod(proof, connection))
+    delayPeriodBlocks = getBlockDelay(delayPeriodTime, expectedTimePerBlock)
+    abortTransactionUnless(tendermint.VerifyDelayPeriodPassed(height, delayPeriodTime, delayPeriodBlocks))
+
+    return multihop.VerifyMultihopMembership(consensusState, connectionHops, proof, prefix, key, value) // see ics-033
+}
+
+function verifyMultihopNonMembership(
+  connection: ConnectionEnd, // the connection end corresponding to the receiving chain.
+  height: Height,
+  proof: MultihopProof,
+  connectionHops: Identifier[],
+  key: CommitmentPath) {
+
+    // the connectionEnd corresponding to the end of the multi-hop channel path (sending/counterparty chain).
+    multihopConnectionEnd = abortTransactionUnless(getMultihopConnectionEnd(proof))
+    prefix = multihopConnectionEnd.GetCounterparty().GetPrefix()
+    client = queryClient(connection.clientIdentifier)
+    consensusState = queryConsensusState(connection.clientIdentifier, height)
+
+    abortTransactionUnless(client.Status() === "active")
+    abortTransactionUnless(client.GetLatestHeight() >= height)
+
+    // verify maximum delay period has passed
+    expectedTimePerBlock = queryMaxExpectedTimePerBlock()
+    delayPeriodTime = abortTransactionUnless(getMaximumDelayPeriod(proof, connection))
+    delayPeriodBlocks = getBlockDelay(delayPeriodTime, expectedTimePerBlock)
+    abortTransactionUnless(tendermint.VerifyDelayPeriodPassed(height, delayPeriodTime, delayPeriodBlocks))
+
+    return multihop.VerifyMultihopNonMembership(consensusState, connectionHops, proof, prefix, key) // see ics-033
+}
+
+// Return the maximum expected time per block from the paramstore.
+// See 03-connection - GetMaxExpectedTimePerBlock.
+function queryMaxExpectedTimePerBlock(): uint64
+
 function getTimestampAtHeight(
   connection: ConnectionEnd,
   height: Height) {
     return queryConsensusState(connection.clientIdentifier, height).getTimestamp()
 }
+
+// Return the connectionEnd corresponding to the source chain.
+function getMultihopConnectionEnd(proof: MultihopProof): ConnectionEnd {
+  return abortTransactionUnless(Unmarshal(proof.ConnectionProofs[proof.ConnectionProofs.length - 1].Value))
+}
+
+// Return the maximum delay period in seconds across all connections in the channel path.
+function getMaximumDelayPeriod(proof: MultihopProof, lastConnection: ConnectionEnd): number {
+  delayPeriodTime = lastConnection.GetDelayPeriod()
+  for connData in range proofs.ConnectionProofs {
+    connectionEnd = abortTransactionUnless(Unmarshal(connData.Value))
+    if (connectionEnd.DelayPeriod > delayPeriodTime) {
+      delayPeriodTime = connectionEnd.DelayPeriod
+    }
+  }
+  return delayPeriodTime
+}
 ```
 
 ### Sub-protocols
@@ -282,7 +354,7 @@ The validation function `validateConnectionIdentifier` MAY be provided.
 type validateConnectionIdentifier = (id: Identifier) => boolean
 ```
 
-If not provided, the default `validateConnectionIdentifier` function will always return `true`. 
+If not provided, the default `validateConnectionIdentifier` function will always return `true`.
 
 #### Versioning
 
@@ -301,7 +373,7 @@ specifies IBC 1.0.0.
 
 The `features` field specifies a list of features compatible with the specified
 identifier. The values `"ORDER_UNORDERED"` and `"ORDER_ORDERED"` specify
-unordered and ordered channels, respectively. 
+unordered and ordered channels, respectively.
 
 Host state machine MUST utilise the version data to negotiate encodings,
 priorities, or connection-specific metadata related to custom logic on top of
@@ -367,7 +439,7 @@ function connOpenInit(
 
     abortTransactionUnless(queryClientState(clientIdentifier) !== null)
     abortTransactionUnless(provableStore.get(connectionPath(identifier)) == null)
-    
+
     state = INIT
     if version != "" {
       // manually selected version must be one we can support
@@ -404,7 +476,7 @@ function connOpenTry(
 ) {
     // generate a new identifier
     identifier = generateIdentifier()
-    
+
     abortTransactionUnless(queryClientState(clientIdentifier) !== null)
     abortTransactionUnless(validateSelfClient(clientState))
     abortTransactionUnless(consensusHeight < getCurrentHeight())