Skip to content

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

event PresetCreated(bytes32 presetId, uint256 batchId)

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

event TokensWithdrawn(address by, uint256 amount)

ClaimingDelegateSet

event ClaimingDelegateSet(address delegate, bool status)

CreateDisabled

event CreateDisabled()

CancelDisabled

event CancelDisabled()

HookDisabled

event HookDisabled()

WithdrawDisabled

event WithdrawDisabled()

InvalidPresetFormat

error InvalidPresetFormat()

0x0ef8e8dc

PresetExists

error PresetExists()

0x7cbb15b4

PresetDoesNotExist

error PresetDoesNotExist()

0xbd88ff7b

ActualDoesNotExist

error ActualDoesNotExist()

0x6aed3166

ActualExists

error ActualExists()

0x0cbf932d

Thrown by TTUnlockerExternalFT when an actual already exists for the given actualId.

InvalidSkipAmount

error InvalidSkipAmount()

0x78c0fc43

NotPermissioned

error NotPermissioned()

0x7f63bd0f

AlreadyWithdrawable

error 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

function withdrawDeposit(uint256 amount, bytes extraData) external virtual

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

function delegateClaim(uint256[] actualIds, uint256 batchId, bytes extraData) external virtual

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

function setHook(contract ITTHook hook) external virtual

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

function setClaimingDelegate(address delegate, bool status) external virtual

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

function setCurrentChainSupportsExternalDelegateRegistry(bool status) external virtual

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

function disableCreate() external virtual

Permanently disables the createActuals() function.

Only callable by the owner.

disableCancel

function disableCancel() external virtual

Permanently disables the cancel() function.

Only callable by the owner.

disableHook

function disableHook() external virtual

Permanently disables the hook.

Only callable by the owner.

The current hook is called one last time before it is removed.

disableWithdraw

function disableWithdraw() external virtual

Permanently prevents the founder from withdrawing deposits.

Only callable by the owner.

setEmergencyWithdrawRequestStatus

function setEmergencyWithdrawRequestStatus(bool status) external virtual

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

function deployer() external view virtual returns (address)

Return Values

Name Type Description
[0] address The deployer instance associated with this Unlocker.

futureToken

function futureToken() external view virtual returns (address)

Return Values

Name Type Description
[0] address The FutureToken instance associated with this Unlocker.

hook

function hook() external view virtual returns (contract ITTHook)

Return Values

Name Type Description
[0] contract ITTHook The external hook associated with this Unlocker.

claimingDelegates

function claimingDelegates() external view virtual returns (address[])

Return Values

Name Type Description
[0] address[] The claiming delegates, who can trigger claims on behalf of schedule recipients.

isCreateable

function isCreateable() external view virtual returns (bool)

Return Values

Name Type Description
[0] bool Whether the founder can create new schedules.

isCancelable

function isCancelable() external view virtual returns (bool)

Return Values

Name Type Description
[0] bool Whether the founder can cancel schedules.

isHookable

function isHookable() external view virtual returns (bool)

Return Values

Name Type Description
[0] bool Whether the founder can attach external hooks to function calls.

isWithdrawable

function isWithdrawable() external view virtual returns (bool)

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

function getEncodedPreset(bytes32 presetId) external view virtual returns (bytes)

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

function actuals(uint256 actualId) external view virtual returns (struct Actual)

Returns the Actual struct for the given ID.

getProjectToken

function getProjectToken() external view virtual returns (address)

Return Values

Name Type Description
[0] address The address of the project token that this Unlocker is associated with.

BIPS_PRECISION

function BIPS_PRECISION() external pure virtual returns (uint256)

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

function currentChainSupportsExternalDelegateRegistry() public view virtual returns (bool)

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

event OwnershipTransferred(address indexed oldOwner, address indexed newOwner)

OwnershipHandoverRequested

event OwnershipHandoverRequested(address indexed pendingOwner)

OwnershipHandoverCanceled

event OwnershipHandoverCanceled(address indexed pendingOwner)

Unauthorized

error Unauthorized()

0x82b42900

The caller is not authorized to call the function.

NewOwnerIsZeroAddress

error NewOwnerIsZeroAddress()

0x7448fbae

NoHandoverRequest

error NoHandoverRequest()

0x6f5e8818

The pendingOwner does not have a valid handover request.

owner

function owner() public view returns (address result)

Returns the owner of the contract.

transferOwnership

function transferOwnership(address newOwner) public payable

Transfers ownership to newOwner. Only callable by the owner. Reverts with NewOwnerIsZeroAddress for the zero address.

renounceOwnership

function renounceOwnership() public payable

Lets the owner renounce ownership.

requestOwnershipHandover

function requestOwnershipHandover() public payable

Requests a two-step ownership handover to the caller. By default, the request expires after 48 hours (172800 seconds).

cancelOwnershipHandover

function cancelOwnershipHandover() public payable

Cancels the two-step ownership handover to the caller, if any.

completeOwnershipHandover

function completeOwnershipHandover(address pendingOwner) public payable

Lets the owner complete the two-step ownership handover to pendingOwner. Reverts if pendingOwner has not requested a handover.

ownershipHandoverExpiresAt

function ownershipHandoverExpiresAt(address pendingOwner) public view returns (uint256 result)

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.