artblocks/develop-postparam-hooks

Developing PostParam Hooks

PostParam hooks are Solidity contracts that extend Art Blocks' PostParams system. Two hook types exist:

| Hook type | Interface | Triggered by | Can revert? | Use for | |---|---|---|---|---| | Augment | IPMPAugmentHook | Every getTokenParams() read | No (view) | Inject live on-chain data into tokenData | | Configure | IPMPConfigureHook | Every configureTokenParams() write | Yes | Validate or gate collector param changes | | Combined | Both | Both | Augment: no; Configure: yes | Full control (e.g. LiftHooks) |

Step 1 — Choose your hook type

Build an augment hook if you want to:

• Inject dynamic on-chain data (token owner, block height, ETH balance, oracle prices, NFT ownership)
• Keep the art script reactive to real-world state without collector interaction

Build a configure hook if you want to:

• Validate that a param change meets custom conditions before it's accepted
• Revert invalid configurations (e.g. "collector must own a specific NFT to set this value")

Build a combined hook (implement both interfaces in one contract) when you need both.

Check reference.md for the full list of standard augment hooks — you may not need to write one at all.

Step 2 — Set up your project

The interfaces are small and self-contained (only depend on OpenZeppelin IERC165).

Foundry — copy the three interface files into src/interfaces/:

• IPMPAugmentHook.sol
• IPMPConfigureHook.sol
• IWeb3Call.sol

Install OpenZeppelin as your only dependency:

forge install OpenZeppelin/openzeppelin-contracts

Hardhat / npm — install the published package for interfaces + ABIs:

npm install @artblocks/contracts @openzeppelin/contracts

Step 3 — Write your hook

See the ready-to-use templates in templates/. Abbreviated versions below.

Augment hook

// SPDX-License-Identifier: LGPL-3.0-only
pragma solidity ^0.8.22;

import {IERC165} from "@openzeppelin/contracts/interfaces/IERC165.sol";
import {IWeb3Call} from "./interfaces/IWeb3Call.sol";
import {IPMPAugmentHook} from "./interfaces/IPMPAugmentHook.sol";

contract MyAugmentHook is IPMPAugmentHook {
    function supportsInterface(bytes4 interfaceId) external pure override returns (bool) {
        return interfaceId == type(IPMPAugmentHook).interfaceId
            || interfaceId == type(IERC165).interfaceId;
    }

    function onTokenPMPReadAugmentation(
        address coreContract,
        uint256 tokenId,
        IWeb3Call.TokenParam[] calldata tokenParams
    ) external view override returns (IWeb3Call.TokenParam[] memory augmentedTokenParams) {
        uint256 n = tokenParams.length;
        augmentedTokenParams = new IWeb3Call.TokenParam[](n + 1);
        for (uint256 i = 0; i < n; i++) {
            augmentedTokenParams[i] = tokenParams[i]; // must copy all existing params
        }
        augmentedTokenParams[n] = IWeb3Call.TokenParam({
            key: "myKey",
            value: _computeValue(coreContract, tokenId)
        });
    }

    function _computeValue(address coreContract, uint256 tokenId)
        internal view returns (string memory)
    {
        // TODO: your on-chain read logic here
    }
}

Configure hook

// SPDX-License-Identifier: LGPL-3.0-only
pragma solidity ^0.8.22;

import {IERC165} from "@openzeppelin/contracts/interfaces/IERC165.sol";
import {IPMPConfigureHook} from "./interfaces/IPMPConfigureHook.sol";
import {IPMPV0} from "./interfaces/IPMPV0.sol";

contract MyConfigureHook is IPMPConfigureHook {
    function supportsInterface(bytes4 interfaceId) external pure override returns (bool) {
        return interfaceId == type(IPMPConfigureHook).interfaceId
            || interfaceId == type(IERC165).interfaceId;
    }

    function onTokenPMPConfigure(
        address coreContract,
        uint256 tokenId,
        IPMPV0.PMPInput calldata pmpInput
    ) external override {
        // Revert to block invalid configuration. Reverts here roll back
        // the collector's entire configureTokenParams transaction.
        require(/* your validation logic */, "Invalid configuration");
    }
}

Combined hook (both interfaces)

