samvallad33/protocolgate

# ProtocolGate ProtocolGate is a deployment-topology policy gate for Web3 control-plane security: a declarative manifest plus reusable controls for smart-contract deployment topology. It treats smart-contract deployment topology like infrastructure. Before a deploy run, ProtocolGate checks the declared control plane: proxy admins, multisig thresholds, timelock delays, treasury splits, oracle assumptions, bridge limits, emergency powers, and upgrade safety. ## Why This Exists Static analyzers catch source-level bugs. Audit reports catch bespoke failure modes. Tools such as Safe, OpenZeppelin Defender, and Tenderly help teams approve, execute, simulate, and monitor protocol operations. ProtocolGate focuses on a narrower layer: the control-plane assumptions around deployment and privileged operations. Those assumptions often still live in spreadsheets, audit notes, deployment scripts, or informal checklists. ProtocolGate turns recurring audit findings into reusable policy controls: - Upgradeable contracts cannot ship with EOA admins. - Redemption flows must have cooldown, circuit breaker, and pause controls. - Token, oracle, and accounting decimals must match at integration boundaries. - Bridge contracts must declare rate limits. - Observed chain-state snapshots can be compared against the declared manifest for drift. - Privileged proposal intent can be checked before signing: signer-readable intent, expiry, calldata hash binding, selector allowlists, Safe module allowlists, simulation evidence, and monitor coverage. ## Quickstart From a checkout of this repository: uv run protocolgate validate examples/protocolgate.valid.yaml uv run protocolgate validate examples/protocolgate.proposal-intent.yaml uv run protocolgate export-input examples/protocolgate.valid.yaml The invalid manifest is expected to fail and emit machine-readable findings: uv run protocolgate validate examples/protocolgate.invalid.yaml --output json Generate an audit-reviewable control-plane report: uv run protocolgate validate examples/protocolgate.invalid.yaml --output markdown See `docs/SAMPLE_CONTROL_PLANE_REPORT.md` for an example report generated from the intentionally unsafe manifest. The drift example is also expected to fail because the live-state snapshot intentionally disagrees with the manifest: uv run protocolgate drift examples/protocolgate.valid.yaml examples/live-state.drift.json --output json Use the experimental OPA/Rego subset when `opa` is installed: uv run protocolgate validate examples/protocolgate.invalid.yaml --engine opa --policy-dir policies ## Public Case-Study Fixtures ProtocolGate now includes public repo fixtures for real protocol control-plane shapes: uv run protocolgate validate examples/public/compound-comet-usdc/protocolgate.yaml uv run protocolgate validate examples/public/lido-core-mainnet/protocolgate.yaml uv run protocolgate validate examples/public/aave-governance-v3-ethereum/protocolgate.yaml Each fixture includes `SOURCE_NOTES.md` explaining which public repo files were used and which fields are modeled ProtocolGate abstractions. These are demo and study fixtures, not live-state assertions or audits of those protocols. ## Manifest Shape `protocolgate.yaml` declares the security-relevant deployment topology: version: 1 deployment: environment: production chain_id: 1 allowed_deployers: [ProtocolMultisig] multisigs: - name: ProtocolMultisig threshold: 3 signers: ["0x...", "0x...", "0x...", "0x...", "0x..."] timelocks: - name: ProtocolTimelock delay_seconds: 172800 proposer: ProtocolMultisig executor: ProtocolMultisig governors: - name: ProtocolGovernor voting_delay_seconds: 86400 voting_period_seconds: 172800 timelock: ProtocolTimelock contracts: - name: Vault type: vault upgradeable: true proxy: admin: ProtocolTimelock See `examples/protocolgate.valid.yaml` for a complete topology. ## GitHub Actions For this repository: - uses: astral-sh/setup-uv@v5 - run: uv run pytest - run: uv run protocolgate validate protocolgate.yaml As a composite action from this repo: - uses: actions/checkout@v4 - uses: samvallad33/protocolgate/action@main with: manifest: protocolgate.yaml ## Policy Catalog The current built-in engine implements CG001-CG026 and CG032-CG038. CG027-CG031 are planned future topology and protocol-control rules. The Rego pack is an experimental subset for teams that already standardize on OPA; the built-in engine is the canonical implementation during the MVP phase and the Rego pack should not be described as full parity yet. See `policies/catalog.md`. ## Drift Detection The first drift detector accepts a JSON chain-state snapshot: uv run protocolgate drift protocolgate.yaml live-state.json A future adapter should collect this snapshot from Etherscan, Alchemy, or direct RPC: - proxy admin slots - timelock delay values - multisig thresholds and owners - guardian roles - oracle feed addresses ## Proposal Intent Gate The Proposal Intent Gate asks: When a manifest includes `proposal_intent`, the built-in engine validates: - human-readable signer intent - proposal creation time and expiry - reviewed calldata hash versus execution calldata hash - privileged selector allowlists - Safe/Squads module allowlists - transaction simulation evidence - monitor coverage for high-risk admin changes Run the focused example: uv run protocolgate validate examples/protocolgate.proposal-intent.yaml See `docs/PROPOSAL_INTENT_GATE.md` for the implementation guide and demo script. ## Positioning ProtocolGate is not another OPA starter repo and not another smart-contract scanner. The category is Smart Contract DevSecOps, specifically Web3 control-plane security. It complements audits by checking deployment and operational assumptions that should not live only in a checklist: who can upgrade, who can pause, whether admin power is behind a multisig and timelock, whether treasury and oracle assumptions are bounded, and whether live state drifted from the manifest.