The magic explained: problem → how → analogy → where to see it · content/how_it_works.md
How It Works — the magic, explained
Eleven pieces, each with the problem it solves, how it works, one everyday analogy, and where to see it for real.
1. The wallet app
The problem. Your money, your chats and your computer-hire live in three different places, and none of them show the same balance.
How it works. Qal Wallet is a desktop app with three tabs: Chat, Payments and Compute. All three tabs read the same balance, so the number is always the number. Keys (the secrets that control your money) never leave your machine. The phone web app repeats the basics in a browser.
The analogy. It's the one remote control for the whole house — lights, telly and heater, one drawer.
Where to see it. platform_apps.md · run it with cargo tauri dev in the wallet-app guide.
2. Chat with money in it
The problem. Normal chat apps can read your messages, and money sent "in chat" is really a promise on someone else's database.
How it works. Messages are sealed (encrypted) on your device before they leave it, and only the recipient's device can open them. The relay — the postman in the middle — carries sealed envelopes it cannot read. An envelope can carry credit as well as words, so a message and its payment arrive together.
The analogy. A sealed envelope posted through a stranger's letterbox: the postman can deliver it but can't read it — and there can be cash inside.
Where to see it. qalchat/DESIGN.md · bash qalchat/test_chat.sh.
3. Spend caps
The problem. An AI agent (or a compromised app) with a wallet can drain it in minutes, and "please behave" is not a safety system.
How it works. Any account can carry a hard daily limit, and the owner sets it — caps are optional and uncapped by default (owner policy 2026-09-12). When a cap is set, the ledger enforces it — not the software asking nicely. When the limit is reached, payment refuses, full stop. Identity can also be revoked in about two seconds, cutting an agent off entirely.
The analogy. A staff card with a daily limit: even if it's stolen, the thief gets today's allowance, not the account.
Where to see it. bash loopd/demo.sh · use_cases.md (capped agent wallets).
4. Escrow: pre-authorise, then settle
The problem. Paying upfront for a job means trusting the worker to finish; paying after means the worker trusts you.
How it works. Before a job, the ledger places a pre-authorisation (hold) — money marked "reserved" but not yet taken. The job runs. Afterwards the exact amount settles against the hold and the rest is released automatically. (Older docs call this a "Hold" — same thing.)
The analogy. A escrow pre-authorisation: the pump reserves a chunk of your card first, then the real amount settles when you're done.
Where to see it. POST :8823/hold → POST :8823/settle · use_cases.md (escrow as a service).
5. The compute market
The problem. Renting a stranger's GPU means paying a stranger and hoping the job actually ran properly.
How it works. Providers register and post a stake (a bond they lose if they cheat). Your job's payment sits in escrow while the machine works and signs its log. The metered result settles the escrow; a failed or faked job bounces the money back and slashes the bond. Every job leaves a receipt.
The analogy. Like a courier with a bond: the parcel money is held by a third party and only paid when the tracking log says "delivered".
Where to see it. qmarket/README.md · bash qmarket/test_market_v2.sh.
6. The API-token exchange
The problem. Selling access to an API (say, an AI service) means either handing out your secret key or building a billing system.
How it works. The seller's secret credentials stay sealed on the server, never shown to buyers. Buyers get their own qk_ keys that draw from a prepaid balance. Usage is metered from the upstream response and charged exactly, via pre-authorisation holds. Resale of prepaid third-party credit uses the same escrow, so the credential is never pooled.
The analogy. A valet key: it starts the car for the one trip you approved, and can't open the boot or the glovebox.
Where to see it. qalkeys/README.md · qalkeys/mock_upstream.py demo.
7. Points and claims
The problem. Reward points scatter across five apps, five databases, and none of them turn into anything spendable.
How it works. Any platform can award points to one wallet handle with a signed message. The user gets a single-use claim link that expires and only works for the awarded handle — a stolen link is worthless. Claimed points become real credit in the wallet, and the claim record is anchored (stamped into the shared record).
The analogy. A coat-check ticket: single-use, and only the person with the ticket gets the coat back.
Where to see it. qalclaim/README.md · bash qalclaim/test_qalclaim.sh · release_and_points.md.
8. Redemption — services only
The problem. Turning credit back into value is where prepaid systems break their own rules — and trip over law.
How it works. Credit is redeemed for services only in this phase — there is no cash-out gate. One spread, one story (Pricing): you bought at about AU$1.20, and 1 Qal redeems AU$1.00 of services value. When a redemption runs it goes through one gate: qalredeem — the gate checks the rules, settles the service value, retires the credit, and anchors the receipt. Everything else in the system spends; only the gate turns credit into service value. (Cash return arrives only in the licensed phase — planned 0.5%, licence-gated, not live.)
The analogy. The till at the shop: the gift card is checked, the rules are applied, and the machine — not the assistant — decides.
Where to see it. qalredeem/README.md · bash qalredeem/test_qalredeem.sh · GET :8835/report.
9. Identity: DIDs
The problem. Apps need to know who is acting — and increasingly that "who" is an AI agent or a machine, which has no login form.
How it works. Every person, agent and device gets a DID — a decentralised identifier, which is a self-owned ID card whose proof is cryptographic, not a password. Devices can sign challenges (prove-you-own-this-id tests). Identity is revocable in about two seconds, so a fired agent is locked out everywhere at once.
The analogy. An employee ID card that cannot be faked — and the bouncer checks the card, not the story.
Where to see it. qalid/README.md · bash qalid/test_identity_v2.sh · identity_architecture.md.
10. Anchoring receipts
The problem. "Trust us, this file/answer/invoice hasn't been changed" is a promise, not a proof.
How it works. For any file or job, the system computes a fingerprint (a sha256 hash — a short digital thumbprint of the content). The fingerprint is stamped into the chain with a timestamp: that's an anchor. Later, anyone can re-compute the fingerprint and check it against the stamp — any tampering shows. The file itself never goes on-chain; only the thumbprint does.
The analogy. A receipt stamp on a parcel: it doesn't prove what's inside, but it proves the parcel existed at that moment, in that state.
Where to see it. qalpipe/ (anchor / verify / tamper-test) · the live view at the Loom.
11. The chain itself
The problem. One database means one owner can quietly edit it; a shared record needs a way to agree on what happened without a referee.
How it works. Qalnet is a small private blockchain — a shared notebook many machines hold copies of, where new pages only stick if the validators (the witness machines) agree. Nobody can tear out a page or sneak one in. Fees on it are sponsored, so users pay nothing (see ground truth F16). It carries the rules the whole system depends on: on-chain cap code is written and tested (qal_reserve — the on-chain twin is being redesigned from mint-gated to genesis-preminted + transfer-gated at the cap-raise checklist), while live cap enforcement is the loopd rail today — chain migration is on the cap-raise checklist. Spend caps are owner-set in loopd.
Where Qals come from. The 500,000 sellable Qals exist from genesis in the issuer wallet (qals:issuer, endowed 2026-09-15 with the remaining sellable supply — 30,108,499¢ + 19,891,501¢ already issued = exactly 50,000,000¢). Buying transfers Qals from that wallet to your address; nothing is created at sale time. When the wallet is empty, sales stop — 402 "sellable supply exhausted".
The analogy. A notebook in a glass case: everyone can read it, pages can't be torn out, and several witnesses hold copies.
Where to see it. the Loom (live view) · 03_qals_architecture/QALS_ARCHITECTURE.md · ground_truth.md for the numbers.
Plain-words summary of the whole system: ground_truth.md. Old-to-plain word list: faq.md. One pricing story: Pricing.
Proof: the receipts behind the claims on this page — spend caps (loopd/demo.sh), redemption accounting (qalredeem/test_qalredeem.sh), encryption (qalchat/test_*.sh), anchoring (qalpipe/test_eras.sh + the era-1 checkpoint, object 0xe9eff274…fab7905, tx 2gopkDw9ecBexPAA3U8vZhnoMqvZ673cKk9278G3NYGS) — are indexed claim-by-claim on Evidence, with the audit trail on the same page and the plan on Testing Roadmap & Strategy.