(Re)Intro to SubbitMan

Posted on 2025-07-01

This blog post has several aims:

  • Follow up on the original intro blog post by pointing to actual code.
  • Orientate a keen dev on how to get started working with Subbit.xyz via the example application, NowDB.
  • A retrospec drawing out some lessons learned from the meandering path it has been to get here.

We also unpack how the output addresses in spirit, if not verbatim, the objectives of Catalyst milestone 3.

The reintroduction

The previous post talked through the principal aspects of wrapping a service (eg web API) in order to deliver it via a pay-as-you-go (payg) model. It steps through this from no payg, to trustful payg, to trustless payg.

Repos

We can now link to explicit repos:

NowDB

NowDB is simple, somewhat pointless, app. The NowDB server can tell the time, and provides access to clients to put in, and get from, content in it’s key-value store db.

It can be run with or without payg, and can be run with different payg account managers.

AccMan

AccMan is simple account manager. It functions a little like a basic auth server. Rather than responding with a boolean when presented with a credential, it responds with a number representing the associated remaining available total balance (aka tot). AccMan has a second endpoint allowing this value to be modified (aka mod).

AccMan can be used as an account manager for NowDB. A consumer first sets up an account, which we presume involves sending funds to the provider. The precise mechanism here is out-of-band. The consumer then includes their AccMan credential in their requests.

SubbitMan

SubbitMan is an almost drop-in replacement for AccMan. The exact nuances in the divergence is explained in the SubbitMan repo. SubbitMan is trustless, whereas AccMan is trustful. Rather than sending funds directly to the provider, the consumer sets up a subbit using Subbit.xyz. This underwrites the provider’s service provision. The consumer does not have to trust the provider with their funds upfront, and the provider is not at risk of the consumer not paying.

Getting oriented

There a number of components here. Where to start? We recommend starting with reading the original blog post.

Next, run the NowDB server without payg, and run queries with the NowDB client. Instructions for both are in the READMEs for the respective packages. Once oriented around the API, it’s time to add payg.

From the AccMan repo, run AccMan and use the just commands to create accounts, and mod the tot. The repo’s README has instructions on setup and usage.

With AccMan running, it’s now possible to run NowDB with AccMan payg. Ensure that both the server and client of NowDB are in a correct payg mode, and that the NowDB client has a valid AccMan credential.

“… A correct payg mode” because the client can be run with or without checking. See the NowDB client README for a further explanation or this.

It’s a good time to get acquainted with the notion of the tos, Terms of Service, and the cost calculation. NowDB demonstrates a constant and linear costing, that depends on properties derivable from header data.

It’s a potentially interesting feature of NowDB that the cost calculation is in part based on a property of the response, and not solely determinable by the request. How ought a consumer provide an IOU for a request if they don’t know how much it will cost? There are different ways this can be solved, and the “right” answer is ultimately dependent on the use case. In many contexts, we can imagine we avoid this context entirely, and would allow us to simplify the design of the client.

Once oriented around AccMan and the changes in the behaviour of the NowDB client and server in order to operate with AccMan, it’s time to try with SubbitMan.

SubbitMan is decoupled from the Cardano blockchain. It expects a piece between: the L1 liaison. Detail of the L1 liaison, can be found in the SubbitMan repo’s README and design docs. For now, it is sufficient to know that we can try SubbitMan without a need to access the L1. See the README for instructions.

Once we understand the basic API of SubbitMan, we can setup subbits using CLI tool available at the Subbit.xyz repo. The tool has been tweaked in order to interface with SubbitMan. Like with AccMan, on setting up a subbit, the secrets must be shared with the NowDB client. Ensure that both the server and client of NowDB are in subbit-man payg mode.

