Migrating from V0.8 to V0.9

What changes for existing contracts

Nothing breaks. V0.9 is fully backward-compatible at the source level. Every V0.8 .cov file compiles unchanged and produces equivalent bytecode under --target-chain mockchain. No deprecations, no warnings, no required edits.

If your CI does cargo install covenant-cli --version 0.8.x today, swap that to 0.9.0 and your build is green.

What’s new that you should adopt

1. Target-chain compilation is explicit

V0.8 compiled for MockChain by default and used legacy precompile addresses on Sepolia (which broke for ceremony, FHE, PQ, ZK — that’s KSR-CVN-005, the V0.8 mitigated finding).

V0.9 introduces explicit --target-chain and routes cryptographic operations to per-chain helper contracts:

covenant build --target-chain sepolia    # helper addresses embedded
covenant build --target-chain mockchain  # legacy 0x101+ precompiles
covenant build --target-chain aster      # Aster Chain SDK lowering (deploy gated on factory verification)

If your V0.8 contracts target Sepolia and use ceremony / FHE / PQ / ZK primitives, rebuild with --target-chain sepolia to pick up the helper bridge. The bytecode embeds CREATE2-deterministic helper addresses; no source change required.

2. Ceremony actually works on Sepolia now

V0.8: ceremony lifecycle compiled but reverted on Sepolia at the precompile call site (no executor at 0x124–0x127).

V0.9: ceremony lifecycle (setup → submit_share → finalize → destroy) executes end-to-end via CeremonyHelper. M1 milestone — the first ceremony destruction on Sepolia — is verifiable on Etherscan.

If you had a ceremony deployed on V0.8 Sepolia, redeploy with V0.9 + --target-chain sepolia to use the live helper.

3. Three new top-level constructs

nft CoolApes {
    name: "Cool Apes"
    symbol: "APE"
    base_uri: "https://api.example.com/"
}

registry KeyRegistry { }

interface IERC20 {
    action transfer(to: address, value: amount) returns bool
    view balance_of(who: address) returns amount
}
  • nft → ERC-721 auto-synthesis (11 functions from 5 lines)
  • registry → ERC-8231 auto-synthesis (5 functions from 1 line)
  • interface → typed cross-contract calls

See 16-nft, 17-registry, 18-external-call for end-to-end examples.

4. Foundry-class CLI

V0.9 ships seven new subcommands:

covenant test                      # run .test.cov files (per-test isolation)
covenant test --watch              # re-run on file changes
covenant test --coverage           # name-heuristic coverage reporting
covenant fmt                       # canonical formatting
covenant fmt --check               # CI format gate
covenant lint src/                 # 6 rules for Solidity-isms
covenant doctor                    # 9 environment probes
covenant init my-token             # scaffold from template
covenant explain E0421             # long-form error explanation

The legacy covenant compile / check / deploy commands keep working unchanged.

5. The linter catches Solidity-isms automatically

V0.9 adds a 6-rule linter (codes L001–L006) that flags common Solidity patterns when you paste code into a .cov file:

  • mapping(address => uint) → map<address, amount>
  • function foo() public → action foo()
  • // comment → -- comment
  • require(cond, "msg") → given cond or revert_with "msg"
  • pragma solidity → drop the line
  • import "..." → drop or replace with Covenant constructs

One-click fix in Monaco (playground) and VSCode. Configure via .covenantlint.json to disable rules per-project.

6. LSP additions

  • goto_definition — jump to declaration of fields, actions, types, interfaces
  • find_definition_at(position) — used by VSCode “Go to Definition”
  • Same hover, symbols, diagnostics as V0.8

What stays the same

  • Language spec (no breaking source changes)
  • All V0.8 type system rules
  • All V0.8 ERCs (8227, 8228, 8229, 8231) — same surfaces, now with reference impl via helper bridge
  • OMEGA V4 audit findings (still resolved)
  • Three target backends: EVM, Aster, WASM
  • 22-crate workspace structure
  1. Bump the compiler: cargo install covenant-cli --version 0.9.0
  2. Rebuild with explicit target: add --target-chain flags to your covenant build invocations.
  3. Run the linter once: covenant lint src/ to surface any Solidity-isms in old code.
  4. Run the doctor: covenant doctor validates your environment.
  5. (Optional) Adopt new constructs (nft, registry, interface) where they replace hand-rolled equivalents.
  6. (Optional) Migrate test scaffolding to covenant test for per-test isolation.

Known limitations in V0.9.0

  • FHE / PQ / ZK helpers are mocked. The interfaces are correct (Sprint 32 audited), the cryptographic logic is simplified for V0.9.0. Real Zama TFHE, Dilithium-5 verifier, and Halo2 land in V1.0 alongside the external audit and mainnet deployment.
  • Aster M2 deferred. Codegen is ready in V0.9. Live deploy is gated on Aster Chain factory verification.
  • NFT tokenURI(id) returns base_uri verbatim. ID-concatenation lands in V0.9.x with text-interpolation primitives.
  • safeTransferFrom (with the receiver hook) is V0.9.x — name reserved in synthesizer, not yet emitted.
  • update_key(new_pk, sig) for registry is V0.9.x — depends on pq_signed integration with stdlib synthesis.

Audit posture

V0.9 is testnet-only by design. OMEGA V5 (internal) cleared all 10 verifications. External audit by a third-party firm (Trail of Bits, OpenZeppelin, or equivalent) is the gate for V1.0 mainnet. See SECURITY.md for the disclosure policy.

Next