Module 09: Vesting

Client: client.vesting Weight: Light

Prerequisites

• Wallet funded with the main's pair asset (→02) and a token to vest
• Understand loan mechanics if you plan to take a vesting loan

Next steps after vesting

• Need liquidity before unlock? Take a vesting loan (§d below; it pledges every unclaimed token)
• Launching with a distribution plan? Combine with token creation
• Distributing to many recipients? Use batch creation (§a)

Why Vesting Matters

Vesting locks tokens and releases them on a schedule you define. Use it to:

• Lock team/advisor/investor tokens to signal long-term commitment
• Distribute allocations that release over months or years
• Build trust with your community: locked tokens can't be dumped immediately
• Access liquidity before unlock by taking a loan against a vesting position

How It Works

Two vesting types:

Roles. A wrong caller reverts.

The creator can give up changeBeneficiary, their own extendVestingPeriod and their own repayLoanOnVesting with renounceVesting(vestingId), or at creation with renounceOnCreation = true. Adding tokens and transferring the creator role still work after renouncing.

An open loan blocks four actions. extendVestingPeriod and addTokensToVesting revert "Loan open: repay first"; changeBeneficiary and claimTokens revert with no reason. It does not block transferCreatorRole or renounceVesting. Repay first, or use repayExtendAndReborrow(vestingId, additionalDays).

No price liquidation on vesting loans: expiry is time-based only, same as regular loans. After liquidationTime a keeper liquidates the position. Assume it can happen in the first block after the deadline. Until that transaction lands a repay or a paid extension still goes through; do not plan on the gap. After a liquidation the beneficiary (or the creator, unless the schedule is renounced) calls repayLoanOnVesting(vestingId), which pays nothing, collects what the liquidation left and shrinks the schedule to claimed + recovered. Do this within 365 days of the liquidation; after that the leftover may no longer be claimable.

Actions

a. Create Vesting

createGradualVesting(beneficiary, token, totalAmount, startTime, durationInDays, timeUnit, memo, ecosystem, renounceOnCreation) (payable)

Creates a linear vesting schedule. Tokens unlock progressively at each timeUnit interval throughout the duration.

A startTime in the past is moved to the block time; it does not revert. A startTime more than 7 days ahead reverts "Start too far". The beneficiary may not be the zero address ("Invalid beneficiary address").

// JS
const result = await client.vesting.createGradualVesting(
  "0xBeneficiary",
  "0xToken",
  parseUnits("10000", 18),
  Math.floor(Date.now() / 1000) + 60,  // a past value becomes now
  365,   // duration in days
  3,     // timeUnit: 3 = daily unlocks
  "Team allocation",
  MAINTOKEN,  // the token's main
  false       // renounceOnCreation
);

# Python
import time
result = client.vesting.create_gradual_vesting(
    "0xBeneficiary", "0xToken", 10000 * 10**18,
    int(time.time()) + 60, 365, 3, "Team allocation",
    MAINTOKEN,  # the token's main
    False       # renounce_on_creation
)

Fee. The call is payable. Send feeAmount() of ETH only when feeEnabled() is true and feeWhitelist(you) is false; otherwise send 0. The fee is off by default. Anything sent above the fee is refunded.

timeUnit examples: durationInDays=30, timeUnit=2 = hourly unlocks over 30 days (720 events). durationInDays=30, timeUnit=3 = daily unlocks over 30 days (30 events).

createCliffVesting(beneficiary, token, totalAmount, unlockTime, memo, ecosystem, renounceOnCreation) (payable)

All tokens unlock at unlockTime in a single event. unlockTime must be 1 hour to 990 days from now: anything else reverts.

Fee. As for the gradual call: feeAmount() in ETH only while feeEnabled() is true and you are not fee-whitelisted (off by default); a surplus is refunded.

Batch Creation

Only beneficiaries, amounts and memos are arrays, and they must have the same length ("Arrays length mismatch"). The memo array comes before startTime in the gradual call and after unlockTime in the cliff call. Both calls are payable, with one fee per batch.

