The Interledger Community 🌱: Gavin Chait

Hop Sauna social marketplace framework — ILF Ambassador Final Report

Gavin Chait — Sat, 24 Jan 2026 08:45:25 +0000

Hop Sauna is a core technical stack aimed at developers to support implementing a federated, community-moderated web shop offering custom digital objects.

Project Update

Those who wish to lead change have a responsibility to demonstrate and build trust with the communities and individuals we hope will support us.

Our online activity is fraught with dark patterns, described by Caroline Sinders in her Ambassador Report. For open payments to reach greater acceptance by regulators, buyers and sellers, we have to demonstrate greater ethical responsibility than the alternatives. More than that; we have to be easier to use, easier to understand, and safer for everyone.

Supporting African creators

The community I most wish to bring online are African authors on the continent who struggle with financial exclusion.

Even if you are a well-published, famous African author in the diaspora - a Suyi Davies, Nnedi Okorafor, or Tade Thompson - that doesn't mean you can reach African readers. And, if you're an African living on the continent, you can give your work away on any of the major platforms - as Dilman Dila does on YouTube - but you struggle to charge for it.

And then there are the horror stories. Anyone who has ever self-published on Amazon knows how hard it is to sell even one book. A few years ago Chovwe Ekpeki, a Nigerian author, edited an anthology of African scifi which he modestly called The Year's Best African Speculative Fiction. Listed on Amazon's US site, he managed to sell $2,000 of books. Just before he was due to be paid out, Amazon notified him that Nigerians weren't eligible to sell, and they closed his account, and took his - and his contributors - money. This was eventually sorted out, but it left us all with a sense of how tenuous is our relationship with these platforms.

And so we come to our challenges: we are not able to gain access to readers, we can't get paid by the places we publish, and our readers can't always use the ways they are used to paying - like mobile money - online.

Hop Sauna release

I'm struck by just how fundamentally weird the contemporary internet has become. It's got the diversity, curiosity and innovation of a small agricultural town in middle America, or even somewhere in the Northern Cape. In many parts of the world, Facebook is the whole of the internet, just like Amazon is the place you shop. Discovery and purchase happens exclusively in properties controlled by such a small number of companies.

You can judge how far into the barren wastes of the web you are by how often the site you're visiting pressures you into subscribing to their newsletters and build an account there. They're desperately worried they're about to lose you forever.

When I started developing Hop Sauna, I wanted to break these walls open to the wild early internet. I want software that encourages connection, is moderated by the creators who sell their work on that site, has some friction to launching new products so that it feels more intentional, and I want payments to be low-cost, and direct between buyer and seller.

Some of this leans into the growing community of ActivityPub social websites, like Mastodon, but a lot depends on Interledger's success with open payments.

Consolidating everything I've learned this year is still a work in progress, and this report is a continuation of my interim report.

Progress on Objectives, Key Activities

If you know your Clausewitz, no plan survives contact with reality, or your Tyson, where everyone has a plan till they get punched in the face, these are my original goals, and how they evolved.

Goal 1: deliver a template developer stack ready for custom creation of creator community-moderated Open Payments-enabled web shop

Hop Sauna is available as an initial release. There is a great deal of documentation for developers, and much more to be done.

This went more or less as expected, although the steepness of the learning curve, and the challenges of working with relatively immature software, did cause delays as I grappled with getting everything into my head.

Goal 2: develop marketplace tools for facilitating buyer and seller exchanges, including for webhooks for responding to successful purchases, disputes and refunds

Here I was limited by the provisional state of the Python Open Payments Developer Kit. Over the course of my project, I refactored and redeveloped the kit, with the following updates:

Model refactoring and fixes: generated code resulted in models that don't return data, or duplications and deeply-nested RootModels much of which could be deleted and simplified.
New convenience functions: testing the API effectively requires building a full purchase workflow, but such a workflow is also useful to developers using the SDK. The README in the process folder details the main objectives and roadmap, and this update implements the simplest possible payments workflow for purchase and sale.
Updated tests: all the tests should be refactored, especially as private endpoints have been committed to the repo. Tests for the convenience functions run through a complete workflow, and use the new environment variables to safely do a real-world test on the Rafiki test server.

There is currently a pull request awaiting review.

Further development on the open payments aspect of Hop Sauna awaits on approval of this pull request.

Goal 3: kick-start cooperative creator marketplaces through engaging with stakeholders to align the template stack with their needs, and to develop a supportive environment for project sustainability

Early in 2025, I convened a group of African SFF authors from around the world to discuss how best to serve their needs. The group includes:

Cheryl Ntumy: Ghana-based SFF author and founding member of Petlo Literary Arts, a non-profit that develops and promotes creative writing from Botswana. She is also a founding member of the Sauútiverse Collective, an African speculative fiction collaborative worldbuilding project.
Dilman Dila: Ugandan writer, film maker and a social activist. His books include Where Rivers Go To Die, which was shortlisted for the PKD Awards (2024), his films include, “What Happened in Room 13”, has been watched more than 8 million times online. He is currently working on his third feature film, about decentralized governance.
Ivor Hartmann: Zimbabwean writer, editor, publisher, and visual artist. Awarded The Golden Baobab Prize (2009), finalist for the Yvonne Vera Award (2011), selected for The 20 in Twenty: The Best Short Stories of South Africa’s Democracy (2014), awarded third in the Jalada Prize for Literature (2015), and Nommo Awards nomination (2017). He also runs the StoryTime micro-press, publisher of the African Roar and AfroSF series of anthologies, and most recently ZamaShort.
Ayodele Arigbabu: is a writer, architect and creative technologist with close to two decades of experience in delivering projects at the intersection of architecture, design, film, digital media, publishing, event production and curation, as well as in the development of digital and interactive arts and applications. His short story "You Live to Die Once" won the 2001 Liberty Bank Short Stories Prize; his poem "Livelihood" got an honourable mention at the 2003 Muson Poetry competition. His stage play Moremi: The Legend Retold was staged in December 2003 at the University of Lagos Main Auditorium to an appreciative audience, and went on to be performed in Oklahoma and at the National Theatre of Nigeria.
Suyi Davies Okungbowa: award-winning author of fantasy, science fiction and general speculative fiction. He has published various novels for adults, the latest of which is Son of the Storm (Orbit, 2021, first in the epic fantasy trilogy), The Nameless Republic (the second book in the series, Warrior of the Wind, 2023). His debut novel, David Mogo, Godhunter (Abaddon, 2019) won the 2020 Nommo Award for Best Speculative Novel.
Jude Umeh: published author and thought leader on the intersection of emerging technology and Intellectual Property on Digital Content and Rights, Umeh currently works as a Director of AI Business Strategy with Salesforce Professional Services.

Much of what follows is influenced by the guidance of this group. Many of them expressed reservations that they could understand or contribute to the tech, but I pointed out that it's not their job to understand the tech. It's my job to understand their needs and then reflect that back to them using the tech.

What impact does the project have on your perception of digital financial inclusion?

I feel more encouraged after this past year than I was at its outset. I have entered my Ambassadorship with a "show, don't tell" strategy, preferring to build and demonstrate what I'm doing than to simply talk about it. The more I engage, listen and learn, the more viable my approach for federated, collaborative social marketplaces feels.

Certainly, there is a long way to go, but the solutions offered need to be better than what exists, not be perfect on the first attempt.

A lot rests on the success of the open-payments enabled payments providers and wallets, and these are still in a very early stage. However, if we don't also have the ability to rapidly implement webshops using open payments, then that time and investment will remain unfulfilled.

Until then, the best hope for the future is to keep building.

Project Impact & Target Audience(s)

There is something in innovation I call the Milk Problem.

Everyone knows what milk is. If I bring you a new type of milk, I don't need to explain what it is, just tell you how it is different from other milk and why you should buy it.

Push your innovation further out, and you end up in a place where no-one knows what it is you're offering them. You first have to explain everything about that thing before you can get around to the product itself and why people should buy it.

Hop Sauna is not "milk". It is a framework for a new type of federated social commerce which doesn't exist formally as generally-available software. Sure, it builds on social publishing and leans on existing commercial models, but it is complex to explain quickly. People don't necessarily have a mental model for it.

My author's group discussed ways in which they want to be paid and I then structured this into a set of archetypes:

One-off: a payment - usually of purchase and sale - between a buyer and seller which happens once.
Recurring: a payment - usually a subscription, or structured fee - between a buyer and seller.
Conditional: a payment which is conditional on some additional factor - e.g. the seller is required to perform some task, or a threshold of purchases are required - before funds are transferred.

This covers everything from an Amazon purchase, to Spotify streaming subscriptions, to Kickstarter campaigns or even an Uber taxi trip.

There are a myriad of these types of requirements. Each of them needed to be documented, understood, mapped to methods in Open Payments or ActivityPub, and then represented in ways that can be understood by developers, and potential buyers and sellers using that software.

The challenge is many developers have little experience of the challenges of the financially excluded, and the financially excluded don't often get a voice in the technical solutions developed on their behalf.

Hop Sauna needs to integrate this dynamic by default without causing anyone to realise they have no idea what milk is.

I think I'm getting there.

Communications and Marketing

2025 Interledger Summit Mexico City

I presented the first release of Hop Sauna at the 2025 Interledger Summit in Mexico City, as well as charting out where we are, and the sorts of apps I'd like to see arising from my work:

As examples, consider cooperative versions of Uber, where groups of drivers regulate and manage themselves, and have a direct relationship with their passengers:

Or a Booking.com alternative, where guesthouses and hotels don't have to pay intermediaries to handle their bookings for them:

2025 Interledger Hackathon Mexico City

I was a mentor at the hackathon, during which teams attempted to build new applications for open payments. This gave me first-hand experience of the types of challenges developers face when using open payment development kits, and also to gauge interest in more enhanced features for the toolkits.

I also had the rare pleasure of having two teams adopt Hop Sauna during the event and deliver completed submissions using it.

Podcast

Cheryl, Dilman, Jeremiah Lee from the Foundation, and I collaborated on a podcast, published in December last year.

This covers much of the ground we considered during my Ambassadorship, ranging from the cascade of transactions necessary to get money from publishers in the US into the hands of authors, to platform exclusion, to the multiple ways we need to borrow identities from others with more privilege just to get things done.

I have also begun engaging with some of the key developers and infrastructure designers of the fediverse to ensure that Hop Sauna plays well with others.

What's Next?

Hop Sauna extension

There is an initial set of moderation hooks, and I will be focusing on extending this in Q1 2026.

My working plan so far is to implement the following:

Site level:
- Universal block lists
- Geotargeting - fairly blunt, but using IP addresses to isolate "bad places"
Actor level:
- Individual blocks/mutes at site and actor level
- No reply except for direct messages, and limit direct messages by default to followers only (they can open this, if they wish)
- Detachable reposts for the inevitable shark-baiting. Given many stacks aren't yet implementing this. I figure it works more like a mute.
- Geotargeting of individual actors with options to block, show different information, or offer a different price. This works on multiple levels from the way I was originally thinking of it (offering books for sale only in certain countries) to the limitation of products which may be illegal outside of certain jurisdictions.

This mostly reduces clutter and problems on the commercial server, but a repost on another server probably supports replies there. Again, a functional mute on main.

The more specific commercial limits will be:

Dunbar's limit of 150 creators (any number of supporters, depending on the type of service - on my Kindle-alt, readers have accounts to store and read their books).
All Actor Services (products) can only be made public by an approved editor with those rights.
Messages are all generated, meaning you can only send a message to your followers when a specific type of action occurs (publishing a book, offering a period-limited discount, that sort of thing).

None of that stops individuals reposting their product announcements on their other socials, but there they would be limited by the rules of those communities.

The Dunbar's limit includes an extension - the stack name cannot be a creator server. As example, the Kindle-alt will be called Qwyre (rebuilding my existing https://qwyre.com which stopped working commercially when Coil was closed, but still works perfectly well as my main ereader). Qwyre itself will be closer to something like JoinMastodon, and eventually become a federated search engine for books from all the different imprints (servers).

I think it's critical to ensure distribution and discovery to prevent agglomeration effects that overwhelm safe communities.

Qwyre for self-publishing

I have a new novel. My intention is to dust off the old Qwyre and build a new Kindle-alternative where I can collaboratively publish my work.

