From a0649cba65bc07dcc376c4d4890ffe198f29e57b Mon Sep 17 00:00:00 2001 From: Alexandre Esteves <2335822+alexfmpe@users.noreply.github.com> Date: Sun, 20 Oct 2019 20:21:34 +0100 Subject: [PATCH] Merge PR #290: Doc fixes --- ibc/1_IBC_TERMINOLOGY.md | 2 +- ibc/2_IBC_ARCHITECTURE.md | 2 +- ibc/3_IBC_DESIGN_PRINCIPLES.md | 2 +- spec/ics-002-client-semantics/README.md | 6 +++--- spec/ics-003-connection-semantics/README.md | 2 +- spec/ics-004-channel-and-packet-semantics/README.md | 2 +- spec/ics-005-port-allocation/README.md | 10 +++++----- spec/ics-020-fungible-token-transfer/README.md | 4 ++-- spec/ics-023-vector-commitments/README.md | 6 +++--- spec/ics-024-host-requirements/README.md | 4 ++-- spec/ics-026-routing-module/README.md | 4 ++-- 11 files changed, 22 insertions(+), 22 deletions(-) diff --git a/ibc/1_IBC_TERMINOLOGY.md b/ibc/1_IBC_TERMINOLOGY.md index b2992c713811..cdd0b657cdb1 100644 --- a/ibc/1_IBC_TERMINOLOGY.md +++ b/ibc/1_IBC_TERMINOLOGY.md @@ -1,4 +1,4 @@ -# 3: IBC Terminology +# 1: IBC Terminology **This is an overview of terms used in IBC specifications.** diff --git a/ibc/2_IBC_ARCHITECTURE.md b/ibc/2_IBC_ARCHITECTURE.md index 4327e5b59ba7..dd47df427bf0 100644 --- a/ibc/2_IBC_ARCHITECTURE.md +++ b/ibc/2_IBC_ARCHITECTURE.md @@ -1,4 +1,4 @@ -# 1: Inter-blockchain Communication Protocol Architecture +# 2: Inter-blockchain Communication Protocol Architecture **This is an overview of the high-level architecture & data-flow of the IBC protocol.** diff --git a/ibc/3_IBC_DESIGN_PRINCIPLES.md b/ibc/3_IBC_DESIGN_PRINCIPLES.md index 65828a6a2017..76bbeb041ab8 100644 --- a/ibc/3_IBC_DESIGN_PRINCIPLES.md +++ b/ibc/3_IBC_DESIGN_PRINCIPLES.md @@ -1,4 +1,4 @@ -# 2: IBC Design Principles +# 3: IBC Design Principles **This is an explanation of the "design principles" of IBC.** diff --git a/spec/ics-002-client-semantics/README.md b/spec/ics-002-client-semantics/README.md index ad5c6b1379a4..83ff3ab2ae02 100644 --- a/spec/ics-002-client-semantics/README.md +++ b/spec/ics-002-client-semantics/README.md @@ -187,14 +187,14 @@ The headers generated from a `Blockchain` are expected to satisfy the following: * Satisfied if: correct block generation & state machine * Possible violation scenario: invariant break, super-majority validator cartel -If the blockchain does not satisfy any of the above then the IBC protocol +Unless the blockchain satisfies all of the above the IBC protocol may not work as intended: the chain can receive multiple conflicting packets, the chain cannot recover from the timeout event, the chain can steal the user's asset, etc. The validity of the validity predicate is dependent on the security model of the `Consensus`. For example, the `Consensus` can be a proof of authority with -a trusted operator, or the a proof of stake but with +a trusted operator, or a proof of stake but with insufficient value of stake. In such cases, it is possible that the security assumptions break, the correspondence between `Consensus` and the validity predicate no longer exists, and the behaviour of the validity predicate becomes @@ -520,7 +520,7 @@ Not applicable. ## Forwards Compatibility -New client types can be added by IBC implementations at-will as long as they confirm to this interface. +New client types can be added by IBC implementations at-will as long as they conform to this interface. ## Example Implementation diff --git a/spec/ics-003-connection-semantics/README.md b/spec/ics-003-connection-semantics/README.md index a4f64cd294ed..5f6a4a1bd7d8 100644 --- a/spec/ics-003-connection-semantics/README.md +++ b/spec/ics-003-connection-semantics/README.md @@ -275,7 +275,7 @@ function connOpenTry( abortTransactionUnless(provableStore.get(connectionPath(desiredIdentifier)) === null) identifier = desiredIdentifier state = TRYOPEN - provableStore.set(connectionPath(identifier), connection) + provableStore.set(connectionPath(identifier), connection) addConnectionToClient(clientIdentifier, identifier) } ``` diff --git a/spec/ics-004-channel-and-packet-semantics/README.md b/spec/ics-004-channel-and-packet-semantics/README.md index 44a00ccb4fed..9df7dedba6aa 100644 --- a/spec/ics-004-channel-and-packet-semantics/README.md +++ b/spec/ics-004-channel-and-packet-semantics/README.md @@ -645,7 +645,7 @@ can no longer be executed and to allow the calling module to safely perform appr Calling modules MAY atomically execute appropriate application timeout-handling logic in conjunction with calling `timeoutPacket`. -In the case of an ordered channel, `timeoutPacket` checks the recvSequence of the receiving channel end and closes the channel if a packet has timed out. +In the case of an ordered channel, `timeoutPacket` checks the `recvSequence` of the receiving channel end and closes the channel if a packet has timed out. In the case of an unordered channel, `timeoutPacket` checks the absence of an acknowledgement (which will have been written if the packet was received). Unordered channels are expected to continue in the face of timed-out packets. diff --git a/spec/ics-005-port-allocation/README.md b/spec/ics-005-port-allocation/README.md index 2714021f6cc7..e0ab57f755a9 100644 --- a/spec/ics-005-port-allocation/README.md +++ b/spec/ics-005-port-allocation/README.md @@ -67,7 +67,7 @@ As a helpful comparison, the following analogies to TCP are roughly accurate: The host state machine MUST support either object-capability reference or source authentication for modules. In the former object-capability case, the IBC handler must have the ability to generate *object-capabilities*, unique, opaque references -which can be passed to a module and will not be duplicable by other modules. Two examples are store keys as used in the Cosmos SDK ([reference](https://github.com/cosmos/cosmos-sdk/blob/master/store/types/store.go#L224)) +which can be passed to a module and will not be duplicable by other modules. Two examples are store keys as used in the Cosmos SDK ([reference](https://github.com/cosmos/cosmos-sdk/blob/97eac176a5d533838333f7212cbbd79beb0754bc/store/types/store.go#L275)) and object references as used in Agoric's Javascript runtime ([reference](https://github.com/Agoric/SwingSet)). ```typescript @@ -98,13 +98,13 @@ function callingModuleIdentifier(): SourceIdentifier { In the former case, `generate` returns a new object-capability key, which must be returned by the outer-layer function, and `authenticate` requires that the outer-layer function take an extra argument `capability`, which is an object-capability key with uniqueness enforced by the host state machine. Outer-layer functions are any functions exposed by the IBC handler ([ICS 25](../ics-025-handler-interface)) or routing module ([ICS 26](../ics-026-routing-module)) to modules. -``` +```typescript function generate(): CapabilityKey { return newCapabilityPath() } ``` -``` +```typescript function authenticate(key: CapabilityKey): boolean { return capability === key } @@ -112,13 +112,13 @@ function authenticate(key: CapabilityKey): boolean { In the latter case, `generate` returns the calling module's identifier and `authenticate` merely checks it. -``` +```typescript function generate(): SourceIdentifier { return callingModuleIdentifier() } ``` -``` +```typescript function authenticate(id: SourceIdentifier): boolean { return callingModuleIdentifier() === id } diff --git a/spec/ics-020-fungible-token-transfer/README.md b/spec/ics-020-fungible-token-transfer/README.md index 9f36b00d83ae..a9c88105007a 100644 --- a/spec/ics-020-fungible-token-transfer/README.md +++ b/spec/ics-020-fungible-token-transfer/README.md @@ -27,7 +27,7 @@ The IBC handler interface & IBC routing module interface are as defined in [ICS - Preservation of total supply (constant or inflationary on a single source chain & module). - Permissionless token transfers, no need to whitelist connections, modules, or denominations. - Symmetric (all chains implement the same logic, no in-protocol differentiation of hubs & zones). -- Fault containment: prevents Byzantine-inflation of tokens originating on chain `A`, on chain `A`, as a result of chain `B`'s Byzantine behaviour (though any users who sent tokens to chain `B` may be at risk). +- Fault containment: prevents Byzantine-inflation of tokens originating on chain `A`, as a result of chain `B`'s Byzantine behaviour (though any users who sent tokens to chain `B` may be at risk). ## Technical Specification @@ -84,7 +84,7 @@ An administrator (with the permissions to create connections & channels on the h to other instances of this module (or another module supporting this interface) on other chains. This specification defines packet handling semantics only, and defines them in such a fashion that the module itself doesn't need to worry about what connections or channels might or might not exist at any point in time. -#### routing module callbacks +#### Routing module callbacks ##### Channel lifecycle management diff --git a/spec/ics-023-vector-commitments/README.md b/spec/ics-023-vector-commitments/README.md index a648107efbf0..16beb43f075c 100644 --- a/spec/ics-023-vector-commitments/README.md +++ b/spec/ics-023-vector-commitments/README.md @@ -43,7 +43,7 @@ A commitment construction MUST specify the following datatypes, which are otherw #### Commitment State -An `CommitmentState` is the full state of the commitment, which will be stored by the manager. +A `CommitmentState` is the full state of the commitment, which will be stored by the manager. ```typescript type CommitmentState = object @@ -51,7 +51,7 @@ type CommitmentState = object #### Commitment Root -An `CommitmentRoot` commits to a particular commitment state and should be constant-size. +A `CommitmentRoot` commits to a particular commitment state and should be constant-size. In certain commitment constructions with constant-size states, `CommitmentState` and `CommitmentRoot` may be the same type. @@ -89,7 +89,7 @@ type applyPrefix = (prefix: CommitmentPrefix, path: Path) => CommitmentPath #### Proof -An `CommitmentProof` demonstrates membership or non-membership for an element or set of elements, verifiable in conjunction with a known commitment root. Proofs should be succinct. +A `CommitmentProof` demonstrates membership or non-membership for an element or set of elements, verifiable in conjunction with a known commitment root. Proofs should be succinct. ```typescript type CommitmentProof = object diff --git a/spec/ics-024-host-requirements/README.md b/spec/ics-024-host-requirements/README.md index 096aa3183f3f..1e76a1004406 100644 --- a/spec/ics-024-host-requirements/README.md +++ b/spec/ics-024-host-requirements/README.md @@ -188,7 +188,7 @@ For a host state machine, the return value of `getCommitmentPrefix` MUST be cons Host state machines MUST implement a port system, where the IBC handler can allow different modules in the host state machine to bind to uniquely named ports. Ports are identified by an `Identifier`. -Host state machines MUST permission interaction with the IBC handler such that: +Host state machines MUST implement permission interaction with the IBC handler such that: - Once a module has bound to a port, no other modules can use that port until the module releases it - A single module can bind to multiple ports @@ -200,7 +200,7 @@ Modules that wish to make use of particular IBC features MAY implement certain h ### Datagram submission -Host state machines which implement the routing module MAY define a `submitDatagram` function to submit [datagrams](../../docs/ibc/2_IBC_TERMINOLOGY.md), which will be included in transactions, directly to the routing module (defined in [ICS 26](../ics-026-routing-module): +Host state machines which implement the routing module MAY define a `submitDatagram` function to submit [datagrams](../../ibc/1_IBC_TERMINOLOGY.md), which will be included in transactions, directly to the routing module (defined in [ICS 26](../ics-026-routing-module)): ```typescript type submitDatagram = (datagram: Datagram) => void diff --git a/spec/ics-026-routing-module/README.md b/spec/ics-026-routing-module/README.md index d4b66685f547..98fc00baf22b 100644 --- a/spec/ics-026-routing-module/README.md +++ b/spec/ics-026-routing-module/README.md @@ -477,7 +477,7 @@ interface ChanOpenConfirm { ```typescript function handleChanOpenConfirm(datagram: ChanOpenConfirm) { - module = lookupModule(portIdentifier) + module = lookupModule(datagram.portIdentifier) module.onChanOpenConfirm( datagram.portIdentifier, datagram.channelIdentifier @@ -500,7 +500,7 @@ interface ChanCloseInit { ```typescript function handleChanCloseInit(datagram: ChanCloseInit) { - module = lookupModule(portIdentifier) + module = lookupModule(datagram.portIdentifier) module.onChanCloseInit( datagram.portIdentifier, datagram.channelIdentifier