ExternalControlListManagement

Asset Tokenization Studio Team

ExternalControlListManagement

Abstract contract implementing external onlyOperational control list management logic for a security token. Maintains a list of trusted third-party control list contracts whose authorisation results are consulted during transfer compliance checks.

Implements IExternalControlListManagement. The external onlyOperational control list is stored in diamond storage at STORAGE_LOCATION_CONTROL_LIST_MANAGEMENT via ExternalListManagementStorageWrapper. All mutating functions after initialisation are gated by ROLE_CONTROL_LIST_MANAGER and the onlyUnpaused modifier inherited from Modifiers. Intended to be inherited exclusively by ExternalControlListManagementFacet.

Methods

addExternalControlList

function addExternalControlList(address _controlList) external nonpayable returns (bool success_)

Adds an external control list contract to the list.

Requires ROLE_CONTROL_LIST_MANAGER, the token to be unpaused, and a non-zero address. Reverts with ListedControlList if the address is already listed. Emits AddedToExternalControlLists.

Parameters

Name	Type	Description
_controlList	address	Address of the external control list contract to add.

Returns

Name	Type	Description
success_	bool	True if the contract was added successfully.

getExternalControlListsCount

function getExternalControlListsCount() external view returns (uint256 externalControlListsCount_)

Returns the total number of external control list contracts in the list.

Returns

Name	Type	Description
externalControlListsCount_	uint256	The current number of listed external control list contracts.

getExternalControlListsMembers

function getExternalControlListsMembers(uint256 _pageIndex, uint256 _pageLength) external view returns (address[] members_)

Returns a paginated slice of the external control list contract list.

_The list offset is computed as \_pageIndex _ \_pageLength. Returns an empty array when the offset meets or exceeds the list length.*

Parameters

Name	Type	Description
_pageIndex	uint256	Zero-based page index.
_pageLength	uint256	Maximum number of addresses to return per page.

Returns

Name	Type	Description
members_	address[]	Array of external control list contract addresses for the requested page.

initializeExternalControlLists

function initializeExternalControlLists(address[] _controlLists) external nonpayable

One-time initialiser that populates the external control list at token deployment.

Can only be called once; subsequent calls revert via onlyFacetNotRegistered. The leading-underscore naming convention signals this is an initialiser function.

Parameters

Name	Type	Description
_controlLists	address[]	Initial array of external control list contract addresses to register.

isExternalControlList

function isExternalControlList(address _controlList) external view returns (bool)

Checks whether an address is present in the external control list.

Parameters

Name	Type	Description
_controlList	address	Address to check.

Returns

Name	Type	Description
_0	bool	True if the address is a listed external control list contract, false otherwise.

removeExternalControlList

function removeExternalControlList(address _controlList) external nonpayable returns (bool success_)

Removes an external control list contract from the list.

Requires ROLE_CONTROL_LIST_MANAGER and the token to be unpaused. Reverts with UnlistedControlList if the address is not listed. Emits RemovedFromExternalControlLists.

Parameters

Name	Type	Description
_controlList	address	Address of the external control list contract to remove.

Returns

Name	Type	Description
success_	bool	True if the contract was removed successfully.

updateExternalControlLists

function updateExternalControlLists(address[] _controlLists, bool[] _actives) external nonpayable returns (bool success_)

Adds or removes multiple external control list contracts in a single transaction.

Requires ROLE_CONTROL_LIST_MANAGER and the token to be unpaused. Both arrays must have the same length and contain no duplicate addresses, validated by ArrayValidation.checkUniqueValues. Emits ExternalControlListsUpdated.

Parameters

Name	Type	Description
_controlLists	address[]	Array of external control list contract addresses to process.
_actives	bool[]	Corresponding flags; true adds the address to the list, false removes it.

Returns

Name	Type	Description
success_	bool	True if the batch update completed successfully.

Events

AddedToExternalControlLists

event AddedToExternalControlLists(address indexed operator, address controlList)

Emitted when an external control list contract is added to the list.

Parameters

Name	Type	Description
operator indexed	address	Address of the caller who performed the addition.
controlList	address	Address of the external control list contract that was added.

ExternalControlListInitialized

event ExternalControlListInitialized(address[] controlLists)

Emitted once when the external control list capability is initialised on a token.

Fires exclusively from initializeExternalControlLists after the storage write succeeds.