Community Support

I would appreciate the following:

Code review
Feature development
Internationalisation
UX / UI
Unicorn Hunters

This latter is aimed at developers who want to build on Hop Sauna with apps targeting existing monopoly commercial tech, like Amazon, Kickstarter, Uber, etc.

Oh, and funding. I'm always looking for funding to support continued development.

I wish to thank Interledger for their support, and look forward to everyone's thoughts on progress to date.

Hop Sauna — ILF Ambassador Progress Report

Gavin Chait — Wed, 16 Jul 2025 17:35:54 +0000

Hop Sauna is a core technical stack aimed at developers to support implementing a federated, community-moderated web shop offering custom digital objects.

Project Update

Any system permitting commercial exchange exists at the intersection of what is technically possible, ethically responsible, and permissible under the patchwork of international regulatory compliance.

Building a commercial website is relatively straightforward. Frameworks - like Django or Drupal - exist. You can integrate Stripe or PayPal quite quickly. But, once you're done, such a site offers little advantage over listing your products on Amazon or eBay, with the huge downside of being functionally invisible to the larger world. If you're already famous, moving to your own infrastructure may have advantages, but if you're less known, or just starting out?

But, what happens if you live in a part of the world not supported by these platforms, or are just tired of the ethical and business practices of the platforms?

A functional, community-oriented commercial platform would have the following characteristics:

A community of peers, selling similar or compatible works, where membership is a function of acceptance by that community,
Review of business behaviour (or moderation of activity) is by the community, ensuring that members are held to agreed norms,
Costs are kept to the minimum with members paying for shared infrastructure, but otherwise keeping their own revenue, or contributing in some agreed way to their community.

Each community would also interoperate with other communities which offer similar works and where their community standards are compatible. This interoperability ensures collective discovery, much like the webrings of the early internet when search was still in its infancy. Discovering one link in the network provides access to a wider world.

A single website can be structured however the developer chooses, but the moment information needs to be exchanged between sites - federated - interoperability standards become critical. It would also be helpful if that standard already supported interactions between millions of people.

Or, to summarise, it would be nice to go where the tea is already being made.

And these then are the objectives of my project.

Building a website based on intrinsic interoperability means that one is never building in isolation. Federation requires a set of standardised methods for services sharing the same protocol to query and interpret data from each other. ActivityPub and ActivityStreams provide the protocols we need, but these exist side-by-side with the ordinary protocols of the site itself.

To contextualise this, think of email. Where email fails is that there is no way to moderate who gets to email you. So you get spam. ActivityPub enforces authenticated fetch, meaning people have to prove who they are before they can send you a message. That process of being able to send authenticated messages between authenticated actors (people) can be used for anything, and the first use-case is social media (think Mastodon).

The main challenge for anyone building from scratch is that, while the protocols themselves are well-documented, you need test servers to send messages to so that you can see if your software is capable of two-way communication. Fortunately, ActivityPub.Academy by Sebastian Jambor exists. But a lot of stuff isn't clear, and ActivityPub itself is like a Matryoshka doll of nested metadata which needs to be tested before it can be used.

An image can be listed as a URI reference, or as a data structure where the link can be named "url" or "href". And then there's the undocumented best-practices, like how exactly should you implement authenticated fetch safely?

Say you have a person on your website who has chosen to be unlisted and protect their privacy. You get a request from an external website to interact with this person. Authenticated fetch requires a named "actor" to send back a query to the sending website, allowing each website to authenticate the other. Site Albert sends a message from Bradley to your website Clarice to the person Dominique. Which identity should respond to Bradley? If this is a wild spam message designed to check if such an identity exists prior to attempting some scam, sending a message back from Clarice would confirm that their identity exists without yet confirming who Bradley is, or if they are who they say they are, or whether Dominique even wants to talk to them.

In Amazon or Facebook, if you want to send a message to another person on the same site, you both have to be logged in. It's a relatively straightforward problem.

With ActivityPub, an undocumented solution is to create a universal site actor which acts as an agent for all identities on this initial approach. Once Bradley is verified, and you can then test if Dominique is open to contact from Bradley, only then do you permit Dominique's identity to be exposed to this external identity.

And so it goes.

Each interaction requires solving two sets of problems:

How do you get this code to do what it is supposed to do? Not a trivial problem.
How do I design this so that my community members are kept safe, and are able to keep themselves safe? Even more challenging in the absence of mature systems.

I have also implemented multi-language support - both statically in the app, and dynamically in text provided by creators and admins (i.e. you could directly serve different translations via the same posts) - from the beginning.

This is very slow going.

However, when you get it right, you suddenly get a whole bunch of things working at once.

This image displays my Wandering.shop profile on the Hop Sauna build. To get what may seem intrinsically simple running requires everything else - authenticated fetch, appropriate webfinger endpoints - to be working.

Hopefully this demonstrates the value of these protocols to a community-based webshop - you can know your customer, moderate who gets to be a customer, and maintain relationships with your customers.

And so, my update is that progress is happening, but in bursts. Along the way I have also kept an eye on the Python Open Payments SDK which I will need as I head deeper into implementing web monetization and payments. Now, payments themselves are a complex set of products. Simple purchases are complemented with subscriptions, milestone-based fundraising, and other variations. Some are artifacts of the way credit cards work and aren't directly transferable to open payments.

I have convened a small group of African authors to discuss the requirements they have from a federated platform, and many of the initial suggestions raise additional questions. Take implementing a Kickstarter-style fundraiser. Credit cards allow for deferred payments, a mechanism largely developed because the high cost of transactions means that reversing a charge creates such a cascade of fees that it makes the whole thing impossible. Instead, a vendor can put a "hold" on a promise to pay, and then keep that until some criteria are met (or not) then either release the hold, or execute the transaction.

Open payments has no such method, because it doesn't need it. But, without a hold, how do you run a criteria-based fundraiser? Well, you need an escrow service. Some third-party which will hold the funds until such time as the criteria are met, or not, and then release or return the funds. And now we've crossed from a technical software problem to a regulatory one.

An affordance is a set of possible actions which arise from the design of a thing. You may wish people to use the thing you made in specific ways, but if your design also permits other ways of acting then you can be sure those ways will be tested. And, unfortunately, affordances that permit bad behaviours impose an external cost on our communities. These externalities - like spam from email, or racist autonomous language models - arise naturally because of design decisions that, while technically clever, didn't take into account ethical and regulatory responsibilities.

Which is a longish way of saying that the creator group is raising requirements that require an ethical and technical assessment, and why Kickstarter-style fundraising will not be supported in the first software release until such time as there are mature escrow services to support the function.

Progress on Objectives, Key Activities

The key goals are time-sequenced.

Goal 1: deliver a template developer stack ready for custom creation of creator community-moderated Open Payments-enabled web shops.
Goal 2: develop marketplace tools for facilitating buyer and seller exchanges, including for webhooks for responding to successful purchases, disputes and refunds.
Goal 3: kick-start cooperative creator marketplaces through engaging with stakeholders to align the template stack with their needs, and to develop a supportive environment for project sustainability.

Goal 1 is about 80% complete. This has taken quite a lot longer than I initially hoped largely owing to limited documentation. I spent a lot of time reading through other people's implementations in programming languages that are quite foreign to me (or - given coding is deeply personal - using approaches in languages I'm familiar with that are as foreign). GoToSocial is a tremendous project, written in Go, that I have trawled through for database structure and various solutions. The Bovine project is also key to my work, with a lot of undocumented features necessitating constant review of the code.

Along the way, I had to "solve" quite a few seemingly non-standardised decisions. Take hashtags, now in common use for theme discovery. Very few implementations support UTF8, meaning that Japanese or Arabic hashtags aren't universally supported. I support this, but I balked at supporting emoji-based hashtags.

What remains to be done is moderation. However, everything in ActivityPub is a message which then gets acted upon depending on the type of message it is. Moderation requests and responses are types of messages that have an impact on how the targeted identity gets to behave (banned, muted, time-outs), and deciding on what is appropriate, and what flexibility of action to permit site administrators, is itself a set of affordances with its own considerations of externalities.

There is also a newly-proposed fedidiscovery standard which is intended to support general search and discovery across federated websites. I will need to explore this with a view to ensuring support. The current standard envisages centralised "hubs" which act to harvest data from sites which opt in, and against which other services can then run queries in an optimised way. This would require an additional "hop sauna search" instance and is currently out of scope.

I am due to begin Goal 2 development this month, and have been talking through the availability of APIs and methods for implementation with the kind help of Uchi Uchibeke at Chimoney. There are currently only a small number of financial services supporting open payments, although more will be joining as Interledger-supported projects launch. As I get deeper into this objective, I'll build a list and try assess their level of maturity to include in the developer documentation.

Goal 3 is to keep the deliverable "honest". I have invited a small group of African speculative fiction authors to discuss what a self-publishing "imprint" would require to support creators. It's far too easy to deliver software which solves problems but in ways that are impenetrable for non-technical people to use. When the software can be easily understood and used by this group, then I will know it can do the job. However, their requirements also raise areas where - even with the best of intentions - open payments financial accessibility will fall short. This has surfaced a needed output for the project where I map existing types of creator financial services (auctions, markets, conditional fundraisers, etc) into open payments equivalents, highlighting where services may not yet support implementation. This group will continue discussions till the end of the project with a potential workshop still to be organised at the end.

What impact does the project have on your perception of digital financial inclusion?

Hop Sauna is not intended to reveal or explore problems of financial inclusion, but to build a developer toolkit to support inclusion. With that caveat, exploring implementation does reveal what is still lacking. At this stage, open payments can handle the core transactional requirements of a webshop - one-off payments and subscriptions - but will require intermediaries to support criteria-based fundraising.

There are also interoperability requirements that can limit cross-border payments (or, increase the costs) even with open payments. The Pan-African Payment and Settlement System (PAPSS) is a pan-African initiative which appears equivalent to the EU open-banking approach that has massively reduced costs and complexity for doing banking across Europe. But ... it is fairly new and a long way from full implementation.

Hop Sauna will be released into what is still an immature implementation environment. While mindful of extending inclusion, I also need to ensure that it supports what absolutely will work right now, rather than what might be available in future.

Plus, there are the affordances of open payments which remain as-yet unexplored. Once you can make microscopic, rapid peer-to-peer payments, what types of services or opportunities may yet emerge? Something for our creator group to consider...

Project Impact & Target Audience(s)

There's an awesome patisserie near where I live. They serve incredibly creative confectionaries; each a flavour journey. And it's all vegan.

This isn't something you'd know unless you went looking to find out. The objective of the people behind this delight is show not tell. I'm the exact type of person they're targeting ... someone who would never consider vegan by default, but am perfectly happy to be educated if it comes in an accessible way.

Until there is widespread adoption of open payments in commercial interactions, the opportunity to impact financially-excluded communities will remain notional. Or, until the tea is made where excluded communities are we're not succeeding. Hop Sauna is not a destination along that path, but a key enabler to ensure it is easier for developers to create accessible products which happens to support using open payments by default. My objective isn't to tell developers that open payments makes markets more accessible, but to build a compelling suite of tools that speeds up their development process and supports widespread adoption without open payments being experienced as anything other than a straightforward payments implementation.

Importantly, this is a moving target. PixelFed, the federated photo-sharing app, has announced an intention to develop micropayments support using Web Monetization. This is likely to be the first major, and mainstream, implementation that will hit the fediverse. That massively raises the exposure of open payments, while also surfacing any potential community concerns which I can account for (or try to mitigate) as I develop.

The impact of what Hop Sauna does, and what I achieve through this ambassadorship, will take time and I expect to be held to these objectives over the long-term.

Communications and Marketing

So far, I've kept this very quiet. Sausage-making is not an attractive process, and technical development is not much of a spectator sport. I have written on some initial development considerations and - once I release the first Hop Sauna ActivityPub build - I'll start writing more frequently on what I'm doing.

This will initially be with developers and then, as I get deeper into developing commercial products, with creators and creator communities.

What's Next?

From this month, Goal 2 takes priority till the end of the project, with implementation of open payments and the various mechanisms to create products and methods for payments. A creator should be able to create a product, then associate regional / currency and price data to their product. The software needs to handle refunds, complaints and time-bound price discounts.

I will also - once the demo version is near completion - facilitate a workshop with the authors collaborating with me on the needs assessment.

