Settings Registry

Payment Processor v3.0.0 introduces a new way of managing a collection's settings, through the CollectionSettingsRegistry contract (Settings Registry). Settings Registry is a central registry contract that will be shared across future versions of Payment Processor v3.X.

The simplest way to manage your collection's settings is through developers.apptokens.com.

For creators that would like to build their own integrations for managing collection settings - the sections below describe the functions and parameters that Payment Processor uses to apply rules to collection orders.

Account Freezing

With the update to Payment Processor v3.0.0, the account freezing functions have been moved to the Creator Token Transfer Validator to prevent exploits via contracts or other forms of transfer validator circumvention. To set the frozen account list, see the documentation for Creator Token Standards v3.

Settings Registry Functions

createPaymentMethodWhitelist

Callable by any account to create a new payment method whitelist. The whitelist will be owned by the address that calls the function.

/**
 * @notice Allows any user to create a new custom payment method whitelist.
 *
 * @dev    <h4>Postconditions:</h4>
 * @dev    1. The payment method whitelist id tracker has been incremented by `1`.
 * @dev    2. The caller has been assigned as the owner of the payment method whitelist.
 * @dev    3. A `CollectionSettingsRegistry__CreatedPaymentMethodWhitelist` event has been emitted.
 *
 * @param  whitelistName             The name of the payment method whitelist.
 * @return paymentMethodWhitelistId  The id of the newly created payment method whitelist.
 */
function createPaymentMethodWhitelist(
    string calldata whitelistName
) external returns (uint32 paymentMethodWhitelistId);

reassignOwnershipOfPaymentMethodWhitelist

Callable by the owner of the whitelist to assign ownership of the whitelist to a new account.

/**
 * @notice Transfer ownership of a payment method whitelist list to a new owner.
 *
 * @dev Throws when the new owner is the zero address.
 * @dev Throws when the caller does not own the specified list.
 *
 * @dev <h4>Postconditions:</h4>
 *      1. The payment method whitelist list ownership is transferred to the new owner.
 *      2. A `ReassignedPaymentMethodWhitelistOwnership` event is emitted.
 *
 * @param id       The id of the payment method whitelist.
 * @param newOwner The address of the new owner.
 */
function reassignOwnershipOfPaymentMethodWhitelist(
    uint32 id, 
    address newOwner
) external;

renounceOwnershipOfPaymentMethodWhitelist

Callable by the owner of the whitelist to renounce ownership of the whitelist. Whitelists with the owner renounced are immutable and can not be modified.

/**
 * @notice Renounce the ownership of a payment method whitelist, rendering the list immutable.
 *
 * @dev Throws when the caller does not own the specified list.
 *
 * @dev <h4>Postconditions:</h4>
 *      1. The ownership of the specified payment method whitelist is renounced.
 *      2. A `ReassignedPaymentMethodWhitelistOwnership` event is emitted.
 *
 * @param id The id of the payment method whitelist.
 */
function renounceOwnershipOfPaymentMethodWhitelist(uint32 id) external;

whitelistPaymentMethod

Callable by the owner of the whitelist to add a new payment method.

/**
 * @notice Allows custom payment method whitelist owners to approve a new coin for use as a payment currency.
 *
 * @dev    Throws when caller is not the owner of the specified payment method whitelist.
 * @dev    Throws when the specified coin is already whitelisted under the specified whitelist id.
 *
 * @dev    <h4>Postconditions:</h4>
 * @dev    1. `paymentMethod` has been approved in `paymentMethodWhitelist` mapping.
 * @dev    2. A `PaymentMethodAddedToWhitelist` event has been emitted.
 *
 * @param  paymentMethodWhitelistId The id of the payment method whitelist to update.
 * @param  paymentMethods           The address of the payment method to whitelist.
 */
function whitelistPaymentMethod(
    uint32 paymentMethodWhitelistId, 
    address[] calldata paymentMethods,
    address[] calldata paymentProcessorsToSync
) external;

unwhitelistPaymentMethod

Callable by the owner of the whitelist to remove a payment method.

/**
 * @notice Allows custom payment method whitelist owners to remove a coin from the list of approved payment 
 *         currencies.
 *
 * @dev    Throws when caller is not the owner of the specified payment method whitelist.
 * @dev    Throws when the specified coin is not currently whitelisted under the specified whitelist id.
 *
 * @dev    <h4>Postconditions:</h4>
 * @dev    1. `paymentMethod` has been removed from the `paymentMethodWhitelist` mapping.
 * @dev    2. A `CollectionSettingsRegistry__PaymentMethodRemovedFromWhitelist` event has been emitted.
 *
 * @param  paymentMethodWhitelistId  The id of the payment method whitelist to update.
 * @param  paymentMethods             The address of the payment method to unwhitelist.
 */
