diff --git a/credible/assertion-da.mdx b/credible/assertion-da.mdx index 7893b7f..5ab3d6b 100644 --- a/credible/assertion-da.mdx +++ b/credible/assertion-da.mdx @@ -59,7 +59,7 @@ pcl store MyAssertion 2. Uploads flattened source code and compiler options to Assertion DA 3. Returns the assertion ID (Keccak256 hash of the bytecode) and DA prover signature -Only authorized admins can deploy, modify, or remove assertions for their contracts. This is enforced on-chain by the Credible Layer smart contracts, which verify administrative authority (such as owner-based checks or approved allowlists) before allowing assertion management operations. Ownership verification will be expanded and improved in future versions to support additional ownership patterns and multisig integration. See [Ownership Verification](/credible/ownership-verification) for details. +Only authorized admins can deploy, modify, or remove assertions for their contracts. This is enforced on-chain by the Credible Layer smart contracts, which verify administrative authority (such as owner-based checks) before allowing assertion management operations. Ownership verification will be expanded and improved in future versions to support additional ownership patterns. See [Ownership Verification](/credible/ownership-verification) for details. ### Retrieving Assertions diff --git a/credible/credible-layer-contracts.mdx b/credible/credible-layer-contracts.mdx index 1b842aa..b0d714b 100644 --- a/credible/credible-layer-contracts.mdx +++ b/credible/credible-layer-contracts.mdx @@ -64,7 +64,8 @@ The Protocol Admin Verification interface verifies who has administrative author Admin verification is required for initial registration of an assertion adopter. The system supports multiple verification methods: - **Owner-based verification**: Checks the `owner()` function on the target contract -- **Whitelist verification**: Allows pre-approved addresses to register + +Additional verification methods may be introduced over time. See [Ownership Verification](/credible/ownership-verification) for details on how ownership is verified. diff --git a/credible/dapp-overview.mdx b/credible/dapp-overview.mdx index 4178e99..de65dd4 100644 --- a/credible/dapp-overview.mdx +++ b/credible/dapp-overview.mdx @@ -64,6 +64,9 @@ Authentication is required to create and manage projects. See the [Deploy Assert 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 4070353..e328628 100644 --- a/credible/dapp-projects.mdx +++ b/credible/dapp-projects.mdx @@ -37,9 +37,9 @@ To create a new project: -Only authorized admins can create a project for a contract. Most deployments use owner-based verification by default, but some networks can use allowlists. See [Ownership Verification](/credible/ownership-verification) for details. +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 Request process may be available. +For contracts that don't pass the default verifier, a [Manual Verification](/credible/manual-verification) process may be available. ## Managing Projects diff --git a/credible/deploy-assertions-dapp.mdx b/credible/deploy-assertions-dapp.mdx index 0458582..c4eeddd 100644 --- a/credible/deploy-assertions-dapp.mdx +++ b/credible/deploy-assertions-dapp.mdx @@ -122,7 +122,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 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/manual-verification.mdx b/credible/manual-verification.mdx new file mode 100644 index 0000000..cb99f5a --- /dev/null +++ b/credible/manual-verification.mdx @@ -0,0 +1,81 @@ +--- +title: 'Manual Verification' +description: 'How to authorize a protocol admin when contracts lack owner interfaces' +--- + +# Manual Verification + +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. + +## Definitions + +| 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. | + +## How protocol admin authority is determined + +There are two ways a protocol admin can be authorized: + +### 1) Owner interfaces (automatic) + +If the target contract exposes an `owner()` interface, the registry can verify the admin on-chain and authorize that address as the protocol admin. + +### 2) Manual verification (fallback) + +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. + +## Manual verification eligibility + +A protocol must satisfy **all** of the following criteria: + +- 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 + +Manual verification is provided at Phylax's discretion and may be declined for any reason. Approval is not guaranteed. + +## Verification methods + +**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 + + +**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 +- Consent to being recorded on a video call for posterity + +## Manual verification will not be offered if + +- 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 + +## After manual verification is approved + +- 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 + +## Opt-out / Blacklist + +**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.** + +- 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 dApp at the time of blacklisting. This escape hatch allows protocols to opt out of Phylax while preserving the option to opt back in later + +## Related docs + +- [Ownership Verification](/credible/ownership-verification) +- [Projects](/credible/dapp-projects) +- [Credible Layer Contracts](/credible/credible-layer-contracts) diff --git a/credible/ownership-verification.mdx b/credible/ownership-verification.mdx index 202760e..085254e 100644 --- a/credible/ownership-verification.mdx +++ b/credible/ownership-verification.mdx @@ -5,7 +5,7 @@ description: 'Understanding ownership verification requirements for the Credible # Ownership Verification -The Credible Layer uses admin verifier modules to determine who can deploy assertions for a contract. Most deployments use owner-based verification by default, and some networks can configure allowlist-based verification. This design will continue to expand with additional ownership patterns. +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. ## Current Implementation @@ -17,7 +17,24 @@ interface IOwnable { } ``` -When testing or developing with the Credible Layer, ensure your contracts implement this interface or that your network provides an allowlist verifier to enable project registration and assertion management. +When testing or developing with the Credible Layer, ensure your contracts implement this interface to enable project registration and assertion management. + + +Managing assertions is a sensitive role. We recommend using hardware wallets and multisig accounts for protocol admin (assertion manager) addresses. + + +## Manual Verification (Overview) + +If your contracts are immutable or don't expose an admin interface, you may be able to request manual verification. In this path, Phylax validates that the requesting team controls the protocol and then registers a protocol admin (manager) address for the specific contracts in the State Oracle registry. + +High-level requirements and signals include: +- Demonstrated control over the protocol codebase (e.g., ability to merge to the official repo and manage collaborators) +- Strong public proof that the protocol wants to use the Credible Layer and that the selected admin address reflects the organization's intent (e.g., multisig signatures or official social announcements) +- Willingness to share identity or evidence when needed + +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](/credible/manual-verification) for the full process and requirements. ## Future Development @@ -26,7 +43,6 @@ We are actively researching alternative ownership verification methods that will - Support different ownership patterns - Enable seamless ownership transfers - Maintain security requirements -- Allow for multisig integration These improvements will be implemented in future versions of the Credible Layer. diff --git a/docs.json b/docs.json index 41a1d47..2503c83 100644 --- a/docs.json +++ b/docs.json @@ -93,7 +93,8 @@ "credible/dapp-transparency-dashboard", "credible/dapp-projects", "credible/dapp-incidents", - "credible/ownership-verification" + "credible/ownership-verification", + "credible/manual-verification" ] }, {