Architecture — On‑Chain vs Off‑Chain

This page defines what lives on‑chain (immutable/accountable) and what runs off‑chain (scalable/flexible), and why. Use this as a placement guide when building clients, nodes, and provider integrations.

Principles

Trust minimization: put verification and funds movement on‑chain; keep raw data off‑chain.
Cost & latency: on‑chain steps are gas‑bounded and slower; off‑chain steps are low‑latency and scalable.
Privacy: only hashes/IDs go on‑chain; payload bytes and PII remain off‑chain.

Responsibilities by layer

Layer	Runs where	Stores / Executes	Guarantees	Costs	Examples
AccessRegistry	On‑chain	API descriptors, plans (PPC/Subscription), per‑API freshness & consistency params, provider signer	Discoverability, integrity (`contentHash`), parameter source of truth	Gas to update; free to read off‑chain	`descriptorOf(apiId)`, `apiPlan(apiId)`
APIEscrow	On‑chain	Lock/purchase, settlement/refund, pull‑payment balances, fee BPS snapshot	Correct accounting, no reentrancy, idempotent settlement	Gas to lock/settle/withdraw	`lockForCall`, `purchaseSubscription`, `withdraw`
APIConsensus	On‑chain	Vote tally of provider‑signed Snapshots, finalize success/failure	Only Provider‑authorized data can win; quorum/expiry rules	Gas per snapshot/finalize	`submitSnapshot`, `finalize`
NodeRegistry	On‑chain (optional)	Active set, stake, slashing/rewards	Node eligibility & incentives	Gas to (un)stake/slash	`stake`, `slash`
EventLogger	On‑chain	Curated human‑readable events	Auditability	Minimal	Protocol‑emitted logs
Provider API	Off‑chain	Raw responses; publishes artifacts (or bytes) that hash to `contentHash`	Performance, business logic	Infra cost	REST/GraphQL, streams
Provider Signer	Off‑chain	EIP‑712 signing of `Snapshot`	Authorization	HSM/HW wallet	Signs `{ apiId, seqNo, providerTs, ttl, contentHash }`
Sylan Nodes	Off‑chain	Fetch, verify, submit snapshots; optional artifact pinning	Throughput; replication	Infra cost	Submit to Consensus
Storage (IPFS/HTTPS)	Off‑chain	Host artifacts addressed by `contentHash`	Integrity via hash match	Storage/bandwidth	`ipfs://...`, `https://...`
Indexers/Dashboard/SDK	Off‑chain	Listen to events; render UX; derive analytics	UX/state materialization	App infra	Marketplace & receipts

Contract addresses & ABIs are listed under Architecture → Addresses & ABIs. Event signatures under Architecture → Events.

What lives where (by data type)

Identifiers (on‑chain & cross‑layer): apiId (bytes32), requestId (deterministic), requestHash (bytes32), contentHash (bytes32), optional pointerURI.
Economic state (on‑chain): escrow balances, fee snapshots, staking balances, subscription purchases.
Policy/params (on‑chain): plans (price/duration/callLimit), BPS splits, maxSkewMs, maxTtlMs, seqMonotonic, providerSigner, activation flags.
Payload bytes (off‑chain): HTTP/WS responses, bulk files, Merkle trees, logs/metrics.
Artifacts (off‑chain, content‑addressed): compressed JSON/CBOR/Parquet, CSVs, or merklized chunks that hash to contentHash.

Flow with boundaries (happy path)

Failure modes & who recovers

Scenario	What fails	Expected behavior	Who fixes
Provider outage	Off‑chain data source	Nodes cannot gather votes → NoQuorum; PPC refunds	Provider restores service
Node churn	Off‑chain voters	Early quorum may not be reached; deadline path still finalizes	Node operators scale/replace
Chain congestion	On‑chain txs	Snapshot/finalize delayed; choose wider expiry windows	Users set `expiresAtMs` prudently; nodes use higher gas
Signer compromised	Off‑chain key	Rotate `providerSigner` via Registry; alert consumers	Provider governance
Descriptor drift	Off‑chain docs/schema	Version bump; `contentHash` change; clients refresh	Provider + clients

Latency & gas guidance (conceptual)

Client expiry: set expiresAtMs to allow for fetch + vote + finalize under normal network load; cap by maxRequestExpiryMs.
Snapshot size: keep artifacts small or merklized so contentHash represents a compact root; only the hash is on‑chain.
Event‑driven UI: drive state from RequestRegistered → ResponseSubmitted → RequestFinalized/RequestFailed → Settled/Refunded.

Privacy & compliance defaults

Never emit raw payloads on‑chain; emit only hashes and IDs.
Avoid PII in descriptors or artifacts; if unavoidable, encrypt at rest off‑chain and publish the hash of the ciphertext.

Upgrade & governance boundaries

On‑chain upgrades via UUPS and multisig owners; subject to pause/unpause.
Off‑chain components (Nodes, Provider infra, indexers) can deploy continuously but must remain protocol‑compatible (hashing, EIP‑712, params).

Checklist

On‑chain: everything needed to verify & settle; nothing that leaks data.
Off‑chain: deterministic hashing, signature verification, artifact pinning.
SDKs: boundary‑aware helpers (request hashing, snapshot verify, event subscriptions).
Ops: monitors for on‑chain events + off‑chain uptime.