Unlocker¶
ITTUnlocker¶
Interface for TTUnlocker, which unlocks and distributes tokens for TokenTable.
This page describes version 2.7.7. The implementation is TTUnlocker, whose version() returns 2.7.7-TTUnlocker followed by the EVM suffix of the build (for example 2.7.7-TTUnlocker-cancun). In npm package 2.7.0 the same interface is called ITokenTableUnlockerV2 and the implementation TokenTableUnlockerV2.
ITTUnlocker extends IVersionable. Ownership is not part of the interface: TTUnlocker uses Solady's Ownable, described under Ownership. Functions marked "Only callable by the owner" revert with Unauthorized() for any other caller.
PresetCreated¶
ActualCreated¶
event ActualCreated(bytes32 presetId, uint256 actualId, address recipient, uint256 recipientId, uint256 batchId)
ActualCancelled¶
event ActualCancelled(uint256 actualId, uint256 pendingAmountClaimable, bool didWipeClaimableBalance, uint256 batchId)
TokensClaimed¶
event TokensClaimed(uint256 actualId, address caller, address to, uint256 amount, uint256 feesCharged, uint256 batchId)
TokensWithdrawn¶
ClaimingDelegateSet¶
CreateDisabled¶
CancelDisabled¶
HookDisabled¶
WithdrawDisabled¶
InvalidPresetFormat¶
0x0ef8e8dc
PresetExists¶
0x7cbb15b4
PresetDoesNotExist¶
0xbd88ff7b
ActualDoesNotExist¶
0x6aed3166
ActualExists¶
0x0cbf932d
Thrown by TTUnlockerExternalFT when an actual already exists for the given actualId.
InvalidSkipAmount¶
0x78c0fc43
NotPermissioned¶
0x7f63bd0f
AlreadyWithdrawable¶
0x2fac9032
initialize¶
function initialize(address projectToken, address futureToken_, address deployer_, bool isCancelable_, bool isHookable_, bool isWithdrawable_) external virtual
Deploy this contract with TTUDeployer, which calls this function with the correct parameters.
The caller of initialize becomes the owner. TTUDeployer then transfers ownership to the address that called deployTTSuite.
Parameters¶
| Name | Type | Description |
|---|---|---|
| projectToken | address | The address of the token that the founder intends to unlock and distribute. |
| futureToken_ | address | The address of the associated FutureToken. |
| deployer_ | address | The address of the deployer, used to reach the fee collector during claims. |
| isCancelable_ | bool | Whether the founder can cancel schedules. Can be disabled later but not re-enabled. |
| isHookable_ | bool | Whether the founder can attach external hooks to function calls. Can be disabled later but not re-enabled. |
| isWithdrawable_ | bool | Whether the founder can withdraw deposited tokens. Can be disabled later but not re-enabled. |
createPresets¶
function createPresets(bytes32[] presetIds, struct Preset[] presets, uint256 batchId, bytes extraData) external virtual
Creates preset unlocking schedule templates.
Emits PresetCreated. Only callable by the owner.
Reverts with PresetExists if an ID is already used, and with InvalidPresetFormat if an ID is zero or a preset fails validation (see Presets and Actuals).
Parameters¶
| Name | Type | Description |
|---|---|---|
| presetIds | bytes32[] | Any nonzero values, for example hashes of plaintext preset names. Reverts if an ID already exists. |
| presets | struct Preset[] | An array of Preset structs. |
| batchId | uint256 | Only emitted in an event, for EthSign frontend use. Has no effect on contract execution. |
| extraData | bytes | An ERC-5750 parameter passed directly to the hook. |
createActuals¶
function createActuals(address[] recipients, struct Actual[] actuals, uint256[] recipientIds, uint256 batchId, bytes extraData) external virtual
Creates actual unlocking schedules based on presets.
Emits ActualCreated. Mints a FutureToken with tokenId == actualId for each actual.
Only callable by the owner. Reverts with NotPermissioned after disableCreate(), with PresetDoesNotExist if the preset is missing, and with InvalidSkipAmount if amountClaimed is not less than totalAmount.
Parameters¶
| Name | Type | Description |
|---|---|---|
| recipients | address[] | The token recipients of the schedules. Transferring a schedule's FutureToken changes who can claim from it. |
| actuals | struct Actual[] | An array of Actual structs. |
| recipientIds | uint256[] | Only emitted in an event, for EthSign frontend use. Has no effect on contract execution. |
| batchId | uint256 | Only emitted in an event, for EthSign frontend use. Has no effect on contract execution. |
| extraData | bytes | An ERC-5750 parameter passed directly to the hook. |
withdrawDeposit¶
Withdraws deposited tokens from the contract.
Emits TokensWithdrawn. Only callable by the owner.
Reverts with NotPermissioned unless withdrawals are enabled (isWithdrawable()) or the deployer has approved an emergency withdraw request (see setEmergencyWithdrawRequestStatus). An approval is consumed by one call.
Parameters¶
| Name | Type | Description |
|---|---|---|
| amount | uint256 | The amount of deposited tokens to withdraw. |
| extraData | bytes | An ERC-5750 parameter passed directly to the hook. |
claim¶
function claim(uint256[] actualIds, address[] claimTos, uint256 batchId, bytes extraData) external virtual
Claims the claimable tokens of the given schedules and sends them to the matching addresses.
Emits TokensClaimed. Only callable by the FutureToken owner.
If the deployer has a fee collector, the Unlocker also transfers the fee, in the project token, from its own balance to the fee collector's owner.
Parameters¶
| Name | Type | Description |
|---|---|---|
| actualIds | uint256[] | The IDs of the unlocking schedules to claim from. |
| claimTos | address[] | Where to send the claimed tokens of each schedule. Pass ethers.constants.AddressZero to send them to the caller (the default). |
| batchId | uint256 | Only emitted in an event, for EthSign frontend use. Has no effect on contract execution. |
| extraData | bytes | An ERC-5750 parameter passed directly to the hook. |
delegateClaim¶
Claims the claimable tokens of the given schedules on behalf of their recipients.
Emits TokensClaimed. Only callable by a claiming delegate.
If currentChainSupportsExternalDelegateRegistry() is true, an address that the FutureToken owner has delegated to through delegate.xyz can also call this function. Claimed tokens go to the current owner of each FutureToken.
Parameters¶
| Name | Type | Description |
|---|---|---|
| actualIds | uint256[] | The IDs of the unlocking schedules to claim from on behalf of their recipients. |
| batchId | uint256 | Only emitted in an event, for EthSign frontend use. Has no effect on contract execution. |
| extraData | bytes | An ERC-5750 parameter passed directly to the hook. |
cancel¶
function cancel(uint256[] actualIds, bool[] shouldWipeClaimableBalance, uint256 batchId, bytes extraData) external virtual returns (uint256[] pendingAmountClaimables)
Cancels the given unlocking schedules, effective immediately. Tokens that are already unlocked but not yet claimed are tallied.
Emits ActualCancelled. Only callable by the owner.
Reverts with NotPermissioned after disableCancel() or if the suite was deployed with isCancelable set to false.
Parameters¶
| Name | Type | Description |
|---|---|---|
| actualIds | uint256[] | The IDs of the actual unlocking schedules to cancel. |
| shouldWipeClaimableBalance | bool[] | Whether to wipe the unlocked, claimable balance of the canceled schedule. Use this to delete a schedule that was created by mistake and has already started unlocking. |
| batchId | uint256 | Only emitted in an event, for EthSign frontend use. Has no effect on contract execution. |
| extraData | bytes | An ERC-5750 parameter passed directly to the hook. |
Return Values¶
| Name | Type | Description |
|---|---|---|
| pendingAmountClaimables | uint256[] | The number of tokens each affected stakeholder can claim at the moment of cancellation. |
setHook¶
Sets the hook contract.
Only callable by the owner.
Reverts with NotPermissioned if hooks are disabled.
Parameters¶
| Name | Type | Description |
|---|---|---|
| hook | contract ITTHook | The address of the ITTHook hook contract. |
setClaimingDelegate¶
Adds or removes a claiming delegate, who can trigger claims on behalf of recipients.
Only callable by the owner.
Parameters¶
| Name | Type | Description |
|---|---|---|
| delegate | address | The claiming delegate address. |
| status | bool | Whether to add (true) or revoke (false) the delegate. |
setCurrentChainSupportsExternalDelegateRegistry¶
Sets whether the current chain supports delegate.xyz.
Only callable by the owner (enforced in the implementation).
Parameters¶
| Name | Type | Description |
|---|---|---|
| status | bool | Whether delegateClaim also accepts delegations registered in the delegate.xyz registry. |
disableCreate¶
Permanently disables the createActuals() function.
Only callable by the owner.
disableCancel¶
Permanently disables the cancel() function.
Only callable by the owner.
disableHook¶
Permanently disables the hook.
Only callable by the owner.
The current hook is called one last time before it is removed.
disableWithdraw¶
Permanently prevents the founder from withdrawing deposits.
Only callable by the owner.
setEmergencyWithdrawRequestStatus¶
Lets the owner request an emergency withdrawal of deposited tokens after withdrawals are disabled. The deployer must approve the request.
Only callable by the owner.
Reverts with AlreadyWithdrawable while withdrawals are still enabled. The request is forwarded to the deployer, whose owner approves or rejects it with handleEmergencyWithdrawRequest (see Deployer). Once approved, the next withdrawDeposit call succeeds and consumes the approval.
Parameters¶
| Name | Type | Description |
|---|---|---|
| status | bool | true to request an emergency withdraw, false to cancel the request. |
deployer¶
Return Values¶
| Name | Type | Description |
|---|---|---|
| [0] | address | The deployer instance associated with this Unlocker. |
futureToken¶
Return Values¶
| Name | Type | Description |
|---|---|---|
| [0] | address | The FutureToken instance associated with this Unlocker. |
hook¶
Return Values¶
| Name | Type | Description |
|---|---|---|
| [0] | contract ITTHook | The external hook associated with this Unlocker. |
claimingDelegates¶
Return Values¶
| Name | Type | Description |
|---|---|---|
| [0] | address[] | The claiming delegates, who can trigger claims on behalf of schedule recipients. |
isCreateable¶
Return Values¶
| Name | Type | Description |
|---|---|---|
| [0] | bool | Whether the founder can create new schedules. |
isCancelable¶
Return Values¶
| Name | Type | Description |
|---|---|---|
| [0] | bool | Whether the founder can cancel schedules. |
isHookable¶
Return Values¶
| Name | Type | Description |
|---|---|---|
| [0] | bool | Whether the founder can attach external hooks to function calls. |
isWithdrawable¶
Return Values¶
| Name | Type | Description |
|---|---|---|
| [0] | bool | Whether the founder can withdraw deposited but unclaimed tokens. |
pendingAmountClaimableForCancelledActuals¶
function pendingAmountClaimableForCancelledActuals(uint256 actualId) external view virtual returns (uint256)
Parameters¶
| Name | Type | Description |
|---|---|---|
| actualId | uint256 | The canceled schedule ID. |
Return Values¶
| Name | Type | Description |
|---|---|---|
| [0] | uint256 | The amount of tokens from the canceled schedule that unlocked but the stakeholder has not claimed. |
getEncodedPreset¶
To decode in JS, use:
ethers.utils.defaultAbiCoder.decode(
["uint256[]", "uint256", "uint256[]", "uint256[]", "bool"],
encodedPreset
);
Parameters¶
| Name | Type | Description |
|---|---|---|
| presetId | bytes32 | The ID of the preset to read. |
Return Values¶
| Name | Type | Description |
|---|---|---|
| [0] | bytes | An ABI-encoded Preset, because Solidity cannot return nested objects directly. |
actuals¶
Returns the Actual struct for the given ID.
getProjectToken¶
Return Values¶
| Name | Type | Description |
|---|---|---|
| [0] | address | The address of the project token that this Unlocker is associated with. |
BIPS_PRECISION¶
TTUnlocker implements this as the public constant BIPS_PRECISION = 10 ** 4 (10000, down to 0.01%).
Return Values¶
| Name | Type | Description |
|---|---|---|
| [0] | uint256 | The basis point precision of this Unlocker. |
currentChainSupportsExternalDelegateRegistry¶
Returns whether the current chain supports delegate.xyz.
calculateAmountClaimable¶
function calculateAmountClaimable(uint256 actualId) public view virtual returns (uint256 deltaAmountClaimable, uint256 updatedAmountClaimed)
Calculates the unlocked tokens not yet claimed in an actual unlocking schedule.
This is the most complex calculation in the contract.
Returns zeros for a canceled or nonexistent actual.
Parameters¶
| Name | Type | Description |
|---|---|---|
| actualId | uint256 | The ID of the actual unlocking schedule. |
Return Values¶
| Name | Type | Description |
|---|---|---|
| deltaAmountClaimable | uint256 | Amount of tokens claimable right now. |
| updatedAmountClaimed | uint256 | The new total amount claimed: all previously claimed tokens plus deltaAmountClaimable. |
simulateAmountClaimable¶
function simulateAmountClaimable(uint256 actualId, uint256 claimTimestampAbsolute) public view virtual returns (uint256 deltaAmountClaimable, uint256 updatedAmountClaimed)
Simulates the unlocked tokens not yet claimed in an actual unlocking schedule at a given time.
This is the most complex calculation in the contract.
Reverts with ActualDoesNotExist for a canceled or nonexistent actual.
Parameters¶
| Name | Type | Description |
|---|---|---|
| actualId | uint256 | The ID of the actual unlocking schedule. |
| claimTimestampAbsolute | uint256 | The simulated time of claim. |
Return Values¶
| Name | Type | Description |
|---|---|---|
| deltaAmountClaimable | uint256 | Amount of tokens claimable at claimTimestampAbsolute. |
| updatedAmountClaimed | uint256 | The new total amount claimed: all previously claimed tokens plus deltaAmountClaimable. |
Ownership¶
TTUnlocker inherits Solady's Ownable (solady 0.1.19). These functions are not part of ITTUnlocker. The write functions are payable in Solady.
OwnershipTransferred¶
OwnershipHandoverRequested¶
OwnershipHandoverCanceled¶
Unauthorized¶
0x82b42900
The caller is not authorized to call the function.
NewOwnerIsZeroAddress¶
0x7448fbae
NoHandoverRequest¶
0x6f5e8818
The pendingOwner does not have a valid handover request.
owner¶
Returns the owner of the contract.
transferOwnership¶
Transfers ownership to newOwner. Only callable by the owner. Reverts with NewOwnerIsZeroAddress for the zero address.
renounceOwnership¶
Lets the owner renounce ownership.
requestOwnershipHandover¶
Requests a two-step ownership handover to the caller. By default, the request expires after 48 hours (172800 seconds).
cancelOwnershipHandover¶
Cancels the two-step ownership handover to the caller, if any.
completeOwnershipHandover¶
Lets the owner complete the two-step ownership handover to pendingOwner. Reverts if pendingOwner has not requested a handover.
ownershipHandoverExpiresAt¶
Returns the expiry timestamp for the two-step ownership handover to pendingOwner.
Implementation constants¶
TTUnlocker also exposes these public constants:
| Name | Value | Description |
|---|---|---|
| BIPS_PRECISION | 10 ** 4 |
Basis point precision. linearBips must add up to it. |
| TOKEN_PRECISION | 10 ** 5 |
Internal precision used in claimable calculations. |
| DURATION_PRECISION | 10 ** 5 |
Internal precision used in claimable calculations. |
| externalDelegateRegistry | 0x00000000000000447e69651d841bD8D104Bed493 |
The delegate.xyz registry used by delegateClaim. |
Variants¶
TTUnlockerExternalFT¶
Used when deployTTSuite is called with an existing NFT as FutureToken (experimental). Schedules are attached to existing token IDs instead of minting new ones:
function createActuals(uint256[] actualIds, struct Actual[] actuals_, uint256[] recipientIds, uint256 batchId, bytes extraData) external virtual
The address-based createActuals from ITTUnlocker reverts with Unsupported() (0x90a2caf2). Creating an actual for an actualId that already has one reverts with ActualExists.
TTUnlockerNative¶
Distributes the chain's native token instead of an ERC-20. Deposits are plain native-token transfers to the contract, which emit DepositReceived(address from, uint256 amount). Claims charge no fees. TTUDeployer has no beacon type for this variant, and the Unlocker deployment records do not list it.