> For the complete documentation index, see [llms.txt](https://whitepaper.litho.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.litho.ai/docs/phases/phase-7-completion.md). # Phase 7 — Contract Tooling & Safety Rails > **Status:** **100%** (2026-05-12). Full CI matrix (compile/test/lint/ slither/gas/abi/coverage) plus Foundry fuzz, ABI drift gate, Slither production blocking, deployment manifest + bytecode verifier, and the multi-sig + Ledger deployment runbook. > > First written at \~55% on 2026-05-11. See [§ Updates](#updates-since-first-writing-2026-05-11) below for what shipped after. ## Updates since first writing (2026-05-11) Six significant additions between this doc's first writing and the 2026-05-12 ceiling close: ### ABI sync gate (2026-05-11) `Makalu/contracts/scripts/sync-abis.mjs` extracts `.abi` from the Hardhat artifacts into `Makalu/packages/blockchain-core/src/abis/`. The new `abi-sync-check` job in `ci-contracts.yaml` runs the script and fails CI on `git diff --exit-code` against the vendored copies. Source of truth is the Solidity compile; SDK ships a verified-in-sync snapshot. Closes the "deferred ABI → SDK auto-publish" item from the original write-up — via a drift gate, which is structurally simpler than a publish pipeline. ### Slither runs against production contracts (2026-05-12) The original Slither job analyzed `Makalu/templates/contracts-template/` only. New `slither-production` job in `ci-contracts.yaml` covers `Makalu/contracts/` (the real LEP100 / WLITHO / LITHONative). `Makalu/contracts/.slither.config.json` carries `fail_on: high`. After the first-scan baseline came back clean, the job was flipped from advisory to blocking. Net posture: Solidity static analysis is now a hard gate for the contracts the network actually runs. ### Foundry fuzz tests for production LEP100 (2026-05-12) `Makalu/contracts/test/foundry/Lep100.t.sol` — 14 property-based tests across 5 invariants: * Mint properties (balance + supply, zero-address reject) * Transfer conservation (balance, insufficient-balance revert, no-approval revert) * Burn correctness (balance + supply both reduced, insufficient burn revert) * Pause semantics (mint/transfer/burn all blocked under pause, unpause restores) * Access control (non-MINTER mint reject, non-PAUSER pause reject) `Makalu/contracts/foundry.toml` has a `[profile.ci]` with 10,000 fuzz runs per property (140k randomized assertions total per CI run; all pass). Production LEP100 invariants are now property-tested to a level the Hardhat/Mocha suite can't express. ### Structured deployment manifest (2026-05-12) `scripts/deploy.ts` rewritten to emit `deployments/.json`: ```json { "chainId": 700777, "network": "makalu", "deployer": "0x...", "commit": "", "deployedAt": "ISO timestamp", "contracts": [ { "name": "LITHONative", "address": "0x...", "txHash": "0x...", "blockNumber": 12345 } ] } ``` Downstream consumers (SDK NETWORKS table, verifier, validator-team runbooks) parse the JSON rather than grepping deploy logs. Local hardhat manifests (`31337.json`, `1337.json`) ignored; production chainIds checked in. ### On-chain bytecode verifier (2026-05-12) `scripts/verify-deployment.ts` reads the manifest, queries `eth_getCode` for each address, compares to the compiled artifact's `deployedBytecode`. Exit 0 on match; exit 1 on any divergence. Catches: * Manifest typos * Source drift since deploy (`.sol` edited but not redeployed) * Silent bytecode changes (selfdestruct, proxy upgrade) ### Multi-sig + Ledger deployment runbook (2026-05-12) `docs/governance/contract-deployment.md` — three-tier runbook: 1. EOA deploys (local / staging only) 2. Multi-sig via Safe (mandatory for production) 3. Ledger-signed multi-sig (mandatory for mainnet) All three share the same pre-flight (CI green, Slither production blocking, Foundry fuzz coverage) and post-deploy verification (bytecode verifier must exit 0). Safe-app + Ledger UI bits stay operator work; Dev Infra owns the runbook + scripts. Closes the "deployment framework hardening" item from the original write-up. ### Coverage advisory → still advisory (no change) The `coverage` job stays `continue-on-error: true` until a baseline threshold is established. Flagging it explicitly because that's the one item the original deferred-work list called out that has NOT moved. The point-in-time content below describes the 2026-05-11 snapshot. *** ## What this phase covers The phase scope: take the Solidity contracts (`Makalu/contracts/`) from "compiles on a laptop" to "every change is auto-analyzed, gas-budgeted, and ABI-published in CI." The companion contracts package (`Makalu/contracts-template/`) is the scaffold consumed by `create-litho-app`. Coming into this phase: `pnpm hardhat compile` worked locally and that was about it. Leaving it: every push that touches `Makalu/contracts/**` triggers compile + test + lint + slither + gas + ABI export + coverage in parallel. ## What we built ### `ci-contracts.yaml` — five-job parallel pipeline The workflow at `.github/workflows/ci-contracts.yaml` runs the following jobs on every push affecting `Makalu/contracts/**`: | Job | What it does | Failure mode | | ------------------ | --------------------------------------------------------------------------------------------------- | --------------------- | | `compile-and-test` | `pnpm hardhat compile && pnpm hardhat test` | Hard fail | | `lint` | `solhint` + `prettier --check` over `src/` | Hard fail | | `gas-report` | Tests with `REPORT_GAS=true`, uploads `gas-report.txt` as 30-day artifact | Hard fail | | `slither` | Slither static analysis emitting SARIF, uploaded to GitHub Security tab | Advisory (SARIF only) | | `abi-export` | Extracts compiled ABIs from `artifacts/` into a flat `abis/` artifact (30-day retention) | Hard fail | | `coverage` | `hardhat coverage` — % summary to `$GITHUB_STEP_SUMMARY`, HTML + `coverage.json` as 30-day artifact | Advisory | The `coverage` job landed in commit `412a114` (2026-05-11) — completes the "contract tooling" matrix listed in the phase plan. ### Slither SARIF in the Security tab Slither output is uploaded via `github/codeql-action/upload-sarif`. Findings show up under **Security → Code scanning** with categorisation by detector (reentrancy, uninitialized-state, etc.). Currently advisory — the job uploads but doesn't fail the build — so triage happens in the Security tab rather than on every PR. ### Gas report as a CI artifact `REPORT_GAS=true pnpm hardhat test` emits a table per contract method showing gas used. The CI step uploads the file as `gas-report-.txt`; if a change unexpectedly bloats `transfer` from 51k to 78k gas, the diff is one artifact download away. ### ABI export → downstream consumers The `abi-export` job copies every compiled ABI from `Makalu/contracts/artifacts/contracts/src/*.sol/*.json` into a flat directory and uploads it as a workflow artifact. The SDK build (Phase 8) currently consumes these from a vendored copy; future work is to wire the CI artifact directly into the SDK publish pipeline. ## How to use what was built **See gas costs for a change:** ```bash # Local cd Makalu/contracts REPORT_GAS=true pnpm hardhat test # or open Actions → CI Contracts → your run → Artifacts → gas-report-* ``` **See coverage for a change:** ```bash cd Makalu/contracts pnpm hardhat coverage open coverage/index.html # or open Actions → CI Contracts → your run → Artifacts → solidity-coverage-html ``` **See slither findings:** Open [Security → Code scanning](https://github.com/KaJLabs/Lithosphere/security/code-scanning?query=tool%3ASlither) and filter by `tool:Slither`. **Get latest ABIs without rebuilding:** ```bash gh run download -n abis -D ./Makalu/contracts/abis ``` ## Why it matters * **Slither catches the cheap wins.** Reentrancy patterns, unchecked externals, unbounded loops — the bugs that have cost the industry billions. Even running it in advisory mode forces a human to look at the Security tab before merging contract changes. * **Gas snapshots prevent silent regressions.** Solidity refactors love to add a few hundred gas without anyone noticing. The artifact is small and the diff is human-readable. * **Coverage tells you what isn't tested.** Especially valuable for templates — contributors who copy `contracts-template/` get a real test suite as the starting point, and the coverage report shows them what's exercised by `forge test` versus untouched. * **ABI export decouples contract releases from SDK releases.** The SDK can bump to a new ABI artifact without recompiling Solidity locally. ## Files & commits | Path | Purpose | | -------------------------------------------------------- | ------------------------------------------------- | | `.github/workflows/ci-contracts.yaml` | The 6-job pipeline above | | `Makalu/contracts/hardhat.config.ts` | Hardhat config (compiler, networks, gas reporter) | | `Makalu/contracts/src/` | LEP100, WLITHO, LITHONative Solidity sources | | `Makalu/contracts/test/` | Hardhat/Mocha test suites | | `Makalu/contracts-template/test/foundry/LithoBase.t.sol` | Foundry test seed for the scaffold | Commit: `412a114` (solidity-coverage wired). Prior CI machinery (slither + gas + ABI export) was already in place from earlier work. ## Deferred work * **Deployment framework hardening.** Today it's `pnpm hardhat run scripts/deploy.ts`. Future: multi-sig (Safe SDK), Ledger signer support, EIP-712 typed deployment manifests. Tracked separately under deployment automation. * **ABI → SDK auto-publish.** The SDK currently vendors a snapshot of the ABIs. Wiring the `abi-export` CI artifact directly into the SDK publish step would remove the manual sync step. Small task; not yet scheduled. * **Slither as a blocking gate.** Today advisory. Promote to blocking once the existing findings are triaged and `# slither-disable-next-line` comments are added where appropriate. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://whitepaper.litho.ai/docs/phases/phase-7-completion.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.