Unlocker

ITokenTableUnlockerV2

The lightweight interface for TokenTableUnlockerV2(.5.x), which handles token unlocking and distribution for TokenTable.

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()

0x06aed316

InvalidSkipAmount

error InvalidSkipAmount()

0x78c0fc43

NotPermissioned

error NotPermissioned()

0x7f63bd0f

initialize

function initialize(address projectToken, address futureToken_, address deployer_, bool isCancelable_, bool isHookable_, bool isWithdrawable_) external virtual

This contract should be deployed with TTUDeployerLite, which calls this function with the correct parameters.

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. It helps call the fee collector during claim.
isCancelable_	bool	If the founder is allowed to cancel schedules. Can be disabled later, but cannot be enabled again.
isHookable_	bool	If the founder is allowed to attach external hooks to function calls. Can be disabled later, but cannot be enabled again.
isWithdrawable_	bool	If the founder is allowed to withdraw deposited tokens. Can be disabled later, but cannot be enabled again.

createPresets

function createPresets(bytes32[] presetIds, struct Preset[] presets, uint256 batchId, bytes extraData) external virtual

Creates an unlocking schedule preset template.

Emits PresetCreated. Only callable by the owner.

Parameters

Name	Type	Description
presetIds	bytes32[]	These IDs can be the hashes of a plaintext preset names but really there is no restriction. Will revert if they already exist.
presets	struct Preset[]	An array of Preset structs.
batchId	uint256	Emitted as an event reserved for EthSign frontend use. This parameter has no effect on contract execution.
extraData	bytes	An ERC-5750 parameter that's passed to the hook directly.

createActuals

function createActuals(address[] recipients, struct Actual[] actuals, uint256[] recipientIds, uint256 batchId, bytes extraData) external virtual

Creates an actual unlocking schedule based on a preset.

Emits ActualCreated. A FutureToken is minted in the process with tokenId == actualId.

Parameters

Name	Type	Description
recipients	address[]	An array of token recipients for the schedules. Note that claiming eligibility can be modified by transfering the corresponding FutureToken.
actuals	struct Actual[]	An array of Actual structs.
recipientIds	uint256[]	Emitted as an event reserved for EthSign frontend use. This parameter has no effect on contract execution.
batchId	uint256	Emitted as an event reserved for EthSign frontend use. This parameter has no effect on contract execution.
extraData	bytes	An ERC-5750 parameter that's passed to the hook directly.

withdrawDeposit

function withdrawDeposit(uint256 amount, bytes extraData) external virtual

Withdraws existing deposit from the contract.

Emits TokensWithdrawn. Only callable by the owner.

Parameters

Name	Type	Description
amount	uint256	Amount of deposited funds the founder wishes to withdraw.
extraData	bytes	An ERC-5750 parameter that's passed to the hook directly.

claim

function claim(uint256[] actualIds, address[] claimTos, uint256 batchId, bytes extraData) external virtual

Claims claimable tokens for the specified schedules to the specified addresses respectively.

Emits TokensClaimed. Only callable by the FutureToken owner.

Parameters

Name	Type	Description
actualIds	uint256[]	The IDs of the unlocking schedules that we are trying to claim from.
claimTos	address[]	If we want to send the claimed tokens to an address other than the caller. To send the claimed tokens to the caller (default behavior), pass in ethers.constants.AddressZero.
batchId	uint256	Emitted as an event reserved for EthSign frontend use. This parameter has no effect on contract execution.
extraData	bytes	An ERC-5750 parameter that's passed to the hook directly.

delegateClaim

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

Claims claimable tokens for the specified schedules on behalf of recipients. Claimed tokens are sent to the schedule recipients.

Emits TokensClaimed. Only callable by the claiming delegate.

Parameters

Name	Type	Description
actualIds	uint256[]	The IDs of the unlocking schedules that we are trying to claim from on behalf of the recipients.
batchId	uint256	Emitted as an event reserved for EthSign frontend use. This parameter has no effect on contract execution.
extraData	bytes	An ERC-5750 parameter that's passed to the hook directly.

cancel

function cancel(uint256[] actualIds, bool[] shouldWipeClaimableBalance, uint256 batchId, bytes extraData) external virtual returns (uint256[] pendingAmountClaimables)

