Token Unlock Scheduler

WHAT IT DOES

Token Unlock Scheduler gives project teams, token distributors, and beneficiaries full control over scheduled token unlock contracts. It reads live on-chain unlock schedule state including scheduled amounts per beneficiary, unlock timestamps, execution status, cancellation status, and total scheduled unlocks. You can create new unlock schedules with specific unlock timestamps, execute pending unlocks when the scheduled time arrives, and cancel scheduled unlocks before execution (returning tokens to the contract owner). The tool shows you in real time whether a schedule is pending, ready to execute, executed, or cancelled—so you never have to guess or rely on event logs that only prove past schedule creations happened.

HOW TO USE

Connect your EVM wallet. Enter the unlock scheduler contract address, token address, and beneficiary address you want to manage. Set the amount to unlock (in human-readable units) and the unlock timestamp as a Unix timestamp (seconds since epoch) or 0 to unlock immediately. Provide a schedule ID to check or manage specific schedules. Use "Check schedule" to see schedule details including token, beneficiary, amount, unlock time, execution status, and cancellation status. Click "Create schedule" to schedule a new token unlock—this requires the scheduler contract to have allowance for the tokens. Use "Execute unlock" to process a pending schedule after the unlock timestamp has passed, sending tokens to the beneficiary. The "Cancel schedule" button permanently voids a pending schedule (if permitted by the contract). Each action generates a transaction you review and sign in your wallet.

TECHNICAL APPROACH

This tool queries live contract state using ethers v5.7.2, not historical event logs. It calls getSchedule() to fetch the full schedule struct (token, beneficiary, amount, unlockTime, executed, cancelled) and isExecutable() to check if the schedule is ready for execution—avoiding the trap of assuming a schedule exists or is executable based on events alone. All RPC calls are wrapped in a robust error handler that extracts the actual failure reason from Ethers error objects, digging three levels deep to avoid showing "[object Object]" when a transaction reverts. For transaction costing, it uses receipt.effectiveGasPrice post-EIP-1559 rather than tx.gasPrice, which overstates actual spend. When creating schedules, it checks token balance and allowance before submitting the transaction, providing clear error messages for insufficient funds or approvals. The tool also converts human-readable amounts to the correct decimals based on the token's decimals() call and validates unlock timestamps against the current block time.

WHAT IT CANNOT SEE

This tool cannot detect off-chain unlock intent, verify beneficiary identity, or guarantee that tokens will be available for unlock at schedule maturity. It cannot ensure that the scheduler contract has sufficient token balance to fulfill all scheduled unlocks. It cannot simulate execution or test whether the unlock timestamp has passed before allowing execution. It cannot see pending unlock operations that are not yet broadcast to the public mempool, nor can it detect contract-specific unlock rules beyond the standard schedule interface. The tool manages schedules and executions, but it does not guarantee that tokens will be unlocked if the contract owner has administrative capabilities to override or cancel schedules.

PLEASE NOTE

This tool supports EVM‑compatible chains only (Ethereum, Goerli, Sepolia, Arbitrum, Optimism, Polygon). Solana, Tron, Starknet, SUI, TON, Aptos, Bitcoin, Cosmos, and XRP are not supported. This is a read‑write tool that requires signing transactions—always verify the scheduler contract address, token address, beneficiary address, amount, and unlock timestamp before approving. No contract addresses are hardcoded; you paste the contract you are using, so you are responsible for verifying its safety and ensuring it implements the expected unlock schedule interface. Cancelling schedules is irreversible—proceed with caution. The tool is free and open under the BotGentz PLAYBOOK‑C specification.