Intro to SubbitMan

Posted on 2025-04-16

Suppose we have a service provided by our provider and consumed by our consumer and that service provision is predominantly consumer driven. Any typical web API is an example of such a service. A classic service provision sequence is something like:

 
sequenceDiagram
    participant Client
    participant Server
    Client->>Server: request
    Server->>Server: process
    Server->>Client: response

Here the consumer is running the client, and the provider the server. Now suppose the provider wishes to run the API on a financially sustainable basis. That is, they want to charge the consumer to cover their costs.

Without further justification, we’ll take it as given that existing payment methods (eg cash, cheque, card, third party platform, etc) can not feasibly be utilised in this context for pay per request. Most companies opt instead for payment in bulk either upfront or in arrears.

Payment in arrears generally requires the provider relying on some other trusted entity to insure payment such as a bank or, ultimately, the law. In contrast, a provider using upfront payment needs no such guarantees. Instead all risk is bourne by the consumer. Our provider considers first this kind of solutions.

Trustful solution

Let’s unpack how this might work. The provider sets up a database for accounts, together with a service exposing some endpoints. We’ll call the service “AccMan”.

A potential consumer must first open an account, including sending funds to the provider, before making a request. On making an account, the provider gives the consumer unique credential (think opaque bearer token). The consumer hands the unique credential to their client.

Each request the client sends to the server contains the credential. Each request the server receives, it extracts and fowards the credential to AccMan. AccMan checks if an account exists, and establishes the funds available.

The sequence looks like:

 
sequenceDiagram
    participant Client
    participant Server
    participant AccMan
    Client->>Server: request
with credential
    Server->>AccMan: credential
    AccMan->>Server: budget
    Server->>Server: process
    Server->>AccMan: update balance
    Server->>Client: response

In this version the consumer must trust the provider to be well behaved. The provider has complete control over the funds of the account.

The provider may find their consumers don’t have sufficient trust in the provider and instead turn to a more well-known brand. The consumer using brand recognition as a proxy for “good service”. Let’s consider how to migrate to a trustless solution with Subbit.xyz

Going trustless

In a trustless system the consumer permits the handover of the control of the funds in an incremental fashion, rather that in bulk. As a consequence, additional functionality is required on the client. Namely, the client is required to create IOUs on the fly, including tracking current balance, calculating costs of a request, and signing the IOU body.

On the provider side, we replace the AccMan with SubbitMan. SubbitMan accepts IOUs rather than credentials. The trustful version already required that the server handled “budget” and “balance” in the logic of servicing a request. This is unchanged with subbit.

Opening & Terms

Rather than opening an account, the consumer opens a subbit. Rather than sending funds directly to the provider, the funds are “locked” on the Cardano blockchain at the subbit validator address. The consumer must request from the provider information in order to open a subbit the provider deems acceptable. This includes information such as the:

  • address of the subbit, including maybe staking credentials
  • provider key
  • currency
  • min close period

The client requires information in order to create IOUs correctly. This includes details of the subbit (namely, IOU key and tag) and the terms of service from which the client can calculate how much each request might cost.

Apart from the provider exposing the details to potential consumers, and perhaps facilitating their setup of a subbit, there are no further changes required by the provider.

Requests

With SubbitMan, the sequence looks like:

 
sequenceDiagram
    participant Client
    participant Server
    participant SubbitMan
    Client->>Server: request
with IOU
    Server->>SubbitMan: IOU
    SubbitMan->>Server: budget
    Server->>Server: process
    Server->>SubbitMan: update balance
    Server->>Client: response
with balance

This is near identical to the sequence in the trustful case. SubbitMan assures the server that the request is coming from a paying consumer, that the IOU is valid, and that the server is safe to process the request.

The above is in the case of a successful request. The sequence is as before, with the addition of handling an IOU.

It is important to consider each way the sequence can diverge from the successful case.

Invalid IOU. An IOU may be invalid for a number of reason:

  • Internal:
    • The signature is not valid
    • The tag is too long
  • L1:
    • There are no known subbits with (IOU key, tag).
    • There are subbits but they are not acceptable to the provider. For examples: they have a different currency; or the close period is too short; or it already Closed
  • L2:
    • There already exists an IOU for the subbit of at least the amount. On an invalid IOU, SubbitMan returns a failure code.

Insufficient budget. SubbitMan replies with the available budget. The server can decide whether or not this is sufficient to cover the processing. In some contexts the true cost of a bit of service may be known only on completion of the processing. For example, the cost may be calculated on the size of output. It’s up to the business logic of the correct way to handle this and whether to error before, during or after processing.

Failed processing. A processing failure, by insufficient funds or otherwise, may or may not result in the client being billed. Again, this is a server decision. If the client is to be billed, then the server updates the balance on SubbitMan.

Closing

SubbitMan tracks that stage of relevant subbits on the L1. Recall that once a consumer closes a subbit, they must then wait for either:

  • the close period to elapse,
  • the provider to settle the subbit with the last IOU

SubbitMan checks the chain at intervals < the close period. It will submit txs to chain whenever there is a closed subbit awaiting settlement. Additional space in the tx will be filled with the IOUs of greatest redeemable value. SubbitMan will also check if there is an excessive amount owed (debt), and again construct a tx with the IOUs of greatest redeemable value.

The output address is configurable.