Module behavior 

Reusable, parameterized account lifecycle behaviors.

What this is

A protocol can implement a behavior once, provide per-use arguments, and call the typed phase helpers for each account. A proposed context-attribute surface is documented in docs/design/BEHAVIORS_RFC.md; it is not part of the current macro API:

#[hopper::context(strict_writes)]
struct Collect<'info> {
    #[account(mut(collected), behavior(fee_vault, max_bps = 30))]
    vault: Vault,
    ...
}

The runtime traits and helper functions are available for explicit use today. The example attribute above remains design work tracked in the RFC.

Runtime contracts

1. Proof tokens. A successful run_check returns BehaviorChecked<B> (plus a behavior-defined payload), which composes with the existing AccountProof capability chain. APIs can require that token as evidence that the check helper completed successfully.
2. Write-set contribution. A behavior declares the byte ranges its update/exit phases write (HopperBehavior::WRITES, field-relative). Explicit callers and future code generation can add these descriptors to a context’s write policy. This module does not install a context policy automatically.

Phase model

Phases mirror the account lifecycle. Associated constants state which helpers a behavior enables:

phase   const        runs                          receives
------- ------------ ----------------------------- -----------------
check   RUN_CHECK    after load, before handler    &view, &state
update  RUN_UPDATE   after check (mut fields)      &view, &mut state
exit    RUN_EXIT     epilogue (mut fields)         &view

Structs

BehaviorChecked

Proof token: behavior B ran its check phase against an account and succeeded, yielding B::CheckOutput.

BehaviorWrite

A field-relative byte range a behavior writes during update/exit.

Traits

HopperBehavior

A packageable per-field lifecycle plugin over layout type T.

Functions

run_check

Run behavior B’s check phase against view, loading the typed state through the normal validated path, and mint the proof token.

run_update

Run behavior B’s update phase through the typed mutable path.