Parameters

Name	Type	Description
controlLists	address[]	The initial array of external control list contract addresses registered.

ExternalControlListsUpdated

event ExternalControlListsUpdated(address indexed operator, address[] controlLists, bool[] actives)

Emitted when multiple external control list addresses are added or removed in a single batch.

Parameters

Name	Type	Description
operator indexed	address	Address of the caller who performed the update.
controlLists	address[]	Array of external control list contract addresses that were processed.
actives	bool[]	Corresponding activation flags; true means added, false means removed.

RemovedFromExternalControlLists

event RemovedFromExternalControlLists(address indexed operator, address controlList)

Emitted when an external control list contract is removed from the list.

Parameters

Name	Type	Description
operator indexed	address	Address of the caller who performed the removal.
controlList	address	Address of the external control list contract that was removed.

Errors

AccountHasNoRole

error AccountHasNoRole(address account, bytes32 role)

Thrown when an account does not hold a required role.

Parameters

Name	Type	Description
account	address	The account that lacks the role.
role	bytes32	The role that is not held.

AssetNotOperational

error AssetNotOperational(bytes32 configId, uint256 versionId)

Raised by InitializerStorageWrapper.checkOperational (and the related isConfigVersionOperational helper) when an operation is attempted on a configuration version that has not yet been marked operational.

Parameters

Name	Type	Description
configId	bytes32	Resolver-proxy configuration whose operational status was checked.
versionId	uint256	Configuration version whose operational status was checked.

ContradictoryValuesInArray

error ContradictoryValuesInArray(uint256 lowerIndex, uint256 upperIndex)

Reverts when ordered array values contradict expected ordering.

Indicates that two indexed values cannot both satisfy the required monotonic or range invariant.

Parameters

Name	Type	Description
lowerIndex	uint256	Lower array index involved in the contradiction.
upperIndex	uint256	Upper array index involved in the contradiction.

Deactivated

error Deactivated()

Thrown when an operation guarded by onlyActivated is attempted on a token whose deactivation flag has already been set.

FacetAlreadyRegistered

error FacetAlreadyRegistered(bytes32 facetId, uint256 lastVersion)

Raised when an initialiser tries to register a facet that already has a non-zero last registered version (i.e. the facet is being re-initialised on a fresh install).

Parameters

Name	Type	Description
facetId	bytes32	Identifier of the offending facet.
lastVersion	uint256	Last version recorded for that facet at the time of the check.

IsPaused

error IsPaused()

Thrown when an operation that requires the token to be unpaused is attempted while the token is paused (own flag or any external pause contract).

ListedControlList

error ListedControlList(address controlList)

Thrown when attempting to add an address already present in the external control list.

Parameters

Name	Type	Description
controlList	address	The duplicate external control list contract address.

MaxExternalListSizeReached

error MaxExternalListSizeReached(uint256 max)

Reverts when adding an entry would grow an external list beyond its maximum size.

Enforced by ExternalListManagementStorageWrapper.addExternalList for the external pause, control and KYC lists. The bound exists because each list is iterated in full on the hot path of token operations, so an unbounded list could exceed the gas limit and brick the token.

Parameters

Name	Type	Description
max	uint256	Maximum number of entries permitted in the external list.

UnexpectedError

error UnexpectedError(bytes4 _errorId)

Reverts when an unreachable validation state is detected.

Replaces assertions for defensive handling of logically impossible states.

Parameters

Name	Type	Description
_errorId	bytes4	Identifier of the unexpected validation condition.

UnlistedControlList

error UnlistedControlList(address controlList)

Thrown when attempting to remove an address not present in the external control list.

Parameters

Name	Type	Description
controlList	address	The unlisted external control list contract address.

UnrecognizedResolverProxyVersion

error UnrecognizedResolverProxyVersion(bytes8 _resolverProxyVersion)

Thrown when the provided proxy version does not match any BLR compatible standard.

Parameters

Name	Type	Description
_resolverProxyVersion	bytes8	proxy version that is not compatible with the BLR.

WalletRecovered

error WalletRecovered()

Thrown when attempting to recover a wallet that has already been recovered.

ZeroAddressNotAllowed

error ZeroAddressNotAllowed()

Reverts when the zero address is supplied where it is not permitted.

Prevents invalid account, contract, or recipient references.