# Vesting Guide

This guide covers the **DecubateVestingV3** contract — the latest Decubate vesting contract.

> Use the **"Read as Proxy"** and **"Write as Proxy"** tabs on the block explorer.

***

### Prerequisites

* Your vesting contract address.
* A block explorer for your chain (e.g., Etherscan, BscScan).
* A wallet (e.g., MetaMask) connected to the correct network.
* You must be whitelisted in a vesting strategy to claim tokens.

***

### Key Concepts

#### Vesting Types

| Type       | Value | Description                                                           |
| ---------- | ----- | --------------------------------------------------------------------- |
| `Linear`   | `0`   | Tokens vest continuously every second from cliff to cliff + duration. |
| `Interval` | `1`   | Tokens unlock in fixed percentages at regular time intervals.         |
| `Full`     | `2`   | All tokens become claimable at once when the cliff is reached.        |

#### Percentages

All percentages in this contract use a **divisor of 1,000,000** (not 1,000). So:

| Value     | Meaning |
| --------- | ------- |
| `100000`  | 10%     |
| `500000`  | 50%     |
| `1000000` | 100%    |

#### Strategy Locking

Strategies start as **revocable** (unlocked). The admin can **lock** a strategy, which:

* Makes it irrevocable, users cannot be revoked or removed.
* Locks tokens in the contract to guarantee all users can claim.
* The strategy parameters cannot be changed after locking.

***

## Part 1: Investor Guide

#### 1.1 — Find Your Strategy ID

If you don't know your strategy ID, you can find it yourself on-chain:

1. Navigate to "Read as Proxy".
2. Call `getVestingStrategiesLength`. Note the returned number — this is the total number of strategies.
3. For each ID from `0` to `length - 1`, call `getUserWhitelisted` with:
   * `_strategyId`: The ID you are checking.
   * `_wallet`: Your wallet address.
4. Any ID that returns `true` is a strategy you belong to.
5. Optionally, call `getVestingInfo` on each matching ID to see the strategy name (e.g., "Seed Round") and confirm it matches what you expect.

#### 1.2 — Check If You Are Whitelisted

1. Navigate to "Read as Proxy".
2. Call `getUserWhitelisted` with:
   * `_strategyId`: Your strategy ID.
   * `_wallet`: Your wallet address.
3. Returns `true` if you are whitelisted.

#### 1.3 — Check Your Vesting Details

Call `getUserInfo` with `_strategyId` and `_wallet`.

You will see:

* `wallet`: Your address.
* `vestedAmount`: Total token allocation (in wei). Divide by 10^18 for the readable amount.
* `distributedAmount`: Tokens already claimed (in wei).
* `whitelistDate`: Timestamp when you were added.
* `isRevoked`: `true` if your vesting was cancelled.

#### 1.4 — Understand Your Vesting Schedule

Call `getVestingInfo` with `_strategyId`.

Key fields:

* `name`: Strategy name (e.g., "Seed Round").
* `vestingType`: `0` = Linear, `1` = Interval, `2` = Full.
* `start`: When vesting begins (Unix timestamp).
* `cliff`: When tokens start unlocking beyond the initial amount.
* `duration`: (Linear only) How long the vesting lasts after cliff.
* `initialUnlockPercent`: Percentage unlocked at start (out of 1,000,000).
* `interval`: (Interval only) Seconds between each unlock.
* `unlockPerInterval`: (Interval only) Percentage per unlock (out of 1,000,000).
* `revocable`: `true` = strategy is unlocked (admin can still revoke users). `false` = locked (guaranteed).
* `isDisabled`: `true` = claiming is paused for all users.
* `vestedAmount`: Total tokens allocated to all users in this strategy.

How Each Type Works:

* **Linear**: After the cliff, tokens vest smoothly every second. At `cliff + duration`, all tokens are fully vested.
* **Interval**: After the cliff, a fixed percentage unlocks every `interval` seconds. For example, 10% every 30 days.
* **Full**: Nothing is available before the cliff. At the cliff, 100% becomes claimable at once.

