Esta página solo está disponible en inglés. La versión en inglés es la que prevalece.
How MZG escrow and the 20% provider lock work
A walk through MZGridEscrow and ProviderRegistry: the job state machine, the settlement arithmetic with real numbers, the invariants we fuzz, why we chose a lock over staking, and exactly how slashing is bounded.
Elena Varga
Ingeniería del protocolo
Every job on MZGrid moves money through two contracts on Base: MZGridEscrow, which holds the customer's deposit, and ProviderRegistry, which holds each provider's locked collateral. Neither contract is upgradeable, and both are small enough to read in one sitting. This post explains how they fit together and why they are shaped the way they are.
Design goals
We started from three requirements:
- A customer can never be charged more than they deposited, and can always get their money back if the job never starts or is never settled — without asking us.
- A provider who misbehaves has something to lose, and the amount at risk grows with the value of the jobs they take on.
- The trusted part is as small as possible. Someone has to attest to how long a job ran. Today that is the coordinator's settlement oracle. The contracts should make sure that oracle can only choose among bounded outcomes.
The escrow state machine
A job is identified by a bytes32 jobId generated by the coordinator. Its lifecycle looks like this:
None ──createJob──▶ Funded ──acceptJob──▶ Running ──completeJob──▶ Completed
│ │
├─ cancelJob ─▶ Cancelled ├─ failJob ────────▶ Failed
│ (client, after 10 min) │ (oracle, full refund)
└─ failJob ───▶ Failed └─ reclaimTimeout ─▶ Reclaimed
(oracle, full refund) (client, after deadline + 1 h)The functions map one-to-one onto the transitions:
createJob(jobId, provider, pricePerHour, maxDuration, specHash)pullspricePerHour × maxDuration / 3600MZG from the client. It requires that the provider is active in the registry and that the deposit does not exceed the provider's job cap.createJobWithPermitdoes the same with an EIP-2612 signature instead of a prior approval.acceptJob(jobId)can only be called by the named provider, and only withinACCEPT_WINDOW = 10 minutesof funding. It setsdeadline = now + maxDurationand tells the registry the provider has an active job.cancelJob(jobId)lets the client walk away with a full refund if the job is stillFundedafter the accept window.completeJob(jobId, usedSeconds, resultHash)is the settlement call, restricted toORACLE_ROLE.failJob(jobId, reason)is the oracle's way to abort a job; it always refunds the full deposit.reclaimTimeout(jobId)is the client's escape hatch: if a running job has not been settled bydeadline + TIMEOUT_GRACE(one hour), the client takes the full deposit back. This is the guarantee that matters most if the coordinator ever goes away.
Settlement arithmetic
Here is the core of completeJob, simplified:
uint256 charged = Math.min(job.deposit, uint256(job.pricePerHour) * usedSeconds / 3600);
uint256 fee = charged * FEE_BPS / 10_000; // FEE_BPS = 700 (7%)
uint256 providerShare = charged - fee;
uint256 lock = providerShare * LOCK_BPS / 10_000; // LOCK_BPS = 2000 (20%)
uint256 liquid = providerShare - lock;
uint256 refund = job.deposit - charged;Two details are deliberate. First, charged is clamped to the deposit, so even an oracle bug that reports an absurd usedSeconds cannot take more than the customer put in. Second, every rounding step rounds down and the remainder goes to the next party: providerShare is whatever is left after the fee, and liquid is whatever is left after the lock. That means the five outputs always sum to exactly the deposit, down to the last wei.
A worked example
A customer rents an H100 SXM at 750 MZG per hour with a four-hour maximum. They stop the job after 2 hours, 30 minutes and 12 seconds (9,012 seconds).
| Step | Formula | MZG |
|---|---|---|
| Deposit | 750 × 4 | 3,000.000 |
| Charged | 750 × 9,012 / 3,600 | 1,877.500 |
| Protocol fee (7%) | charged × 0.07 | 131.425 |
| Provider share (93%) | charged − fee | 1,746.075 |
| Locked in registry (20%) | share × 0.20 | 349.215 |
| Paid to provider now (80%) | share − lock | 1,396.860 |
| Refunded to customer | deposit − charged | 1,122.500 |
(Figures are exact here; on-chain everything is in wei.) Fee, lock, liquid and refund add up to 3,000 MZG — the full deposit. All four transfers happen in the same transaction, and the JobCompleted event carries every one of them, so indexers never have to recompute anything.
The provider lock
The 349.215 MZG in that example does not go to the provider's wallet. The escrow transfers it to ProviderRegistry and calls addLock(provider, amount). From then on it sits in the provider's locked balance.
The lock has exactly one way out: the provider calls requestExit(), which moves them to Exiting and records the time. After EXIT_DELAY = 10 days, and only once they have no active jobs, they can call withdrawLocked() and receive the whole balance. During those ten days the provider can no longer receive new jobs, but they can still be slashed for anything that happened before or during the exit. The delay exists precisely so that a provider can't abandon a job and immediately pull their collateral.
The job cap
The lock also determines how large a job a provider may take:
function jobCap(address provider) public view returns (uint256) {
return BASE_JOB_CAP + CAP_MULTIPLIER * providers[provider].locked; // 25e18 + 4 × locked
}A brand-new provider has nothing locked, so they can only accept jobs with deposits up to 25 MZG. A provider with 1,000 MZG locked can take deposits up to 4,025 MZG. The multiplier of four is a judgement call: high enough that an honest provider's cap grows quickly, low enough that the worst-case abandonment slash (two times the deposit, see below) remains meaningful relative to the lock for most jobs.
Why a lock instead of staking?
We considered the usual design — providers buy and stake tokens up front — and rejected it for three reasons.
- It turns hardware owners into token buyers. Requiring an up-front stake means a provider has to acquire MZG before they have earned any. That is a barrier for exactly the community operators we want, and it pushes them toward market exposure they did not ask for.
- Collateral should track risk. A staked amount is fixed when you stake it. A lock that grows with completed work scales naturally with the size and number of jobs a provider handles, and the job cap ties the two together explicitly.
- There is no yield to explain. Locked MZG earns nothing. It is not a deposit in a pool, it does not pay a reward, and it is not a governance weight. It is collateral, full stop. That makes it much easier to reason about — for providers and for us.
The trade-off is that a new provider has very little at stake. The 25 MZG base cap is what limits the damage they can do while their lock is small.
Slashing
Slashing lives in the registry, behind SLASHER_ROLE, which is held by the coordinator's verifier:
function slash(address provider, uint256 amount, bytes32 jobId, uint8 reason, address client) external;The amount is always capped at the provider's locked balance. Half goes to the affected client and half to the treasury (if there is no affected client, everything goes to the treasury). The verifier applies three rules:
| Reason | Trigger | Slash amount |
|---|---|---|
| 1 · Abandoned | Accepted job not completed by its deadline | min(locked, 2 × job deposit) |
| 2 · OfflineDuringJob | No usage report for more than 10 minutes while running | min(locked, 1 × job deposit) |
| 3 · VerificationFailed | Canary output mismatch or other proven fraud | 100% of locked |
Slashing always happens after the job has been failed, and failJob already refunds the full deposit. So in the abandonment case with a 3,000 MZG deposit and a provider who has 26,500 MZG locked, the customer gets their 3,000 MZG back from the escrow, plus half of the 6,000 MZG slash (3,000 MZG) from the registry. The treasury receives the other 3,000 MZG.
The details of how each trigger is detected are in Slashing; a follow-up post will cover the verification side.
Invariants we test
The test suite has unit and fuzz tests for every function, but the tests we lean on most are three invariants that a stateful fuzzer checks after every random sequence of calls:
- Conservation: the sum of all MZG balances (clients, providers, treasury, escrow, registry) never changes. Nothing is minted, nothing disappears.
- Escrow solvency: the escrow's MZG balance always equals the sum of deposits of jobs in
FundedorRunning. - Registry solvency: the registry's MZG balance always equals the sum of all providers'
lockedbalances.
The fuzzer's handler deliberately calls functions in the wrong state, from the wrong account, with zero and maximum values, and warps time across the accept window, the deadline, the grace period and the exit delay. Those three properties have held across every run. We target full line coverage on all three core contracts.
Importante
Tests are not an audit. The contracts have not been through an independent security audit, and the settlement oracle is operated by MZGrid Labs. The risk disclosure and Security pages describe what that means in practice.
What the oracle can and cannot do
To close, here is the trust boundary in one list. The settlement oracle can choose usedSeconds for a running job, fail a funded or running job, and (via the slasher role) slash a provider within the rules' caps. It cannot charge more than a deposit, redirect a refund to anyone but the client, move locked MZG anywhere except to the affected client and the treasury, or prevent a client from reclaiming a timed-out job.
The full function and event reference is on the contracts page, and the code is on GitHub. If you find something that looks wrong, please write to [email protected] before posting it publicly.
