Credible Layer Contracts

Smart contracts for the Credible Layer protocol, built with Foundry.

Overview

The Credible Layer is a protocol that enables trustless and verifiable assertion execution on smart contracts. This repository contains the core smart contracts that power the protocol.

Components

                           +------------+------------+            +-------------------------+
###############            |                         |            |                         |
#             #            |                         |            |  Protocol               |
#    User     #----------->+      State Oracle       +----------->|  Admin                  |
#             #            |                         |            |  Verification           |
###############            |                         |            |                         |
                           +------------+------------+            +-------------------------+
                                        |
                                        |
                                        v
                           +------------+------------+
                           |                         |
                           |  Data Availability      |
                           |  Verification           |
                           |                         |
                           +-------------------------+

The State Oracle

The state oracle coordinates protocol admins/managers and network operators. Protocol admins attach assertions to their protocol by adding entries in the state oracle contract. Network operators and/or block builders operate the assertion executor who adhere to the entries of the contracts and enforce the validation of assertions.

State Oracle Behavior

• Each assertion adopter maintains a manager and a set of assertion windows.
• An assertion ID can be registered only once. If removed (inactive), it cannot be re-added—attempting to reuse the same ID will revert.
• Activation and deactivation blocks are enforced via the configured timelock.
• External admin verifiers (owner-based, whitelist) govern who may register new adopters.
• Managers select a registered DA verifier when adding each assertion, enabling per-assertion choice of data availability mechanism from a governance-managed registry.

Protocol Admin Verification

The Protocol Admin Verification interface allows for methods to verify who the rightful admin of a protocol is. This adapter acts as an oracle which verifies who has the administrative authority over the protocol. It is needed for initial registration.

Data Availability Verification

The Data Availability Verification interface ensures that the assertion bytecode is available. Governance can register multiple DA verifiers in the DA verifier registry, and managers select which registered verifier to use when adding each assertion. Two DA verifier implementations are available:

• DAVerifierECDSA: Requires a signature over the assertion ID from a configured DA_PROVER_ADDRESS. When storing the assertion at the Assertion DA, the user will receive the signature in return.
• DAVerifierOnChain: Validates that keccak256(proof) == assertionId, proving that the assertion bytecode is available on-chain through the proof data itself.

Typical data availability layers include network-hosted DA servers, decentralized DA networks, and the underlying network itself.

State Oracle Administration

The State Oracle owner retains privileged controls as a safety net for protocol operations:

• Add or remove admin verifiers: Adjust which verification modules are authorized to verify ownership of new assertion adopters.
• Register or revoke managers: Directly assign, revoke, or reset managers for assertion adopters when necessary.
• Remove assertions: Forcefully deactivate assertions if malicious or unwanted logic is introduced, or if a project requests emergency removal.
• Add or remove DA verifiers: Adjust which data availability verification modules are authorized for use when adding assertions (addDAVerifier, removeDAVerifier).

These controls are intended strictly for emergency response scenarios—such as attacks or lost manager keys—and should be exercised with operational safeguards to avoid disrupting legitimate protocol activity.

Deployment

The deployment scripts (script/DeployCore.s.sol, script/DeployCoreWithCreateX.s.sol, and script/DeployCoreWithStaging.s.sol) provision the core protocol with both DAVerifierECDSA and DAVerifierOnChain implementations. Both DA verifiers are deployed and registered in the DA verifier registry during initialization, allowing managers to select either mechanism when adding assertions.

Environment Variables

Set the following environment variables before running the deployment scripts:

• STATE_ORACLE_MAX_ASSERTIONS_PER_AA
• STATE_ORACLE_ASSERTION_TIMELOCK_BLOCKS
• STATE_ORACLE_ADMIN_ADDRESS
• DA_PROVER_ADDRESS
• DEPLOY_ADMIN_VERIFIER_OWNER (true/false)
• DEPLOY_ADMIN_VERIFIER_WHITELIST (true/false)
• ADMIN_VERIFIER_WHITELIST_ADMIN_ADDRESS (required when whitelist verifier is enabled)

The following additional variables apply only to DeployCoreWithStaging.s.sol:

• STAGING_STATE_ORACLE_MAX_ASSERTIONS_PER_AA
• STAGING_STATE_ORACLE_ASSERTION_TIMELOCK_BLOCKS

Deployment Overview

Running DeployCore or DeployCoreWithCreateX will:

