# Vesting V3 Guide

This guide covers the **V3 DecubateVestingV2** contract (Upgradeable version with role-based access). If you are unsure which version you are on, see the Version Identification Guide.

***

### 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.

> **Important:** V3 uses a proxy pattern. On the block explorer, use the **"Read as Proxy"** and **"Write as Proxy"** tabs to interact with the contract.

***

### Key Differences from V2

| Feature                 | V2                       | V3                                           |
| ----------------------- | ------------------------ | -------------------------------------------- |
| Access control          | Single owner (`Ownable`) | Role-based (`MANAGER_ROLE`, `DEFAULT_ADMIN`) |
| Upgradeable             | No                       | Yes (proxy pattern)                          |
| Claim fees              | No                       | Yes (optional fee on claims)                 |
| Disable entire strategy | No                       | Yes (`setVestingStatus`)                     |
| Batch revoke/disable    | No                       | Yes (`batchRevokeOrSetVestingStatus`)        |

***

## Part 1: Investor Guide

This section is for investors who need to check their vesting status and claim tokens.

### 1.1 — Check If You Are Whitelisted

1. Go to your contract on the block explorer.
2. Navigate to **"Read as Proxy"**.
3. Find **`hasWhitelist`**.
4. Enter:
   * `_option`: Your vesting pool ID (usually `0` — ask your project admin if unsure).
   * `_wallet`: Your wallet address.
5. If it returns `true`, you are whitelisted.

### 1.2 — Check Your Vesting Details

1. In **"Read as Proxy"**, find **`getWhitelist`**.
2. Enter `_option` and `_wallet`.
3. You will see:
   * `wallet` — Your address.
   * `dcbAmount` — Total token allocation (in wei). Divide by `10^18` for the readable amount.
   * `distributedAmount` — Tokens already claimed (in wei).
   * `joinDate` — Timestamp when you were added.
   * `revoke` — `true` if your vesting was revoked.
   * `disabled` — `true` if claiming is temporarily disabled.

### 1.3 — Understand Your Vesting Schedule

1. Call **`getVestingInfo`** with your pool ID (`_strategy`).
2. Key fields:
   * `vestType`: `0` = Linear, `1` = Monthly, `2` = Interval.
   * `initialUnlockPercent`: Percentage unlocked immediately (out of 1000, so `100` = 10%).
   * `start`: When vesting begins.
   * `cliff`: When tokens start unlocking beyond the initial amount.
   * `duration`: (Linear only) How long the linear vesting lasts.
   * `interval`: (Interval only) Time between each unlock.
   * `unlockPerInterval`: (Monthly/Interval) Percentage unlocked each period (out of 1000).
   * `timestamps`: (Monthly only) Array of exact unlock dates.
   * `isDisabled`: If `true`, the entire strategy is disabled — no one can claim.

#### How Each Type Works

**Linear:** After the cliff, tokens vest smoothly every second until `cliff + duration`.

**Monthly:** After the cliff, a fixed percentage unlocks on each monthly date listed in `timestamps`.

**Interval:** After the cliff, a fixed percentage unlocks every `interval` seconds.

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

### 1.4 — Check How Many Tokens Are Vested

1. Find **`getVestAmount`** in "Read as Proxy".
2. Enter `_option` and `_wallet`.
3. The result is total tokens vested to date (in wei).

### 1.5 — Check Claimable (Releasable) Amount

1. Find **`getReleasableAmount`**.
2. Enter `_option` and `_wallet`.
3. The result is: `vested - already claimed` (in wei).

### 1.6 — Check Claim Fees

V3 may charge a fee on claims. To check:

1. In "Read as Proxy", call **`claimFee`**.
2. You will see:
   * `claimFeePercent`: Fee percentage (out of 10000, so `100` = 1%).
   * `claimFeeReceiver`: Address that receives the fee.

> The fee is deducted from the contract's token balance, **not** from your claimed amount. You still receive the full release amount.

### 1.7 — Claim Your Tokens

1. Navigate to **"Write as Proxy"**.
2. **Connect your wallet** by clicking "Connect to Web3".
3. Find **`claimDistribution`**.
4. Enter:
   * `_option`: Your vesting pool ID.
   * `_wallet`: Your wallet address.
5. Click **Write** and confirm the transaction.

> **Note:** If `maxTokenTransfer` is active, you may need to claim multiple times. If the strategy is disabled (`isDisabled = true`), claiming will fail until the admin re-enables it.

***

## Part 2: Admin / Founder Guide

This section is for contract managers who manage vesting strategies and whitelists.

### Understanding Roles

V3 uses role-based access control instead of a single owner:

| Role                 | Who               | What They Can Do                                      |
| -------------------- | ----------------- | ----------------------------------------------------- |
| `DEFAULT_ADMIN_ROLE` | Contract deployer | Grant/revoke manager role. Full admin access.         |
| `MANAGER_ROLE`       | Assigned by admin | Manage strategies, whitelists, and contract settings. |

To check if an address has a role:

1. In "Read as Proxy", call **`hasRole`**.
2. Enter the role hash and the address.
   * `DEFAULT_ADMIN_ROLE`: `0x0000000000000000000000000000000000000000000000000000000000000000`
   * `MANAGER_ROLE`: `0x241ecf16d79d0f8dbfb92cbc07fe17840425976cf0667f022fe9877caa831b08`

### 2.1 — Grant or Revoke Manager Role

> Requires `DEFAULT_ADMIN_ROLE`.

1. In "Write as Proxy", call **`setManagerRole`** with:
   * `_user`: Address to grant/revoke.
   * `_status`: `true` to grant, `false` to revoke.

### 2.2 — View All Vesting Pools

1. In "Read as Proxy", call **`getAllVestingPools`**.

### 2.3 — View a Specific Pool

