# caller-supplied-ledger-equality

> An unchanged caller input must equal preexisting public ledger bytes before a state-changing effect.

Canonical: https://nightshade.dicksonwu.xyz/rules/caller-supplied-ledger-equality.html
Release: Nightshade 0.1.1 (v0.1.1)

| Field | Value |
| --- | --- |
| Rule ID | `caller-supplied-ledger-equality` |
| Severity | medium |
| Confidence | medium |
| Maturity | experimental |
| Selection | Opt-in |
| Policy intent | not required |
| Default enabled | no |
| Category | Other active opt-ins / State and collections |
| Engine facts used | all-successful-predicates, private-provenance, exact-effect-histories |
| Release | v0.1.1 |

## Selection and scope

Not selected by default. Select it with `--detectors` or the `detectors` list in nightshade.json. Either one replaces profile selection, so list every rule you want.

```sh
./.nightshade/node_modules/.bin/nightshade ./contracts --detectors caller-supplied-ledger-equality
./.nightshade/node_modules/.bin/nightshade detector show caller-supplied-ledger-equality
```

The first command runs only this rule; `--detectors` takes a comma-separated list. The second prints the rule's metadata from your installed version.

Severity is review priority. It does not express exploitability or impact. Confidence is detector metadata, not a probability. All built-in rules are experimental.

Compiler scope: the engine supports the pinned profiles 0.28.0, 0.29.0, 0.30.0, 0.31.1, 0.33.0-rc.2, 0.34.0, 0.35.0-rc.1 and 0.35.0, with ZKIR2 by default. Support for this rule can be narrower; the rule documentation below states any narrower scope.

## Corpus checks

Synthetic corpus checks for this rule in the 0.1.1 proof run. A check counts only with compiler acceptance and complete analysis.

| Positive detected | Corrected quiet | Lookalike quiet | Other negative quiet | Incomplete |
| ---: | ---: | ---: | ---: | ---: |
| 1/1 | 1/1 | 1/1 | 0/0 | 0 |

No deviations were recorded for this rule.

These are behavior checks on synthetic fixtures, not a precision or recall estimate. See [evaluation](https://nightshade.dicksonwu.xyz/evaluation.md#synthetic-corpus).

## Rule documentation

From https://github.com/DicksonWu654/nightshade/blob/v0.1.1/docs/detectors/caller-supplied-ledger-equality.md at v0.1.1.

Availability: **opt-in review**, no policy required. Severity/confidence:
**medium/high**. Select with `--detectors caller-supplied-ledger-equality`.

An unchanged caller-supplied `Bytes<32>` leaf must equal definite preexisting public
ledger bytes before every modeled successful reach of an affected write or Kernel
effect. The finding groups one guard site per entry and lists the actual effects,
invocations and immutable ledger identities. Neither `disclose` nor this equality
establishes secret possession. The input may remain private to the caller.

```compact
import CompactStandardLibrary;
export ledger admin: Bytes<32>;
export ledger paused: Boolean;
export circuit pause(caller: Bytes<32>): [] {
  assert(disclose(caller) == admin, "claimed admin");
  paused = true;
}
```

If this argument represents caller authority, separately enforce the protocol's
reviewed signature or secret-possession relationship, bound to the intended key,
message and replay domain. A supported enforced private-preimage check against
preexisting ledger data on every reaching history suppresses this review; that
check still relies on secrecy and adequate entropy. Additional arbitrary checks
remain visible in the histories and prevent any sole-authorization inference.
Later publication is a separate disclosure-analysis obligation; a suppressed
review does not establish that a preimage remains secret throughout a protocol.

Known review noise includes routing, public record consistency and mock identity
checks. These legitimate patterns make the rule opt-in. A source-correct match
is not a confirmed authentication defect, a concrete path or a deployed bypass.

Constructor setup, optional/discarded/negative/after-effect comparisons, transformed
inputs and self-written ledger echoes do not meet this contract. Old snapshots
retain their initial revision. Scalars other than `Bytes<32>`, dynamic membership,
general multi-secret/signature proofs and cross-entry protocol intent remain outside.

The isolated exact pass observes all successful predicates, disables compressed
fold/hash histories and retains the ordinary 40,000-step/256-path/50,000-value
limits. It never reuses witness-only source-query certificates to prove this new
obligation. Baseline-incomplete entries, wildcard selectors, missing predicate or
invocation identities and exhausted evidence produce rule/entry-scoped incomplete
diagnostics, separately from baseline completion. Consumer work is bounded to
200,000 applicability/decomposition/intersection checks.

Constant-refined root inputs retain their unchanged identity. Conversely, a
potential alternate preimage check with reconstructed/transformed equality
dependencies cannot establish private status: bytewise equality may expose a
whole preimage without equating its original scalar identity. Such entries are
explicitly rule-incomplete; this consumer does not prove reconstruction secrecy.

## Suppress a match

If a match is intentional, suppress it on the line before with the exact rule ID and a reason of at least eight characters:

```compact
// nightshade-disable-next-line caller-supplied-ledger-equality -- Reason this match is intentional
```

Diagnostics cannot be suppressed, and an unmatched directive for a selected rule makes analysis incomplete. See [configuration](https://nightshade.dicksonwu.xyz/configuration.md#suppress-an-intentional-match) for fingerprint suppressions and baselines.

## References

- [Rule source document at v0.1.1](https://github.com/DicksonWu654/nightshade/blob/v0.1.1/docs/detectors/caller-supplied-ledger-equality.md)
- [Catalog entry in rules.json](https://nightshade.dicksonwu.xyz/rules.json)
- [All rules](https://nightshade.dicksonwu.xyz/rules.md#state-and-collections)
- [Limitations](https://nightshade.dicksonwu.xyz/limitations.md)