In all types, `initialUnlockPercent` is available as soon as the start time passes.

#### 1.5 — Check Claimable Amount

Call `getClaimableAmount` with `_strategyId` and `_wallet`.

Returns the amount you can claim right now (in wei).

#### 1.6 — Check Total Releasable Amount

Call `getReleasableAmount` with `_strategyId` and `_wallet`.

Returns the total vested amount to date (in wei), including what you've already claimed.

#### 1.7 — Check Claim Fees

There may be two types of fees:

**Token Fee (Percentage)**

Call `claimFee`.

* `claimFeePercent`: Percentage out of 1,000,000.
* `claimFeeReceiver`: Address that receives the fee.

This fee is taken from the contract's token balance, not from your claimed amount. You receive the full release amount.

**Native Token Fee (USD-denominated)**

Call `minFeeUSD`. If greater than `0`, you must pay a fee in the chain's native token (ETH, BNB, etc.) when claiming.

The fee amount in wei is determined by the `feeConverter` contract at claim time. You need to send this fee as the transaction value when calling `claim`.

#### 1.8 — Claim Your Tokens

1. Navigate to "Write as Proxy".
2. Connect your wallet.
3. Find `claim`.
4. Enter:
   * `_strategyId`: Your strategy ID.
5. If `minFeeUSD > 0`: Set the **value** (`payableAmount`) field. To find the correct amount:
   * Call `feeConverter` to get the converter address.
   * On the converter contract, call `convertUSDFeeToWei` with the `minFeeUSD` value.
   * Use the returned value (or slightly more) as the transaction value.
6. Click **Write** and confirm the transaction.

If the strategy is disabled (`isDisabled = true`), claiming will fail. Contact your project admin.

***

## Part 2: Admin / Founder Guide

> Requires `MANAGER_ROLE` unless otherwise noted.

### Understanding Roles

| Role                 | Who               | Access                                 |
| -------------------- | ----------------- | -------------------------------------- |
| `DEFAULT_ADMIN_ROLE` | Contract deployer | Grant/revoke manager role              |
| `MANAGER_ROLE`       | Assigned by admin | Manage strategies, users, and settings |

#### Grant / Revoke Manager

> Requires `DEFAULT_ADMIN_ROLE`.

1. Call **`setManagerRole`** with `_user` and `_status` (`true`/`false`).

***

### Strategy Management

#### Add a New Strategy

1. Call **`addVestingStrategy`** with:
   * `_name`: Strategy name.
   * `_cliff`: Cliff duration in seconds (added to `_start`).
   * `_start`: Unix timestamp (must be in the future).
   * `_duration`: Vesting duration in seconds (Linear type).
   * `_initialUnlockPercent`: Initial unlock out of 1,000,000.
   * `_interval`: Seconds between unlocks (Interval type, `0` for others).
   * `_unlockPerInterval`: Percentage per unlock out of 1,000,000 (Interval type, `0` for others).
   * `_type`: `0` = Linear, `1` = Interval, `2` = Full.

> Strategies are created as **revocable** (unlocked) by default.

**Example: Linear Vesting**

```
_name: "Seed Round"
_cliff: 2592000              (30 days)
_start: 1750000000           (future timestamp)
_duration: 15552000           (180 days)
_initialUnlockPercent: 100000     (10%)
_interval: 0
_unlockPerInterval: 0
_type: 0
```

**Example: Interval Vesting**

```
_name: "Advisor Pool"
_cliff: 2592000              (30 days)
_start: 1750000000
_duration: 0                  (not used)
_initialUnlockPercent: 0
_interval: 2592000            (30 days)
_unlockPerInterval: 100000    (10% per interval)
_type: 1
```

**Example: Full Vesting (Cliff Only)**

```
_name: "TGE Unlock"
_cliff: 0                    (no cliff — available at start)
_start: 1750000000
_duration: 0
_initialUnlockPercent: 0
_interval: 0
_unlockPerInterval: 0
_type: 2
```