function unwhitelistPaymentMethod(
    uint32 paymentMethodWhitelistId, 
    address[] calldata paymentMethods,
    address[] calldata paymentProcessorsToSync
) external;

syncRemovedPaymentMethodsFromWhitelist

Callable by any user. This function will force a sync of the removed payment methods from a whitelist.

/**
 * @notice Forces sync of removed payment methods from the whitelist. This is unowned to allow for anyone to trigger updates of removed payment methods.
 *
 * @dev    Leaving this unowned allows for anyone to trigger the removal of payment methods from the whitelist.
 * @dev    If there is an issue with a payment method, this allows for a quick removal from all payment processors.
 * @dev    Throws when the specified payment method is still whitelisted under the specified whitelist id.
 * 
 * @dev    <h4>Postconditions:</h4>
 * @dev    1. `paymentMethod` has been removed from each payment processor in the `paymentProcessorsToSync` array.
 * @dev    2. X * Y `PaymentMethodRemovedFromWhitelist` events have been emitted where X is the number of payment methods and Y is the number of payment processors to sync.
 *
 * @param  paymentMethodWhitelistId   The id of the payment method whitelist to update.
 * @param  paymentMethods             An array of payment method addresses to remove.
 * @param  paymentProcessorsToSync    An array of the payment processors to sync the removal with.
 */
function syncRemovedPaymentMethodsFromWhitelist(
    uint32 paymentMethodWhitelistId, 
    address[] calldata paymentMethods,
    address[] calldata paymentProcessorsToSync
) external;

addTrustedPermitProcessors

Callable by the owner of the default payment method whitelist to add a new permit processor instance.

/**
 * @notice Allows the trusted permit processor list owner to add a new trusted permit processor and sync.
 *
 * @dev    Throws when caller is not the owner of the trusted permit processor list.
 *
 * @dev    <h4>Postconditions:</h4>
 * @dev    1. `trustedPermitProcessor` has been approved in `_trustedPermitProcessors` list.
 * @dev    2. A `TrustedPermitProcessorAdded` event has been emitted.
 *
 * @param  permitProcessors           The addresses of trusted permit processors to add to the list.
 * @param  paymentProcessorsToSync    An array of the payment processors to sync the removal with.
 */
function addTrustedPermitProcessors(
    address[] calldata permitProcessors,
    address[] calldata paymentProcessorsToSync
) external;

removeTrustedPermitProcessors

Callable by the owner of the default payment method whitelist to remove a permit processor instance.

/**
 * @notice Allows the trusted permit processor list owner to remove a trusted permit processor and sync.
 *
 * @dev    Throws when caller is not the owner of the trusted permit processor list.
 *
 * @dev    <h4>Postconditions:</h4>
 * @dev    1. `trustedPermitProcessor` has been removed from the `_trustedPermitProcessors` list.
 * @dev    2. A `TrustedPermitProcessorRemoved` event has been emitted.
 *
 * @param  permitProcessors           The addresses of trusted permit processors to remove from the list.
 * @param  paymentProcessorsToSync    An array of the payment processors to sync the removal with.
 */
function removeTrustedPermitProcessors(
    address[] calldata permitProcessors,
    address[] calldata paymentProcessorsToSync
) external;

setCollectionPaymentSettings

Callable by the token contract, the owner of the token contract or any account assigned the default admin role for the token contract. This function will configure the payment settings rules to apply to all orders executed on Payment Processor.

/**
 * @notice Allows the smart contract, the contract owner, or the contract admin of any NFT collection to 
 *         specify the payment settings for their collections.
 *
 * @dev    Throws when the specified tokenAddress is address(0).
 * @dev    Throws when the caller is not the contract, the owner or the administrator of the specified tokenAddress.
 * @dev    Throws when the royalty backfill numerator is greater than 10,000.
 * @dev    Throws when the royalty bounty numerator is greater than 10,000.
 * @dev    Throws when the specified payment method whitelist id does not exist.
 * 
 * @dev    <h4>Postconditions:</h4>
 * @dev    1. The `PaymentSettings` type for the collection has been set.
 * @dev    2. The `paymentMethodWhitelistId` for the collection has been set, if applicable.
 * @dev    3. The `constrainedPricingPaymentMethod` for the collection has been set, if applicable.
 * @dev    4. The `royaltyBackfillNumerator` for the collection has been set.
 * @dev    5. The `royaltyBackfillReceiver` for the collection has been set.
 * @dev    6. The `royaltyBountyNumerator` for the collection has been set.
 * @dev    7. The `exclusiveBountyReceiver` for the collection has been set.
 * @dev    8. The `blockTradesFromUntrustedChannels` for the collection has been set.
 * @dev    8. An `UpdatedCollectionPaymentSettings` event has been emitted.
 *
 * @param  tokenAddress             The smart contract address of the NFT collection.
 * @param  params                   The payment settings parameters for the collection.
 * @param  dataExtensions           The data extensions to set.
 * @param  dataSettings             The data settings to set.
 * @param  wordExtensions           The word extensions to set.
 * @param  wordSettings             The word settings to set.
 * @param  paymentProcessorsToSync  An array of the payment processors to sync the removal with.
 */
