Skip to main content

Anatomy of a contract

A state contract is deployable JSON logic that lives inside your machine and runs on its clock. It has exactly four load-bearing parts: states, transitions, the operators those transitions fire, and the audit clock that proves every fire. Below is a real template, verbatim from the live registry — reproduce it yourself:

curl -s https://zeqsdk.com/api/contracts/templates/force-threshold-alarm
{
  "name": "force_threshold_alarm",
  "version": "1.0",
  "states": {
    "idle":     { "initial": true },
    "watching": {},
    "alert":    {},
    "cleared":  { "terminal": true }
  },
  "transitions": [
    { "from": "idle",     "to": "watching", "operator": "KO42", "proof_required": false },
    { "from": "watching", "to": "alert",    "operator": "NM19",
      "condition": "input.mass_kg * input.acceleration_ms2 > input.force_limit_n",
      "proof_required": true },
    { "from": "alert",    "to": "watching", "operator": "NM19",
      "condition": "input.mass_kg * input.acceleration_ms2 <= input.force_limit_n",
      "proof_required": true },
    { "from": "alert",    "to": "cleared",  "operator": "KO42",
      "condition": "input.acknowledged == true", "proof_required": false }
  ],
  "observers": [],
  "audit_clock": true
}

That is a complete structural-load watchdog: NM19 (F = ma) evaluated on every reading, idle → watching → alert when the computed force crosses your limit, back to watching when it clears, cleared as the terminal state once acknowledged.

The parts​

States​

Named positions the contract can occupy. Exactly one carries "initial": true (where a fresh deploy starts); any state may carry "terminal": true (the contract stops there). Everything between is yours to shape.

Transitions​

Each transition is a guarded edge: from → to, firing an operator, optionally gated by a condition over the transition's input (input.mass_kg * input.acceleration_ms2 > input.force_limit_n — plain expressions over the payload you post). No condition means the edge fires when explicitly triggered.

The operator​

Every transition names the operator it runs — the compute is a real solver evaluation, not a label. KO42 transitions are protocol steps (clock-stamped, no physics claim); an NM19 transition actually computes F = ma from the transition's inputs through the full pipeline.

proof_required and the audit clock​

With "proof_required": true, the fire is recorded with a ZeqProof (HMAC(operator | result | zeqond)) on the machine's hash-linked audit chain — the envelope a stranger can verify. "audit_clock": true stamps every transition with the machine's Zeqond clock, so the ordering and timing of the contract's history is part of what's provable — and the seal spine makes rewriting that history cost real time.

Where contracts come from​

  • 316 ready-made templates across the physics domains — list them: GET /api/contracts/templates (public), one: GET /api/contracts/templates/:id, deploy into your machine: POST /api/contracts/templates/:id/deploy.
  • Natural language — POST /api/contracts/generate turns a described behaviour into a contract definition you can review and deploy.
  • By hand — write the JSON above yourself and deploy it (custom deploy).