NFT callbacks

Which NFTs support it?

The collection contract must implement IFWAPurchaseCallback and advertise it through ERC-165. The pool's notifier checks supportsInterface(0x91f3d79d) on that collection when the listing settles. A compatible collection returns true. Ordinary ERC-721 support alone does not enable the feature.

This is a callback to the NFT collection itself. Implementing it on a purchaser wallet or an ordinary depositor contract does not subscribe that address. It is also separate from the ERC-721 receiving hook used by some NFT transfers.

A FWAIR collection can support the same feature. Its collection callback is independent of the launch contract's accounting notification. The launch is notified first; if the launch and collection are the same address, that address is called once.

These callbacks are supported by the main pool. Standard and buyback custom pools do not dispatch them, even when the NFT contract advertises the interface.

What if the NFT callback fails?

A failed collection callback does not undo a successful settlement. The receiver gets up to 100,000 gas and no ETH. If it reverts or runs out of its allotted gas, its own changes roll back while the settlement can still complete. Any collection-specific effect may therefore be absent even though the purchase settled.

The notifier records each actual receiver call in PurchaseCallbackAttempted(fwa, target, listingId, success). A failed or unsupported ERC-165 probe skips the collection without an attempted-callback event. A successful call means the receiver returned without reverting; it does not prove a particular collection effect occurred.

The pool does not replay missed collection callbacks after successful settlement. Collections should keep essential state recoverable from canonical listings and settlement events, and provide their own reconciliation path if their feature needs one.

The pool's call to the notifier itself is a separate requirement. If that outer call fails, the entire settlement reverts and the position can be resolved again. The pool forwards 300,000 gas to the notifier, which requires at least 290,000 gas on entry; collection lookup and the ERC-165 probe each have a 30,000-gas cap. These are internal budgets, not a suggested limit for the complete settlement transaction.

Collection implementation reference

The interface lives at src/interfaces/IFWAPurchaseCallback.sol in the contracts repository. Its function has no return value or success selector:

function onFWAPurchase(
    address fwa,
    uint256 listingId,
    address purchaser,
    address resolver,
    uint256 backing,
    uint256 settlementAmount,
    IFWAPurchaseCallback.Outcome outcome
) external;

At the receiver, msg.sender is the immutable purchase notifier. Authenticate both that exact trusted notifier and the expected fwa address. The notifier is permissionless, so checking its address alone is insufficient. Use the notifier address from trusted deployment configuration.

Read listings(listingId) from the trusted pool and verify that it is settled and names your contract as the collection before applying collection behavior. The purchaser is the recipient named in the acquisition request, who owns the allocation even when a different wallet or router paid. The resolver is the immediate caller of the pool's settlement function, which can be a campaign or forwarding contract rather than the wallet that submitted the outer transaction.

Keep the handler small and safe to reconcile more than once. Identify outcomes by pool and listing ID. Receiver return data is ignored, and guarded pool settlement functions cannot be called again from inside the callback. Ordinary collection listings do not receive the dedicated FWAIR accounting receipt.