Architecture

1. Overview

ezys-core turns a currency-exchange intent into a settled trade. Work moves through three layers: partners come in through the Integration Layer, the Execution Layer finds a path and drives Delivery-vs-Payment (DvP), and actual asset movement happens in the Settlement Layer — partly on-chain (custodial) and partly through external fiat partners.

Integration Layer

Where partners connect to Ezys. All entry paths normalize into one canonical intent event before anything downstream runs.

Entry surface	Connection	Purpose
REST client	HTTP (POST /intents, /quotes)	Submit an intent, or request a quote
FIX customer	FIX session (NewOrderSingle, 35=D)	Order entry over FIX
FIX LP	FIX session (Quote / MassQuote)	Supply liquidity quotes
Console (web)	REST via console API	Operator dashboard / remittance management

There is no separate client SDK today — partners call the REST/FIX surfaces directly. Two request styles exist: an RFQ flow (request a firm quote, then confirm it to execute) and a direct intent flow (single-shot submit that is accepted or rejected, no separate confirm step).

Execution Layer

The core of Ezys: it processes an intent and decides how to execute it. A single solver service (not a competing network) receives each intent, finds a settlement path, and reserves the output balance. For institutional actors it first checks capacity with ALM. It then starts a durable DvP workflow and publishes an intent.accepted event.

Liquidity sources plug into the solver through a common adapter interface, so heterogeneous sources participate uniformly whether they settle on-chain or off-chain.

Source type	Integrated today
On-chain	DEX / AMM, order book
Off-chain	External LPs (via FIX), fiat gateway (banks / on-ramps)

Batch-window collection, intent bundling, and netting of opposite-direction intents (CoW) are defined in the type model but not yet implemented — intents are currently processed one at a time.

Settlement Layer

Once a plan is accepted, the workflow executes each leg. On-chain legs move value through the protocol's own vault (which does custody assets) and an HTLC escrow for atomicity; off-chain legs are paid out through fiat providers, which are custodial to those third-party banks rather than to Ezys. Off-chain confirmation is pushed back into the workflow as a signal, and the settlement service emits a terminal settle.completed / settle.failed event.

Leg type	How it settles	Custody
On-chain	Vault + HTLC escrow, claim by preimage	Protocol vault holds assets
Off-chain	Fiat provider payout	Third-party bank / provider

---

2. Sequence Flow

A single institutional intent, from entry to settled. Solid arrows are synchronous calls, dashed arrows are broker events, and the dotted arrow is a workflow signal. Only implemented paths are shown (the on-chain ERC-7683 entry is planned and omitted).

---

3. Component Detail

Clients

Entry point	Role
REST Client	Submits an intent directly over REST (POST /intents). This is the simplest entry path — the request DTO is validated and handed to the solver as a canonical intent.
FIX Customer	Sends customer orders over a FIX session (NewOrderSingle, 35=D). The edge adapter terminates the session and converts each order into a canonical intent, so downstream services never see FIX.
FIX LP	Supplies liquidity quotes over FIX (Quote / MassQuote). Quotes are pooled at the edge and consumed during path-finding rather than turned into intents.
On-chain (ERC-7683)	Opens an intent on-chain via the ERC-7683 open() flow. (Planned entry path: the on-chain IntentSettler contract exists, but the off-chain listener that would turn an open() event into a canonical intent is not yet implemented.)

Edge Adapter

Service	Role
@ezys/fix-acceptor	Terminates FIX sessions with mTLS + HMAC authentication and is the single edge for FIX traffic. Customer orders are bridged into canonical intents and published to the broker, while LP quotes are kept in an in-memory pool for the solver to draw on.
solver REST	REST entry point that turns request DTOs into intents. It performs the same normalization as the FIX path, so REST and FIX converge on one canonical intent event.

Message Broker

• Central event bus carrying every intent, order, and settlement event between services. Delivery is at-least-once; the core services (solver, settlement, fiat-gateway) publish through a transactional outbox and consumers dedup with an inbox guard, so re-delivered events are not processed twice.
• The off-chain entry paths (FIX / REST) are normalized into a single canonical intent event before flowing downstream, and settlement progress flows back as its own event stream (planned → completed / failed).
• Events are schema-validated so producers and consumers stay compatible as event versions evolve.

