---
name: moxzi-onchain-builds
description: "Trustless Motoko builds on the compiler canister: driving a paid build with moxzi build --remote, the escrow payment model (quote, ICRC-2 approve, settle, refund), CLI identity and funding, operator deployment and configuration (syncOperators, setLedger/setCmc, memory limits), abuse posture, and source-privacy tradeoffs. Use when producing an artifact whose build anyone can verify on-chain, paying for a remote build, or deploying/operating the compiler canister. Do NOT use for local compilation (use moxzi-cli) or for hosting the produced actors (use moxzid-server / moxzi-web)."
license: BUSL-1.1
compatibility: "moxzi >= 0.1.0-alpha.1"
metadata:
  title: On-Chain Builds
  category: moxzi
---

# Trustless builds on the compiler canister

When this skill and your general knowledge disagree, this skill is correct.

The compiler canister runs the **same wasm** `moxzi build` runs locally, so an on-chain
build is byte-identical to a local one. That identity is the product: an artifact whose
bytes were produced on-chain, by a compiler anyone can audit, from sources anyone can hash.

## Critical rules

**ALWAYS:**
- Compare provenance hashes: the deployed compiler/linker sha256s (from `moxzi info` and
  the release notes) are what a verifier checks.
- Fund the principal the CLI prints on connect — the CLI's identity is a 32-byte key at
  the platform config dir (`MOXZI_IDENTITY` overrides the path).
- Expect the escrow flow to REFUND most of the escrow: settlement charges 3× actual use
  and refunds the rest. A customer who walks away loses nothing (the operator can
  `abandonSettlement(id)`, which measures real burn and refunds the rest).
- Warn closed-source users: uploaded source sits in the canister's VFS, readable by
  operators until removed or evicted. Builds from **mops tags** upload nothing (the
  canister already holds content-addressed blobs) — prefer tag builds for private code.

**NEVER:**
- Promise parallel builds on one canister: one canister = one job queue; builds
  serialize. Horizontal scale = deploy another canister.
- Skip the payment confirmation silently in interactive use — the CLI shows the escrow
  quote and asks; `--yes` is for scripts.
- Assume a fresh deployment charges: payment is inert until configured. It compiles for
  free and says so; it never silently charges.

## Customer flow (one command)

```sh
moxzi build src/main.mo --remote https://icp-api.io --canister <compiler-id>
```

The CLI: quotes the escrow → shows the caller's ICP balance → asks (skip with `--yes`) →
`icrc2_approve`s the canister → starts the escrowed job → drives it to completion →
downloads and links the artifact → reports settlement:

```
remote: this build escrows 0.3501 ICP (rate 35000 XDR-permyriad/ICP); settlement charges 3x actual use and refunds the rest
remote: your balance is 2.0000 ICP
remote: escrow pulled, job 0
…
remote: settled (done): charged 0.0009 ICP, refunded 0.3489 ICP
compiled by … (sha256 …), moxzi 0.1.0-alpha.1
```

Useful with it: `--progress N` (report every N steps), `--status-secs S` (name the
compiler's phase, coarsely — it costs a query), `--max-steps N` (give up),
`moxzi deps entry.mo` (preview exactly which files would be uploaded, with VFS paths).

## The payment model (escrow → measure → 3× actual → refund)

- `quoteEscrow()` (an update — the rate comes from the CMC live) returns exactly what
  `startEscrowed` will pull: escrow cycles at the CMC's ICP↔XDR rate plus the ledger fee.
  Pricing is server-side so clients cannot drift.
- `startEscrowed` pulls escrow via `icrc2_transfer_from` and samples the cycle balance;
  the delta at completion is what the compile actually consumed.
- `settleStep(id)` is an idempotent machine: measure → refund unused escrow → convert 1×
  actual back to cycles (self-funding top-up) → donations → done.
- A flat-fee path also exists (`startPaid`, `getPrice`); the CLI prefers escrow because
  it charges what a build costs, not what the worst build costs.

## Operator: deploy and arm

1. **Build reproducibly**: `make compiler-canister-wasm` and `make moxzi-linker`; pin the
   `mops toolchain` moc version; record both SHA-256s — they are the provenance every
   build cites.
2. **Deploy both canisters**: compiler with `wasm_memory_limit` = 6 GiB (big compiles
   really peak near it) and generous cycles; linker > 3 GiB.
3. **Bootstrap operators**: call `syncOperators()` — callable by anyone, grants nothing
   new: it copies the controller list into the operator set. A fresh deployment is
   LOCKED (empty operator set fails closed) until this runs.
4. **Arm payment** (operator): `setLedger(ryjl3-tyaaa-aaaaa-aaaba-cai)` (mainnet ICP),
   `setCmc(rkp4c-7iaaa-aaaaa-aaaca-cai)`, optionally `setEscrowCycles(n)`,
   `setPrice(e8s)`, `setChargeMultiplier(n)`.
5. **Smoke it**: an unfunded identity must be refused with "insufficient balance" BEFORE
   any transfer; a funded hello-world must compile, settle, and refund most of its escrow.
6. **Watch it**: `sdStatus()` (heartbeat), `jobStats()` (jobs/finished/artifact bytes),
   `revenue()` (flat-path e8s), the canister's ledger account, and the cycle balance —
   top-ups convert 1× actual back to cycles, so a busy canister partially self-funds.

## Abuse posture (what a stranger can and cannot do)

| Surface | Bound |
|---|---|
| VFS uploads | 64 MiB per caller, 1 GiB total — writes trap past either |
| Job records/artifacts | evicted oldest-first past a retention cap; a job with an open settlement is **never** evicted |
| Others' jobs | every job method checks owner-or-operator; refusals are silent (null/0/false) so probing ids teaches nothing |
| Compute | a job runs only after escrow is pulled; the self-driven stepper bounds per-message instructions by construction |
| Concurrency | one queue; builds serialize (the alpha's honest scale ceiling) |
| Cost griefing | escrow is the customer's money; a compile that OOMs still settles for what it burned |

## Error → cause → fix

| Symptom | Cause | Fix |
|---|---|---|
| "insufficient balance" before any transfer | unfunded CLI identity | send ICP to the principal the CLI printed |
| build compiles free on a fresh deployment | payment not configured — this is by design | operator runs the arming sequence |
| all calls refused after deployment | operator set is empty (fails closed) | call `syncOperators()` |
| artifact fails wasm validation before linking | on-chain output is UNLINKED by design | the CLI links automatically; manually, `moxzi link` |
| second build queues behind the first | one canister = one queue | wait, or deploy another canister |

Related skills: local builds → `moxzi-cli`; running artifacts → `moxzid-server` / `moxzi-web`.