# Hopper Examples

These examples teach Hopper in layers. Start with the counter, then move into a
small vault or escrow flow, Token-2022, migration, cross-program interfaces, and
the full showcase once the basics are familiar.

## Learning Order

### Tier 1: Start Here

1. **[hopper-counter](hopper-counter/src/lib.rs)** - The smallest macro-first
   Hopper program: one account, one context, one instruction. Start here when
   you want the framework model before any systems concepts.

2. **[hopper-vault](hopper-vault/src/lib.rs)** - A compact SOL vault. Three
   instructions (init, deposit, withdraw). Good for seeing Hopper's account,
   dispatch, and state basics in one place. Companion guide:
   [hopper-vault/README.md](hopper-vault/README.md)

3. **[hopper-escrow](hopper-escrow/src/lib.rs)** - Token escrow with authority
   checks and SPL Token integration. Companion guide: [hopper-escrow/README.md](hopper-escrow/README.md)

4. **[hopper-token-2022-vault](hopper-token-2022-vault/src/lib.rs)** - Hopper-owned
   Token-2022 vault flow with a local `hopper.manifest.json`, so the CLI can
   infer the package manifest and emit lowered accessors directly from the
   example directory.

5. **[quasar-port-20-min](quasar-port-20-min/src/lib.rs)** - Bounded
   dynamic-tail example for a fixed vault and multisig metadata using
   `#[hopper::dynamic_account]`, initialization helpers, and threshold checks.
   Companion guide:
   [../docs/PORT_QUASAR_IN_20_MINUTES.md](../docs/PORT_QUASAR_IN_20_MINUTES.md)

### Tier 2: Advanced Patterns

6. **[hopper-proc-vault](hopper-proc-vault/src/lib.rs)** - Proc-macro vault that
   demonstrates the `#[hopper::account]` / `#[hopper::program]` authoring path.

7. **[hopper-treasury](hopper-treasury/src/lib.rs)** - Multi-segment treasury
   with permissions and budget controls.

8. **[hopper-registry](hopper-registry/src/lib.rs)** - Segmented account with
   journal, virtual state, and named segment lookup.

9. **[hopper-migration](hopper-migration/src/lib.rs)** - V1 to V2 layout
   evolution. Shows how append-only versioning and the migration planner work
   together. Companion guide: [hopper-migration/README.md](hopper-migration/README.md)

10. **[hopper-virtual-state](hopper-virtual-state/src/lib.rs)** - Multi-account
   entities with VirtualState and ShardedAccess. For when your state is too big
   for one account.

11. **[cross-program-read](cross-program-read/)** - Two separate programs reading
   each other's accounts via `hopper_interface!`. No shared crate dependency.
   Companion guide: [cross-program-read/README.md](cross-program-read/README.md)

12. **[hopper-policy-vault](hopper-policy-vault/src/lib.rs)** - Three sibling
    programs (`strict`, `sealed`, `raw`) demonstrating the policy-driven runtime
    plus the `#[instruction(N, unsafe_memory, skip_token_checks)]` per-handler
    overrides. Companion guide:
    [hopper-policy-vault/README.md](hopper-policy-vault/README.md)

13. **[hopper-showcase](hopper-showcase/src/lib.rs)** - Full systems-mode tour.
    Uses layout, dispatch, phased frame, policy, receipts, invariants, segment
    roles, and state diffs. Read this after the smaller examples. Companion
    guide: [hopper-showcase/README.md](hopper-showcase/README.md)

### Tier 3: Escape Hatch

Every example uses the standard Hopper path. When you need to go lower, the
framework provides `load_unchecked`, raw `overlay_mut`, manual `write_header`,
and `segment_data_mut_unchecked`. These are documented in the API but not
demonstrated in a dedicated example because the whole point is that you
should not need them often.
