Skip to main content

Crate grillo_verifier

Crate grillo_verifier 

Source
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

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§

AccountDelta
A pre/post snapshot of one account in the instruction, its bytes and, optionally, its lamport balance.
AccountRoleContractV2
One account role, reused by fixed and remaining-account grammar entries.
AccountTransitionV2
Pre/post state for one unique pubkey.
BoundInvocationV2
Immutable, validated binding of a concrete frame to a v0.2 contract.
ContractCompletenessV2
Dimensions for which the producer claims the contract is complete.
CpiAccountBindingV2
Map one child position to one concrete parent position.
CpiEnvelopeV2
One declared child invocation shape.
DataPolicyV2
Byte writes permitted within data that exists after the invocation.
DataRangeV2
Half-open data range [offset, offset + size) within one role.
DeploymentIdentityV2
Concrete loader/deployment identity observed for one invocation.
EffectContractV2
A complete program effect contract.
EvidenceCompletenessV2
Dimensions claimed present in this evidence object.
InstructionContract
The mutation contract for one instruction.
InstructionEffectContractV2
One fully identified instruction contract.
InvocationAccountRefV2
Effective account meta at one invocation position.
InvocationFrameV2
Full concrete evidence for one invocation plus its ordered CPI children.
MutationManifest
A Hopper program manifest, parsed down to its mutation contract.
NetworkIdentityV2
Cluster identity for replay separation.
ParametricRangeContract
One invocation-parametric byte-range rule from a Hopper manifest.
PassEvidence
Evidence backing a PASS.
PassEvidenceV2
Evidence returned by an unauthenticated behavioral PASS.
RangeContract
One authorized byte-range write permission on a single account.
RemainingAccountsContractV2
Deterministic account-suffix grammar.
RemainingGroupV2
One fixed-width role group repeated a statically bounded number of times.
ResolvedAccountRoleV2
Concrete resolved role after expanding the remaining-account grammar.
ResolvedInstructionContract
A concrete instruction effect contract after all parametric rules have been bound to invocation arguments.
TouchEvidenceV2
Optional attributed touch carrier. The digest is committed, but this first slice does not treat it as independently authenticated.
TouchMap
A decoded touch map, with its honesty flags preserved.
TouchRecord
One decoded touch record: a single (account, offset, size, R/W) range the instruction touched.
TransactionIdentityV2
Transaction and exact call-tree location.
TransitionPolicyV2
All state-transition dimensions for one account role.

Enums§

AccountStateV2
Logical loaded-state observation. Absence is explicit and is never inferred from zero lamports or System ownership.
AddressConstraintV2
Address identity for one role.
BindErrorV2
Why an untrusted frame could not be bound to a contract.
CpiPolicyV2
Complete CPI policy for an instruction.
DecodeError
Why a byte slice is not a valid touch-map v1 payload.
DeploymentBindingV2
How a portable contract binds to deployed executable code.
DuplicatePolicyV2
Alias policy for the complete fixed + remaining account list.
EffectContractV2Error
Strict v0.2 parse/validation failure.
EffectVerdictV2
Behavioral verdict. No variant claims ledger or provider authenticity.
EvidenceProvenanceV2
Untrusted provenance label retained in evidence and verdicts.
ExecutablePolicyV2
Executable-bit transition.
InconclusiveReason
Why a verdict could not be a definitive PASS or VIOLATION.
InconclusiveReasonV2
Why a privately bound frame still cannot support a complete verdict.
InvocationOutcomeV2
Whether an invocation’s effects survived its observed execution boundary.
LamportPolicyV2
Permitted balance direction.
LengthPolicyV2
Data-length transition.
ObservationBoundaryV2
Boundary at which pre/post state was observed.
OwnerPolicyV2
Owner transition.
OwnerTargetV2
Resolved owner target.
PresencePolicyV2
Logical account presence transition. A close tombstone can be represented as a present zeroed/System-owned post-state; it is not inferred as absent.
PrivilegeRequirementV2
Required/forbidden/optional effective privilege.
ResolveError
Why an invocation-specific effect contract could not be resolved.
UnverifiedAuthenticityV2
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.
ViolationV2
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 Unauthenticated regardless of its label.
decode_touch_map
Decode a touch-map sol_log_data payload. 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.