Reference
What it does
The settlement module turns metered usage into money. Provider daemons collect per-workload resource metrics on an hourly cadence, batch them into signed usage records, and submit them on-chain (MsgRecordUsage). The module validates records against their leases and converts them into billable line items priced by the lease terms.
Every reported record sits in a 24-hour dispute window during which either party can raise corrections — anomaly detection on the provider side flags outliers before they ever reach the chain. After the window closes, line items settle against lease escrow and the agreed funds transfer to the provider at the full agreed amount. Reconciliation against platform metrics (default every 6 hours) cross-checks reported usage.
Why it exists: Metering and billing are where cloud customers get hurt and providers get stiffed. Making settlement a consensus function — signed records, public dispute window, automatic escrow release — replaces invoice trust with protocol guarantees for both sides.
State
Primary objects
| Concept | Definition |
|---|---|
Usage record | A signed, per-lease report of metered resource consumption for a collection period. |
Dispute window | The 24-hour period after reporting during which corrections can be raised. |
Line item | A priced billing entry derived from a validated usage record. |
Messages
Messages & queries
Message and query surfaces are documented at implementation level in the module docs ↗ and the source ↗. The objects above are the state those messages create and transition.
Connections
Module interactions
Flows
Core flow
- Collect — Daemons meter hourly. Per-workload resource metrics gathered on schedule and reconciled against platform metrics every 6 hours by default.
- Submit — Signed records go on-chain. Batched usage records are validated against their leases and priced by lease terms into billable line items.
- Dispute — The window opens. Twenty-four hours for corrections from either party; fraud and support paths engage on escalation.
- Release — Escrow pays out. Cleared items transfer the agreed funds to the provider — full amount, no platform deduction.
Questions
Asked about x/settlement
What is a usage record?
A signed, per-lease report of metered resource consumption for a collection period — the atomic unit of marketplace billing.
What is a line item?
A priced billing entry derived from a validated usage record — the thing escrow actually releases against.
How are anomalies caught before payout?
Provider-side anomaly detection flags outliers before submission, reconciliation cross-checks reported usage every 6 hours by default, and the 24-hour dispute window gives both parties a final correction pass.
Related