schema

the protocol's hardcoded constants, program instructions, and view interface.

constants

total supply21,000,000 × 10^9

pool fee0

tick spacing64

max tick range±443636

coefficient walk window±3 tickArrays

stage count7

threshold precision9 decimals

coefficient max1.000 (1e9 fixed-point)

all constants are declared in the program bytecode and the immutable mint config. total supply is minted once at initialization. mint authority and freeze authority are renounced. none of these can be changed by any caller, including the deployer.

program instructions

initialize_pool

initialize_extra_account_meta_list

transfer_hook_execute

update_coefficient_state

emit_stage_transition

fallback

Six instructions exposed. The transfer hook entrypoint is invoked by the Token-2022 program on every tame token movement and dispatches internally on transfer direction. The Token-2022 program validates the ExtraAccountMetaList before invocation — a malformed list causes the entire transfer to fail at the program boundary.

view functions

get_concentration_coefficient() → u64returns the current concentration coefficient as 9-decimal fixed-point. the value the creature's tameness is computed from.

get_cumulative_swap_count() → u64total swaps the hook has processed across the bound pool's lifetime. incremented in the swap path, never decremented.

get_current_tick() → i32the pool's active tick at the moment of the call. read from the Whirlpool state account and returned without modification.

get_stage_metrics() → (u64, u64, i64)batched read returning (coefficient, swap count, delta per swap) in a single RPC call to minimize round-trips for the frontend.

get_allowable_tick_width() → u64the current maximum tick width for new LP deposits. computed live from MAX_TICK_RANGE × (1 − coefficient). reverts the transfer hook when an attempted deposit exceeds this value.

get_coefficient_walk_result(active_tick: i32) → u64deterministic re-computation of the coefficient given a hypothetical active tick. used by the frontend to predict tameness transitions.

events

event CoefficientUpdated { old_value: u64, new_value: u64, at_tick: i32 }emitted by the swap path whenever the coefficient changes. consumed by off-chain indexers to build historical state.

event StageTransition { from_stage: u8, to_stage: u8, coefficient: u64 }emitted whenever the swap path causes the coefficient to cross a tameness threshold. the archive page indexes these as the creature's taming log.

event LiquidityRangeRejected { provider: Pubkey, tick_lower: i32, tick_upper: i32 }emitted by the position-open path when a deposit is rejected. the rejected deposit reverts; this event is the only on-chain record that the attempt was made.

event TickWalk { active_tick: i32, walked_ticks: u64, compute_units: u64 }emitted on every swap-path execution with diagnostic data about the tick walk. useful for frontend rendering and compute-unit analysis.