Self-Healing Smart Contracts Operational Specification

1. Executive Summary

This document resolves six open operational questions for the Self-Healing Smart Contracts (SHSC) subsystem. Together these decisions define the boundary between automated and human-governed healing, establish measurable quality targets, standardize the formal specification language, assign liability across fix types, accommodate non-standard contracts, and guarantee response times for governance escalation.

SHSC continuously monitors every enrolled contract on the JIL network. When an anomaly is detected, the system classifies it, generates a candidate fix, verifies correctness through formal methods, and either auto-applies the patch or escalates to governance - depending on the vulnerability class. This specification makes those rules concrete and auditable.

2. Auto-Approval Vulnerability Classes

Three vulnerability classes are eligible for automatic healing without a governance vote. The remaining four require explicit governance approval before any fix is applied on-chain. Classification is based on fix determinism, template success rate, and blast radius.

Eligibility Table

Eligibility Threshold

A vulnerability class qualifies for auto-approval only when its fix template achieves a sustained success rate of 95% or higher over a rolling 90-day window. The continuous-fuzzer (port 8705) monitors success rates per class in real time. If a class drops below 95%, it is automatically demoted to governance-required until the rate recovers for 30 consecutive days.

3. False Positive Rate Policy

The maximum acceptable false positive rate for SHSC anomaly detection is 0.5%, stricter than the original 1% design target. False positives erode developer trust and waste governance bandwidth. The system operates in three zones based on the rolling 30-day rate.

Zone Thresholds

Calibration Protocol

• New detection rules enter a 90-day calibration period where all findings require human confirmation before action.
• The AI security monitor (port 8515) tracks false positive rates per rule type, per contract category, and per vulnerability class.
• Rate calculation uses a rolling 30-day window with a minimum sample size of 100 detections. Below that threshold, the rule remains in calibration mode.
• Weekly calibration reports are published to the governance dashboard with per-rule breakdowns.

4. Formal Specification Language

JIL-Spec is the formal specification DSL for annotating contract invariants, preconditions, and postconditions. It compiles to multiple verification backends and serves as the single source of truth for what a contract should do - enabling the SHSC engine to distinguish bugs from intended behavior.

Annotation Primitives

Example

/// @invariant totalSupply == sum(balances)
/// @invariant forall(addr): balances[addr] >= 0

/// @precondition amount > 0 && balances[msg.sender] >= amount
/// @postcondition balances[to] == old(balances[to]) + amount
/// @postcondition balances[msg.sender] == old(balances[msg.sender]) - amount
function transfer(address to, uint256 amount) external {
    // ...
}

Compilation Targets

• Certora CVL - for deep property verification via the Certora Prover
• Scribble annotations - for runtime assertion injection and fuzzing
• Solidity NatSpec - for documentation and toolchain compatibility

The developer-annotation-sdk (port 8990) ships with 12 annotation templates covering the most common contract patterns (ERC-20, ERC-721, vault, AMM, bridge, staking, governance, timelock, oracle, proxy, multi-sig, access control) and supports 4 export formats (CVL, Scribble, NatSpec, raw JSON).

5. AI-Fix Liability Framework

Liability for SHSC-generated fixes follows a three-tier model based on how the fix was approved. The framework balances the speed benefits of auto-healing against clear accountability for each approval pathway.

Liability Assignment

Insurance and Coverage

• The $250K+ protection coverage included with Premium tier applies to all auto-approved fixes. If an auto-approved fix causes damage, the protocol covers losses up to the lesser of contract value or $250K+.
• Governance voters accept risk through their explicit vote. Liability is distributed pro-rata based on each voter's weight in the approval decision.
• An insurance reserve is funded by 0.1% of all healing-governance contract fees. This reserve backstops auto-approved fix claims and is managed by the protocol treasury.
• Emergency committee members carry personal liability only in cases of gross negligence - defined as approving a fix without reviewing the generated verification report.

6. Non-Standard Contract Handling

Not all contracts follow standard patterns. Flash loan protocols may use intentional reentrancy. Custom AMMs may have non-standard price curves. SHSC must accommodate these without generating false positives or applying incorrect fixes.

Custom Invariant Profiles

• Registration: Contract developers register custom invariant sets via the developer-annotation-sdk (port 8990). Custom profiles override the default invariant set for that specific contract.
• Pattern whitelisting: Specific patterns can be whitelisted per contract - for example, marking intentional reentrancy in flash loan callbacks as expected behavior.
• Severity overrides: Developers can reclassify severity levels for specific vulnerability types within their contract context.
• Manual-only mode: Any enrolled contract can opt out of auto-healing entirely, receiving detection alerts but requiring manual approval for all fixes.

Validator Emergency Override

When a non-standard contract's behavior causes cascading damage to other enrolled contracts, the 14-of-20 validator quorum can override custom profiles and apply standard healing rules. This is a last-resort mechanism with the following constraints:

• Requires 14-of-20 validator signatures (standard BFT quorum)
• Override is temporary - 72 hours maximum, then requires governance vote to extend
• The affected contract developer is notified immediately and can petition for reversal
• All overrides are logged on-chain with full validator attestation for auditability

Certification Requirement

Custom invariant profiles require certification before activation. The certification process includes a review of the custom invariant set against the contract source, a 30-day shadow-mode period where the custom profile runs alongside the default profile, and sign-off by at least one member of the security committee.

7. Governance Escalation SLA

When SHSC detects a vulnerability that requires governance approval, the escalation process follows strict SLA timelines. Missed SLAs trigger automatic protective actions to prevent damage accumulation while governance deliberates.

Severity-Based SLA

Auto-Pause on Critical SLA Miss

If a Critical-severity vote does not reach quorum within 4 hours, the affected contract is automatically paused. This prevents ongoing exploitation while governance catches up. The pause persists until either the vote completes or the emergency committee intervenes. Auto-pause is the single most important safety mechanism in the escalation flow - it ensures that governance delays never translate to uncapped losses.

Emergency Committee Powers

• The emergency committee (3-of-5) can extend any vote window once by 50% - for example, extending a 4-hour Critical window to 6 hours.
• Extensions require 3-of-5 committee signatures and a written justification logged on-chain.
• The committee cannot extend a window more than once. If the extended window also expires, auto-actions trigger immediately.
• Committee membership is rotated quarterly. Members are drawn from JIL Sovereign core team, independent security auditors, and validator operators.

8. Cross-Reference Matrix

The following matrix maps each operational decision to the services, ports, and contracts that implement it.

All port numbers reference DevNet/Portal services on Hetzner. Mainnet validators run the same services with identical port assignments. On-chain components are deployed to the JIL L1 chain (jil-mainnet-1).