02 / Hooks / holder-xp
Holder XP
An on-chain loyalty ledger earned through routed buys and holding, with anti-wash rules.
01
Behavior
- XP is earned on routed buys only, never on sells.
- Buy XP vests after a hold period; selling before vesting forfeits the unvested XP, so buy/sell loops earn nothing.
- Per-trade cap, minimum trade size and a daily cap per wallet.
- Optional holding XP on min(balance at last checkpoint, balance now) × elapsed time.
Limitation. XP is a ledger entry, not a token and not a claim on fees.
Limitation. Two wallets that each hold at both of their own checkpoints can overlap holding intervals; caps bound the effect (threat model T20).
02
Callbacks
ABI v1 · wire values frozen| # | Callback | Subscribable | Default | Semantics |
|---|---|---|---|---|
| 0 | BeforeBuy | — | Routed buy, before the Pump CPI. Can deny. | |
| 1 | AfterBuy | yes | ● | Routed buy, after the Pump CPI. Sees executed amounts; can still fail the transaction. |
| 2 | BeforeSell | — | Routed sell, before the Pump CPI. Can deny. | |
| 3 | AfterSell | yes | ● | Routed sell, after the Pump CPI. |
| 4 | BeforeSwap | — | Either side, before the Pump CPI. Can deny. | |
| 5 | AfterSwap | — | Either side, after the Pump CPI. | |
| 6 | BeforeLiquidity | reserved | Reserved (wire value 6). | |
| 7 | AfterLiquidity | reserved | Reserved (wire value 7). | |
| 8 | BeforeFeeAction | reserved | Reserved (wire value 8). | |
| 9 | AfterFeeAction | reserved | Reserved (wire value 9). | |
| 10 | OnGraduation | reserved | Reserved (wire value 10). | |
| 11 | OnStrategySignal | reserved | Reserved (wire value 11). |
03
Capabilities
granted at install; enforced by the executor| ■ | READ_MARKET | Read market config, venue reserves and the trade context |
| □ | VETO_ROUTED_SWAP | Deny a routed trade in a before-callback (reverts the transaction) |
| ■ | WRITE_HOOK_STATE | Persist its 48-byte slot state on the market |
| ■ | WRITE_USER_STATE | Update the trading wallet's per-market state |
| ■ | AWARD_POINTS | Credit XP / points in the wallet's per-market ledger |
| □ | TREASURY_SIGNAL | Emit treasury allocation intents for the strategy vault |
| □ | STRATEGY_EXECUTION | Bound or request vault strategy execution (TWAP, orders) |
| □ | ORACLE_READ | Read an external oracle account (reserved; not granted in V1) |
| □ | EXTERNAL_CPI | Call an external hook program (reserved; no permissionless CPI hooks in V1) |
| □ | EMIT_SIGNAL | Emit or consume signed strategy signals |
04
Config schema
48 bytes · little-endian| Field | Type | Offset | Unit | Preset | Description |
|---|---|---|---|---|---|
| perTradeCapQuote | u64 | 0 | lamports | 10 SOL | Quote above this per trade earns nothing extra |
| xpPerSol | u32 | 8 | xp | 100 | XP per 1 SOL of routed buy |
| vestSecs | u32 | 12 | seconds | 3600 | Hold period before buy XP vests |
| dailyCap | u32 | 16 | xp | 10000 | XP per wallet per day |
| holdXpPerDay | u32 | 20 | xp | — | XP per day for holding |
| holdCapBase | u64 | 24 | base | — | Balance that earns the full holding XP |
| minTradeQuote | u64 | 32 | lamports | 0.01 SOL | Trades below this earn no XP |
05
Identity
Module ID
4 (0x0004)
Version
v1
Developer
Pump Hooks
Program
91kRNewiED… (built-in)
Priority range
2000–2999 · default 2100
Markets
bonding-curve · pumpswap
Source
crates/hook-runtime/src/modules/holder_xp.rs
Verification
source in this repository; reproducible-build verification not yet published
Audit
unaudited
06