Community Support

I would appreciate technical code reviews on the template stack (Python/FastAPI and TypeScript/NuxtJS), as well as help with the Open Payments SDK. Also, non-technical, looking for members of cooperatives or creative communities working collaboratively on creative commercial activities, discussing their needs so I can ensure that the template has them covered.

Also, if anyone reading specialises in developing user interfaces at the intersection of commerce and social media and has ideas, as well as experience with Nuxt/Tailwind, please get in contact. I may have some budget to pay for your time to help sort out the frontend interface.

The battle between the Commute and the Community, or the strangeness of online monopolies

Gavin Chait — Sat, 24 May 2025 09:46:23 +0000

If the town where you live was more like the internet, there would be one large department store where hundreds of vendors, all selling more-or-less the same things, would all be yelling at once while waving long lists of customer ratings to persuade you to buy from them. When you go through to pay, the department store - whose employees you never see - would extract anywhere between 30% to 70% of the price as their cut before passing the rest onto the vendor.

There would be no charismatic little streets with cafes spilling onto the pavement, or the bustle of people chatting, laughing and living. Instead, what you'd have is commerce stripped to its essence, "red in tooth and claw".

The challenge for any community recovering from this centralisation is how difficult it is change behaviours when there is no - seeming - compelling reason to do so. Unless something dramatic happens.

In 2020, with COVID, many of us got to experience that change. Amidst the pain, we also experienced a liberation of community. Restaurants spilling onto pavements. Shopping close to home. Living in community. And we liked it. Since then our battle between the Commute and the Community has become polarising and heated.

Gradually, perhaps imperceptibly, this battle has also been coming to the internet through federated, interoperable social media like Mastodon, BlueSky and their ilk. Hop Sauna, my 2025 Ambassadorship, is intended to push this further into the commercial space, recovering our online economic communities.

What does a webshop need to do?

Anyone can launch a new webshop; barriers to entry are low, but barriers to success are enormous.

Any commercial stack must support two key behaviours:

Discovery is the opportunity to find the beings and doings of others.
Delivery is the opportunity to express our being through our doings, or to enjoy the beings and doings of others. To be creative or legitimately acquire the creativity of others.

You can't rely on search engines to help you. You need - in the words of Raymond Ackerman - to "go where the tea is being made". To be part of what people already do.

Engaging with people where they already have community must play well with that community - creators, buyers and sellers, makers and users, readers and writers - and ensure their safety by ensuring:

Simple and ethical rules which apply to all, ensuring diversity, equity and inclusion,
Respect for the privacy and protection of its community,
Protection of its community from force or fraud,
Clear, transparent and fair means of discovery,
Simple and low-cost means of delivery.

An accessible federated stack must also offer:

Simple ways to deploy the same stack independently,
Tools for migration between stacks without losing supporters or anything purchased,
Equal opportunity for discovery across a federated network of equivalent services, subject to adherence to a common set of ethical rules,
Moderation tools to support enforcement of ethical rules, whether the moral subject is an individual, or an entire other server.

Why is federation necessary to compete with monopolies?

Any centralised stack (be it Facebook, Amazon, eBay, Uber, AirBnB or Etsy) offers both discovery and delivery. But, they are also rent-seeking, in that they extract most of the value created by their creators, and do very little to uphold ethical values. Ethics are an expense and, in any case, controversy is good for "engagement".

They're equivalent to feudal landlords, charging their tenant farmers a significant share of what they produce and holding to themselves the right to turf any of their tenants off the land at any time, for any reason, rendering them instantaneously destitute.

Given these online spaces are entirely virtual, how did we get to a place where land is scarce, and landlords can do what they will?

The short answer is that - without ethics, standards and discipline - feudalism is inevitable. Learning why, and how it came to be, is crucial to understanding how to avoid it.

The early internet of the 1990s was a wild place. Along with blogs and early commercial sites were random interactive experiments with a tendency to explode, and lots and lots of porn.

Discovery was largely down to curated lists, webrings, web bookmarks, and search engines. Any of these could be open to spoofing, and so clicking on any link ran the risk of ending up on a porn site, or crashing your computer as some poorly configured website generated infinite new pages.

Yahoo offered curated search results. That's right, early Yahoo hand-curated every link, which scaled about as well as you can imagine it would.

Google arrived with a new algorithmic approach: weighting links by the number of inbound references. Suddenly, for a brief while, you could find things and - with discovery stabilised - delivery could really begin.

Every company started offering their own online shops. With that, they needed to ensure discovery, and the advertising market of contextual links exploded. Unfortunately, so did "search engine optimisation", referral links, and "me-too" sites.

Companies with economic heft could rise above the noise, but small startups had no way through the morass. Enter Amazon, eBay, Bookings and Facebook.

The challenge of selling online is discovery and delivery. If, though, you went inside a gated mall then - in exchange for a significant share of your income - you got protection and exposure.

Twitter and Facebook offered their sequential feed of people and services you were actually interested in by opting in to what they posted. Amazon, Booking, Uber and Etsy allowed you to buy things you could discover using a search engine that actually delivered on what you were looking for.

And again, for a while, that worked. But exploitation soon followed.

As before, the problem is "noise" which includes spam, chum, fraud, and hate speech. Worse, creators are deliberately trapped. Whether by relying on centralised systems of discovery (Google, Facebook, Twitter, Instagram) or delivery (Amazon, Uber, AirBnB, Etsy), where do you go?

The noise of enshittification really took off with the acquisition of Twitter in 2022 and an opportunity arose from IndieWeb's POSSE (Publish (on your) Own Site, Syndicate Elsewhere) philosophy when Mastodon's ActivityPub implementation took off.

Federation means that interoperable websites share a common way of communicating and sharing information. You can finally discover and curate a community. More importantly, federation returned moderation decision-making to small communities.

The rejoinder from the centralised stacks is that Mastodon is tiny, so why would you bother, but that's a bit like complaining that your favourite coffee shop only seats 20 while the huge department store can accommodate millions. Is that what you want from a café?

And so that is the task before me as I continue to build out Hop Sauna. A webshop that not only uses the open payments protocols to reduce the costs of exchange, but also offers communities an opportunity to moderate themselves while not losing the opportunity to be discovered.

I would love to hear from you … what features and requirements do you have from a community-moderated and federated webshop?

Hop Sauna, a social marketplace framework - introduction and roadmap

Gavin Chait — Sun, 13 Apr 2025 13:51:58 +0000

The online new is no longer absorbed into society with the unquestioning rapture of the 1990s. Neither should it be, especially when it comes to new ways to make and receive payments.

Low-cost, low-fee transactions are not a "solved" problem in federated online communities. Every community server raises funds using PayPal, Patreon or various other "tip" portals rather than integrating payments directly into their systems, forfeiting significant fees along the way. Creators still sell on Amazon, or other centralised portals, while promoting their work via multiple social channels. And little of that is available to creators working and living in the global South.

Nothing here is connected or integrated. All of it costs more than it needs to.

The logic of open payments is that instead of every website using the extensive banking infrastructure of credit cards and an authentication process involving multiple fee-charging intermediaries, payments are instead made via interoperable digital wallets. Individuals manage cash in and out of their wallets in whatever ways their service-provider supports.

The protocol for interacting with these wallets uses the open payments architecture, and each website must then manage interaction with these APIs. That often involves a lot of duplicated boilerplate code, not just at the transaction level, but also in defining and managing products and fees, authenticating payments are received, and then acting on that authentication.

This is tedious even with mature and well-documented payment libraries, but in a new protocol can be confusing, frustrating, and a barrier to adoption. Such barriers - if the incentive is sufficient - often produce new centralised intermediaries to act as an interface to that complexity. Best to get in early with an open source alternative.

The purpose of the Interledger Foundation Ambassadorships is to support early-stage efforts at building bridges into the adoption and use of the open payments protocols. My Ambassadorship is all about enhancing accessibility to a technical protocol that most shouldn't need to know about to experience value from it.

Putting new payment systems into use is less about telling people, than putting it where they most need it as simply as possible.

My project, Hop Sauna, is an open-source template stack ready for custom development of community-moderated Open Payments-enabled web shops, including a base server and client, with documentation, to support rapidly creating new types of federated commercial social applications.

My technical deliverables are:

Open Payments web shop template stack.
Open Payments Python SDK and template components.
A dedicated documentation site for the template.

The first step along the way is a base template stack, which is already available for use, along with all the documentation required to develop and extend it.

This foundation will become Hop Sauna, which will integrate the Open Payments API, along with full digital product and purchase management. The objective is that sellers add their wallet / API keys and then the stack manages everything for them:

Digital product creation, registration, and pricing (including multiple currencies),
Purchase process between service providers (wallet services) for seller and buyer,
Payment authentication and administration for the seller,
Digital product distribution for the buyer.

The template manages an exchange, authenticates that exchange and then approves distribution. The specific nature of what is distributed, and how, is a factor for the developer to build. It is their unique "product". Developers will not have to implement any part of the product or payments process.

Effectively, it will be a foundation to many of the required coding challenges in the server and client, permitting standardised exchange of digital goods.

Towards the end of my Ambassadorship, I will begin looking to the next phase of my work, which is ensuring that the stack supports the needs of creators. I will run a small creator's workshop where collaborators will discuss their particular requirements and allow me to ensure that the stack is able to fulfil these needs.

If you want to get involved, I will need code reviewers, and - especially for the open payments SDK - technical collaborators to speed up development.

If you have any questions or suggestions, please get in contact.

'Empathy' - new African speculative fiction by Cheryl Ntumy on Qwyre.com

Gavin Chait — Mon, 09 Jan 2023 08:24:07 +0000

Qwyre is starting 2023 with the release of Empathy, a new work of African speculative fiction by Ghanaian writer, Cheryl Ntumy.

In Empathy, a mother tries to save her son from himself in this haunting tale set at the brutal intersection of alien intelligence and humanity.

Cheryl's work is monetised and you can read it here.

Qwyre is a streaming payments platform for collaborative publishing, and an ereader, and received a grant from the Interledger Foundation. Tap left or right on the page to go forwards or back.

