Module foreign 

Manifest-backed foreign-account lenses.

The Hopper Safety Audit (page 14, “Manifest-backed foreign account lenses”) proposed a verifiable cross-program read API as the next step beyond ad-hoc offset-based foreign reads. This module implements it.

Problem

Today, reading a field from an account owned by a different program either imports the foreign program’s crate (tight coupling, forces version-lock) or reads raw bytes by hand-maintained offset (no ABI-drift detection. if the foreign program changes its layout, silent misreads result).

Design

A ForeignManifest is an opaque witness (supplied by the caller) that carries the foreign program’s wire_fp64 hash plus the layout discriminator it expects for a particular T: AccountLayout. When ctx.foreign::<T>(idx, &manifest)? is called:

1. The account’s owner must match manifest.program_id
2. The account’s header discriminator must match T::DISC and manifest.expected_disc
3. The header’s wire_fp64 must match T::WIRE_FINGERPRINT and manifest.expected_wire_fp
4. schema_epoch must fall in manifest.supported_epochs

Only after all four pass does the lens expose field access. Any mismatch returns ProgramError::InvalidAccountData. never silent mis-reads, never UB.

Manifest sourcing

Hopper does not fetch manifests from RPC inside a program (that would be round-trip CPI with no caching story). Manifests are caller-supplied, typically from:

• An embedded const ForeignManifest authored when the program was built (works when the foreign program’s ABI is known at build time)
• A manifest account located at the canonical manifest PDA (find_program_address(&[MANIFEST_SEED], &foreign_program_id)) whose payload has already been verified by a prior instruction
• A Hopper-authored IDL that emits manifest constants as part of its client-generation output

Structs

ForeignLens

A verified read-only handle into a foreign account.

ForeignManifest

Opaque witness to a foreign program’s layout ABI.