From 0c03ec3324dc388262e7fad0396a593431586f1d Mon Sep 17 00:00:00 2001 From: Michael Heller <21163552+mdheller@users.noreply.github.com> Date: Sat, 4 Jul 2026 17:49:23 -0400 Subject: [PATCH] feat(triparty): governed-triparty marketplace contract (netting cell + bundles) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Stage 2 of the 5 handoff specs — the marketplace/settlement layer from the Governed Triparty Netting Fabric whitepaper. The three-party clearing cell that couples value + proof + authority + disclosure and governs release/refund/export by policy rather than confidence. - NettingCell: three legs (A/B counterparties, C clearing/verifier), each carrying value / capability-right / proof kept DISTINCT (evidence != permission). stage (Observed→Proposed→Ready→Escrowed→Filled→Verified→Released→Exported / Refunded/Reversed), truthClass (PROVEN⊐ATTESTED⊐INFERRED⊐REPUTED), admissibility (evidence⊇admit⊇release⊇export — export stricter than local validity), policyKernelRef, reserveRef, and an optional supplyChainRef so a cell can clear a supply-chain trade. - TripartyBundle: the typed proof-carrying bundle (intent/acceptance/escrow/fill/ verification/export) that advances a cell, carrying payload + proof + attestation (the Truth Record) so release is a function of evidence + admissibility + freshness. Composes over the Truth-Engine constitution + ties to the TriTRPC/membrane moat. + examples + tools/validate_triparty_examples.py + Makefile target. Both validate. --- Makefile | 8 +- examples/netting_cell.json | 36 ++++++ examples/triparty_bundle.json | 16 +++ schemas/NettingCell.json | 163 ++++++++++++++++++++++++++++ schemas/TripartyBundle.json | 81 ++++++++++++++ tools/validate_triparty_examples.py | 39 +++++++ 6 files changed, 341 insertions(+), 2 deletions(-) create mode 100644 examples/netting_cell.json create mode 100644 examples/triparty_bundle.json create mode 100644 schemas/NettingCell.json create mode 100644 schemas/TripartyBundle.json create mode 100644 tools/validate_triparty_examples.py diff --git a/Makefile b/Makefile index f5570ba..eb7f73d 100644 --- a/Makefile +++ b/Makefile @@ -1,8 +1,12 @@ -.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples +.PHONY: validate validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-triparty-examples -validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples +validate: validate-control-plane-examples validate-nlboot-examples validate-lattice-data-governai-examples validate-ops-history-examples validate-runtime-observability-examples validate-interpretability-examples validate-lifecycle-boundary-examples validate-svf-contracts validate-sync-cycle-receipts validate-onboarding-examples validate-runtime-causality-examples validate-triparty-examples @echo "OK: validate" +validate-triparty-examples: + python3 -m pip install --user jsonschema >/dev/null + python3 tools/validate_triparty_examples.py + validate-control-plane-examples: python3 -m pip install --user jsonschema >/dev/null python3 tools/validate_control_plane_examples.py diff --git a/examples/netting_cell.json b/examples/netting_cell.json new file mode 100644 index 0000000..0906730 --- /dev/null +++ b/examples/netting_cell.json @@ -0,0 +1,36 @@ +{ + "id": "urn:srcos:netting-cell:cu-trade-0001", + "type": "NettingCell", + "specVersion": "2.0.0", + "legs": [ + { + "party": "urn:srcos:party:antofagasta-port", + "role": "A", + "valueRef": "asset://copper-cathode/500t", + "proofRef": "urn:srcos:attestation:antofagasta/bill-of-lading" + }, + { + "party": "urn:srcos:party:shanghai-buyer", + "role": "B", + "valueRef": "asset://ASI/1.16M", + "capabilityRef": "cap://import-license/cn" + }, + { + "party": "urn:srcos:party:clearing-verifier", + "role": "C", + "proofRef": "urn:srcos:attestation:route-anf-sha/delivery" + } + ], + "stage": "Verified", + "truthClass": "ATTESTED", + "admissibility": "release", + "bundleRefs": [ + "urn:srcos:triparty-bundle:cu-trade-0001-fill", + "urn:srcos:triparty-bundle:cu-trade-0001-verify" + ], + "policyKernelRef": "policy://triparty/release-guard", + "reserveRef": "reserve://asi/primary", + "netAmount": 1160000, + "asset": "ASI", + "supplyChainRef": "hg:route/anf-sha" +} diff --git a/examples/triparty_bundle.json b/examples/triparty_bundle.json new file mode 100644 index 0000000..0ab42a3 --- /dev/null +++ b/examples/triparty_bundle.json @@ -0,0 +1,16 @@ +{ + "id": "urn:srcos:triparty-bundle:cu-trade-0001-verify", + "type": "TripartyBundle", + "specVersion": "2.0.0", + "kind": "verification", + "cellRef": "urn:srcos:netting-cell:cu-trade-0001", + "payload": { + "verifier": "clearing-verifier", + "result": "delivery-confirmed", + "scope": "route-anf-sha" + }, + "proofRef": "urn:srcos:proof:cu-trade-0001/state", + "attestationRef": "urn:srcos:attestation:route-anf-sha/delivery", + "truthClass": "ATTESTED", + "issuedAt": "2026-07-03T18:00:00Z" +} diff --git a/schemas/NettingCell.json b/schemas/NettingCell.json new file mode 100644 index 0000000..0997041 --- /dev/null +++ b/schemas/NettingCell.json @@ -0,0 +1,163 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/NettingCell.json", + "title": "NettingCell", + "description": "A governed triparty netting cell — the smallest local clearing object that couples value, proof, authority, and disclosure. Cancels interior circulation across three legs and governs release/refund/export by policy rather than confidence alone.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "legs", + "stage", + "truthClass", + "admissibility" + ], + "properties": { + "id": { + "type": "string", + "pattern": "^urn:srcos:netting-cell:", + "description": "Stable URN identifier. Pattern: urn:srcos:netting-cell:" + }, + "type": { + "const": "NettingCell", + "description": "Discriminator constant — always \"NettingCell\"." + }, + "specVersion": { + "type": "string", + "description": "Spec version, e.g. \"2.0.0\"." + }, + "legs": { + "type": "array", + "minItems": 3, + "maxItems": 3, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "party", + "role" + ], + "properties": { + "party": { + "type": "string", + "minLength": 1, + "description": "Party URN / identifier for this leg." + }, + "role": { + "type": "string", + "enum": [ + "A", + "B", + "C" + ], + "description": "Triparty leg role (A, B are counterparties; C is the clearing/verifier leg)." + }, + "valueRef": { + "type": [ + "string", + "null" + ], + "description": "The monetary/asset value this leg carries into the cell." + }, + "capabilityRef": { + "type": [ + "string", + "null" + ], + "description": "The capability right this leg carries (from the CapabilityRegistry) — kept distinct from value." + }, + "proofRef": { + "type": [ + "string", + "null" + ], + "description": "The proof/attestation this leg carries (Truth Engine) — evidence distinct from permission." + } + } + }, + "description": "The three triparty legs (A, B counterparties; C clearing/verifier)." + }, + "stage": { + "type": "string", + "enum": [ + "Observed", + "Proposed", + "Ready", + "Escrowed", + "Filled", + "Verified", + "Released", + "Exported", + "Refunded", + "Reversed" + ], + "description": "Lifecycle stage: Observed→Proposed→Ready→Escrowed→Filled→Verified→Released→(Exported); or Refunded/Reversed." + }, + "truthClass": { + "type": "string", + "enum": [ + "PROVEN", + "ATTESTED", + "INFERRED", + "REPUTED" + ], + "description": "Truth class of the cell's current state (constitution): PROVEN⊐ATTESTED⊐INFERRED⊐REPUTED." + }, + "admissibility": { + "type": "string", + "enum": [ + "evidence", + "admit", + "release", + "export" + ], + "description": "Current admissibility ceiling on the lattice evidence⊇admit⊇release⊇export. Export is stricter than local validity." + }, + "bundleRefs": { + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "pattern": "^urn:srcos:triparty-bundle:" + }, + "description": "The typed bundles that moved this cell through its lifecycle." + }, + "policyKernelRef": { + "type": [ + "string", + "null" + ], + "description": "The PolicyKernel that disposes release/refund/export (policy disposes; evidence proposes; proof preserves)." + }, + "reserveRef": { + "type": [ + "string", + "null" + ], + "description": "ReserveManager reference backing settlement." + }, + "netAmount": { + "type": [ + "number", + "null" + ], + "description": "Net residual after interior cancellation." + }, + "asset": { + "type": [ + "string", + "null" + ], + "description": "Settlement asset / token (e.g. ASI/FET)." + }, + "supplyChainRef": { + "type": [ + "string", + "null" + ], + "description": "Optional hg: / node ref when this cell clears a supply-chain trade." + } + } +} diff --git a/schemas/TripartyBundle.json b/schemas/TripartyBundle.json new file mode 100644 index 0000000..d383299 --- /dev/null +++ b/schemas/TripartyBundle.json @@ -0,0 +1,81 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.srcos.ai/v2/TripartyBundle.json", + "title": "TripartyBundle", + "description": "A typed, proof-carrying bundle that moves a netting cell through one lifecycle step. Bundle kinds mirror the settlement flow; each carries payload + proof + attestation so release is a function of evidence, admissibility, and freshness — not confidence.", + "type": "object", + "additionalProperties": false, + "required": [ + "id", + "type", + "specVersion", + "kind", + "cellRef", + "payload", + "truthClass" + ], + "properties": { + "id": { + "type": "string", + "pattern": "^urn:srcos:triparty-bundle:", + "description": "Stable URN identifier. Pattern: urn:srcos:triparty-bundle:" + }, + "type": { + "const": "TripartyBundle", + "description": "Discriminator constant — always \"TripartyBundle\"." + }, + "specVersion": { + "type": "string", + "description": "Spec version, e.g. \"2.0.0\"." + }, + "kind": { + "type": "string", + "enum": [ + "intent", + "acceptance", + "escrow", + "fill", + "verification", + "export" + ], + "description": "Bundle kind: intent→acceptance→escrow→fill→verification→export." + }, + "cellRef": { + "type": "string", + "pattern": "^urn:srcos:netting-cell:", + "description": "The netting cell this bundle advances." + }, + "payload": { + "type": "object", + "description": "Kind-specific payload (terms, fill metadata, verification result, export scope)." + }, + "proofRef": { + "type": [ + "string", + "null" + ], + "description": "Packet/state proof (freshness, replay-safety)." + }, + "attestationRef": { + "type": [ + "string", + "null" + ], + "description": "Witness/attestation (provenance + independence) — the Truth Record backing this bundle." + }, + "truthClass": { + "type": "string", + "enum": [ + "PROVEN", + "ATTESTED", + "INFERRED", + "REPUTED" + ], + "description": "Truth class this bundle asserts." + }, + "issuedAt": { + "type": "string", + "description": "ISO-8601 issue time (freshness)." + } + } +} diff --git a/tools/validate_triparty_examples.py b/tools/validate_triparty_examples.py new file mode 100644 index 0000000..27fe370 --- /dev/null +++ b/tools/validate_triparty_examples.py @@ -0,0 +1,39 @@ +#!/usr/bin/env python3 +"""Validate the governed-triparty marketplace contract examples. + +Covers the settlement/marketplace primitives: NettingCell (the triparty clearing +cell that couples value + proof + authority + disclosure) and TripartyBundle (the +typed, proof-carrying bundle that advances a cell through its lifecycle). +""" +from __future__ import annotations + +import json +from pathlib import Path + +import jsonschema + +ROOT = Path(__file__).resolve().parents[1] +PAIRS = [ + (ROOT / "schemas" / "NettingCell.json", ROOT / "examples" / "netting_cell.json"), + (ROOT / "schemas" / "TripartyBundle.json", ROOT / "examples" / "triparty_bundle.json"), +] + + +def validate_pair(schema_path: Path, example_path: Path) -> None: + schema = json.loads(schema_path.read_text(encoding="utf-8")) + jsonschema.validators.validator_for(schema).check_schema(schema) + example = json.loads(example_path.read_text(encoding="utf-8")) + jsonschema.validate(example, schema) + + +def main() -> int: + checks: dict[str, bool] = {} + for schema_path, example_path in PAIRS: + validate_pair(schema_path, example_path) + checks[example_path.name] = True + print(json.dumps({"ok": all(checks.values()), "checks": checks}, indent=2, sort_keys=True)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())