Qwyre.com - What we learned, and our ethical foundations and plans for future development [Grant Report #2]

Gavin Chait — Tue, 29 Mar 2022 09:19:02 +0000

I'll be sharing these experiences during April's Grant for the Web Community Call. Please come along and let me know what you think.

Register here for the Grant for the Web Project Skill Share Community Event 10am EST / 4pm CEST on Monday 25 April

Streaming micropayments - web monetization - is new. And the online new is no longer absorbed into society with the unquestioning rapture of the 1990s. Neither should it.

From cryptocurrency pump and dump fraud to wildly hyperbolic promises to the tech industry's complicity in genocide ... there are many reasons for the average person to be sceptical of the new.

So, while the technical challenges are great, the social ones - of building trust, resilience, and engagement - are even greater.

Yet the promise of disintermediated micropayments is greater still. It is up to us, the community of web monetization makers, to earn that trust.

What follows may seem unduly negative, but it helps to take stock. To have a realistic appraisal of what challenges us as we take our first tentative steps in this new medium. And, mostly, for me to recognise what I got right, wrong, and still have to reckon with.

Makers are not speculators. Risk is not theirs to take.

I used to run a small development project in the shanty towns around the formal neighborhoods of Cape Town. An ubiquitous feature of every street are tiny spaza kiosks selling small packets of sugar, soap, coffee or whatever, repackaged from much larger boxes. What is in those packets isn't some no-name brand, cheapest of the cheap. Nope. Brands. Omo. Lux. Five Roses. Hulett. All the comforting South African logos.

For a simple reason.

When you are poor you have no room for risk. Too much goes wrong on a daily basis for which you have no protection. You cannot afford to buy the wrong brand of soap.

Creators on the internet may not be quite as poor, but they're on the cusp. Most are not superstars, but have multiple sources of income, cross-subsidising their creative pursuits with whatever ad hoc work they can take. Setting up Qwyre.com and telling authors, "Hey, come publish here, you'll get paid in real-time and direct to your payment pointer." isn't a quick win.

Sampling the writing community yielded responses like, "Cryptocurrency? Hell no!"

It doesn't matter that publishing on Qwyre is simpler than publishing on Amazon, there is no halo effect from established brands. Payments aren't via Visa or Mastercard. Creators can't use their own credit cards, Stripe or PayPal accounts.

Instead, creators have to sign up for a whole new "wallet" and generate a "pointer" on a web service replete with promotion of speculative cryptocurrency investment.

It certainly helps that Uphold and Gatehub are working on complying with regulatory authorities in the US and EU, but that takes time. It's also happening now, so when people do go to sign up, they're sometimes told that new accounts aren't available in their region while this regulatory process unfolds.

Lessons: I made the technical process of uploading creative work and publishing as easy as possible, but payment pointers and getting paid are - like most publishing platforms - not part of the core workflow. It's not a technical challenge, but a critical part of their user experience.

I will be redeveloping the publishing experience to integrate payment information and ensure writers know I take their getting paid as equal to them publishing and being read.

Making monopolised proprietary lock-in impossible

The tech industry has awoken to new EU legislation which mandates prying open the locked-down world of text apps, like WhatsApp. Such lockin should never have been tolerated in the first place, and a world in which the underlying technology had been designed around open interoperability protocols wouldn't have supported tech monopolies in quite the same way, or caused such pandemonium when eventually dismantled. After all, we take it for granted you can phone anyone on any network.

But just because we came up with a new way to support micropayments doesn't mean we haven't stored up a future where a small number of companies monopolise monetization.

As Eric Parker, South African franchise guru and co-founder of Nandos, used to say, "Run your small company as if you were a big company."

He didn't mean "exploit your workers, offshore your profits, and lobby politicians". What he was talking about was technical and management debt. That the mistakes you make in the early days become part of the foundation of your company and impossible to remove later on. They will hurt you forever, and most are avoidable. If you hire only white males from the same schools at the beginning, and twenty years later you wonder how you have fomented a bro-led toxic culture hostile to women and diversity, you're being deliberately ignorant of the world around you.

To summarise the summary: Start as you mean to go on.

In our case that means make monopolies impossible from the beginning. Don't give yourself the option. Make it easy for your users to leave. Let them take their stuff and go whenever they want.

I can't do much about how Coil, Uphold or Gatehub may choose to run their businesses, for good or ill. But I can control my own.

That means make leaving easy. Creators must be able to take their work - their epubs - and publish them elsewhere. There must never be the option for me to centralise payments. Creators must always be paid direct. But these are relatively easy. There's harder stuff on interoperability I'm not sure how to solve:

If you have a successful link to your work, how do you take that with you? Probably impossible, unless I figure out how authors can use their own domain names?
What happens if someone already has their own website but wants to integrate with mine for search and reading interface, is that possible?
What about other platforms doing the same thing? Should we have shared APIs and expose each other's work? Should a reader on Qwyre be able to read a work on my platform on a different app?

If you think about Amazon, or Spotify, your library isn't available on other platforms. Even when you outright buy the work, you're locked in to reading or listening on their app. I have multiple copies of some things simply because of this lack of interoperability. And it's not right.

Lessons: It's easy to get lost in the technical challenge of making interoperability work, but that's to lose sight of needing to have enough readers and creators to make this necessary in the first place. Start as you mean to go on doesn't mean do it now.

So ... this is a commitment to making interoperability core to Qwyre - to using open standards (like epub and not inventing some alternative locked-down mobi standard instead) - but not to be so obsessed with this that it overwhelms a primary need to build a community of happy readers and creators in the first place.

Crucially, it is also to be a vocal champion against monopolies, and for open interoperability. To be mindful of what I make, and what I do, to ensure I am in accord with these standards.

Patience and the new

One challenge of engaging with tech-driven innovation is watching the wave lift boats all around you, but not yours. Too early, too late, not in the right place ... you end up obsessively running weird - and unnecessary - A/B testing. What about this colour? If the button was 2mm higher on the page? How about a different font?

Before we had the monopoly stacks, I remember grazing widely on search engines and news portals. We certainly have a winner-takes-all problem, but see my previous point.

It will take time to build confidence. Time for the various tech components to mature. Time to become part of the world.

So, what should you be doing in the absence of users. What should I be doing in the absence of readers and creators?

I'm running a short-story competition although the pushback from communities where I've sought to promote it has been weird. It's not ok to promote it because of the payments process. Promoting writers to publish because they will get paid by readers while they read is, somehow, not acceptable, but charging readers for a published work and not paying the writer a live share of that is traditional and acceptable.

Until monetization becomes as mainstream as credit cards, it's going to be difficult for it to be an innocuous and inoffensive way of simply getting paid.

So, however long it takes to attract other writers and readers is going to take patience. Whether I like it or not doesn't enter into it.

But ... I am a writer. I can write for my own platform, and that will help me improve the app in measurable ways that make writing and publishing more pleasing for others.

You can see my doing that now. Here's a short story called "If only they couldn't talk". Go ahead. It's free. You don't even need to enable monetization to read it.

Similarly, I need to engage, as much as this navel-gazing introvert is capable of.

Lessons: It's easy to over-think slow-uptake as indicative of commercial failure, but in a new industry - where so many of the concepts and technology are still very immature - it may simply be that you're too early. Spending emotional and financial bandwidth leaping about trying different things may leave you burned-out and spent.

It is better to have a consistent plan, one that fits within the limits of your mental and financial health, and keep going. There are certainly examples of overnight wonders, but there are just as many of plodders who got there slow and steady.

I commit to writing more, promoting more (but not obsessing about likes or hits ... I'm not particularly good at social media), and using the awesome thing I made.

Being supported by Grant for the Web has been an amazing and creative experience. I've enjoyed the community, feedback, and support from the team. I know this is only the beginning, and I hope the alumni of these first few years get to gather in a few years time and look back in wonder and gratitude at all we achieved.

Good luck, and go read something (on Qwyre.com).

Qwyre launches its first web-monetized African speculative fiction short-story competition

Gavin Chait — Tue, 22 Mar 2022 14:57:12 +0000

African speculative fiction is finally achieving recognition. Nnedi Okorafor and Tade Thompson have won all the awards. All of them. And amazing anthologies like Dominion edited by Oghenechovwe Donald Ekpeki and Zelda Knight have introduced some amazing authors, like Dilman Dila and Mame Bougouma Diene, to a wider audience.

We can do more.

Qwyre.com is live and we want to showcase awesome writers while also promoting web monetization for authors.

We are offering $50 to each of the ten best African speculative fiction short-stories published on Qwyre.com by 30 April 2022.

The rules are simple:

5,000 words, but if your story works longer or shorter, do that. Don't let a word count get in the way of a good story.
Competition only open to African speculative fiction.
Multiple submissions are fine, but you can only win for one.
Original is preferred but – if you have rights to republish – a second publication is ok. This is especially welcomed if you've self-published elsewhere.
Abide by Qwyre's rules.

Most fiction competitions end there, with the prize. But Qwyre can offer everyone - including those who aren't amongst the ten - the opportunity to earn direct from readers from the moment they're published.

Web monetized work earns about 36 cents per hour, or 0.6 cents per minute. For every minute someone reads your work on Qwyre, you get paid.

To put this in perspective, streaming music services pay about 0.003 to 0.12 cents per 5-minute song. A 5,000 word short-story would take about 12 minutes to read and earn 7.2 cents. You need to be read 700 times to earn $50.

Qwyre authors share in this income directly and in real time.

If you've self-published on Amazon, you know how their approach works. They take all the money and, some interminable time later, they pay you your share. Web monetization means you get paid in real time. Instead of us taking the money, calculating shares, and sending to different people, we divert payments to parties as people read.

If you agree to pay an editor 15%, and 85% for yourself, then there is a three-way split: 12:73:15 (this ratio takes into account Qwyre's 15% share). Web monetization is per-second payments, and we push payments to each party in this agreed ratio. Everyone gets paid right away.

Which means - just like other publishing platforms - you need to create an account so you can be paid.

Here's how all this works ...

Publishing your work on Qwyre.com

First things first. Open your veins and bleed. Write something. Once you have something written, proceed.

Prepare your work for publication

There are plenty of ways independent authors can self-publish. That lack of any friction between the author and the reader is one reason so much is produced, and with such low quality. Commercially-published work benefits from the simple barrier of being edited. Just that surfaces poor prose and obscure, or irrational, storytelling.

Qwyre is about collaborative publication, so here's the workflow:

1. Start at your new creator's workshop

Here you'll find links to the docx convertor, as well as panels to review your works in progress, and offers for editors.

2. Convert your Word document docx to an epub, in a three step process where you'll describe your work (title, author, publishing date, keywords, that sort of thing ...), upload the document and cover, and then build the standards-compliant epub. This allows Qwyre to stream your work to readers.

3. Import your epub, either during the docx conversion process or, if you've produced your epub in some other way, direct into the platform:

This is intended to be as easy as possible. If you've got an external link or a local file, either can be imported.

4. Review your work and check that metadata (your descriptions and keywords), the contents and sample text are presented as expected:

The metadata and text are derived entirely from the epub you uploaded. If anything is incorrect it may be because of non-conformance to the epub standard, or because the text is wrong in the source. Correct that, upload a new epub, and ensure you're happy.

4. Prepare a contract with your revenue share between yourself and prospective editors. This is what will be shared between the author and editor during monetization.

Anyone can be an editor and I encourage writers to offer to edit other writers work. Not only does this help you improve as a writer, but you also have the opportunity to share in the revenue of a greater diversity of work. Editors are paid too!

5. Offline collaboration for publication is an important part of the creative process.

The review and collaboration process is initiated via email. Sharing the editor's email address with the author only when offered, and then getting out of their way once they finalise their contract. Qwyre is not going to own the editorial process and the parties to the creative work should edit and review as they prefer.

Only once both parties have agreed the contract, and agreed the work is ready for publication, can the creator release the work onto the platform.

6. Set up your payment pointer

You can't use your credit card and need a dedicated payment pointer to start receiving streaming payments. This is straightforward and well-described here Digital Wallet and Payment Pointers for each of the current wallet providers:

Once you have your pointer, simply save it to your personal profile.

You're ready to be read!

7. Readers can search for published works and start streaming

There is as little friction between reader and reading as possible. You don't need to login to start reading a work. You don't even need to pay for the initial pages. The app works for free, giving a reader the opportunity to anonymously try out the app, and your creative work.

A call to readers and writers

So ... there it is. I created Qwyre in part because of my frustration with app-based self-publishing services and my desire to read more African speculative fiction.

I you can write, please write. If you can edit, please edit. And if you can't do either, help me get this message out!

If you have any questions or concerns email me, or drop a comment in the chat. I would love your help in spreading the word and helping to draw out writers to Qwyre and web monetization. And I hope, soon, to be reading your work.

Qwyre.com — Converting a digital work into a monetized stream [Grant Report #1]

Gavin Chait — Mon, 03 Jan 2022 18:04:55 +0000

Projects are like London buses. You wait for hours, standing alone in the pouring rain at midnight freezing your important bits and wondering if you'll ever be warm again, when two come along together.

And so I found myself, six months ago, navigating two wonderful projects while hoping that I'd pull it off.

Gentle reader. Working 14-hour days, seven days a week, for six months, is not a healthy pursuit. Hence the break in these monthly reports. My apologies. But the last month has been well spent with an interim release for you to play with.

One of the most gratifying new features (for me, as a lazy person) is that you can paste a link to an epub and simply import direct into the app. And here a shout-out to Standard eBooks which are a wonderful community project reformatting public domain books into standards-compliant epubs.

If you're a self-published author and want to link to the app direct and don't want your readers to have to faff about, generate a link yourself:

Converting digital objects into digital streams

Web Monetization is a per-second payment stream and it requires a per-second product. Some things are naturals for this, and they're usually live or where the digital service is tightly linked to a platform. Text isn't normally streamed, but music and movies can easily be downloaded as well.

Streaming means deliberately breaking data into chunks and streaming those in a format that permits live, iterative, building of the digital object from these chunks while also serving the content in that dynamic object.

For text, that means a stream of words. Except they also have to carry markup so they're formatted properly on arrival. Then the page needs to be updated without offending the reader. It's not trivial.

For anyone else stuck with this, here is an exceptional Stackoverflow answer that details not just the high-level strategy, but also provides a great foundation in code.

Progress on objectives

The status as of the previous updates (1, 2, 3):

Convert docx into epub using Chapisha,
Read epub using Futurepress,
Monetize using Coil (and please do read my lengthy write-up on how to do this).

For this report, these additional features are complete:

Importing an *epub" for publication,
Agreeing, and signing, a contract with an editor,
Converting a work to a stream source,
Streaming the work in response to web monetization.

Preparation of a work for publication

There are plenty of ways independent authors can self-publish. That lack of any friction between the author and the reader is one reason so much is produced, and with such low quality. Commercially-published work benefits from the simple barrier of being edited. Just that surfaces poor prose and obscure, or irrational, storytelling.

Qwyre is about collaborative publication, so here's the workflow:

1. Start at your new creator's workshop

Here you'll find links to the docx convertor, as well as panels to review your works in progress, and offers for editors.

2. Import your epub, either during the docx conversion process or, if you've produced your epub in some other way, direct into the platform:

This is intended to be as easy as possible. If you've got an external link or a local file, either can be imported.

3. Review the work and check that metadata, the contents and sample text are presented as expected:

4. Prepare a contract with your revenue share between yourself and prospective editors. This is what will be shared between the author and editor during monetization.

Here's another reason to only permit publication after review by an editor. Here I'm attempting to claim authorship of 'The Magician' by W. Somerset Maugham. No, that should never be accepted. Any editor should catch that right away and refuse even to accept an offer to collaborate on the work in the first place.

5. Offline collaboration for publication is an important part of the creative process.

Only once both parties have agreed the contract, and agreed the work is ready for publication, can the creator release the work onto the platform.

6. Readers can search for published works and start streaming

7. Seamless call to monetization, and a judgement call ...

The sign-up process involves two steps:

Creating a Qwyre.com account
Creating a Coil.com subscription and linking that to Qwyre.com

One reason was to physically seperate Qwyre.com from monetization. The app itself stores nothing about monetization out of the browser. There's no account to delete or concern about data probity. Sure, not forcing the user to create an account would simplify sign-up. That way we only have to worry about the reader signing up with Coil.

However ... I need some way to keep track of where the reader has gotten to in streaming any work so that they are not double-charged for the same thing across multiple devices. That requires a login.

Once the reader has authenticated everything, they are still in complete control of the monetization process.

Development and monetization receipts ...

This is harder than it needs to be. There are no development APIs, so you're working with live Coil accounts, and the largest challenge is proving that you are getting paid.

Webmonetization offers a receipt verifier service. This is yet another third-party layer between your app and payment. Instead of embedding wallet pointers into your code, you now interpose a verifier endpoint: $receipt-verifier.example/%24wallet.example%2Falice

It's a complex requirement and immediately runs into CORS issues, meaning you'll need to implement this all yourself creating additional opportunities for broken/dangerous code.

Some recommendations I'd like to see:

We need some developer endpoints. I want to test out what happens when payments fail in various scenarios. This is hard to do with a live account.
The Web Monetization scripts returns a series of events. It would be tremendous if this included a receipt by default. If I want to implement my own receipts verifier, fine, but not having it here creates sequencing issues. Receipts need to be verified continuously for continuous payments. The more endpoints to pole, the more chance for glitches and delays.

What's next?

The last outstanding feature is the search engine. Once that is done, I'll release the final version. I also intend to run a demo with the African Speculative Fiction Society members and get some feedback on the work to date. The 2021 Nommo Awards were just announced so go find some African scifi to read.

What community support would benefit your project?

I'd appreciate thoughts and feedback on the publication workflow, as well as on the interim release at Qwyre.com.

Qwyre.com - A guide for integrating Coil & Web Monetization APIs for creatives doing the job once

Gavin Chait — Fri, 03 Sep 2021 17:46:05 +0000

There are two principle types of developer: journeymen and creatives. A journeyman gains experience through repetition. Overly-technical or complex documentation isn't a problem since the journeyman uses it more like landmarks. The creative coder is developing software as a means to express their idea. They know where they want to go but are covering the ground once.

This guide for integrating Coil & Web Monetization APIs is written for creatives.

Why implement the API? It is your responsibility - as creative - to ensure that your prospective subscribers and supporters can easily, and quickly, i) understand what it is that you are offering, and ii) pay for it in a way that is easy and doesn't scare them. You cannot rely on them to install a browser plugin for a technology they may never have heard of.

There is a secondary reason ... the API offers you more flexibility and creativity in what you can offer. It is more expressive.

Notes to the guide

Approach

The first step is to have a high-level understanding of exactly what needs to happen to authenticate a subscriber and authorise web monetization. This may feel like repetition, but that means we go through this twice. First to get a broad understanding, then into the technical detail and gotchas.

I recommend you follow along in the reference documentation (see References at the end), and this guide. This guide compliments the documentation and is not a substitute for it.

Development stack

I make the assumption you know how to code and that you know enough about best-practice in app development that I won't need to include everything. I provide most code required for implementation, but the tech stack is very specific:

Nuxt.js - A Vue.js framework, based on Node.js, for the Progressive Web App frontend,
FastAPI - A Python framework for building APIs, for the server backend.

The coding languages are TypeScript and Python with annotations (specifically Pydantic). These annotations ensure code consistency and reduce the number of gotchas.

The complete development stack is available as a Docker Compose base project generator:

whythawk / full-stack-fastapi-postgresql

Full stack, modern web application generator. Using FastAPI, PostgreSQL as database, Nuxt3, Docker, automatic HTTPS and more.

Gotchas

There are a LOT of gotchas. These will be presented as:

GOTCHA: a gotcha is an easy-to-miss detail, which - once overlooked - will cause you hours / days of lost time.

Consider this a first draft, and please do respond in the comments below if anything is unclear, or you see a better / more efficient way of doing things.

Let's get started.

Web Monetization is about `authentication` and `authorisation`

Your app is in the middle between your subscribers and Coil as monetization provider. Your objectives are authentication - prove who you are - and authorisation - prove you have authority to perform an action.

Your app needs to perform each of these tasks with each party.
You need to tool up your app so that it has the necessary credentials and scripts to perform these tasks.

There are four separate components you'll need to build:

Authenticate your app with Coil: you'll do this once for each app - a minimum of twice, for your development and production environments, and is largely a manual process with application via email and an online form,
Embed the OAuth Web Monetization (OWM) script in your app: again, once, as you develop your app,
Your subscriber authenticates your rights to their monetisation account: for each new subscriber,
Your subscriber authorises your right to monetize your content: for each subscriber, every time they permit monetization, and refreshed every 30 minutes.

This is how your subscriber will experience the process:

1. They visit your app

2. They decide to authorise your app to receive payments and click on a link you generate

3. They are referred to Coil where they must approve authentication.

4. Coil refers the subscriber back to a specific receiving page where your app needs to process the token it receives and authenticate.

5. Your app updates the subscriber and invites them to begin streaming.

Only one of these steps requires your subscriber to leave your app and make an active authentication decision. Thereafter, how you decide to start and stop monetization is up to you.

Now for the technical details.

1. Authenticate your app with Coil

At the end of this process you will have:

client_id,

client_secret converted to base64.

This is a strictly manual process and takes some time. Do it earlier rather than later.

Follow Coil's documentation to register your developer account, and email devs@coil.com,
It is normal to wait a week or more for them to respond, when they do, you will be able to register apps and request authentication tokens,

https://coil.com/oauth_register
- Client app name: qwyre-local
- Redirect URIs (comma-separated): https://localhost:3000, https://localhost:3000/support-us
- Logo URI: https://localhost:3000/qwyre-logo.svg
Make a note of the app registration details as they are not listed anywhere afterwards, and you must have them exact for the next step.

GOTCHA: before you decide on the redirect URI pause to think. This URI will become the most important page in managing this process, and it may not work for you if that page is root.

Once you receive your app authentication token from Coil, you will need to register with Coil's Open ID Connect (OIDC) provider to exchange the token for a client ID and client secret. You can do this from a bash command line.

Coil's documentation is relatively straightforward. Dig out the app registration terms you used above:

request:

curl -X POST https://coil.com/oauth/reg \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer Pb8w98v18ikkZyy26nxXK5OKDDsN6kfEJVmQ2id9tbC' \
  -d \
  '{
    "redirect_uris":["http://localhost:3000","http://localhost:3000/support-us"],
    "client_name": "qwyre-local",
    "tos_uri": "https://localhost:3000/privacy/",
    "policy_uri": "https://localhost:3000/privacy/",
    "logo_uri": "http://localhost:3000/qwyre-logo.svg"
  }'

GOTCHA: tos_uri and policy_uri must be https otherwise the request will fail. It doesn't matter whether your development environment is not certified (although you can issue yourself a self-signed certificate if you like). The end-points are not tested, only the form of the URI.

response:

{
  "client_id": "314ac134-fc3c-4d28-bf43-ccb75a2f9fb2",
  "client_secret": "uVE2t7y1QvyM78PlBA3aQAUh6syXVw7P2XBr4QDsS2yrkETR6al9YFpH4NDloXh5",
}

This is abbreviated, and is the only time you'll get this, so save these details somewhere safe. These are the only two keys you need (for now): client_id and client_secret.

GOTCHA: Not really a gotcha, since it's clearly flagged in the docs, however, before you can use your client_secret, you need to make the string web-safe since you will be sending this in your first GET request. That requires converting it to base 64. In Python, that's pretty easy:

import base64
base64.b64encode(bytes(client_secret, 'utf-8'))

Then use that string as your client_secret.

2. Embed the OAuth Web Monetization (OWM) script in your app

At the end of this process you will have:

Embedded Coil's OWM script in your app.

Coil describes this as a relatively straightforward process. It is not.

GOTCHA: the Coil OWM script does not play well with Nuxt.js and, I'm assuming, any Node-based JavaScript/TypeScript framework that performs server-side-rendering and hydration. If you don't know what this means, just be aware that this process is the source of many gotchas, not just when implementing web monetization.

Coil recommends you create a base index.html file as follows:

<html>
  <head>
    <meta name="monetization" content="$wallet.example.com/~alice">
    <script>
      if (document.monetization) {
        document.monetizationExtensionInstalled = true
      } else {
        document.monetization = document.createElement('div')
        document.monetization.state = 'stopped'
      }
    </script>
    <script src="https://cdn.coil.com/coil-oauth-wm.v7.beta.js" defer>
    </script>
  </head>
  <body>
    <p>Testing web monetization via coil polyfill using btp token.</p>
    <script>
      document.coilMonetizationPolyfill.init({ btpToken: 'e0y1...' })
    </script>
  </body>
</html>

You'll notice three important components:

The meta tag with the destination wallet for streaming payments,
A script tag with defer import of the OWM script,
And an if else statement setting up the div for interacting with document.monetization.

Something that I spent quite a bit of time frustrated by is that I couldn't interact with the OWM script in any way until after it had been initialised by creating that seemingly innocuous div. This has implications for the way Node interacts with the script.

The recommended way to include external / third-party scripts in Node is via a config.js file. For example:

// Global page headers: https://go.nuxtjs.dev/config-head
// https://vue-meta.nuxtjs.org/api/#script
// https://javascript.info/script-async-defer
head: {
    title: "Qwyre",
    meta: [
      { charset: "utf-8" },
      { name: "viewport", content: "width=device-width, initial-scale=1" },
      { name: "monetization", content: process.env.COIL_PAYMENT_POINTER },
      { hid: "description", name: "description", content: "" },
      { src: "https://cdn.coil.com/coil-oauth-wm.v7.beta.js", defer: true },
    ],
    link: [{ rel: "icon", type: "image/x-icon", href: "/favicon.ico" }],
}

Then you would initialise the script in your layout (base html templates to structure any pages). This does not work.

At this time, you need to bypass Node/Nuxt.js and initialise your app.html (ordinarily not customised, and left to the framework to manage):

    <!DOCTYPE html>
    <html {{ HTML_ATTRS }}>
      <head {{ HEAD_ATTRS }}>
        {{ HEAD }}
        <script>
            if (document.monetization) {
              document.monetizationExtensionInstalled = true
            } else {
              document.monetization = document.createElement('div')
              document.monetization.state = 'stopped'
            }
          </script>
          <script src="https://cdn.coil.com/coil-oauth-wm.v7.beta.js" defer></script>
      </head>
      <body {{ BODY_ATTRS }}>
        {{ APP }}
      </body>
    </html>

Even then, you will get some flaky responses. I am unclear as to whether this is normal, or related to the compromises.

3. Your subscriber authenticates your rights to their monetisation account

At the end of this process you will have:

Set up TypeScript interfaces for requests and responses,

Set up all API request code,

Set up a proxy for queries to Coil,

Store the refresh_token as a cookie, and access_token and sub in the store,

[Optional] Request your subscriber's personal information.

Maybe go get some coffee. This is going to get very technical, very fast.

Set up your TypeScript interfaces

It is very easy to get lost amongst the keys and their requirements. TypeScript interfaces permit us to define what data we need to request, and what we expect in response. These are documented over several pages, but we'll pool them all in one, then use them throughout what follows. It will make things easier.

Create ./interfaces/coil.ts:

    /* eslint-disable camelcase */

    export interface ICoilUserResourceRequest {
      response_type: string
      scope: string
      client_id: string
      state: string
      redirect_uri: string
      prompt: string
    }

    export interface ICoilUserResourceResponse {
      code: string
      state: string
      scope: string
    }

    export interface ICoilUserTokenRequest {
      code: string
      grant_type: string
      redirect_uri: string
    }

    export interface ICoilUserTokenResponse {
      access_token: string
      expires_in: number
      id_token: string
      refresh_token: string
      scope: string
      token_type: string
    }

    export interface ICoilUserTokenRefreshRequest {
      refresh_token: string
      grant_type: string
      scope: string
    }

    export interface ICoilUserTokenRevokeRequest {
      token: string
    }

    export interface ICoilUserInfo {
      email?: string
      sub: string
    }

    export interface ICoilUserBTP {
      btpToken: string
    }

That should be fairly readable. Interfaces for request are followed by a counterparty response. We make the request, we receive the response. It should all validate.

Set up all API request code

We'll go through this step-by-step ... I'm using Axios to make the requests.

1. Generate and present the referral URI to your subscriber

GOTCHA: While Coil states that you can refer the subscriber to either of a signup or login page, the reality is only login works. Note this for the prompt key in the API.

In Nuxt.js, create ./api/coil.ts:

import axios from "axios"
import {
  ICoilUserResourceRequest,
  ICoilUserTokenRequest,
  ICoilUserTokenResponse,
  ICoilUserTokenRefreshRequest,
  ICoilUserTokenRevokeRequest,
  ICoilUserInfo,
  ICoilUserBTP,
} from "@/interfaces"

export const coil = {

    getUserResource(coilState: string): string {
        // https://help.coil.com/docs/dev/get-oauth-auth#request-parameters
        // NOTE: currently the 'signup' prompt doesn't work
        // https://www.valentinog.com/blog/url/
        const getResourceURL = new URL(`${process.env.coilUrl}/oauth/auth`)
        const data: ICoilUserResourceRequest = {
          response_type: "code",
          scope: "simple_wm openid",
          client_id: (process.env.coilID as unknown) as string,
          state: coilState,
          redirect_uri: `${process.env.baseUrl}/support-us`,
          prompt: "login",
        }
        for (const [key, value] of Object.entries(data)) {
          getResourceURL.searchParams.append(key, value)
        }
        return getResourceURL.href
    }

}

GOTCHA: coilState is a really important token you will use to ensure you can trust the response from Coil (i.e. no spoofing of your website by sending random scripts to your processing page). Effectively, you generate a random string, send that to Coil along with your request, then Coil sends it back. It is YOUR responsibility to validate the state you receive as being identical to the one you sent. I generate these as UUIDs:

In frontend create ./utilities/keys.ts:

function generateUUID(): string {
  // Reference: https://stackoverflow.com/a/2117523/709884
  // And: https://stackoverflow.com/a/61011303/295606
  return "10000000-1000-4000-8000-100000000000".replace(/[018]/g, (s) => {
    const c = Number.parseInt(s, 10)
    return (
      c ^
      (crypto.getRandomValues(new Uint8Array(1))[0] & (15 >> (c / 4)))
    ).toString(16)
  })
}

You will call and use the generated URI in your redirect_uri page script.

In frontend, redirect processing page ./pages/support-us.vue:

this.coilRequestURI = coil.getUserResource(this.coilState)

And then use this to generate the "Sign in with Coil" button:

<a class="mt-9" :href="coilRequestURI"
  ><SvgIcon terms="w-56 h-10" icon="svgCoilWhite"
/></a>

Note: you defined which page you want Coil to return the subscriber's response as redirect_uri. It is this page where all the following processing will take place. Mine is ./pages/support-us.vue.

GOTCHA: You can't make requests from the frontend. You run straight into Cross-Origin Resource Sharing (CORS) errors where the requests and / or responses are blocked. You need to proxy your requests. This is especially painful if you were hoping for a Single-Page Application, or a static app.

Fortunately, I'm using FastAPI on the backend so it's relatively straightforward to set it up to proxy requests. We'll do that in the next section, so for here just note that the URIs for axios.post and axios.get are being requested from the backend, not Coil.

2. Receive and use response token to request subscriber authentication keys

The coil redirect will return to your response page, along with query terms in the path. It may look something like this:

response:

https://example.com/
?code=CU6LG36vKvVmUbF9QWFwj7F5zvY
&state=b5f1872f-9d32-5f31-819d-5a4daeab4ea9
&scope=simple_wm openid

First, parse this to extract the parameters and then send this for processing. I'm using the Nuxt Store to manage browser state.

In frontend, in redirect processing page ./pages/support-us.vue:

if (
  this.$route.query.code &&
  this.$route.query.state &&
  this.$route.query.scope
) {
  const payload: ICoilUserResourceResponse = {
    code: this.$route.query.code as string,
    state: this.$route.query.state as string,
    scope: this.$route.query.scope as string,
  }
  await this.getUserToken(payload)
}

The asyncronous await to getUserToken populates the store and triggers the cascade of authentication requests we need. In ./store/monetization/actions.ts:

async getUserToken({ commit, dispatch }, payload: ICoilUserResourceResponse) {
    if (getCoilState() !== payload.state) {
      await commit("setRequestError", true)
    } else {
      try {
        try {
          const response: AxiosResponse = await coil.getUserToken(payload.code)
          const data: ICoilUserTokenResponse = response.data
          await commit("setCoilToken", data.access_token)
          saveCoilRefresh(data.refresh_token)
        } catch (error) {
          await dispatch("checkCoilError", error)
        }
      } catch (error) {
        await dispatch("checkCoilError", error)
      }
    }
}

This requires a request to the coil API, and then we save the authentication token to the store, and the refresh token as a persistent cookie in the subscriber's browser.

This is the critical self-validation call to ensure that the response you receive is valid and from Coil:

if (getCoilState() !== payload.state) ...

Here is the next api call to Coil to pass back the token you received and exchange it for your subscriber's authentication and refresh tokens:

await coil.getUserToken(payload.code)

Back to ./api/coil.ts and pop this into the export:

async getUserToken(coilCode: string) {
    // https://help.coil.com/docs/dev/post-oauth-token/index.html#request-an-access-token-for-an-authenticated-user
    const data: ICoilUserTokenRequest = {
      code: coilCode,
      grant_type: "authorization_code",
      redirect_uri: `${process.env.baseUrl}/create`,
    }
    return await axios.post<ICoilUserTokenResponse>(
      `${process.env.apiUrl}/api/v1/coil/proxy/oauth/token`,
      data,
      requestHeaders()
    )
}

This is a post and you pass your app's authentication keys to Coil in the header:

requestHeaders()

That function is included in ./api/coil.ts:

function requestHeaders() {
  const token = btoa(`${process.env.coilID}:${process.env.coilSecret}`)
  return {
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Basic ${token}`,
    },
  }
}

GOTCHA: Note again that you're escaping your two keys, client_id and client_secret, as base64. Here using btoa. I don't know if this was just me, but I found that I had to do this 'twice'. I first converted client_secret to base64, then generated a new base64 string on the result btoa(client_id:client_secrect_base64).

Coil returns a response json object.

response:

{
  "access_token": "eyJhbGciOi...JSUzI1NfsQ",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUz...I1NiIsInR5",
  "refresh_token": "dzfKQUEFYXEZ2~WKq5t0atT36X~",
  "scope": "simple_wm", "openid",
  "token_type": "Bearer"
}

Store the `refresh_token` as a cookie, and `access_token` and `sub` in the `store`

This access_token authenticates you to request a BTP token which is what you need to begin streaming money. This token is only valid for an hour, and so I don't bother storing it in a persistent cookie, leaving it in the store. However, the refresh_token is valid indefinitely and so you need to take care with it.

ETHICS: You may be tempted to store this refresh_token in your database. DO NOT DO SO. It doesn't belong to you. It belongs to your subscriber. Should they wish to revoke your use of that token, it should never be a request to your database. They should have the power to simply clear their browser cookies.

Request your subscriber's personal information

Optional: Depending on how your app works, you may want your subscriber's personal information (user id and/or email). This is a separate request. It is not needed to authorise streaming.

In the store ./store/monetization/actions.ts:

async getUserInfo({ commit, dispatch, state }) {
    try {
      const response: AxiosResponse = await coil.getUserInfo(state.coilToken)
      const data: ICoilUserInfo = response.data
      await commit("setCoilSub", data.sub)
    } catch (error) {
      await dispatch("checkCoilError", error)
    }
}

Back in ./api/coil.ts:

async getUserInfo(accessToken: string) {
    return await axios.get<ICoilUserInfo>(
      `${process.env.apiUrl}/api/v1/coil/proxy/user/info`,
      requestUserHeaders(accessToken)
    )
}

GOTCHA: you are using both a new API endpoint for this request, as well as a new header. https://api.coil.com, and this header:

function requestUserHeaders(accessToken: string) {
  return {
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Bearer ${accessToken}`,
    },
  }
}

