Read this page to verify a caller against a contract that a separately compiled library
publishes in a sidecar file, Lib.leancil.contracts. It covers the extract options, the
sidecar schema, the form the caller theorem must have and what the result does and does not
establish. Publishing a sidecar is in
publishing verified contracts; generic instances
and struct references are in typed imports.
extract can bind a plain static external call to a contract slot. The implementation DLL is
read as metadata: its method bodies are not copied into the caller program, and the imported
method has no body in the unlinked program.
leancil extract App.dll 'App::Entry(ulong)' extracted scalar \
--import Lib.leancil.contracts \
--import-implementation Lib=/path/to/Lib.dll \
--import-sha256 Lib=<independently-supplied-sha256> \
--import-interface-sha256 Lib=<independently-supplied-interface-digest>
leancil check extracted
| Option | Meaning |
|---|---|
--import path |
A sidecar. Optional when Lib.leancil.contracts lies next to the application, where it is discovered. |
--import-implementation Lib=path |
The implementation DLL; an explicit path overrides discovery. The default is Lib.dll next to the sidecar, then next to the application. |
--import-sha256 Lib=hex |
The independently supplied SHA-256 of the implementation DLL. This option is required. |
--import-interface-sha256 Lib=digest |
The independently supplied interface digest. This option is required. |
A discovered sidecar is read only when a reachable call resolves to Lib, so sidecars of
uncalled libraries need no pins and never enter the extraction. A hash found in the same sidecar
cannot serve as the independent --import-sha256 input. A supplied digest establishes byte
identity; it does not establish authenticity or prove the implementation.
--import-interface-sha256 pins the canonical interface descriptor, including every Lean source
byte, and is required before the interface is staged or compiled. Obtain it through your
accepted publisher channel. Interface sources can execute Lean metaprograms and IO with verifier
permissions, and accepting their digest accepts execution of those exact sources. A digest is
neither a sandbox nor independent publisher authentication. Rechecks enforce the recorded
independent interface pin before compilation.
check reopens recorded sidecars and implementations and recomputes their hashes, metadata,
generated CIL, import slots and interface sources. After the DLL changes it reports both the
expected and actual implementation SHA-256. CLI path/hash overrides can be supplied again for
an explicit recheck. identity.json records sidecar and implementation paths relative to the
output directory, as it does assemblyPath, so a moved extraction rechecks against the moved
files.
resolve-imports turns SDK output into the explicit --import and --import-implementation
arguments of extract. It only locates files: extract never reads deps.json or NuGet assets,
and the independent pins stay required.
leancil resolve-imports bin/App.dll --library Lib \
--assets obj/project.assets.json --runtime-identifier linux-x64 \
--rid-graph "$(dotnet msbuild App.csproj -getProperty:RuntimeIdentifierGraphPath)" \
--output resolved.json
| Option | Meaning |
|---|---|
--library Lib |
A library to resolve; at least one, repeatable. List every required library, including transitive contract dependencies: sidecar dependencies are not followed. |
--deps file |
The deps file. The default is App.deps.json next to the application. |
--assets file |
The NuGet assets file, obj/project.assets.json. One of the deps and assets files is required. |
--package-root directory |
An extra package root, repeatable; the packageFolders of the assets file are used too. |
--runtime-identifier RID |
The target RID; it must not conflict with the deps file's runtime target. |
--rid-graph file |
The SDK's PortableRuntimeIdentifierGraph.json. |
--profile name or @profile.json |
The execution profile; see the architecture rule below. |
--output file |
Write the result as JSON there. The default is standard output. |
Only net10.0 targets are accepted. The command does not restore, use the network, or infer a
RID from the host.
Selection follows the .NET 8+ host and NuGet. RID fallback is NuGet's breadth-first
RuntimeGraph.ExpandRuntime over the SDK's PortableRuntimeIdentifierGraph.json. For
linux-x64 the fallback list is linux-x64, linux, unix-x64, unix, any, base; the
host's built-in list is the prefix of that list through any. A deps.json runtimes section
is never read; the host ignores it too unless UseRidGraph is set. A library's best-matching RID
group replaces its whole portable runtime group; with no match, the portable group applies. A
library with RID-specific runtime assets needs --runtime-identifier and --rid-graph.
deps.json assets are probed in the application directory as hostpolicy does: at localPath
(written for executables), else at a RID asset's relative path, else at the bare file name.
Package assets are probed at <root>/<package path>/<asset path>. Copies with different bytes
are rejected.
The RID must be x64 or arm64. A fallback that ends in another architecture is rejected.
--profile defaults to scalar, as extract does; any other profile must agree with the RID's
architecture. Compile assets never become implementations. A reference-only selection fails.
Nethermind.LeanCIL.LeanCilContractsAttribute(string digest) on the runtime or reference
assembly advertises the interface digest; declare it in the library source with assembly-only,
non-repeatable usage. The attribute locates a sidecar and pins nothing. The resolver looks for
Lib.leancil.contracts and contracts/<digest>.leancil.contracts in the application,
implementation and package directories. The located sidecar must name the library and, when
advertised, carry that digest. The output lists each import's library, asset path, matched RID,
implementation and sidecar, plus the arguments for extract.
Required fields of a sidecar:
schema,semanticsVersion,formatVersion: each is1.frameworkKey: SHA-256 of the sorted framework source manifest described below.assemblyIdentity,mvid,targetFramework,implementationSha256, andisReferenceAssembly: exact implementation metadata and bytes. Target framework is.NETCoreApp,Version=v10.0. Reference assemblies are authoring-only; caller proofs can be checked, but no successful verification report is published.interfaceModules: module names and full Lean source strings. Names are plain dotted identifiers. Framework, toolchain, generated, example and test module roots and the driver'sLeanCIL*modules are reserved. Names are compared ignoring case, since case variants collide on Windows and macOS. Duplicate modules and conflicting definitions are rejected.interfaceDigest: the canonical descriptor digest described below.exports: exact assembly-scoped method identity, Cecil full signature,parameterCount,hasThis,returnsValue,visibility,contractConstant,closureDigest,profiles, andkind(methodoroutcome).certifications: records withidentity,profile,implementationSha256,interfaceDigest,closureDigest,theorem,statement,statementDigest, andstaticIdentities. Each static entry has a decimal-stringidentity,assemblyIdentity, andfieldName. The selected record must bind the selected export, profile, DLL and interface.dependencies: an empty array in version 1.fullVerificationLocator: optional provenance metadata. This importer does not fetch or verify the named artifact.
Unknown properties, duplicate JSON properties, missing fields and invalid digest or identifier forms are rejected. Methods must be static, non-virtual, public or protected, non-P/Invoke and non-generic. Instance, constructor, function pointer and virtual call sites are rejected. Import signatures must use supported parameter and result types with matching assembly-scoped type identities. Profiles must name an exact built-in profile; custom profiles are not admitted.
For an implementation DLL, the selected export is validated with its independently pinned direct dependencies and its explicitly declared initialization assumptions. Its own reachable static identity set must match the selected certification exactly. This validation checks metadata and serialization; it does not verify the imported theorem.
An optional initializationAssumptions descriptor records each exported profile's sorted
assembly/type pairs and participates in the interface digest. Each local type must have a
static constructor in the selected implementation. These premises require the implementation
DLL; a reference-only import is rejected. Imported dependency premises must match those reached
by implementation validation exactly. The exporter kernel-checks and structurally audits
equality with the generated Extracted.initializationAssumptions list. Callers propagate this
list into their generated source, identity and report; exporting such a caller propagates it
again. The assumptions are deployment premises that initialization completed successfully. They
are not CLR initialization theorems or field-value guarantees. Recorded staticValues,
including unknown ones, are unexportable, and forced full verification rejects initialization
premises.
Each node's static identities are checked with those of its direct imports before output, and a
collision reports both scoped field names. Extraction does not compare every pair of graph
nodes: conditional transitive proofs retain the StaticWorldValid premises, and
full verification checks all descriptors of its linked program with
linkChecked, including those of dependencies linked into an imported library.
The framework manifest lists CIL.lean, all CIL/**/*.lean, and lean-toolchain
in ordinal relative-path order. Paths use /. Each line is path=sha256(bytes).
Join lines with \n and no final newline, then hash the UTF-8 bytes. The CLI
uses the framework sources packaged with the executable. It does not read them from the current
working directory. The framework key identifies the framework sources. It is not a semantic
preservation theorem.
The canonical interface descriptor serializes these fields in this order:
schema, semanticsVersion, formatVersion, frameworkKey, assemblyIdentity,
targetFramework, interfaceModules, exports, dependencies. Use compact
System.Text.Json serialization with the declared record field order, camel-case
property names, and its default string escaping. Arrays retain their order.
Every interface module source and every qualified contract name is included in this digest.
The descriptor excludes MVID, implementation SHA-256, certification records and
full-verification locator, so a rebuild can retain its interface digest when its
source interface and assembly identity do not change.
closureDigest is recomputed from the canonical exported contract closure and
must equal the selected certification record. The closure includes definition values,
theorem/inductive types, constructor metadata and recursor computation rules.
A certification record does not supply a Lean implementation proof. Its theorem,
statement and statement digest are publisher provenance accepted by
the consumer, and are reported as such. No pinned digest covers them: the
interface digest excludes certifications. statementDigest hashes the UTF-8 statement that
the theorem audit returned, and hashing the reported statement cannot
authenticate a publisher's theorem. Reports therefore set certificationAuthenticated to false
and record the sidecarSha256 the text came from.
Import slot j is Extracted.program.length + j. Extracted.lean contains its
full method identity, shape and closure digest. The kernel-checked
ManagedCallsValid certificate binds each live raw external call to that slot.
It checks call opcode, identity, type arguments, argument count, receiver and
return arity. The implementation hash is absent from Extracted.lean.
ExtractedImports.lean imports the declared interface sources and defines:
def Extracted.ImportsHold (linked : _root_.CIL.Program) : Prop :=
@_root_.CIL.Safety.MethodContract.Holds _ _ _root_.Library.Contract linked <absolute-slot>
Several slots form a conjunction. The selected kind uses the fully qualified
framework MethodContract.Holds or OutcomeContract.Holds predicate. Both the
framework predicate and selected contract use _root_ qualification, so an
Extracted namespace declaration cannot replace either one. Lean checks
that the named value has that framework contract type. The audit compares
the head constant of that type, so a contract typed through an abbrev of
MethodContract or OutcomeContract is rejected; declare it with the framework
structure directly. A user-defined
Contract.Holds predicate cannot replace this check. Each contract applies to
the linked program and its absolute slot. No body, axiom, summary or
implementation proof is generated for an import.
The caller theorem must have the conditional form:
CIL.Safety.HoldsGiven Extracted.program Extracted.ImportsHold claim
This form retains both Links and the required imported contracts. The theorem audit
(leancil-audit, on replayed oleans) compares the compiled theorem type with this
application structurally, so no binder may precede it, and requires the compiled
value of Extracted.ImportsHold to equal the conjunction rebuilt from
identity.json: each slot's root contract at the canonical Nat numeral. An
interface OfNat instance, notation or elaborator therefore cannot retarget a
slot. This shape check does not establish that an arbitrary claim is useful.
The caller proof supplies the intended claim. A concrete linked implementation
must separately discharge the import contracts before this conditional result
can establish an unconditional application guarantee.
The verifier stages the exact interface sources, includes them in proof cache
identities, compiles them, and performs kernel replay. leancil-audit then
validates the interface declarations and computes each canonical closure from the
replayed oleans, without running interface code; no compiler output is read, so
an interface macro or elaborator cannot forge a closure. The compiled interface
artifacts are hashed before replay and must keep those hashes after the audit
and before each later step. Consumer workspaces also
reject source-name collisions and include their hashes in snapshot checks.
Schema-4 reports list imports accepted via published-certification, as well
as contractImports; CLI output states the conditional assumptions and deployment
obligations.
Hashes and certification records never discharge those assumptions.
identity.json schema 3 records each slot's identity, implementation path/hash,
kind, sidecar path/hash, interface digest, contract constant and closure digest.
It also hashes each generated interface source. The final extraction recheck
runs before a successful report is published. A manifest of another schema is
rejected; run leancil extract again.
Transitive contract imports states how to supply and pin a dependency graph. The graph rejects cycles before method validation. Each library implementation is checked against its declared direct dependencies with separate call slots, and validation compares its actual static identity set with its certification record. A supplied library does not authorize an undeclared dependency.