grillo_verifier/lib.rs
1//! # Grillo verifier
2//!
3//! Given caller-supplied pre/post snapshots, a decoded touch map, and an
4//! instruction mutation contract from [`grillo_manifest`], this crate checks
5//! whether the supplied scope is consistent with the contract. It is
6//! computationally separate from the program runtime, but it does not
7//! authenticate bundles or discover omitted accounts.
8//!
9//! The verdict checks one invariant within that supplied scope:
10//!
11//! > **changed subset acquired subset authorized**
12//!
13//! - `changed` comes from pre/post account byte [snapshots](AccountDelta).
14//! - `acquired` comes from the [touch map](TouchMap) the instruction
15//! emitted (its own self-report of what it mutated).
16//! - `authorized` comes from the manifest's `writeRanges`
17//! ([`grillo_manifest::RangeContract`]).
18//!
19//! Acquired-but-unchanged is legal because access is not modification. It is
20//! surfaced as a note on a scoped [PASS](Verdict::Pass), never a violation.
21//!
22//! The verifier re-derives `changed` from supplied raw bytes rather than
23//! trusting the touch map. A changed byte omitted from that supplied map is an
24//! [`UntrackedWrite`](Violation::UntrackedWrite); an acquisition outside the
25//! authorized set is an
26//! [`UnauthorizedAcquisition`](Violation::UnauthorizedAcquisition). A
27//! [partial](TouchMap::is_partial) map yields
28//! [`INCONCLUSIVE`](InconclusiveReason::PartialTouchMap). Changes in accounts
29//! omitted from the bundle remain outside the observation boundary.
30//!
31//! ```
32//! use grillo_manifest::MutationManifest;
33//! use grillo_verifier::{verify, AccountDelta, TouchMap, TouchRecord, Verdict};
34//!
35//! // A `pause` that may only write config byte 114 (paused).
36//! let manifest = MutationManifest::from_json(r#"{
37//! "name": "p", "version": "1.0.0",
38//! "instructions": [
39//! { "name": "pause", "tag": 1, "strictWrites": true,
40//! "writeRanges": [ { "accountIndex": 1, "offset": 114, "size": 1 } ],
41//! "accounts": [ { "name": "admin" }, { "name": "config" } ] }
42//! ]
43//! }"#).unwrap();
44//! let pause = manifest.instruction("pause").unwrap();
45//!
46//! let pre = vec![0u8; 200];
47//! let mut post = pre.clone();
48//! post[114] = 1; // set `paused`
49//!
50//! let map = TouchMap {
51//! overflowed: false, skipped: false,
52//! records: vec![TouchRecord { slot: 1, offset: 114, size: 1, write: true }],
53//! };
54//! let verdict = verify(pause, &[AccountDelta::new(1, &pre, &post)], &map);
55//! assert!(verdict.is_pass());
56//! ```
57
58#[cfg(feature = "cli")]
59mod bundle;
60mod frame_v2;
61mod touch_map;
62mod verify;
63mod verify_v2;
64
65#[cfg(feature = "cli")]
66pub use bundle::{parse_bundle, verify_bundle, BundleAccount, BundleError, EvidenceBundle};
67
68pub use frame_v2::{
69 bind_invocation_v2, AccountStateV2, AccountTransitionV2, BindErrorV2, BoundInvocationV2,
70 DeploymentIdentityV2, EvidenceCompletenessV2, EvidenceProvenanceV2, InvocationAccountRefV2,
71 InvocationFrameV2, InvocationOutcomeV2, NetworkIdentityV2, ObservationBoundaryV2,
72 ResolvedAccountRoleV2, TouchEvidenceV2, TransactionIdentityV2, UnverifiedAuthenticityV2,
73};
74pub use touch_map::{
75 decode_touch_map, DecodeError, TouchMap, TouchRecord, MAX_TOUCH_RECORDS,
76 TOUCH_MAP_FLAG_OVERFLOWED, TOUCH_MAP_FLAG_SKIPPED, TOUCH_MAP_HEADER_LEN, TOUCH_MAP_MAGIC,
77 TOUCH_MAP_RECORD_LEN, TOUCH_MAP_VERSION,
78};
79pub use verify::{
80 verify, verify_invocation, verify_resolved, AccountDelta, InconclusiveReason, PassEvidence,
81 Verdict, Violation,
82};
83pub use verify_v2::{
84 verify_bound_invocation_v2, EffectVerdictV2, InconclusiveReasonV2, PassEvidenceV2, ViolationV2,
85};
86
87// Re-exported so downstream users get the contract types without a second
88// `use` of the sibling crate.
89/// Upgrade authority diff between two manifests (re-exported from
90/// `grillo-manifest`).
91pub use grillo_manifest::authority;
92pub use grillo_manifest::{
93 AccountRoleContractV2, AddressConstraintV2, ContractCompletenessV2, CpiAccountBindingV2,
94 CpiEnvelopeV2, CpiPolicyV2, DataPolicyV2, DataRangeV2, DeploymentBindingV2, DuplicatePolicyV2,
95 EffectContractV2, EffectContractV2Error, ExecutablePolicyV2, InstructionEffectContractV2,
96 LamportPolicyV2, LengthPolicyV2, OwnerPolicyV2, OwnerTargetV2, PresencePolicyV2,
97 PrivilegeRequirementV2, RemainingAccountsContractV2, RemainingGroupV2, TransitionPolicyV2,
98 EFFECT_ABI_V2,
99};
100pub use grillo_manifest::{
101 InstructionContract, MutationManifest, ParametricRangeContract, RangeContract, ResolveError,
102 ResolvedInstructionContract,
103};