diff --git a/assertions-book/assertions/aave-v3-suite.mdx b/assertions-book/assertions/aave-v3-suite.mdx index 6a4fd39..59aee10 100644 --- a/assertions-book/assertions/aave-v3-suite.mdx +++ b/assertions-book/assertions/aave-v3-suite.mdx @@ -23,7 +23,7 @@ We have mocked parts of the protocol in order to properly test the assertions an The Aave V3 assertion suite has been tested quite thoroughly given the early stage of the Credible Layer testing capabilities. We feel confident that the production assertions could be added to an Aave V3 deployment and add value to the security and robustness of the protocol. -We would recommend running the assertions in a test environment against old transactions to ensure that the assertions do not trigger false positives or other unexpected behavior. This is standard best practice that should be followed for any protocol upgrades and does not just apply to assertions. +We recommend running the assertions in a test environment against historical transactions to validate behavior before production promotion. This is standard best practice for protocol upgrades and does not just apply to assertions. ## Here Be Dragons 🐲 diff --git a/assertions-book/assertions/ass08-sum-of-all-positions.mdx b/assertions-book/assertions/ass08-sum-of-all-positions.mdx index 2f95b88..ea8803c 100644 --- a/assertions-book/assertions/ass08-sum-of-all-positions.mdx +++ b/assertions-book/assertions/ass08-sum-of-all-positions.mdx @@ -25,7 +25,7 @@ Uses these cheatcodes: - `ph.context()` and `ph.callinputAt()`: Inspect the triggered position-modifying call - `registerFnCallTrigger()`: Trigger on position-modifying functions -Check the [Modified Keys](/credible/use-case-mappings/unsupported-use-cases/modified-keys) use case for details on what direct position iteration would look like. +Check [Modified Key Discovery](/credible/use-case-mappings/unsupported-use-cases/modified-keys) for details on what direct position iteration would look like. For more information about cheatcodes, see the [Cheatcodes Documentation](/credible/cheatcodes-reference). diff --git a/assertions-book/previous-hacks/abracadabra-gmx-v2-exploit.mdx b/assertions-book/previous-hacks/abracadabra-gmx-v2-exploit.mdx index 7fe0aeb..2d73733 100644 --- a/assertions-book/previous-hacks/abracadabra-gmx-v2-exploit.mdx +++ b/assertions-book/previous-hacks/abracadabra-gmx-v2-exploit.mdx @@ -3,6 +3,8 @@ title: Abracadabra GMX V2 Cauldron Exploit description: Exploit that drained $13.4M from Abracadabra's GMX V2 Cauldron through accounting manipulation in the RouterOrder system --- +This case study explains how the Abracadabra GMX V2 Cauldron exploit worked and which assertion pattern could have constrained the invalid state transition. + ## What Happened This exploit drained $13.4M from Abracadabra's GMX V2 Cauldron through an accounting bug that created "phantom collateral" - allowing the same tokens to be borrowed against multiple times. @@ -108,4 +110,4 @@ The exploit succeeded because of the growing gap between reported and actual val - **During exploit**: `sendValueInCollateral()` extracts 500 USDC, but `orderValueInCollateral()` still returns 1000 USDC equivalent, actual balance = 500 USDC β†’ **Assertion fails** ❌ - **After multiple extractions**: All tokens extracted, but `orderValueInCollateral()` still returns 1000 USDC equivalent, actual balance = 0 USDC β†’ **Assertion fails** ❌ -**Key insight**: This assertion doesn't need to understand the complex GMX V2 order mechanics or the specific accounting bug. It simply enforces the fundamental principle that "you cannot extract more value than actually exists" - a rule the exploit fundamentally violated. \ No newline at end of file +**Key insight**: This assertion doesn't need to understand the complex GMX V2 order mechanics or the specific accounting bug. It simply enforces the fundamental principle that "you cannot extract more value than actually exists" - a rule the exploit fundamentally violated. diff --git a/assertions-book/previous-hacks/abracadabra-hack-3.mdx b/assertions-book/previous-hacks/abracadabra-hack-3.mdx index 29a8f7c..c0fe9fa 100644 --- a/assertions-book/previous-hacks/abracadabra-hack-3.mdx +++ b/assertions-book/previous-hacks/abracadabra-hack-3.mdx @@ -3,6 +3,8 @@ title: Abracadabra CauldronV4 Cook Function Exploit description: Logic flaw in the cook() function allowed bypassing solvency checks, enabling $1.8M in uncollateralized borrowing --- +This case study explains how the Abracadabra CauldronV4 cook function exploit worked and which assertion pattern could have constrained the invalid state transition. + ## What Happened A logic flaw in Abracadabra's `cook()` function allowed an attacker to borrow $1.8M in MIM tokens without posting any collateral. diff --git a/assertions-book/previous-hacks/abracadabra-rounding-error.mdx b/assertions-book/previous-hacks/abracadabra-rounding-error.mdx index 4a38f9f..f1e40a7 100644 --- a/assertions-book/previous-hacks/abracadabra-rounding-error.mdx +++ b/assertions-book/previous-hacks/abracadabra-rounding-error.mdx @@ -3,6 +3,8 @@ title: Abracadabra Rounding Error Attack description: Rounding error in Abracadabra protocol allowed attacker to inflate base value without corresponding adjustment of elastic value --- +This case study explains how the Abracadabra rounding error attack worked and which assertion pattern could have constrained the invalid state transition. + ## What Happened The vulnerability stems from an intricate implementation of a RebaseToken mechanism in the Abracadabra protocol: @@ -76,4 +78,4 @@ contract AbracadabraRebaseInvariantAssertion is Assertion { } ``` -This assertion ensures that when no assets are owed (elastic = 0), there should be no debt shares (base = 0), thereby preventing the exploit. \ No newline at end of file +This assertion ensures that when no assets are owed (elastic = 0), there should be no debt shares (base = 0), thereby preventing the exploit. diff --git a/assertions-book/previous-hacks/balancer-v2-stable-rate-exploit.mdx b/assertions-book/previous-hacks/balancer-v2-stable-rate-exploit.mdx index 2a13d88..180bacf 100644 --- a/assertions-book/previous-hacks/balancer-v2-stable-rate-exploit.mdx +++ b/assertions-book/previous-hacks/balancer-v2-stable-rate-exploit.mdx @@ -3,6 +3,8 @@ title: Balancer V2 Rate Manipulation Exploit description: $120m+ lost due to rate manipulation caused by rounding error accumulation --- +This case study explains how the Balancer V2 rate manipulation exploit worked and which assertion pattern could have constrained the invalid state transition. + ## What Happened In November 2025, an attacker systematically manipulated exchange rates in Balancer V2 stable pools by exploiting accumulated rounding errors in the stable pool invariant calculation. @@ -16,7 +18,7 @@ This demonstrates how assertions protect protocols by focusing on *what should n -This assertion was developed by analyzing the observable effects of the exploit (drastic rate changes) rather than the root cause (rounding error accumulation). While this approach provides broad protection against rate manipulation attacks, it may not cover all edge cases or could potentially trigger false positives on legitimate operations that we have not yet discovered. +This assertion was developed by analyzing the observable effects of the exploit (drastic rate changes) rather than the root cause (rounding error accumulation). This approach provides broad protection against rate manipulation attacks and should be validated against representative legitimate operations before production use. **Use with caution.** This assertion should undergo extended testing and monitoring in non-production environments before deployment to production systems. The 3x threshold may need adjustment based on real-world transaction patterns. @@ -176,7 +178,7 @@ We chose **3x (300%)** as the threshold based on the following analysis: - Rate provider updates: If a pool uses yield-bearing tokens with rate providers, legitimate rates should change gradually over time. A 3x change in a single transaction would indicate either oracle manipulation or a severe underlying issue (slashing event, de-pegging) that warrants investigation. - Amplification changes: Limited to 2x per day by protocol, causing minimal per-transaction rate impact -**Trade-off:** The 3x threshold is aggressive enough to catch exploitation attempts while providing margin for legitimate operations. If false positives occur in production, the threshold can be increased to 5x or higher, though this would reduce sensitivity to smaller manipulation attempts. +**Trade-off:** The 3x threshold is aggressive enough to catch exploitation attempts while providing margin for legitimate operations. Teams can tune the threshold upward for protocols whose normal transaction patterns need more room, though this would reduce sensitivity to smaller manipulation attempts. **Disclaimer:** This assertion is conceptual. Based on our analysis of the protocol mechanics, we have not discovered any legitimate operations that would cause rate changes exceeding 3x in a single transaction. However, we cannot guarantee that such edge cases do not exist. Thorough testing and analysis of real-world scenarios and edge cases is required before using this assertion in production. diff --git a/assertions-book/previous-hacks/bunni-xyz-rounding-error.mdx b/assertions-book/previous-hacks/bunni-xyz-rounding-error.mdx index 3038240..7958b84 100644 --- a/assertions-book/previous-hacks/bunni-xyz-rounding-error.mdx +++ b/assertions-book/previous-hacks/bunni-xyz-rounding-error.mdx @@ -3,6 +3,8 @@ title: Bunni XYZ Rounding Error Exploit description: Sophisticated rounding error exploitation in Bunni AMM led to $8.4M loss through disproportionate liquidity manipulation --- +This case study explains how the Bunni XYZ rounding error exploit worked and which assertion pattern could have constrained the invalid state transition. + ## What Happened On September 2, 2025, Bunni was exploited for $8.4M through a rounding error in the protocol's withdrawal mechanism. The attack affected two pools: weETH/ETH on Unichain and USDC/USDT on Ethereum. diff --git a/assertions-book/previous-hacks/bybit-safe-ui.mdx b/assertions-book/previous-hacks/bybit-safe-ui.mdx index a7c59d5..dc06b5b 100644 --- a/assertions-book/previous-hacks/bybit-safe-ui.mdx +++ b/assertions-book/previous-hacks/bybit-safe-ui.mdx @@ -3,6 +3,8 @@ title: Bybit - Compromised Safe Wallet UI description: Safe Wallet UI was compromised by gaining access to the host machine. --- +This case study explains how the Bybit compromised Safe Wallet UI attack worked and which assertion pattern could have constrained the invalid state transition. + ## What Happened Bybit suffered from a security breach in Safe's hosting infrastructure losing 1.4bn USD. diff --git a/assertions-book/previous-hacks/compound-upgrade-bug.mdx b/assertions-book/previous-hacks/compound-upgrade-bug.mdx index 77d4c9d..59ad6ee 100644 --- a/assertions-book/previous-hacks/compound-upgrade-bug.mdx +++ b/assertions-book/previous-hacks/compound-upgrade-bug.mdx @@ -3,6 +3,8 @@ title: Compound Upgrade Bug description: Compound comptroller contract had a one letter bug that allowed users to receive massive amounts of COMP rewards --- +This case study explains how the Compound upgrade bug worked and which assertion pattern could have constrained the invalid state transition. + ## What Happened Compound upgraded their comptroller contract to https://etherscan.io/address/0x374abb8ce19a73f2c4efad642bda76c797f19233 which had a one letter bug on L1217. diff --git a/assertions-book/previous-hacks/euler-finance-donation-hack.mdx b/assertions-book/previous-hacks/euler-finance-donation-hack.mdx index 2bc7317..a83a878 100644 --- a/assertions-book/previous-hacks/euler-finance-donation-hack.mdx +++ b/assertions-book/previous-hacks/euler-finance-donation-hack.mdx @@ -3,6 +3,8 @@ title: Euler Finance Donation Hack description: Euler Finance forgot to add a health check to the donation function --- +This case study explains how the Euler Finance donation hack worked and which assertion pattern could have constrained the invalid state transition. + ## What Happened The Euler Finance hack exploited two key protocol features: diff --git a/assertions-book/previous-hacks/first-depositor.mdx b/assertions-book/previous-hacks/first-depositor.mdx index d5a0b73..c315d34 100644 --- a/assertions-book/previous-hacks/first-depositor.mdx +++ b/assertions-book/previous-hacks/first-depositor.mdx @@ -3,6 +3,8 @@ title: First Depositor Bug description: First depositor bug in Compound / Aave v2 lending protocols --- +This case study explains how the first depositor bug works and which assertion pattern can constrain the invalid state transition. + ## What Happened Background: https://akshaysrivastav.hashnode.dev/first-deposit-bug-in-compoundv2-and-its-forks diff --git a/assertions-book/previous-hacks/gma-aum-jul25-hack.mdx b/assertions-book/previous-hacks/gma-aum-jul25-hack.mdx index 982473c..c1717cb 100644 --- a/assertions-book/previous-hacks/gma-aum-jul25-hack.mdx +++ b/assertions-book/previous-hacks/gma-aum-jul25-hack.mdx @@ -1,7 +1,10 @@ --- title: GMX v1 AUM Manipulation Hack +description: Explanation of the GMX v1 AUM manipulation exploit and assertion patterns that could have constrained it. --- +This case study explains how the GMX v1 AUM manipulation attack worked and which assertion patterns could have constrained the invalid state transition. + ## What Happened On July 9, 2025, [GMX v1 lost around ~\$42 million to an attack](https://x.com/GMX_IO/status/1942989975814820347) that exploited how the protocol calculated its total value (Assets Under Management or AUM). This was GMX's second hack of 2025, following a $13 million loss in March. The attacker used a reentrancy vulnerability to manipulate pricing data, artificially inflating the protocol's apparent value, then immediately withdrew tokens at the inflated price. @@ -24,7 +27,7 @@ The critical vulnerability chain: ### Normal AUM Calculation GMX calculates its total value using this formula: -``` +```text AUM = Physical Tokens + Stablecoins + Unrealized Trading Profits + Fees ``` diff --git a/assertions-book/previous-hacks/hack1-radiant-capital.mdx b/assertions-book/previous-hacks/hack1-radiant-capital.mdx index 8ebc4e3..d30525d 100644 --- a/assertions-book/previous-hacks/hack1-radiant-capital.mdx +++ b/assertions-book/previous-hacks/hack1-radiant-capital.mdx @@ -3,6 +3,8 @@ title: Radiant Capital Hack description: Ownership change of lending pools lead to drain --- +This case study explains how the Radiant Capital hack worked and which assertion pattern could have constrained the invalid state transition. + ## What Happened In October 2024, Radiant Capital was hacked. You can read more about the hack on [Rekt](https://rekt.news/radiant-capital-rekt2/). diff --git a/assertions-book/previous-hacks/hack2-vestra-dao.mdx b/assertions-book/previous-hacks/hack2-vestra-dao.mdx index d42510f..53d5882 100644 --- a/assertions-book/previous-hacks/hack2-vestra-dao.mdx +++ b/assertions-book/previous-hacks/hack2-vestra-dao.mdx @@ -3,6 +3,8 @@ title: Vestra DAO Hack description: Unchecked isActive flag in maturity --- +This case study explains how the Vestra DAO hack worked and which assertion pattern could have constrained the invalid state transition. + ## What Happened In December 2024, VestraDAO was hacked. The hacker exploited a vulnerability in the `unStake` function which allowed users to stake and unstake without waiting for the maturity period. For an in-depth analysis of the hack, you can read this [post](https://x.com/_czepluch/status/1866112404242743590). diff --git a/assertions-book/previous-hacks/uxlink-multisig-hack.mdx b/assertions-book/previous-hacks/uxlink-multisig-hack.mdx index d9bdae8..b18ec25 100644 --- a/assertions-book/previous-hacks/uxlink-multisig-hack.mdx +++ b/assertions-book/previous-hacks/uxlink-multisig-hack.mdx @@ -3,6 +3,8 @@ title: UxLink Multisig Ownership Compromise description: Compromised private keys led to \$10M+ drain from UxLink multisig through threshold manipulation and owner replacement --- +This case study explains how the UxLink multisig ownership compromise worked and which assertion pattern could have constrained the invalid state transition. + ## What Happened On September 22, 2025, UxLink's multisig was compromised through private key theft, resulting in \$11.3M direct theft plus unauthorized minting of 10 trillion tokens worth ~\$28M. Attackers manipulated the multisig configuration to drain funds and gain token minting privileges. diff --git a/assertions-book/previous-hacks/vicuna-finance-hack.mdx b/assertions-book/previous-hacks/vicuna-finance-hack.mdx index 9db1fb3..3f069eb 100644 --- a/assertions-book/previous-hacks/vicuna-finance-hack.mdx +++ b/assertions-book/previous-hacks/vicuna-finance-hack.mdx @@ -3,6 +3,8 @@ title: Vicuna Finance Oracle Manipulation Hack description: Vicuna Finance lost $700K due to LP token oracle manipulation that ignored invariant-based pricing --- +This case study explains how the Vicuna Finance oracle manipulation hack worked and which assertion pattern could have constrained the invalid state transition. + ## What Happened The Vicuna Finance hack resulted in a $700K loss through oracle manipulation of Beets LP tokens used as collateral on the Sonic chain. The Core Bug was that LP tokens were priced using a simple sum formula: `price_lp = price_token1 * amount_token1 + price_token0 * amount_token0` instead of fair pricing that accounts for the underlying pool's constant product formula. diff --git a/credible/apply-assertions.mdx b/credible/apply-assertions.mdx index b98ada1..2840659 100644 --- a/credible/apply-assertions.mdx +++ b/credible/apply-assertions.mdx @@ -3,14 +3,14 @@ title: 'Apply Assertions' description: 'Configure assertions and create a release on the platform using `pcl apply`' --- -This guide walks you through configuring your assertions in `credible.toml` and creating a release on the platform with `pcl apply`. +This guide shows you how to configure your assertions in `credible.toml` and create a release on the platform with `pcl apply`. **Prerequisites**: - [pcl installed](/credible/credible-install) - An assertion [written](/credible/write-first-assertion) and [tested](/credible/testing-assertions) - A [project created](/credible/deploy-assertions-dapp#step-2-create-a-project) in the platform -**What you'll do**: Authenticate, configure `credible.toml`, and create a release. Then review and deploy it in the platform. +**What you'll do**: Authenticate, declare the desired assertion state in `credible.toml`, and create a release. Then review and deploy that release in the platform. ## Step 1: Authenticate @@ -34,7 +34,7 @@ pcl auth status ## Step 2: Configure `credible.toml` -Create a `credible.toml` file at `assertions/credible.toml` in your project root. This file declares which assertions protect which contracts: +Create a `credible.toml` file at `assertions/credible.toml` in your project root. This file declares the desired release state for your project: which contracts are in scope and which assertion files should protect them. ```toml environment = "production" @@ -75,6 +75,10 @@ Each contract address must be unique within the configuration. See the [pcl Refe Set `project_id` in your `credible.toml` to skip the interactive project selection prompt. This is especially useful for CI/CD pipelines. + +`credible.toml` is declarative. If a later release removes a contract or assertion from the manifest, the platform treats that as a requested removal from the project when the release is reviewed, deployed, and the State Oracle timelock expires. + + ## Step 3: Apply Your Assertions Create a release on the platform: @@ -86,7 +90,8 @@ pcl apply This command: 1. Reads your `credible.toml` configuration 2. Builds and compiles the referenced assertion contracts -3. Creates a release on the platform +3. Previews the release changes against the current project state +4. Creates a pending release on the platform after you confirm You'll be prompted to confirm before applying. Use `--yes` to skip the confirmation prompt: @@ -98,18 +103,19 @@ pcl apply --yes `pcl apply` automatically builds your project. You can also run `pcl build` separately to check for compilation errors before applying. -## Step 4: Deploy in the Platform +## Step 4: Review and Deploy in the Platform After applying, complete deployment in the [Phylax platform](https://app.phylax.systems) using the [Deploy Assertions guide](/credible/deploy-assertions-dapp#step-4-deploy-the-assertion): 1. Navigate to your project 2. Click "Deployment" tab 3. Find your assertion and click "Proceed to Review" -4. Select the target contract and environment (Staging or Production) -5. Click "Deploy" and sign the transaction +4. Review the release diff and selected target contracts +5. Select the target environment (Staging or Production) +6. Click "Deploy" and sign the transaction -Creating a release through `pcl apply` does not make the assertion active by itself. The assertion becomes active only after you deploy it through the platform and the configured timelock in the on-chain State Oracle contracts expires. Removals follow the same State Oracle timelock flow. +Creating a release through `pcl apply` does not make the assertion active by itself. The release is pending until an authorized protocol admin, also called a manager, signs the deployment transaction in the platform. The assertion becomes active only after that transaction is accepted on-chain and the configured timelock in the State Oracle contracts expires. Removals follow the same State Oracle timelock flow. ## Troubleshooting diff --git a/credible/architecture-overview.mdx b/credible/architecture-overview.mdx index 0d11bce..1095206 100644 --- a/credible/architecture-overview.mdx +++ b/credible/architecture-overview.mdx @@ -153,7 +153,7 @@ flowchart LR ## Integration Paths - + How protocols deploy and manage assertions @@ -217,6 +217,6 @@ For concrete assertion examples and real-world use cases, explore the [Assertion Detailed reference for assertion functions - Guarantees, assumptions, and failure modes + Guarantees, scope, and operational model diff --git a/credible/assertion-enforcer.mdx b/credible/assertion-enforcer.mdx index 72abcd5..8e8f0f0 100644 --- a/credible/assertion-enforcer.mdx +++ b/credible/assertion-enforcer.mdx @@ -22,7 +22,7 @@ As a [sidecar](/credible/glossary#sidecar), the Assertion Enforcer: - **Operates independently** from the main L2 infrastructure - **Integrates alongside block builders** without changing core protocol rules - **Scales separately** from the main network components -- **Fails gracefully** without affecting L2 operations +- **Preserves network continuity** by keeping block production policy under the network operator's integration This design allows networks to adopt the Credible Layer without modifying their core infrastructure. @@ -102,6 +102,30 @@ The Assertion Enforcer integrates with block builders to ensure only valid trans - The block builder or sequencer receives clear valid/invalid signals - Block production continues normally with validated transactions +## Performance Model + +The Assertion Enforcer is designed to keep the synchronous block-building path small. In the common case, the block builder pays for routing work such as metadata collection, assertion selection, checkpoint creation, and work submission. Assertion execution itself can run separately from that serial path, depending on the network integration. + +The important performance constraint is keeping assertion work bounded and predictable for the transaction workload. Network integrations use bounded queues, publication policies, fine-grained triggers, deterministic gas or runtime limits, and bounded execution surfaces to keep validation predictable. + +The enforcer also avoids network fetches on the transaction hot path. Assertion bytecode is fetched after deployment events and cached before validation. + +## Production Admission and Resource Limits + +Production execution uses the active assertion set admitted through the configured registry and review process. + +Production assertion admission should account for: + +- Protected protocol surface and trigger conditions +- Expected trigger frequency +- Maximum gas or runtime budget +- Expected read footprint +- Deterministic behavior and read-only execution +- Historical backtesting and staging behavior +- Suitability for common acceleration paths, such as compact trace summaries or native helper functions + +These controls keep block-building resources predictable and help protocol teams understand which assertions are ready to promote from staging to production. + ## Operational Expectations (Public) - **Non-invasive**: Runs alongside existing block builders without changing consensus rules @@ -109,14 +133,6 @@ The Assertion Enforcer integrates with block builders to ensure only valid trans - **Staging support**: Networks can validate assertions before enforcing them in production - **Transparent outcomes**: Incidents are visible in the platform and dashboard -## Forced Inclusion Transactions - -Forced inclusion transactions (such as L1β†’L2 deposits) require special handling since they must be included regardless of assertion results. The Credible Layer has mitigation pathways for these scenarios. - - -We have developed a solution for forced inclusion transactions and are actively implementing it. Ask us about it! - - ## Assertion Caching To ensure high-performance validation, the Assertion Enforcer maintains an internal cache of assertion bytecode: @@ -124,7 +140,7 @@ To ensure high-performance validation, the Assertion Enforcer maintains an inter - **On deployment**: When an assertion is deployed on-chain, the Assertion Enforcer detects the event and fetches bytecode from [Assertion DA](/credible/assertion-da) - **During validation**: Assertions are loaded from cache. No network requests occur on the hot path. -This caching strategy ensures validation latency doesn't impact block production times. +This caching strategy keeps assertion data retrieval out of the block-production hot path. ## Learn More @@ -133,6 +149,6 @@ This caching strategy ensures validation latency doesn't impact block production High-level integration for networks and sequencers - Guarantees, assumptions, and failure modes + Guarantees, scope, and operational model diff --git a/credible/assertions-overview.mdx b/credible/assertions-overview.mdx index d6ea846..efb93d6 100644 --- a/credible/assertions-overview.mdx +++ b/credible/assertions-overview.mdx @@ -5,6 +5,8 @@ description: 'Understanding Credible Layer assertions' An [assertion](/credible/glossary#assertion) is a function that checks if a transaction violates a rule. If the rule is violated, the transaction is dropped during block building and never enters a block. +Assertions are most useful when they describe an invalid effect, not every possible path that could produce it. A protocol may not know whether a future failure comes from an oracle issue, signer compromise, integration bug, rounding error, or governance action, but it can still define the state transition that should not be allowed. + ## How Assertions Work When a transaction is submitted to the network: @@ -33,12 +35,18 @@ When a transaction tries to change the owner, this assertion runs. If the owner ## What They Can Do That Regular Solidity Can't +**Enforce effects instead of hooks** +Contract-level checks usually protect the code paths where they were added. Assertions can protect based on the resulting transaction effects, such as balance deltas, storage changes, nested calls, or debt changes. This helps cover paths that were not anticipated when the protocol contracts were originally written. + **Compare before/after states** Regular Solidity only sees the current state during execution. Assertions can compare values before and after a transaction using [cheatcodes](/credible/glossary#cheatcodes) like `ph.loadStateAt` with explicit `ForkId` snapshots. You can also inspect state around a specific matched call by combining `ph.context()` with call-scoped `ForkId` values. **Protect immutable contracts** You can add assertions to contracts without modifying them. No redeployment needed. +**Keep policy separate from protocol mechanics** +Assertions let teams review security rules separately from accounting, settlement, permissioning, and integration logic. This can make it easier to audit what the rule is meant to prevent and to update the rule without upgrading the protected contract. + **Check across multiple contracts** An assertion can read and validate state across multiple contracts in a single check, even if those contracts are in different protocols. @@ -61,11 +69,11 @@ Assertions run [off-chain](/credible/glossary#off-chain-execution) with higher g Assertion functions are limited to 300,000 gas per execution. If an assertion exceeds this limit, the transaction is dropped. -This is a security measure: assertion gas usage can vary depending on the transaction being validated. Without this limit, an attacker could craft a transaction that causes the assertion to exceed gas limits, bypassing the protection. By dropping transactions that cause assertions to run out of gas, the system remains secure. +This bound keeps validation predictable under adversarial inputs. Transactions that exhaust the assertion gas budget are treated as invalid, preserving the enforcement invariant. Stay mindful of gas consumption: - Use [triggers](/credible/triggers) to run assertions only when needed -- Be aware that some cheatcodes like `getCallInputs()` have variable gas costs due to unknown input lengths +- Account for variable gas costs in cheatcodes such as `getCallInputs()`, where input lengths can vary - Optimize your assertion logic to stay within the gas limit - Test with realistic data volumes - see [Gas Limits in Testing](/credible/testing-assertions#gas-limits) diff --git a/credible/backtesting-reference.mdx b/credible/backtesting-reference.mdx index 798a1b4..ca3e459 100644 --- a/credible/backtesting-reference.mdx +++ b/credible/backtesting-reference.mdx @@ -119,7 +119,7 @@ BacktestingTypes.BacktestingResults memory results = executeBacktest( Executes a backtest for a single transaction specified by its hash. This is useful for: - Testing assertions against specific known transactions (such as historical exploits) -- Debugging potential false positives reported during staging (see [Testing Strategy](/credible/testing-strategy) for more on the staging workflow) +- Debugging staging findings (see [How to Plan Assertion Testing](/credible/testing-strategy) for more on the staging workflow) - Quickly validating assertion behavior on a problematic transaction without specifying a block range ```solidity @@ -218,13 +218,13 @@ struct BacktestingResults { **Interpreting Results:** -The `assertionFailures` field indicates how many transactions triggered assertion reverts. Since backtesting runs against historical transactions, non-zero values most commonly indicate false positives in your assertion logic rather than actual exploits. +The `assertionFailures` field indicates how many transactions triggered assertion reverts. Since backtesting runs against historical transactions, review non-zero values to confirm whether they represent expected assertion behavior, logic that needs tuning, or a known exploit window. ```solidity // Check results if (results.assertionFailures > 0) { console.log("Assertion failures detected:", results.assertionFailures); - console.log("Review assertion logic for false positives or gas issues"); + console.log("Review assertion logic, expected behavior, or gas usage"); } // Log detailed results @@ -235,7 +235,7 @@ console.log("Assertion failures:", results.assertionFailures); ``` **Common Causes of Assertion Failures:** -- **False positives:** Assertion logic incorrectly flags legitimate protocol behavior (most common) +- **Assertion tuning needed:** Assertion logic flags legitimate protocol behavior - **Gas limit exceeded:** Assertion ran out of gas (300k limit) during complex operations - **Assertion bugs:** Logic errors in the assertion code - **Known exploits:** If testing against historical exploit blocks, failures may be expected diff --git a/credible/backtesting.mdx b/credible/backtesting.mdx index c1f3309..f28e053 100644 --- a/credible/backtesting.mdx +++ b/credible/backtesting.mdx @@ -3,12 +3,16 @@ title: Backtesting description: Test assertions against historical blockchain transactions --- -Backtesting runs your assertions against actual historical transactions from a specified block range. This helps ensure your assertions work correctly with real transaction patterns and don't trigger false positives on legitimate protocol operations. +Backtesting runs your assertions against actual historical transactions from a specified block range. This helps ensure your assertions behave as expected with real transaction patterns before deployment. If you're looking for the reference documentation on all configuration parameters, see the [Backtesting Reference](/credible/backtesting-reference). + +Backtesting is a development-time validation tool. Running a backtest does not deploy assertions, change the on-chain registry, or affect production enforcement. + + ## How It Works Backtesting operates in two phases: @@ -102,7 +106,7 @@ See the [Balancer V2 Rate Manipulation Exploit](/assertions-book/previous-hacks/ ### Testing a Single Transaction by Hash -For debugging false positives or validating against a specific transaction, use `executeBacktestForTransaction`: +For debugging a staging finding or validating against a specific transaction, use `executeBacktestForTransaction`: ```solidity bytes32 txHash = 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef; @@ -117,7 +121,7 @@ BacktestingTypes.BacktestingResults memory results = executeBacktestForTransacti ``` This is particularly useful for: -- Debugging potential false positives reported during staging (see [Testing Strategy](/credible/testing-strategy)) +- Debugging staging findings (see [How to Plan Assertion Testing](/credible/testing-strategy)) - Quick validation of assertion behavior on a specific transaction - Investigating incidents without needing to know the block number @@ -226,7 +230,7 @@ See [CI/CD Integration](/credible/ci-cd-integration#foundry-profile-configuratio 1. **Start small** - Test with 10-20 blocks first to verify your setup 2. **Use paid RPC providers** - For block ranges over 1,000 3. **Check assertion failures** - Ensure `results.assertionFailures == 0` -4. **Run before deployment** - Catch false positives on real transactions +4. **Run before deployment** - Validate behavior on real transactions 5. **Run manually** - Exclude from CI/CD to avoid long test runs 6. **Debug with single transactions** - Use `executeBacktestForTransaction` to investigate specific failures diff --git a/credible/cheatcodes-overview.mdx b/credible/cheatcodes-overview.mdx index 8bb1137..1882425 100644 --- a/credible/cheatcodes-overview.mdx +++ b/credible/cheatcodes-overview.mdx @@ -13,6 +13,7 @@ Cheatcodes enable functionality that would be impossible or impractical with sta - **Callstack introspection**: Inspect call traces and execution flow in ways not possible with standard EVM tools - **State change tracking**: Monitor specific storage slots and track how they change during transaction execution - **Triggering assertions**: Define precise conditions for when assertions should execute with `onFnCall` and `onTxEnd` triggers +- **Cumulative flow tracking**: Register circuit-breaker triggers for ERC20 inflows or outflows over rolling windows ## Why Cheatcodes Exist @@ -36,6 +37,7 @@ Use cheatcodes when you need to: - **Compare state changes**: Check if values changed correctly (e.g., "balance decreased by exactly the withdrawal amount") - **Validate call patterns**: Ensure functions were called in the correct order or with expected parameters - **Monitor storage**: Track changes to specific storage slots that represent critical protocol state +- **Limit cumulative flows**: Trigger checks after ERC20 inflows or outflows exceed configured rolling-window thresholds - **Optimize performance**: Use triggers to run assertions only when relevant state changes occur diff --git a/credible/credible-introduction.mdx b/credible/credible-introduction.mdx index ceddde6..e72ae88 100644 --- a/credible/credible-introduction.mdx +++ b/credible/credible-introduction.mdx @@ -3,6 +3,8 @@ title: 'Introduction' description: 'Block exploits before they execute by linking security rules to your smart contracts on-chain.' --- +Use this page to understand what the Credible Layer is and choose the right documentation path for your goal. + ## What is the Credible Layer? The Credible Layer is security infrastructure that enables developers to link security rules to their smart contracts on-chain. Then, the network validates every transaction that interacts with their smart contracts against their security rules, dropping any invalidating transaction. @@ -70,7 +72,7 @@ Use this page to choose the right kind of documentation for what you need next: - **No contract changes** β€” Add protection to any contract, including immutable ones - **Transparent & verifiable** β€” All rules are public Solidity, auditable by anyone - **No external execution services** β€” Enforcement runs within the network’s block-building flow -- **Zero false positives** β€” Binary enforcement based on your rules, no AI guessing +- **Deterministic decisions** β€” Binary enforcement based on your rules, not opaque scoring ## Community & Support diff --git a/credible/credible-layer-overview.mdx b/credible/credible-layer-overview.mdx index 63192ce..3adcf14 100644 --- a/credible/credible-layer-overview.mdx +++ b/credible/credible-layer-overview.mdx @@ -3,6 +3,8 @@ title: 'High-Level Overview' description: 'High-level overview of the Credible Layer system that explains how exploit prevention works, without requiring deep technical knowledge.' --- +This explanation describes how the Credible Layer prevents invalid transactions before execution and why that model matters for protocol teams and networks. + ## Introduction Phylax's real-time security system detects and pre-emptively removes exploits before losses can be realized. @@ -15,7 +17,7 @@ Phylax's real-time security system detects and pre-emptively removes exploits be At a glance: -- **Security rules** are defined by the protocol team and deployed on-chain as [assertions](/credible/glossary#assertion) +- **Security rules** are defined by the protocol team as [assertions](/credible/glossary#assertion), with assertion IDs registered on-chain and bytecode served through [Assertion DA](/credible/assertion-da) - **The network** validates every transaction against relevant assertions before adding them to blocks - **Invalid transactions** are [dropped](/credible/glossary#drop). If an assertion fails, the transaction never executes @@ -146,7 +148,7 @@ Once assertions are defined, they need to be deployed to protect your contracts. ![Submitting assertions for enforcement](/images/overview-step-2.png) -The [Phylax platform](https://app.phylax.systems) submits assertions to the Credible Layer smart contracts, which deploy them on-chain. These contracts are the source of truth and supply the network with the relevant assertions when a transaction interacts with a protected contract. +The [Phylax platform](https://app.phylax.systems) creates releases and submits assertion changes to the Credible Layer smart contracts. Those contracts are the source of truth for which assertion IDs protect which contract addresses and when changes become active. Assertion bytecode is stored in [Assertion DA](/credible/assertion-da) and fetched by the enforcer before validation. #### How Enforcement Works @@ -168,7 +170,7 @@ Each contract that has assertions is checked by the sidecar, which simulates the 4. If all assertions pass, the transaction is included in the block 5. If any assertion fails, the transaction is dropped -This validation process never exceeds the time to produce a block. The Credible Layer adapts to each network's architecture while maintaining the same security guarantees. +The validation path is designed to keep assertion lookup and execution bounded for each network integration. The Credible Layer adapts to each network's architecture while preserving the same core model: protocol-authored assertions inform the block inclusion decision. For the full technical flow, see [Architecture](/credible/architecture-overview). diff --git a/credible/dapp-incidents.mdx b/credible/dapp-incidents.mdx index b743aec..8608e14 100644 --- a/credible/dapp-incidents.mdx +++ b/credible/dapp-incidents.mdx @@ -3,7 +3,7 @@ title: 'Incidents' description: 'View incidents prevented by the Credible Layer' --- -Incidents show when transactions were dropped because they violated assertions protecting contracts. This happens when a transaction that interacted with an assertion-protected contract was dropped by the [Enforcer](/credible/glossary#assertion-enforcer) because it caused an assertion to revert. +Incidents group invalidating transactions: transactions that violated assertions protecting contracts. In production, the [Enforcer](/credible/glossary#assertion-enforcer) drops those transactions before settlement. In staging, the platform records that the transaction would have been dropped, but the transaction still lands on the live network because staging is observe-only. For the end-to-end flow, see the incident lifecycle diagram in @@ -12,7 +12,7 @@ For the end-to-end flow, see the incident lifecycle diagram in ## How Incidents Are Grouped -An incident represents the invalidation of an assertion over a one-hour time period. Multiple dropped transactions can belong to the same incident if they violate the same assertion within that window. +An incident represents the invalidation of an assertion over a one-hour time period. Multiple invalidating transactions can belong to the same incident if they violate the same assertion within that window. **Why group transactions into incidents?** @@ -108,13 +108,22 @@ See [Integrations](/credible/dapp-integrations) for setup instructions. ## Public Transparency Incidents -The Transparency dashboard includes a public incidents list with limited metadata for visibility. -Detailed transaction and trace views are only available to project managers. +The public explorer includes a limited invalidations view for transparency. Detailed transaction payloads, traces, and project-specific incident evidence are only available to project managers and collaborators with access. + +Detailed invalidation evidence is scoped to the project team so they can triage with full payloads and traces while public views remain concise. + +### Staging vs. Production + +| Environment | What an invalidation means | User impact | +| --- | --- | --- | +| Staging | The transaction would have violated an assertion under production enforcement | The transaction is recorded for review but is not dropped | +| Production | The transaction violated an enforced assertion | The transaction is dropped before settlement | ## Use Cases - Monitor when assertions prevent violations for your projects -- Understand attack patterns and attempted exploits targeting your protocol +- Review attempted invalid transactions targeting your protocol +- Tune assertions based on staging invalidations before production promotion - Add or refine assertions based on incident data diff --git a/credible/dapp-integration.mdx b/credible/dapp-integration.mdx index 4d1cc4a..95393f6 100644 --- a/credible/dapp-integration.mdx +++ b/credible/dapp-integration.mdx @@ -1,15 +1,19 @@ --- -title: 'Platform Integration Overview' -description: 'High-level integration path for protocols adopting the Credible Layer' +title: 'How to Plan a Platform Integration' +description: 'Plan the platform, authorization, and rollout work for a protocol adopting the Credible Layer' --- -Use this page when your goal is to plan how a protocol team would adopt the Credible Layer. +This guide shows you how to plan the platform, authorization, and rollout work for a protocol team adopting the Credible Layer. If you are ready to execute deployment, use [Deploy Assertions with the Platform](./deploy-assertions-dapp). If you need background on how the system works, start with the [Architecture Overview](./architecture-overview). -This page outlines the minimum steps and interfaces needed to get protected. +Use it before deployment to identify the contracts, assertions, admins, and environments involved in the rollout. + + +Project creation and assertion deployment require authorization for the target contracts. Depending on the contract and network, authorization can happen through an on-chain admin verifier such as `owner()` or through [manual verification](/credible/manual-verification). + ## Adoption Workflow @@ -41,6 +45,23 @@ flowchart LR - Staging vs production deployments - Incident notification routing and monitoring +## Coverage Planning + +Before writing assertions, map the surfaces you intend to protect: + +- Protected contracts and external entry points +- Privileged roles and admin operations +- Critical state variables and accounting relationships +- Oracle, bridge, vault, and downstream market dependencies +- High-risk user flows, such as borrows, withdrawals, upgrades, and parameter changes +- Known gaps that the first assertion release will not cover + +This map helps the protocol team decide which assertions belong in the first release and which risks should be handled by later releases or operational runbooks. + +## Authorization Requirements + +Before assertions can be deployed for a contract, the platform needs to determine which protocol admin can manage that contract's assertion lifecycle. The common path is owner-based verification. If your contracts do not expose a supported ownership interface, use [How to Request Manual Verification](/credible/manual-verification) to understand the fallback process. + ## Deployment Modes - **Staging**: test and iterate on assertions without impacting production users diff --git a/credible/dapp-integrations.mdx b/credible/dapp-integrations.mdx index fccee78..032364a 100644 --- a/credible/dapp-integrations.mdx +++ b/credible/dapp-integrations.mdx @@ -6,7 +6,7 @@ description: 'Configure Slack and PagerDuty to receive real-time incident notifi Set up Slack and PagerDuty integrations to receive notifications when [assertion incidents](/credible/dapp-incidents) occur in your Credible Layer projects. -Looking for the high-level adoption flow? See [Platform Integration Overview](/credible/dapp-integration). +Looking for the high-level adoption flow? See [How to Plan a Platform Integration](/credible/dapp-integration). ## Accessing Integration Settings diff --git a/credible/dapp-overview.mdx b/credible/dapp-overview.mdx index 4f4cf50..7a590ff 100644 --- a/credible/dapp-overview.mdx +++ b/credible/dapp-overview.mdx @@ -3,9 +3,9 @@ title: 'Platform Overview' description: 'Overview of the Phylax platform and its role in the Credible Layer stack' --- -The [Phylax platform](https://app.phylax.systems) is the interface for managing assertions and monitoring incidents. Protocol teams use it to create projects, link contracts, and deploy assertions to protect their contracts. When deploying assertions, teams choose between Staging (for testing) or Production (for active protection). Users, investors, and researchers use it to review which assertions protect specific protocols. +The [Phylax platform](https://app.phylax.systems) is the interface for managing assertions and monitoring invalidations. Protocol teams use it to create projects, link contracts, review releases, deploy assertions, and inspect events that would violate those assertions. When deploying assertions, teams choose between Staging (for testing) or Production (for active protection). Users, auditors, and researchers use the public explorer to review which assertions protect specific protocols. -When you create a project and deploy assertions through the platform, those assertions are deployed on-chain. The platform is the control surface, but the on-chain [State Oracle](./credible-layer-contracts#state-oracle) contracts are the source of truth for which assertions are attached to which contracts and when they become active. +When you create a project and deploy assertions through the platform, the project remains an off-chain organizing layer. The on-chain [State Oracle](./credible-layer-contracts#state-oracle) contracts are the source of truth for which assertion IDs are attached to which contract addresses and when those assertions become active. Adding an assertion or removing one is not instantaneous. Both operations pass through a configured timelock enforced by the State Oracle contracts before the change takes effect. @@ -13,7 +13,7 @@ Adding an assertion or removing one is not instantaneous. Both operations pass t ### Transparency Dashboard -The [Transparency Dashboard](/credible/dapp-transparency-dashboard) provides public visibility into all projects and their assertions. Browse, search, and review which protocols are protected and how. +The [Transparency Dashboard](/credible/dapp-transparency-dashboard) provides public visibility into projects and their assertions. Browse, search, and review which protocols are protected and how. ### Projects @@ -21,10 +21,10 @@ The [Projects](/credible/dapp-projects) interface enables protocol teams to crea ### Incidents -The [Incidents](/credible/dapp-incidents) page tracks assertion violations that were prevented, showing when transactions were dropped and which assertions caught them. +The [Incidents](/credible/dapp-incidents) page tracks invalidations: transactions that violated assertions in production, or would have violated assertions in staging. Production invalidations correspond to transactions that were dropped before settlement. Staging invalidations are observe-only records that help teams tune assertions before promotion. - - Landing Page + + Phylax Explorer projects page showing public projects ## Authentication @@ -37,16 +37,17 @@ Authentication is required to create and manage projects. Open the platform at [ ## Key Features -- **Public Transparency**: All projects and assertions are publicly visible -- **Unified Management**: Manage all assertions for your protocol from one interface -- **Incident Monitoring**: Track when assertions prevent violations -- **Verifiable Security**: Users can verify protection before interacting with protocols +- **Public transparency**: Browse public projects, protected contracts, and assertion posture +- **Release review**: Inspect assertion changes before signing on-chain deployment transactions +- **Unified management**: Manage assertion releases, project metadata, and notification settings from one interface +- **Invalidation monitoring**: Track assertion failures in staging and production +- **Verifiable security**: Users can verify protection before interacting with protocols ## Getting Started - Browse and search all projects and assertions + Browse and search public projects and assertions Create and manage your protocol projects @@ -55,7 +56,7 @@ Authentication is required to create and manage projects. Open the platform at [ Step-by-step guide to deploying assertions - Track assertion violations that were prevented + Track production drops and staging invalidations Get started with pcl @@ -66,10 +67,10 @@ Authentication is required to create and manage projects. Open the platform at [ Understand ownership requirements - + Fallback process for immutable contracts - + High-level adoption flow for protocol teams diff --git a/credible/dapp-projects.mdx b/credible/dapp-projects.mdx index da9efd6..354aeef 100644 --- a/credible/dapp-projects.mdx +++ b/credible/dapp-projects.mdx @@ -10,9 +10,13 @@ Projects are the organizational unit in the [Phylax platform](https://app.phylax A project groups together: - One or more smart contract addresses - Assertions that protect those contracts +- Pending and deployed releases +- Staging and production invalidations +- Notification settings and project events +- Collaborators and role-based access - Project metadata (name, description, target chain) -Projects enable you to manage all your protocol's assertions from a single interface. +Projects enable you to manage all your protocol's assertions from a single interface. The project itself is an off-chain organizing layer; the on-chain [State Oracle](/credible/credible-layer-contracts#state-oracle) remains the source of truth for which assertions are active for each protected contract. ## Creating a Project @@ -30,16 +34,16 @@ To create a new project: - Only contracts where your wallet is authorized can be added - The platform verifies admin access via the network's admin verifier (often owner-based) 6. Review your project details -7. Click "Save and publish" to create the project +7. Click "Create Project" to create the project - Creating a Project + Create project form in the Phylax platform Only authorized admins can create a project for a contract. Most deployments use owner-based verification by default. See [Ownership Verification](/credible/ownership-verification) for details. -For contracts that don't pass the default verifier, a [Manual Verification](/credible/manual-verification) process may be available. +For contracts that don't pass the default verifier, you may be able to [request manual verification](/credible/manual-verification). ## Managing Projects @@ -50,7 +54,7 @@ Once created, you can manage your project through the project dashboard: - See all contract addresses in the project - View project metadata - See all assertions -- See all events (timeline for the project) +- See project events in the audit log, including assertion, contract, release, notification, collaborator, and invalidation activity - See all [incidents](/credible/dapp-incidents) ### Add or Remove Contracts @@ -60,7 +64,7 @@ Once created, you can manage your project through the project dashboard: ### Deploy Assertions - Deploy assertions to your project via `pcl apply` -- Link assertions to specific contracts through the platform +- Review release changes through the platform - View all active assertions protecting your contracts @@ -79,11 +83,26 @@ Here you can update the project name, description, and delete the project. **Transfer Project Ownership:** You can transfer projects and contracts (including their associated assertions) to other wallets. This allows you to transfer project ownership while maintaining all linked assertions and contracts. +**Protocol admin / manager wallet:** +The wallet that signs assertion lifecycle transactions can be separate from the day-to-day platform account. Use this separation when your team wants project collaborators to review releases and incidents without requiring routine access to the multisig or governance wallet that controls deployment. + +**Access controls:** +Admins can invite collaborators by email or wallet address. Use roles to separate review work from deployment authority: + +| Role | Typical permissions | +| --- | --- | +| Viewer | View incidents and project information without making changes | +| Editor | Create releases and configure notifications | +| Admin | Manage members, settings, and the protocol manager wallet | + +**Analytics sharing:** +Detailed invalidation evidence is scoped to project members. Admins can opt in to share invalidations or transactions dropped by the node operator with Phylax support and network teams for customer support and debugging. + **Integrations:** -Setup integrations to receive notifications when incidents occur. For now you can setup Slack. +Set up integrations to receive notifications when incidents occur, including Slack and PagerDuty where available. - - Project Settings + + Project settings showing analytics sharing controls and integration options ## Project Dashboard @@ -95,10 +114,29 @@ The project dashboard provides a unified view of your project's security: - **Ready for Deployment**: Assertions submitted via `pcl` that need to be linked and deployed - **Assertion Status**: Monitor execution status and any triggered violations. Status shows whether assertions are marked for enforcement/staging or enforced/staged - **Recent Incidents**: View detailed incidents for your project (see [Incidents](/credible/dapp-incidents#project-incidents-manager-view)) +- **Audit Log**: Review project changes, assertion lifecycle events, collaborator changes, release activity, and invalidations over time - **Project Settings**: Update project details and manage contracts - - Project Dashboard with Incident + + Project overview showing releases, contracts, active assertions, status, and network + + +### Audit Log + +The audit log gives your team a chronological record of project activity. Use it to answer what changed, who initiated the change, what entity was affected, and when the change occurred. + +Audit log entries can include: + +- Project creation and profile changes +- Contracts added or removed +- Assertions submitted, activated, or removed +- Production and staging release events +- Protocol manager changes +- Collaborator role changes +- Invalidations and incident-related activity + + + Project audit log showing timestamped project, assertion, contract, manager, and invalidation events ## Next Steps diff --git a/credible/dapp-transparency-dashboard.mdx b/credible/dapp-transparency-dashboard.mdx index f8a293c..4ca39a4 100644 --- a/credible/dapp-transparency-dashboard.mdx +++ b/credible/dapp-transparency-dashboard.mdx @@ -1,9 +1,9 @@ --- title: 'Transparency Dashboard' -description: 'Browse and analyze all projects and their active assertions' +description: 'Browse and analyze public projects and their active assertions' --- -The Transparency Dashboard is a public interface that displays all projects registered on the Credible Layer, their linked contracts, and the assertions protecting them. +The Transparency Dashboard is a public interface that displays projects registered on the Credible Layer, their linked contracts, and the assertions protecting them. For a high-level view of how the platform interfaces with the rest of the system, see @@ -14,16 +14,17 @@ For a high-level view of how the platform interfaces with the rest of the system ### Browse Projects -View all projects and their details: +View public projects and their details: - Project names, descriptions, and target chains - Linked contract addresses - Active assertions protecting each contract - Assertion implementation details, trigger conditions, and parameters -- Recent events related to contracts and assertions being added or removed +- Recent public events related to contracts and assertions being added or removed +- Limited public invalidation records, when available ### Search / Filter -- You can search for projects at any time using the search bar in the top right corner of hitting `cmd/ctrl + k` +- You can search for projects at any time using the search bar in the top right corner or by hitting `cmd/ctrl + k` - You can filter projects by network ## Accessing the Transparency Dashboard @@ -31,8 +32,8 @@ View all projects and their details: 1. Click the "Transparency" tab in the navigation bar 2. Browse projects - - Explorer + + Phylax Explorer projects page showing public projects ## Use Cases @@ -46,10 +47,29 @@ View all projects and their details: - Learn from existing assertion implementations - Copy and adapt assertion patterns for your own protocol +## Visibility Boundaries + +The public explorer is designed to make assertion posture reviewable without exposing private incident evidence. + +Public views can show: +- Projects and protected contracts +- Active assertion posture +- Public project events +- Limited invalidation metadata +- Aggregate invalidation history, such as a reference ID and timestamp + +Private project views are required for: +- Full invalidating transaction payloads +- Execution traces and assertion traces +- Staging invalidations +- Notification and project management settings + +Detailed invalidation evidence is scoped to project managers and approved collaborators. Public views keep the dashboard useful for posture review while private views retain the full payloads and traces needed for triage. + ## Why Users Trust Protected Protocols - **Public registry**: Assertions and protected contracts are visible on-chain -- **Transparent enforcement**: Dropped transactions surface as incidents +- **Transparent enforcement**: Dropped transactions surface as limited public invalidation records and detailed private project incidents - **Auditable rules**: Assertions are published Solidity, not opaque policy ## Next Steps @@ -62,7 +82,7 @@ View all projects and their details: Create your own project - Learn more about incident removal events + Learn more about invalidations Learn how to write assertions diff --git a/credible/deploy-assertions-dapp.mdx b/credible/deploy-assertions-dapp.mdx index 0a329ac..83a10ba 100644 --- a/credible/deploy-assertions-dapp.mdx +++ b/credible/deploy-assertions-dapp.mdx @@ -3,14 +3,14 @@ title: 'Deploy Assertions with the Platform' description: 'Create projects and deploy assertions to protect your contracts' --- -This guide walks you through creating a project in the [Phylax platform](https://app.phylax.systems) and deploying assertions to protect your smart contracts. +This guide shows you how to create a project in the [Phylax platform](https://app.phylax.systems), create a release with `pcl apply`, and deploy assertions to protect your smart contracts. **Prerequisites**: - [pcl installed](/credible/credible-install) - Smart contracts deployed on a supported chain - An assertion [written](/credible/write-first-assertion) and [tested](/credible/testing-assertions) -**What you'll accomplish**: Create a project, link your contracts, and deploy assertions to production. +**What you'll accomplish**: Create a project, link your contracts, create a pending release, and deploy assertions to staging or production. New to the platform? See the [Platform Overview](/credible/dapp-overview) to understand its features. @@ -53,10 +53,10 @@ Authentication links your wallet address with your `pcl` session, allowing you t - Only contracts where your wallet is authorized can be added - The platform verifies admin access via the network's admin verifier (often owner-based) -5. Review and click "Save and publish" +5. Review and click "Create Project" - Creating a Project + Create project form in the Phylax platform @@ -71,7 +71,7 @@ Configure your `credible.toml` and create a release with `pcl apply`: pcl apply ``` -This reads your `credible.toml` configuration, builds the assertion contracts, and creates a release on the platform. See [Apply Assertions](/credible/apply-assertions) for detailed instructions on configuring `credible.toml` and using `pcl apply`. +This reads your `credible.toml` configuration, builds the assertion contracts, previews the requested changes, and creates a pending release on the platform after you confirm. See [Apply Assertions](/credible/apply-assertions) for detailed instructions on configuring `credible.toml` and using `pcl apply`. ## Step 4: Deploy the Assertion @@ -83,7 +83,7 @@ After applying via `pcl`, complete deployment in the platform: 3. Find your assertion and click "Proceed to Review" -4. Select the target contract to protect +4. Review the release diff 5. Review assertion details: - Assertion name and parameters @@ -104,6 +104,10 @@ After applying via `pcl`, complete deployment in the platform: Adding an assertion is not immediate. The deployment transaction registers it in the on-chain [State Oracle](./credible-layer-contracts#state-oracle), and the State Oracle enforces a configured [timelock](./glossary#timelock) before the assertion becomes staged or enforced. + +Projects are managed in the platform, but the deployment transaction should be signed by the protocol admin, also called the manager wallet, that controls assertion lifecycle operations for the protected contracts. Use a multisig or governance-controlled wallet where appropriate. + + The same model applies when you remove an assertion later. Removal is also scheduled through the State Oracle contracts and only takes effect after that configured timelock expires. @@ -122,7 +126,7 @@ After deployment, manage assertions through your project dashboard: | Error | Solution | |-------|----------| -| "Contract ownership verification failed" | Ensure your wallet passes the admin verifier (often `owner()`) or request [Manual Verification](/credible/manual-verification) if available | +| "Contract ownership verification failed" | Ensure your wallet passes the admin verifier (often `owner()`) or [request manual verification](/credible/manual-verification) if available | | "Assertion already exists" | Use a different name or update the existing assertion | | "Authentication expired" | Run `pcl auth login` to refresh | diff --git a/credible/evaluate-credible-layer.mdx b/credible/evaluate-credible-layer.mdx index 5937ebf..cd5b821 100644 --- a/credible/evaluate-credible-layer.mdx +++ b/credible/evaluate-credible-layer.mdx @@ -27,7 +27,7 @@ If you answered β€œyes” to most of the above, Credible Layer is likely a good ## Next Steps - + High-level adoption for protocol teams diff --git a/credible/faq.mdx b/credible/faq.mdx index d1bb27e..0f9cd11 100644 --- a/credible/faq.mdx +++ b/credible/faq.mdx @@ -38,11 +38,11 @@ There are several key advantages: ### How does the Credible Layer differ from other security approaches? The Credible Layer offers several key advantages: -1. **Deterministic Prevention**: Binary enforcement with zero false positives rather than AI/heuristic guessing +1. **Deterministic prevention**: Binary enforcement based on protocol-authored assertions rather than opaque scoring 2. **Pre-execution Protection**: Stop hacks during sequencing rather than detecting after damage 3. **Network-Native Security**: Protocol-controlled rules enforced by the network itself, without relying on external execution services 4. **Transparent Enforcement**: Public, verifiable Solidity rules rather than opaque algorithms -5. **Instant Deployment**: Add new protections without contract modifications, downtime, or governance votes +5. **No contract modifications**: Add new protections without changing the protected contract; activation still follows the configured assertion lifecycle and timelocks **Learn More:** - [Credible Layer Overview - Why Neutrality Matters](/credible/credible-layer-overview#why-neutrality-matters) @@ -56,19 +56,22 @@ While audits provide point-in-time code reviews, the Credible Layer offers conti - [Assertions Book](/assertions-book/assertions-book-intro) ### What is the transparency dashboard? -The transparency dashboard is a tool that allows anyone to view and browse all assertions deployed by different protocols. -It is a useful tool for end users as they can verify the security guarantees of any protocol, while devs can use it to copy assertions from protocols with similar contracts. +The transparency dashboard is a tool that allows anyone to view public projects and their active assertion posture. +It is useful for end users because they can review what protections a protocol has made visible, while developers can use it to learn from assertions used by protocols with similar contracts. **Learn More:** - [Deploy Assertions](/credible/deploy-assertions-dapp) - [Glossary - Transparency Dashboard](/credible/glossary#transparency-dashboard) ### Is the Credible Layer a SaaS protocol? -No. We are a permissionless protocol that enables hack definition and prevention. Enforcement does not rely on external execution services, and protocols do not need to trust third parties beyond the network itself. +No. The Credible Layer is a protocol with a product surface around it: the platform and `pcl` help teams author, review, deploy, and monitor assertions, while the on-chain registry remains the source of truth for active assertion state. + +Access to assertion management is still gated by authorization. Only verified protocol admins can attach assertions to protected contracts, and supported networks may have onboarding or availability constraints. **Learn More:** - [Credible Layer Overview - Why Neutrality Matters](/credible/credible-layer-overview#why-neutrality-matters) - [Architecture](/credible/architecture-overview) +- [Ownership Verification](/credible/ownership-verification) --- @@ -175,7 +178,7 @@ Editing an assertion is straightforward: Yes, you can copy and adapt assertions from other protocols and use them to protect your own protocol. You should make sure that the assertions are compatible with your protocol. It will make the most sense to copy assertions for standard libraries and interfaces. -You will be able to see all assertions deployed by other protocols on the transparency dashboard. +You can inspect public assertion posture on the transparency dashboard. Some project and invalidation details are only visible to project managers and collaborators. **Learn More:** - [Assertions Book](/assertions-book/assertions-book-intro) @@ -202,11 +205,12 @@ You will be able to see all assertions deployed by other protocols on the transp **Learn More:** - [Architecture - Abstract Overview](/credible/architecture-overview#abstract-overview) -### How are forced included transactions handled for OP Stack Rollups? +### How are L1-originated transactions handled for OP Stack rollups? -The solution is currently in development. Ask us about it! +OP Stack integrations define a validation policy for L1-originated deposits as part of the network integration. The policy specifies where assertion validation runs, how results are routed to sequencing components, and which incident metadata is sent to affected protocols. **Learn More:** +- [Network Integration Overview - L1-originated transaction paths](/credible/network-integration#l1-originated-transaction-paths) - [Glossary - Forced Inclusion Transactions](/credible/glossary#forced-inclusion-transactions) ### Does the Credible Layer introduce new trust assumptions or centralization points? @@ -228,10 +232,12 @@ The Credible Layer simply lets protocol teams define assertions that can prevent ### Does the Credible Layer slow down the network? -No. We have performed worst-case stress tests, using the most inefficient operations available (hashing), to execute assertions worth 1bn gas per block without slowing down the block time. This is because the Credible Layer heavily parallelizes execution and can fully utilize CPU cores compared to standard serial execution of transactions. +The Credible Layer is designed to keep assertion overhead bounded and off the serial block-building path where the network integration supports that model. The hot path should mainly pay for tracing, assertion routing, checkpointing, and work submission, while assertion execution can run in parallel worker capacity. + +The practical requirement is that assertion workers keep up with the transaction workload. If assertion execution falls behind, the integration needs bounded backpressure, publication-boundary waiting, or another network-specific policy. **Learn More:** -- [Architecture - PhEVM](/credible/architecture-overview#phevm-phylax-evm) +- [Assertion Enforcer - Performance Model](/credible/assertion-enforcer#performance-model) - [Architecture](/credible/architecture-overview) ### How do you extend the validation logic of the sequencer to the platform? @@ -256,12 +262,13 @@ This way, we ensure that no malicious third party reduces functionality by writi - [Ownership Verification](/credible/ownership-verification) - [Deploy Assertions](/credible/deploy-assertions-dapp) -### My protocol doesn't support the owner interface, can I still use the Credible Layer? +### My protocol doesn't support the owner interface. Can I still use the Credible Layer? -We are working on more authentication techniques to service protocols with non-traditional ownership architectures. Reach out! +Yes, but you may need manual verification. If your contracts are immutable or do not expose an admin interface such as `owner()`, Phylax can verify off-chain evidence that your team controls the protocol and then register the selected protocol admin for the specific contracts. **Learn More:** - [Ownership Verification](/credible/ownership-verification) +- [How to Request Manual Verification](/credible/manual-verification) ### How can you write rules for immutable contracts? diff --git a/credible/fuzz-testing.mdx b/credible/fuzz-testing.mdx index f1828c1..547607a 100644 --- a/credible/fuzz-testing.mdx +++ b/credible/fuzz-testing.mdx @@ -41,7 +41,7 @@ Use `vm.assume()` to filter out invalid inputs that would cause the test to fail 1. **Set reasonable bounds** - Use `vm.assume()` to constrain inputs to valid ranges 2. **Test multiple parameters** - Fuzz multiple inputs simultaneously to catch interaction bugs 3. **Use meaningful ranges** - Consider the actual values your protocol will encounter -4. **Check for reverts** - Ensure assertions don't false-positive on valid edge cases +4. **Check valid edge cases** - Ensure assertions pass for valid edge cases ## Running Fuzz Tests diff --git a/credible/glossary.mdx b/credible/glossary.mdx index 4ceaafe..659a3d2 100644 --- a/credible/glossary.mdx +++ b/credible/glossary.mdx @@ -3,6 +3,8 @@ title: 'Glossary' description: 'This glossary contains terms and concepts specific to the Credible Layer and related technologies.' --- +Use this reference to look up Credible Layer terms, component names, lifecycle states, and platform concepts. + ## Core Concepts ### The Credible Layer @@ -53,7 +55,7 @@ Learn more: [Assertion Enforcer](/credible/assertion-enforcer) The [Phylax platform](https://app.phylax.systems) is the web application interface for interacting with the Credible Layer. It allows protocol teams and end-users to deploy, manage, and view assertions and projects. ### Transparency Dashboard -A tool that allows users to view and browse all assertions deployed by different protocols, providing visibility into their security posture. +A public interface for browsing projects, protected contracts, active assertions, and limited invalidation metadata. Detailed project management data, staging invalidations, transaction payloads, and traces are only available in private project views. ### Sidecar A software architecture pattern where a component runs alongside the main application without changing core protocol rules. The Credible Layer operates as a sidecar to the network's block builder, intercepting and validating transactions during the block building process. @@ -142,7 +144,7 @@ The PCL testing interface that extends Forge's testing capabilities with additio Learn more about testing assertions in the [Testing Guide](/credible/testing-assertions). ### Backtesting -A testing method that runs assertions against historical blockchain transactions from a specified block range. Backtesting helps ensure assertions work correctly with real transactions and don't trigger false positives on legitimate protocol operations. It is a useful tool for testing assertions before deployment. +A testing method that runs assertions against historical blockchain transactions from a specified block range. Backtesting helps ensure assertions behave as expected with real transaction patterns before deployment. Learn more: [Backtesting](/credible/backtesting) @@ -152,10 +154,13 @@ Learn more: [Backtesting](/credible/backtesting) The ability to run complex security rules outside the main blockchain execution, providing significant efficiency gains compared to on-chain validation. ### Forced Inclusion Transactions -Special transactions that must be included in blocks regardless of validation, such as L1->L2 deposits. PCL handles these by intercepting and validating them appropriately. +Special transactions that may have protocol-level inclusion guarantees, such as L1->L2 deposits. Network integrations define the validation policy for these transaction paths. + +### Circuit Breaker +An assertion pattern that limits how much value can flow into or out of a protected contract over a rolling window. Circuit breakers are useful when the goal is to reduce exploit velocity or contain blast radius rather than block one specific function call. ### Verifiability -The transparent and public nature of all assertions deployed on PCL. Since assertions are stored in the Assertion DA and are publicly accessible, any user or auditor can inspect and verify the security mechanisms in place for a protocol. This transparency enables community-driven security reviews and builds trust by making security measures fully auditable. +The ability to inspect the rules and registry state behind a protocol's Credible Layer posture. Assertion IDs and registry entries are on-chain, while assertion bytecode is stored in Assertion DA. Public views expose the protocol's visible assertion posture; private project data remains restricted to authorized project users. ## Prevention diff --git a/credible/interfaces-overview.mdx b/credible/interfaces-overview.mdx index 9e8fd7e..4c80fdf 100644 --- a/credible/interfaces-overview.mdx +++ b/credible/interfaces-overview.mdx @@ -32,6 +32,20 @@ flowchart LR | Enforcer ↔ Registry | Registry events + schema | Network + contracts maintainers | | Enforcer ↔ Assertion DA | Bytecode storage API | DA + enforcer maintainers | +## Product and Protocol Boundaries + +The Credible Layer combines protocol components with Phylax-operated product surfaces. This boundary matters when evaluating trust, availability, and operational ownership. + +| Component | Purpose | Layer | +| --- | --- | --- | +| Credible Layer contracts | On-chain registry, protocol admin authority, assertion windows, and timelocks | Core protocol | +| Assertion Enforcer | Executes active assertions and returns inclusion decisions during block production | Network enforcement | +| Assertion DA | Stores assertion bytecode and source code for enforcers and public verification | Phylax-operated storage today | +| `pcl` CLI | Builds, tests, authenticates, and submits assertion releases | Local developer tooling | +| Backtesting | Replays assertions against historical transactions before promotion | Phylax-operated development service | +| Staging | Runs assertions against live network activity without dropping transactions | Phylax-operated validation environment | +| Platform | Manages releases, incidents, audit logs, collaborators, alerts, and project metadata | Phylax product | + ## Guidance - Keep interface changes backward compatible when possible @@ -42,5 +56,5 @@ flowchart LR - [Architecture Overview](/credible/architecture-overview) - [Trust Model & Guarantees](/credible/trust-model) -- [Platform Integration Overview](/credible/dapp-integration) +- [How to Plan a Platform Integration](/credible/dapp-integration) - [Network Integration Overview](/credible/network-integration) diff --git a/credible/manual-verification.mdx b/credible/manual-verification.mdx index fc5d760..f9fd41c 100644 --- a/credible/manual-verification.mdx +++ b/credible/manual-verification.mdx @@ -1,78 +1,89 @@ --- -title: 'Manual Verification' -description: 'How to authorize a protocol admin when contracts lack owner interfaces' +title: 'How to Request Manual Verification' +description: 'Request protocol admin authorization when contracts lack supported owner interfaces' --- -# Manual Verification +This guide shows you how to prepare a manual verification request when your contracts are immutable or do not expose a supported admin interface such as `owner()`. -Manual verification is the fallback path for protocols whose contracts are immutable or do not expose an admin interface (like `owner()`). In this flow, Phylax verifies off-chain evidence that the requesting team controls the protocol and then registers the selected protocol admin in the on-chain State Oracle registry. + +Manual verification is the fallback path. If your target contracts expose a supported owner interface, use the normal [Ownership Verification](/credible/ownership-verification) and [deployment](/credible/deploy-assertions-dapp) flow instead. + -## Definitions +## Prerequisites -| Term | Definition | -| --- | --- | -| Assertion Group | A smart contract that follows the Assertion Interface and is deployed as EVM bytecode. It is associated with a target smart contract (assertion adopter). | -| Protocol Admin (Manager) | The smart contract or EOA that has permission to deploy, update, and remove assertions for one or more target contracts. | -| Protocol | A group of deployed smart contracts maintained by a company, DAO, or other entity. | -| State Oracle (Registry) | The Credible Layer contract that is the source of truth for protocol admins, assertions, and the target contracts they are attached to. | +- The target contracts do not pass automatic owner-based verification. +- You can identify the contract addresses that need a protocol admin. +- You have selected the smart contract or EOA that should manage assertions for those contracts. +- You can provide evidence that the requesting team controls the protocol. +- You can provide public proof that the organization wants to use the Credible Layer, if required. +- You are willing to share identity or authorization evidence when needed. -## How protocol admin authority is determined +## Step 1: Confirm Automatic Verification Does Not Apply -There are two ways a protocol admin can be authorized: +Check whether the target contracts expose a supported ownership interface. The common automatic path expects an `owner()` function: -### 1) Owner interfaces (automatic) +```solidity +interface IOwnable { + function owner() external view returns (address); +} +``` -If the target contract exposes an `owner()` interface, the registry can verify the admin on-chain and authorize that address as the protocol admin. +If your contracts expose this interface, use [Ownership Verification](/credible/ownership-verification). If they are immutable or use a different ownership architecture, continue with manual verification. -### 2) Manual verification (fallback) +## Step 2: Choose the Protocol Admin Address -When on-chain verification is not possible, Phylax can authorize a protocol team to define a protocol admin address through manual verification. This requires trust in Phylax as a verifier, since Phylax updates the registry with the chosen admin address after reviewing evidence. +Choose the smart contract or EOA that should be allowed to deploy, update, and remove assertions for the target contracts. -## Manual verification eligibility + +Managing assertions is a sensitive role. We recommend using hardware wallets and multisig accounts for protocol admin addresses. + -A protocol must satisfy **all** of the following criteria: +## Step 3: Prepare Code-Control Evidence -- Control over protocol code -- Sufficient evidence that the requesting party is authorized to act for the protocol, assessed in a good-faith, case-by-case review -- Consent to sharing identity, if required +Prepare evidence that the requesting party controls the active, official protocol codebase. Useful signals include: -Manual verification is provided at Phylax's discretion and may be declined for any reason. Approval is not guaranteed. +- Ability to merge pull requests to the active, official repo +- Permission to manage collaborators in the GitHub organization +- Ability to commit and merge a pull request to a default branch -## Verification methods +## Step 4: Prepare Proof of Protocol Intent -**Control over protocol code** -- Must be able to merge PRs to the active, official repo -- Must have permissions to manage collaborators in the GitHub org -- Must be able to commit and merge a PR to a default branch +Prepare strong public signals that the organization wants to use the Credible Layer and that the selected protocol admin address reflects the organization's intent. +Non-exhaustive examples: -**Proof of intent and alignment** - -Phylax will look for strong public signals that the organization wants to use the Credible Layer and that the selected admin address reflects the org's intent. Non-exhaustive examples: -- Proof of control (e.g., signature) from an emergency council or admin multisig -- Posting a GitHub commit hash on the official X account -- Posting a GitHub commit hash in an official Discord +- A signature from an emergency council or admin multisig +- A GitHub commit hash posted from the official X account +- A GitHub commit hash posted in an official Discord - Consent to being recorded on a video call for posterity -## Manual verification will not be offered if +## Step 5: Submit the Request for Review + +Share the target contracts, selected protocol admin address, code-control evidence, and proof of protocol intent with Phylax for review. + +Phylax reviews manual verification requests in good faith on a case-by-case basis. Approval is not guaranteed, and Phylax may decline a request for any reason. + +Manual verification will not be offered if: + +- The protocol is fully anonymous. +- The team refuses to provide public proofs. +- The submitted evidence is insufficient to verify the rightful protocol maintainer or owner. + +## Step 6: Verify the Result -- The protocol is fully anonymous -- The team refuses to provide public proofs -- The Phylax team does not believe it is authorizing the rightful protocol maintainer/owner +If manual verification is approved: -## After manual verification is approved +- The selected protocol admin address is added to the State Oracle registry. +- The protocol admin is associated with the approved contract addresses. +- A 5-day timelock begins before the admin can add assertions, giving the protocol time to react or cancel if needed. -- The selected protocol admin address is added to the State Oracle registry -- The protocol admin is associated with a specific set of contract addresses and can deploy assertions for those contracts -- A 5-day timelock begins before the admin can add assertions, giving the protocol time to react or cancel if needed +Before deploying assertions, confirm that the registered admin address and contract set match the approved request. -## Opt-out / Blacklist +## Opt Out of Registry Additions -**Protocols can request manual verification specifically to be blacklisted: we still verify control, but instead of adding them to the registry, we add their contracts to an opt-out registry that blocks additions from everyone except a provided escape-hatch address.** +Protocols can also request manual verification to opt out of registry additions. Phylax still verifies control, but instead of adding the protocol admin to the registry, Phylax adds the contracts to an opt-out registry. -- Any protocol that wants to opt out can add themselves to an opt-out registry after manual verification confirms control -- This opt-out registry prevents Phylax from adding the specified contracts to the registry (no assertions can be attached to those contracts) -- The only entity that can re-enable registration is an address provided by the platform at the time of blacklisting. This escape hatch allows protocols to opt out of Phylax while preserving the option to opt back in later +The opt-out registry blocks assertion additions for those contracts. The only entity that can re-enable registration is an address provided by the platform at the time of blacklisting. This escape hatch allows protocols to opt out while preserving the option to opt back in later. ## Related docs diff --git a/credible/network-integration.mdx b/credible/network-integration.mdx index a54f49c..df1b7e3 100644 --- a/credible/network-integration.mdx +++ b/credible/network-integration.mdx @@ -44,6 +44,30 @@ Networks provide the following integration surfaces: - **Assertion data access**: the enforcer fetches assertion bytecode from Assertion DA - **Operational monitoring**: incidents and status are surfaced via the Phylax platform +## Integration Policy Decisions + +Network integrations should define how enforcement is applied across the network's transaction paths and traffic management layers. + +### L1-originated transaction paths + +Some rollups include L1-originated transaction paths, deposits, or delayed inboxes alongside ordinary sequencer-selected transactions. The integration policy should specify how assertion validation fits into each path. + +Before production rollout, define: + +- Which L1-originated, deposit, or delayed inbox paths the network supports +- Where assertion validation runs for those transactions +- How validation results are routed into sequencing or block-building policy +- Which application-layer response options protocols can use during the validation window +- What incident metadata is sent to affected protocols + +L1-originated transaction policy is network-specific and should be documented as part of the integration. + +### Ingress traffic management + +Networks can pair assertion validation with ingress-level caching and rate-limit policies for repeated invalid submissions. + +Common controls include exact invalid-transaction caching, broader short-lived fingerprints for repeated attempts against the same assertion and target surface, peer or sender budgets, and clear TTLs for any broad match. + ## Operational Expectations - The enforcer runs alongside the block builder and does not change consensus rules @@ -55,6 +79,7 @@ Networks provide the following integration surfaces: - Identify the block-building hook for transaction validation - Configure access to registry data and assertion bytecode - Ensure the enforcer respects staged vs enforced assertions as set by protocol teams +- Define validation policy for L1-originated transactions and repeated invalid submissions - Set up monitoring and incident review workflows ## Integration Requirements (Public) diff --git a/credible/network-integrations/architecture-op-stack.mdx b/credible/network-integrations/architecture-op-stack.mdx index 2c7792c..4762ea4 100644 --- a/credible/network-integrations/architecture-op-stack.mdx +++ b/credible/network-integrations/architecture-op-stack.mdx @@ -86,6 +86,12 @@ class RollupBoostProxy,AssertionEnforcer rollupBoost - The Assertion DA serves assertion bytecode to the Block Builder, ensuring up-to-date enforcement. - `pcl` and the platform provide interfaces for assertion development, submission and management. +## L1-Originated Transactions + +OP Stack networks can define an L1-originated transaction validation policy alongside the ordinary sequencer-selected transaction path. + +An integration should specify where assertion validation runs, how validation results are reported to sequencing components, and what metadata is sent to the platform. See [Network Integration Overview](/credible/network-integration#l1-originated-transaction-paths) for the general checklist. + ## Transaction Flow ![Transaction Flow](/images/tx-flow-credible.png "OP Stack transaction flow with assertion execution detail") diff --git a/credible/neutrality.mdx b/credible/neutrality.mdx index e622dcb..1e0c6f7 100644 --- a/credible/neutrality.mdx +++ b/credible/neutrality.mdx @@ -10,7 +10,7 @@ As middleware, the Credible Layer extends network capabilities without requiring ## Decentralization Preservation - Networks can remove the Credible Layer anytime and still execute their core functionality -- Protocol teams can remove (or add) assertions anytime +- Protocol teams can add or remove assertions through the configured assertion lifecycle and timelocks - The system passes the "off-switch test" - By avoiding centralized control points, this architecture preserves decentralization for both protocols and networks @@ -34,7 +34,7 @@ Security solutions should optimally **not** add additional trust assumptions or Technical deep dive into system architecture - Guarantees, assumptions, and failure modes + Guarantees, scope, and operational model Common questions about the Credible Layer diff --git a/credible/ownership-verification.mdx b/credible/ownership-verification.mdx index fb8902a..8df8ff9 100644 --- a/credible/ownership-verification.mdx +++ b/credible/ownership-verification.mdx @@ -6,7 +6,7 @@ description: 'Understand how the Credible Layer determines who is allowed to man The Credible Layer uses admin verifier modules to determine who can deploy assertions for a contract. Most deployments use owner-based verification by default. This design will continue to expand with additional ownership patterns. -This page explains the ownership model. If your contracts do not fit the default verifier and you need the process for getting approved, use [Manual Verification](./manual-verification). +This page explains the ownership model. If your contracts do not fit the default verifier and you need the process for getting approved, use [How to Request Manual Verification](./manual-verification). ## Current Implementation @@ -36,7 +36,7 @@ High-level requirements and signals include: After approval, the protocol admin address is added to the registry and a timelock begins before assertions can be deployed. Protocols can also opt out of registry additions if they do not want assertions attached to their contracts. -See [Manual Verification](./manual-verification) for the full process and requirements. +See [How to Request Manual Verification](./manual-verification) for the full process and requirements. ## Future Development diff --git a/credible/pcl-quickstart.mdx b/credible/pcl-quickstart.mdx index f91f965..ed8ecce 100644 --- a/credible/pcl-quickstart.mdx +++ b/credible/pcl-quickstart.mdx @@ -3,8 +3,6 @@ title: 'Quickstart Tutorial' description: 'Tutorial: write, test, and deploy your first assertion with `pcl`' --- -## Introduction - Use this tutorial when you are new to the Credible Layer and want one guided, happy-path run from local project setup to an enforced assertion. By the end of this tutorial, you will: @@ -116,7 +114,7 @@ pcl auth login This will provide you with a URL and an authentication code. You can authenticate via wallet, email, Google, or GitHub. -If authentication fails, first confirm that your wallet is on the correct network and that `pcl` is using the expected auth URL. Then use the [Troubleshooting guide](./troubleshooting) for the common failure modes. +If authentication fails, first confirm that your wallet is on the correct network and that `pcl` is using the expected auth URL. Then use the [Troubleshooting guide](./troubleshooting) for common setup issues. ## 5. Create a Project diff --git a/credible/testing-assertions.mdx b/credible/testing-assertions.mdx index 531d411..600e889 100644 --- a/credible/testing-assertions.mdx +++ b/credible/testing-assertions.mdx @@ -6,7 +6,7 @@ description: Validate assertions locally with `CredibleTest`, realistic test pat Use this guide when you want to validate an assertion locally before staging or production. -For the higher-level testing philosophy, see [Testing Strategy](./testing-strategy). For historical transaction configuration fields, see the [Backtesting Reference](./backtesting-reference). +For the higher-level testing workflow, see [How to Plan Assertion Testing](./testing-strategy). For historical transaction configuration fields, see the [Backtesting Reference](./backtesting-reference). Testing assertions is very similar to writing regular Forge tests. If you're familiar with Forge testing, you'll feel right at home. You get access to all the same testing utilities: diff --git a/credible/testing-strategy.mdx b/credible/testing-strategy.mdx index 6b3d136..d83ead3 100644 --- a/credible/testing-strategy.mdx +++ b/credible/testing-strategy.mdx @@ -1,12 +1,14 @@ --- -title: 'Testing Strategy' -description: 'Where to invest testing effort: deploy to staging early, iterate with real transactions' +title: 'How to Plan Assertion Testing' +description: 'Plan local testing, backtesting, staging, and production promotion for assertions' --- +This guide shows you how to allocate assertion testing effort across local tests, backtesting, staging, and production promotion. + **Summary** - Local testing validates core logic; staging validates real-world behavior -- Deploy to staging early to catch false positives and edge cases +- Deploy to staging early to observe behavior against real transaction flow - Real transactions expose scenarios that are difficult to predict locally - Use backtesting to debug specific transactions with the smallest feedback loop @@ -68,12 +70,14 @@ Backtesting serves two distinct purposes in the development workflow: Before deploying to staging, run a quick backtest against recent transactions: -- Verifies no obvious false positives on normal protocol operations +- Verifies expected behavior on normal protocol operations - Catches trigger mismatches (assertion not running when expected) - Identifies gas issues with realistic transaction complexity Keep block ranges small (10-100 blocks) for this sanity check. The goal is quick verification, not comprehensive coverage. +For production promotion, expect a broader historical review. The exact window depends on protocol risk, transaction volume, network requirements, and the assertions being promoted. At minimum, include representative high-volume periods, known incident windows when applicable, and enough normal activity to measure assertion behavior on normal transactions. + ### 2. Debugging Staging Issues When staging reveals unexpected behavior, backtesting becomes your debugging tool: @@ -112,8 +116,8 @@ Once local tests pass and backtesting shows no obvious issues, [deploy to stagin Check the [platform dashboard](https://app.phylax.systems) regularly for assertion execution status and enable [incident notifications](/credible/dapp-integrations) to get alerted via Slack or PagerDuty. Look for: -- False positives on legitimate operations -- Unexpected assertion behavior or edge cases +- Unexpected invalidations on legitimate operations +- Assertion behavior that needs tuning before production Staging runs assertions but does NOT drop transactions, so you can observe behavior without risk. @@ -142,8 +146,10 @@ The goal is sufficient transaction diversity, not a specific timeframe. As the d Before promoting to production, verify: -- No false positives observed on legitimate transactions +- Expected behavior observed on legitimate transactions - Sufficient transaction diversity to build confidence +- Historical backtesting covers the relevant protocol surfaces and known risky periods +- Trigger frequency, runtime, and gas usage fit the network's production limits - You understand how the assertion behaves across different scenarios @@ -156,7 +162,7 @@ Moving to production means transactions that violate your assertion will be drop **Skipping backtesting entirely:** A quick backtest catches obvious issues before staging and is essential for debugging staging discoveries. -**Deploying directly to production:** Always validate in staging first. The cost of a false positive in production can be high. +**Deploying directly to production:** Always validate in staging first. Production should only use assertions that have passed staging review. **Expecting immediate feedback:** Edge cases may take weeks to surface in staging. Be patient and let real usage patterns emerge. diff --git a/credible/trust-model.mdx b/credible/trust-model.mdx index 034c0bc..3dda04d 100644 --- a/credible/trust-model.mdx +++ b/credible/trust-model.mdx @@ -1,11 +1,11 @@ --- title: 'Trust Model & Guarantees' -description: 'What the Credible Layer guarantees, what it does not, and the operational assumptions' +description: 'Credible Layer enforcement guarantees, scope, and operational model' --- This page summarizes the Credible Layer trust model in plain language. -## What We Guarantee +## Core Guarantees - **Deterministic enforcement**: given the same on-chain state and assertion code, enforcement results are deterministic @@ -13,24 +13,24 @@ This page summarizes the Credible Layer trust model in plain language. blocks by networks running the enforcer - **Transparent rules**: assertions are public Solidity code and can be audited by anyone -## What We Do Not Guarantee +## Scope of Guarantees -- **Assertion correctness**: teams are responsible for writing accurate assertions -- **Complete coverage**: only behaviors covered by assertions are enforced -- **Off-chain security**: custodial, UI, or off-chain service risks are out of scope +- **Assertion-defined coverage**: enforcement applies to the behaviors captured by active assertions +- **Protocol-authored rules**: protocol teams define and maintain the rules that protect their contracts +- **Integrated environments**: enforcement applies on networks and environments where the enforcer is integrated and the assertion is active +- **On-chain coordination**: the State Oracle contracts remain the source of truth for assertion lifecycle state and timelocks -## Operational Assumptions +## Operational Model - The network runs the Assertion Enforcer during block building - The enforcer can access registry data (from on-chain events) and assertion bytecode - The network follows its normal transaction validity rules alongside enforcement +- Production assertions are admitted with bounded triggers and resource limits before they become part of the active execution set +- Network integrations define continuity behavior for maintenance windows and degraded components -## Failure Modes (High Level) +## Assurance Practices -- **Enforcer unavailable**: the network continues normal operation without enforcement until the - enforcer is restored -- **Registry misconfiguration**: assertions may not apply to intended contracts -- **DA connectivity issues**: new assertions may be delayed until bytecode is reachable +Teams build confidence by validating assertions locally, backtesting against historical transactions, running assertions in staging, and promoting to production only after sufficient review. See [How to Plan Assertion Testing](/credible/testing-strategy) for the recommended workflow. ## Next Steps diff --git a/credible/use-case-mappings/call-frame-context.mdx b/credible/use-case-mappings/call-frame-context.mdx index fda6385..a16fb45 100644 --- a/credible/use-case-mappings/call-frame-context.mdx +++ b/credible/use-case-mappings/call-frame-context.mdx @@ -3,6 +3,8 @@ title: Call Frame Context description: Gain fine-grained context about a call frame in order to improve the precision of assertions by allowing to access pre and post call frame states. --- +Call frame context mappings describe how assertions can use matched call context and call-scoped snapshots to validate state around a specific function call. + ## Status - [x] Supported @@ -112,9 +114,9 @@ contract CallFrameContextAssertion is Assertion { - **Oracle price updates:** Verify each price update doesn't exceed deviation limits (see [Intra-TX Oracle Deviation](/assertions-book/assertions/ass28-intra-tx-oracle-deviation)) - **Rate provider validation:** Check rate changes before and after swaps (see [Balancer V2 Stable Rate Exploit](/assertions-book/previous-hacks/balancer-v2-stable-rate-exploit)) -## Known Limitations +## Implementation Considerations -- **Recursive function calls:** Recursive calls will compound state changes similar to transaction-level execution. Users should ensure no recursive function calls are possible if precise call frame tracking is required. +- **Recursive function calls:** Recursive calls compound state changes similar to transaction-level execution. Account for recursive call paths when precise call frame tracking is required. ## Related Use Cases diff --git a/credible/use-case-mappings/function-call-inputs.mdx b/credible/use-case-mappings/function-call-inputs.mdx index f5fe394..e70736f 100644 --- a/credible/use-case-mappings/function-call-inputs.mdx +++ b/credible/use-case-mappings/function-call-inputs.mdx @@ -3,6 +3,8 @@ title: Function Call Inputs description: Capture and verify function input parameters to validate that the resulting end state is as expected. --- +Function call input mappings describe how assertions can inspect call data for a target function and compare the resulting state transition against expected behavior. + ## Status - [x] Supported @@ -110,7 +112,7 @@ contract FunctionCallInputsAssertion is Assertion { - Consider all functions that modify relevant state variables - Account for complex state dependencies between function calls -- **State reconstruction limitations:** +- **State reconstruction considerations:** - Manual tracking required for parameter-dependent storage slots (i.e. keys of mappings) - No direct access to intermediate call frame states - Order guarantees only within same function calls, not across different functions @@ -120,7 +122,7 @@ contract FunctionCallInputsAssertion is Assertion { - Balance mappings of tokens or deposits/withdrawals - Ownership changes -## Known Limitations +## Implementation Considerations 1. **Parameter-dependent Storage Access** - Storage slots that depend on function parameters lack automated tracking diff --git a/credible/use-case-mappings/intro-use-case-mapping.mdx b/credible/use-case-mappings/intro-use-case-mapping.mdx index 5d6e02d..67f831d 100644 --- a/credible/use-case-mappings/intro-use-case-mapping.mdx +++ b/credible/use-case-mappings/intro-use-case-mapping.mdx @@ -1,8 +1,10 @@ --- -title: Introduction -description: This section documents the various use cases that can be implemented with the Credible Layer's cheatcodes. Each mapping demonstrates how specific cheatcodes enable different types of on-chain assertions. +title: Use Case Mappings +description: Reference for assertion capabilities enabled by Credible Layer cheatcodes. --- +Use this reference to look up which Credible Layer cheatcodes support each assertion use case and what implementation constraints apply. + ## What You'll Find Here - **Use Case Mappings**: Documentation of different assertion capabilities enabled by Credible Layer cheatcodes @@ -11,6 +13,6 @@ description: This section documents the various use cases that can be implemente Each mapping includes example code with both the protocol contract being monitored and the corresponding assertion implementation. The examples demonstrate the technical approach for implementing different types of validations using the available cheatcodes. -The mappings are organized to help you understand what's currently possible with the Credible Layer. For each use case, you'll find implementation details, example code, and notes about any limitations or considerations. +The mappings are organized to help you choose the right Credible Layer primitive for each use case. For each use case, you'll find implementation details, example code, and notes about implementation considerations. -We also document unsupported use cases to provide transparency about current system limitations and potential future capabilities. +Some pages describe use cases that require alternate patterns or future primitives, so you can choose the right implementation path. diff --git a/credible/use-case-mappings/read-logs.mdx b/credible/use-case-mappings/read-logs.mdx index d1abb39..a5358d0 100644 --- a/credible/use-case-mappings/read-logs.mdx +++ b/credible/use-case-mappings/read-logs.mdx @@ -3,6 +3,8 @@ title: Read Logs description: Capture and verify logs as a signal for changes in the state of the contract. --- +Read log mappings describe how assertions can inspect emitted events and use them as signals for state changes during a transaction. + ## Status - [x] Supported @@ -113,7 +115,7 @@ contract ReadLogsAssertion is Assertion { - Consider all functions that modify relevant state variables - Account for complex state dependencies between function calls -- **State reconstruction limitations:** +- **State reconstruction considerations:** - Manual tracking required for parameter-dependent storage slots (i.e. keys of mappings) - No direct access to intermediate call frame states - Order guarantees only within same function calls, not across different functions @@ -124,7 +126,7 @@ contract ReadLogsAssertion is Assertion { - Ownership changes - Whenever a log is emitted, which represents a state change, it can be used to reconstruct the expected behavior -## Known Limitations +## Implementation Considerations 1. **Parameter-dependent Storage Access** - Storage slots that depend on event parameters lack automated tracking diff --git a/credible/use-case-mappings/state-changes.mdx b/credible/use-case-mappings/state-changes.mdx index 09ea9d7..de75678 100644 --- a/credible/use-case-mappings/state-changes.mdx +++ b/credible/use-case-mappings/state-changes.mdx @@ -3,6 +3,8 @@ title: Variable State Change Tracking description: Track and assert all values assigned to a specific storage variable during a transaction's execution, including intermediate states. --- +Variable state change mappings describe how assertions can track writes to a specific storage slot during transaction execution. + ## Status - [x] Supported @@ -75,17 +77,17 @@ contract StateChangesAssertion is Assertion { - Price oracle increases/decreases max by x% - Address changed to a whitelisted value -## Known Limitations +## Implementation Considerations 1. **Slot granularity** - - User can only request on a slot level, not on a variable level - - User has to know the storage layout of the contract - - User has to potentially shift/mask for the correct bits of the slot + - Request state changes at the slot level + - Use the target contract's storage layout to select the right slot + - Shift or mask values when the relevant variable occupies only part of a packed slot 2. **Slot Coupling** - - Arrays of state changes of different slots don't give you timing guarantees - - i.e. There is no guarantee that `changes1[1]` and `changes2[1]` held the value at the same time - - Unless the user knows exactly when state changes occur, it is not recommended to assume timing guarantees + - Treat arrays of state changes for different slots as independent observations + - Align values across slots only when your assertion explicitly establishes that relationship + - Use protocol-specific knowledge of write order when timing relationships matter ## Future Improvements diff --git a/credible/use-case-mappings/storage-lookups.mdx b/credible/use-case-mappings/storage-lookups.mdx index 7ca44b2..e72b65e 100644 --- a/credible/use-case-mappings/storage-lookups.mdx +++ b/credible/use-case-mappings/storage-lookups.mdx @@ -3,6 +3,8 @@ title: Storage Lookup description: Access the value of a storage variable at a specific address. Even if the variable is not publicly accessible and not part of the contract's state. --- +Storage lookup mappings describe how assertions can read raw storage slots from a target contract when a public getter is not available. + ## Status - [x] Supported @@ -84,9 +86,9 @@ contract StorageLookupAssertion is Assertion { - Access internal contract state for validation - Verify ownership or admin privileges properly set -## Known Limitations +## Implementation Considerations -1. **State snapshot limitations:** +1. **State snapshot semantics:** - Values can only be read from pre or post states of the executed transactions - No access to intermediate state changes during transaction execution - To work around this, use `getStateChanges()` to capture all intermediate values diff --git a/credible/use-case-mappings/unsupported-use-cases/modified-keys.mdx b/credible/use-case-mappings/unsupported-use-cases/modified-keys.mdx index f7ea874..1532ffc 100644 --- a/credible/use-case-mappings/unsupported-use-cases/modified-keys.mdx +++ b/credible/use-case-mappings/unsupported-use-cases/modified-keys.mdx @@ -1,7 +1,10 @@ --- -title: Modified Keys -description: Get the modified keys of a mapping +title: Modified Key Discovery +description: Discover mapping keys through transaction inputs and emitted logs --- + +Modified key discovery describes how to identify mapping keys that changed during a transaction by using transaction inputs, emitted logs, and explicit storage-slot knowledge. + ## Status - [ ] Supported @@ -44,7 +47,7 @@ function assertionUseCase() public { - Check invariants about total balances - Check invariants about balances of specific addresses -## Workarounds +## Implementation Patterns - Use `FunctionCallInputs` to get the inputs of the function call and retrieve the modified keys. -- Use `getLogs` to get the logs of the transaction and retrieve the modified keys. \ No newline at end of file +- Use `getLogs` to get the logs of the transaction and retrieve the modified keys. diff --git a/docs.json b/docs.json index e5849a2..2aeda9f 100644 --- a/docs.json +++ b/docs.json @@ -58,6 +58,7 @@ "group": "Test and Operate", "pages": [ "credible/testing-assertions", + "credible/testing-strategy", "credible/fuzz-testing", "credible/backtesting", "credible/ci-cd-integration", @@ -110,7 +111,6 @@ "credible/development-effort", "credible/cheatcodes-overview", "credible/triggers", - "credible/testing-strategy", "credible/execution-model" ] } @@ -155,7 +155,7 @@ "credible/use-case-mappings/state-changes", "credible/use-case-mappings/call-frame-context", { - "group": "Unsupported", + "group": "Alternative Patterns", "pages": [ "credible/use-case-mappings/unsupported-use-cases/modified-keys" ] diff --git a/images/create_project_dapp.webp b/images/create_project_dapp.webp index eab0e2a..5e655a3 100644 Binary files a/images/create_project_dapp.webp and b/images/create_project_dapp.webp differ diff --git a/images/explorer_screenshot_dapp.png b/images/explorer_screenshot_dapp.png index 90c1bb3..096e60f 100644 Binary files a/images/explorer_screenshot_dapp.png and b/images/explorer_screenshot_dapp.png differ diff --git a/images/landing_view_transparency.png b/images/landing_view_transparency.png deleted file mode 100644 index 328df80..0000000 Binary files a/images/landing_view_transparency.png and /dev/null differ diff --git a/images/project_audit_log.png b/images/project_audit_log.png new file mode 100644 index 0000000..d1f59bc Binary files /dev/null and b/images/project_audit_log.png differ diff --git a/images/project_dashboard_with_incident.png b/images/project_dashboard_with_incident.png index ed51680..afa7ce2 100644 Binary files a/images/project_dashboard_with_incident.png and b/images/project_dashboard_with_incident.png differ diff --git a/images/project_settings.png b/images/project_settings.png index 29163b5..7097c36 100644 Binary files a/images/project_settings.png and b/images/project_settings.png differ diff --git a/package.json b/package.json index 4ee34b4..445266d 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "packageManager": "pnpm@10.9.0", + "packageManager": "pnpm@10.33.4", "engines": { "node": "24.x" }, diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml new file mode 100644 index 0000000..3910192 --- /dev/null +++ b/pnpm-workspace.yaml @@ -0,0 +1,18 @@ +# Require newly resolved package versions to be at least 10 days old. +# pnpm expects this value in minutes: 10 days * 24 hours * 60 minutes. +minimumReleaseAge: 14400 + +# Keep installs on the package manager version that supports these protections. +packageManagerStrictVersion: true + +# Do not let transitive dependencies resolve through git URLs or tarballs. +# This blocks the GitHub optional-dependency route used in the reported attack. +blockExoticSubdeps: true + +# Dependency install scripts must be reviewed explicitly. Mintlify currently +# needs sharp's install check; Puppeteer's browser download is not needed here. +strictDepBuilds: true +dangerouslyAllowAllBuilds: false +allowBuilds: + sharp: true + puppeteer: false