The Inner-Workings of Our Settlement

9-state settlement engine lifecycle - from intent submission through finality proof, covering fiat-to-fiat, fiat-to-crypto, and crypto-to-crypto settlement lanes.

01Settlement Types

The settlement engine supports three distinct lanes, each with different compliance paths and attestation requirements.

02Settlement State Machine - Happy Path

The 8-step happy path from client submission through finality. Each state transition is driven by the settlement engine's poll loop running at ENGINE_POLL_INTERVAL_MS (default 2000ms).

03DVP/PVP Leg Attestation Flow

For multi-leg settlements (DVP and PVP), the engine holds at the ACCEPTED state until all counterparties have confirmed their legs. This section details the attestation branching.

04Terminal Failure States

Settlements can exit the happy path and reach a terminal failure state at several points in the lifecycle.

05API Endpoints

Example: Create a SIMPLE Settlement

Example: Create a DVP Settlement

06Service Architecture

The settlement lifecycle is orchestrated across five services, each responsible for specific state transitions.

07Database Schema

id                     UUID PRIMARY KEY
uetr                   UUID NOT NULL UNIQUE       -- Unique End-to-End Transaction Reference
type                   TEXT NOT NULL               -- SIMPLE | DVP | PVP
status                 TEXT NOT NULL               -- received | validated | compliance_check | accepted | ready | submitted | confirmed | final | rejected | failed | cancelled | expired
asset                  TEXT NOT NULL               -- primary settlement asset
amount                 NUMERIC NOT NULL
sender_legal_name      TEXT
sender_account_id      TEXT NOT NULL
sender_country         TEXT
sender_address         TEXT
receiver_legal_name    TEXT
receiver_account_id    TEXT NOT NULL
receiver_country       TEXT
receiver_address       TEXT
compliance_receipt     TEXT                       -- SHA-256 of compliance proof bundle
compliance_decision    TEXT                       -- allow | deny
travel_rule_result     TEXT                       -- pass | fail | not_applicable
tx_id                  TEXT                       -- L1 transaction ID (set at SUBMITTED)
block_height           BIGINT                     -- L1 block height (set at CONFIRMED)
block_hash             TEXT                       -- L1 block hash
confirmations          INT DEFAULT 0
fee_bps                INT                        -- fee in basis points (set at FINAL)
fee_amount             NUMERIC                    -- calculated fee amount
finality_proof         TEXT                       -- finality proof hash (set at FINAL)
callback_url           TEXT                       -- webhook URL for notifications
batch_id               UUID                       -- batch reference (if created via /batch)
expires_at             TIMESTAMPTZ NOT NULL       -- expiry deadline
created_at             TIMESTAMPTZ DEFAULT NOW()
updated_at             TIMESTAMPTZ DEFAULT NOW()
      

id                     UUID PRIMARY KEY
settlement_id          UUID NOT NULL REFERENCES settlements(id)
leg_id                 TEXT NOT NULL               -- e.g. "leg_1", "leg_2"
direction              TEXT NOT NULL               -- delivery | payment
asset                  TEXT NOT NULL
amount                 NUMERIC NOT NULL
party_id               TEXT NOT NULL
party_legal_name       TEXT
compliance_receipt     TEXT                       -- per-leg compliance proof hash
compliance_decision    TEXT                       -- allow | deny
attested               BOOLEAN DEFAULT FALSE
attested_at            TIMESTAMPTZ
status                 TEXT DEFAULT 'pending'     -- pending | attested | settled | failed
created_at             TIMESTAMPTZ DEFAULT NOW()
      

id                     BIGSERIAL PRIMARY KEY
settlement_id          UUID NOT NULL REFERENCES settlements(id)
event_type             TEXT NOT NULL               -- state_change | compliance_result | leg_attested | webhook_sent | error
from_state             TEXT
to_state               TEXT
metadata               JSONB                      -- event-specific payload
created_at             TIMESTAMPTZ DEFAULT NOW()
      

08Configuration

Key configuration parameters for the settlement engine. All values are set via environment variables.

09Key Source Files