From 0640ad126177aca186c28e45987bc6df92fc0f6c Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 01:54:45 +0100 Subject: [PATCH 01/17] Add public integration and trust model docs --- credible/architecture-op-stack.mdx | 4 ++ credible/architecture-overview.mdx | 36 +++++++++++++++++ credible/assertion-enforcer.mdx | 10 +++++ credible/credible-introduction.mdx | 6 +++ credible/credible-layer-overview.mdx | 11 ++++++ credible/dapp-integration.mdx | 56 ++++++++++++++++++++++++++ credible/dapp-integrations.mdx | 5 ++- credible/dapp-overview.mdx | 3 ++ credible/network-integration.mdx | 59 ++++++++++++++++++++++++++++ credible/trust-model.mdx | 47 ++++++++++++++++++++++ docs.json | 3 ++ 11 files changed, 239 insertions(+), 1 deletion(-) create mode 100644 credible/dapp-integration.mdx create mode 100644 credible/network-integration.mdx create mode 100644 credible/trust-model.mdx diff --git a/credible/architecture-op-stack.mdx b/credible/architecture-op-stack.mdx index 5ee39e8..e96f44c 100644 --- a/credible/architecture-op-stack.mdx +++ b/credible/architecture-op-stack.mdx @@ -5,6 +5,10 @@ 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). + + ## Architecture Diagram ```mermaid diff --git a/credible/architecture-overview.mdx b/credible/architecture-overview.mdx index b44023e..74c35f4 100644 --- a/credible/architecture-overview.mdx +++ b/credible/architecture-overview.mdx @@ -127,6 +127,39 @@ 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 + + + For details on the assertion validation process, see [Assertion Enforcer](/credible/assertion-enforcer#validation-process). ## System Components @@ -179,4 +212,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-enforcer.mdx b/credible/assertion-enforcer.mdx index bde4c49..77d75ba 100644 --- a/credible/assertion-enforcer.mdx +++ b/credible/assertion-enforcer.mdx @@ -119,3 +119,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..d6eb13e 100644 --- a/credible/credible-introduction.mdx +++ b/credible/credible-introduction.mdx @@ -33,9 +33,15 @@ The Credible Layer is security infrastructure that enables developers to link se 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 diff --git a/credible/credible-layer-overview.mdx b/credible/credible-layer-overview.mdx index 4ef4719..471845f 100644 --- a/credible/credible-layer-overview.mdx +++ b/credible/credible-layer-overview.mdx @@ -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 diff --git a/credible/dapp-integration.mdx b/credible/dapp-integration.mdx new file mode 100644 index 0000000..b34e316 --- /dev/null +++ b/credible/dapp-integration.mdx @@ -0,0 +1,56 @@ +--- +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 Paths + +Teams typically choose one of two paths: + +- **CLI + dApp**: write assertions locally, store bytecode, and manage deployments in the dApp. +- **dApp-first**: use the dApp for project management, staging, and incident monitoring. + +## 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 + +## What Users Can Verify + +- Which assertions are active for a protocol +- On-chain registry entries and transparency views +- Incident history for protected contracts + +## 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..71ecd75 100644 --- a/credible/dapp-overview.mdx +++ b/credible/dapp-overview.mdx @@ -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/network-integration.mdx b/credible/network-integration.mdx new file mode 100644 index 0000000..6ea4650 --- /dev/null +++ b/credible/network-integration.mdx @@ -0,0 +1,59 @@ +--- +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 reads the on-chain registry 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. + +## Next Steps + + + + Detailed system architecture and transaction flow + + + Sidecar validation flow and enforcement role + + + OP Stack integration notes + + diff --git a/credible/trust-model.mdx b/credible/trust-model.mdx new file mode 100644 index 0000000..56258da --- /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 the on-chain registry 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..0adcbd8 100644 --- a/docs.json +++ b/docs.json @@ -27,6 +27,9 @@ "group": "Architecture", "pages": [ "credible/architecture-overview", + "credible/network-integration", + "credible/dapp-integration", + "credible/trust-model", "credible/assertion-enforcer", "credible/phevm", "credible/credible-layer-contracts", From bf0504aeff71483ee9daedd02fe1ad319d92dbef Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 01:57:58 +0100 Subject: [PATCH 02/17] Add public interface overview and integration guidance --- credible/architecture-overview.mdx | 3 ++ credible/credible-layer-overview.mdx | 2 ++ credible/dapp-integration.mdx | 7 ++++ credible/dapp-transparency-dashboard.mdx | 6 +++- credible/interfaces-overview.mdx | 46 ++++++++++++++++++++++++ credible/network-integration.mdx | 7 ++++ docs.json | 1 + 7 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 credible/interfaces-overview.mdx diff --git a/credible/architecture-overview.mdx b/credible/architecture-overview.mdx index 74c35f4..1b133a5 100644 --- a/credible/architecture-overview.mdx +++ b/credible/architecture-overview.mdx @@ -158,6 +158,9 @@ flowchart LR 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). diff --git a/credible/credible-layer-overview.mdx b/credible/credible-layer-overview.mdx index 471845f..5543e24 100644 --- a/credible/credible-layer-overview.mdx +++ b/credible/credible-layer-overview.mdx @@ -174,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-integration.mdx b/credible/dapp-integration.mdx index b34e316..228e7c3 100644 --- a/credible/dapp-integration.mdx +++ b/credible/dapp-integration.mdx @@ -35,6 +35,13 @@ flowchart LR - 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 diff --git a/credible/dapp-transparency-dashboard.mdx b/credible/dapp-transparency-dashboard.mdx index a3045ad..5661c5d 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 @@ -57,4 +62,3 @@ View all projects and their details: Learn how to write assertions - diff --git a/credible/interfaces-overview.mdx b/credible/interfaces-overview.mdx new file mode 100644 index 0000000..df85809 --- /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[On-Chain Registry] + 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 contract 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 index 6ea4650..2ae7ff0 100644 --- a/credible/network-integration.mdx +++ b/credible/network-integration.mdx @@ -44,6 +44,13 @@ Networks provide the following integration surfaces: - 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 the on-chain registry and assertion data +- Decide on staging vs production enforcement +- Set up monitoring and incident review workflows + ## Next Steps diff --git a/docs.json b/docs.json index 0adcbd8..119540a 100644 --- a/docs.json +++ b/docs.json @@ -27,6 +27,7 @@ "group": "Architecture", "pages": [ "credible/architecture-overview", + "credible/interfaces-overview", "credible/network-integration", "credible/dapp-integration", "credible/trust-model", From a1a17cb54da463c0951567148395044913e04ef3 Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 01:59:02 +0100 Subject: [PATCH 03/17] Add public interface references in dapp and contracts docs --- credible/credible-layer-contracts.mdx | 4 ++++ credible/dapp-incidents.mdx | 6 +++++- 2 files changed, 9 insertions(+), 1 deletion(-) 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/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 - From 03dcd01fc5f5cb8d3326e56364ed52af3e3d2400 Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 02:01:24 +0100 Subject: [PATCH 04/17] Add evaluation checklist and public expectations --- credible/assertion-enforcer.mdx | 7 +++++ credible/credible-introduction.mdx | 3 ++ credible/dapp-transparency-dashboard.mdx | 6 ++++ credible/evaluate-credible-layer.mdx | 39 ++++++++++++++++++++++++ docs.json | 3 +- 5 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 credible/evaluate-credible-layer.mdx diff --git a/credible/assertion-enforcer.mdx b/credible/assertion-enforcer.mdx index 77d75ba..6a0c001 100644 --- a/credible/assertion-enforcer.mdx +++ b/credible/assertion-enforcer.mdx @@ -102,6 +102,13 @@ The Assertion Enforcer integrates with block builders to ensure only valid trans - The network validator 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. diff --git a/credible/credible-introduction.mdx b/credible/credible-introduction.mdx index d6eb13e..2d84a52 100644 --- a/credible/credible-introduction.mdx +++ b/credible/credible-introduction.mdx @@ -27,6 +27,9 @@ 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. diff --git a/credible/dapp-transparency-dashboard.mdx b/credible/dapp-transparency-dashboard.mdx index 5661c5d..ddb7c2c 100644 --- a/credible/dapp-transparency-dashboard.mdx +++ b/credible/dapp-transparency-dashboard.mdx @@ -46,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 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/docs.json b/docs.json index 119540a..44a7f31 100644 --- a/docs.json +++ b/docs.json @@ -20,7 +20,8 @@ "credible/credible-introduction", "credible/credible-install", "credible/pcl-quickstart", - "credible/credible-layer-overview" + "credible/credible-layer-overview", + "credible/evaluate-credible-layer" ] }, { From 77ba04fd2be1bf6a6c94480b706603d29eea3520 Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 02:04:32 +0100 Subject: [PATCH 05/17] Expand integration requirements and FAQ guidance --- credible/dapp-integration.mdx | 6 ++++++ credible/faq.mdx | 8 ++++++++ credible/network-integration.mdx | 7 +++++++ 3 files changed, 21 insertions(+) diff --git a/credible/dapp-integration.mdx b/credible/dapp-integration.mdx index 228e7c3..cefd92a 100644 --- a/credible/dapp-integration.mdx +++ b/credible/dapp-integration.mdx @@ -48,6 +48,12 @@ Learn more about ownership checks in [Ownership Verification](/credible/ownershi - 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 diff --git a/credible/faq.mdx b/credible/faq.mdx index f546b67..83c3304 100644 --- a/credible/faq.mdx +++ b/credible/faq.mdx @@ -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/network-integration.mdx b/credible/network-integration.mdx index 2ae7ff0..4f5e561 100644 --- a/credible/network-integration.mdx +++ b/credible/network-integration.mdx @@ -51,6 +51,13 @@ Networks provide the following integration surfaces: - 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 +- **DA access** for assertion bytecode retrieval +- **Incident visibility** through the Credible dApp + ## Next Steps From c0e5a269bf6d577e6543ea24bfb6eb2ea598f77a Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 10:35:52 +0100 Subject: [PATCH 06/17] Reorder architecture docs for user flow --- docs.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs.json b/docs.json index 44a7f31..776dd6d 100644 --- a/docs.json +++ b/docs.json @@ -28,15 +28,15 @@ "group": "Architecture", "pages": [ "credible/architecture-overview", + "credible/trust-model", "credible/interfaces-overview", "credible/network-integration", "credible/dapp-integration", - "credible/trust-model", "credible/assertion-enforcer", "credible/phevm", + "credible/assertion-da", "credible/credible-layer-contracts", "credible/architecture-op-stack", - "credible/assertion-da", "credible/system-requirements", "credible/neutrality" ] From d80dd8b5082070e022645d07f41e8ef47d72252a Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 10:37:36 +0100 Subject: [PATCH 07/17] Group architecture docs into subcategories --- docs.json | 42 +++++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 11 deletions(-) diff --git a/docs.json b/docs.json index 776dd6d..5768dc2 100644 --- a/docs.json +++ b/docs.json @@ -28,17 +28,37 @@ "group": "Architecture", "pages": [ "credible/architecture-overview", - "credible/trust-model", - "credible/interfaces-overview", - "credible/network-integration", - "credible/dapp-integration", - "credible/assertion-enforcer", - "credible/phevm", - "credible/assertion-da", - "credible/credible-layer-contracts", - "credible/architecture-op-stack", - "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-op-stack" + ] + }, + { + "group": "Operations", + "pages": [ + "credible/system-requirements" + ] + } ] }, { From db5785f8f36c985bc9814d89803ce2391eb641d8 Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 10:46:26 +0100 Subject: [PATCH 08/17] Fix public doc terminology and ownership claims --- credible/architecture-overview.mdx | 8 ++++---- credible/assertion-da.mdx | 2 +- credible/assertion-enforcer.mdx | 6 +++--- credible/faq.mdx | 2 +- credible/glossary.mdx | 4 ++-- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/credible/architecture-overview.mdx b/credible/architecture-overview.mdx index 1b133a5..dd62f02 100644 --- a/credible/architecture-overview.mdx +++ b/credible/architecture-overview.mdx @@ -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 @@ -79,14 +79,14 @@ 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). -**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 fetches relevant assertions and executes them 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 diff --git a/credible/assertion-da.mdx b/credible/assertion-da.mdx index a2a3d1b..e4b3fcb 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 diff --git a/credible/assertion-enforcer.mdx b/credible/assertion-enforcer.mdx index 6a0c001..9eebb71 100644 --- a/credible/assertion-enforcer.mdx +++ b/credible/assertion-enforcer.mdx @@ -9,7 +9,7 @@ The Assertion Enforcer is a sidecar component that validates transactions agains The Assertion Enforcer sits between the mempool and block production: -1. Receives transactions from the network validator +1. Receives 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 @@ -99,7 +99,7 @@ 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) diff --git a/credible/faq.mdx b/credible/faq.mdx index 83c3304..07537c6 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 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) From 2623abd78fe3ea0c49d114d73f3d161195c8f73d Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 11:38:06 +0100 Subject: [PATCH 09/17] Refine public terminology and reorganize getting started --- credible/architecture-overview.mdx | 2 +- credible/credible-introduction.mdx | 2 +- credible/dapp-overview.mdx | 4 ++-- credible/faq.mdx | 10 +++++----- credible/neutrality.mdx | 8 ++++---- credible/system-requirements.mdx | 32 ++++++++++++++---------------- docs.json | 6 +++--- 7 files changed, 31 insertions(+), 33 deletions(-) diff --git a/credible/architecture-overview.mdx b/credible/architecture-overview.mdx index dd62f02..114ee9d 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 sequencer. Networks that integrate the Credible Layer run this sidecar as part of their sequencer infrastructure. This means enforcement does not rely on external execution services beyond the network you already trust to include transactions. ### System Architecture diff --git a/credible/credible-introduction.mdx b/credible/credible-introduction.mdx index 2d84a52..d3c16df 100644 --- a/credible/credible-introduction.mdx +++ b/credible/credible-introduction.mdx @@ -52,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/dapp-overview.mdx b/credible/dapp-overview.mdx index 71ecd75..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. diff --git a/credible/faq.mdx b/credible/faq.mdx index 07537c6..5d67514 100644 --- a/credible/faq.mdx +++ b/credible/faq.mdx @@ -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 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/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/docs.json b/docs.json index 5768dc2..049b55d 100644 --- a/docs.json +++ b/docs.json @@ -18,10 +18,10 @@ "group": "Getting Started", "pages": [ "credible/credible-introduction", - "credible/credible-install", - "credible/pcl-quickstart", "credible/credible-layer-overview", - "credible/evaluate-credible-layer" + "credible/evaluate-credible-layer", + "credible/credible-install", + "credible/pcl-quickstart" ] }, { From fb98d6ba0027021dbeb6297847e1deff586507d3 Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 11:59:12 +0100 Subject: [PATCH 10/17] Add Linea/Besu integration overview --- credible/architecture-linea.mdx | 66 ++++++++++++++++++++++++++++++ credible/architecture-op-stack.mdx | 4 ++ credible/network-integration.mdx | 3 ++ docs.json | 1 + 4 files changed, 74 insertions(+) create mode 100644 credible/architecture-linea.mdx diff --git a/credible/architecture-linea.mdx b/credible/architecture-linea.mdx new file mode 100644 index 0000000..2bf99a6 --- /dev/null +++ b/credible/architecture-linea.mdx @@ -0,0 +1,66 @@ +--- +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 Sidecar["Assertion Enforcer Sidecar"] + Engine["Assertion Execution Engine"] + Store["Assertion Store"] + Registry["On-Chain Registry"] + DA["Assertion DA"] + end + + TxPool --> Builder + Builder --> Plugin + Plugin <--> Sidecar + Sidecar --> Engine + Engine --> Store + Store <---> Registry + Store <---> 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 the on-chain registry 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) diff --git a/credible/architecture-op-stack.mdx b/credible/architecture-op-stack.mdx index e96f44c..08ad11a 100644 --- a/credible/architecture-op-stack.mdx +++ b/credible/architecture-op-stack.mdx @@ -9,6 +9,10 @@ The OP Stack implementation uses [Rollup-Boost](https://github.com/flashbots/rol 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 diff --git a/credible/network-integration.mdx b/credible/network-integration.mdx index 4f5e561..45d43d6 100644 --- a/credible/network-integration.mdx +++ b/credible/network-integration.mdx @@ -64,6 +64,9 @@ Networks provide the following integration surfaces: Detailed system architecture and transaction flow + + Plugin-based integration pattern for Besu + Sidecar validation flow and enforcement role diff --git a/docs.json b/docs.json index 049b55d..8378fd9 100644 --- a/docs.json +++ b/docs.json @@ -50,6 +50,7 @@ "pages": [ "credible/network-integration", "credible/dapp-integration", + "credible/architecture-linea", "credible/architecture-op-stack" ] }, From 82b8360fc7500ac783baf616d86cf5a88795511c Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 12:36:09 +0100 Subject: [PATCH 11/17] Address PR feedback on integration docs --- credible/architecture-linea.mdx | 8 +++++--- credible/dapp-integration.mdx | 9 +++++---- credible/network-integration.mdx | 14 +++++++------- 3 files changed, 17 insertions(+), 14 deletions(-) diff --git a/credible/architecture-linea.mdx b/credible/architecture-linea.mdx index 2bf99a6..a24c945 100644 --- a/credible/architecture-linea.mdx +++ b/credible/architecture-linea.mdx @@ -39,11 +39,12 @@ flowchart LR TxPool --> Builder Builder --> Plugin - Plugin <--> Sidecar + Plugin --> Sidecar + Sidecar --> Plugin Sidecar --> Engine Engine --> Store - Store <---> Registry - Store <---> DA + Sidecar --> Registry + Sidecar --> DA ``` ## Validation Flow @@ -64,3 +65,4 @@ flowchart LR - [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/dapp-integration.mdx b/credible/dapp-integration.mdx index cefd92a..dd2f7bb 100644 --- a/credible/dapp-integration.mdx +++ b/credible/dapp-integration.mdx @@ -6,12 +6,13 @@ description: 'High-level integration path for protocols adopting the Credible La 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 Paths +## Adoption Workflow -Teams typically choose one of two paths: +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 + dApp**: write assertions locally, store bytecode, and manage deployments in the dApp. -- **dApp-first**: use the dApp for project management, staging, and incident monitoring. +- **CLI authoring**: write assertions locally and store bytecode +- **dApp management**: link contracts, stage or deploy, and monitor incidents ## End-to-End Flow diff --git a/credible/network-integration.mdx b/credible/network-integration.mdx index 45d43d6..7274446 100644 --- a/credible/network-integration.mdx +++ b/credible/network-integration.mdx @@ -33,16 +33,16 @@ flowchart LR Networks provide the following integration surfaces: - **Block-building hook**: the block builder queries the Assertion Enforcer before including a - transaction. -- **Registry access**: the enforcer reads the on-chain registry 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. + transaction +- **Registry access**: the enforcer reads the on-chain registry 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. +- 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) From 063e0562d888087f82e73f9d3bba998d58d34172 Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 12:41:28 +0100 Subject: [PATCH 12/17] Refresh OP Stack diagram colors --- credible/architecture-op-stack.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/credible/architecture-op-stack.mdx b/credible/architecture-op-stack.mdx index 08ad11a..7a3c4a2 100644 --- a/credible/architecture-op-stack.mdx +++ b/credible/architecture-op-stack.mdx @@ -21,9 +21,9 @@ title: OP Stack Implementation Architecture --- flowchart TD -classDef sequencer fill:#0288d1,stroke:#01579b,stroke-width:2px,color:#fff -classDef credible fill:#7b1fa2,stroke:#4a148c,stroke-width:2px,color:#fff -classDef rollupBoost fill:#388e3c,stroke:#1b5e20,stroke-width:2px,color:#fff +classDef sequencer fill:#0f172a,stroke:#1e293b,stroke-width:2px,color:#f8fafc +classDef credible fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#111827 +classDef rollupBoost fill:#14b8a6,stroke:#0f766e,stroke-width:2px,color:#0f172a subgraph Sequencer[**Sequencer**] SequencerCL[op-node] From 7c75578adc04c4719f0d7bc68fc78631b8dab39b Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 12:45:24 +0100 Subject: [PATCH 13/17] Align diagram colors and polish public guidance --- credible/architecture-op-stack.mdx | 6 +++--- credible/assertion-da.mdx | 2 +- credible/interfaces-overview.mdx | 6 +++--- credible/trust-model.mdx | 24 ++++++++++++------------ 4 files changed, 19 insertions(+), 19 deletions(-) diff --git a/credible/architecture-op-stack.mdx b/credible/architecture-op-stack.mdx index 7a3c4a2..08ad11a 100644 --- a/credible/architecture-op-stack.mdx +++ b/credible/architecture-op-stack.mdx @@ -21,9 +21,9 @@ title: OP Stack Implementation Architecture --- flowchart TD -classDef sequencer fill:#0f172a,stroke:#1e293b,stroke-width:2px,color:#f8fafc -classDef credible fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#111827 -classDef rollupBoost fill:#14b8a6,stroke:#0f766e,stroke-width:2px,color:#0f172a +classDef sequencer fill:#0288d1,stroke:#01579b,stroke-width:2px,color:#fff +classDef credible fill:#7b1fa2,stroke:#4a148c,stroke-width:2px,color:#fff +classDef rollupBoost fill:#388e3c,stroke:#1b5e20,stroke-width:2px,color:#fff subgraph Sequencer[**Sequencer**] SequencerCL[op-node] diff --git a/credible/assertion-da.mdx b/credible/assertion-da.mdx index e4b3fcb..7893b7f 100644 --- a/credible/assertion-da.mdx +++ b/credible/assertion-da.mdx @@ -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/interfaces-overview.mdx b/credible/interfaces-overview.mdx index df85809..1461196 100644 --- a/credible/interfaces-overview.mdx +++ b/credible/interfaces-overview.mdx @@ -34,9 +34,9 @@ flowchart LR ## 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. +- 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 diff --git a/credible/trust-model.mdx b/credible/trust-model.mdx index 56258da..68068d6 100644 --- a/credible/trust-model.mdx +++ b/credible/trust-model.mdx @@ -8,29 +8,29 @@ 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. + 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. + 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. +- **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 the on-chain registry and assertion bytecode. -- The network follows its normal transaction validity rules alongside enforcement. +- The network runs the Assertion Enforcer during block building +- The enforcer can access the on-chain registry 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. + 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 From dfcaf689c055204ab734c0c8ccd35ccc2296b647 Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 13:14:56 +0100 Subject: [PATCH 14/17] Fix OP Stack diagram assertion flows --- credible/architecture-op-stack.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/credible/architecture-op-stack.mdx b/credible/architecture-op-stack.mdx index 08ad11a..6ad3a88 100644 --- a/credible/architecture-op-stack.mdx +++ b/credible/architecture-op-stack.mdx @@ -47,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 From 4974a89ba888caefe1adc9593e38ae2b82cf835f Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 13:38:20 +0100 Subject: [PATCH 15/17] Refine public docs accuracy --- credible/architecture-linea.mdx | 7 ++++--- credible/architecture-overview.mdx | 13 +++++++------ credible/assertion-enforcer.mdx | 6 +++--- credible/credible-layer-overview.mdx | 2 +- credible/dapp-projects.mdx | 9 ++++----- credible/deploy-assertions-dapp.mdx | 8 ++++---- credible/interfaces-overview.mdx | 4 ++-- credible/network-integration.mdx | 6 +++--- credible/ownership-verification.mdx | 7 +++---- credible/trust-model.mdx | 2 +- 10 files changed, 32 insertions(+), 32 deletions(-) diff --git a/credible/architecture-linea.mdx b/credible/architecture-linea.mdx index a24c945..d39bd3c 100644 --- a/credible/architecture-linea.mdx +++ b/credible/architecture-linea.mdx @@ -33,10 +33,11 @@ flowchart LR subgraph Sidecar["Assertion Enforcer Sidecar"] Engine["Assertion Execution Engine"] Store["Assertion Store"] - Registry["On-Chain Registry"] - DA["Assertion DA"] end + Registry["Registry Data
(On-Chain Events)"] + DA["Assertion DA"] + TxPool --> Builder Builder --> Plugin Plugin --> Sidecar @@ -57,7 +58,7 @@ flowchart LR ## Notes - The plugin uses Besu’s transaction selection hooks to validate transactions during block building. -- The sidecar relies on the on-chain registry and assertion data to determine applicable assertions. +- 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 diff --git a/credible/architecture-overview.mdx b/credible/architecture-overview.mdx index 114ee9d..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 enforcement does not rely on external execution services beyond the network you already trust to include transactions. +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 @@ -77,9 +77,9 @@ 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 block builder or sequencer 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 @@ -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 diff --git a/credible/assertion-enforcer.mdx b/credible/assertion-enforcer.mdx index 9eebb71..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 block builder or sequencer +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 @@ -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) diff --git a/credible/credible-layer-overview.mdx b/credible/credible-layer-overview.mdx index 5543e24..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 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/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/interfaces-overview.mdx b/credible/interfaces-overview.mdx index 1461196..516bbfe 100644 --- a/credible/interfaces-overview.mdx +++ b/credible/interfaces-overview.mdx @@ -17,7 +17,7 @@ flowchart LR DappUI[Credible dApp UI] <--> Contracts[Credible Layer Contracts] DappUI <--> Indexer[Transparency Indexer] Enforcer[Assertion Enforcer] <--> Builder[Block Builder] - Enforcer <--> Registry[On-Chain Registry] + Enforcer <--> Registry["Registry Data
(On-Chain Events)"] Enforcer <--> DA[Assertion DA] ``` @@ -29,7 +29,7 @@ flowchart LR | 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 contract schema | Network + contracts maintainers | +| Enforcer ↔ Registry | Registry events + schema | Network + contracts maintainers | | Enforcer ↔ Assertion DA | Bytecode storage API | DA + enforcer maintainers | ## Guidance diff --git a/credible/network-integration.mdx b/credible/network-integration.mdx index 7274446..56022aa 100644 --- a/credible/network-integration.mdx +++ b/credible/network-integration.mdx @@ -34,7 +34,7 @@ Networks provide the following integration surfaces: - **Block-building hook**: the block builder queries the Assertion Enforcer before including a transaction -- **Registry access**: the enforcer reads the on-chain registry to discover which assertions apply +- **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 @@ -47,14 +47,14 @@ Networks provide the following integration surfaces: ## Integration Checklist (High Level) - Identify the block-building hook for transaction validation -- Configure access to the on-chain registry and assertion data +- 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 +- **Registry access** for assertion discovery (on-chain events indexed locally) - **DA access** for assertion bytecode retrieval - **Incident visibility** through the Credible dApp 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/trust-model.mdx b/credible/trust-model.mdx index 68068d6..034c0bc 100644 --- a/credible/trust-model.mdx +++ b/credible/trust-model.mdx @@ -22,7 +22,7 @@ This page summarizes the Credible Layer trust model in plain language. ## Operational Assumptions - The network runs the Assertion Enforcer during block building -- The enforcer can access the on-chain registry and assertion bytecode +- 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) From 92eb1523114ec42de4d815f00d8b9615b4245e24 Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 14:26:06 +0100 Subject: [PATCH 16/17] Fix Linea diagram node wiring --- credible/architecture-linea.mdx | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/credible/architecture-linea.mdx b/credible/architecture-linea.mdx index d39bd3c..cc42b52 100644 --- a/credible/architecture-linea.mdx +++ b/credible/architecture-linea.mdx @@ -30,9 +30,12 @@ flowchart LR Plugin["Credible Layer Plugin"] end - subgraph Sidecar["Assertion Enforcer Sidecar"] + subgraph SidecarGroup["Assertion Enforcer Sidecar"] + SidecarSvc["Assertion Enforcer"] Engine["Assertion Execution Engine"] Store["Assertion Store"] + SidecarSvc --> Engine + Engine --> Store end Registry["Registry Data
(On-Chain Events)"] @@ -40,12 +43,10 @@ flowchart LR TxPool --> Builder Builder --> Plugin - Plugin --> Sidecar - Sidecar --> Plugin - Sidecar --> Engine - Engine --> Store - Sidecar --> Registry - Sidecar --> DA + Plugin --> SidecarSvc + SidecarSvc --> Plugin + SidecarSvc --> Registry + SidecarSvc --> DA ``` ## Validation Flow From 18f0ce5b6142fb665fdc45b242ce0a129ca9917b Mon Sep 17 00:00:00 2001 From: "Odysseas.eth" Date: Thu, 15 Jan 2026 14:41:58 +0100 Subject: [PATCH 17/17] Shorten Linea sidecar label --- credible/architecture-linea.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/credible/architecture-linea.mdx b/credible/architecture-linea.mdx index cc42b52..b02266d 100644 --- a/credible/architecture-linea.mdx +++ b/credible/architecture-linea.mdx @@ -30,7 +30,7 @@ flowchart LR Plugin["Credible Layer Plugin"] end - subgraph SidecarGroup["Assertion Enforcer Sidecar"] + subgraph SidecarGroup["Enforcer Sidecar"] SidecarSvc["Assertion Enforcer"] Engine["Assertion Execution Engine"] Store["Assertion Store"]