On protocol & implementation specifications about ibc HOT 12 CLOSED

we should distinguish between implementation spec and state-machine-expected-behaviour specs - from my experience, implementation evolves naturally as the code matures and we should not require any more process than we currently have - although we should maintain an implementation spec as well. When developing the code, so long as the expected behaviour stays the same (or is corrected to expected behaviour) as the existing implementation (or approved ICS) these implementations should not require going through the ICS proposal process

Agreed. Implementation specs are out-of-scope of the ICS process & this repository - those are left to the implementers (e.g. Cosmos SDK) to choose and execute upon.

from ibc.

We need a "concrete spec"s which are the implementations of abstract specs, for example, ICS23 Accumulator is an abstract spec where Merkle tree is a concrete spec which satisfies ICS23, ICS2 Consensus Verification is an abstract spec where Tendermint Lightclient is a concrete spec which satisfies ICS2.

Separated from the actual implementations, it seems that storing concrete specs under the abstract specs looks organized:

ICS/
- ICS2: Consensus Verification
  - ICS2-1: Tendermint Lightclient(link to tendermint/lite, etc. under "implementations")
  - ICS2-2: Finality Pegzone(link to finality pegzone implementations)
- ICS23: Accumulator
  - ICS23-1: Merkle tree(link to iavl, merkle patricia, etc. under "implementations")
  - ICS23-2: Another Accumulator(link to their implementations...)

clearer then

ICS/
- ICS2: Consensus Verification
- ICS7: Tendermint Lightclient
- ICS22: Finality Pegzone
- ICS23: Accumulator
- ICS??: Merkle Tree

which makes the relationship less noticeable

The distinction between concrete specs and implementations specs are little blurry, and I think that the implementation specs should live with their code, but the concrete specs will be defined as ICSs any way, better structure them in some sort of hierarchical way

from ibc.

We could, but in the future when there are many implementations of a particular protocol (IBC connection version negotiation, for example) I think that might get messy - better to leave the implementation specifications in their own repositories (e.g. the Cosmos SDK repo) and link to them in the protocol spec (there is a sub-section for implementations in ICS 1).

from ibc.

from slack

we should distinguish between implementation spec and state-machine-expected-behaviour specs - from my experience, implementation evolves naturally as the code matures and we should not require any more process than we currently have - although we should maintain an implementation spec as well. When developing the code, so long as the expected behaviour stays the same (or is corrected to expected behaviour) as the existing implementation (or approved ICS) these implementations should not require going through the ICS proposal process

from ibc.

I' also all in favour of not including implementation specs in this repo. If anything we could recommend implementers to include a design document / implementation spec in their repo.

from ibc.

I covered some of this in ICS 1 under "What is an ICS?".

from ibc.

I think we can store one protocol specification and one (possibly multiple) implementation specification(s) in a ics-XXX-*/ together. For example, ics-003-connection-semantics/{protocol.md, implementation-sdk.md, implementation-rust.md, etc.}.

from ibc.

Yes, I like the focus on protocol specs

from ibc.

Also see #47 for several historical protocol specifications for inspiration.

from ibc.

The distinction between concrete specs and implementations specs are little blurry, and I think that the implementation specs should live with their code, but the concrete specs will be defined as ICSs any way, better structure them in some sort of hierarchical way

This is an excellent point - maybe we should call them "interface" specifications and "concrete" specifications (both are protocols, not implementations, since we're not including actual code)?

I agree with the hierarchical folder structure. We should look at the current ICS set and figure out which will be "concrete" specs, as you've started to do, then rename them accordingly.

from ibc.

Note from @jaekwon - call it "ICS 2: Tendermint" instead of "ICS 2a".

Consider moving the implementation-specs to Tendermint later.

But if the goal is to have this repo specify exact IBC we need it here.

from ibc.

This has been sufficiently clarified, I think.

from ibc.