diff --git a/credible/architecture-linea.mdx b/credible/architecture-linea.mdx new file mode 100644 index 0000000..b02266d --- /dev/null +++ b/credible/architecture-linea.mdx @@ -0,0 +1,70 @@ +--- +title: 'Linea / Besu Integration' +description: 'High-level integration of the Credible Layer with Linea via Besu plugins' +--- + +This page summarizes the Linea integration pattern at a high level. It focuses on interface boundaries +and the enforcement flow without internal implementation details. + +## Integration Pattern + +Linea uses a **plugin pattern** that integrates directly with the Besu node through its plugin system +and delegates assertion execution to a sidecar process. + +Key characteristics: + +- **Plugin-based enforcement**: Besu plugins hook into block building to validate transactions +- **Sidecar execution**: Assertions run in the Credible Layer sidecar alongside the node +- **Low-latency flow**: Validation happens during block building and returns a valid/invalid decision + +## System Overview + +```mermaid +--- +title: Linea Besu Integration (High Level) +--- +flowchart LR + subgraph BesuNode["Linea Besu Node"] + TxPool["Transaction Pool"] + Builder["Block Builder"] + Plugin["Credible Layer Plugin"] + end + + subgraph SidecarGroup["Enforcer Sidecar"] + SidecarSvc["Assertion Enforcer"] + Engine["Assertion Execution Engine"] + Store["Assertion Store"] + SidecarSvc --> Engine + Engine --> Store + end + + Registry["Registry Data
(On-Chain Events)"] + DA["Assertion DA"] + + TxPool --> Builder + Builder --> Plugin + Plugin --> SidecarSvc + SidecarSvc --> Plugin + SidecarSvc --> Registry + SidecarSvc --> DA +``` + +## Validation Flow + +1. The block builder selects a candidate transaction. +2. The plugin sends the transaction to the sidecar for assertion validation. +3. The sidecar executes applicable assertions and returns a decision. +4. The block builder includes valid transactions and drops invalid ones. + +## Notes + +- The plugin uses Besu’s transaction selection hooks to validate transactions during block building. +- The sidecar relies on registry data (from on-chain events) and assertion data to determine applicable assertions. +- This integration does not change core protocol rules; it runs alongside the existing block builder. + +## Related Docs + +- [Network Integration Overview](/credible/network-integration) +- [Assertion Enforcer](/credible/assertion-enforcer) +- [Assertion DA](/credible/assertion-da) +- [OP Stack](/credible/architecture-op-stack) diff --git a/credible/architecture-op-stack.mdx b/credible/architecture-op-stack.mdx index 5ee39e8..6ad3a88 100644 --- a/credible/architecture-op-stack.mdx +++ b/credible/architecture-op-stack.mdx @@ -5,6 +5,14 @@ description: 'OP Stack specific implementation of the Credible Layer' The OP Stack implementation uses [Rollup-Boost](https://github.com/flashbots/rollup-boost) to connect an external sidecar assertion validation components with the L2 sequencer through a bridge proxy. + +For the general integration path, see [Network Integration Overview](/credible/network-integration). + + + +Looking for the Besu/Linea pattern? See [Linea / Besu Integration](/credible/architecture-linea). + + ## Architecture Diagram ```mermaid @@ -39,9 +47,9 @@ end SequencerEL --> |Fallback Blocks + Validation| RollupBoost AssertionDA --> |Serve Assertions| AssertionEnforcerBlockBuilder -AssertionEnforcerCLI --> |Submit Assertions| AssertionEnforcerDapp -AssertionEnforcerDapp --> |OAuth| AssertionEnforcerCLI -AssertionEnforcerDapp --> |Submit Assertions| AssertionDA +AssertionEnforcerCLI --> |Store bytecode| AssertionDA +AssertionEnforcerCLI --> |Auth + submit metadata| AssertionEnforcerDapp +AssertionEnforcerDapp --> |Fetch assertions| AssertionDA AssertionEnforcerEL <--> |Pulls State + Txs| SequencerEL AssertionEnforcerEL <--> |Provide Best Transactions| AssertionEnforcerBlockBuilder diff --git a/credible/architecture-overview.mdx b/credible/architecture-overview.mdx index b44023e..1784c33 100644 --- a/credible/architecture-overview.mdx +++ b/credible/architecture-overview.mdx @@ -22,7 +22,7 @@ The Credible Layer consists of four core components: The Credible Layer is a **sidecar security infrastructure** that validates transactions against developer-defined security rules (assertions) before they are included in blocks. As a sidecar, it runs alongside the L2 network's main components, intercepting transactions during block building and ensuring they don't violate any deployed security rules. -The Assertion Enforcer is operated by the network's sequencer. Networks that integrate the Credible Layer run this sidecar as part of their sequencer infrastructure. This means you're not adding new trust assumptions: if you trust the network to include your transactions, you can trust it to enforce your assertions. +The Assertion Enforcer is operated by the network's block builder or sequencer. Networks that integrate the Credible Layer run this sidecar as part of their block production infrastructure. This means enforcement does not rely on external execution services beyond the network you already trust to include transactions. ### System Architecture @@ -43,7 +43,7 @@ flowchart LR subgraph network["Network"] direction LR - VALIDATOR["Network Validator"] + VALIDATOR["Block Builder / Sequencer"] REGISTRY["Credible Layer
Contracts"] end @@ -57,7 +57,7 @@ flowchart LR CLI -->|"Submit"| DAPP DAPP -->|"Deploy"| REGISTRY - VALIDATOR -->|"Transaction"| PhEVM + VALIDATOR -->|"Candidate Tx"| PhEVM PhEVM -->|"Valid/Invalid"| VALIDATOR PhEVM -.->|"Fetch"| DA PhEVM -.->|"Check"| REGISTRY @@ -77,16 +77,16 @@ flowchart LR The diagram shows two main flows: -**Development Flow**: Developers use [`pcl`](/credible/store-submit-assertions) to develop and test assertions. `pcl` stores assertion code in [Assertion DA](/credible/assertion-da), then submits to the [Credible dApp](/credible/dapp-overview). The dApp deploys assertions to the on-chain [Credible Layer Contracts](/credible/credible-layer-contracts). +**Development Flow**: Developers use [`pcl`](/credible/store-submit-assertions) to develop and test assertions. `pcl` stores assertion code in [Assertion DA](/credible/assertion-da), then submits to the [Credible dApp](/credible/dapp-overview). The dApp deploys assertions to the on-chain [Credible Layer Contracts](/credible/credible-layer-contracts) so they can be enforced by the network. -**Runtime Flow**: The network validator sends transactions to the [Assertion Enforcer](/credible/assertion-enforcer) during block production. The enforcer fetches relevant assertions and executes them via [PhEVM](/credible/phevm). Valid transactions are included in blocks; invalid transactions are dropped. +**Runtime Flow**: The block builder or sequencer sends transactions to the [Assertion Enforcer](/credible/assertion-enforcer) during block production. The enforcer uses its registry snapshot (from on-chain events) and cached assertion bytecode (from [Assertion DA](/credible/assertion-da)) to execute relevant assertions via [PhEVM](/credible/phevm). Valid transactions are included in blocks; invalid transactions are dropped. ### How It Works 1. **Assertion Deployment**: Developers write and submit assertions through `pcl` and the dApp, which are stored in Assertion DA and deployed on-chain 2. **Transaction Validation**: The network sends transactions to the Assertion Enforcer during block production 3. **Assertion Execution**: The Assertion Enforcer simulates each transaction and validates it against relevant assertions using PhEVM -4. **Validation Results**: The Assertion Enforcer returns valid/invalid results to the network validator +4. **Validation Results**: The Assertion Enforcer returns valid/invalid results to the block builder or sequencer 5. **Security Enforcement**: Only valid transactions are included in blocks, preventing security violations before they reach the blockchain ## Transaction Flow @@ -99,10 +99,11 @@ title: Transaction Validation Flow --- flowchart LR USER["User"] -->|"Submits Transaction"| MP["Mempool"] - MP --> SIDECAR["Assertion Enforcer
(Sidecar)"] - - SIDECAR -->|"Valid"| BLOCK["Block"] + MP --> BUILDER["Block Builder / Sequencer"] + BUILDER -->|"Candidate Tx"| SIDECAR["Assertion Enforcer
(Sidecar)"] + SIDECAR -->|"Valid"| BUILDER SIDECAR -->|"Invalid"| DROP["Dropped"] + BUILDER -->|"Include"| BLOCK["Block"] classDef user fill:#9e9e9e,stroke:#616161,stroke-width:2px,color:#fff classDef mempool fill:#64b5f6,stroke:#1976d2,stroke-width:2px,color:#fff @@ -127,6 +128,42 @@ flowchart LR The Assertion Enforcer is integrated with the block builder. During block production, the block builder invokes the Assertion Enforcer to validate transactions before including them. +## Incident Lifecycle (Public View) + +When an assertion is violated, the incident is recorded and exposed for transparency and alerts. + +```mermaid +--- +title: Incident Lifecycle +--- +flowchart LR + ENFORCER["Assertion Enforcer"] --> DAPP["Credible dApp"] + DAPP --> DASH["Transparency Dashboard"] + DAPP --> ALERTS["Slack/PagerDuty Alerts"] + + classDef enforcer fill:#7b1fa2,stroke:#4a148c,stroke-width:2px,color:#fff + classDef dapp fill:#388e3c,stroke:#1b5e20,stroke-width:2px,color:#fff + classDef output fill:#0288d1,stroke:#01579b,stroke-width:2px,color:#fff + + class ENFORCER enforcer + class DAPP dapp + class DASH,ALERTS output +``` + +## Integration Paths + + + + How protocols deploy and manage assertions + + + How networks and sequencers integrate enforcement + + + High-level component boundaries and dependencies + + + For details on the assertion validation process, see [Assertion Enforcer](/credible/assertion-enforcer#validation-process). ## System Components @@ -179,4 +216,7 @@ For concrete assertion examples and real-world use cases, explore the [Assertion Detailed reference for assertion functions + + Guarantees, assumptions, and failure modes + diff --git a/credible/assertion-da.mdx b/credible/assertion-da.mdx index a2a3d1b..7893b7f 100644 --- a/credible/assertion-da.mdx +++ b/credible/assertion-da.mdx @@ -59,7 +59,7 @@ pcl store MyAssertion 2. Uploads flattened source code and compiler options to Assertion DA 3. Returns the assertion ID (Keccak256 hash of the bytecode) and DA prover signature -Only the contract owner (the address returned by the contract's `owner()` function) can deploy, modify, or remove assertions for their contract. This is enforced on-chain by the Credible Layer smart contracts, which verify ownership before allowing any assertion management operations. During the early phase of the project, there is also a manual whitelist in place. Ownership verification will be expanded and improved in future versions to support additional ownership patterns and multisig integration. See [Ownership Verification](/credible/ownership-verification) for details. +Only authorized admins can deploy, modify, or remove assertions for their contracts. This is enforced on-chain by the Credible Layer smart contracts, which verify administrative authority (such as owner-based checks or approved allowlists) before allowing assertion management operations. Ownership verification will be expanded and improved in future versions to support additional ownership patterns and multisig integration. See [Ownership Verification](/credible/ownership-verification) for details. ### Retrieving Assertions @@ -108,7 +108,7 @@ The protocol intentionally omits bytecode validation because: **Integrity**: The Keccak256 hash verification ensures assertions haven't been modified. Each assertion ID uniquely corresponds to its bytecode. -**Transparency**: All assertions are publicly accessible, enabling users and auditors to verify security measures. +**Transparency**: Assertions can be retrieved via Assertion DA, enabling users and auditors to verify security measures. **Incentive Alignment**: Invalid assertions only harm the developer who submitted them, as they will fail execution deterministically. diff --git a/credible/assertion-enforcer.mdx b/credible/assertion-enforcer.mdx index bde4c49..9d4e82b 100644 --- a/credible/assertion-enforcer.mdx +++ b/credible/assertion-enforcer.mdx @@ -7,9 +7,9 @@ The Assertion Enforcer is a sidecar component that validates transactions agains ## Role in the System -The Assertion Enforcer sits between the mempool and block production: +The Assertion Enforcer operates inside the block production pipeline: -1. Receives transactions from the network validator +1. Receives candidate transactions from the block builder or sequencer 2. Identifies which assertions apply to each transaction 3. Invokes [PhEVM](/credible/phevm) to execute assertions against transaction states 4. Returns validation results (valid/invalid) to the network @@ -20,7 +20,7 @@ The Assertion Enforcer sits between the mempool and block production: As a [sidecar](/credible/glossary#sidecar), the Assertion Enforcer: - **Operates independently** from the main L2 infrastructure -- **Integrates without code changes** to the sequencer +- **Integrates alongside block builders** without changing core protocol rules - **Scales separately** from the main network components - **Fails gracefully** without affecting L2 operations @@ -79,7 +79,7 @@ flowchart LR ### Step-by-Step -1. **Identify Relevant Assertions**: The Assertion Enforcer queries the [on-chain registry](/credible/credible-layer-contracts) to find which assertions apply to the contracts the transaction interacts with +1. **Identify Relevant Assertions**: The Assertion Enforcer consults registry data (indexed from [on-chain events](/credible/credible-layer-contracts)) to find which assertions apply to the contracts the transaction interacts with 2. **Fetch Assertion Bytecode**: Assertion bytecode is retrieved from internal cache (populated from [Assertion DA](/credible/assertion-da) when assertions are deployed) @@ -99,9 +99,16 @@ flowchart LR The Assertion Enforcer integrates with block builders to ensure only valid transactions enter blocks: - Transactions that would violate assertions are dropped before block inclusion -- The network validator receives clear valid/invalid signals +- The block builder or sequencer receives clear valid/invalid signals - Block production continues normally with validated transactions +## Operational Expectations (Public) + +- **Non-invasive**: Runs alongside existing block builders without changing consensus rules +- **Deterministic**: Results are based on on-chain state and assertion code only +- **Staging support**: Networks can validate assertions before enforcing them in production +- **Transparent outcomes**: Incidents are visible in the dApp and dashboard + ## Forced Inclusion Transactions Forced inclusion transactions (such as L1→L2 deposits) require special handling since they must be included regardless of assertion results. The Credible Layer has mitigation pathways for these scenarios. @@ -119,3 +126,13 @@ To ensure high-performance validation, the Assertion Enforcer maintains an inter This caching strategy ensures validation latency doesn't impact block production times. +## Learn More + + + + High-level integration for networks and sequencers + + + Guarantees, assumptions, and failure modes + + diff --git a/credible/credible-introduction.mdx b/credible/credible-introduction.mdx index 0ef1822..d3c16df 100644 --- a/credible/credible-introduction.mdx +++ b/credible/credible-introduction.mdx @@ -27,15 +27,24 @@ The Credible Layer is security infrastructure that enables developers to link se Write and deploy your first assertion. Get from zero to protected in minutes. + + A quick checklist for dApps and networks. + Non-technical overview of how the Credible Layer prevents exploits. Technical deep dive into system design, transaction flow, and integration requirements. + + High-level adoption flow for protocol teams. + Explore assertion patterns and see how real-world hacks could have been prevented. + + High-level integration for networks and sequencers. + ## Key Benefits @@ -43,7 +52,7 @@ The Credible Layer is security infrastructure that enables developers to link se - **Pre-execution prevention** — Exploits are blocked before they execute, not detected after - **No contract changes** — Add protection to any contract, including immutable ones - **Transparent & verifiable** — All rules are public Solidity, auditable by anyone -- **No external dependencies** — Runs natively within the network, no SaaS or APIs +- **No external execution services** — Enforcement runs within the network’s block-building flow - **Zero false positives** — Binary enforcement based on your rules, no AI guessing ## Community & Support diff --git a/credible/credible-layer-contracts.mdx b/credible/credible-layer-contracts.mdx index e987395..1b842aa 100644 --- a/credible/credible-layer-contracts.mdx +++ b/credible/credible-layer-contracts.mdx @@ -9,6 +9,10 @@ The Credible Layer Contracts are the on-chain smart contracts that power the pro The contracts are open source and available on [GitHub](https://github.com/phylaxsystems/credible-layer-contracts). + +For how these contracts fit into the overall system, see [Interface Overview](/credible/interfaces-overview). + + ## Components ```mermaid diff --git a/credible/credible-layer-overview.mdx b/credible/credible-layer-overview.mdx index 4ef4719..7ae84e7 100644 --- a/credible/credible-layer-overview.mdx +++ b/credible/credible-layer-overview.mdx @@ -15,7 +15,7 @@ Phylax's real-time security system detects and pre-emptively removes exploits be At a glance: -- **Security rules** are defined by the protocol team and deployed as on-chain [assertions](/credible/glossary#assertion) +- **Security rules** are defined by the protocol team and deployed on-chain as [assertions](/credible/glossary#assertion) - **The network** validates every transaction against relevant assertions before adding them to blocks - **Invalid transactions** are [dropped](/credible/glossary#drop). If an assertion fails, the transaction never executes @@ -55,6 +55,17 @@ Assertions enable a wide range of security and compliance use cases: For concrete examples and implementations, explore the [Assertions Book](/assertions-book/assertions-book-intro). +## Who It's For + + + + Deploy and manage assertions to protect your contracts + + + Integrate enforcement into block building + + + ## How It Works ### Defining Security Rules @@ -163,6 +174,8 @@ For the full technical flow, see [Architecture](/credible/architecture-overview) The Credible Layer is designed as neutral middleware that preserves decentralization for both dApps and networks. Learn more about [why neutrality matters](/credible/neutrality). +For interface boundaries and integration touchpoints, see [Interface Overview](/credible/interfaces-overview). + ## Next Steps Ready to dive deeper? diff --git a/credible/dapp-incidents.mdx b/credible/dapp-incidents.mdx index a7e63c3..28f255b 100644 --- a/credible/dapp-incidents.mdx +++ b/credible/dapp-incidents.mdx @@ -5,6 +5,11 @@ description: 'View incidents prevented by the Credible Layer' Incidents show when transactions were dropped because they violated assertions protecting contracts. This happens when a transaction that interacted with an assertion-protected contract was dropped by the [Enforcer](/credible/glossary#assertion-enforcer) because it caused an assertion to revert. + +For the end-to-end flow, see the incident lifecycle diagram in +[Architecture Overview](/credible/architecture-overview#incident-lifecycle-public-view). + + ## How Incidents Are Grouped An incident represents the invalidation of an assertion over a one-hour time period. Multiple dropped transactions can belong to the same incident if they violate the same assertion within that window. @@ -101,4 +106,3 @@ Incident viewing is read-only. You cannot modify or delete incident records. Understand how assertion validation works - diff --git a/credible/dapp-integration.mdx b/credible/dapp-integration.mdx new file mode 100644 index 0000000..dd2f7bb --- /dev/null +++ b/credible/dapp-integration.mdx @@ -0,0 +1,70 @@ +--- +title: 'dApp Integration Overview' +description: 'High-level integration path for protocols adopting the Credible Layer' +--- + +This page outlines how protocol teams adopt the Credible Layer to protect their smart contracts. +It focuses on the minimum steps and interfaces needed to get protected. + +## Adoption Workflow + +Teams follow the same underlying steps. The CLI is used to author and store assertions, while the dApp +is used to manage deployments and monitoring. + +- **CLI authoring**: write assertions locally and store bytecode +- **dApp management**: link contracts, stage or deploy, and monitor incidents + +## End-to-End Flow + +```mermaid +--- +title: Protocol Adoption Flow +--- +flowchart LR + Dev[Protocol Team] --> Assertion[Write Assertions] + Assertion --> DA[Assertion DA] + Assertion --> Dapp[Credible dApp] + Dapp --> Registry[On-Chain Registry] + Registry --> Enforcer[Assertion Enforcer] + Enforcer --> Outcome[Block Inclusion Decision] + Outcome --> Incidents[Incidents + Dashboard] +``` + +## What You Control + +- Which assertions protect which contracts +- Staging vs production deployments +- Incident notification routing and monitoring + +## Deployment Modes + +- **Staging**: test and iterate on assertions without impacting production users +- **Production**: enforce assertions at the network level for real transactions + +Learn more about ownership checks in [Ownership Verification](/credible/ownership-verification). + +## What Users Can Verify + +- Which assertions are active for a protocol +- On-chain registry entries and transparency views +- Incident history for protected contracts + +## What Successful Rollout Looks Like + +- Assertions cover critical protocol invariants and admin operations +- Staging assertions are validated before moving to production +- Teams review incidents and iterate on coverage over time + +## Next Steps + + + + Step-by-step deployment guide + + + Learn how assertions work and how to write them + + + Understand how the dApp is used by teams and users + + diff --git a/credible/dapp-integrations.mdx b/credible/dapp-integrations.mdx index 38a39e3..2caced1 100644 --- a/credible/dapp-integrations.mdx +++ b/credible/dapp-integrations.mdx @@ -5,6 +5,10 @@ description: 'Configure Slack and PagerDuty to receive real-time incident notifi Set up Slack and PagerDuty integrations to receive notifications when [assertion incidents](/credible/dapp-incidents) occur in your Credible Layer projects. + +Looking for the high-level adoption flow? See [dApp Integration Overview](/credible/dapp-integration). + + ## Accessing Integration Settings 1. Navigate to your project in the Credible Layer dashboard @@ -160,4 +164,3 @@ Removing an integration stops all notifications but does not delete historical d Create assertions for your contracts - diff --git a/credible/dapp-overview.mdx b/credible/dapp-overview.mdx index 47fc800..4178e99 100644 --- a/credible/dapp-overview.mdx +++ b/credible/dapp-overview.mdx @@ -5,7 +5,7 @@ description: 'Overview of the Credible Layer dApp and its role in the Credible L The Credible Layer dApp is the interface for managing assertions and monitoring incidents. Protocol teams use it to create projects, link contracts, and deploy assertions to protect their contracts. When deploying assertions, teams choose between Staging (for testing) or Production (for active protection). Users, investors, and researchers use it to review which assertions protect specific protocols. -When you create a project and deploy assertions through the dApp, those assertions are deployed on-chain. Network validators use this registry to validate every transaction against your assertions before including them in blocks. +When you create a project and deploy assertions through the dApp, those assertions are deployed on-chain. Block builders or sequencers use this registry to validate transactions against your assertions before including them in blocks. ## Core Components @@ -27,7 +27,7 @@ The [Incidents](/credible/dapp-incidents) page tracks assertion violations that ## Authentication -To use project management features, you need to authenticate through [`pcl`](/credible/cli-reference#auth). The dApp uses OAuth-based authentication integrated with `pcl`, ensuring secure access through wallet connection. +To use project management features, you need to authenticate through [`pcl`](/credible/cli-reference#auth). The dApp uses a `pcl`-based authentication flow with wallet connection to enable secure access. Authentication is required to create and manage projects. See the [Deploy Assertions guide](/credible/deploy-assertions-dapp#step-1-authenticate) for step-by-step authentication instructions. @@ -64,4 +64,7 @@ Authentication is required to create and manage projects. See the [Deploy Assert Understand ownership requirements + + High-level adoption flow for protocol teams + diff --git a/credible/dapp-projects.mdx b/credible/dapp-projects.mdx index 0272e9b..4070353 100644 --- a/credible/dapp-projects.mdx +++ b/credible/dapp-projects.mdx @@ -27,8 +27,8 @@ To create a new project: 4. Click "Continue" 5. Add contract addresses: - Enter each contract address you want to protect - - Only contracts where you are the `owner` can be added - - The dApp verifies ownership by calling the `owner()` function + - Only contracts where your wallet is authorized can be added + - The dApp verifies admin access via the network's admin verifier (often owner-based) 6. Review your project details 7. Click "Save and publish" to create the project @@ -37,9 +37,9 @@ To create a new project: -Only the owner of a contract can create a project for it. Ensure your contract implements an `owner()` function that returns the current owner address. See [Ownership Verification](/credible/ownership-verification) for details. +Only authorized admins can create a project for a contract. Most deployments use owner-based verification by default, but some networks can use allowlists. See [Ownership Verification](/credible/ownership-verification) for details. -For contracts without the `owner()` interface, a Manual Verification Request process is available. +For contracts that don't pass the default verifier, a Manual Verification Request process may be available. ## Managing Projects @@ -117,4 +117,3 @@ The project dashboard provides a unified view of your project's security: `pcl` command reference - diff --git a/credible/dapp-transparency-dashboard.mdx b/credible/dapp-transparency-dashboard.mdx index a3045ad..ddb7c2c 100644 --- a/credible/dapp-transparency-dashboard.mdx +++ b/credible/dapp-transparency-dashboard.mdx @@ -5,6 +5,11 @@ description: 'Browse and analyze all projects and their active assertions' The Transparency Dashboard is a public interface that displays all projects registered on the Credible Layer, their linked contracts, and the assertions protecting them. + +For a high-level view of how the dApp interfaces with the rest of the system, see +[Interface Overview](/credible/interfaces-overview). + + ## Features ### Browse Projects @@ -41,6 +46,12 @@ View all projects and their details: - Learn from existing assertion implementations - Copy and adapt assertion patterns for your own protocol +## Why Users Trust Protected dApps + +- **Public registry**: Assertions and protected contracts are visible on-chain +- **Transparent enforcement**: Dropped transactions surface as incidents +- **Auditable rules**: Assertions are published Solidity, not opaque policy + ## Next Steps @@ -57,4 +68,3 @@ View all projects and their details: Learn how to write assertions - diff --git a/credible/deploy-assertions-dapp.mdx b/credible/deploy-assertions-dapp.mdx index a7afa29..0458582 100644 --- a/credible/deploy-assertions-dapp.mdx +++ b/credible/deploy-assertions-dapp.mdx @@ -50,8 +50,8 @@ Authentication links your wallet address with your `pcl` session, allowing you t 4. Add contract addresses: - Enter each contract you want to protect - - Only contracts where you are the `owner` can be added - - The dApp verifies ownership by calling `owner()` on each contract + - Only contracts where your wallet is authorized can be added + - The dApp verifies admin access via the network's admin verifier (often owner-based) 5. Review and click "Save and publish" @@ -60,7 +60,7 @@ Authentication links your wallet address with your `pcl` session, allowing you t -Only the contract owner can create a project for it. See [Ownership Verification](/credible/ownership-verification) for details on verification methods. +Only authorized admins can create a project for a contract. See [Ownership Verification](/credible/ownership-verification) for details on verification methods. ## Step 3: Store and Submit Your Assertion @@ -122,7 +122,7 @@ After deployment, manage assertions through your project dashboard: | Error | Solution | |-------|----------| -| "Contract ownership verification failed" | Ensure your contract has `owner()` and you're connected with the owner wallet | +| "Contract ownership verification failed" | Ensure your wallet passes the admin verifier (often `owner()`) or request manual verification if available | | "Assertion already exists" | Use a different name or update the existing assertion | | "Authentication expired" | Run `pcl auth login` to refresh | diff --git a/credible/evaluate-credible-layer.mdx b/credible/evaluate-credible-layer.mdx new file mode 100644 index 0000000..ac2f08f --- /dev/null +++ b/credible/evaluate-credible-layer.mdx @@ -0,0 +1,39 @@ +--- +title: 'Evaluate Credible Layer' +description: 'A quick checklist for dApps and networks evaluating Credible Layer' +--- + +This checklist helps teams evaluate whether the Credible Layer is a fit for their protocol or network. + +## For Protocol Teams (dApps) + +- Do we have invariants that should never be violated? +- Can we encode those rules as assertions in Solidity? +- Do we want pre-execution protection rather than post-mortem monitoring? +- Are we comfortable with transparent, public rules? +- Do we have a team to monitor incidents and iterate on rules? + +## For Networks & Sequencers + +- Can we integrate an external enforcer into block building? +- Do we want a policy layer for transaction admission? +- Do we want to offer protocol teams optional enforcement? +- Do we have monitoring and incident review workflows? + +## Decision Support + +If you answered “yes” to most of the above, Credible Layer is likely a good fit. + +## Next Steps + + + + High-level adoption for protocol teams + + + High-level adoption for networks and sequencers + + + System components and transaction flow + + diff --git a/credible/faq.mdx b/credible/faq.mdx index f546b67..5d67514 100644 --- a/credible/faq.mdx +++ b/credible/faq.mdx @@ -14,7 +14,7 @@ our [Telegram](https://t.me/phylax_credible_layer). ### What is the Phylax Credible Layer? The Credible Layer is a network extension that enables developers to link security rules to their smart contracts on-chain. -These rules are defined in Solidity, executed off-chain, and enforced on-chain. Since these rules are verifiable, apps can turn implicit security assumptions into an explicit security posture using our transparency dashboard so that users can trust the apps they use. +These rules are defined in Solidity, executed off-chain, and enforced by the network during block building. Since these rules are verifiable, apps can turn implicit security assumptions into an explicit security posture using our transparency dashboard so that users can trust the apps they use. **Learn More:** - [Credible Layer Overview](/credible/credible-layer-overview) - Non-technical introduction @@ -25,7 +25,7 @@ There are several key advantages: 1. **Off-chain Execution**: Rules that would be too expensive or impossible to express on-chain due to gas costs and limits can be implemented easily as assertions as they are run off-chain. Our current benchmarks show around 1000x efficiency gains. 2. **Simpler Security Model**: By writing invariants that define a state to prevent instead of every edge case that would lead there, you simplify and strengthen your protocol. If you are confused about what an invariant is, read on 👇🏻 -3. **No Redeployment, downtime or APIs**: Add new security rules without modifying your existing contracts. You can even add rules to immutable contracts. To learn how this is possible read the [How do you extend the validation logic of the sequencer to the dApp?](#how-do-you-extend-the-validation-logic-of-the-sequencer-to-the-dapp) section below. +3. **No redeployment or downtime**: Add new security rules without modifying your existing contracts. You can even add rules to immutable contracts. To learn how this is possible read the [How do you extend the validation logic of the sequencer to the dApp?](#how-do-you-extend-the-validation-logic-of-the-sequencer-to-the-dapp) section below. **Learn More:** - [Credible Layer Overview - Use Cases](/credible/credible-layer-overview#use-cases) @@ -36,7 +36,7 @@ The Credible Layer offers several key advantages: 1. **Deterministic Prevention**: Binary enforcement with zero false positives rather than AI/heuristic guessing 2. **Pre-execution Protection**: Stop hacks during sequencing rather than detecting after damage -3. **Network-Native Security**: Protocol-controlled rules enforced by the network itself, with no external dependencies or single points of failure +3. **Network-Native Security**: Protocol-controlled rules enforced by the network itself, without relying on external execution services 4. **Transparent Enforcement**: Public, verifiable Solidity rules rather than opaque algorithms 5. **Instant Deployment**: Add new protections without contract modifications, downtime, or governance votes @@ -60,7 +60,7 @@ It is a useful tool for end users as they can verify the security guarantees of - [Glossary - Transparency Dashboard](/credible/glossary#transparency-dashboard) ### Is the Credible Layer a SaaS protocol? -No. We are a permissionless protocol that enables hack definition and prevention. No APIs for dApps. No points of failure. No additional trust assumptions. +No. We are a permissionless protocol that enables hack definition and prevention. Enforcement does not rely on external execution services, and protocols do not need to trust third parties beyond the network itself. **Learn More:** - [Credible Layer Overview - Why Neutrality Matters](/credible/credible-layer-overview#why-neutrality-matters) @@ -71,7 +71,7 @@ No. We are a permissionless protocol that enables hack definition and prevention ## Technical Details ### What exactly is an assertion? -An assertion is a Solidity contract, that defines an invariant about your protocol, some state you want to prevent, and that is stored on-chain. You can think of it as an inverse intent - you define the state you don't want to occur without specifying or caring about all the specific vectors that could lead to it. +An assertion is a Solidity contract that defines an invariant about your protocol, some state you want to prevent. Its identifier and registry entry are stored on-chain, while bytecode is stored in Assertion DA for enforcement. You can think of it as an inverse intent — you define the state you don't want to occur without specifying or caring about all the specific vectors that could lead to it. Assertions are binary in nature, implemented through Solidity's **`require`** statement: @@ -120,7 +120,7 @@ For a good explainer on invariants see [this article](https://blog.trailofbits.c ### How do assertions work? -Although assertions are stored on-chain for transparency's sake, assertions are run off-chain through the PhEVM (Phylax EVM) by the sequencer for performance reasons and can: +Although assertion IDs and registry entries are stored on-chain for transparency, assertions are run off-chain through the PhEVM (Phylax EVM) by the sequencer or block builder for performance reasons and can: 1. Compare state before and after transactions 2. Monitor specific function calls @@ -133,6 +133,14 @@ Although assertions are stored on-chain for transparency's sake, assertions are - [Architecture - Transaction Flow](/credible/architecture-overview#transaction-flow) - [Glossary - PhEVM](/credible/glossary#phevm-phylax-evm) +### What counts as an assertion failure? +An assertion failure occurs when an assertion reverts during validation. The transaction is then +considered invalid and is dropped before it can be included in a block. + +**Learn More:** +- [Assertion Enforcer](/credible/assertion-enforcer) +- [Incidents](/credible/dapp-incidents) + ### What are cheatcodes and how do they help? Cheatcodes are special functions provided by the PhEVM that give assertions powerful capabilities diff --git a/credible/glossary.mdx b/credible/glossary.mdx index c7aeb87..3a4bce5 100644 --- a/credible/glossary.mdx +++ b/credible/glossary.mdx @@ -56,12 +56,12 @@ The web application interface for interacting with the Credible Layer. It allows A tool that allows users to view and browse all assertions deployed by different protocols, providing visibility into their security posture. ### Sidecar -A software architecture pattern where a component runs alongside the main application without modifying it. The Credible Layer operates as a sidecar to the network's sequencer, intercepting and validating transactions during the block building process. This allows the Credible Layer to add assertion validation capabilities without requiring changes to the core network code. +A software architecture pattern where a component runs alongside the main application without changing core protocol rules. The Credible Layer operates as a sidecar to the network's block builder, intercepting and validating transactions during the block building process. See the [Architecture documentation](/credible/architecture-overview#abstract-overview) for implementation details. ### Network Validator (Node) -The network infrastructure component responsible for processing transactions, building blocks, and maintaining blockchain consensus. In L2 networks, this is typically the sequencer. The Credible Layer integrates with the network validator through a sidecar to validate transactions against assertions before block inclusion. +The network infrastructure component responsible for processing transactions and building blocks. In L2 networks, this is typically the sequencer or block builder. The Credible Layer integrates with the network validator through a sidecar to validate transactions against assertions before block inclusion. Related terms: [Sequencer](/credible/glossary#sequencer), [Block Builder](/credible/glossary#block-builder) diff --git a/credible/interfaces-overview.mdx b/credible/interfaces-overview.mdx new file mode 100644 index 0000000..516bbfe --- /dev/null +++ b/credible/interfaces-overview.mdx @@ -0,0 +1,46 @@ +--- +title: 'Interface Overview' +description: 'High-level interface boundaries between Credible Layer components' +--- + +This page summarizes the public interface boundaries between Credible Layer components. +It is intentionally high-level and does not expose internal endpoints or configuration details. + +## Interface Map + +```mermaid +--- +title: Public Interface Boundaries +--- +flowchart LR + CLI[pcl CLI] <--> DappAPI[Credible dApp API] + DappUI[Credible dApp UI] <--> Contracts[Credible Layer Contracts] + DappUI <--> Indexer[Transparency Indexer] + Enforcer[Assertion Enforcer] <--> Builder[Block Builder] + Enforcer <--> Registry["Registry Data
(On-Chain Events)"] + Enforcer <--> DA[Assertion DA] +``` + +## What Changes Require Coordination + +| Interface | Depends On | Coordinate With | +| --- | --- | --- | +| CLI ↔ dApp API | Assertion submission and auth flows | dApp + CLI maintainers | +| dApp UI ↔ Contracts | Contract ABI + events | dApp + contracts maintainers | +| dApp UI ↔ Indexer | GraphQL schema | dApp + indexer maintainers | +| Enforcer ↔ Block Builder | Transaction validation hook | Network integrators | +| Enforcer ↔ Registry | Registry events + schema | Network + contracts maintainers | +| Enforcer ↔ Assertion DA | Bytecode storage API | DA + enforcer maintainers | + +## Guidance + +- Keep interface changes backward compatible when possible +- If a breaking change is needed, update all dependent components in the same release window +- Ensure public docs reflect any new interface expectations + +## Related Docs + +- [Architecture Overview](/credible/architecture-overview) +- [Trust Model & Guarantees](/credible/trust-model) +- [dApp Integration Overview](/credible/dapp-integration) +- [Network Integration Overview](/credible/network-integration) diff --git a/credible/network-integration.mdx b/credible/network-integration.mdx new file mode 100644 index 0000000..56022aa --- /dev/null +++ b/credible/network-integration.mdx @@ -0,0 +1,76 @@ +--- +title: 'Network Integration Overview' +description: 'High-level integration path for networks and sequencers adopting the Credible Layer' +--- + +This page explains how networks integrate the Credible Layer at a high level. It focuses on the +interface surfaces and operational expectations without internal implementation details. + +## Who This Is For + +- L2 networks and sequencers evaluating integration +- Infrastructure teams operating block builders or validators +- Security teams defining network-level enforcement goals + +## High-Level Flow + +```mermaid +--- +title: Network Integration Flow +--- +flowchart LR + Users[Users + dApps] --> RPC[Network RPC] + RPC --> Builder[Block Builder] + Builder --> Enforcer[Assertion Enforcer] + Enforcer -->|valid| Block[Block] + Enforcer -->|invalid| Drop[Dropped] + Enforcer -.-> Registry[On-Chain Registry] + Enforcer -.-> DA[Assertion DA] +``` + +## Integration Surfaces + +Networks provide the following integration surfaces: + +- **Block-building hook**: the block builder queries the Assertion Enforcer before including a + transaction +- **Registry access**: the enforcer consumes registry data (indexed from on-chain events) to discover which assertions apply +- **Assertion data access**: the enforcer fetches assertion bytecode from Assertion DA +- **Operational monitoring**: incidents and status are surfaced via the Credible dApp + +## Operational Expectations + +- The enforcer runs alongside the block builder and does not change consensus rules +- Enforcement is deterministic and only depends on on-chain state and assertion code +- Networks can stage assertion deployments before enforcing them in production + +## Integration Checklist (High Level) + +- Identify the block-building hook for transaction validation +- Configure access to registry data and assertion bytecode +- Decide on staging vs production enforcement +- Set up monitoring and incident review workflows + +## Integration Requirements (Public) + +- **Block-building hook** that can query the enforcer before inclusion +- **Registry access** for assertion discovery (on-chain events indexed locally) +- **DA access** for assertion bytecode retrieval +- **Incident visibility** through the Credible dApp + +## Next Steps + + + + Detailed system architecture and transaction flow + + + Plugin-based integration pattern for Besu + + + Sidecar validation flow and enforcement role + + + OP Stack integration notes + + diff --git a/credible/neutrality.mdx b/credible/neutrality.mdx index 0acd5be..4f8db0d 100644 --- a/credible/neutrality.mdx +++ b/credible/neutrality.mdx @@ -5,7 +5,7 @@ description: 'Why neutrality is critical to the Credible Layer architecture and *Neutrality is critical. It determines who controls the system. Who controls the system decides how the system is regulated.* -As middleware, the Credible Layer extends network capabilities without introducing new trust assumptions. Protocols define security rules through existing governance channels, and networks enforce these rules through existing mechanisms. +As middleware, the Credible Layer extends network capabilities without requiring external execution services. Protocols define security rules through existing governance channels, and networks enforce these rules through existing mechanisms. ## Decentralization Preservation @@ -30,12 +30,12 @@ Security solutions should optimally **not** add additional trust assumptions or Learn how the Credible Layer works - - Network-specific implementation details - Technical deep dive into system architecture + + Guarantees, assumptions, and failure modes + Common questions about the Credible Layer diff --git a/credible/ownership-verification.mdx b/credible/ownership-verification.mdx index 4a606ca..202760e 100644 --- a/credible/ownership-verification.mdx +++ b/credible/ownership-verification.mdx @@ -5,11 +5,11 @@ description: 'Understanding ownership verification requirements for the Credible # Ownership Verification -The current version of the Credible Layer requires that the address returned by the `owner()` function of a contract is the only address that can deploy assertions for that contract. This is a temporary implementation that will be expanded in future versions. +The Credible Layer uses admin verifier modules to determine who can deploy assertions for a contract. Most deployments use owner-based verification by default, and some networks can configure allowlist-based verification. This design will continue to expand with additional ownership patterns. ## Current Implementation -The Credible Layer expects contracts to implement the `owner()` function, typically through the Ownable pattern. Here's an example of the expected interface: +The common default verifier expects contracts to implement the `owner()` function (Ownable pattern). Here's an example of the expected interface: ```solidity interface IOwnable { @@ -17,7 +17,7 @@ interface IOwnable { } ``` -When testing or developing with the Credible Layer, ensure your contracts implement this interface to enable project registration and assertion management. +When testing or developing with the Credible Layer, ensure your contracts implement this interface or that your network provides an allowlist verifier to enable project registration and assertion management. ## Future Development @@ -36,4 +36,3 @@ These improvements will be implemented in future versions of the Credible Layer. - [Assertion Guide](/credible/write-first-assertion) - Learn how to write assertions - [Deploy Assertions](/credible/deploy-assertions-dapp) - Learn how to deploy assertions - [FAQ](/credible/faq) - Find answers to common questions - diff --git a/credible/system-requirements.mdx b/credible/system-requirements.mdx index ba4f846..fdd6c75 100644 --- a/credible/system-requirements.mdx +++ b/credible/system-requirements.mdx @@ -3,18 +3,18 @@ title: 'System Requirements' description: 'Hardware and infrastructure requirements for running the Credible Layer sidecar in production and development environments.' --- -The Credible Layer operates as a [sidecar](/credible/glossary#sidecar) alongside the network sequencer. This page outlines the system requirements for running the sidecar. +The Credible Layer operates as a [sidecar](/credible/glossary#sidecar) alongside the network block builder or sequencer. This page outlines high-level requirements for running the sidecar. -## Production Requirements +## Production Guidance -For production usage on a real network, run the sidecar with at least the following specifications: +Sizing depends on network throughput and assertion complexity. Use these guidelines as a starting point and scale based on load testing: -| Component | Requirement | -|-----------|-------------| -| **CPU** | 32 physical cores, AMD Zen 3 performance equivalent or higher | -| **RAM** | 128 GB recommended | -| **Storage** | 512 GB+ recommended | -| **Network** | 10 Gbps minimum between sequencer and sidecar | +| Component | Guidance | +|-----------|----------| +| **CPU** | High-core, modern server CPU | +| **RAM** | Sufficient memory for state caches and execution | +| **Storage** | Fast local SSD with headroom for growth | +| **Network** | Low-latency, high-bandwidth link to the block builder | ### CPU @@ -22,23 +22,21 @@ The sidecar requires significant compute for assertion execution. Use 32 physica ### Memory -Allocate 128 GB RAM minimum. RAM allocation should be enough to store the entire chain state (not full blocks, just state) in memory. +Allocate enough RAM for state caches and execution overhead. Exact requirements vary by chain size and assertion complexity. ### Storage -Use 512 GB+ of fast local (not networked) PCIe NVMe SSDs to keep I/O latency low. Budget for sustained IOPS and 2x storage capacity to maintain fast SSD reads. +Use fast local (not networked) SSDs to keep I/O latency low. Budget for sustained IOPS and headroom for state growth. ### Networking -Keep round-trip time (RTT) to the sequencer sub-millisecond by colocating in the same availability zone or cluster. Co-scheduling on the same Kubernetes node/pod is ideal. +Keep round-trip time (RTT) to the block builder low by colocating in the same availability zone or cluster. Co-scheduling on the same Kubernetes node or pod is ideal. **Key requirements:** -- 10 Gbps minimum bandwidth between sequencer and sidecar -- VPC-peer the sequencer and sidecar; avoid routing over the public internet -- Stable, low-jitter egress to your DA RPC (HTTP) and indexer RPC (WebSocket) endpoints -- Prefer private endpoints or allowlisted static egress IPs +- Low-latency, high-bandwidth link between block builder and sidecar +- Prefer private networking; avoid routing over the public internet +- Stable egress to chain RPC and assertion data endpoints ## Local Development For local testing, unless you are benchmarking performance, the sidecar is lightweight and has no hard hardware requirements. - diff --git a/credible/trust-model.mdx b/credible/trust-model.mdx new file mode 100644 index 0000000..034c0bc --- /dev/null +++ b/credible/trust-model.mdx @@ -0,0 +1,47 @@ +--- +title: 'Trust Model & Guarantees' +description: 'What the Credible Layer guarantees, what it does not, and the operational assumptions' +--- + +This page summarizes the Credible Layer trust model in plain language. + +## What We Guarantee + +- **Deterministic enforcement**: given the same on-chain state and assertion code, enforcement + results are deterministic +- **Pre-execution protection**: transactions that violate deployed assertions are excluded from + blocks by networks running the enforcer +- **Transparent rules**: assertions are public Solidity code and can be audited by anyone + +## What We Do Not Guarantee + +- **Assertion correctness**: teams are responsible for writing accurate assertions +- **Complete coverage**: only behaviors covered by assertions are enforced +- **Off-chain security**: custodial, UI, or off-chain service risks are out of scope + +## Operational Assumptions + +- The network runs the Assertion Enforcer during block building +- The enforcer can access registry data (from on-chain events) and assertion bytecode +- The network follows its normal transaction validity rules alongside enforcement + +## Failure Modes (High Level) + +- **Enforcer unavailable**: the network continues normal operation without enforcement until the + enforcer is restored +- **Registry misconfiguration**: assertions may not apply to intended contracts +- **DA connectivity issues**: new assertions may be delayed until bytecode is reachable + +## Next Steps + + + + Understand the system components and flows + + + Enforcement details and validation process + + + Common questions about the Credible Layer + + diff --git a/docs.json b/docs.json index 0b6cd7a..8378fd9 100644 --- a/docs.json +++ b/docs.json @@ -18,22 +18,48 @@ "group": "Getting Started", "pages": [ "credible/credible-introduction", + "credible/credible-layer-overview", + "credible/evaluate-credible-layer", "credible/credible-install", - "credible/pcl-quickstart", - "credible/credible-layer-overview" + "credible/pcl-quickstart" ] }, { "group": "Architecture", "pages": [ "credible/architecture-overview", - "credible/assertion-enforcer", - "credible/phevm", - "credible/credible-layer-contracts", - "credible/architecture-op-stack", - "credible/assertion-da", - "credible/system-requirements", - "credible/neutrality" + { + "group": "Principles", + "pages": [ + "credible/trust-model", + "credible/interfaces-overview", + "credible/neutrality" + ] + }, + { + "group": "Core Components", + "pages": [ + "credible/assertion-enforcer", + "credible/phevm", + "credible/assertion-da", + "credible/credible-layer-contracts" + ] + }, + { + "group": "Integrations", + "pages": [ + "credible/network-integration", + "credible/dapp-integration", + "credible/architecture-linea", + "credible/architecture-op-stack" + ] + }, + { + "group": "Operations", + "pages": [ + "credible/system-requirements" + ] + } ] }, {