One wallet across every app and agent · 04_credit_token_platform/CREDIT_PLATFORM.md

Qal Credit — Token & Credit Platform Across qalarc Apps

Parent doc: 03_qals_architecture/QALS_ARCHITECTURE.md • Date: 2026-09-06

1. Problem

qalarc's apps (qalarc.com AI services, tradez.au, doof.ing, endispute.com.au, agent hub, compute rig) each need: user balances, metered billing (AI calls, compute seconds), subscriptions, refunds, payouts to partners, and eventually cross-app credit. Classic SaaS billing (Stripe per-app) is expensive, siloed, and cannot express machine-to-machine payments (agent pays agent, agent pays GPU rig) — the exact case IOTA was invented for.

One ledger, one token, every app. QALS is prepaid service credit; the chain is the shared source of truth.

2. Model: three kinds of "money" on Qalnet

Credit-tier NFTs (see 08_nft_strategy/) sit on top: membership tiers that unlock discounts/limits — the "Zip Pay tier" analogue without being consumer credit.

3. Core Move contract: qal_credit

/// One per user (or agent), created lazily on first top-up.
public struct CreditAccount has key {
    id: UID,
    owner: address,              // bound to a Qal ID DID-controlled address
    balance: Balance<QALS>,      // escrowed prepaid credit
    tier: u8,                    // 0 free / 1 plus / 2 pro / 3 whale (NFT-gated)
    spend_cap_epoch: u64,        // rolling epoch spend cap (agent safety!)
    spent_this_epoch: u64,
    created_ms: u64,
}

/// Pre-authorisation object: like a "card pre-auth" for a job/call.
public struct Hold has key {
    id: UID,
    account: ID,
    amount: u64,                 // max estimated cost, held (not spent)
    expires_at_ms: u64,          // auto-release — no orphaned holds
    purpose: String,             // "llm-call", "gpu-job-123", ...
}

/// Subscription stream: constant drip from account → treasury per epoch.
public struct Subscription has key {
    id: UID,
    account: ID,
    rate_per_epoch: u64,         // QALS/epoch
    app: String,                 // "qalarc.ai", "tradez", ...
    active: bool,
}

Flows: - Top-up: user buys QALS (fiat via Phase-2 exchange path, or earns via compute/airdrop) → CreditAccount balance. - Metered call (AI inference): app backend → place_hold(account, est_cost) → run inference → settle(hold, actual_doofs) (difference released). Identical to how petrol stations pre-authorise cards. On-chain this is 2 small objects, gas sponsored by Qal Pass. - Subscription: Subscription drips per epoch; pausing/cancelling is one object mutation. No external billing provider. - Agent spend: every agent's CreditAccount has a hard spend_cap_epoch — an AI agent literally cannot exceed its allowance, enforced by the chain, not by prompt engineering. This is the killer feature for agentic commerce. - Refund/reversal: settle with negative delta or treasury-signed refund tx; every reversal is an on-chain audit event.

4. Metering: the qal_meter service + price oracle

• Each app runs a small meter agent (the qalarc hub pattern — same infra as the Signal/WhatsApp hub) that meters usage (tokens, seconds, GB, jobs) and co-signs settle() txs.
• Price table is an on-chain shared object PriceTable { service_key: String -> doofs_per_unit: u64 }, updated by treasury multisig — prices are public and auditable, changes are events users can subscribe to.
• Units are normalised into doofs (10⁻⁹ QALS): 1M-token LLM context ≈ X doofs; 1 GPU-hour ≈ Y doofs; 1 GB anchored ≈ Z doofs. Everything becomes comparable → one wallet pays for everything.

5. Cross-app experience

"Exchange system usable across applications and smart device systems" (user's words) = exactly this: Qal ID (who) + CreditAccount (wallet) + PriceTable (what things cost) + Qal Pass (no gas UX) + QR/deep-link (POS-like UX) + Hierarchies caps (device/agent limits). Any new qalarc app plugs into the same four contracts on day one.

6. Credit (deferred credit, Zip-style) — Phase 3

Phase 1 is strictly prepaid (no credit risk, minimal regulation). Phase 3 (after 06_bank_exchange/ licensing path) adds:

• Qal Instalments: "buy now, pay over 4 fortnights" for large service invoices, priced in QALS — Zip Co's model ported to service credits. Requires Australian Credit Licence work; do not pre-announce.
• Reputation object: ReputationScore — a non-transferable object (soulbound-style) recording on-time settlement history on-chain. Feeds underwriting; never sold, only proven via zero-knowledge or selective disclosure (BBS+ VCs — see 09).
• Credit line object: CreditLine { limit, drawn, apr_basis_points } with per-epoch interest accrual executed by the chain (Move makes this a 10-line function; try that in Stripe).

7. Treasury & flywheel

 users/apps pay fiat or compute ──► Treasury mints/allocates QALS
        │                                   │
        ▼                                   ▼
  services consumed ──► doofs burned as fees ◄── Qal Pass sponsors gas
        │                                   │
        ▼                                   ▼
  compute providers earn QALS ──► spend on services ──► (loop)

• Service revenue is real revenue regardless of QALS price (it's prepaid credit).
• Treasury burns a slice of consumed doofs → deflationary pressure as usage grows (usage > speculation, the IOTA lesson).
• Liquidity for "cash-out" only via licensed path (Phase 2+), keeping Phase 1 clean.

8. Rollout

1. Now: deploy qal_credit on qalnet-dev-1; wire metering into ONE app (agent hub's LLM calls are the easiest — we already proxy them).
2. +2w: PriceTable + dashboards; airdrop pilot allocation to internal testers.
3. +6w: tradez + doof integrations; QR payment links.
4. +3m: external users (closed beta, identity-gated), compute settlement live.
5. Later: qAUD bridge, instalments (licensed), device POS pilots (a "smart device" here can be as small as a Raspberry-Pi kiosk with a QR screen).