Flow SDK Guidelines

[JeffreyDoyle]

In order to provide SDK developers with expectations for what functionality a Flow SDKs should provide, we must create a language agnostic SDK spec. This specification should outline what functionality a Flow SDK should provide. The specification should not specify how such functionality must be achieved.

The outcome should be a specification for what functionality a Flow SDK must provide. Depending on which language implements the SDK spec, it should be flexible enough such that the varying features of such language can be utilized. The aim being that each Flow SDK can feel friendly and intuitive to users of the SDK's language, yet function with feature parity to Flow SDKs of other languages.

The Flow SDK spec will standardize a new "layer" of abstraction between the Flow protocol, Access API, Flow SDK and a developers application.

Layer 0: Flow Protocol Layer 1: Access API Layer 2: Flow SDK Spec <- New! Introduced by this issue. Layer 3: A Flow SDK implementation. Layer 4: A developers application.

Further Questions

• What are the set of features each SDK should provide?
• How can we standardize the ways that SDKs enable developers to engage with functionality exposed by the Access API?

Expected Outcomes

• [ ] A specification exists for the functionality a Flow SDK should implement.

[10thfloor]

@JeffreyDoyle Could you point to any well-implemented specs as prior art? This could help with requirements here.

[devbugging]

Context & Purpose

The SDK Guidelines will provide us with a framework to build SDKs that will be:

• consistent (UX, terminology...)
• accessible (documentation, specifications...)
• reliable (API changes, bugfixes...)
• community-driven (clear goals and definition, make it easy to build SDKs)

Language agnostic rules that will allow developers to build a library that will comply with a "standard".

Process:

• define guidelines (conversation, draft, feedback, publish)
• update existing SDKs (Go SDK, JavaScript SDK) to meet guidelines (standard)
• help other teams and individuals update their SDKs to match

Building

• Versioning format https://semver.org/
• Terminology and domain language
  • domain language definitions - SDK repo
  • ubiquitous language https://martinfowler.com/bliki/UbiquitousLanguage.html
  • https://en.wikipedia.org/wiki/Colloquialism
• Definition of the SDK functionality and user stories, user stories will guide the developer during the implementation and provide a common testing suite
• Network interactions and API access points
• Code quality tools / formats
• Define the release schedule if possible
• SDKs guidelines should outline the suggested architecture where it should be visible that:
  • Cryptography operation shouldn't be implemented as part of SDK but instead should define an interface that is consumed by the SDKs to do all crypto operations, reasons behind this are security considerations, adding unnecessary complexity. However, we should provide a feasible default to not add the implementation complexity for the developer using the SDK, but doing so by using the pattern defined above.
  • Network communication should also be decoupled from the SDK and just provide an interface for usage, reasoning behind this is the changes in protocols shouldn't affect the SDK itself but only the network layer. On top of that should be another layer implementing specific API type (rest, grpc, rpc...) and exposing only exposing an interface, reason behind this is to allow mocking (hot-swap mock during the testing) and to potentially support different communication mechanisms for the SDKs while sufficiently isolating the other parts.
  • TBD - more of the SDK architecture should be defined as guideline for implementation but of course not requirement

Documentation

• docs from all the SDKs complying with the standards will be built and published on Flow documentation alongside developer info, logo etc to incentivize compliance
• write docs around the user stories, user stories will be predefined as part of the structure of the doc
• provide formats and structure for the docs. Potentially have a structure for docs they can clone - or structure of examples (query_blockchain.c, createAccount(c|js|py...))
• provide high documentation coverage
• we will be able to have single unified documentation with multiple programming language examples
• version the documentation and provide breaking changes as part of the documentation alongside the migration guide

Testing

• Providing test fixtures for the SDKs functionality
• Testability of the SDK within the implementation (mocks)

Maintaining

• Breaking changes and changelog https://keepachangelog.com/en/1.0.0/
  • Mindful of backward compatibility - standard of how much time for deprecation
    • transition documentation
  • The PRs introducing a breaking change should reference an existing changelog as included in the documentation
  • Live by the moto: Don't break my things
  • communicate the changes in time
    • how it breaks
    • changes needed
    • what you need to do so it doesn't break
