Skip to content

Commit

Permalink
Merge PR cosmos#447: Abstract height type
Browse files Browse the repository at this point in the history
  • Loading branch information
@cwgoes
cwgoes authored Jul 21, 2020
1 parent 771c519 commit a06d603
Show file tree
Hide file tree
Showing 10 changed files with 231 additions and 95 deletions.
17 changes: 16 additions & 1 deletion misc/aspell_dict
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
personal_ws-1.1 en 608
personal_ws-1.1 en 623
ABCI
ABI
ADR
Expand Down Expand Up @@ -42,6 +42,7 @@ Devs
Directionality
Dogemos
EIP
EQ
ERC
EVM
EmptyLogStore
Expand Down Expand Up @@ -86,6 +87,7 @@ OpHeaderProof
OpValidityPredicate
OpValidityPredicateBase
OpaquePacket
Ord
POC
PacketAcknowledgement
PacketCleanup
Expand All @@ -97,6 +99,7 @@ PacketTimeoutOnClose
Polkadot
Pre
Privkey
ProofSpec
Protobuf
PubKey
QUIC
Expand All @@ -118,6 +121,7 @@ TCP
TLS
TRYOPEN
Tendermint
TendermintHeight
Tezos
TransferCoins
Tribble
Expand Down Expand Up @@ -171,6 +175,7 @@ callbackKey
callbackPath
calldata
callingModuleIdentifier
chainID
chainType
chanCloseConfirm
chanCloseInit
Expand Down Expand Up @@ -289,6 +294,8 @@ emitLogEntry
encodings
endian
enum
epochHeight
epochNumber
errorCode
escrowAccount
escrowAddress
Expand Down Expand Up @@ -379,6 +386,7 @@ localEnd
logEntry
lookupModule
loopback
maxClockDrift
md
mempools
middled
Expand All @@ -394,6 +402,7 @@ newCallbacks
newCapability
newCapabilityKey
newCapabilityPath
newClientState
newPublicKey
newState
newpubkey
Expand Down Expand Up @@ -447,6 +456,7 @@ portOnB
portOnD
portPath
positionally
pre
precommit
precommits
prefixedPath
Expand All @@ -459,6 +469,7 @@ proofConsensus
proofHeight
proofInit
proofNonMembership
proofSpecs
proofTimeout
proofTry
proto
Expand Down Expand Up @@ -555,6 +566,7 @@ topologies
tradeoff
transactional
transferPort
trustLevel
trustingPeriod
tx
txBytes
Expand All @@ -578,6 +590,9 @@ updateClient
updateConsensusState
updatePort
updateable
upgradeClientState
upgradeCommitmentPrefix
upgradeKey
validRound
validValue
validateChannelIdentifier
Expand Down
Binary file modified spec.pdf
View file
Binary file not shown.
96 changes: 66 additions & 30 deletions spec/ics-002-client-semantics/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -256,6 +256,31 @@ Once misbehaviour is detected, clients SHOULD be frozen so that no future update
A permissioned entity such as a chain governance system or trusted multi-signature MAY be allowed
to intervene to unfreeze a frozen client & provide a new correct header.
#### Height
`Height` is an opaque data structure defined by a client type.
It must form a partially ordered set & provide operations for comparison.
```typescript
type Height
```

```typescript
enum Ord {
LT
EQ
GT
}
type compare = (h1: Height, h2: Height) => Ord
```

A height is either `LT` (less than), `EQ` (equal to), or `GT` (greater than) another height.

`>=`, `>`, `===`, `<`, `<=` are defined through the rest of this specification as aliases to `compare`.

There must also be a zero-element for a height type, referred to as `0`, which is less than all non-zero heights.

#### ClientState

