Skip to content

Tokenised usage billing — design notes for on-chain settlement

Gaiastra already meters usage precisely: every call transaction is recorded, reconciled and attributable to a tenant. That is most of the work of a billing ledger. The on-chain phase asks a narrower question: what should live in a smart contract, and what should stay in PostgreSQL?

Keep the meter off-chain, settle on-chain

Raw usage events are high-volume and private. They stay in the platform's database. What goes on-chain is the settled result: periodic usage totals per tenant, signed by the platform, and the token transfers that pay for them. The contract's job is to make settlement verifiable, not to store call records.

Constraints that decide the design

  • Idempotent settlement. A settlement for a period must be applied exactly once. The contract keys settlements by tenant and period and rejects duplicates — the same rule the off-chain reconciliation already enforces.
  • Reconcilable both ways. Every on-chain settlement references a hash of the off-chain usage report, so an auditor can re-derive the total from the database and compare.
  • Upgrade path without migration pain. ERC-20 for the usage token, a separate settlement contract, and no business logic in the token itself.
  • Security first. Access control on settlement submission, pausability, and a test suite in Hardhat/Foundry that mirrors the platform's existing 1,393-test discipline.

Why this matters beyond telephony

Any platform that meters something — API calls, storage, energy, trades — has the same shape. The hard part is not the contract; it is having usage data you can already reconcile to the cent before you put a hash of it on-chain.