MidnightLedger
A typed, eagerly-evaluated snapshot of a deployed contract's ledger.
Obtained via MidnightContract.ledger. Each top-level Compact ledger field is decoded ONCE at construction (a single QuickJs round-trip through the contract's ledger() getter object — see LedgerEvaluator for the runtime flow) and stored in fields keyed by the field's .compact name.
Why typed accessors instead of a generic get(name): Any?. The runtime returns each type as a specific Kotlin shape — BigInteger for any Uint, Boolean, ByteArray, List<BigInteger> for Vector<N, Uint<8>>, etc. Callers shouldn't have to know that; the typed accessors enforce the expected shape AND validate range (e.g. Uint<8> must be 0..255). If the chain returns something incompatible with the requested type — schema drift, version mismatch — we throw WrongLedgerFieldTypeException loudly rather than silently truncating.
Missing-field semantics. A typo or version-mismatch field name throws MissingLedgerFieldException. For forward-compatible feature detection, every typed accessor has a *OrNull sibling.
Zero-value semantics. A field whose value is the type's zero (Uint=0, Boolean=false, Bytes=zeros) is still present — the contract's getter returned the decoded zero. *OrNull returns null ONLY for missing field names, not for zero values.
Functions
All ledger field names exposed by the contract.
Read a Boolean field. Accepts a native JS boolean or a BigInteger of value 0/1 (the JS marshaller in LedgerEvaluator normalizes integer Numbers to bigint envelopes, and some Compact runtime paths return 0/1 for Boolean cells). Any other value throws WrongLedgerFieldTypeException.
Read a Bytes
Read a Maybe<Opaque<String>> field as nullable String:
Same as getRaw but returns null when name is not in the schema instead of throwing. NOTE: a field that exists in the schema with a literal null value is indistinguishable from a missing field through this accessor — the underlying Map collapses both cases. Prefer the typed *OrNull accessors (getUint8OrNull, etc.) when this distinction matters; those use name in fields and unambiguously mean "absent."
Read any Uint up to 64 bits as Long. Includes Counter (which is internally Uint<64>). Throws if the chain value exceeds Long.MAX_VALUE — at that point the caller should use getUintBig for full-range access.
Read a Uint<8> field as Int. Value must fit in 0..255. Compact's runtime decodes any Uint as BigInteger; we narrow here with an explicit range check so callers don't get silent truncation on a schema mismatch (e.g. asked for Uint<8> but the field is actually a Uint<16>).
Read a Uint of arbitrary precision as BigInteger. Use for Uint<128>+ fields where Long would overflow. Lossless; recommended whenever the contract field width is unknown.
Read a Vector<N, Uint<8>> losslessly. Each element comes from Compact's runtime as BigInteger; we narrow to Int with a 0..255 range check per element. List length must equal expectedLength — mismatch indicates schema drift; throws.