Where accessToken is the access_token you received from getUserToken.

In addition, your request to getUserInfo is a get request. That's a minor change here, but a big change on your proxy.

response:

{
  "sub": "22028a7c-b720-7a3e-4387-6c9845f6201b",
  "email": "alice@coil.com"
}

Set up a `backend` proxy for queries to Coil

As described earlier, all of the API calls in the Nuxt frontend are proxied to the FastAPI backend.

The way this works is, your frontend interacts with the subscriber and manages the monetization state. It then sends any queries it has direct to the server and immediately refers back any responses. It stores nothing and remembers nothing.

Python code follows, using HTTPX as the http client.

ETHICS: You'll see that, while your subscriber is anonymous (as are their payments), control over when to charge them and how to do so is not actually in their control. It's entirely in yours. That means you have to deliberately - from the beginning - make it easy to NOT ABUSE YOUR SUBSCRIBER. The only way you can do that effectively is if you resolve never to store any auth keys anywhere near your backend, but leave them entirely in your subscriber's browser. This is the reason we only proxy at the backend and not manage the entire process.

What follows is longer than it needs to be because of yet another gotcha.

GOTCHA: Coil's API has two inconsistencies. The first is that not all requests are POST. There is one GET. The second is that not all requests are to the same URI. It switches from https://coil.com to https://api.coil.com. You need to account for this in your proxy.

