Why kangoh, and why now?
Breaches take what you keep
Member records from years ago, a points ledger nobody uses. What attackers walk off with is what was left there. What you do not hold cannot leak.
Small shops are dropping their points
The duty to protect member data and the cost of an app are closing loyalty programs. A program with nothing to protect and nothing to maintain can stay open.
No terminal needed at the shop
No special terminal, no member system. With ordinary receipts and a check once a day, a shop can start shared points with its neighbours.
How it works, in three minutes
Take a shopping street where a bakery, a café and a bookshop share a program. No shop needs a special terminal.
A purchase, and a photo of the receipt
After spending 1,850 yen at the bakery, the customer photographs the ordinary receipt with an app on their phone. Only the shop, the time, the receipt number and the total are read; the photo and the items bought are not sent. Each claim uses a fresh key, so claims cannot be linked to each other or to a person. A receipt counts once: the first claim wins.
The shop confirms once a day
After closing, the bakery lists the day’s claims, checks them against its sales and approves them together. Approval signs 18 points with the bakery’s key, and they reach the customer. Duplicate claims are set apart as errors from the start. A shop whose till prints a signed QR on its receipts does not even need this step.
It is spent at another shop
At the café, the phone presents the points. It can use 9 of the 18; the operator issues the other 9 as change and they go back to the phone. The café checks that the bakery really issued them, that they belong to this phone’s owner, that they have not expired, and that they have not been used, and does nothing for the change. Points already spent are known on the spot, so they cannot be used twice.
The operator settles at month end
The operator matches every shop’s ledger (points issued, points taken) and works out what the bakery owes the café. When the change is spent later at another shop, the bakery, which issued the original points, pays for it too. The shop that approves a claim pays for it, so approving claims that are not its sales gains it nothing.
What is kept, and what is not
Not kept
- Customers’ names, phone numbers, e-mail
- Who bought what, where and when
- Receipt photos or the items bought
- Member numbers or a member app
Kept
- The shop’s signing key (its stamp on a voucher)
- A ledger of vouchers issued and taken (amounts and times only)
- The vouchers it took, as the basis of its claim
- The operator’s desk: the number, time and total of each receipt claimed, and the outcome. Only outcomes are published, with receipts as keyed hashes
If a shop’s whole ledger leaks, what comes out is when vouchers of what value moved. Nothing else.
Compared with a conventional program
| Conventional shared points | kangoh | |
|---|---|---|
| Sign-up | Required (name, contact) | None. A key |
| What a shop needs | A terminal, a till integration | Its ordinary receipts, and a phone or computer for the daily check |
| Customer data a shop must protect | Member database, purchase history | None |
| App on the customer’s side | The program’s own app | A wallet app with no sign-up, holding each street’s points apart |
| Preventing a double spend | A central server, instantly | Checked at the moment of use; matched again at settlement |
| Using part of the points | Deducted from a balance | The shop takes what is used; the operator issues the rest as change |
| Systems to run | A member platform and servers | A published program file, a small claims desk, a monthly settlement |
| Cost structure | Fees and breakage | Software is free (Apache-2.0); run it yourself or with help |
What you need to run it
By role, here is what each party holds and runs. The only thing that runs all the time is the operator’s small service, which is both the claims desk and the registry.
The operator (a street association, a guild)
- Publish the program: one file (JSON) naming the shops and their keys, how points are earned (one point per 100 yen, say) and their validity, placed anywhere on a website
- Run one small service: the desk that takes customers’ receipt claims and passes them to the shops, the registry of points already spent, and change when part of the points is used. None of it holds anything about anyone (included in kangoh; runs on a small server)
- Hold one key for change: change only splits points a shop issued, and the operator’s key cannot create points (settlement would find them)
- Publish the outcomes: claims, refusals as duplicates, issues and rejections, as a deedlog evidence trail, so customers can check how their claim was handled
- Settle monthly: collect the shops’ ledgers, run kangoh’s settlement, and fix what each shop pays and receives
A shop
- Print receipts as usual. Nothing changes at the till
- Once a day, check the day’s claims against the sales in kangoh’s shop tool on a phone or computer, and approve them together. Duplicates are set apart as errors
- A shop whose till prints a signed QR on its receipts skips the check
- When a customer refused as a duplicate brings the real receipt, issue the points at the counter
- Keep the shop folder (signing key, ledger, points taken) and a backup of the key
A customer
- Photograph the receipt, or scan its QR, with the phone app (the app is in development; for now it can be tried with an AI agent that speaks MCP)
- Points arrive by the next day, once the shop has checked; a receipt with a QR does not wait
- No sign-up; nobody asks for a name or contact. A lost device loses the points
In the current version
Now
- Points from receipts: the claims desk, first-claim-wins duplicates, the shop’s daily check, signed receipt QRs
- Presenting and redeeming points, using part of them with change, and matching for settlement
- An MCP server and a command line for each role: shop, wallet, operator
- A double use refused at the counter, and an evidence trail of claim outcomes in deedlog’s format
Next
- A phone app that only photographs receipts, with keys kept by passkeys
- Signed QRs printed by existing tills
- A shop app that makes the daily check quick
- A site where customers can check their claim’s outcome
For developers
- Install
npm install -g kangoh. Node.js 20 or later.- What a voucher is
- A Verifiable Credential as an SD-JWT: signed by the issuing shop, bound to the customer’s key (cnf), presented with a key-binding JWT.
- Receipts
- With earn in the program (one point per 100 yen, say), a voucher’s value follows the receipt’s total. The operator’s desk (
kangoh registry --program) takes claims; shops check and approve withkangoh receipts; a till makes the signed QR withkangoh receipt-qr. - Change
- A presentation may name the points used and a fresh key for the rest; the registry issues the rest with the operator’s key. Change names the original voucher and its issuer, and settlement accepts only the exact rest of a voucher redeemed in part, to the key the holder named, once.
- Settlement
- Every shop’s ledger in time order; each voucher paid once, for the points used, to the first shop that recorded it. Every redemption not paid is reported with its reason.
- Registry
- The operator’s registry holds the digests of vouchers taken; a shop asks it before taking one. If it cannot be reached, the shop takes the voucher and leaves a double use to settlement.
- Ledger
- An append-only record per shop, matched by the operator. Claim outcomes are recorded in deedlog’s format, ready to checkpoint, cosign and publish.
- AI agents
- For a future where AI agents shop online unattended, there are MCP servers for the wallet, the shop and the operator.
- Licence
- Apache-2.0. On GitHub and npm.
- Related
- shinten keeps delivery addresses and enquiries sealed from the shop. A sister project with the same idea: hold nothing.
Talk to us
Program design for a shopping street, a trade association or a small local economy; printing QRs on receipts and connecting online shops; running the claims desk and the monthly settlement. The software is free. What costs is design and integration.
What you send is used only to answer you, and is not stored on this site. See the privacy policy.