2018-04-05 Engineering Meeting

Date/Time: 2018-04-05 @ 13:00 UTC / 09:00 EDT / 21:00 HKT
Length: 45 minutes
Meeting link: https://zoom.us/j/416493133


Please reply to this forum post with items you would like included on the agenda.

Each item should include:

Item name
Background information: Links to github issues, forum posts, etc with background information on the item
Desired outcome: what decision or deliverable would you like from the discussion of this topic at the meeting?

We’ll save ~10 minutes or so for community questions or comments at the end of the meeting.


Background information

In order to implement libraries for new languages (e.g. blockstack.ts or blockstack.go) it would really help to have clear specifications of the different parts (auth tokens, profiles, zone files, key derivation, storage, etc), maybe also architecture diagrams.

Currently the specification is in an unclear state, mainly defined by code spread around the project. Also due to JavaScript’s lack of types it’s in many cases unclear whether a type is needed or not.

This is a really big and important topic, since it defines how all the different parts of the ecosystem are supposed to work together. This is certainly not a topic to discuss and resolve in a week or so, I just want to push this topic forward before it gets lost between other things.

It might make sense to split these things into smaller action items / decisions.

Previous work

Desired outcome

  • How should the specification look like?
  • Which parts need specification?
  • Who is responsible for which part?
  • When should which part be completely specified?

Previously my take on this

I think it make sense to put this into an own repository (e.g. blockstack-specifications). This way we could add it as sub-module into other projects (to derive interfaces from it, etc). Developers also would have a clear location to go when searching for specifications.

This repository should define the parts of the ecosystem separately (own specifications for auth, profiles, etc), so libraries that don’t need a part can only take the ones needed. Libraries then would state things like

This library implements Blockstack Authentication in v1.2.3 and Blockstack Profiles in v4.5.6.

I think using JSON schema makes sense here. The current parts mostly exchange data using JSON objects, for what JSON schema is the quasi-standard to specify properties. It’s supported by many other languages and is also used for specifying profiles.

Changing these specifications should have a clear formal way of proposing new things, as these may affect multiple other parts. It should be clear what’s part of the specification and what’s not, and probably most important what’s part of which version.

Just realized that the meeting is tomorrow instead of the usual Thursday. Won’t be able to attend since I’m not at home the whole day.
Feel free to discuss this anyway :slight_smile:

Thanks for catching that. That was a time zone related date typo on my part probably. Fixed it. Still Thursday!

1 Like

Blockers on Blockstack Browser Release

There’s two issues with the coreless browser release:

  1. If you have existing redux state, the API URLs won’t update right now, because the new release only changes defaults.

  2. The regtest mode activation in the browser is a little wonky. @Jude and I both experienced some issues trying it out yesterday, but I didn’t spend enough time to fully diagnose it.

I have a commit that fixes (1), by bumping the state version, and during the UPDATE, checking if the version is rolling past v12, and if so, attempts to rewrite the API URLs. I will push that to the feature branch feature/enable-reg-webapp (the branch for the core-less browser build) following the morning meetings. However, I think both of these issues are caused by hacky uses of redux state, so I’d appreciate it if someone more well versed in diagnosing redux problems can look at that code.

As a follow-up for this meeting, I think I got this a bit sorted in my head.

The reason I need a specification for blockstack.ts is to stay compatible with the rest of the deployed ecosystem. To do this I started using integration tests that query real endpoints and look whether the library knows what’s returned from there.
I think this way we’d even be able to test compatibility (as discussed in the meeting) without a specification.

Though in my opinion the end goal should stay to have a single place to go to when implementing a new library (which shouldn’t be somewhere in a library).

The steps to take would be:

  1. Bring every library at a point where all data that entry/leave the service is specified as an interface
    (Make sure that these interfaces get updated when the code change)
  2. Gather these interfaces in a single place (for easy discovery)
  3. Gather these interfaces in a single repository (for even easier discovery)
  4. Add documentation and informal descriptions to these

Also for versioning: I think that we should try to specify things and then look how frequently these get updated (and we then still can decide on rolling releases vs feature-driven releases).

Regardless I’d happy to have a specification rather sooner than later, because the more projects that (re)use format assumptions made in the code, the harder it gets to clear this up afterwards. The specification surely can be labeled as draft or unstable, but if there’s a single specification, people know where to look and what to do :slight_smile:

2018-04-05 Engineering Meeting Notes


Yannis De Cleene
Ben Longstaff
Jack Zampolin
Aaron Blankstein
Shankar Ganesh
Jude Nelson
Jeff Domke
Larry Salibra
Chase Wackerfuss
Mario Ceballos

Versioning And Specs

  • Larry:
    • We should separate developer toolkits from the user-facing product
    • Iterate quickly on the user-facing product
    • Developer toolkits go more life-cycle focused, where you have a year-long period of development interfaces that change often
  • The trade-off is that we’re not necessarily at a point where everything is very stable, and we know what a platform “is”.
  • Breaking changes only quarterly — non-breaking changes allowed in more frequent releases
  • Documentation and specification:
    • interfaces of blockstack.js
    • interfaces between blockstack.js and core
  • Action item: binding json schemas and documentation for core.blockstack (and similar deployments)
  • Specification ask:
    • Single location for specs?
    • Specs update if code updates
    • Use json schemas for interfaces
  • Tie specs onto unit tests — we need a framework for enforcing specs
    • Next sprint: have someone assigned to working on this
  • Release schedule is also important (somewhat orthogonal to the specs)


  • Progressive on-boarding?
    • If we’re committing to browser.blockstack.org — then what options do we really have for storing information?
    • Where do we store information if we want the transition to be seamless?
  • Redux state cleanup
    • Can we make this a concrete goal for next sprint?
  • Core-less Browser Build
    • Do we want this to block on the redux state cleanup?