Create ./app/api/api_v1/endpoints/coil.py:

    from typing import Any
    from fastapi import APIRouter, HTTPException, Request, Response
    import httpx

    from app.core.config import settings


    router = APIRouter()
    # https://coil.com
    coil_uri = settings.COIL_URI
    # https://api.coil.com
    coil_api_uri = settings.COIL_API_URI


    # FOR POST
    @router.post("/proxy/{path:path}")
    async def proxy_post_request(*, path: str, request: Request) -> Any:
        # https://www.starlette.io/requests/
        # https://www.python-httpx.org/quickstart/
        # https://github.com/tiangolo/fastapi/issues/1788#issuecomment-698698884
        # https://fastapi.tiangolo.com/tutorial/path-params/#__code_13
        try:
            URI = coil_uri
            if path.startswith("user/"):
                URI = coil_api_uri
            data = await request.json()
            headers = {
                "Content-Type": request.headers["Content-Type"],
                "Authorization": request.headers.get("Authorization"),
            }
            async with httpx.AsyncClient() as client:
                proxy = await client.post(f"{URI}/{path}", headers=headers, data=data)
            response = Response(content=proxy.content, status_code=proxy.status_code)
            return response
        except Exception as e:
            raise HTTPException(status_code=403, detail=str(e))

    #FOR GET
    @router.get("/proxy/{path:path}")
    async def proxy_get_request(*, path: str, request: Request) -> Any:
        try:
            URI = coil_uri
            if path.startswith("user/"):
                URI = coil_api_uri
            headers = {
                "Content-Type": request.headers.get("Content-Type", "application/x-www-form-urlencoded"),
                "Authorization": request.headers["Authorization"],
            }
            async with httpx.AsyncClient() as client:
                proxy = await client.get(f"{URI}/{path}", headers=headers)
            response = Response(content=proxy.content, status_code=proxy.status_code)
            return response
        except Exception as e:
            raise HTTPException(status_code=403, detail=str(e))

