Skip to main content

System Overview

Home · Generic Index · Chain Overlays

This document provides the highest-level architecture view of the Credible Layer system as implemented in this workspace. It combines the docs in phylax-docs/ with code-level findings across each repository.

System Context​

Key Relationships​

  • credible-sdk provides the Assertion Enforcer sidecar, Assertion DA, PCL CLI, and assertion execution components.
  • credible-layer-besu-plugin integrates Besu with the sidecar using the TransactionSelectionService hook and JSON-RPC or gRPC transports.
  • credible-layer-dapp contains the Next.js dApp, ts-rest API, Inngest background jobs, Ponder indexer, and Supabase data model.
  • invalidating-trace is an external tracer service that the dApp calls to produce Foundry debug traces for incident investigations.
  • phylax-docs provides architectural references (system overview + OP Stack integration) aligned with the code.
  • The dApp integrates with external services (Airtable for manual verification, Slack/PagerDuty for incident notifications).
  • linea-monorepo provides the Linea sequencer plugins used alongside the Credible plugin in Besu.

Primary Flows (Summary)​

  1. Assertion authoring: pcl builds and stores assertion bytecode in Assertion DA, then submits assertions to the dApp. The dApp deploys registry updates on-chain (State Oracle).
  2. Assertion indexing: Sidecar indexer monitors State Oracle events and pulls assertion bytecode from Assertion DA into the local assertion store for enforcement.
  3. Transaction enforcement: Block builders send transactions to the sidecar during block production; sidecar executes assertions via PhEVM and responds with allow/reject decisions.
  4. Incident reporting: When assertions fail, the sidecar emits incident reports to the dApp API, which processes them asynchronously via Inngest and stores in Supabase. Notification jobs can forward alerts to Slack/PagerDuty.
  5. Debug tracing: Inngest triggers a trace request to the tracer service; tracer callbacks return trace output to the dApp API for storage and UI display.
  6. Ops automation: Inngest jobs track enforcer status, prune history, check chain landing events, and orchestrate staging cleanup via admin wallet transactions.

Next: dive into the runtime enforcement architecture in docs/generic/credible-layer-runtime.md.