EVM smart contracts that act as the trust authority for BlackCat installations.
The core idea:
- every BlackCat install gets its own on-chain Instance Controller contract (clone/proxy),
- the contract stores the attested integrity state (install + upgrades) and emergency controls,
- the runtime (via
blackcat-core+blackcat-config) treats the on-chain state as the source of truth and fails closed in production when trust cannot be verified.
This repository is intentionally Solidity-only. Runtime policy, config permission checks, and CLI/installer flows live in other repos.
ReleaseRegistry: global registry of “official” component releases (version → root hash + URI).InstanceFactory: creates/clonesInstanceControllerper install and runs the setup ceremony (CREATE + CREATE2).InstanceController: per-install state machine (propose → stage → activate upgrades), pause/unpause, and history events.KernelAuthority(optional): minimal EIP-712 threshold signer authority (multi-device by design without Safe dependency).ManifestStore(optional): append-only on-chain blob store for manifests (“full detail” mode availability).AuditCommitmentHub(optional): commits batched audit Merkle roots (event hub) with EIP-1271 reporter signatures.
| Document | What it covers |
|---|---|
| SPEC | On-chain structures and invariants |
| SECURITY_FLOWS | Diagram-first flows (Mermaid) |
| THREAT_MODEL | Threat model + assumptions |
| POLICY_ENFORCEMENT | Runtime PEP (“Back Controller”) design |
| AUTHORITY_MODES | Safe vs KernelAuthority vs EOA |
| OPERATIONS | Operational flows (bots, incidents, upgrades) |
| BUILD_AND_VERIFICATION | Build settings, EIP-170 size notes, metadata/verification portability |
| DRY_RUN_EDGEN | Step-by-step Edgen dry-run (no broadcast) |
| DRY_RUN_EDGEN_KERNELAUTHORITY | Same, but using KernelAuthority |
| DEPLOY_EDGEN | Edgen Chain dry-run + broadcast deployment |
| VERIFY_EDGENSCAN | Explorer verification (decode method names) |
| AUDIT_CHECKLIST | Practical pre-production checklist |
| AUDIT_REPORT | Internal audit notes + fixes |
| TEST_REPORT | What the Foundry test suite validates |
| TEST_MATRIX | External/public API → test mapping |
| AUDIT_COMMITMENTS | Optional audit Merkle root commitments |
| ROADMAP | Planned work |
Example deployment reports:
Do not embed complex multisig logic inside these contracts. Prefer external multisig wallets (e.g. Safe) and treat them as authorities:
root_authority(policy changes, signer rotation, thresholds)upgrade_authority(propose/activate upgrades)emergency_authority(pause/unpause / emergency gates)
In practice each authority can be a separate Safe with its own threshold.
root+uri(recommended baseline): store a Merkle/tree root plus a content URI (IPFS/HTTPS) for full manifests.full detail(paranoid): store more on-chain detail (chunked manifest bytes or per-file hashes). Expensive; only for high-value systems.
Dev stack: Foundry (forge).
Run via Docker (recommended for consistent solc/forge versions):
export FOUNDRY_IMAGE="${FOUNDRY_IMAGE:-ghcr.io/foundry-rs/foundry:stable}"
docker run --rm -v "$PWD":/app -w /app --entrypoint forge "$FOUNDRY_IMAGE" fmt
docker run --rm -v "$PWD":/app -w /app --entrypoint forge "$FOUNDRY_IMAGE" test --via-irScripts live in script/ and intentionally avoid external dependencies.
For a complete operator-oriented guide (including authority rotation, guard/bot helpers, and production finalization), see: OPERATIONS.
- Deploy: DeployAll.s.sol, DeployReleaseRegistry.s.sol, DeployInstanceFactory.s.sol, DeployManifestStore.s.sol
- Release publishing: PublishRelease.s.sol, PublishReleaseAuthorized.s.sol, PublishReleaseBatchAuthorized.s.sol
- Release revocation: RevokeRelease.s.sol, RevokeReleaseAuthorized.s.sol, RevokeReleaseBatchAuthorized.s.sol, RevokeByRootAuthorized.s.sol
- Instances + upgrades: CreateInstanceDeterministic.s.sol, ProposeUpgrade.s.sol, ProposeUpgradeByRelease.s.sol, ActivateUpgradeExpected.s.sol, CancelUpgradeExpected.s.sol, FinalizeProduction.s.sol
- Monitoring + incidents: CheckIn.s.sol, ReportIncident.s.sol, PauseIfStale.s.sol, PauseIfActiveRootUntrusted.s.sol
- Attestations: SetAttestation.s.sol, ClearAttestation.s.sol, SetAttestationAndLock.s.sol, LockAttestationKey.s.sol
- Manifest blobs: UploadManifestBlob.s.sol
- Audit commitments (optional): DeployAuditCommitmentHub.s.sol, PostAuditCommit.s.sol
Security status (2026-01-02): not independently audited yet. Continuous checks: Foundry tests + Slither (High/Medium=0) + rotating AI audits (daily). Internal “production candidate” target: 2026-02-01 (conditional). See: SECURITY_STATUS.