Escrow & Settlement
Payments on VirtEngine are usage-driven: tenants fund an escrow account up front, but money only moves to providers after signed usage records survive a dispute window and settle on-chain.
Escrow accounts
Section titled “Escrow accounts”When a tenant creates a deployment, they deposit funds into an escrow
account managed by x/escrow. The escrow account:
- backs every lease formed under the deployment,
- is drawn down only by settled usage, and
- can be topped up at any time; when it empties, the lease closes.
This protects both sides: providers know funded capacity is real, and tenants never grant a provider direct pull access to their wallet.
The settlement pipeline
Section titled “The settlement pipeline”The provider daemon runs a settlement pipeline that connects metered usage to on-chain billing. Its cadence is configurable; the defaults are:
| Setting | Default | Meaning |
|---|---|---|
settlement_interval | 1 hour | How often pending usage is processed into settlements |
dispute_window | 24 hours | Time tenants have to dispute a usage record |
reconciliation_interval | 6 hours | Cross-validation against platform metrics |
max_pending_records | 100 | Backlog size that triggers early settlement |
Usage records are submitted on-chain in signed batches (MsgRecordUsage),
then settled by x/settlement into billable line items once the dispute
window has elapsed and no dispute is open.
Disputes and corrections
Section titled “Disputes and corrections”A tenant who believes a record is wrong can dispute it inside the window.
Dispute lifecycle: Created → Pending → Reviewing → Resolved / Rejected / Expired. Key guarantees:
- usage cannot be settled while a dispute on it is open;
- accepted disputes produce corrections — new usage records that reference the original rather than silently rewriting history;
- dispute evidence is immutable once recorded.
Reconciliation and discrepancy handling
Section titled “Reconciliation and discrepancy handling”Settled usage is cross-checked against independent platform metrics (the reconciler compares provider container/volume/GPU metrics with platform-side component usage). Discrepancies escalate by size:
| Difference | Severity | Action |
|---|---|---|
| 0–5% | Low | Log only |
| 5–10% | Medium | Alert generated |
| 10–25% | High | Alert + review |
| >25% | Critical | Settlement blocked |
Provider payout
Section titled “Provider payout”At payout, x/escrow transfers the full agreed lease amount to the provider
in VCC. There is no settlement take-rate or platform deduction. Network
transaction fees apply separately to on-chain messages. The issuance model is
covered in Settlement & BME.
Operator commands
Section titled “Operator commands”Neither forcing a settlement nor listing disputed escrows is available
from the CLI today. virtengine query escrow is the reachable group
(accounts, payments).