Expand description
§Grillo verifier
Given caller-supplied pre/post snapshots, a decoded touch map, and an
instruction mutation contract from grillo_manifest, this crate checks
whether the supplied scope is consistent with the contract. It is
computationally separate from the program runtime, but it does not
authenticate bundles or discover omitted accounts.
The verdict checks one invariant within that supplied scope:
changed subset acquired subset authorized
changedcomes from pre/post account byte snapshots.acquiredcomes from the touch map the instruction emitted (its own self-report of what it mutated).authorizedcomes from the manifest’swriteRanges(grillo_manifest::RangeContract).
Acquired-but-unchanged is legal because access is not modification. It is surfaced as a note on a scoped PASS, never a violation.
The verifier re-derives changed from supplied raw bytes rather than
trusting the touch map. A changed byte omitted from that supplied map is an
UntrackedWrite; an acquisition outside the
authorized set is an
UnauthorizedAcquisition. A
partial map yields
INCONCLUSIVE. Changes in accounts
omitted from the bundle remain outside the observation boundary.
use grillo_manifest::MutationManifest;
use grillo_verifier::{verify, AccountDelta, TouchMap, TouchRecord, Verdict};
// A `pause` that may only write config byte 114 (paused).
let manifest = MutationManifest::from_json(r#"{
"name": "p", "version": "1.0.0",
"instructions": [
{ "name": "pause", "tag": 1, "strictWrites": true,
"writeRanges": [ { "accountIndex": 1, "offset": 114, "size": 1 } ],
"accounts": [ { "name": "admin" }, { "name": "config" } ] }
]
}"#).unwrap();
let pause = manifest.instruction("pause").unwrap();
let pre = vec![0u8; 200];
let mut post = pre.clone();
post[114] = 1; // set `paused`
let map = TouchMap {
overflowed: false, skipped: false,
records: vec![TouchRecord { slot: 1, offset: 114, size: 1, write: true }],
};
let verdict = verify(pause, &[AccountDelta::new(1, &pre, &post)], &map);
assert!(verdict.is_pass());Modules§
- authority
- Upgrade authority diff between two manifests (re-exported from
grillo-manifest). Upgrade authority diff between two Hopper program manifests.
Structs§
- Account
Delta - A pre/post snapshot of one account in the instruction, its bytes and, optionally, its lamport balance.
- Account
Role Contract V2 - One account role, reused by fixed and remaining-account grammar entries.
- Account
Transition V2 - Pre/post state for one unique pubkey.
- Bound
Invocation V2 - Immutable, validated binding of a concrete frame to a v0.2 contract.
- Contract
Completeness V2 - Dimensions for which the producer claims the contract is complete.
- CpiAccount
Binding V2 - Map one child position to one concrete parent position.
- CpiEnvelope
V2 - One declared child invocation shape.
- Data
Policy V2 - Byte writes permitted within data that exists after the invocation.
- Data
Range V2 - Half-open data range
[offset, offset + size)within one role. - Deployment
Identity V2 - Concrete loader/deployment identity observed for one invocation.
- Effect
Contract V2 - A complete program effect contract.
- Evidence
Completeness V2 - Dimensions claimed present in this evidence object.
- Instruction
Contract - The mutation contract for one instruction.
- Instruction
Effect Contract V2 - One fully identified instruction contract.
- Invocation
Account RefV2 - Effective account meta at one invocation position.
- Invocation
Frame V2 - Full concrete evidence for one invocation plus its ordered CPI children.
- Mutation
Manifest - A Hopper program manifest, parsed down to its mutation contract.
- Network
Identity V2 - Cluster identity for replay separation.
- Parametric
Range Contract - One invocation-parametric byte-range rule from a Hopper manifest.
- Pass
Evidence - Evidence backing a PASS.
- Pass
Evidence V2 - Evidence returned by an unauthenticated behavioral PASS.
- Range
Contract - One authorized byte-range write permission on a single account.
- Remaining
Accounts Contract V2 - Deterministic account-suffix grammar.
- Remaining
Group V2 - One fixed-width role group repeated a statically bounded number of times.
- Resolved
Account Role V2 - Concrete resolved role after expanding the remaining-account grammar.
- Resolved
Instruction Contract - A concrete instruction effect contract after all parametric rules have been bound to invocation arguments.
- Touch
Evidence V2 - Optional attributed touch carrier. The digest is committed, but this first slice does not treat it as independently authenticated.
- Touch
Map - A decoded touch map, with its honesty flags preserved.
- Touch
Record - One decoded touch record: a single
(account, offset, size, R/W)range the instruction touched. - Transaction
Identity V2 - Transaction and exact call-tree location.
- Transition
Policy V2 - All state-transition dimensions for one account role.
Enums§
- Account
State V2 - Logical loaded-state observation. Absence is explicit and is never inferred from zero lamports or System ownership.
- Address
Constraint V2 - Address identity for one role.
- Bind
Error V2 - Why an untrusted frame could not be bound to a contract.
- CpiPolicy
V2 - Complete CPI policy for an instruction.
- Decode
Error - Why a byte slice is not a valid touch-map v1 payload.
- Deployment
Binding V2 - How a portable contract binds to deployed executable code.
- Duplicate
Policy V2 - Alias policy for the complete fixed + remaining account list.
- Effect
Contract V2Error - Strict v0.2 parse/validation failure.
- Effect
Verdict V2 - Behavioral verdict. No variant claims ledger or provider authenticity.
- Evidence
Provenance V2 - Untrusted provenance label retained in evidence and verdicts.
- Executable
Policy V2 - Executable-bit transition.
- Inconclusive
Reason - Why a verdict could not be a definitive PASS or VIOLATION.
- Inconclusive
Reason V2 - Why a privately bound frame still cannot support a complete verdict.
- Invocation
Outcome V2 - Whether an invocation’s effects survived its observed execution boundary.
- Lamport
Policy V2 - Permitted balance direction.
- Length
Policy V2 - Data-length transition.
- Observation
Boundary V2 - Boundary at which pre/post state was observed.
- Owner
Policy V2 - Owner transition.
- Owner
Target V2 - Resolved owner target.
- Presence
Policy V2 - Logical account presence transition. A close tombstone can be represented as a present zeroed/System-owned post-state; it is not inferred as absent.
- Privilege
Requirement V2 - Required/forbidden/optional effective privilege.
- Resolve
Error - Why an invocation-specific effect contract could not be resolved.
- Unverified
Authenticity V2 - This pure verifier performs no signature, ledger, or replay validation.
- Verdict
- The verdict of a verification.
- Violation
- A single contract violation, with byte-precise evidence.
- Violation
V2 - One precise v0.2 transition violation.
Constants§
- EFFECT_
ABI_ V2 - Exact Effect ABI version accepted by this module.
- MAX_
TOUCH_ RECORDS - Capacity of the on-chain touch log. This caps slots, not coverage: at capacity the runtime coalesces records whose union is exactly the touched byte set (contiguous same-kind workloads stay complete and unflagged); the overflow flag means the instruction touched more than this many pairwise-unmergeable ranges and the map is genuinely partial.
- TOUCH_
MAP_ FLAG_ OVERFLOWED - Flags bit0: the on-chain touch log overflowed; the map is partial.
- TOUCH_
MAP_ FLAG_ SKIPPED - Flags bit1: the encoder skipped at least one record it could not represent (unmappable address, or offset beyond 31 bits).
- TOUCH_
MAP_ HEADER_ LEN - Fixed header length (magic, version, flags, count).
- TOUCH_
MAP_ MAGIC - Magic byte of the touch-map wire format v1 (
'z'). - TOUCH_
MAP_ RECORD_ LEN - Encoded length of one touch record.
- TOUCH_
MAP_ VERSION - Touch-map wire format version.
Functions§
- bind_
invocation_ v2 - Validate and bind one concrete frame. Provenance is copied verbatim and
authenticity remains
Unauthenticatedregardless of its label. - decode_
touch_ map - Decode a touch-map
sol_log_datapayload. Returns an error unless the magic, version, and exact-length equation all hold. - verify
- Verify one instruction’s effects against its mutation contract.
- verify_
bound_ invocation_ v2 - Verify every modeled account transition in a validated frame.
- verify_
invocation - Resolve a parametric instruction from its real post-discriminator argument payload, then verify its concrete effects.
- verify_
resolved - Verify against an already invocation-resolved effect contract.