`ClientState` is an opaque data structure defined by a client type.
Expand All @@ -279,7 +304,7 @@ Client types MUST define a method to fetch the current height (height of the mos
```typescript
type latestClientHeight = (
clientState: ClientState)
=> uint64
=> Height
```

#### CommitmentProof
Expand All @@ -300,10 +325,10 @@ Internal implementation details may differ (for example, a loopback client could
```typescript
type verifyClientConsensusState = (
clientState: ClientState,
height: uint64,
height: Height,
proof: CommitmentProof,
clientIdentifier: Identifier,
consensusStateHeight: uint64,
consensusStateHeight: Height,
consensusState: ConsensusState)
=> boolean
```
Expand All @@ -313,7 +338,7 @@ type verifyClientConsensusState = (
```typescript
type verifyConnectionState = (
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
connectionIdentifier: Identifier,
Expand All @@ -326,7 +351,7 @@ type verifyConnectionState = (
```typescript
type verifyChannelState = (
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
portIdentifier: Identifier,
Expand All @@ -340,7 +365,7 @@ type verifyChannelState = (
```typescript
type verifyPacketData = (
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
portIdentifier: Identifier,
Expand All @@ -355,7 +380,7 @@ type verifyPacketData = (
```typescript
type verifyPacketAcknowledgement = (
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
portIdentifier: Identifier,
Expand All @@ -370,7 +395,7 @@ type verifyPacketAcknowledgement = (
```typescript
type verifyPacketAcknowledgementAbsence = (
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
portIdentifier: Identifier,
Expand All @@ -384,7 +409,7 @@ type verifyPacketAcknowledgementAbsence = (
```typescript
type verifyNextSequenceRecv = (
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
portIdentifier: Identifier,
Expand All @@ -402,15 +427,15 @@ These query endpoints are assumed to be exposed over HTTP or an equivalent RPC A
`queryHeader` MUST be defined by the chain which is validated by a particular client, and should allow for retrieval of headers by height. This endpoint is assumed to be untrusted.

```typescript
type queryHeader = (height: uint64) => Header
type queryHeader = (height: Height) => Header
```

`queryChainConsensusState` MAY be defined by the chain which is validated by a particular client, to allow for the retrieval of the current consensus state which can be used to construct a new client.
When used in this fashion, the returned `ConsensusState` MUST be manually confirmed by the querying entity, since it is subjective. This endpoint is assumed to be untrusted. The precise nature of the
`ConsensusState` may vary per client type.

```typescript
type queryChainConsensusState = (height: uint64) => ConsensusState
type queryChainConsensusState = (height: Height) => ConsensusState
```

Note that retrieval of past consensus states by height (as opposed to just the current consensus state) is convenient but not required.
Expand All @@ -430,7 +455,7 @@ function queryClientState(identifier: Identifier): ClientState {
The `ClientState` type SHOULD expose its latest verified height (from which the consensus state can then be retrieved using `queryConsensusState` if desired).

```typescript
type latestHeight = (state: ClientState) => uint64
type latestHeight = (state: ClientState) => Height
```
Client types SHOULD define the following standardised query functions in order to allow relayers & other off-chain entities to interface with on-chain state in a standard API.
Expand All @@ -440,7 +465,7 @@ Client types SHOULD define the following standardised query functions in order t
```typescript
type queryConsensusState = (
identifier: Identifier,
height: uint64
height: Height,
) => ConsensusState
```
Expand All @@ -453,46 +478,46 @@ These functions may constitute external queries over RPC to a full node as well
```typescript
type queryAndProveClientConsensusState = (
clientIdentifier: Identifier,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
consensusStateHeight: uint64) => ConsensusState, Proof
consensusStateHeight: Height) => ConsensusState, Proof

type queryAndProveConnectionState = (
connectionIdentifier: Identifier,
height: uint64,
height: Height,
prefix: CommitmentPrefix) => ConnectionEnd, Proof

type queryAndProveChannelState = (
portIdentifier: Identifier,
channelIdentifier: Identifier,
height: uint64,
height: Height,
prefix: CommitmentPrefix) => ChannelEnd, Proof

type queryAndProvePacketData = (
portIdentifier: Identifier,
channelIdentifier: Identifier,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
sequence: uint64) => []byte, Proof

type queryAndProvePacketAcknowledgement = (
portIdentifier: Identifier,
channelIdentifier: Identifier,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
sequence: uint64) => []byte, Proof

type queryAndProvePacketAcknowledgementAbsence = (
portIdentifier: Identifier,
channelIdentifier: Identifier,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
sequence: uint64) => Proof

type queryAndProveNextSequenceRecv = (
portIdentifier: Identifier,
channelIdentifier: Identifier,
height: uint64,
height: Height,
prefix: CommitmentPrefix) => uint64, Proof
```
Expand Down Expand Up @@ -523,11 +548,11 @@ For clients of state machines with Merklized state trees, these functions can be
root stored in the `ClientState`, to verify presence or absence of particular key/value pairs in state at particular heights in accordance with [ICS 23](../ics-023-vector-commitments).
```typescript
type verifyMembership = (ClientState, uint64, CommitmentProof, Path, Value) => boolean
type verifyMembership = (ClientState, Height, CommitmentProof, Path, Value) => boolean
```
```typescript
type verifyNonMembership = (ClientState, uint64, CommitmentProof, Path) => boolean
type verifyNonMembership = (ClientState, Height, CommitmentProof, Path) => boolean
```
### Sub-protocols
Expand Down Expand Up @@ -637,6 +662,17 @@ The client-specific types are then defined as follows:
- `checkMisbehaviourAndUpdateState` checks for two headers with the same height & different commitment roots, then mutates the internal state

```typescript
type Height = uint64

function compare(h1: Height, h2: Height): Ord {
if h1 < h2
return LT
else if h1 === h2
return EQ
else
return GT
}

interface ClientState {
frozen: boolean
pastPublicKeys: Set<PublicKey>
Expand Down Expand Up @@ -696,7 +732,7 @@ function checkValidityAndUpdateState(

function verifyClientConsensusState(
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
clientIdentifier: Identifier,
Expand All @@ -708,7 +744,7 @@ function verifyClientConsensusState(

function verifyConnectionState(
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
connectionIdentifier: Identifier,
Expand All @@ -720,7 +756,7 @@ function verifyConnectionState(

function verifyChannelState(
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
portIdentifier: Identifier,
Expand All @@ -733,7 +769,7 @@ function verifyChannelState(

function verifyPacketData(
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
portIdentifier: Identifier,
Expand All @@ -747,7 +783,7 @@ function verifyPacketData(

function verifyPacketAcknowledgement(
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
portIdentifier: Identifier,
Expand All @@ -761,7 +797,7 @@ function verifyPacketAcknowledgement(

function verifyPacketAcknowledgementAbsence(
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
portIdentifier: Identifier,
Expand All @@ -774,7 +810,7 @@ function verifyPacketAcknowledgementAbsence(

function verifyNextSequenceRecv(
clientState: ClientState,
height: uint64,
height: Height,
prefix: CommitmentPrefix,
proof: CommitmentProof,
portIdentifier: Identifier,
Expand Down
Loading

0 comments on commit a06d603

Please sign in to comment.