🔒 SETTLEMENT DOMAIN FORMAL SPEC v1.0
0. Status
Version: 1.0
Status: Canonical
Authority: packages/core/settlement/*
Binding to: GovernanceRecordType
Canonical RecordTypes:
SETTLEMENT_INTENT
SETTLEMENT_EVENT
- Domain Purpose
Settlement domain governs:
Monetary commitments
Escrow lifecycle
Conditional release logic
Refund resolution
Governance-bound financial execution
Settlement is ledger-driven, not execution-driven.
Execution layer is external.
Ledger = authoritative truth.
- Canonical Record Types
2.1 SETTLEMENT_INTENT
Represents:
Creation of settlement obligation
Escrow configuration
Asset specification
Binding to policy
Binding to subject (auction/tender/etc)
Properties:
subjectId (composite)
policyHash
action = SETTLEMENT.CREATE
decision = INFO
metadata optional
Intent does NOT move funds.
Intent creates:
Immutable obligation state
2.2 SETTLEMENT_EVENT
Represents lifecycle progression.
Valid event actions:
SETTLEMENT.ESCROW_OPENED
SETTLEMENT.DEPOSIT_CONFIRMED
SETTLEMENT.RELEASE_REQUESTED
SETTLEMENT.RELEASE_EXECUTED
SETTLEMENT.REFUND_EXECUTED
Each event:
Must have prior ALLOW ACCESS_DECISION
Must reference same subjectId
Must reference same policyHash
Must follow lifecycle constraints
- Settlement Lifecycle State Machine
Settlement lifecycle is derived from ordered events.
No stored mutable state.
State is computed by ledger replay.
3.1 Logical States (Derived)
Derived State Condition
CREATED INTENT exists
ESCROW_OPENED ESCROW_OPENED event exists
FUNDED DEPOSIT_CONFIRMED exists
RELEASE_PENDING RELEASE_REQUESTED exists
RELEASED RELEASE_EXECUTED exists
REFUNDED REFUND_EXECUTED exists
4. Lifecycle Invariants
4.1 Authorization Invariant
For each Settlement record:
Latest matching ACCESS_DECISION(subjectId, action, policyHash) must be:
decision === ALLOW
Else reject.
4.2 Escrow Ordering
Invalid if:
DEPOSIT_CONFIRMED before ESCROW_OPENED
RELEASE_EXECUTED before RELEASE_REQUESTED
RELEASE_REQUESTED after REFUND_EXECUTED
RELEASE_EXECUTED after REFUND_EXECUTED
4.3 Monotonicity
Events must not violate prior terminal state:
Terminal states:
RELEASE_EXECUTED
REFUND_EXECUTED
After terminal state:
No further lifecycle events allowed.
- Determinism Rules
Settlement validation must:
Be pure function
Depend only on ledger
Not depend on wall clock
Not depend on environment config
Not depend on network responses
Not depend on blockchain state
Ledger replay MUST produce identical lifecycle result.
- Cross-Domain Dependencies
Settlement requires:
Policy freeze (if policy-bound)
Parent process closure (Auction CLOSED / Tender CLOSED)
KES_VERSION_RATIFIED if settlementProfileHash is KES-bound
Settlement must not activate before parent domain completion.
- Escrow Model
Settlement supports abstraction layer:
railType:
BLOCKCHAIN
BANK
VASP
INTERNAL_LEDGER
custodyType:
PLATFORM
PARTNER_ESCROW
SELF_CUSTODY
Protocol does not execute funds.
Protocol validates:
authorization
lifecycle
trace metadata
Execution layer performs actual movement.
- Cryptographic Traceability
Each SETTLEMENT_EVENT must include:
authDecisionEntryHash
authDecisionPayloadHash
authDecisionAction
authDecisionPolicyHash
These bind:
event → authorization decision → policy
Ensures forensic traceability.
- Forbidden Patterns
❌ No settlement without intent
❌ No event without prior authorization
❌ No duplicate milestone release
❌ No re-open after terminal state
❌ No mutable state outside ledger
- Formal Guarantees
Settlement Domain guarantees:
Deterministic replay
Authorization trace binding
Lifecycle monotonicity
Cross-domain ordering safety
Audit-grade immutability
- Versioning Policy
Any change to:
lifecycle rules
allowed event types
authorization binding
terminal states
Requires:
Major version bump
Update to:
PROTOCOL_GOVERNANCE_INVARIANTS.md
GOVERNANCE_STATE_MACHINE_MATRIX.md
METADATA_KEY_ALLOWLIST.md
RECORDTYPE_REGISTRY.md
Failure = protocol drift.
- Governance Boundary
Settlement Domain belongs to:
Core Governance Layer
It is NOT:
Payment processor
Blockchain execution engine
Banking adapter
Smart contract runtime
It is:
Governance-level settlement authorization and lifecycle validation engine.