Batch creation is the efficient path when distributing to many recipients at once (e.g., investor round, team allocation).

b. Claim Tokens

claimTokens(vestingId)

Claims all currently unlocked tokens. Only the beneficiary can call this.

• For cliff vesting: only callable after unlockTime
• For gradual vesting: callable anytime after vesting starts, claims whatever has vested since last claim
• Check getClaimableAmount(vestingId) before calling to confirm non-zero amount (it reads 0 while a loan is open)

const claimable = await client.vesting.getClaimableAmount(vestingId);
if (claimable > 0n) {
  await client.vesting.claimTokens(vestingId);
}

c. Manage Vesting

Creator calls, except that the beneficiary may also extend.

Blocked by an open loan: changeBeneficiary, extendVestingPeriod and addTokensToVesting. Repay the vesting loan first, or use repayExtendAndReborrow (§d).

d. Vesting Loans (Beneficiary; the Creator May Repay)

Borrow against a vesting position to access liquidity before tokens unlock.

takeLoanOnVesting(vestingId)

Takes a loan in the pair asset of the vesting's main. You choose neither the amount nor the term: it pledges every unclaimed token (totalAmount − claimedAmount) for the rest of the schedule plus loanBuffer() days (10), and pays the beneficiary the pair asset of the token's main.

Preview: the loan is sized at the collateral value of every unclaimed token (totalAmount − claimedAmount; quote it as in Module 05). A factory token is valued at its floor, not its market price. The term is the schedule's remaining whole days plus loanBuffer(). You receive that value less the origination fee (staticFeePercentage()) and the prepaid daily fee for the term (getDynamicFee(value, days)). A position worth less than minimumLoan() cannot borrow.

• Origination fee: 2% of the collateral value (today's value; read staticFeePercentage() on the main)
• Interest: 0.005% per day, prepaid for the whole term (today's value; read dynamicFeePercentage() on the main)
• Duration: set by the contract (the schedule's remaining days plus loanBuffer())
• Expiry: time-based only: no price liquidation
• Reverts: "Active loan exists", "No unclaimed tokens"

repayLoanOnVesting(vestingId)

Beneficiary, or the creator while the schedule is not renounced. Pulls the loan's fullAmount of the main's pair asset from the caller into the vesting contract: approve VESTING (the vesting entry of /contracts.json), not the loan hub. The loan is read from the hub it was opened on (loanHubOf(vestingId)). The tokens go back into the schedule, not to the caller. When the creator repays, the beneficiary keeps what it borrowed. After a liquidation the same call settles instead of paying (see How It Works).

repayExtendAndReborrow(vestingId, additionalDays)

Beneficiary only. Repays the open loan in full, extends the schedule by additionalDays and opens a new loan, in one transaction. The new loan pays the origination fee again. It is the only way to lengthen a schedule that has a loan. Reverts "Loan not active" if the loan was liquidated (settle it with repayLoanOnVesting first). Approve the pair asset to VESTING for the repay, as above.

Only one active loan per vesting position at a time. Check getActiveLoan(vestingId) to see current loan ID.

Read Methods

getVestingDetails struct fields (14, in contract order). Read the struct by field name. A positional reader written for the old 12-field list is off by one from index 3.

Fees

Errors

What Next

• Monitor claims: Poll getClaimableAmount() periodically for beneficiaries to know when to claim
• Loan against positions: Use takeLoanOnVesting() for liquidity before unlock (it pledges every unclaimed token)
• Trust signal: Publicly visible locked tokens signal commitment; use alongside token launches
• Batch distribution: Use batchCreateGradualVesting() or batchCreateCliffVesting() for investor rounds to save gas

See Also

• Module 05: Lending: Loan fees, extensions, repay flow in the main's pair asset, same mechanics apply to vesting loans
• Module 07: Token Creation: Launch a token, then vest allocations from it
• Module 10: Portfolio & Info: Query all your vesting schedules and claimable amounts
• Module 16: Trust & Security: Why locked tokens build platform trust
• Module 18: SDK Reference: Full vesting method signatures and errors