Cancels an array of unlocking schedules effective immediately. Tokens not yet claimed but are already unlocked will be tallied.

Emits ActualCancelled. Only callable by the owner.

Parameters

Name	Type	Description
actualIds	uint256[]	The ID of the actual unlocking schedule that we want to cancel.
shouldWipeClaimableBalance	bool[]	If the unlocked and claimable balance of the canceled schedule should be wiped. This is usually used to delete an erroneously created schedule that has already started unlocking.
batchId	uint256	Emitted as an event reserved for EthSign frontend use. This parameter has no effect on contract execution.
extraData	bytes	An ERC-5750 parameter that's passed to the hook directly.

Return Values

Name	Type	Description
pendingAmountClaimables	uint256[]	Number of tokens eligible to be claimed by the affected stakeholders at the moment of cancellation.

setHook

function setHook(contract ITTHook hook) external virtual

Sets the hook contract.

Only callable by the owner.

Parameters

Name	Type	Description
hook	contract ITTHook	The address of the ITTHook hook contract.

setClaimingDelegate

function setClaimingDelegate(address delegate, bool status) external virtual

Sets the claiming delegate who can trigger claims on behalf of recipients.

Only callable by the owner.

Parameters

Name	Type	Description
delegate	address	The claiming delegate we wish to set.
status	bool	Whether the delegate is added(true) or revoked(false).

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.

disableWithdraw

function disableWithdraw() external virtual

Permanently prevents the founder from withdrawing deposits.

Only callable by the owner.

deployer

function deployer() external view virtual returns (contract ITTUDeployer)

Return Values

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

futureToken

function futureToken() external view virtual returns (contract ITTFutureTokenV2)

Return Values

Name	Type	Description
[0]	contract ITTFutureTokenV2	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[]	Returns the array of 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	If the founder is allowed to create new schedules.

isCancelable

function isCancelable() external view virtual returns (bool)

Return Values

Name	Type	Description
[0]	bool	If the founder is allowed to cancel schedules.

isHookable

function isHookable() external view virtual returns (bool)

Return Values

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

isWithdrawable

function isWithdrawable() external view virtual returns (bool)

Return Values

Name	Type	Description
[0]	bool	If 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 canceled schedules that have been unlocked but unclaimed by the stakeholder.

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 we are trying to read.

Return Values

Name	Type	Description
[0]	bytes	An ABI-encoded Preset, as nested objects cannot be returned directly in Solidity.

actuals

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

Returns the Actual struct based on the input ID.

BIPS_PRECISION

function BIPS_PRECISION() external pure virtual returns (uint256)

Return Values

Name	Type	Description
[0]	uint256	The basis point precision of this Unlocker.

calculateAmountClaimable

function calculateAmountClaimable(uint256 actualId) public view virtual returns (uint256 deltaAmountClaimable, uint256 updatedAmountClaimed)

Calculates the amount of unlocked tokens that have yet to be claimed in an actual unlocking schedule.

This is the most complex part of the smart contract. Quite a bit of calculations are performed here.

Parameters

Name	Type	Description
actualId	uint256	The ID of the actual unlocking schedule that we are working with.

Return Values

Name	Type	Description
deltaAmountClaimable	uint256	Amount of tokens claimable right now.
updatedAmountClaimed	uint256	New total amount of tokens claimed. This is the sum of all previously claimed tokens and deltaAmountClaimable.

simulateAmountClaimable

function simulateAmountClaimable(uint256 actualId, uint256 claimTimestampAbsolute) public view virtual returns (uint256 deltaAmountClaimable, uint256 updatedAmountClaimed)

Simulates the amount of unlocked tokens that have yet to be claimed at a specific time in an actual unlocking schedule.

This is the most complex part of the smart contract. Quite a bit of calculations are performed here.

Parameters

Name	Type	Description
actualId	uint256	The ID of the actual unlocking schedule that we are working with.
claimTimestampAbsolute	uint256	The simulated time of claim.

Return Values

Name	Type	Description
deltaAmountClaimable	uint256	Amount of tokens claimable right now.
updatedAmountClaimed	uint256	New total amount of tokens claimed. This is the sum of all previously claimed tokens and deltaAmountClaimable.