That's all you need on the server, but let me give you a little context and explanation.

@router.post("/proxy/{path:path}")

FastAPI uses types and Pydantic to annotate variables. What's going to happen here is that all the text after path is going to be treated as a path type and provided as a variable to the function. We then use httpx to make a new post to Coil. Note, though, how we have to account for the gotcha of shifting endpoints.

URI = coil_uri
if path.startswith("user/"):
    URI = coil_api_uri

Then we regenerate our headers, get any data from the request in json/dict format, and proxy using httpx:

data = await request.json()
async with httpx.AsyncClient() as client:
    proxy = await client.post(f"{URI}/{path}", headers=headers, data=data)

GOTCHA: Coil response codes are a little unclear. The only failure code is a 403 request failure. You do get some text to explain the error, and you can send that back to the app, but I found it often quite obscure. It wasn't always clear what I had done wrong, or what wasn't working.

4. Your subscriber authorises your right to monetize your content

At the end of this process you will have:

Authorise your rights to monetize a subscriber,

Initialise your web monetization stream, and specify a destination wallet,

Refresh streaming tokens as required,

Stop / Revoke streaming in response to your subscriber's wishes.

Authorise your rights to monetize a subscriber

A btpToken - which is a promise to fulfill a payment request, not payment in and of itself - is only valid for 30 minutes. There is no point in generating one until your subscriber actually expresses their intention to stream money to your wallet.

You'll need some sort of "start" / "stop" UX on your app, and the Web Monetization Foundation has a great set of docs that explain exactly this. You can review those after this section. First we use the subscriber's authentication token to request a BTP token.

In the frontend store ./store/monetization/actions.ts:

async getUserBTP({ commit, dispatch, state }) {
    try {
      const response: AxiosResponse = await coil.getUserBTP(state.coilToken)
      const data: ICoilUserBTP = response.data
      await commit("setBtpToken", data.btpToken)
    } catch (error) {
      await dispatch("checkCoilError", error)
    }
}

Back in frontend ./api/coil.ts:

async getUserBTP(accessToken: string) {
    return await axios.post<ICoilUserBTP>(
      `${process.env.apiUrl}/api/v1/coil/proxy/user/btp`,
      {},
      requestUserHeaders(accessToken)
    )
}

There's no point in storing the token outside of the store. It is valid for only 30 minutes from the time of issue, whether it is used or not.

GOTCHA: the request to get the btpToken is both in camel-case, and a post. It also has no data to send in post, so ensure you include an empty object: {}. It also uses https://api.coil.com. Both the request to get user info, and BTP token are the only requests to this root endpoint.

response:

{
  "btpToken": "eyJhbGciOiJCchQ8...SeOz98I2Sqyf1LrVM"
}

Now you have a btpToken, but possession of a token is not money. That still needs to happen in the next process.

Initialise your web monetization stream, and specify a destination wallet

We'll start with the gotcha.

GOTCHA: The challenge of websites is also the purpose of JavaScript web frameworks, like Node. To manage, and persist, state. The more you can persist between state changes (shifting between different web pages) the more a website can feel like a native application. A Progressive Web App is all about near native user-experience. Problem is, the current Coil OWM script does not seem to expect this. Their documentation expressly states "Add the following code to the <body> section of each page you are monetizing.":

<script>
    document.coilMonetizationPolyfill.init({ btpToken: 'USERS_TOKEN_HERE' })
</script>

Doing that in a Node app, though, will instantly crash your app during transitions since this is exactly the sort of state that Node will preserve. That means initialising the coilMonetizationPolyfill needs to look like this on every page:

if (
  process.client &&
  Object.prototype.hasOwnProperty.call(document, "coilMonetizationPolyfill")
)
  try {
    document.coilMonetizationPolyfill.init({ btpToken: this.btpToken })
  } catch (error) {}

In words: check that your script will execute only client-side, and that the coilMonetizationPolyfill has been initialised, and then try/catch to initialise it with the btpToken.

I created a single "start" / "stop" component to listen to subscriber instructions.

In frontend ./components/monetization/MenuToggle.vue:

public setMonetizationTag() {
    // https://github.com/Techgethr/webmonvuejs/blob/main/index.js
    // https://webmonetization.org/docs/start-stop/
    const monetizationTag = document.querySelector('meta[name="monetization"]')
    if (!monetizationTag && this.coilPointer) {
      const meta = document.createElement("meta")
      meta.name = "monetization"
      meta.content = this.coilPointer
      document.getElementsByTagName("head")[0].appendChild(meta)
    }
    if (monetizationTag && !this.coilPointer) {
      monetizationTag.remove()
    }
}

ETHICS: The way that the OWM script "listens" to whether or not a valid BTP token should be used to stream payments is whether or not there is a metatag pointing to a wallet. You end streaming payments by removing the pointer. Everyone, from your subscriber, to Coil, to the Web Monetization Foundation and Grant for the Web are relying on you to honour your subscriber's intentions and expressed instructions.

When your subscriber tells you to stream, you add the wallet pointer:

if (!monetizationTag && this.coilPointer) {
  const meta = document.createElement("meta")
  meta.name = "monetization"
  meta.content = this.coilPointer
  document.getElementsByTagName("head")[0].appendChild(meta)
}

And when they tell you to stop, you remove it:

if (monetizationTag && !this.coilPointer) {
  monetizationTag.remove()
}

That's the entirety of your subscriber's protection from abuse of their trust in you. That you MUST honour their instructions and delete the wallet pointer. Please - and I know I'm whispering in a thunderstorm - please don't abuse this.

Refresh streaming tokens as required

"Start" and "Stop" is equivalent to a call to check the validity of a token, and refresh them as required.

In the same frontend component ./components/monetization/MenuToggle.vue

public async toggleMonetizationStreaming() {
    if (!this.isStreaming) await this.startMonetizationStream()
    else await this.stopMonetizationStream()
    this.setMonetizationTag()
}

This is in response to the subscriber toggling a button in the menu bar of the app.

It is your responsibility to check that a BTP token is still valid. A JWT token intrinsically contains the time it was created, so you can easily check.

In frontend ./utilities/keys.ts:

function getTimeInSeconds(): number {
  // https://stackoverflow.com/a/3830279/295606
  return Math.floor(new Date().getTime() / 1000)
}

function tokenExpired(token: string) {
  // https://stackoverflow.com/a/60758392/295606
  const expiry = JSON.parse(atob(token.split(".")[1])).exp
  return getTimeInSeconds() >= expiry
}

And then on to the frontend store, where we manage monetization state ./store/monetization/actions.ts:

  async startMonetizationStream({ commit, dispatch, state }) {
    await dispatch("refreshUserBTP")
    if (!state.requestError) {
      await commit("setIsStreaming", true)
      await commit("setCoilPointer", process.env.coilPointer as string)
      await commit(
        "main/addNotification",
        {
          content: "You have started web monetization.",
          color: "success",
        },
        { root: true }
      )
    }
  }

Refreshing the BTP token triggers a cascade of requests. I felt there was no point in worrying about the difference between an authentication_token valid for 60 minutes, and a btpToken valid for 30. Just refresh both of them.

In the frontend ./store/monetization/actions.ts:

async refreshUserBTP({ commit, dispatch, state }) {
    if (getCoilRefresh()) {
      try {
        const response: AxiosResponse = await coil.getUserRefresh(
          getCoilRefresh() as string
        )
        const data: ICoilUserTokenResponse = response.data
        // https://stackoverflow.com/a/32108184/295606
        if (
          data &&
          Object.keys(data).length !== 0 &&
          data.constructor === Object
        ) {
          await commit("setCoilToken", data.access_token)
          saveCoilRefresh(data.refresh_token)
          if (!state.requestError) {
            await dispatch("getUserBTP")
            await commit("setRequestError", false)
          }
        } else {
          await commit("setRequestError", true)
        }
      } catch (error) {
        await dispatch("checkCoilError", error)
      }
    } else {
      await commit("setRequestError", true)
      await commit(
        "main/addNotification",
        {
          content: "Error authorising web monetization.",
          color: "error",
        },
        { root: true }
      )
    }
}

You'll note that there are profoundly numerous points in the process where things can go wrong and try / catch is triggered.

With the frontend api request in ./api/coil.ts:

async getUserRefresh(refreshToken: string) {
    const data: ICoilUserTokenRefreshRequest = {
      refresh_token: refreshToken,
      grant_type: "refresh_token",
      scope: "simple_wm openid",
    }
    return await axios.post<ICoilUserTokenResponse>(
      `${process.env.apiUrl}/api/v1/coil/proxy/oauth/token`,
      data,
      requestHeaders()
    )
}

With that you can get your BTP token, as described above.

Stop / Revoke streaming in response to your subscriber's wishes

Technically, all that's required to stop the process is to remove the wallet pointer in the metatag.

In the frontend ./store/monetization/actions.ts:

async stopMonetizationStream({ commit }) {
    await commit("setIsStreaming", false)
    await commit("setCoilPointer", "")
    await commit(
      "main/addNotification",
      {
        content: "You have stopped web monetization.",
        color: "success",
      },
      { root: true }
    )
}

Cascading back up the code, you call this.setMonetizationTag() which removes the metatag pointer.

From the frontend component ./components/monetization/MenuToggle.vue

if (monetizationTag && !this.coilPointer) {
  monetizationTag.remove()
}

Revoking is slightly more convoluted. If a subscriber revokes, you need their authentication_token to perform the action. However, their token may no longer be valid, so you may need to first refresh their token and only then revoke your access to their keys.

In the frontend ./store/monetization/actions.ts:

async revokeMonetization({ commit, dispatch, state }) {
    await dispatch("stopMonetizationStream")
    if (state.coilToken) {
      await coil.revokeUserResource(state.coilToken)
      await commit("setCoilToken", "")
    } else if (getCoilRefresh()) {
      // Counterintuitively, we need a new user_token to request the revoke
      try {
        const response: AxiosResponse = await coil.getUserRefresh(
          getCoilRefresh() as string
        )
        const data: ICoilUserTokenResponse = response.data
        if (
          data &&
          Object.keys(data).length !== 0 &&
          data.constructor === Object
        )
          await coil.revokeUserResource(data.access_token)
      } catch (error) {
        await dispatch("checkCoilError", error)
      }
    }
    if (getCoilRefresh()) removeCoilRefresh()
    await commit(
      "main/addNotification",
      {
        content: "You have successfully revoked web monetization.",
        color: "success",
      },
      { root: true }
    )
}

With the frontend api request in ./api/coil.ts:

async revokeUserResource(token: string) {
    const data: ICoilUserTokenRevokeRequest = {
      token,
    }
    return await axios.post(
      `${process.env.apiUrl}/api/v1/coil/proxy/oauth/token/revocation`,
      data,
      requestHeaders()
    )
}

There is no response to a revoke request. However, remember we adopted an ethical design approach. If our subscriber has deliberately cleared their cookies, we no longer have access to their refresh_token anyway, and so no longer have access to their account.

And that's it (so far). There's more we can do ... split payments (proportionally specifying which wallet pointer is monetized), opening up sections of your app to streaming subscribers, etc. All of that requires a rock-solid payment process, and I hope this guide helps save you at least some time and frustration in achieving that.

Please let me know in the comments what you think, what I missed, and what can be fixed / improved.

References

For both this guide, and for those of you wishing to go further and add things like scheduled token refresh, proportional payments, etc.

Qwyre.com - What does a minimum lovable product even look like?

Gavin Chait — Tue, 10 Aug 2021 16:20:12 +0000

