Contracts — Overview

Repo: https://github.com/sylanproject/sylan-contracts

This section introduces the smart‑contract suite that powers Sylan. It describes what each contract is responsible for, how they compose, and shared concerns like upgradeability, pausing, and events. Individual ABI surfaces live on their respective pages.

All core contracts are UUPS‑upgradeable proxies. Interact with proxy addresses published under Architecture → Addresses & ABIs.

Contract map

* Calls are one‑way notifications from APIConsensus to APIEscrow, and (optionally) from Consensus to NodeRegistry for slashing/rewards.

Responsibilities (at a glance)

Contract	Purpose	Key reads/writes	Page
AccessRegistry	Source of truth for descriptors, plans (PPC/Subscription), and per‑API consistency/freshness params.	Read by UI, Nodes, Escrow, Consensus. Updates when provider changes metadata, signer, or activation.	/contracts/access-registry
APIEscrow	Holds funds for PPC locks and Subscription purchases; performs settlement/refund; maintains pull‑payment balances.	Writes `Locked/Settled/Refunded/Withdrawn`; reads plan & BPS snapshot; receives finalize notifications.	/contracts/api-escrow
APIConsensus	Tallies provider‑signed snapshots, enforces freshness/signature/quorum, and finalizes success/failure.	Emits `RequestRegistered/ResponseSubmitted/RequestFinalized/Failed`; notifies Escrow; may consult NodeRegistry.	/contracts/api-consensus
NodeRegistry	(Optional) Maintains active set, stake, slashing and rewards for Nodes.	Emits stake/unstake/slash/reward; queried by Consensus.	/contracts/node-registry
EventLogger	Curated, human‑readable event sink for protocol components.	Trusted callers log opaque bytes under a tag; indexers consume.	/contracts/event-logger
SylanToken	ERC‑20 used for payments, staking, and ecosystem flows.	Standard ERC‑20 reads; approved by Escrow; transferred on payouts.	/contracts/sylan-token
SylanStaking	Separate staking incentives (not per‑request settlement).	Moves SYL; may link to NodeRegistry reputation.	/contracts/sylan-staking
SylanVesting	Linear/cliff vesting schedules for team/investors.	Releases SYL over time; off‑path to Escrow.	/contracts/sylan-vesting
PresaleContract	(Optional) Presale/IDO mechanics for distributing SYL.	Accepts payment; allocates/claims SYL; off‑path to Escrow.	/contracts/presale

Shared design patterns

Upgradeability (UUPS)

Proxies follow EIP‑1967 storage slots; logic is upgradable via upgradeTo/upgradeToAndCall gated by the owner.
Use initializer functions instead of constructors (e.g., initialize(...), reinitialize(version) for new modules).
Upgrades should be governed by a multisig and (ideally) a timelock; publish upgrade notices in Deploy → Verifications.

Access control & pausing

Owner‑gated admin flows (upgrade, parameter changes, allowing emitters in EventLogger).
Pausable: Escrow/Consensus/Registry can be paused independently. UIs should surface paused state and block writes.

Reentrancy & accounting

Escrow uses pull‑payment balances and ReentrancyGuard on settlement/withdraw.
Fee snapshots (BPS) are taken at lock/purchase time to make settlement deterministic.

Time & units

All request‑lifecycle timestamps in events and params are milliseconds since Unix epoch (uint64).
Token amounts use 18 decimals (SYL).

Interfaces (read‑only contracts)

The codebase ships I* interfaces to help integration and testing:

IAccessRegistry — descriptor, plan, and per‑API param getters.
IAPIEscrow — lock/purchase/withdraw surfaces.
IAPIConsensus — submit/finalize, event structs.
INodeRegistry — staking/eligibility getters.
ISylanStaking, ISylanVesting, IEventLogger — auxiliary modules.

Link to minimal ABIs on Architecture → Addresses & ABIs for dapp usage.

Events (what to watch)

Key events are summarized under Architecture → Events. At minimum, indexers should track:

AccessRegistry.RequestCreated (PPC request birth)
APIConsensus.RequestRegistered/ResponseSubmitted/RequestFinalized/RequestFailed
APIEscrow.Locked/Settled/Refunded/Withdrawn
Optional: NodeRegistry stake/slash/reward, descriptor/plan updates, EventLogger tags

Invariants & checks

BPS sum = 10,000 across {providerBps, nodeBps, platformBps} or the tx reverts.
Active flag: Escrow and Consensus must respect isActive(apiId)—inactive APIs fail and PPC funds are refunded.
Signer match: Provider snapshot ecrecover address must equal providerSignerOf(apiId).
Seq monotonicity (optional): if enabled per API, finalized seqNo cannot regress.
Idempotency: settlement paths are safe to call again; no double spending.

Testing & verification checklist

Unit tests cover happy path and NoQuorum/InactiveAPI failures.
Event assertions for every state transition.
Reentrancy tests on settlement & withdraw.
UUPS storage gap & upgrade test (proxy → new impl).
Access control tests for admin flows (pause, BPS change, signer rotation).
Fuzz tests for expiresAtMs, ttl, maxSkewMs, and fork‑choice ties.

What this page omits

Full ABIs and parameter details → see each Contracts → Contract name page.
Addresses → Architecture → Addresses & ABIs.
Deep dives into hashing/signing → Concepts → Data Integrity and Consensus.