Things to try?

  1. When running with payg, stop the server, and increase the costs in the Terms of Service (instructions of how are contained in NowDB). When the NowDB client is run:
    • with no check AccMan payg, then consumer is none the wiser.
    • with check AccMan payg, then consumer is informed but powerless
    • with SubbitMan, then the consumer can withdraw their consent and their remaining funds!
  2. There are different types of cred allowable in SubbitMan. Experiment turning them on and off, and matching those options in the NowDB client.
  3. The L1 liaison is currently manually triggered, but needs to be automatic?! Yes, but. We recommend kicking the tyres hard, before attempting to take the human out of the loop of the L1 liaison; the critical juncture.

Retrospec

Build the right thing

This is always easier with hindsight.

Alarm bells were ringing early on. The M3 milestone was initially rejected by the assessors on the grounds that it was too vague. This was entirely correct. So too was the following from the accepted proposal

An appropriate form this takes is not yet known.

The motivation for M3 was to address the suspicion that without something, Subbit.xyz was yet another piece of infrastructure that devs would not know what it does, or how to use it, or have any confidence that it would be fruitful to commit the time and energy to attempt to find out.

The wording of the milestone says SDK, with an edit commenting on the potential “suboptimal” word choice. What we have emerged with is:

  • SubbitMan, a service that works out of the box to support integrating subbit in applications.
  • NowDB, a toy application with supporting documentation, to be run and literally played with.
  • AccMan, a stepping stone in the set of ideas.

Together we hope that this surmounts the described issue: that these repos allow devs to get Subbit.xyz up and running in a short time, with little pain, to learn which component does what, and piece together what features and functionality present fit their use cases.

Things we did and didn’t do

(Below follows the M3 “Milestone Outputs” section.)

Between SubbitMan the tweaks to Subbit.xyz together with the just functions, facilitates the integration. This can be code directly deployed and run alongside the service(s) which a provider desires to wrapped with Subbit.xyz based payg.

NowDB’s client server demonstrate how an application needs to be extended and/or modified to work with payg, and the additions specific the trustlessness of Subbit.xyz, via AccMan. This includes using LevelDB as persistent storage.

Initial work attempted to find a comprehensive solution to the L1 integration. Even experimenting with plugging directly in to the Cardano node, and working directly with the mini protocols.

Ultimately we judged the benefits could not warrant the massive increase in complexity. Keeping SubbitMan very loosely coupled, but being very explicit on the assumptions! It is safe and tolerable with respect to UX (we think … time and users will tell).

The two repos, SubbitMan and NowDB meet the functionality proposed. NowDB has the API described.

We had suggested that every request from the NowDB client would contain an IOU when run in SubbitMan payg mode. For NowDB type service, we think this design suggestion is insufficient. The NowDB repo describes why; that we can get a divergence between the IOU amount and the cost. The SubbitMan design docs describe why we don’t permit the reuse of previous IOUs, and present some alternatives.

That said, for many use cases this type of problem will not occur. And the complexity solutions introduce can and ought to be excised.

The proposal suggests that there are scripts demonstrating “bad behaviour”. The idea of a script here is misplaced. Our overarching goal is to impart understanding of how these components work. Simply firing off a script that says “Yay!” or “Oops!” is not likely to be informative. Instead, some guide rails laying out how to run code, prod it, and play with it is informative.

JS/TS stack

The language choice wasn’t really moot. The goal is to make software that is accessible to the most number of interested devs. Choose the most popular language.

My personal reflections on JS/TS are not novel. No runtime, framework, or stack that I have worked with have I particularly loved working with.

Specific issues faced here include:

  • Promise chain forking. Very hard to debug. In the end async/await was relegated to very few locations.
  • Cbor serde. See the note on Serde (hell) in SubbitMan.
  • Error handling is terrible, where it is present at all. I was trying to keep the number of dependencies down and keep things vanilla, but in retrospect this backfired. JS sorely misses the rust style Result, ? behaviour.

The cold start time on the nodejs CLI tools is regrettable.

If I did this again, I would just write it all in rust and say sorry.