function setCollectionPaymentSettings(
    address tokenAddress, 
    CollectionPaymentSettingsParams memory params,
    bytes32[] memory dataExtensions, 
    bytes[] memory dataSettings,
    bytes32[] memory wordExtensions,
    bytes32[] memory wordSettings,
    address[] calldata paymentProcessorsToSync
) external;

setTokenPricingBounds

Callable by the token contract, the owner of the token contract or any account assigned the default admin role for the token contract. This function sets the floor and ceiling price for specific tokens

/**
 * @notice Allows the smart contract, the contract owner, or the contract admin of any NFT collection to 
 *         specify their own bounded price at the individual token level.
 *
 * @dev    Throws when the specified tokenAddress is address(0).
 * @dev    Throws when the caller is not the contract, the owner or the administrator of the specified tokenAddress.
 * @dev    Throws when the lengths of the tokenIds and pricingBounds array don't match.
 * @dev    Throws when the tokenIds or pricingBounds array length is zero. 
 * @dev    Throws when the any of the specified floor prices is greater than the ceiling price for that token id.
 * 
 * @dev    <h4>Postconditions:</h4>
 * @dev    1. The token-level pricing bounds for the specified tokenAddress and token ids has been set.
 * @dev    2. An `UpdatedTokenLevelPricingBoundaries` event has been emitted.
 *
 * @param  tokenAddress             The smart contract address of the NFT collection.
 * @param  tokenIds                 An array of token ids for which pricing bounds are being set.
 * @param  pricingBounds            An array of pricing bounds used to set the floor and ceiling per token.
 * @param  paymentProcessorsToSync  An array of the payment processors to sync the removal with.
 */
function setTokenPricingBounds(
    address tokenAddress, 
    uint256[] calldata tokenIds, 
    RegistryPricingBounds[] calldata pricingBounds,
    address[] calldata paymentProcessorsToSync
) external;

addTrustedChannelForCollection

Callable by the token contract, the owner of the token contract or any account assigned the default admin role for the token contract. This function approves a series of channel to be allowed to execute orders for the collection when blockTradesFromUntrustedChannels is set to true in setCollectionPaymentSettings.

See Trusted Forwarder for more information on channels.

/**
 * @notice Allows trusted channels to be added to a collection.
 *
 * @dev    Throws when the specified tokenAddress is address(0).
 * @dev    Throws when the caller is not the contract, the owner or the administrator of the specified tokenAddress.
 * @dev    Throws when the specified address is not a trusted forwarder.
 *
 * @dev    <h4>Postconditions:</h4>
 * @dev    1. `channel` has been approved for trusted forwarding of trades on a collection.
 * @dev    2. A `TrustedChannelAddedForCollection` event has been emitted.
 *
 * @param  tokenAddress             The smart contract address of the NFT collection.
 * @param  channels                 The smart contract address of the trusted channel.
 * @param  paymentProcessorsToSync  An array of the payment processors to sync the addition with.
 */
function addTrustedChannelForCollection(
    address tokenAddress, 
    address[] calldata channels,
    address[] calldata paymentProcessorsToSync
) external;

removeTrustedChannelForCollection

Callable by the token contract, the owner of the token contract or any account assigned the default admin role for the token contract. This function removes a series of channels from the approval to execute orders for the collection when blockTradesFromUntrustedChannels is set to true in setCollectionPaymentSettings.

See Trusted Forwarder for more information on channels.

/**
 * @notice Allows trusted channels to be removed from a collection.
 *
 * @dev    Throws when the specified tokenAddress is address(0).
 * @dev    Throws when the caller is not the contract, the owner or the administrator of the specified tokenAddress.
 *
 * @dev    <h4>Postconditions:</h4>
 * @dev    1. `channel` has been dis-approved for trusted forwarding of trades on a collection.
 * @dev    2. A `TrustedChannelRemovedForCollection` event has been emitted.
 *
 * @param  tokenAddress             The smart contract address of the NFT collection.
 * @param  channels                 The smart contract address of the trusted channel to remove.
 * @param  paymentProcessorsToSync  The payment processors to sync with.
 */
function removeTrustedChannelForCollection(
    address tokenAddress, 
    address[] calldata channels,
    address[] calldata paymentProcessorsToSync
) external;

