> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phylax.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# General Design

> How the Credible Layer components work together to enforce security rules

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

<Note>
  Looking for a non-technical introduction? Start with the [Credible Layer Overview](/credible/credible-layer-overview).
</Note>

## System Overview

The Credible Layer consists of four core components:

1. **[Assertions](/credible/assertions-overview)**: Security rules written in Solidity that define states that should never occur
2. **[Assertion Enforcer](/credible/assertion-enforcer)**: Sidecar that validates transactions against assertions during block production
3. **[Credible Layer Contracts](/credible/credible-layer-contracts)**: On-chain registry that maps assertions to protected contracts
4. **[Assertion DA](/credible/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 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

```mermaid theme={null}
---
title: Credible Layer System Architecture
---
flowchart LR
    subgraph dev["Development Tools"]
        direction TB
        CLI["pcl"]
        PLATFORM["Phylax Platform"]
    end

    subgraph storage["Storage"]
        DA["Assertion DA"]
    end

    subgraph network["Network"]
        direction LR
        VALIDATOR["Block Builder / Sequencer"]
        REGISTRY["Credible Layer<br/>Contracts"]
    end

    subgraph enforcer["Assertion Enforcer (Sidecar)"]
        direction TB
        SPACER_E[" "]
        PhEVM["PhEVM"]
    end

    CLI -->|"Apply"| PLATFORM
    PLATFORM -->|"Store"| DA
    PLATFORM -->|"Deploy"| REGISTRY

    VALIDATOR -->|"Candidate Tx"| PhEVM
    PhEVM -->|"Valid/Invalid"| VALIDATOR
    PhEVM -.->|"Fetch"| DA
    PhEVM -.->|"Check"| REGISTRY

    classDef dev fill:#388e3c,stroke:#1b5e20,stroke-width:2px,color:#fff
    classDef storage fill:#ff9800,stroke:#e65100,stroke-width:2px,color:#fff
    classDef network fill:#0288d1,stroke:#01579b,stroke-width:2px,color:#fff
    classDef sidecar fill:#7b1fa2,stroke:#4a148c,stroke-width:2px,color:#fff
    classDef invisible fill:none,stroke:none

    class CLI,PLATFORM dev
    class DA storage
    class VALIDATOR,REGISTRY network
    class PhEVM sidecar
    class SPACER_E invisible
```

The diagram shows two main flows:

**Development Flow**: Developers use [`pcl`](/credible/apply-assertions) to develop, test, and deploy assertions. Running `pcl apply` compiles assertion code and creates a release on the [Phylax platform](https://app.phylax.systems), which handles storing it in [Assertion DA](/credible/assertion-da). The platform 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 uses its registry snapshot (from on-chain events) and cached assertion bytecode (from [Assertion DA](/credible/assertion-da)) to execute relevant assertions via [PhEVM](/credible/phevm). Valid transactions are included in blocks; invalid transactions are dropped.

### How It Works

1. **Assertion Deployment**: Developers write assertions and deploy them via `pcl apply`, which creates a release on the platform. The platform stores assertion bytecode in Assertion DA and deploys 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 block builder or sequencer
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:

```mermaid theme={null}
---
title: Transaction Validation Flow
---
flowchart LR
    USER["User"] -->|"Submits Transaction"| MP["Mempool"]
    MP --> BUILDER["Block Builder / Sequencer"]
    BUILDER -->|"Candidate Tx"| SIDECAR["Assertion Enforcer<br/>(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
    classDef sidecar fill:#7b1fa2,stroke:#4a148c,stroke-width:2px,color:#fff
    classDef valid fill:#388e3c,stroke:#1b5e20,stroke-width:2px,color:#fff
    classDef invalid fill:#d32f2f,stroke:#b71c1c,stroke-width:2px,color:#fff

    class USER user
    class MP mempool
    class SIDECAR sidecar
    class BLOCK valid
    class DROP invalid
```

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

<Note>
  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.
</Note>

## Incident Lifecycle (Public View)

When an assertion is violated, the incident is recorded and exposed for transparency and alerts.

```mermaid theme={null}
---
title: Incident Lifecycle
---
flowchart LR
    ENFORCER["Assertion Enforcer"] --> PLATFORM["Phylax Platform"]
    PLATFORM --> DASH["Transparency Dashboard"]
    PLATFORM --> ALERTS["Slack/PagerDuty Alerts"]

    classDef enforcer fill:#7b1fa2,stroke:#4a148c,stroke-width:2px,color:#fff
    classDef platform fill:#388e3c,stroke:#1b5e20,stroke-width:2px,color:#fff
    classDef output fill:#0288d1,stroke:#01579b,stroke-width:2px,color:#fff

    class ENFORCER enforcer
    class PLATFORM platform
    class DASH,ALERTS output
```

## Integration Paths

<CardGroup cols={2}>
  <Card title="Plan a Platform Integration" icon="browser" href="/credible/dapp-integration">
    How protocols deploy and manage assertions
  </Card>

  <Card title="Network Integration Overview" icon="sitemap" href="/credible/network-integration">
    How networks and sequencers integrate enforcement
  </Card>

  <Card title="Interface Overview" icon="diagram-project" href="/credible/interfaces-overview">
    High-level component boundaries and dependencies
  </Card>
</CardGroup>

For details on the assertion validation process, see [Assertion Enforcer](/credible/assertion-enforcer#validation-process).

## System Components

### Assertion Enforcer

The [Assertion Enforcer](/credible/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](/credible/phevm) is the execution engine that runs assertion bytecode. It extends the standard EVM with [cheatcodes](/credible/glossary#cheatcodes) for state inspection, enabling assertions to compare pre-transaction and post-transaction states.

### Assertion DA

[Assertion Data Availability](/credible/assertion-da) 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](/credible/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

* **[Phylax platform](https://app.phylax.systems)**: Web interface for deploying, managing, and viewing assertions
* **[`pcl`](/credible/apply-assertions)**: Command-line tool for writing, testing, and deploying assertions
* **[`credible-std`](/credible/credible-std-overview)**: 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](/credible/network-integrations/architecture-op-stack)

***

For concrete assertion examples and real-world use cases, explore the [Assertions Book](/assertions-book/assertions-book-intro).

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/credible/pcl-quickstart">
    Write and deploy your first assertion
  </Card>

  <Card title="Installation" icon="download" href="/credible/credible-install">
    Set up your development environment
  </Card>

  <Card title="Assertion Guide" icon="code" href="/credible/write-first-assertion">
    Comprehensive guide to writing assertions
  </Card>

  <Card title="Cheatcodes Reference" icon="book" href="/credible/cheatcodes-reference">
    Detailed reference for assertion functions
  </Card>

  <Card title="Trust Model" icon="shield-check" href="/credible/trust-model">
    Guarantees, scope, and operational model
  </Card>
</CardGroup>