• SDK guidelines could have a repository where we track all the feature requests, announce upcoming changes SDKs will have to implement and act as a single source of truth for domain language and other definitions
• Introduce SDK ratings as an incentive to maintain all community-driven SDKs
  • ratings will consist of categories and the total score will be the sum of all
  • SDKs shouldn't be forced to comply with all the standards and will be listed anyway, but we should encourage compliance and help developers achieve it
  • Example of this https://redis.io/clients
• One Flow core team member acts as the champion for each SDK

The next steps in the proposed process would be to move this to a repository centered around (SDK) guidelines. That would become a home and source of truth for providing guidelines, test data, documentation structures, ubiquitous language, track feature requests. This issue is a pre-draft, a source of information to include in the draft published in the repo after. We should make sure that we cover all important topics we want to define in this pre-draft version.

[bluesign]

First of all, it is a great write-up @sideninja, covers almost all points pretty well.

I have only one question and comment about testing.

The first critical question is I read before "Access Node REST API in development" in a GitHub issue (https://github.com/onflow/flow/issues/535)

• Will this be some public endpoint?
• If so, any estimate on the release date?
• Also on a side note, maybe some information communicated to the community about future developments like this can be nice (not everyone is reading every notification like me)

Testing

• I think here is better to provide some mocking endpoint and specs of tests. So keeping eye on what SDKs are implemented, what is missing with CI, or any breaking changes implemented, etc can be good.
• Most problems here are about making wrong requests, or missing requests (not implemented)

Now all is good and solid, but we have a problem in general about SDK development, which this guideline not covers.

As far as I know current status:

• js and go sdk's are official and not much problem there.
• python and dart seem like managed by flow employees. (I am not sure if they are committed to go with this spec or somehow flow will somehow make them official)

But rest is very problematic. The main attitude on SDK development is currently people sharing what they have done for their own use and covers their cases. Either they don't have time, or they have moved on to something else.

This guideline requires serious maintainer(s), I think this should be organized somehow by you without leaving to the community. I think maybe you can kickstart SDKs, then give them to some community maintainer to maintain (for future improvements, handling breaking changes, etc). If he/she is not keeping up find a new maintainer.

I don't know how much time you spent for Go or js SDK, but developing an SDK with these specs is not an easy task, and to be honest, I don't think it will succeed. I don't know the exact ratio, but I think there is a big N for: (number of SDK users in Language X) / (for number of volunteer SDK developers in Language X)

[devbugging]

Thank you for providing feedback on this.

The first critical question is I read before "Access Node REST API in development" in a GitHub issue (#535)

We are currently developing a REST API that will become the preferred way to communicate with access nodes. I understand we have communication problems about changes like that, and the guidelines repo will help with part of that by becoming one place to communicate things around the SDK changes which would flag similar issues or upcoming changes. Developer communications are constantly improving and although we are aware of issues it will take us some time to improve, but I understand the concerns.

Testing

• I think here is better to provide some mocking endpoint and specs of tests. So keeping eye on what SDKs are implemented, what is missing with CI, or any breaking changes implemented, etc can be good.

I was thinking of providing some specs but also support with mock data, can you elaborate more on your idea of providing mocking endpoints? I'm not quite sure I understand.

• Most problems here are about making wrong requests, or missing requests (not implemented)

Now all is good and solid, but we have a problem in general about SDK development, which this guideline not covers.

As far as I know current status:

• js and go sdk's are official and not much problem there.
• python and dart seem like managed by flow employees. (I am not sure if they are committed to go with this spec or somehow flow will somehow make them official)

But rest is very problematic. The main attitude on SDK development is currently people sharing what they have done for their own use and covers their cases. Either they don't have time, or they have moved on to something else.

This guideline requires serious maintainer(s), I think this should be organized somehow by you without leaving to the community. I think maybe you can kickstart SDKs, then give them to some community maintainer to maintain (for future improvements, handling breaking changes, etc). If he/she is not keeping up find a new maintainer.

I don't know how much time you spent for Go or js SDK, but developing an SDK with these specs is not an easy task, and to be honest, I don't think it will succeed. I don't know the exact ratio, but I think there is a big N for: (number of SDK users in Language X) / (for number of volunteer SDK developers in Language X)

I agree and this is the biggest problem we need to solve. We prefer community first development when it comes to SDKs. We are aware this will be a huge challenge but you can only solve one problem at a time and the first problem to get there is to write guidelines. We will also try to establish an internal SDK advocate who will help and keep in touch with the SDKs maintainers. Do you have any ideas on how we could better incentivize the community to develop the SDKs? We actually discussed idea of bootstrapping but we are on the fence if it is good or not, since it might feel like it is not a community effort but our command and rules how to do things which we don't like.

[bluesign]

REST API will be very good solution, and speed up development of SDKs I believe.

For testing part: I was thinking like let's say I am developing a python SDK, instead of mocking everything myself. In guidelines there will be some spec (I think it is what you called user stories)

I will have a test.py ( which I will define in a spec file in repo)

• (SINGLE_SIGNER) Send Transaction signed by 0x01 with private key XXXXX

then I will point my endpoint to https://sdk-test.onflow.org. (I can add some HTTP-HEADER like Test-Id: SINGLE_SIGNER)

• while developing I can run test.py, and see if it fails. and fix accordingly
• on your end, you can run test.py (even automate with CI to run test.py on some interval), you can check if SDK correctly implements SINGLE_SIGNER, log last success etc. (if developers adds something and not changes tests, or somehow some breaking change is breaking some SDK (like last time payload and envelope signature double sign issue) )

Also this service can have some test utility functions

• canonical envelope RLP check, you can send envelope, and your canonical result, it can check if it matches etc
• signature check, with some fixed private KEY, if signature is implemented correctly

As this service will have always up to date spec, it is better to do testing over spec on your side.

So this tests will be step by step development guide. ( even can be some multiple step ones, sendTransaction, getResult, sendResult to verify etc)

SDK advocate is a very good idea, but incentivize part is very hard for me to tell, I am incentivized only by the good feeling I am getting back, but some SDK developers can be incentivized by some kind of résumé building, it is hard to predict. But the main problem is number of developers are very low :(

Main problem with maintainers are use-as-is mentality, I tried to contribute to 3 SDKs so far, only Dart implemented by bug report or pull request :)

Anyway I will try to bootstrap some for sure, fingers crossed for REST endpoint :)

[devbugging]

For testing part: I was thinking like let's say I am developing a python SDK, instead of mocking everything myself. In guidelines there will be some spec (I think it is what you called user stories)

Exactly, the user stories will guide you through development and give you an easy way to test.

then I will point my endpoint to https://sdk-test.onflow.org. (I can add some HTTP-HEADER like Test-Id: SINGLE_SIGNER)

Ohh, ok I see. We were thinking of having tests sets you would use to mock the response. Having a good architecture of the SDK it would allow you to isolate network responses and be possible to swap between mock and network implementation easily, but then again I really like this idea of not actually having test data but test API. It will ease the development, it would provide us insight into SDKs that are passing the tests. Thank you so much for this idea, I think this will be the way to go.

SDK advocate is a very good idea, but incentivize part is very hard for me to tell, I am incentivized only by the good feeling I am getting back, but some SDK developers can be incentivized by some kind of résumé building, it is hard to predict. But the main problem is number of developers are very low :(

If only the world would be full of people like you :) but yes the challenge is real.

REST endpoints are coming :)

[bjartek]

This is a good example of a well written spec and tck i think https://github.com/reactive-streams/reactive-streams-jvm/blob/v1.0.3/README.md#specification

[devbugging]

NEW: Feature Domains

SDK guidelines could define feature domains. Feature domain would be a group of actions that are related and their definition would live in the SDK guidelines repo. Each language-specific implementation of the SDK could then implement an arbitrary set of feature domains and be advertised as such thus removing the idea of one SDK per language to rule them all. For example, some feature sets would make more sense to be reused alongside backend services while others could be reused more on the frontend.

The feature set we would initially define would cover the current SDK functionality but this concept could be more scalable going forward as more feature sets occur (things like wallet discovery,...). The benefit of having more smaller defined feature sets could also be beneficial for making SDKs as small as possible which means easier to maintain and easier to create. Let's repeat an old mantra: Do one thing and do it well.

[bluesign]

@sideninja that's nice, composability for SDKs :)