Data Structures

RegistryPricingBounds

isSet	floorPrice	ceilingPrice
bool	uint120	uint120

• isSet: Boolean true/false flag to indicate the pricing bounds have been set. Distinguishes set zero-value bounds from unset bounds that have default values of zero in the storage slot.
• floorPrice: Minimum value to accept for a sales price without rejecting the sale.
• ceilingPrice: Maximum value to accept for a sales price without rejecting the sale.

struct RegistryPricingBounds {
    bool isSet;
    uint120 floorPrice;
    uint120 ceilingPrice;
}

CollectionPaymentSettingsParams

paymentSettings	paymentMethodWhitelistId	constrainedPricingPaymentMethod	royaltyBackfillNumerator	royaltyBackfillReceiver	royaltyBountyNumerator	exclusiveBountyReceiver	extraData	collectionMinimumFloorPrice	collectionMaximumCeilingPrice
uint8	uint32	address	uint16	address	uint16	address	uint16	uint120	uint120

• paymentSettings: The payment settings for the collection.
• paymentMethodWhitelistId: The ID of the payment method whitelist to use for the collection.
• constrainedPricingPaymentMethod: The payment method to use for constrained pricing.
• royaltyBackfillNumerator: The numerator to use for the royalty backfill.
• royaltyBackfillReceiver: The address to use as the royalty backfill receiver.
• royaltyBountyNumerator: The numerator to use for the royalty bounty.
• exclusiveBountyReceiver: The address to use as the exclusive bounty receiver.
• extraData: Extra data for the payment settings. The first 8 bits of this data contains the SettingsRegistry Flags.
• gasLimitOverride: The gas limit override for the collection.
• collectionMinimumFloorPrice: The minimum floor price for the collection.
• collectionMaximumCeilingPrice: The maximum ceiling price for the collection.

CollectionRegistryPaymentSettings

initialized	paymentSettingsType	paymentMethodWhitelistId	royaltyBackfillReceiver	royaltyBackfillNumerator	royaltyBountyNumerator	extraData
bool	uint8	uint32	address	uint16	uint16	uint16

• initialized: True if the payment settings have been initialized, false otherwise.
• paymentSettingsType: The type of payment settings for the collection.
• paymentMethodWhitelistId: The ID of the payment method whitelist to use for the collection.
• royaltyBackfillReceiver: The address to use as the royalty backfill receiver.
• royaltyBackfillNumerator: The numerator to use for the royalty backfill.
• royaltyBountyNumerator: The numerator to use for the royalty bounty.
• extraData: Extra data for the payment settings. The first 8 bits of this data contains the SettingsRegistry Flags.

Settings Registry Flags

In Payment Processor V3.0.0, flags are used to efficiently store and retreive boolean values in a single uint8. These flags are stored in the _collectionPaymentSettings mapping as CollectionRegistryPaymentSettings.extraData.

uint8 constant FLAG_IS_ROYALTY_BOUNTY_EXCLUSIVE = 1 << 0;
uint8 constant FLAG_BLOCK_TRADES_FROM_UNTRUSTED_CHANNELS = 1 << 1;
uint8 constant FLAG_USE_BACKFILL_AS_ROYALTY_SOURCE = 1 << 2;

Flags are stored in a single uint8 which uninitialized looks like 0000000000000000. When utilizing flags, bit shifts are used to mask the value. For example, FLAG_IS_ROYALTY_BOUNTY_EXCLUSIVE == 1 << 0 which would set the uint8 to 0000000000000001.

To check the whether a flag is set, we can use bitwise AND (&). For example, if we want to check if FLAG_IS_ROYALTY_BOUNTY_EXCLUSIVE is set, you would use: if (flags & FLAG_IS_ROYALTY_BOUNTY_EXCLUSIVE != 0).

Exclusive Royalty Bounty Flag

The exclusive royalty bounty flag is used to indicate whether an exclusive marketplace has been designated as eligible to receive a royalty bounty. If the flag is set, only the address eligible to receive a royalty bounty is the address set in collectionExclusiveBountyReceivers[tokenAddress].

Block Trades From Untrusted Channels Flag

The block trades from untrested channels flag is used to indicate whether trades originating from non-permissioned channels should be reverted. If the flag is set, all trades will be checked against collectionTrustedChannels[tokenAddress]. If the originator is not registered as a trusted channel for the token contract address, the trade will be reverted.

Use Backfill As Royalty Source Flag

The use backfill as royalty source flag is used to indicate whether a royalty source should be backfilled. If a token contract is not ERC2981 compliant, creators can set backfilled royalty to ensure that royalties are honored on any trade flow that occurs through Payment Processor.