News from the Fadroma Frontlines. Issue 1

Cover Image for News from the Fadroma Frontlines. Issue 1

Welcome to the first issue of the Fadroma news bulletin!

Honestly, we should’ve started publishing this stuff way earlier.

Between CosmWasm, Rust, Node.js, TypeScript, Docker — and all the other bits and pieces that we’re knitting together to establish the new DevEx baseline for the CosmWasm community — there’s plenty of funny shenanigans going on.

We hope we get around to telling some of those stories before they fade from living memory. But for now, let’s start with a quick overview of what’s been cooking these past few weeks.

Bulldozers bulldozin’.
Happily bulldozing through the desert of the real. Where else

Shelving legacy versions

Let’s get the chores out of the way first: in our repository, a bunch of branches of our repo, with confusing names (like v3 or v99) have now gained a legacy/ prefix.

Note: having slashes (/) in the names of Git branches — or tags — is not a particularly great idea. Don’t try this at home — prefer a more path-friendly delimiter such as underscore (_).

Why were those branches there in the first place? Fadroma’s project structure, went through a few sizable metamorphoses — until we eventually settled down on the current shape of our polyglot monorepo. (Some of the legacy packages such as @fadroma/client-* and @fadroma/ops-* are still on NPM, even. They will also go away soon.)

We even tried a Calendar Versioning scheme at one point (think 23.09.x, like NixOS or Ubuntu). Turns out Cargo and NPM don’t have good support for that, at all. For a while, we even entertained the the crazy idea of seamlessly switching from CalVer to SemVer by making our first stable release version 23.0.0 (as in 2023, get it?). Thankfully, all that confusion is in the past. And good riddance! Let’s leave the crazy version number backflips to the browsers and operating systems.

We’re committed to making the most of Semantic Versioning. This means not being afraid to increment the major version when there are breaking changes to API or to behavior. Indeed, our @fadroma/scrt module for supporting Secret Network has already reached version 10.x.x, and we find nothing wrong with that 🙂

In the future, we plan to be even more strict about major versions and breaking changes. Of course, this doesn’t mean incrementing major versions every other week; it means avoiding breaking changes unless absolutely necessary — and staying within the boundaries of the existing API as much as possible.

Version zero forever?

We consider staying on version 0.x forever (like a lot of crucial tooling and foundational libraries unfortunately do) to be somewhat irresponsible: 0.x versioning means downstream developers wouldn’t know when they need to modify their code to accommodate an upgraded dependency. This is a source of uncertainty, confusion and lack of maintenance.

Trouble is, people like round numbers, and can be quite accustomed to version numbers as part of a software product’s branding. So we just weren’t sure when to release 1.0.0, especially considering 1.0.1 would soon follow… Thankfully, Secret Network Proposal #183 provided us with funding to publish a stable version, and we’ve been officially on the radar ever since.

In the meantime, we did publish nearly a hundred 1.0.0-rc.x versions as we stabilized our single-command onboarding through npx. (Surprise surprise, NPM doesn’t have great support for the -rc. suffixes — even though they’re part of the official Semantic Versioning spec.)

Besides, testing an onboarding workflow that goes through an external service such as NPM isn’t a great experience — as we kept finding out all the way up to the following news item.

Someone who is doing versioning right

OKP4 brings Prolog-based Governance as a Service to the world of CosmWasm. It’s great to see their smart contracts starting from v1.0.0 at the outset — and they maintain documentation for all versions of the API. Way to go, folks!

Disclaimer: we lent them a hand with improving the usability of the docs 🙂

Our pull request replaced the excessively verbose and difficult to navigate output of an old Adobe tool, “jsonschema2md”, with concise one-page guides to the API of each contract. This is what we used to achieve that: https://github.com/hackbg/fadroma/blob/master/schema/schema.mjs

The will to do things correctly and completely goes a long way!

Caret versions can be a blessing — or a curse

Those were a major source of silent breakage when initializing Fadroma projects through our npx @hackbg/fadroma@latest create entrypoint. We finally identified and resolved it — hopefully putting issues like this one in the past.

If, like us, you’re a heavy user of multi-package workspaces, careful there: even if you boast an extensive test suite, it probably doesn’t cover how NPM resolves the dependencies between your packages, does it?

So, if a broken a patch version of one of your libs ever gets through all the way to the NPM package repository, the caret ranges (^x.y.z) that package.json helpfully supports may propagate the error back to older versions of other packages that depend on it. Oops, and ouch.

In the future, we hope to speed up and automating our package publishing procedures — which, surprise surprise, become more of a bottleneck the more packages you publish.

And yet more fun with NPM, Node and TypeScript…

We miss CommonJS dearly — but ESM is the future of JS, and we’re helping to bring it about. That can’t happen fast enough — unless we take up maintaining some forks.

So far, the case of RPC bindings proved trickiest. These are automatically generated by protobuf.js, and both @cosmjs/stargate and secretjs contain them, in order to be able to talk to the chain nodes.

Protobuf.js is written in CommonJS. Node.js and TypeScript each address the problem of loading CommonJS code from ESM code independently. And, of course, their individual backwards compatibility solutions have proven to be a little… wait for it… mutually incompatible.

Let’s just say we’re not surprised in the slightest. In our next bulletin, we’ll give you more details on what that fuss was all about — and what we did to resolve it.

Stay tuned, follow us on Medium, and give our tooling a try:

Until next time!


Hack.bg Skunkworks and Deep Dives
About the author:

Hack.bg Skunkworks and Deep Dives


More Stories

Cover Image for Real-World Assets and the Future of DeFi

Real-World Assets and the Future of DeFi

Real-world assets are blockchain-based digital tokens that represent physical and traditional financial assets. The first wave of decentralized finance (DeFi) […]

Read more
Cover Image for Navigating Upgradable Solidity Smart Contracts: A Practical Guide

Navigating Upgradable Solidity Smart Contracts: A Practical Guide

In the ever-evolving landscape of blockchain technology, the concept of upgradeable smart contracts has emerged as a crucial tool for […]

Read more

Have a project in mind?

We have the expertise! Drop us a line and lets talk!