Block-Height Vesting Needs One Clock Across Chains

Block-height vesting releases tokens as a chain advances, so a schedule spanning several networks needs one designated clock and a way to carry its state. A contract can compare the current block number with a release threshold, but block numbers on separate chains do not measure the same elapsed time.

That difference matters when a grant is split across networks: one chain may reach its next threshold before another. For a broader look at how wallets coordinate assets and applications across networks, see this guide to omnichain wallet activity across chains; vesting adds the separate question of which chain’s progress controls the unlock.

What does block-height vesting measure?

Block-height vesting measures progress by counting blocks on a specified chain. Solidity’s documentation identifies block.number as a value contracts can read, so a vesting contract can store a start height, a release interval and the amount made available at each interval.

For example, a contract might make a portion claimable after a set number of blocks, then repeat that rule at later thresholds. The calculation is deterministic on that chain, but blocks arrive at a variable pace; a height target is not an exact calendar date. A schedule expressed in blocks is therefore useful when the protocol wants releases tied to chain progress, while a timestamp schedule is easier to communicate as a date.

How can one vesting schedule stay aligned across chains?

A multi-chain design needs a canonical clock: one chain whose height determines how much has vested. A contract on that chain can calculate the unlocked amount, while destination contracts accept updates that state the latest authorized vesting checkpoint.

The update can travel as a cross-chain message or as a proof that the destination verifies. Either way, the destination must not treat its own block height as a substitute for the canonical chain’s height. The update should identify the grant, checkpoint and amount, and the destination should reject a checkpoint it has already applied.

The central trade-off is between fresh claims and simple accounting. Waiting for a verified update can delay a claim on a destination chain; allowing each chain to calculate independently can make the same grant appear to vest at different rates. A design should state what happens while a message is pending and whether users can claim against the last confirmed checkpoint.

What should teams check before using this design?

Teams reviewing a block-height vesting plan should check these points in the contracts and their public schedule:

• Clock: Name the chain whose block height controls each release.
• Conversion: Explain how a canonical unlock becomes a claimable amount on each destination.
• Message handling: Define confirmation, replay protection, failed delivery and delayed updates.
• Accounting: Ensure claims across chains cannot exceed the grant’s total vested amount.

For most readers, the easier design to audit is one canonical schedule with destination contracts that verify updates and keep a visible record of the last accepted checkpoint. Independent schedules may be simpler to launch, but they leave users to reconcile different chain clocks and create more room for inconsistent balances.

The next event in this system is a checkpoint on the designated chain. After that height is reached, the update must be verified on each destination before its contract makes the corresponding tokens claimable.