Harpoon Module Reference
The Harpoon module allows CosmWasm smart contracts to subscribe to staking module hooks for tracking historical voting power and other staking events.Messages
MsgManageHookSubscription
Manages hook subscriptions for a contract address. Can only be executed by the module’s authority (governance).- Adds the contract to specified hook types
- Removes the contract from hook types not in the list
- Passing an empty
hooks
array removes all subscriptions for the contract
Queries
SubscribedContracts
Retrieves contracts subscribed to a specific hook type.GET /neutron/harpoon/subscribed_contracts
CLI Commands
Query Commands
subscribed-contracts
Lists all contracts subscribed to a given hook type.hook-type
: The specific hook type to query (e.g.,HOOK_TYPE_AFTER_VALIDATOR_CREATED
)
Hook Types
Available staking hooks that contracts can subscribe to:Storage
Hook Subscriptions
The module stores subscriptions with the following structure:Genesis
The module’s genesis state contains all hook subscriptions:Module Constants
- ModuleName:
"harpoon"
- StoreKey:
"harpoon"
- RouterKey:
"harpoon"
Sudo Message Formats
When hooks are triggered, contracts receive specific message formats:Validator Hooks
Delegation Hooks
Unbonding Hooks
Key Implementation Details
- No Cached Context: Sudo calls use the original context, ensuring state consistency
- Error Propagation: Contract errors can abort transactions or halt the chain
- Governance-Only: Only governance can manage hook subscriptions
- Special Slashing Hook:
BeforeValidatorSlashed
panics;BeforeValidatorSlashedWithTokensToBurn
is used instead - Subscription Management: Adding/removing hooks is done atomically per contract