SETTLEMENT_MULTI_RAIL_DETERMINISTIC_ABSTRACTION_SPEC.md

Purpose

Define a deterministic, rail-agnostic settlement abstraction for governance records while preserving canonical dual record types:

• SETTLEMENT_INTENT
• SETTLEMENT_EVENT

Scope

This specification covers governance-layer representation and validation only. It does not define actual payment execution behavior.

Definitions

• railType: one of BLOCKCHAIN, BANK, VASP, INTERNAL_LEDGER.
• custodyType: one of PLATFORM, PARTNER_ESCROW, SELF_CUSTODY.
• subjectId: composite identifier <SubjectType>:<SubjectId>.
• correlationId: deterministic reference linking governance event to external execution attempt.

Normative Rules

1. Settlement MUST use SETTLEMENT_INTENT for obligation creation (SETTLEMENT.CREATE).
2. Settlement lifecycle progression MUST use SETTLEMENT_EVENT with actions SETTLEMENT.<EVENT_TYPE>.
3. Validation MUST be ledger-only and MUST NOT call external rail adapters.
4. Governance records MUST NOT imply funds are moved by protocol itself.
5. Metadata written on-chain MUST remain compatible with string -> string allowlist constraints.

Rail-Agnostic Event Semantics

• ESCROW_OPENED: escrow channel is considered opened by external operator.
• DEPOSIT_CONFIRMED: deposit is externally confirmed.
• RELEASE_REQUESTED: release intent has been requested.
• RELEASE_EXECUTED: release confirmed externally.
• REFUND_EXECUTED: refund confirmed externally.

These semantics are invariant across rails; only external evidence format differs.

Metadata Profile by Rail (Allowlist-Compatible)

All values below MUST be stored using existing allowed keys.

Common Intent Metadata

For SETTLEMENT_INTENT:

• requestId MUST carry unique deterministic request reference.
• externalReference SHOULD encode rail and custody context, for example rail=BLOCKCHAIN;custody=PARTNER_ESCROW.
• memo MAY contain human-readable short context.

Common Event Metadata

For SETTLEMENT_EVENT:

• externalTxId SHOULD carry rail transaction id where available.
• providerReference SHOULD carry provider operation id.
• note MAY carry deterministic normalized status details.
• authDecisionEntryHash and authDecisionPayloadHash SHOULD be present for traceability.

Rail-Specific Guidance

• BLOCKCHAIN: externalTxId SHOULD be tx hash; providerReference SHOULD be chain+network reference.
• BANK: externalTxId SHOULD be bank transfer id; providerReference SHOULD be bank operation code.
• VASP: externalTxId SHOULD be settlement transfer id; providerReference SHOULD be custody-provider request id.
• INTERNAL_LEDGER: externalTxId SHOULD be internal posting id; providerReference SHOULD be system journal reference.

External Execution Adapter Contract

Inputs

Adapters SHOULD receive:

• settlement event payload (action, metadata)
• policyHash
• subjectId
• correlation identifiers (requestId, providerReference, or deterministic equivalent)

Outputs

Adapters MAY return:

• externalTxId
• providerReference

These outputs, if persisted to governance, MUST be written through explicit settlement events using allowlisted metadata keys.

Failure Handling

• Adapter failures MUST NOT auto-append governance records.
• If protocol supports explicit failure events, they MUST be appended through normal governance authorization and validation.
• If protocol does not support explicit failure event in current flow, governance state MUST remain pending with no implicit mutation.

Determinism Guardrails

1. Validators MUST NOT call adapters.
2. Validators MUST NOT branch on live network results.
3. All validity outcomes MUST be derivable from ledger entries only.
4. Execution adapters are outside governance trust boundary.

Mapping to Code

• Intent authorization path conceptually aligns with verifySettlementAuthorization.
• Event authorization path conceptually aligns with verifySettlementEventAuthorization.
• Lifecycle ordering path conceptually aligns with verifySettlementLifecycle.
• Append/build flow is represented by settlement record builders and appenders in packages/core/settlement/*.

Non-normative Notes

• Rail profile encoding inside externalReference is a compatibility mechanism to remain within current metadata allowlist.
• Stronger typed rail fields can be introduced only through coordinated schema and allowlist updates.

Testability

• Conformance test 1 (BLOCKCHAIN): intent + escrow-opened event contains deterministic tx hash in externalTxId and passes lifecycle checks.
• Conformance test 2 (BANK): deposit-confirmed event with bank transfer id in externalTxId and provider op id in providerReference remains valid.
• Conformance test 3 (VASP): release-requested then release-executed with stable provider references passes ordering checks.
• Conformance test 4 (INTERNAL_LEDGER): refund-executed followed by release-requested MUST fail lifecycle validation.
• Conformance test 5: replay same ledger twice MUST yield identical authorization and lifecycle reports.