General Design

This page provides an overview of the Credible Layer architecture, how the components fit together and interact to enforce security rules for smart contracts.

​

System Overview

The Credible Layer consists of four core components:

1. Assertions: Security rules written in Solidity that define states that should never occur
2. Assertion Enforcer: Sidecar that validates transactions against assertions during block production
3. Credible Layer Contracts: On-chain registry that maps assertions to protected contracts
4. Assertion DA: Storage layer for assertion bytecode and source code

​

How the Credible Layer Works

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.

​

System Architecture

The diagram shows two main flows: Development Flow: Developers use pcl to develop and test assertions. pcl stores assertion code in Assertion DA, then submits to the Credible dApp. The dApp deploys assertions to the on-chain Credible Layer Contracts. Runtime Flow: The network validator sends transactions to the Assertion Enforcer during block production. The enforcer fetches relevant assertions and executes them via 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
5. 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:

1. Transaction Submission: User submits a transaction to the network
2. Mempool Entry: Transaction enters the mempool awaiting selection
3. Block Builder Selection: The block builder picks transactions from the mempool
4. Assertion Validation: Each transaction is validated against deployed assertions
5. Inclusion Decision: Valid transactions are included in the block, invalid ones are dropped

For details on the assertion validation process, see Assertion Enforcer.

​

System Components

​

Assertion Enforcer

The Assertion Enforcer is a sidecar that orchestrates transaction validation. It identifies which assertions apply to incoming transactions, invokes PhEVM to execute them, and makes inclusion/exclusion decisions based on the results.

​

PhEVM (Phylax EVM)

PhEVM is the execution engine that runs assertion bytecode. It extends the standard EVM with cheatcodes for state inspection, enabling assertions to compare pre-transaction and post-transaction states.

​

Assertion DA

Assertion Data Availability stores assertion bytecode and source code, making them accessible to Assertion Enforcers and providing transparency for users and auditors.

​

Credible Layer Contracts

The Credible Layer Contracts are on-chain smart contracts that manage the assertion registry. The State Oracle coordinates protocol admins with network operators and serves as the source of truth for which assertions protect which contracts.

​

Developer Tools

• Credible dApp: Web interface for deploying, managing, and viewing assertions
• pcl: Command-line tool for writing, testing, and deploying assertions
• credible-std: Standard library exposing cheatcodes and testing utilities

​

Network Integrations

The Credible Layer can be implemented on different networks. The core concepts remain the same, but implementation details vary by network architecture. For specific implementation details, see:

• OP Stack Implementation

---

For concrete assertion examples and real-world use cases, explore the Assertions Book.

​

Next Steps