Module foreign 

Manifest-backed foreign-account lenses.

This module provides manifest-backed foreign-account lenses as a verifiable alternative to ad-hoc offset-based foreign reads.

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 IDL that emits manifest constants as part of its client-generation output

Structs

ExternalAccount

Validated handle to a known external account.

ExternalBytes

Minimal guard-owned external byte view.

ExternalChecked

External account paired with an adapter-specific point-in-time proof token.

ExternalLens

Bounds-checked zero-copy byte lens into an external account.

ForeignLens

A verified read-only handle into a foreign account.

ForeignManifest

Opaque witness to a foreign program’s layout ABI.

Traits

ExplainExternal

Optional structured explain hook for external account adapters.

ExternalExplainSink

Minimal no-allocation sink for external explain adapters.

ExternalLensValue

Copyable value that can be read from a checked external-account byte lens.

ExternalProof

Adapter-specific proof verifier for known external accounts.

ExternalResolve

Owner/discriminator-selected resolver for external account families.

ExternalZeroCopy

Validation contract for known non-Hopper account layouts.