We now have a stable set of specifications for the Status app that correspond to Status v1. In this post I’ll talk about what this means, how these specs can and will be used, and how we can incorporate them into our workflow.
Why have specs in the first place?
Many reasons:
- clarifies what a protocol requires and provides in terms of security guarantees and capabilities
- allows us to reason about the protocol at higher level, without getting bogged down by implementation details
- allows multiple interoperable implementations with different trade-offs
- allows us to have rigorous conversations about changes we make and the impact they have
- allows us to be bold when replacing components in a modular fashion, provided they follow the agreed contract
- acts as documentation for people new to the project or a piece of it
- acts as universal understanding of how things should work
- acts as raw material for security audits
- acts as an interface for the wider Ethereum/Crypto(graphy)/Academic community
- acts as raw material for technically accurate marketing
- acts as tools for thinking clearly about problems we are solving
And so on.
What does a spec being stable mean?
We use a life cycle loosely based on https://rfc.unprotocols.org/spec:2/COSS/
A stable spec means it is used by some app in production. Changes to these are cosmetic, errata and clarifications. It acts as a contract between editors, implementers and end users.
A draft spec is something that is still not quite live, but is in the process of being standardized. It acts as a contract between editors and implementers.
Then you have raw specs which are very speculative, as well as deprecated and retired specs.
Currently the following specs are marked as stable:
- 1/CLIENT 1/CLIENT - Status Specification
- 2/ACCOUNT 2/ACCOUNT - Status Specification
- 3/WHISPER-USAGE 3/WHISPER-USAGE - Status Specification
- 4/WHISPER-MAILSERVER 4/WHISPER-MAILSERVER - Status Specification
- 5/SECURE-TRANSPORT 5/SECURE-TRANSPORT - Status Specification
- 6/PAYLOADS 6/PAYLOADS - Status Specification
- 8/EIPS 8/EIPS - Status Specification
7/GROUP-CHAT https://specs.status.im/spec/7 is still marked as Draft since it isn’t live in the app yet. It is expected to become stable without any changes soon.
The specs are wrong / how do I make changes?
Thank you! Please submit an issue here: Issues · status-im/specs · GitHub. Even better, submit a pull request. If you need help, go to protocol.
What’s missing?
Quite a lot actually! The specs should accurately reflect the important interface pieces of the Status app(s) as well as security guarantees. Aside from misc clarifications and errata to the stable specs above, there are several pieces that are not accurately documented. Here are a few things that come to mind:
- How we use IPFS gateway for stickers (impacts availability, censorship and privacy guarantees)
- How notifications work since changes last few months (differences across platforms and so on)
- How we interface with the Ethereum blockchain, i.e. use Infura and Cloudflare for transactions history etc (documenting this clearly also acts as requirements for research efforts such as Beam Sync)
- How Status clients use Keycard
- Other 3rd party APIs used for core functionality that impacts things like availability/censorship and privacy
- Dapp browser API usage
- As well as things on the horizon: mentions, images, etc
And probably a lot more. Now, a lot of this are things that the Core team are experts at. Things move fast, and knowledge lives at the edges. While everyone in the protocol team channel is happy to help out with how to be precise in spec language etc, ultimately this knowledge comes from you, the domain expert at the specific thing you are working on. While there is definitely an element of prioritization between urgent features and documentation, in an ideal world, Core would own these specs.
Note that this is in addition to more greenfield research efforts, which are happening under https://vac.dev/ and https://specs.vac.dev/. This is a different topic.
Now what?
-
If you know about something that isn’t specified but should be please create an issue and/or issue a PR for a raw/draft spec.
-
If you need help, go to protocol or ping people in specs repo for issues or PRs. I and many others (Corey, Dean et al) are happy to pair on this stuff!
As well as…
Using Core dev calls
Lately it appears the Core Dev calls and their original purpose have drifted and fizzled out a bit. When we started them (Status.app), we weren’t in the state of specs and protocol sophistication we are at now. Instead, we discussed Swarms and groups of people. I believe we are now at a much better position to make use of them to talk about specific protocol proposals and make decisions as a group of core contributors. This will only become more relevant as projects such as Nimbus become more tightly integrated with the Status app. This is similar to how the EIP process works in Ethereum. It would also act as a cadence and reminder to keep caring for our protocol and the specs that we put out.
Let me know what your thoughts are the above and how we can best move forward on this and make our specs even better, as well as ensure that we specify things appropriately.