Overview
The Harpoon module allows CosmWasm smart contracts to subscribe to staking module hooks. Its primary purpose is to enable the calculation of historical voting power from the staking module, which is essential for governance systems that rely on historical data at specific block heights.Table of contents
- Overview — a high-level description of the module.
- Explanation — an explanation of the module’s concepts and the reasoning behind its design choices.
- How-to — short guides on performing basic operations with the module.
- Reference — details about the module’s interface, including messages, queries, and hook types.
Concepts
The Harpoon module acts as a bridge between the staking module’s hooks and CosmWasm smart contracts. When staking-related events occur (such as delegations, unbondings, or validator changes), the module notifies subscribed contracts viasudo calls, allowing them to maintain historical records.
Why Harpoon is Needed
Standard CosmWasm contracts cannot directly query historical staking data. While contracts can query current staking information, they cannot access data from previous block heights. This limitation is particularly problematic for governance systems that need to determine voting power at the time a proposal was created. Harpoon solves this by allowing contracts to subscribe to staking events and maintain their own historical records, enabling accurate historical voting power calculations.Subscription Mechanism
Subscriptions to staking hooks can only be created through governance proposals using theManageHookSubscription message. This restriction ensures that only thoroughly vetted contracts can receive these notifications, preventing potential spam or security issues.
Available Hooks
Harpoon supports all the hooks provided by the Cosmos SDK staking module:- Validator Hooks:
AfterValidatorCreated,BeforeValidatorModified,AfterValidatorRemoved,AfterValidatorBonded,AfterValidatorBeginUnbonding - Delegation Hooks:
BeforeDelegationCreated,BeforeDelegationSharesModified,BeforeDelegationRemoved,AfterDelegationModified - Slashing Hooks:
BeforeValidatorSlashed(implemented asBeforeValidatorSlashedWithTokensToBurn) - Unbonding Hooks:
AfterUnbondingInitiated
Hook Execution Model
When a staking event occurs, the Harpoon module executes asudo call on each subscribed contract. These calls are performed in the same context as the original operation (no cached context), meaning:
- Transaction Hooks: Can abort the transaction if the contract returns an error
- End-Blocker Hooks: Can potentially halt the chain if the contract returns an error