1. Call **`getVestingInfo`** with `_strategy` (pool index starting from `0`).

### 2.4 — Add a New Vesting Strategy

> Requires `MANAGER_ROLE`.

1. Go to **"Write as Proxy"** and connect your wallet.
2. Call **`addVestingStrategy`** with:
   * `_name`: Strategy name.
   * `_cliff`: Cliff duration in seconds (added to `_start`).
   * `_start`: Unix timestamp for vesting start (must be > 0).
   * `_duration`: Vesting duration in seconds (Linear type).
   * `_initialUnlockPercent`: Initial unlock out of 1000 (max 1000 = 100%).
   * `_revocable`: `true` or `false`.
   * `_interval`: Time between unlocks in seconds (Interval type only, `0` for others).
   * `_unlockPerInterval`: Percentage per unlock out of 1000 (Interval/Monthly, `0` for Linear).
   * `_monthGap`: Months between unlocks (Monthly type only, `0` for others).
   * `_type`: `0` = Linear, `1` = Monthly, `2` = Interval.

#### Example: Linear Vesting

```
_name: "Seed Round"
_cliff: 2592000          (30 days)
_start: 1700000000       (Unix timestamp)
_duration: 15552000      (180 days)
_initialUnlockPercent: 100   (10%)
_revocable: true
_interval: 0
_unlockPerInterval: 0
_monthGap: 0
_type: 0
```

#### Example: Monthly Vesting

```
_name: "Team Allocation"
_cliff: 7776000          (90 days)
_start: 1700000000
_duration: 0
_initialUnlockPercent: 50    (5%)
_revocable: false
_interval: 0
_unlockPerInterval: 100  (10% per month)
_monthGap: 1
_type: 1
```

#### Example: Interval Vesting

```
_name: "Advisor Pool"
_cliff: 2592000          (30 days)
_start: 1700000000
_duration: 0
_initialUnlockPercent: 0
_revocable: true
_interval: 604800        (7 days)
_unlockPerInterval: 50   (5% per interval)
_monthGap: 0
_type: 2
```

### 2.5 — Update an Existing Vesting Strategy

1. Call **`setVestingStrategy`** with:
   * `_strategy`: Pool index.
   * All fields as in `addVestingStrategy` (except `_monthGap` and `_type`).

> **Important:** Monthly strategies **cannot** be updated.

### 2.6 — Enable / Disable an Entire Strategy

This prevents all users in a pool from claiming or being added.

1. Call **`setVestingStatus`** with:
   * `_option`: Pool index.
   * `_status`: `true` to disable, `false` to re-enable.

### 2.7 — Add a Single User to Whitelist

1. Call **`addWhitelist`** with:
   * `_wallet`: User's wallet address.
   * `_dcbAmount`: Total allocation in wei.
   * `_option`: Vesting pool ID.

> Strategy must not be disabled.

### 2.8 — Add Multiple Users (Batch)

1. Call **`batchAddWhitelist`** with:
   * `wallets`: Array of addresses.
   * `amounts`: Array of amounts in wei.
   * `option`: Vesting pool ID.

### 2.9 — Update a User's Allocation

1. Call **`setWhitelist`** with:
   * `_wallet`: User's address.
   * `_dcbAmount`: New allocation in wei.
   * `_option`: Vesting pool ID.

> Strategy must not be disabled.

### 2.10 — Revoke a User's Vesting

1. Call **`revoke`** with `_option` and `_wallet`.
2. Vested but unclaimed tokens are automatically distributed before revoking.

> Strategy must have `revocable` set to `true`.

### 2.11 — Batch Revoke or Disable Multiple Users

1. Call **`batchRevokeOrSetVestingStatus`** with:
   * `batchRevoke`: `true` to revoke all listed wallets, `false` to set their disabled status.
   * `_option`: Vesting pool ID.
   * `_wallets`: Array of wallet addresses.
   * `status`: (Only used when `batchRevoke` is `false`) `true` to disable, `false` to enable.

#### Example: Revoke 3 users

```
batchRevoke: true
_option: 0
_wallets: ["0xABC...", "0xDEF...", "0x123..."]
status: false  (ignored when batchRevoke is true)
```

#### Example: Disable 3 users from claiming

```
batchRevoke: false
_option: 0
_wallets: ["0xABC...", "0xDEF...", "0x123..."]
status: true
```

### 2.12 — Enable / Disable a Single User's Claiming

1. Call **`setVesting`** with:
   * `_option`: Vesting pool ID.
   * `_wallet`: User's address.
   * `_status`: `true` to disable, `false` to re-enable.

### 2.13 — Set Max Token Transfer Limit

1. Call **`setMaxTokenTransfer`** with:
   * `_amount`: Maximum amount in wei per claim.
   * `_active`: `true` to enable, `false` to disable.

### 2.14 — Change the Token Address

1. Call **`setToken`** with `_addr`.

> Address must not be `0x0`.

### 2.15 — Set Claim Fee

> Only callable by the current `claimFeeReceiver`.

1. Call **`setClaimFee`** with a tuple:
   * `claimFeePercent`: Fee out of 10000 (max 5000 = 50%).
   * `claimFeeReceiver`: Address to receive fees.

### 2.16 — Withdraw Tokens from the Contract

1. Call **`transferToken`** with:
   * `_addr`: Token contract address.
   * `_amount`: Amount in wei.

> In V3, tokens are sent to the **caller's address** (not the owner), so make sure you call this from the correct wallet.

### 2.17 — View Whitelist for a Pool

1. Call **`getWhitelistPool`** with `_option`.

#### 2.18 — Check Contract Token Balance

Call `getTotalToken` with `_addr` (token contract address).

Returns the total token balance held by the vesting contract.


---

# 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/vesting-contracts/vesting-v3-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.