Introduction
This page provides a comprehensive overview of the architecture of the Credible Layer. It details the primary system components, their roles, and how they interact to enforce security rules for smart contracts.Looking for a non-technical introduction? Start with the Credible Layer Overview.
System Overview
The Credible Layer consists of four key components working together:- Assertions: Security rules written in Solidity that define states that should never occur (e.g., “proxy implementation address shouldn’t change”, “price reported by oracle shouldn’t deviate more than x% inside of a single transaction”)
- Protocols / dApps: Define assertions for their contracts and link them on-chain
- Block Builders/Sequencers: The network infrastructure that validates every transaction against assertions before inclusion in a block, dropping any that would violate security rules
- Transparency Dashboard: A platform where users can see which protocols are protected and how, creating a focal point for ecosystem security
How the Credible Layer Works
Abstract Overview
The Credible Layer is a sidecar security infrastructure that validates every transaction 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 the block building process and ensuring they don’t violate any deployed security properties.Sidecar Architecture
The sidecar design allows the Credible Layer to:- Operate independently from the main L2 infrastructure
- Validate transactions without modifying core L2 code
- Scale separately from the main network components
- Fail gracefully without affecting L2 operations
System Architecture
The diagram above shows the Credible Layer at the system level. It illustrates two main flows: Development Flow: Developers use thepcl to develop and test assertions. The pcl stores assertion bytecode directly in Assertion DA, then submits to the Credible dApp with the assertion ID. The dApp deploys these assertions in the on-chain Credible Layer contracts.
Runtime Flow: The network validator sends transactions to the Assertion Enforcer sidecar during block production. The Assertion Enforcer fetches relevant assertions from Assertion DA and executes them via PhEVM. Crucially, assertion validation happens during block production, which means the Assertion Enforcer has access to the final transaction ordering. The sidecar returns validation results (valid/invalid) back to the network validator, which only includes valid transactions in blocks.
How It Works
- Assertion Deployment: Developers write and submit assertions through the
pcland dApp, which are stored in Assertion DA and then deployed on-chain - Transaction Validation During Block Production: The network sends transactions to the Assertion Enforcer during block production
- Assertion Execution: The Assertion Enforcer simulates each transaction and validates it against relevant assertions using PhEVM
- Validation Results: The Assertion Enforcer returns valid/invalid results to the network validator
- Security Enforcement: Only valid transactions are included in blocks, preventing security violations before they reach the blockchain
Transaction Flow
When a user submits a transaction, it goes through the following validation process:- Transaction Submission: User submits a transaction to the network
- Mempool Entry: Transaction enters the mempool awaiting selection
- Block Builder Selection: The block builder picks transactions from the mempool and validates them
- Assertion Validation: Each transaction is simulated and validated against deployed Assertions
- Inclusion Decision: Valid transactions are included in the block, invalid ones are dropped
Assertion Validation Process
The assertion validation step (step 4 above) is where the Credible Layer’s security enforcement happens. Here’s what occurs during this critical phase:- Identify Relevant Assertions: The system identifies which assertions apply to the contracts the transaction interacts with
- Fetch Assertion Bytecode: The system retrieves Assertion Bytecode from the Assertion DA
- Simulate Transaction: The transaction is simulated to create two state snapshots:
- Pre-transaction state: The blockchain state before the transaction
- Post-transaction state: The blockchain state after the transaction
- Execute Assertions: The PhEVM executes all relevant assertions against these states
- Return Result:
- If any assertion reverts (invalid state), the transaction is flagged as invalid
- If all assertions pass, the transaction is considered valid
Forced Inclusion Transactions: You might be wondering how the Credible Layer handles forced inclusion transactions. We have found a solution and are actively working on implementing it. Ask us about it!
System Components
Component Details
The Credible Layer consists of several key infrastructure components:Assertion Enforcer (Sidecar)
- Custom block builder implementation that operates as a sidecar to the sequencer
- Integrates with the sequencer without requiring sequencer code modifications
- Orchestrates the validation process by:
- Identifying which assertions apply to incoming transactions
- Invoking PhEVM to execute the assertions against transaction states
- Making inclusion/exclusion decisions based on assertion results
- Builds blocks that exclude any transactions violating assertions
- Handles forced inclusion transactions with special mitigation pathways
PhEVM (Phylax EVM)
The execution arm of the Assertion Enforcer:- Executes assertion bytecode in an isolated off-chain environment
- Supports special cheatcodes (precompiles) for efficient state access and comparison
- Can simulate both pre-transaction and post-transaction states
- Evaluates assertions in parallel to maximize throughput (we’ve benchmarked 1 gigagas/s of assertions against 30 megagas/s transaction throughput)
Assertion Data Availability (Assertion DA)
- Compiles and stores assertion source code and bytecode securely
- Provides assertion code to block builders for enforcement
- Enables transparency by making assertions publicly available to users and auditors
Credible Layer Protocol
Smart contracts that manage the on-chain assertion registry:- Maps assertions to protected contracts
- Handles assertion deployments, updates, and removals
- Supports proof verification for mitigation triggers
- Maintains security parameters and protocol metadata
Developer Tools
Credible Layer dApp
User interface for protocols to deploy and manage assertions:- Transparency Dashboard: Provides visibility into project security measures
- OAuth-based authentication for assertion submission
- Project and assertion management interface
pcl
Command-line tool for writing, testing, and deploying assertions:
- Write assertions in Solidity
- Test assertions locally with
pcl test - Deploy assertions to the Credible Layer
- Manage assertion lifecycle
credible-std
Standard library exposing cheatcodes and testing functionality:
- Provides access to PhEVM cheatcodes for assertion development
- Testing utilities for local assertion validation
- Helper functions for common assertion patterns
credible-std reference for details.
Network Integrations
The Credible Layer can be implemented on different networks using various architectures. The core concepts remain the same, but implementation details vary by network architecture.Rollup-Boost Architecture
- Block builder that integrates assertion enforcement directly
- Uses external sidecar components to integrate with the L2 sequencer
- Minimal changes to L2 node code
- Suitable for modular L2 architectures
For concrete assertion examples and real-world use cases, explore the Assertions Book.