#### Edit a Strategy

1. Call **`setVestingStrategy`** with `_strategyId` and updated params.

> Can only edit **before the strategy has started** and while it is **unlocked** (revocable).

#### Disable / Enable a Strategy

1. Call **`setStrategyStatus`** with `_strategyId` and `_status`:
   * `true` = disabled (no claiming).
   * `false` = enabled.

> Strategy must be unlocked (revocable).

#### Lock a Strategy (Make Irrevocable)

Locking guarantees all users can claim by reserving tokens in the contract.

1. Call **`lockStrategy`** with `_strategyId`.

> **Requirements:**
>
> * Strategy must not be disabled.
> * Strategy must currently be revocable.
> * The contract must hold enough tokens to cover the strategy's entire `vestedAmount`.

> **Warning:** This action is **permanent**. Once locked, the strategy cannot be edited, disabled, or have users revoked.

***

### User Management

#### Add a Single User

1. Call **`addWhitelist`** with:
   * `_strategyId`: Strategy ID.
   * `_wallet`: User's address.
   * `_vestedAmount`: Total allocation in wei.

> Strategy must be unlocked and not disabled.

#### Add Multiple Users (Batch)

1. Call **`batchAddWhitelist`** with:
   * `_strategyId`: Strategy ID.
   * `wallets`: Array of addresses.
   * `amounts`: Array of amounts in wei.

#### Change a User's Allocation

1. Call **`setUserAllocation`** with:
   * `_strategyId`, `_wallet`, `_amount` (new allocation in wei).

> Can only change **before the strategy has started**. Strategy must be unlocked.

#### Revoke a User

Cancels a user's remaining vesting. Already claimed tokens are not affected.

1. Call **`revoke`** with `_strategyId` and `_wallet`.

> Strategy must be unlocked (revocable).

#### Batch Revoke

1. Call **`batchRevoke`** with `_strategyId` and `_wallets` (array of addresses).

***

### Fee Management

#### Set Claim Fee (Token Percentage)

> Only callable by the current `claimFeeReceiver`.

1. Call **`setClaimFee`** with:
   * `claimFeePercent`: Out of 1,000,000 (max 500,000 = 50%).
   * `claimFeeReceiver`: Address to receive fees.

#### Set User Fee (Native Token / USD)

> Only callable by the current `claimFeeReceiver`.

1. Call **`setUsersFee`** with:
   * `_feeConverter`: Fee converter contract address.
   * `_minFeeUSD`: Minimum fee in USD (in stable coin decimals, e.g., `1000000` = $1 for 6-decimal stables).

> Set `_minFeeUSD` to `0` to disable the native token fee.

***

### Token Management

#### Withdraw Available Tokens

Withdraw tokens that are **not locked** for any strategy.

1. Call **`withdrawTokens`** with `_amount` (in wei).
2. Returns `false` if there are not enough available tokens (locked tokens cannot be withdrawn).

> Available = `contract balance - totalAmountLocked`.

#### Check Locked vs Available Balances

1. Call **`totalAmountLocked`** — tokens reserved for locked strategies.
2. Call **`totalAmountVested`** — tokens allocated to unlocked strategies.
3. Check the token balance of the contract on the token contract.
4. Available to withdraw = `balance - totalAmountLocked`.

***

### Viewing Data

#### List All Strategies

1. Call **`getVestingStrategiesLength`** to get the count.
2. Call **`getVestingStrategies`** with `_start` and `_end` indices (0-based, inclusive).

#### View Users in a Strategy

1. Call **`getUsersLength`** with `_strategyId` to get the count.
2. Call **`getUsers`** with `_strategyId`, `_start`, and `_end` (0-based, inclusive).

> Revoked users are included in the results (check `isRevoked` field).

#### Check a Specific User

1. Call **`getUserInfo`** with `_strategyId` and `_wallet`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tms-finance.gitbook.io/tms.finance/tms-contracts/vesting-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.