GDK Documentation Improvement Proposal

[sonnyvesali]

I have spent the past 3 hours writing up a bloated, detailed, and useless GitHub issue draft that I ended up trashing about my troubles with GDK mobile integrations with flutter. But I thought it would be more helpful to suggest a contribution effort that I would like to spearhead with the help of the GDK developer team at Blockstream. Which is a complete revamp of the GDK platform integration documentation.

My Motivation:

I believe in Liquid as a future settlement layer for the future of Bitcoin Finance and the next generation of Bitcoin-based payment processors [the latter is the use-case I'm interested in pursuing] that can settle other assets besides Bitcoin alone. The groundwork for this is approachable, concise, & comprehensive documentation that covers most common base use cases. As it stands now with the current GDK documentation, it might as well be closed-source because it's inapproachable for outsiders like myself who aren't familiar with the codebase or its languages, or tools, to quickly integrate with Liquid and move on to the feature set that makes their wallet special. I don't think the GDK Documentation puts the Liquid network in a position to capitalize off of a community that will take the Liquid Ecosystem to the next level, even on the dimension of community maintained wallets alone.

My Experience with GDK & Blockstream support:

I have spent the past week trying to understand where to start to integrate GDK with a Liquid Bitcoin Wallet Product Idea I have, and I can't even get to the point where I have the library added, let alone use it. It has been a wild goose chase of teaching myself basic C, C++, the C++ build tools ecosystem and may more things just to get my head around where to start. I don't think it's a coincidence that the only wallet [to my knowledge] in the Liquid ecosystem is maintained by the Blockstream team. Even when I got into contact with Blockstream support through email TWICE to get in contact with the GDK team, my complaints got shelved, because I was told that the team had important deadlines to hit, and they'll get to it when they can. Truthfully this felt like an emotional gut punch. The feeling of being on an island with a foreign codebase and no developer support is one of the worst feelings a developer can have. This only worsens the mortality rate of new projects in the ecosystem. Vibrant developer ecosystems require a sizable upfront investment, and if we want to build something that's larger than Blockstream it's time to invest in our developer ecosystem with quality resources. This feels almost too obvious to mention, but documentation has asymmetrically large compounding effects for any developer ecosystem.

Next Steps:

I would like to connect with at least 1 person on the Blockstream GDK team who would have enough expertise on the GDK Codebase to help draw up some initial skeleton documentations, and the programming of pre-made templates that could be leveraged further to show the power of the GDK. We could start with the full documentation and comprehensive demos of the following platforms:

1. iOS [Swift]
2. Android [Kotlin]
3. Flutter [Dart]

I would need at least 1 person from the GDK team to help me with this starting out because I have no idea what the protocol for C/C++ integration is for these platforms is, and I couldn't do it on my own, even if I wanted to. I estimate the time commitment won't be too large but I believe the benefits of easily approachable documentation far exceed the upfront time investment, and I would be more than willing to do the supermajority of the work, I just need the knowledge.

Apologies for the diatribe, but I'm hoping this can be an inflection point for the Liquid and more generally the Blockstream developer ecosystem, Thanks.

[jgriffiths]

Hi @sonnyvesali

I hear you. Our support staff do not give out developer contact details due to privacy and security concerns, and this will not likely change. In order to reach the Green devs like myself, github is your best option unless you contact Blockstream and arrange a more formal (B2B) working relationship.

There are multiple systems integrated or integrating with Liquid; Green/gdk is not the only option although we hope in the near term it will be one of the easiest to work with. We devs will attempt to fix any bugs you may raise in a timely fashion, and can answer questions when we have time - but at this stage we are focused on following our development plan which will make integrating/using gdk easier.

In brief, gdk predates the PSBT/PSET standards and so uses bespoke JSON formats to pass data for tx construction and signing. These formats are updated often and so do not make a good basis for external integrations. We are adding support to accept and return PSBT/PSET so that integrators can use the established standards instead. Hopefully its clear that working on this is much more important than attempting to make the bespoke, changable formats widely used, since it pays back much more over time and allows us to interoperate with standardised tooling.

In regards to building gdk, we don't have resources to help users with this unless you find a bug/problem with the build process. The scripts and docker config in the repo build the releases we use; we expect you should be able to navigate building the library if you wish to hack on/integrate it into your own project.

In regards to flutter, no one in the dev group has any real experience with it. A brief google suggests that the flutter CFFI should be used to call the exposed gdk C API - this does not require any changes in gdk AFAICS. If you implement a wrapper for gdk we would be happy to review a PR to add it to the repo for others to use.

I hope the above helps clarify our current position somewhat.