{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ecoclouddev.com/schemas/settlement-instruction.schema.json",
  "title": "EcoCloud Settlement Instruction (ISO-AGENT)",
  "description": "The off-network settlement instruction emitted at the close of a clearing cycle. EcoCloud computes the multilateral net (see the netting kernel) and this schema; the member's ERP/PSP (SAP, Stripe, a bank ledger) reads it and posts the actual financial journal entry. EcoCloud guarantees the math and the schema match — it NEVER touches the bank or moves money. The amounts are a billable BASIS (a measure), not a transfer.",
  "type": "object",
  "additionalProperties": false,
  "required": ["network_rules_version", "instruction_id", "period", "member", "currency", "net_balance", "settlements", "generated_at", "digest"],
  "properties": {
    "network_rules_version": { "type": "string", "description": "the EcoCloud Operating Regulations version these instructions clear under, e.g. 'or-1'", "examples": ["or-1"] },
    "instruction_id": { "type": "string", "description": "unique id for this settlement instruction" },
    "period": {
      "type": "object", "additionalProperties": false, "required": ["start", "end"],
      "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } }
    },
    "member": { "type": "string", "description": "the network member this instruction is addressed to" },
    "currency": { "type": "string", "description": "ISO 4217 unit of the basis (e.g. USD) — denominates the measure; no money moves through EcoCloud" },
    "net_balance": { "type": "number", "description": "the member's net position for the cycle; Σ net_balance across all members = 0 (conservation)" },
    "settlements": {
      "type": "array",
      "description": "the minimal set of off-network transfers that clears this member's position",
      "items": {
        "type": "object", "additionalProperties": false, "required": ["counterparty", "direction", "amount"],
        "properties": {
          "counterparty": { "type": "string" },
          "direction": { "type": "string", "enum": ["pay", "receive"] },
          "amount": { "type": "number", "minimum": 0 }
        }
      }
    },
    "basis": {
      "type": "object", "additionalProperties": false,
      "description": "the verified work this settlement nets — links back to the signed attestations",
      "properties": {
        "attestation_refs": { "type": "array", "items": { "type": "string" } },
        "gau_total": { "type": "number", "minimum": 0 }
      }
    },
    "generated_at": { "type": "string", "format": "date-time" },
    "digest": { "type": "string", "description": "tamper-evident hash over the canonical instruction (the member clicks 'Settled' to close the Settle phase against this digest)" }
  },
  "examples": [
    {
      "network_rules_version": "or-1",
      "instruction_id": "si_2026Q2_acme",
      "period": { "start": "2026-04-01T00:00:00Z", "end": "2026-06-30T23:59:59Z" },
      "member": "acme-corp",
      "currency": "USD",
      "net_balance": -1840.50,
      "settlements": [{ "counterparty": "globex", "direction": "pay", "amount": 1840.50 }],
      "basis": { "attestation_refs": ["att_9f2a", "att_71cd"], "gau_total": 36810 },
      "generated_at": "2026-07-01T00:05:00Z",
      "digest": "a3f1e2c7"
    }
  ]
}