Module cached_prover_index 

mmap-backed proving-key cache.

The cache file is a self-describing binary layout:

1. File magic + format version + ark-ff version + identifier.
2. Fixed-size ScalarHeader holding all small POD metadata (public input count, zk_rows, domain sizes + generators, endo, shift, etc.).
3. A section table pointing at variable-length POD payload sections (sid, pruned gates, column evaluation arrays, lookup arrays).

The readable side MmapProverIndex holds an Arc<ReadOnlyMmap> plus precomputed slice references into the mapping. Field-element accesses do not allocate; the OS page cache handles eviction under pressure.

Only available with the mmap_cache feature.

Structs

FeatureFlagBits

Feature-flag bits packed into ScalarHeader::feature_flags.

LookupParts 🔒

Validated, not-yet-materialised lookup sections gathered during the reader’s validation phase. The &[u8] descriptors borrow the mmap; the owned runtime-table data is parsed eagerly (it is not mmap-backed). All of this is turned into a LookupConstraintSystem in the infallible materialisation phase so no mmap-backed Vec is built before validation completes. _desc fields are (bytes, element_count).

LookupSelectorBits

Bits indicating which optional LookupConstraintSystem sections are stored, packed into ScalarHeader::lookup_selectors_present.

MmapProverIndex

A ProverIndex whose large Vec<F> fields are backed by memory in a live mmap(2) region instead of owned heap allocations.

OptionalSelectorBits

Bits indicating which optional column-evaluation selectors are stored.

Preamble

Parsed preamble data, returned to the reader along with the tail slice.

PrunedGate

A gate record stripped down to the fields the prover reads at prove time: type tag and wire targets. Coefficients are deliberately omitted because they are folded into ColumnEvaluations::coefficients8 at key generation time.

PrunedWire

On-disk form of crate::circuits::wires::Wire: 4-byte row, 4-byte col.

ReadOnlyMmap 🔒

Minimal read-only MAP_SHARED mmap wrapper built on libc. Keeps the feature flag self-contained (no external memmap2 crate required in the kimchi-stubs vendored registry) and matches the subset of behavior we need: open file, map read-only, munmap on drop.

ScalarHeader

Fixed-size header holding all scalar-valued metadata.

SectionEntry

One entry in the section table.

WriteContext 🔒

Context tracked during a cache-write to record sections in parallel with the growing payload buffer.

Enums

CacheError

Errors surfaced by the cache read/write paths.

SectionTag

Tags identifying the different payload sections in the section table. Tag values are stable across format versions within the same major version and must never be reused for a different meaning.

Constants

ARK_FF_VERSION

The ark-ff version string recorded in cache files produced by this binary. Read back at open time and compared to the reader’s version; mismatched readers reject the file rather than silently corrupting.

ARK_FF_VERSION_MAX_LEN

Maximum length of the ark-ff version string recorded in the header.

FIELD_ELEMENT_BYTES

Size of one field element on disk: four little-endian u64 limbs of Montgomery representation.

FILE_MAGIC

Magic bytes at file offset 0. Distinct from any existing cache format in the Mina stack so a wrong file is rejected immediately.

FORMAT_VERSION

Current on-disk layout version. Bump on any incompatible change.

IDENTIFIER_MAX_LEN

Maximum length (in bytes) of the caller-supplied identifier stored in the file header. Sized to comfortably accommodate sha512 hex (128 bytes) plus a caller prefix. Stored length-prefixed inside a fixed-size field so the header layout is constant regardless of identifier length.

PREAMBLE_SIZE

Byte offset (from file start) of the num_sections u32 in the fixed preamble. Callers outside this module shouldn’t need this, but tests sometimes do.

PRUNED_GATE_SIZE

Byte size of one pruned gate record on disk. Must match write_pruned_gate exactly.

SECTION_ALIGNMENT

Alignment (in bytes) applied to every payload section. BigInt<4> (four u64 limbs) only needs 8-byte alignment for zero-copy &[F] casts via from_raw_parts; 32 is a conservative choice that comfortably covers it and matches the field element’s on-disk size.

SECTION_TABLE_OFFSET

Total file offset at which the section table begins (immediately after the ScalarHeader).

Functions

align_up

Rounds n up to the nearest multiple of SECTION_ALIGNMENT.

alignment_padding

Padding required after a byte-run of length n to reach section alignment.

coefficient_tag

Returns the section tag for the i-th coefficient column (0..COLUMNS).

field_to_limbs

Returns the four LE u64 Montgomery-form limbs underlying f.

fixed_region_size 🔒

Computes the total bytes consumed by the fixed preamble + ScalarHeader

gate_type_from_tag 🔒

gate_type_to_tag 🔒

limbs_to_field

Reconstructs a field element from its four LE u64 Montgomery-form limbs. Inverse of field_to_limbs; see that function’s docstring for the layout assumptions.

mmap_field_vec_unchecked 🔒 ^⚠

Zero-copy: constructs a Vec<F> whose backing storage is the mmap region itself, via Vec::from_raw_parts(mmap_ptr, len, len).

pack_feature_flags 🔒

pad_string 🔒

Encodes s into a fixed-size zero-padded field. Errors if s is longer than max.

permutation_coefficient_tag

Returns the section tag for the i-th permutation coefficient column (0..=6).

read_cache

Reads a cache file produced by write_cache and returns an MmapProverIndex: a ProverIndex-compatible wrapper whose bulk Vec<F> fields are backed by the mmap’d file rather than heap copies.

read_exact 🔒

read_preamble 🔒

read_pruned_gate 🔒

read_u32_le 🔒

read_u64_le 🔒

unpack_feature_flags 🔒

unpad_string 🔒

Reads a zero-terminated UTF-8 string from a fixed-size field.

validate_field_section 🔒

Validates that bytes holds exactly count field elements, i.e. that bytes.len() == count * FIELD_ELEMENT_BYTES. Purely a check — constructs nothing — so it is safe to call in the reader’s fallible validation phase before any mmap-backed Vec exists. tag is only used for the error.

write_cache

Writes a proving index to path in the mmap cache format.

write_field_slice 🔒

Serializes a slice of field elements as contiguous little-endian u64 limbs. Output length is elements.len() * FIELD_ELEMENT_BYTES.

write_preamble 🔒

write_pruned_gate 🔒

write_u32_le 🔒

write_u64_le 🔒