Add public integration and trust model docs#181
Merged
Conversation
czepluch
suggested changes
Jan 15, 2026
Contributor
czepluch
left a comment
czepluch
left a comment
There was a problem hiding this comment.
looks good. suggested some changes for consistency, but it's purely optics
credible/interfaces-overview.mdx
Outdated
|
|
||
| ## Guidance | ||
|
|
||
| - Keep interface changes backward compatible when possible. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Keep interface changes backward compatible when possible. | |
| - Keep interface changes backward compatible when possible |
credible/interfaces-overview.mdx
Outdated
| ## Guidance | ||
|
|
||
| - Keep interface changes backward compatible when possible. | ||
| - If a breaking change is needed, update all dependent components in the same release window. |
Contributor
There was a problem hiding this comment.
Suggested change
| - If a breaking change is needed, update all dependent components in the same release window. | |
| - If a breaking change is needed, update all dependent components in the same release window |
credible/interfaces-overview.mdx
Outdated
|
|
||
| - Keep interface changes backward compatible when possible. | ||
| - If a breaking change is needed, update all dependent components in the same release window. | ||
| - Ensure public docs reflect any new interface expectations. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Ensure public docs reflect any new interface expectations. | |
| - Ensure public docs reflect any new interface expectations |
credible/network-integration.mdx
Outdated
Comment on lines
+35
to
+39
| - **Block-building hook**: the block builder queries the Assertion Enforcer before including a | ||
| transaction. | ||
| - **Registry access**: the enforcer reads the on-chain registry to discover which assertions apply. | ||
| - **Assertion data access**: the enforcer fetches assertion bytecode from Assertion DA. | ||
| - **Operational monitoring**: incidents and status are surfaced via the Credible dApp. |
Contributor
There was a problem hiding this comment.
Suggested change
| - **Block-building hook**: the block builder queries the Assertion Enforcer before including a | |
| transaction. | |
| - **Registry access**: the enforcer reads the on-chain registry to discover which assertions apply. | |
| - **Assertion data access**: the enforcer fetches assertion bytecode from Assertion DA. | |
| - **Operational monitoring**: incidents and status are surfaced via the Credible dApp. | |
| - **Block-building hook**: the block builder queries the Assertion Enforcer before including a | |
| transaction | |
| - **Registry access**: the enforcer reads the on-chain registry to discover which assertions apply | |
| - **Assertion data access**: the enforcer fetches assertion bytecode from Assertion DA | |
| - **Operational monitoring**: incidents and status are surfaced via the Credible dApp |
credible/network-integration.mdx
Outdated
Comment on lines
+43
to
+45
| - The enforcer runs alongside the block builder and does not change consensus rules. | ||
| - Enforcement is deterministic and only depends on on-chain state and assertion code. | ||
| - Networks can stage assertion deployments before enforcing them in production. |
Contributor
There was a problem hiding this comment.
Suggested change
| - The enforcer runs alongside the block builder and does not change consensus rules. | |
| - Enforcement is deterministic and only depends on on-chain state and assertion code. | |
| - Networks can stage assertion deployments before enforcing them in production. | |
| - The enforcer runs alongside the block builder and does not change consensus rules | |
| - Enforcement is deterministic and only depends on on-chain state and assertion code | |
| - Networks can stage assertion deployments before enforcing them in production |
credible/trust-model.mdx
Outdated
Comment on lines
+10
to
+33
| - **Deterministic enforcement**: given the same on-chain state and assertion code, enforcement | ||
| results are deterministic. | ||
| - **Pre-execution protection**: transactions that violate deployed assertions are excluded from | ||
| blocks by networks running the enforcer. | ||
| - **Transparent rules**: assertions are public Solidity code and can be audited by anyone. | ||
|
|
||
| ## What We Do Not Guarantee | ||
|
|
||
| - **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. | ||
|
|
||
| ## Operational Assumptions | ||
|
|
||
| - The network runs the Assertion Enforcer during block building. | ||
| - The enforcer can access the on-chain registry and assertion bytecode. | ||
| - The network follows its normal transaction validity rules alongside enforcement. | ||
|
|
||
| ## Failure Modes (High Level) | ||
|
|
||
| - **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. |
Contributor
There was a problem hiding this comment.
Suggested change
| - **Deterministic enforcement**: given the same on-chain state and assertion code, enforcement | |
| results are deterministic. | |
| - **Pre-execution protection**: transactions that violate deployed assertions are excluded from | |
| blocks by networks running the enforcer. | |
| - **Transparent rules**: assertions are public Solidity code and can be audited by anyone. | |
| ## What We Do Not Guarantee | |
| - **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. | |
| ## Operational Assumptions | |
| - The network runs the Assertion Enforcer during block building. | |
| - The enforcer can access the on-chain registry and assertion bytecode. | |
| - The network follows its normal transaction validity rules alongside enforcement. | |
| ## Failure Modes (High Level) | |
| - **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. | |
| - **Deterministic enforcement**: given the same on-chain state and assertion code, enforcement | |
| results are deterministic | |
| - **Pre-execution protection**: transactions that violate deployed assertions are excluded from | |
| blocks by networks running the enforcer | |
| - **Transparent rules**: assertions are public Solidity code and can be audited by anyone | |
| ## What We Do Not Guarantee | |
| - **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 | |
| ## Operational Assumptions | |
| - The network runs the Assertion Enforcer during block building | |
| - The enforcer can access the on-chain registry and assertion bytecode | |
| - The network follows its normal transaction validity rules alongside enforcement | |
| ## Failure Modes (High Level) | |
| - **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 |
credible/dapp-integration.mdx
Outdated
Comment on lines
+13
to
+14
| - **CLI + dApp**: write assertions locally, store bytecode, and manage deployments in the dApp. | ||
| - **dApp-first**: use the dApp for project management, staging, and incident monitoring. |
Contributor
There was a problem hiding this comment.
Suggested change
| - **CLI + dApp**: write assertions locally, store bytecode, and manage deployments in the dApp. | |
| - **dApp-first**: use the dApp for project management, staging, and incident monitoring. | |
| - **CLI + dApp**: write assertions locally, store bytecode, and manage deployments in the dApp | |
| - **dApp-first**: use the dApp for project management, staging, and incident monitoring |
czepluch
reviewed
Jan 15, 2026
Comment on lines
+12
to
+14
| <Note> | ||
| Looking for the Besu/Linea pattern? See [Linea / Besu Integration](/credible/architecture-linea). | ||
| </Note> |
Contributor
There was a problem hiding this comment.
SHould we add a note going in the other direction too? Linking to OP from Linea. I guess it's not as important currently, so I'm fine with leaving things as is
czepluch
suggested changes
Jan 15, 2026
Comment on lines
+22
to
+47
| ```mermaid | ||
| --- | ||
| title: Linea Besu Integration (High Level) | ||
| --- | ||
| flowchart LR | ||
| subgraph BesuNode["Linea Besu Node"] | ||
| TxPool["Transaction Pool"] | ||
| Builder["Block Builder"] | ||
| Plugin["Credible Layer Plugin"] | ||
| end | ||
|
|
||
| subgraph Sidecar["Assertion Enforcer Sidecar"] | ||
| Engine["Assertion Execution Engine"] | ||
| Store["Assertion Store"] | ||
| Registry["On-Chain Registry"] | ||
| DA["Assertion DA"] | ||
| end | ||
|
|
||
| TxPool --> Builder | ||
| Builder --> Plugin | ||
| Plugin <--> Sidecar | ||
| Sidecar --> Engine | ||
| Engine --> Store | ||
| Store <---> Registry | ||
| Store <---> DA | ||
| ``` |
Contributor
There was a problem hiding this comment.
This diagram looks pretty weird if you look at it in the staged docs: https://phylaxsystems-public-docs-refresh.mintlify.app/credible/architecture-linea
Especially the arrow "<--->" from "assertion execution engine" to "assertion store".
Wasn't the old diagram better? Or is it too detailed?
Contributor
|
The Linea diagram I comment on above is still not fixed. Otherwise things look good |
czepluch
suggested changes
Jan 15, 2026
czepluch
approved these changes
Jan 15, 2026
Contributor
czepluch
left a comment
czepluch
left a comment
There was a problem hiding this comment.
looks good to me. excellent additions and clarifications.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.