Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Figure out best syntactical format for specifications and write meta-protocol #67

Closed
cwgoes opened this issue Apr 2, 2019 · 5 comments
Closed

Figure out best syntactical format for specifications and write meta-protocol #67

cwgoes opened this issue Apr 2, 2019 · 5 comments
Assignees
@milosevic @cwgoes
Labels
meta Issues or proposals about the ICS process.

Comments

@cwgoes
Copy link
Contributor

cwgoes commented Apr 2, 2019 •
edited

Per suggestion from @milosevic.

Also includes English guidelines ("natural compiler"):

  • Define terms before usage
  • Move motivation out of "Specification"
  • Add top-level architecture document to define basic set of terms

Other notes

  • Split handleDatagram into sub-functions (likewise for other functions)
  • Keep pseudcode snippets short
  • Try CoffeeScript/Golang snippets instead of Markdown
  • Define pseudocode keywords in meta-spec
  • Include proto3 encoding file
  • Include state machine descriptions
  • Express IBC as protocol between modules on blockchains
  • First include definitions of communications channels
  • "Requirements" section can only use previously defined terms
  • Subprotocol definitions include concrete message types, processing behavior

Clear technical reports

  • Paxos original paper
  • TCP specification

Other ideas

  • Executable spec for protocol conformance
  • Standard / reference testsuite + fuzzer

Try this with ICS 2 / 3.
@cwgoes cwgoes added the meta Issues or proposals about the ICS process. label Apr 2, 2019
@cwgoes cwgoes added this to the Minimum Viable Insecure IBC milestone Apr 2, 2019
@cwgoes cwgoes mentioned this issue Apr 2, 2019
Closed
@cwgoes
Copy link
Contributor Author

cwgoes commented Apr 3, 2019

Example layout:

  1. INTRODUCTION
    1.1. Motivation
    1.2. Scope
    1.3. About this Document
    1.4. Interfaces
    1.5. Operation

  2. PHILOSOPHY
    2.1. Elements of the Interconected Blockchain System
    2.2. Model of Operation
    2.4. Interfaces
    2.5. Relation to Other Protocols/ Modules/ Apps
    2.6. Connection Establishment and Clearing
    2.8. Data Communication
    2.9. Precedence and Security
    2.10. Robustness Principle

  3. FUNCTIONAL SPECIFICATION
    3.1. Header Format
    3.4. Establishing a connection
    3.5. Closing a Connection
    3.7. Data Communication
    3.8. Interfaces
    3.9. Event Processing

@mossid
Copy link

mossid commented Apr 3, 2019 •
edited

Some RFCs:

Pseudocodes:

@cwgoes
Copy link
Contributor Author

cwgoes commented Apr 9, 2019

#68 defines a bunch of terms.

@cwgoes
Copy link
Contributor Author

cwgoes commented Apr 15, 2019

#70 is a start at a high-level protocol explanation a la the TCP RFC.

@cwgoes cwgoes removed this from the Pre-Implementation Requirements milestone May 14, 2019
@cwgoes
Copy link
Contributor Author

cwgoes commented Jun 9, 2019

We're now using RFC 2119 and have a standard set of sections in each specification.

Requests for any meta-level changes are welcome in followup issues.

@cwgoes cwgoes closed this as completed Jun 9, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@milosevic milosevic

@cwgoes cwgoes

Labels
meta Issues or proposals about the ICS process.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@milosevic @mossid @cwgoes