Security

This page is a conceptual security model for Sylan—what we protect, who we trust, and the guardrails that exist in contracts and operations. Implementation details (ABIs, exact modifiers) live in the Contracts section.

Threat model & trust boundaries

• Consumers fund requests or subscriptions. They must not lose funds to unauthorized settlement or replay.
• Providers authorize data via an EIP‑712 provider signer. Their infra must not be able to push arbitrary data without that signer.
• Nodes carry data and vote. A minority of nodes can be faulty or malicious; consensus must tolerate this.
• Protocol (contracts) is the final arbiter: verifies signatures/freshness, enforces plan rules, settles funds, and can be paused/upgraded by governance.

Trust boundaries

• On‑chain → verifies off‑chain inputs via hashes + signatures; it does not trust raw HTTP responses.
• Off‑chain → retrieves artifacts by pointer (e.g., IPFS/HTTPS) but accepts them only if the hash matches the signed snapshot.

On‑chain safety properties

Deterministic request scope

• Each PPC lock creates a deterministic requestId using (contract addr, chain id, apiId, consumer, per‑API nonce).
• Binds one requestHash with an expiresAtMs window → prevents late or replayed settlements.

Provider authorization (EIP‑712)

• Consensus accepts only provider‑signed snapshots. The recovered signer must equal the API’s providerSigner recorded in AccessRegistry.
• Freshness bounds: reject future‑dated snapshots (clock skew) and stale snapshots (TTL upper‑bound). These parameters are per‑API.

Finalization safety

• Two paths: Early quorum or expiry + grace. Both are idempotent.
• If the API is inactive at finalize time, consensus marks InactiveAPI and escrow refunds.
• Optional sequence monotonicity prevents regressions in finalized data.

Economic safety

• Escrow uses pull‑payments with per‑recipient balances and withdraw()—no untrusted external calls inside fund distribution.
• SafeERC20 + ReentrancyGuard are used where funds move; settlement/withdrawals are protected from reentrancy.
• BPS fee splits must sum to 10,000; otherwise a transaction reverts.
• Slashing (when enabled): mismatching nodes can lose stake (bps‑based), and honest nodes receive the redistributed amount.

Administrative safety

• All core contracts are UUPS‑upgradeable with owner‑gated upgrades and pause/unpause circuit breakers.
• EventLogger records human‑readable metadata from trusted contracts; the owner controls who can emit.

Off‑chain safety (Providers & Nodes)

Provider hardening

• Keep the provider signer key in a hardware wallet or HSM. Do not co‑locate it with HTTP serving infra.
• Use the signer rotation flow in AccessRegistry to rotate keys. A timelock can be enforced so clients and nodes have time to update.
• Sign compact Snapshots only; never sign raw payloads with secrets. Publish response artifacts so anyone can recompute the content hash.
• Prefer content‑addressed storage (IPFS, S3 with checksum headers). If compressing, hash the compressed bytes and document this in the descriptor.

Node hardening

• Stake above minStake for resilience; monitor unbonding status and reputation.
• Enforce one‑vote‑per‑request locally; cache submitted digests to avoid accidental duplicates.
• Verify: descriptor hash → provider signature → snapshot freshness → artifact content hash before voting.
• Alert on ProviderEquivocation and on repeated NoQuorum across an API.

Known attack classes & mitigations

Key & upgrade management (governance recommendations)

• Deployers/Owners: use a Gnosis Safe (>=2‑of‑3) for each proxy admin.
• Upgrade policy: publish a changelog + planned upgrade time; consider a 24–48h timelock for non‑critical changes.
• Emergency: have a runbook for pause (Escrow, Consensus, Registry) and public comms.
• Authorized callers: keep the EventLogger allow‑list tight; review after upgrades.

Operations & monitoring

• Index and watch: RequestCreated, RequestRegistered, ResponseSubmitted, RequestFinalized/Failed, Settled/Refunded, ProviderEquivocation.
• Alert on: repeated NoQuorum, sudden InactivateAPI transitions, sharp changes in quorum timing, spikes in refund rate, or high slash counts.
• Maintain dashboards for escrow balances, withdraw totals, node reputation, and API uptime.

Secure defaults & parameters (conceptual)

• Keep request expiry windows short (on the order of tens of seconds) with a grace cap on the order of minutes.
• Use per‑API skew and TTL that match the data domain (e.g., tighter for price feeds than for slow‑moving datasets).
• Enforce BPS sum = 10,000 at plan creation; prefer explicit per‑API BPS over global defaults when economics differ.

Hardening checklist

• Multisig owners for all upgradeable proxies; emergency pause tested.
• Provider signer in HSM/Hardware wallet; rotation playbook documented.
• SDK: canonical hashing for requestHash with test vectors.
• Node: verifies descriptor hash → EIP‑712 signature → snapshot freshness → artifact hash.
• Indexer alerts wired for equivocation, refund spikes, and quorum slippage.
• Privacy: no PII in on‑chain events; descriptors avoid secrets.
• Backups: descriptors/artifacts mirrored (IPFS pinning + HTTPS fallback).

What this page omits

• Full event and function signatures → see Architecture → Events and Contracts.
• Operational runbooks for Providers/Nodes → see Provider and Node sections.
• Tokenomics specifics (staking rewards, burn/treasury splits) → see Tokenomics.