Mint hooks

[shanev]

Mint hooks are a way to extend minters by running custom code before and after minting. Creators may write custom hooks to perform tasks such as implementing burn-to-mint. If a hook fails, the entire transaction is rolled back, so this can be used for pre-mint gating.

Hooks can also be chained together to implement composite actions. For example if you want to burn an NFT while requiring 5000 STARS to be staked, you can chain together a burn-to-mint pre-mint hook and a staked tokens pre-mint hook.

For example, a pre-mint hook could receive an NFT and check if its in the collection to be burned. Then after the mint is complete, the post-mint hook could do the actual burn operation.

The pre-mint action, mint, and post-mint actions are sub-messages that are implemented as a single atomic action. They are executed in order, and all rollback if one of them fails.

Macros are provided to easily add this functionality to any minter. This hasn't been added to any minter yet as it depends on cw-ownable being added to minters. However, work is ongoing at #611.

For Creators: How to add a hook

1. Instantiate hook contract(s).
2. Call AddPreMintHook { hook } or AddPostMintHook { hook } for each hook.

For Devs: How to add mint hooks to a minter contract

Add macros for execute and query enums

#[sg_mint_hooks_execute]
#[cw_serde]
pub enum ExecuteMsg {}

#[sg_mint_hooks_query]
#[cw_serde]
#[derive(QueryResponses)]
pub enum QueryMsg {}

Add the pre and post submessages to mint execution

    let premint_hooks = prepare_premint_hooks(
        deps.as_ref(),
        collection.clone(),
        Some(token_id.clone()),
        info.sender.to_string(),
    )?;

    let postmint_hooks = prepare_postmint_hooks(
        deps.as_ref(),
        collection.clone(),
        Some(token_id.clone()),
        info.sender.to_string(),
    )?;

    let mint = WasmMsg::Execute { ... };

    Response::new()
        .add_submessages(premint_hooks)
        .add_submessage(SubMsg::reply_on_error(mint, MINT_REPLY_ID));
        .add_submessages(postmint_hooks);

Handle the reply errors

pub fn reply(deps: DepsMut, _env: Env, msg: Reply) -> Result<Response, ContractError> {
    handle_reply(msg.id)?;

    match msg.id {
        MINT_REPLY_ID => Err(ContractError::MintFailed {}),
    }

}

[codecov]

Codecov Report

Patch coverage has no change and project coverage change: -1.09% ⚠️

Comparison is base (2861976) 59.20% compared to head (62cb016) 58.12%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #612      +/-   ##
==========================================
- Coverage   59.20%   58.12%   -1.09%     
==========================================
  Files          80       82       +2     
  Lines        4246     4325      +79     
==========================================
  Hits         2514     2514              
- Misses       1732     1811      +79     

Files Changed	Coverage Δ
packages/mint-hooks/derive/src/lib.rs	0.00% <0.00%> (ø)
packages/mint-hooks/src/lib.rs	0.00% <0.00%> (ø)

... and 1 file with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[github-actions]

Cosm-Orc Gas Usage

No gas diff larger than 0.5%

Raw Report for ba84d73

Contract	Op Name	Gas Used	Gas Wanted	File
base_factory	Store__Store	2665605	3975267	e2e/src/helpers/chain.rs:78
base_minter	Store__Store	6995048	10469372	e2e/src/helpers/chain.rs:78
open_edition_factory	Store__Store	3434360	5128400	e2e/src/helpers/chain.rs:78
open_edition_factory	Execute__factory_exec_minter_inst	541640	789335	e2e/src/tests/open_edition_factory_and_mint_tests.rs:202
open_edition_factory	Instantiate__factory_inst	186625	256820	e2e/src/helpers/open_edition_minter_helpers.rs:39
open_edition_factory	Execute__factory_exec_minter_inst_w_trading_time	542350	790400	e2e/src/tests/open_edition_factory_and_mint_tests.rs:405
open_edition_minter	Store__Store	8493792	12717488	e2e/src/helpers/chain.rs:78
sg721_base	Store__Store	8382096	12549944	e2e/src/helpers/chain.rs:78
sg721_metadata_onchain	Store__Store	8832975	13226262	e2e/src/helpers/chain.rs:78
sg721_nt	Store__Store	7781314	11648771	e2e/src/helpers/chain.rs:78
sg721_updatable	Store__Store	9157689	13713333	e2e/src/helpers/chain.rs:78
sg_whitelist	Store__Store	3582040	5349920	e2e/src/helpers/chain.rs:78
sg_whitelist_flex	Store__Store	3519822	5256593	e2e/src/helpers/chain.rs:78
vending_factory	Store__Store	3044906	4544219	e2e/src/helpers/chain.rs:78
vending_factory	Execute__factory_exec_minter_inst	34037398	51032904	e2e/src/tests/factory_test.rs:98
vending_factory	Instantiate__factory_inst	187313	257853	e2e/src/helpers/helper.rs:35
vending_factory	Execute__factory_exec_minter_inst_w_trading_time	3857603	5763207	e2e/src/tests/factory_test.rs:244
vending_minter	Store__Store	8757887	13113630	e2e/src/helpers/chain.rs:78
vending_minter_wl_flex	Store__Store	8935500	13380045	e2e/src/helpers/chain.rs:78
whitelist_immutable	Store__Store	2195122	3269543	e2e/src/helpers/chain.rs:78
minter	Execute__minter_exec_mint_to_token	363964	522827	e2e/src/tests/open_edition_minter_executes_tests.rs:180
minter	Execute__minter_exec_purge	139026	185472	e2e/src/tests/open_edition_minter_executes_tests.rs:281
minter	Execute__minter_exec_update_per_addr_limit	209170	290637	e2e/src/tests/open_edition_minter_executes_tests.rs:216
minter	Execute__minter_exec_update_trading_time	271327	383871	e2e/src/tests/open_edition_minter_executes_tests.rs:99
multiple_contracts	Execute__minter_batch_exec_mint_token	3106975	4637592	e2e/src/tests/open_edition_factory_and_mint_tests.rs:272
multiple_contracts	Execute__minter_batch_exec_mint_token_w_trading_time	3108242	4639553	e2e/src/tests/open_edition_factory_and_mint_tests.rs:491