​
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 via sudo 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 the ManageHookSubscription 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 as BeforeValidatorSlashedWithTokensToBurn)
  • Unbonding Hooks: AfterUnbondingInitiated

​
Hook Execution Model

When a staking event occurs, the Harpoon module executes a sudo 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
This design ensures state consistency between the staking module and subscribed contracts, but requires contracts to be extremely robust and error-free.

​
Documentation Sections

​
Technical Details

Deep dive into how Harpoon works and its integration with the staking module

​
How-to Guide

Step-by-step instructions for using Harpoon in your contracts

​
Reference

Complete reference documentation for the Harpoon module