IHoldFacet
Asset Tokenization Studio Team
IHoldFacet
Interface for the high-level, partition-agnostic hold read accessors.
Defines the read surface of the HoldFacet diamond facet: the aggregate held balance for an account and the third party registered on a specific hold. Partition-scoped accessors remain on IHoldByPartition. Implementations are expected to honour TimeTravelStorageWrapper for adjusted balance reads so results stay consistent under time-travel tests.
Methods
getHeldAmountFor
function getHeldAmountFor(address _tokenHolder) external view returns (uint256 amount_)
Returns the adjusted held amount for an account across every partition.
The returned value reflects any balance adjustments applicable at the current timestamp.
Parameters
| Name | Type | Description |
|---|---|---|
| _tokenHolder | address | Address whose aggregate held balance is queried. |
Returns
| Name | Type | Description |
|---|---|---|
| amount_ | uint256 | Sum of held balances across all partitions, adjusted to the current timestamp. |
getHoldThirdParty
function getHoldThirdParty(IHoldTypes.HoldIdentifier _holdIdentifier) external view returns (address thirdParty_)
Parameters
| Name | Type | Description |
|---|---|---|
| _holdIdentifier | IHoldTypes.HoldIdentifier | undefined |
Returns
| Name | Type | Description |
|---|---|---|
| thirdParty_ | address | undefined |
initializeHold
function initializeHold() external nonpayable
Initialises the hold capability on the token.
Callable once; subsequent calls revert with FacetAlreadyRegistered. Requires DEFAULT_ADMIN_ROLE. Called by the factory during deployment.
Events
ControllerHeldByPartition
event ControllerHeldByPartition(address indexed operator, address indexed tokenHolder, bytes32 partition, uint256 holdId, IHoldTypes.Hold hold, bytes operatorData)
Emitted when a controller creates a hold on a holder's behalf.
Parameters
| Name | Type | Description |
|---|---|---|
operator indexed | address | The controller initiating the hold. |
tokenHolder indexed | address | The holder whose balance is being held. |
| partition | bytes32 | Partition over which the hold is placed. |
| holdId | uint256 | Sequence id assigned to the hold. |
| hold | IHoldTypes.Hold | The hold definition. |
| operatorData | bytes | Operator-supplied metadata. |
HeldByPartition
event HeldByPartition(address indexed operator, address indexed tokenHolder, bytes32 partition, uint256 holdId, IHoldTypes.Hold hold, bytes operatorData)
Emitted when a holder creates a hold over its own partitioned balance.
Parameters
| Name | Type | Description |
|---|---|---|
operator indexed | address | The address that initiated the hold (the holder itself). |
tokenHolder indexed | address | The holder whose balance is being held. |
| partition | bytes32 | Partition over which the hold is placed. |
| holdId | uint256 | Sequence id assigned to the hold. |
| hold | IHoldTypes.Hold | The hold definition (escrow, recipient, expiration, amount, data). |
| operatorData | bytes | Operator-supplied metadata. |
HeldFromByPartition
event HeldFromByPartition(address indexed operator, address indexed tokenHolder, bytes32 partition, uint256 holdId, IHoldTypes.Hold hold, bytes operatorData)
Emitted when an authorised third party creates a hold on a holder's behalf.
Parameters
| Name | Type | Description |
|---|---|---|
operator indexed | address | The third-party caller initiating the hold. |
tokenHolder indexed | address | The holder whose balance is being held. |
| partition | bytes32 | Partition over which the hold is placed. |
| holdId | uint256 | Sequence id assigned to the hold. |
| hold | IHoldTypes.Hold | The hold definition (escrow, recipient, expiration, amount, data). |
| operatorData | bytes | Operator-supplied metadata. |
HoldByPartitionExecuted
event HoldByPartitionExecuted(address indexed tokenHolder, bytes32 indexed partition, uint256 holdId, uint256 amount, address to)
Emitted when an existing hold is executed and balance transferred to a recipient.
Parameters
| Name | Type | Description |
|---|---|---|
tokenHolder indexed | address | The holder whose hold was executed. |
partition indexed | bytes32 | Partition over which the hold lived. |
| holdId | uint256 | Sequence id of the executed hold. |
| amount | uint256 | Amount released to the recipient. |
| to | address | Recipient of the executed balance. |
HoldByPartitionReclaimed
event HoldByPartitionReclaimed(address indexed operator, address indexed tokenHolder, bytes32 indexed partition, uint256 holdId, uint256 amount)
Emitted when an expired hold is reclaimed by the holder.
Parameters
| Name | Type | Description |
|---|---|---|
operator indexed | address | The address that triggered the reclaim. |
tokenHolder indexed | address | The holder receiving the reclaimed balance. |
partition indexed | bytes32 | Partition over which the hold lived. |
| holdId | uint256 | Sequence id of the reclaimed hold. |
| amount | uint256 | Amount returned to the holder's available balance. |
HoldByPartitionReleased
event HoldByPartitionReleased(address indexed tokenHolder, bytes32 indexed partition, uint256 holdId, uint256 amount)
Emitted when a hold is partially or fully released back to the holder.
Parameters
| Name | Type | Description |
|---|---|---|
tokenHolder indexed | address | The holder receiving the released balance. |
partition indexed | bytes32 | Partition over which the hold lived. |
| holdId | uint256 | Sequence id of the released hold. |
| amount | uint256 | Amount returned to the holder's available balance. |
HoldInitialized
event HoldInitialized()
Emitted once when the hold capability is initialised on a token.
Fires exclusively from initializeHold.
OperatorHeldByPartition
event OperatorHeldByPartition(address indexed operator, address indexed tokenHolder, bytes32 partition, uint256 holdId, IHoldTypes.Hold hold, bytes operatorData)
Emitted when an ERC-1410 operator creates a hold on a holder's behalf.
Parameters
| Name | Type | Description |
|---|---|---|
operator indexed | address | The authorised operator initiating the hold. |
tokenHolder indexed | address | The holder whose balance is being held. |
| partition | bytes32 | Partition over which the hold is placed. |
| holdId | uint256 | Sequence id assigned to the hold. |
| hold | IHoldTypes.Hold | The hold definition. |
| operatorData | bytes | Operator-supplied metadata. |
ProtectedHeldByPartition
event ProtectedHeldByPartition(address indexed operator, address indexed tokenHolder, bytes32 partition, uint256 holdId, IHoldTypes.Hold hold, bytes operatorData)
Emitted when a protected hold authorised by an EIP-712 signature is created.
Parameters
| Name | Type | Description |
|---|---|---|
operator indexed | address | The address submitting the protected hold (signature relayer). |
tokenHolder indexed | address | The holder whose balance is being held; must match the signer. |
| partition | bytes32 | Partition over which the hold is placed. |
| holdId | uint256 | Sequence id assigned to the hold. |
| hold | IHoldTypes.Hold | The hold definition. |
| operatorData | bytes | Operator-supplied metadata. |
Errors
HoldExpirationNotReached
error HoldExpirationNotReached()
Reverts when a reclaim is attempted before the hold's expiration timestamp.
HoldExpirationReached
error HoldExpirationReached()
Reverts when an operation requires an unexpired hold but the hold has expired.
InsufficientHoldBalance
error InsufficientHoldBalance(uint256 holdAmount, uint256 amount)
Reverts when the requested release amount exceeds the hold's remaining balance.
Parameters
| Name | Type | Description |
|---|---|---|
| holdAmount | uint256 | The amount still held. |
| amount | uint256 | The amount requested. |
InvalidDestinationAddress
error InvalidDestinationAddress(address holdDestination, address to)
Reverts when the recipient supplied to {executeHoldByPartition} mismatches the hold.
Parameters
| Name | Type | Description |
|---|---|---|
| holdDestination | address | The recipient stored on the hold. |
| to | address | The recipient supplied to the execute call. |
InvalidHoldAmount
error InvalidHoldAmount()
Reverts when a hold is created with a zero or otherwise invalid amount.
IsNotEscrow
error IsNotEscrow()
Reverts when a caller that is not the recorded escrow attempts to execute the hold.
WrongHoldId
error WrongHoldId()
Reverts when the supplied hold id does not exist for the (partition, holder) pair.