diff --git a/README.md b/README.md index 0ee67c68b42a..a9f1dc8a068a 100644 --- a/README.md +++ b/README.md @@ -30,20 +30,20 @@ All standards in the "draft" stage are listed here in order of their ICS numbers ### Meta -| Interchain Standard Number | Standard Title | Stage | -| ---------------------------- | -------------------------- | ----- | -| [1](spec/ics-1-ics-standard) | ICS Specification Standard | Draft | +| Interchain Standard Number | Standard Title | Stage | +| ------------------------------ | -------------------------- | ----- | +| [1](spec/ics-001-ics-standard) | ICS Specification Standard | Draft | ### IBC (Core) | Interchain Standard Number | Standard Title | Stage | | --------------------------------------------------- | ---------------------------------- | ----- | -| [2](spec/ics-2-consensus-verification) | Consensus Verification | Draft | -| [3](spec/ics-3-connection-semantics) | Connection Semantics | Draft | -| [4](spec/ics-4-channel-and-packet-semantics) | Channel & Packet Semantics | Draft | -| [18](spec/ics-18-relayer-algorithms) | Relayer Algorithms | Draft | -| [23](spec/ics-23-vector-commitments) | Vector Commitments | Draft | -| [24](spec/ics-24-host-requirements) | Host Requirements | Draft | +| [2](spec/ics-002-consensus-verification) | Consensus Verification | Draft | +| [3](spec/ics-003-connection-semantics) | Connection Semantics | Draft | +| [4](spec/ics-004-channel-and-packet-semantics) | Channel & Packet Semantics | Draft | +| [18](spec/ics-018-relayer-algorithms) | Relayer Algorithms | Draft | +| [23](spec/ics-023-vector-commitments) | Vector Commitments | Draft | +| [24](spec/ics-024-host-requirements) | Host Requirements | Draft | ## Standard Dependency Visualization diff --git a/deps.png b/deps.png index 2db0853ee169..758724e748e4 100644 --- a/deps.png +++ b/deps.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:7942cc5b9c4a1a2a96e400293af3e4746f304a4ad281c32e5364e4955eb30b11 -size 36640 +oid sha256:6ea263078c31fb780f202e005e84bc57943e7d0742a0f910c8a18b26c5b7a5a8 +size 42633 diff --git a/ibc/1_IBC_ARCHITECTURE.md b/ibc/1_IBC_ARCHITECTURE.md index 66e8383aa178..6fd0c2d55312 100644 --- a/ibc/1_IBC_ARCHITECTURE.md +++ b/ibc/1_IBC_ARCHITECTURE.md @@ -56,7 +56,7 @@ IBC sits between modules — smart contracts, other state machine components, or IBC provides to modules a set of functions much like the functions which might be provided to a module for interacting with another module on the same ledger: sending data packets and receiving data packets on an established connection & channel (primitives for authentication & ordering, see [definitions](./3_IBC_TERMINOLOGY.md)) — in addition to calls to manage the protocol state: opening and closing connections and channels, choosing connection, channel, and packet delivery options, and inspecting connection & channel status. -IBC assumes functionalities and properties of the underlying consensus protocols and ledgers as defined in [ICS 2](../../spec/ics-2-consensus-requirements), primarily finality, cheaply-verifiable consensus transcripts, and simple key-value store functionality. On the network side, IBC requires only eventual data delivery — no authentication, synchrony, or ordering properties are assumed. +IBC assumes functionalities and properties of the underlying consensus protocols and ledgers as defined in [ICS 2](../../spec/ics-002-consensus-verification), primarily finality, cheaply-verifiable consensus transcripts, and simple key-value store functionality. On the network side, IBC requires only eventual data delivery — no authentication, synchrony, or ordering properties are assumed. ### Protocol relations @@ -152,16 +152,16 @@ Consider the path of an IBC packet between two chains — call them *A* and *B*: 1. On chain *A* 1. Module (application-specific) 1. Handler (parts defined in different ICSs) - 1. Packet (defined in [ICS 4](../spec/ics-4-channel-and-packet-semantics)) - 1. Channel (defined in [ICS 4](../spec/ics-4-channel-and-packet-semantics)) - 1. Connection (defined in [ICS 3](../spec/ics-3-connection-semantics)) - 1. Consensus (defined in [ICS 2](../spec/ics-2-consensus-verification)) + 1. Packet (defined in [ICS 4](../spec/ics-004-channel-and-packet-semantics)) + 1. Channel (defined in [ICS 4](../spec/ics-004-channel-and-packet-semantics)) + 1. Connection (defined in [ICS 3](../spec/ics-003-connection-semantics)) + 1. Consensus (defined in [ICS 2](../spec/ics-002-consensus-verification)) 2. Off-chain - 1. Relayer (defined in [ICS 18](../../spec/ics-18-relayer-algorithms)) + 1. Relayer (defined in [ICS 18](../../spec/ics-018-relayer-algorithms)) 3. On chain *B* - 1. Consensus (defined in [ICS 2](/../spec/ics-2-consensus-verification)) - 1. Connection (defined in [ICS 3](/../spec/ics-3-connection-semantics)) - 1. Channel (defined in [ICS 4](/../spec/ics-4-channel-and-packet-semantics)) - 1. Packet (defined in [ICS 4](/../spec/ics-4-channel-and-packet-semantics)) + 1. Consensus (defined in [ICS 2](/../spec/ics-002-consensus-verification)) + 1. Connection (defined in [ICS 3](/../spec/ics-003-connection-semantics)) + 1. Channel (defined in [ICS 4](/../spec/ics-004-channel-and-packet-semantics)) + 1. Packet (defined in [ICS 4](/../spec/ics-004-channel-and-packet-semantics)) 1. Handler (parts defined in different ICSs) 1. Module (application-specific) diff --git a/scripts/check_sections.py b/scripts/check_sections.py index 751501b93bc3..272bd58fc4f4 100755 --- a/scripts/check_sections.py +++ b/scripts/check_sections.py @@ -7,7 +7,7 @@ sub_sub_section_regex = re.compile('[^#]### (.*)') specs = [f.path for f in os.scandir('./spec') if f.is_dir()] -files = [f.path for spec in specs for f in os.scandir(spec) if f.is_file() and f.path[-9:] == 'README.md' and 'ics-1-ics-standard' not in f.path] +files = [f.path for spec in specs for f in os.scandir(spec) if f.is_file() and f.path[-9:] == 'README.md' and 'ics-001-ics-standard' not in f.path] expected_sub_sections = ['Synopsis', 'Technical Specification', 'Backwards Compatibility', 'Forwards Compatibility', 'Example Implementation', 'Other Implementations', 'History', 'Copyright'] expected_sub_sub_sections = ['Motivation', 'Definitions', 'Desired Properties'] diff --git a/spec/ics-1-ics-standard/README.md b/spec/ics-001-ics-standard/README.md similarity index 100% rename from spec/ics-1-ics-standard/README.md rename to spec/ics-001-ics-standard/README.md diff --git a/spec/ics-2-consensus-verification/CONSENSUS.md b/spec/ics-002-consensus-verification/CONSENSUS.md similarity index 100% rename from spec/ics-2-consensus-verification/CONSENSUS.md rename to spec/ics-002-consensus-verification/CONSENSUS.md diff --git a/spec/ics-2-consensus-verification/README.md b/spec/ics-002-consensus-verification/README.md similarity index 99% rename from spec/ics-2-consensus-verification/README.md rename to spec/ics-002-consensus-verification/README.md index 14326d40f331..23cd80ce2111 100644 --- a/spec/ics-2-consensus-verification/README.md +++ b/spec/ics-002-consensus-verification/README.md @@ -33,9 +33,9 @@ as long as associated light client algorithms fulfilling the requirements are pr ### Definitions -* `get`, `set`, `Key`, and `Identifier` are as defined in [ICS 24](../ics-24-host-requirements). +* `get`, `set`, `Key`, and `Identifier` are as defined in [ICS 24](../ics-024-host-requirements). -* `CommitmentRoot` is as defined in [ICS 23](../ics-23-vector-commitments). +* `CommitmentRoot` is as defined in [ICS 23](../ics-023-vector-commitments). * `ConsensusState` is an opaque type representing the verification state of a light client. `ConsensusState` must be able to verify state updates agreed upon by the associated consensus algorithm, diff --git a/spec/ics-3-connection-semantics/Makefile b/spec/ics-003-connection-semantics/Makefile similarity index 100% rename from spec/ics-3-connection-semantics/Makefile rename to spec/ics-003-connection-semantics/Makefile diff --git a/spec/ics-3-connection-semantics/README.md b/spec/ics-003-connection-semantics/README.md similarity index 94% rename from spec/ics-3-connection-semantics/README.md rename to spec/ics-003-connection-semantics/README.md index 9891353c9041..80aa2bdcd796 100644 --- a/spec/ics-3-connection-semantics/README.md +++ b/spec/ics-003-connection-semantics/README.md @@ -16,15 +16,15 @@ This standards document describes the abstraction of an IBC *connection*: two st ### Motivation -The core IBC protocol provides *authorization* and *ordering* semantics for packets: guarantees, respectively, that packets have been committed on the sending blockchain (and according state transitions executed, such as escrowing tokens), and that they have been committed exactly once in a particular order and can be delivered exactly once in that same order. The *connection* abstraction specified in this standard, in conjunction with the *client* abstraction specified in [ICS 2](../ics-2-consensus-verification), defines the *authorization* semantics of IBC. Ordering semantics are described in [ICS 4](../ics-4-channel-and-packet-semantics)). +The core IBC protocol provides *authorization* and *ordering* semantics for packets: guarantees, respectively, that packets have been committed on the sending blockchain (and according state transitions executed, such as escrowing tokens), and that they have been committed exactly once in a particular order and can be delivered exactly once in that same order. The *connection* abstraction specified in this standard, in conjunction with the *client* abstraction specified in [ICS 2](../ics-002-consensus-verification), defines the *authorization* semantics of IBC. Ordering semantics are described in [ICS 4](../ics-004-channel-and-packet-semantics)). ### Definitions -`ConsensusState`, `Header`, and `updateConsensusState` are as defined in [ICS 2](../ics-2-consensus-verification). +`ConsensusState`, `Header`, and `updateConsensusState` are as defined in [ICS 2](../ics-002-consensus-verification). -`CommitmentProof`, `verifyMembership`, and `verifyNonMembership` are as defined in [ICS 23](../ics-23-vector-commitments). +`CommitmentProof`, `verifyMembership`, and `verifyNonMembership` are as defined in [ICS 23](../ics-023-vector-commitments). -`Identifier` and other host state machine requirements are as defined in [ICS 24](../ics-24-host-requirements). The identifier is not necessarily intended to be a human-readable name (and likely should not be, to discourage squatting or racing for identifiers). +`Identifier` and other host state machine requirements are as defined in [ICS 24](../ics-024-host-requirements). The identifier is not necessarily intended to be a human-readable name (and likely should not be, to discourage squatting or racing for identifiers). The opening handshake protocol allows each chain to verify the identifier used to reference the connection on the other chain, enabling modules on each chain to reason about the reference on the other chain. @@ -88,7 +88,7 @@ interface Connection { ### Subprotocols -This ICS defines two subprotocols: opening handshake and closing handshake. Header tracking and closing-by-equivocation are defined in [ICS 2](../ics-2-consensus-verification). Datagrams defined herein are handled as external messages by the IBC relayer module defined in ICS 26. +This ICS defines two subprotocols: opening handshake and closing handshake. Header tracking and closing-by-equivocation are defined in [ICS 2](../ics-002-consensus-verification). Datagrams defined herein are handled as external messages by the IBC relayer module defined in ICS 26. ![State Machine Diagram](state.png) @@ -275,7 +275,7 @@ function connOpenTimeout(identifier: Identifier, proofTimeout: CommitmentProof, #### Header Tracking -Headers are tracked at the client level. See [ICS 2](../ics-2-consensus-verification). +Headers are tracked at the client level. See [ICS 2](../ics-002-consensus-verification). #### Closing Handshake @@ -407,7 +407,7 @@ function connCloseTimeout(identifier: Identifier, proofTimeout: CommitmentProof, #### Freezing by Equivocation -The equivocation detection subprotocol is defined in [ICS 2](../ics-2-consensus-verification). If a client is frozen by equivocation, all associated connections are immediately frozen as well. +The equivocation detection subprotocol is defined in [ICS 2](../ics-002-consensus-verification). If a client is frozen by equivocation, all associated connections are immediately frozen as well. Implementing chains may want to allow applications to register handlers to take action upon discovery of an equivocation. Further discussion is deferred to ICS 12. diff --git a/spec/ics-3-connection-semantics/state.png b/spec/ics-003-connection-semantics/state.png similarity index 100% rename from spec/ics-3-connection-semantics/state.png rename to spec/ics-003-connection-semantics/state.png diff --git a/spec/ics-3-connection-semantics/state.tex b/spec/ics-003-connection-semantics/state.tex similarity index 100% rename from spec/ics-3-connection-semantics/state.tex rename to spec/ics-003-connection-semantics/state.tex diff --git a/spec/ics-4-channel-and-packet-semantics/Makefile b/spec/ics-004-channel-and-packet-semantics/Makefile similarity index 100% rename from spec/ics-4-channel-and-packet-semantics/Makefile rename to spec/ics-004-channel-and-packet-semantics/Makefile diff --git a/spec/ics-4-channel-and-packet-semantics/README.md b/spec/ics-004-channel-and-packet-semantics/README.md similarity index 99% rename from spec/ics-4-channel-and-packet-semantics/README.md rename to spec/ics-004-channel-and-packet-semantics/README.md index d10f8ea6ee2b..a730b92f94dd 100644 --- a/spec/ics-4-channel-and-packet-semantics/README.md +++ b/spec/ics-004-channel-and-packet-semantics/README.md @@ -25,15 +25,15 @@ In order to provide the desired ordering, exactly-once delivery, and module perm ### Definitions -`ConsensusState` is as defined in [ICS 2](../ics-2-consensus-verification). +`ConsensusState` is as defined in [ICS 2](../ics-002-consensus-verification). -`Connection` is as defined in [ICS 3](../ics-3-connection-semantics). +`Connection` is as defined in [ICS 3](../ics-003-connection-semantics). -`Commitment`, `CommitmentProof`, and `CommitmentRoot` are as defined in [ICS 23](../ics-23-vector-commitments). +`Commitment`, `CommitmentProof`, and `CommitmentRoot` are as defined in [ICS 23](../ics-023-vector-commitments). `commit` is a generic collision-resistant hash function, the specifics of which must be agreed on by the modules utilizing the channel. -`Identifier`, `get`, `set`, `delete`, `getConsensusState`, and module-system related primitives are as defined in [ICS 24](../ics-24-host-requirements). +`Identifier`, `get`, `set`, `delete`, `getConsensusState`, and module-system related primitives are as defined in [ICS 24](../ics-024-host-requirements). A *channel* is a pipeline for exactly-once packet delivery between specific modules on separate blockchains, which has at least one end capable of sending packets and one end capable of receiving packets. diff --git a/spec/ics-4-channel-and-packet-semantics/channel-state-machine.png b/spec/ics-004-channel-and-packet-semantics/channel-state-machine.png similarity index 100% rename from spec/ics-4-channel-and-packet-semantics/channel-state-machine.png rename to spec/ics-004-channel-and-packet-semantics/channel-state-machine.png diff --git a/spec/ics-4-channel-and-packet-semantics/channel-state-machine.tex b/spec/ics-004-channel-and-packet-semantics/channel-state-machine.tex similarity index 100% rename from spec/ics-4-channel-and-packet-semantics/channel-state-machine.tex rename to spec/ics-004-channel-and-packet-semantics/channel-state-machine.tex diff --git a/spec/ics-4-channel-and-packet-semantics/dataflow.png b/spec/ics-004-channel-and-packet-semantics/dataflow.png similarity index 100% rename from spec/ics-4-channel-and-packet-semantics/dataflow.png rename to spec/ics-004-channel-and-packet-semantics/dataflow.png diff --git a/spec/ics-4-channel-and-packet-semantics/dataflow.tex b/spec/ics-004-channel-and-packet-semantics/dataflow.tex similarity index 100% rename from spec/ics-4-channel-and-packet-semantics/dataflow.tex rename to spec/ics-004-channel-and-packet-semantics/dataflow.tex diff --git a/spec/ics-4-channel-and-packet-semantics/packet-state-machine.png b/spec/ics-004-channel-and-packet-semantics/packet-state-machine.png similarity index 100% rename from spec/ics-4-channel-and-packet-semantics/packet-state-machine.png rename to spec/ics-004-channel-and-packet-semantics/packet-state-machine.png diff --git a/spec/ics-4-channel-and-packet-semantics/packet-state-machine.tex b/spec/ics-004-channel-and-packet-semantics/packet-state-machine.tex similarity index 100% rename from spec/ics-4-channel-and-packet-semantics/packet-state-machine.tex rename to spec/ics-004-channel-and-packet-semantics/packet-state-machine.tex diff --git a/spec/ics-18-relayer-algorithms/README.md b/spec/ics-018-relayer-algorithms/README.md similarity index 100% rename from spec/ics-18-relayer-algorithms/README.md rename to spec/ics-018-relayer-algorithms/README.md diff --git a/spec/ics-23-vector-commitments/README.md b/spec/ics-023-vector-commitments/README.md similarity index 99% rename from spec/ics-23-vector-commitments/README.md rename to spec/ics-023-vector-commitments/README.md index 2a3a8c36783e..86c8d2a49a33 100644 --- a/spec/ics-23-vector-commitments/README.md +++ b/spec/ics-023-vector-commitments/README.md @@ -23,7 +23,7 @@ In order to provide a guarantee of a particular state transition having occurred The *manager* of a vector commitment is the actor with the ability and responsibility to add or remove items from the commitment. Generally this will be the state machine of a blockchain. -The *prover* is the actor responsible for generating proofs of inclusion or non-inclusion of particular elements. Generally this will be a relayer (see [ICS 18](../ics-18-relayer-algorithms)). +The *prover* is the actor responsible for generating proofs of inclusion or non-inclusion of particular elements. Generally this will be a relayer (see [ICS 18](../ics-018-relayer-algorithms)). The *verifier* is the actor who checks proofs in order to verify that the manager of the commitment did or did not add a particular element. Generally this will be an IBC handler (module implementing IBC) running on another chain. diff --git a/spec/ics-24-host-requirements/README.md b/spec/ics-024-host-requirements/README.md similarity index 98% rename from spec/ics-24-host-requirements/README.md rename to spec/ics-024-host-requirements/README.md index c76f0728904b..b6284f6d8d90 100644 --- a/spec/ics-24-host-requirements/README.md +++ b/spec/ics-024-host-requirements/README.md @@ -20,7 +20,7 @@ IBC is designed to be a common standard which will be hosted by a variety of blo ### Definitions -`ConsensusState` is as defined in [ICS 2](../ics-2-consensus-verification). +`ConsensusState` is as defined in [ICS 2](../ics-002-consensus-verification). ### Desired Properties