Core Services

Service	Role
@ezys/solver	Consumes the canonical intent from the broker and drives the front half of a trade: it finds a settlement path and reserves the output balance. For institutional actors it also calls ALM synchronously as a capacity gate before committing (retail intents skip this). On success it starts the DvP workflow and emits an intent.accepted event carrying the plan. Batch (CoW) matching is planned.
@ezy/alm	Owns asset-liability exposure and institutional limits. The solver calls it synchronously as a pre-trade capacity gate for institutional intents, and it also consumes settlement plans to update exposure by tenor bucket after the fact.
@ezys/oracle	Aggregates external price sources into a single reference feed and publishes price updates to the broker. The solver reads prices from it over HTTP for path-finding, and the on-chain layer has its own separate aggregator contract for settlement-time pricing.
@eyzs/aggregator	Intended to hold an intent pool and run batch-auction matching. (planned — no service exists yet.)
@ezys/settlement	Consumes the settlement plan and executes each leg — on-chain, off-chain, or HTLC — handing long-running legs to the workflow engine. It correlates fiat provider events back to the plan, advances leg status monotonically, and emits settle.completed / settle.failed when the plan reaches a terminal state.

Orchestration

Element	Role
@ezys/workflows	Orchestrates a settlement's legs as a durable, multi-phase workflow (input resolution → fill → confirm → HTLC claim). It calls the settlement and fiat layers through activities, waits for an off-chain confirmation signal pushed from the settlement consumer, and on failure releases the balance reservation. (A failed leg also records an SLA violation, currently logged as a placeholder for future slashing enforcement.)
Workflow Engine	Durable execution backend that guarantees each workflow step runs to completion or safely retries, and that keeps long-running waits (e.g. hours for a fiat provider) alive across restarts.

Fiat Abstraction Layer

Element	Role
@ezys/fiat-gateway	Exposes payout / quote / provider REST endpoints and routes each request to a provider through a provider hub. Payout status changes are published as fiat provider events so the settlement layer can confirm the off-chain leg.
Provider Adapters	Pluggable connectors behind a common interface (quote / payout / status) so adding a provider does not change the core flow. Most adapters are currently simulators; only some are wired to a real provider API.

On-chain (EVM)

Contract	Role
EzysVault	Custodies protocol assets and gates withdrawals behind a treasury role. Deposits can be made directly or gaslessly via a signed permit, and transfers run any registered hooks — a generic extension point that can enforce checks such as supported-asset or compliance rules, though which hooks are active is configurable.
HTLCEscrow	Hash Time-Locked escrow that holds funds against a hashlock and deadline, giving DvP its atomicity: the recipient claims by revealing the preimage, or the sender refunds after the timelock. It owns fund custody while IntentSettler tracks the matching intent.
IntentSettler	Drives the on-chain intent lifecycle (open → fill → settle → cancel, ERC-7683-inspired) and records which solver was assigned and when it filled. By convention its fill deadline is kept inside the escrow's timelock so an intent can be cancelled before the funds become refundable — the coordinator enforces this; the contract does not check it.
EzysPermit2	Verifies EIP-712 permits so approvals and settlement authorizations can be signed off-chain. The vault calls it to validate permit-based deposits, and owners can invalidate pending permits by advancing their nonce.
Registries · Oracle · Hooks	Supporting contracts: an asset registry (allowlist + decimals) and solver registry (bond, KYC, slashing) define who and what can participate, an on-chain oracle aggregator produces consensus prices with staleness limits, and a hook registry runs pluggable pre-settlement / pre-transfer checks.

Data / Infra

Element	Role
RDB	Durable store of record for each service — transactional outbox/inbox tables, settlement plans, and session state — so events and state stay consistent even across restarts.
Cache	In-memory store for hot data such as cached prices and session/quote state, keeping the request path fast without touching the RDB.

External

Element	Role
Bank / On-ramp / PG	Off-chain settlement counterparties reached through the provider adapters — banks, on-ramps, and payment gateways that actually move fiat.
Blockchain / BaaS	The external chain or managed blockchain network the on-chain contracts settle on; the vault and escrow sit in front of it as the protocol's integration point.