One of the management-speak fads of the last decade has been the minimum viable product which, instinctively, we probably all know is wrong. It leaves us with scaffolding and dodgy wiring. Made things that are difficult to use, fail easily, and add to the noise and clutter of the world.

They can be important early steps, but they're difficult to "love". And, if what we want is people to switch to wanting to use what we make, we need to offer at least a modicum of enjoyment to these fledgling efforts.

This approach is the minimum lovable product. Unlike MVP, MLP doesn't seem to have an established parent, but the earliest visual representation of this I can find is from Jussi Pasanen:

// Detect dark theme var iframe = document.getElementById('tweet-515301088660959233-135'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=515301088660959233&theme=dark" }

Henrik Kniberg, writing in 2016, presented a more visual way or representing this:

Problem is, this implies you know what all of these intermediate things are when all you've got is this wheel you invented. Except ... none of us invented a wheel in a world of pedestrians. We're iterating on what exists.

In the case of Qwyre, that means there are already many ways to convert a document to an epub, and multiple ways to publish them. I know what my iteration looks like at the end, but I want an interim release, and that release needs to be useful.

Useful to me so I can get feedback and test how webmonetization works in production, but definitely useful to people so that they want to give me that feedback in the first place.

Originally, I thought I'd go as far as releasing an epub converter and call that interim.

The more I sat with that, though, the less enjoyable that became. The process of conversion is easy-enough, and the design - while interim - is inoffensive. I'm a professional writer, and this is also a tool I'd like to use.

But ... my workflow, using my own app, was:

Generate the epub,
Download it,
Import it into Calibre,
Check that it looks ok.

That's a lot of effort, and distinctly displeasing. I can't ask anyone else to struggle that way.

I decided that the interim app needs to have a functioning ereader. But you can't have a MVP ereader in this here 2021. It has to be an ereader. Which led me to the rabbit-hole of Epub.js, still the only mostly-functioning open-source browser-based ereader library:

futurepress / epub.js

Enhanced eBooks in the browser.

There is documentation, but no actual developer manual, and definitely no tutorials. The API appears to have changed without notice, so what works in other packages doesn't work anymore. It's a bit tedious. I'm also a little nervous as to how large it is, but I'll see how that goes once I get to the build point.

A large-scale digression over the last five weeks means this is possible:

The app is a Progressive Web App, and I'm using IndexedDB to store data in the browser to make the user-experience truly offline. You can store all your epubs in the app, just like a real reader, and it is fully mobile responsive, meaning swipes and taps work as well.

My workflow now is:

Upload and convert a doc to epub,
Read my epub...
Get lost importing and reading other ebooks.

Which is the way it's supposed to be.

The app itself works fine for release, but I still want to get basic webmonetization implemented, and then it should be ready to deploy for interim release. I've just picked up another project, so I'm going to be delayed for a few weeks, but hopefully by early September.

One thing I'd like to know, though (for those who read this far) ... what is your favourite ereader app (not device), and what features makes it special for you?

Qwyre.com - a framework for ethics and technical development in fiction publishing

Gavin Chait — Wed, 30 Jun 2021 17:53:26 +0000

Two months after my dad died, I was sitting on a beach in the Philippines writing my first novel. My dad's passing was expected. My writing trip long-planned. It's the sequence that wasn't the one I had hoped.

I wrote 2,000 words a day for a month, and, when it was done, the orbital prison of Tartarus and the remote Nigerian village of Ewuru were real.

Lament for the Fallen

Isolated and with his orbital city hiding in the rubble of a devastating war, Samara falls 35,000km to escape from the space-based prison of Tartarus, smashing into the jungle near an isolated Nigerian village. Struggling to heal, and hunted by a brutal warlord in a ruthless land, Samara searches for a way home to the woman he loves.

I never expected an agent or publishing contract, didn't want to rely on Amazon, and so I rolled my own. Within a few months, my long-term software roadmap became moot when Penguin Random House picked up LAMENT for publication. The world of creative self-publishing stops at the border of formal publication.

turukawa / whyqd

Whyqd is an extensible object-based wiki bringing revision control, content presentation, forking and embedding to any type of digital object.

A publishing house must have a list of titles, each within a set of genres conforming to the topics in the average bookshop. They make their money off their handful of giants, and do little to promote or develop the careers of their mid-list writers. You are expected to promote your own work, but you can't sell your own work. Twitter ok. Experimental self-publishing definitely not.

The challenge with lists and genres is that success is a game of whack-a-mole. Success leads to copycats, leads to perpetuation of specific norms. For African writers, this has meant we need to conform to an industry notion satirised by Binyavanga Wainaina in his frustrated guide on How to Write About Africa:

Never have a picture of a well-adjusted African on the cover of your book, or in it, unless that African has won the Nobel Prize. An AK-47, prominent ribs, naked breasts: use these. If you must include an African, make sure you get one in Masai or Zulu or Dogon dress.

A continent of 54 countries, countless ethnicities, and over a billion people reduced to a cartoon cameo in the mid-list.

A framework for African collaborative publishing

Umumtu ngumuntu ngabangtu

The African philosophy of Ubuntu can be summarised as "I am because we are." As I writer, I am both reader and writer because there are other writers. There is no line between writer and reader just as there is no line between genres, stories and influences.

Qwyre starts with the following simple principles:

All Qwyre users are creators,
A creator can perform any task of:
- Reading,
- Writing,
- Editing,
- Curating.
The path to publication requires appointing an editor and letting them decide when a creative work is ready,
Editors and curators are first-class citizens in the creative process and should be paid,
An forum of peers is there to resolve disputes,
Popularity can be gamed and is no guide to what a reader may enjoy,
All writers should have an equal shot at being read.

In practice, this implies moderated publication. There is no gatekeeping. We do not assign an editor and decide who gets published. All we require is that a writer recruit and appoint an editor, and that their editor gets to decide when their work is ready for publication. This will require an appeals process, and so we need an editors forum.

This leads to the following structured components to support a Qwyre workflow:

EPUB generator: convert a .docx file to a standards-compliant .epub,
Editor recruitment: manage the recruitment and contractual agreement between a writer and editor,
eReader: an online standards-compliant EPUB reader,
Web monetisation: books can be read by streaming and, once paid for via monetisation, can be downloaded as an epub,
Editor's forum: a formal review process to permit dispute resolution between writers and their editors,
Curation: create lists of works which can be shared and promoted,
Search and discovery: a neutral, automated method to categorise and assess creative works to support reader discovery.

At this time, given the diverse needs of writers and their preferred ways of working, Qwyre will not offer any online editing or writing support. These are to take place offsite.

Where possible, components will be released as free-standing apps as they are developed. The most immediately obvious of these are the EPUB generator, and the ereader app.

Nuxt.js and FastAPI as our technical stacks

Qwyre will be a progressive web app (PWA) with offline support for the reader's library of ebooks. Books can be bought as epubs, or streamed via web monetisation. What a reader "buys" via web monetisation, they own. Once they have streamed an entire book, they are able to download an epub version of the work.

I have developed on Django for years and enjoyed it, and its documentation. Recently, however, I've wanted to try something new and more in line with my current standards-based approach to data curation. Python's support for types has evolved, and the most modern and mature framework for working with Pydantic is FastAPI which comes with a Docker base project with PostreSQL and Vue.js. I didn't want to faff too much with Vue, and set out to produce a version for Nuxt.js (which is to Vue what Next is to React) as well as replacing Vuetify with Tailwind for the user interface design.

whythawk / nuxt-for-fastapi

Nuxt.js frontend drop-in replacement for Vue.js FastAPI base project generator.

This provides a solid starting point for further development.

Current development: Chapisha and EPUB Generator PWA

Chapisha provides an intuitive method for converting a well-formatted Microsoft Word .docx file into a standards-compliant EPUB3 ebook. I developed the standalone Python package to support a Nuxt.js progressive web application.

whythawk / chapisha

Python-based docx to standards-compliant epub3 conversion

The core functionality for the EPUB convertor is almost complete.

Next up is to work with Coil's web monetisation API and test streaming payments to support EPUB conversion. The specific mechanism is that:

A creator provides all the content and metadata required to generate an EPUB in the PWA,
Data only transfer from the creator to the Qwyre server during the generation process,
During generation, they can stream payments to support the app,
Streaming is monitored directly using websockets giving the creator feedback on the generation process, and costs,
On completion, all creator data is deleted from the server and returned to the creator.

I'm hoping to complete this in mid-July and deploy a test server with the EPUB generator for public testing and use by the end of July 2021. In my next update, I'll hopefully have a link for you to go test what I built so far.

I'm keen on feedback and discussion, so please get in contact and let me know your thoughts or concerns.

The Interledger Community 🌱: Gavin Chait

Hop Sauna social marketplace framework — ILF Ambassador Final Report

Project Update

Supporting African creators

Hop Sauna release

Progress on Objectives, Key Activities

Goal 1: deliver a template developer stack ready for custom creation of creator community-moderated Open Payments-enabled web shop

Goal 2: develop marketplace tools for facilitating buyer and seller exchanges, including for webhooks for responding to successful purchases, disputes and refunds

Goal 3: kick-start cooperative creator marketplaces through engaging with stakeholders to align the template stack with their needs, and to develop a supportive environment for project sustainability

What impact does the project have on your perception of digital financial inclusion?

Project Impact & Target Audience(s)

Communications and Marketing

2025 Interledger Summit Mexico City

2025 Interledger Hackathon Mexico City

Podcast

What's Next?

Hop Sauna extension

Qwyre for self-publishing

Community Support

Hop Sauna — ILF Ambassador Progress Report

Project Update

Progress on Objectives, Key Activities

What impact does the project have on your perception of digital financial inclusion?

Project Impact & Target Audience(s)

Communications and Marketing

What's Next?

Community Support

The battle between the Commute and the Community, or the strangeness of online monopolies

What does a webshop need to do?

Why is federation necessary to compete with monopolies?

Hop Sauna, a social marketplace framework - introduction and roadmap

'Empathy' - new African speculative fiction by Cheryl Ntumy on Qwyre.com

Qwyre.com - What we learned, and our ethical foundations and plans for future development [Grant Report #2]

Makers are not speculators. Risk is not theirs to take.

Making monopolised proprietary lock-in impossible

Patience and the new

Qwyre launches its first web-monetized African speculative fiction short-story competition

Publishing your work on Qwyre.com

Prepare your work for publication

A call to readers and writers

Qwyre.com — Converting a digital work into a monetized stream [Grant Report #1]

Converting digital objects into digital streams

Progress on objectives

Preparation of a work for publication

Development and monetization receipts ...

What's next?

What community support would benefit your project?

Qwyre.com - A guide for integrating Coil & Web Monetization APIs for creatives doing the job once

Notes to the guide

Approach

Development stack

whythawk / full-stack-fastapi-postgresql

Full stack, modern web application generator. Using FastAPI, PostgreSQL as database, Nuxt3, Docker, automatic HTTPS and more.

Gotchas

Web Monetization is about authentication and authorisation

1. Authenticate your app with Coil

2. Embed the OAuth Web Monetization (OWM) script in your app

3. Your subscriber authenticates your rights to their monetisation account

Set up your TypeScript interfaces

Set up all API request code

Store the refresh_token as a cookie, and access_token and sub in the store

Request your subscriber's personal information

Set up a backend proxy for queries to Coil

4. Your subscriber authorises your right to monetize your content

Authorise your rights to monetize a subscriber

Initialise your web monetization stream, and specify a destination wallet

Refresh streaming tokens as required

Stop / Revoke streaming in response to your subscriber's wishes

References

Qwyre.com - What does a minimum lovable product even look like?

futurepress / epub.js

Enhanced eBooks in the browser.

Qwyre.com - a framework for ethics and technical development in fiction publishing

turukawa / whyqd

Whyqd is an extensible object-based wiki bringing revision control, content presentation, forking and embedding to any type of digital object.

A framework for African collaborative publishing

Nuxt.js and FastAPI as our technical stacks

whythawk / nuxt-for-fastapi

Nuxt.js frontend drop-in replacement for Vue.js FastAPI base project generator.

Current development: Chapisha and EPUB Generator PWA

Web Monetization is about `authentication` and `authorisation`

Store the `refresh_token` as a cookie, and `access_token` and `sub` in the `store`

Set up a `backend` proxy for queries to Coil