Architecture — Components

This page maps the major building blocks of Sylan and how they fit together. It’s a structural view—contracts, off‑chain services, and their responsibilities. Implementation details (ABIs, addresses) live elsewhere.

High‑level view

On‑chain components

Component	Type	Responsibilities	Emits	Reads/Calls
AccessRegistry	Registry	Stores API descriptors (URI, contentHash, updatedAt, version), plan metadata (PPC/Subscription, price, duration, callLimit), and per‑API consistency/freshness params (seqMonotonic, maxSkewMs, maxTtlMs, providerSigner).	`RequestCreated` (PPC), descriptor/plan updates	Read by UI/Nodes/Consensus/Escrow.
APIEscrow	Payment	Holds SYL for PPC locks and Subscription purchases; snapshots BPS fee splits; on success/failure performs settlement/refund; maintains pull‑payment balances.	`Locked`, `Settled`, `Refunded`, `Withdrawn`	Reads plan/BPS from Registry; invoked by UI; called by Consensus on finalize.
APIConsensus	Finality	Tallies provider‑signed Snapshots from Nodes; enforces freshness, signer, quorum, and (optional) sequence monotonicity; finalizes success/failure and notifies Escrow.	`RequestRegistered`, `ResponseSubmitted`, `RequestFinalized`, `RequestFailed`, `ProviderEquivocation`	Reads per‑API params from Registry; may consult NodeRegistry for eligibility.
NodeRegistry	ACL/Staking	(Optional) Maintains active node set, stake, slashing and rewards for (mis)matching votes.	Slashing/reward events	Queried by Consensus for eligibility; holds/updates stakes.
EventLogger	Utility	Curates cross‑contract human‑readable logs for indexers/explorers.	Contract‑specific log events	Called by trusted contracts; read by indexers.
SylanToken	ERC‑20	Payment token SYL used for Escrow, staking, fees, and ecosystem.	Standard ERC‑20 events	Approved/Transferred by Escrow.
SylanStaking	Incentives	Optional staking for participants (Nodes/Providers) with reward logic separate from per‑request settlement.	Stake/Unstake/Reward events	Interacts with Token; may be referenced by NodeRegistry.
SylanVesting	Token mgmt	Linear/claiffed vesting schedules for team/investors; not in the request path.	Grants/Release events	Interacts with Token.
PresaleContract	Token sale	Optional presale/IDO mechanism for distributing SYL; not in the request path.	Purchase/Claim events	Interacts with Token; off‑path to Escrow.

All core contracts follow UUPS upgradeability with owner‑gated upgrades and pause/unpause circuit breakers.

Off‑chain components

Component	Role	Responsibilities
Provider API	Data origin	Serves raw data; should be deterministic for a given request; publishes response artifacts (or bytes) that hash to `contentHash`.
Provider Signer	Authority	EIP‑712 signer for `Snapshot { apiId, seqNo, providerTs, ttl, contentHash }`; held in HSM/hardware wallet; rotated via Registry flow.
Sylan Nodes	Execution & voting	Fetch descriptor → build request → retrieve Provider data → verify artifact hash → submit snapshot to Consensus → (optionally) pin artifacts to IPFS.
Indexers / Relayers	Observability	Subscribe to on‑chain events, materialize request states, serve dashboards/alerts, and help UIs correlate `requestId ↔ contentHash/pointerURI`.
Dashboard / SDKs	Client interface	Wallet connect; approve/lock/purchase flows; progress UI by following events; receipt & withdrawal UX.
IPFS/HTTP Storage	Content addressing	Host artifacts pointed to by `contentHash`. Hash, not location, provides integrity; multiple mirrors encouraged.

Cross‑component interactions (happy path)

Read: Client reads descriptorOf(apiId) and apiPlan(apiId) from AccessRegistry.
Lock/Purchase: Client approves SYL and either locks for PPC (lockForCall(apiId, requestHash, expiresAtMs)) or purchases a subscription.
Register: Escrow/Consensus register the request; RequestCreated/Registered are emitted.
Submit: Nodes submit provider‑signed Snapshots to APIConsensus.
Finalize: Consensus finalizes (quorum or expiry+grace) and notifies Escrow.
Settle: Escrow splits fee snapshot (Provider/NodePool/Platform) or refunds.
Withdraw: Recipients call withdraw() to pull their balances.

Key identifiers & data

apiId (bytes32) — listing identifier across Registry/Consensus/Escrow.
descriptor { uri, contentHash, updatedAt, version } — off‑chain metadata integrity anchor.
requestHash (bytes32) — canonical payload hash (client side) for PPC.
requestId — deterministic id created when locking/creating a request.
contentHash (bytes32) — digest of the concrete response artifact (or Merkle root).
pointerURI — optional retrieval hint (IPFS/HTTPS) associated with a snapshot.

Event surface (for UIs/indexers)

Watch these to drive UI state and analytics:

Escrow: Locked, Settled, Refunded, Withdrawn
Consensus: RequestRegistered, ResponseSubmitted, RequestFinalized, RequestFailed, ProviderEquivocation
Registry: descriptor/plan updates (activation, signer rotations)

Out of scope for this page

Addresses & ABI details → Architecture → Addresses & ABIs
Event signatures → Architecture → Events
Per‑contract specifics → Contracts section
Operational runbooks → Node and Provider sections