Skip to main content

Prize Hooks

What are Prize Hooks?​

Prize hooks are modular onchain actions, configurable by a depositor, that automatically execute when a prize is claimed for them on a standard vault.

What can they do?​

Prize hooks can be used to create enriched prize experiences such as:

How do they work?​

Prize Hook Diagram

In the above diagram, we see how Alice can set a custom prize hook on a vault to automatically trigger the execution of additional code when she wins a prize.

Prize hooks can be created permissionlessly by deploying a contract that extends the IPrizeHooks interface. Up to two hooks can be implemented (beforeClaimPrize and afterClaimPrize). Like the names suggest, the first is called immediately before the prize is claimed while the second is called immediately after. Both hooks are passed some basic data about the prize that is being claimed which can be used to verify the prize win, determine prize size and claim fee, and identify the recipient.

Each user can set different hooks on each vault they are deposited in. When that user wins a prize, their specified hooks are called. The user can change or remove their hooks at any time.

Create a Prize Hook​

Custom prize hooks can be created by deploying a contract that extends the IPrizeHooks interface. See the prize hook examples to get started!

Gas Limits​

On standard vaults, each hook (beforeClaimPrize and afterClaimPrize) is limited to 150k gas. This is to prevent hook executions from becoming too costly for claimers since they pay the extra gas required. If the hook exceeds this limit, the call will revert. Limits may be different on non-standard vaults.

Using a Prize Hook​

To opt-in to a new prize hook on a standard vault, you can call the setHooks function on the vault with the following data:

struct VaultHooks {
  bool useBeforeClaimPrize; // if true, the `beforeClaimPrize` hook will be called
  bool useAfterClaimPrize; // if true, the `afterClaimPrize` hook will be called
  contract IPrizeHooks implementation; // the address of the hook contract
}

If you would like to set the hooks on multiple vaults, you will need to repeat the process on each one.

Removing a Prize Hook​

To unset a prize hook on a vault, call the setHooks function with all params set to their default values:

VaultHooks({
  useBeforeClaimPrize: false,
  useAfterClaimPrize: false,
  implementation: address(0)
})

Try it out!​

If you have a hook you would like to try, use the following form to generate the transaction data needed to set it on a prize vault:

Use Before Claim Hook Use After Claim Hook