Implement both onTokenPMPReadAugmentation and onTokenPMPConfigure in one contract and return true for both interface IDs in supportsInterface. See templates/CombinedHook.sol for the full pattern.

Step 4 — Test your hook

No fork or full repo clone required for unit tests.

Unit test (Foundry) — call the hook directly:

function test_augmentation_appends_key() public {
    MyAugmentHook hook = new MyAugmentHook();

    IWeb3Call.TokenParam[] memory input = new IWeb3Call.TokenParam[](1);
    input[0] = IWeb3Call.TokenParam({key: "existingKey", value: "existingValue"});

    IWeb3Call.TokenParam[] memory result =
        hook.onTokenPMPReadAugmentation(address(0), 0, input);

    assertEq(result.length, 2);
    assertEq(result[0].key, "existingKey"); // original param preserved
    assertEq(result[1].key, "myKey");       // new param appended
}

function test_supportsInterface() public {
    MyAugmentHook hook = new MyAugmentHook();
    assertTrue(hook.supportsInterface(type(IPMPAugmentHook).interfaceId));
    assertTrue(hook.supportsInterface(type(IERC165).interfaceId));
}

Integration test against real PMPV0 — fork Sepolia:

forge test --fork-url $SEPOLIA_RPC_URL

// Uses live PMPV0 at 0x00000000A78E278b2d2e2935FaeBe19ee9F1FF14
IPMPV0 pmpV0 = IPMPV0(0x00000000A78E278b2d2e2935FaeBe19ee9F1FF14);
IWeb3Call.TokenParam[] memory params = pmpV0.getTokenParams(coreContract, tokenId);
// assert your hook's injected key appears in params

Step 5 — Deploy

Deploy to Sepolia staging first, then repeat for mainnet.

# Foundry
forge create src/MyAugmentHook.sol:MyAugmentHook \
  --rpc-url $SEPOLIA_RPC_URL \
  --private-key $PRIVATE_KEY

# Verify on Etherscan
forge verify-contract <deployed-address> src/MyAugmentHook.sol:MyAugmentHook \
  --chain sepolia --etherscan-api-key $ETHERSCAN_API_KEY

# Hardhat
npx hardhat run scripts/deploy.js --network sepolia
npx hardhat verify <deployed-address> --network sepolia

Step 6 — Register via Creator Dashboard

The Creator Dashboard is the recommended way to attach your hook:

1. Go to create.artblocks.io → your project → PostParams
2. Find the Augmentation Hooks (or Configure Hooks) section
3. Paste your deployed contract address
4. The dashboard validates ERC165 compatibility on-chain before saving

To register programmatically instead, call PMPV0 directly (artist wallet required):

IPMPV0(0x00000000A78E278b2d2e2935FaeBe19ee9F1FF14).configureProjectHooks(
    coreContract,
    projectId,
    IPMPConfigureHook(address(0)),    // pass address(0) if not using configure hook
    IPMPAugmentHook(myAugmentHook)    // pass address(0) if not using augment hook
);

PMPV0 is deployed at the same address on all chains (mainnet, Sepolia, Arbitrum, Base).

Step 7 — Access injected data in your art script

const postParams = tokenData.externalAssetDependencies[0];
const myValue = postParams?.data?.["myKey"]; // string or undefined

Verify the correct dependency index in Creator Dashboard under Scripts → Flex Assets.

Critical gotchas

• Augment hook must return ALL params — copy the input array in full, then append. Returning only new params drops all configured PostParams from tokenData.
• Configure hook reverts block the collector's entire transaction — validate carefully and keep access control tight.
• supportsInterface is validated on-chain at registration time — if it returns false for the correct interface ID, configureProjectHooks reverts.
• Augment hooks are view — no state changes, no events.
• Gas cost — augment hooks are called on every read of getTokenParams(). Keep computation cheap; avoid unbounded loops or heavy storage reads.
• No standard hook needed? — check reference.md for the full list of pre-deployed standard hooks (block height, token owner, ETH balance, etc.) that require zero Solidity.

Additional resources

• reference.md — full interface specs, deployed addresses, standard hook catalog
• templates/AugmentHook.sol — complete augment hook template
• templates/ConfigureHook.sol — complete configure hook template
• templates/CombinedHook.sol — combined hook template
• artblocks-contracts repo — 16 real augment hook examples
• PostParams docs — full PostParams reference