Proposal Hooks

There are two kinds of hooks that proposal modules fire:

1. Proposal hooks: fire when proposals are created and when their status changes.
2. Vote hooks: fire when new votes are cast.

Proposal Hooks

The AddProposalHook message will add a new proposal hook receiver. RemoveProposalHook will remove it.

Hooks are fired on every proposal status change except ExecutionFailed and when proposals are created. For example, if a passed proposal is executed, hook receivers will receive a status changed hook:

{
    proposal_status_changed: {
        id: u64,
        old_status: string,
        new_status: string
    }
}

The old_status and new_status fields will contain a string version of whatever status enum the proposal module in question uses.

When a proposal is created, a new proposal hook:

{
    new_proposal: {
        id: u64,
        proposer: string
    }
}

Vote Hooks

When a vote is cast, a new vote hook fires:

{
    new_vote: {
        proposal_id: u64,
        voter: string,
        vote: string
    }
}

If revoting is enabled, vote hooks may fire more than once for the same voter and proposal_id. If you are implementing some kind of voting rewards system, be aware of this. You may want to collect vote information and then distribute rewards once a proposal hooks says the proposal has completed.

The vote field will contain a string version of the vote cast. Note that this will differ across proposal modules as, for example, a multiple and single choice vote look fairly different.

Error handling

If a hook receiver ever panics or errors while receiving a hook, the proposal module will remove the receiver and they will receive no additional hooks until such a time that they are registered again.