1. Deploy the DA verifier (ECDSA) and log its address.
2. Deploy the DA verifier (OnChain) and log its address.
3. Deploy AdminVerifierOwner if DEPLOY_ADMIN_VERIFIER_OWNER=true and log its address.
4. Deploy AdminVerifierWhitelist if DEPLOY_ADMIN_VERIFIER_WHITELIST=true (using ADMIN_VERIFIER_WHITELIST_ADMIN_ADDRESS as constructor owner) and log its address.
5. Deploy the StateOracle implementation and log its address.
6. Deploy the proxy, initialize it with the configured admin verifiers and DA verifiers, and log the proxy address.

Console output will include labeled addresses for each deployed contract, e.g.:

DA Verifier (ECDSA) deployed at <address>
DA Verifier (OnChain) deployed at <address>
Admin Verifier (Owner) deployed at <address>
Admin Verifier (Whitelist) deployed at <address>
State Oracle Implementation deployed at <address>
State Oracle Proxy deployed at <address>

Installation

1. Clone the repository:

git clone https://github.com/phylax/credible-layer-contracts
cd credible-layer-contracts

2. Install dependencies:

forge install

CreateX

The forge script script/DeployCoreWithCreateX uses the CreateX contract factory for maintaining and controlling contract addresses of the protocol. The deployment address of CreateX is 0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed. If CreateX is not deployed on your chain, you will find a helper script to deploy CreateX at shell/deploy_create_x.sh.

Run

FUNDER_PRIVATE_KEY="0x..." \
RPC_URL="" \
./shell/deploy_create_x.sh

Note: The funder account will send 0.5 ether to the deployer account of CreateX.

For more information about CreateX see https://github.com/pcaversaccio/createx.

Testing with Anvil

To deploy the protocol on an anvil instance run

anvil
cast rpc anvil_setBalance "0x8d63e0FE87CA36E06a076584fCA651A684D4c97d" "0xDE0B6B3A7640000" --rpc-url http://localhost:8545

FUNDER_PRIVATE_KEY="0xac431098061ca49f5b36121d01a17d30e1d0624227d08b583ff328f1efe0d4a2" \

RPC_URL="http://localhost:8545" \
./shell/deploy_create_x.sh

STATE_ORACLE_MAX_ASSERTIONS_PER_AA=5 \
STATE_ORACLE_ASSERTION_TIMELOCK_BLOCKS=10 \
STATE_ORACLE_ADMIN_ADDRESS=0xD2EfB83dd46094775188d927323b2523EaE3d087 \
DA_PROVER_ADDRESS=0x670cFA8781BF365Aefb6c048CDc522B857946C71 \
DEPLOY_ADMIN_VERIFIER_OWNER=true \
DEPLOY_ADMIN_VERIFIER_WHITELIST=true \
ADMIN_VERIFIER_WHITELIST_ADMIN_ADDRESS=0xD2EfB83dd46094775188d927323b2523EaE3d087 \
forge script script/DeployCoreWithCreateX.s.sol --rpc-url http://localhost:8545 --private-key 0xac431098061ca49f5b36121d01a17d30e1d0624227d08b583ff328f1efe0d4a2 --broadcast
```

The contracts will be deployed at

```txt
== Logs ==
  DA Verifier (ECDSA) deployed at 0xE5b59c5AF181D522be5e721D83F8b0F69592A6b0
  DA Verifier (OnChain) deployed at 0x1234567890abcdef1234567890abcdef12345678
  Admin Verifier (Owner) deployed at 0x3e06372d794a48552203069915eA91b223297736
  Admin Verifier (Whitelist) deployed at 0xcaaC06Fc3826D47950aD28fA58bA8D986BBae0A4
  State Oracle Implementation deployed at 0x080f6B740F9CAC60BA17Adab3d763997EEdce1e7
  State Oracle Proxy deployed at 0x6dD3f12ce435f69DCeDA7e31605C02Bb5422597b

In this example the contracts are deployed by

// keccak256("credible-layer-sandbox-deployer")
Private Key: 0xac431098061ca49f5b36121d01a17d30e1d0624227d08b583ff328f1efe0d4a2
Account: (0x8d63e0FE87CA36E06a076584fCA651A684D4c97d)

When broadcasting script/DeployCore.s.sol with the above key, the contracts will always be deployed at the same address. Neither the initCode of the contracts nor the nonce influence the address generation.