> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notareum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Venota

# veNOTA

The `veNOTA` contract (Solidity name `NotareumVeNOTA`) implements vote-escrowed NOTA. Holders lock NOTA for a chosen duration (up to 4 years) and receive non-transferable `veNOTA` balances that decay linearly to zero as the unlock date approaches. Governance weight and validator reward boosts are computed from the current `balanceOf` read on the contract. Longer locks yield more governance weight and deeper reward boosts per NOTA committed, at the cost of illiquidity.

## Design origin

The mechanic follows the ve(3,3) lineage pioneered by Curve's veCRV: time-weighted voting power with linear decay, no early withdrawal, governance-controlled boost mechanics. Notareum's variant sheds the gauge system and stays focused on protocol governance and validator reward multipliers.

## Parameters

| Parameter         | Value                      |
| ----------------- | -------------------------- |
| Max lock duration | 4 years (`4 * 365 days`)   |
| Min lock duration | 1 week                     |
| Decay             | Linear to zero             |
| Transferability   | Non-transferable           |
| Early withdrawal  | Disabled                   |
| Epoch length      | 1 week (for checkpointing) |

## Voting power curve

For a lock of `amount` NOTA expiring at `end`, the veNOTA balance at time `t`:

```
bal(t) = amount * max(0, end - t) / MAXTIME
```

where `MAXTIME = 4 * 365 * 86400`. A 1000-NOTA lock for 4 years starts at 1000 veNOTA and decays to 0 over 4 years. A 1000-NOTA lock for 1 year starts at 250 veNOTA.

```mermaid theme={"system"}
flowchart LR
    subgraph A[4-year lock]
        A1[t=0 → 1000 ve] --> A2[t=2y → 500 ve] --> A3[t=4y → 0 ve]
    end
    subgraph B[1-year lock]
        B1[t=0 → 250 ve] --> B2[t=6m → 125 ve] --> B3[t=1y → 0 ve]
    end
```

## Data structures

```solidity theme={"system"}
struct Lock {
    int128  amount;     // NOTA amount locked (int for slope math)
    uint64  end;        // unlock timestamp (rounded to weekly epoch)
    uint64  startedAt;
}

struct Point {
    int128 bias;       // current balance at block (ve value)
    int128 slope;      // slope of decay (ve per second, negative)
    uint64 ts;         // timestamp of point
    uint64 blk;        // block number
}
```

Per-user point history and a global point history are maintained, mirroring the canonical veCRV layout. Global history enables historical voting-weight queries for proposals that snapshot at a block.

## Functions

### `createLock`

```solidity theme={"system"}
function createLock(uint256 amount, uint256 unlockTime) external;
```

Transfers `amount` NOTA from the caller and creates a lock ending at `unlockTime` (rounded down to the nearest weekly boundary). Reverts if:

* The caller already has a lock.
* `amount == 0`.
* `unlockTime <= block.timestamp`.
* `unlockTime - block.timestamp > MAXTIME`.
* `unlockTime - block.timestamp < MIN_LOCK_TIME`.

Emits `LockCreated(user, amount, unlockTime)`.

### `increaseLockAmount`

```solidity theme={"system"}
function increaseLockAmount(uint256 amount) external;
```

Adds `amount` NOTA to the caller's existing lock. Unlock time is unchanged. Reverts if the lock has expired. Emits `LockIncreased(user, amount, newTotal)`.

### `extendLock`

```solidity theme={"system"}
function extendLock(uint256 newUnlockTime) external;
```

Pushes the unlock time forward. Reverts if:

* `newUnlockTime <= currentLock.end`.
* `newUnlockTime - block.timestamp > MAXTIME`.

Both the voting power at current time and at subsequent times are recomputed. Emits `LockExtended(user, oldEnd, newEnd)`.

### `withdraw`

```solidity theme={"system"}
function withdraw() external;
```

After the lock has expired, withdraws the full locked amount to the caller. Emits `LockWithdrawn(user, amount)`.

### `balanceOf`

```solidity theme={"system"}
function balanceOf(address user) public view returns (uint256);
function balanceOfAt(address user, uint256 blockNumber) external view returns (uint256);
```

`balanceOf` returns the current veNOTA balance. `balanceOfAt` returns the veNOTA balance at a historical block, used by governance for snapshot voting.

### `totalSupply`

```solidity theme={"system"}
function totalSupply() external view returns (uint256);
function totalSupplyAt(uint256 blockNumber) external view returns (uint256);
```

Returns the aggregate veNOTA supply, used as the denominator for quorum computations.

## Non-transferability

The contract rejects all transfers:

```solidity theme={"system"}
function transfer(address, uint256) public pure override returns (bool) {
    revert("veNOTA: non-transferable");
}
function transferFrom(address, address, uint256) public pure override returns (bool) {
    revert("veNOTA: non-transferable");
}
```

Governance power cannot be bought or sold; it must be earned by locking.

## Integration points

* **Governance.** Proposal voting weight is `veNOTA.balanceOfAt(voter, proposalBlock)`.
* **Validator reward boost.** Validators who lock additional NOTA receive a boost on attestation rewards proportional to their veNOTA balance.
* **Dispute bond scaling.** Disputants' required bond can scale inversely with veNOTA balance to reward long-term commitment.
* **Staking synergy.** Validators' own staked NOTA in [ValidatorStaking](validator-staking.md) does not count toward veNOTA; the two contracts are independent.

### Boost formula (illustrative)

A validator's effective attestation reward:

```
boost = min(2.5, 1 + 1.5 * (veNOTA_validator / stake_validator) / R)
```

where `R` is a governance parameter (default 1.0). A validator with equal veNOTA and stake receives the full 2.5× boost; one with no lock receives 1.0×. The exact boost curve and ceiling are set at initialization and changeable by governance.

## Checkpointing

Every state change (`createLock`, `increaseLockAmount`, `extendLock`, `withdraw`) writes a user point and a global point. Points form a piecewise-linear representation of the decay curve. The contract maintains `slopeChanges[week]` to handle lock expiries efficiently when updating the global supply.

```solidity theme={"system"}
function _checkpoint(address user, Lock memory oldLock, Lock memory newLock) internal;
```

The internal checkpoint is identical to Curve's canonical implementation with gas micro-optimizations.

## Events

```solidity theme={"system"}
event LockCreated(address indexed user, uint256 amount, uint256 unlockTime);
event LockIncreased(address indexed user, uint256 amount, uint256 newTotal);
event LockExtended(address indexed user, uint256 oldEnd, uint256 newEnd);
event LockWithdrawn(address indexed user, uint256 amount);
```

## SDK usage

```typescript theme={"system"}
import { Notareum } from "@notareum/sdk";

const ntm = Notareum({ provider, signer, contracts });

// Lock 10000 NOTA for 2 years
await ntm.nota.approve(ntm.governance.address, parseNota("10000"));
await ntm.governance.createLock(
  parseNota("10000"),
  Math.floor(Date.now() / 1000) + 2 * 365 * 86400
);

// Add more NOTA to the existing lock
await ntm.governance.increaseLockAmount(parseNota("5000"));

// Extend the unlock time by 1 year
const lock = await ntm.governance.getLock(myAddr);
await ntm.governance.extendLock(lock.end + 365 * 86400);

// Current voting power
const bal = await ntm.governance.balanceOf(myAddr);

// Historical power at proposal snapshot
const weightAt = await ntm.governance.balanceOfAt(myAddr, proposal.snapshotBlock);
```

## Invariants

1. `lock.amount` for an existing lock is monotonically non-decreasing until withdrawal.
2. `lock.end` is monotonically non-decreasing until withdrawal; it can never be pulled forward.
3. `end - startedAt <= MAXTIME` at lock creation or extension.
4. `balanceOf(user) == 0` after the lock end has passed and withdrawal has occurred.
5. The contract's NOTA balance equals the sum of all outstanding `lock.amount`.

## Related pages

* [NOTA Token](nota-token.md)
* [ValidatorStaking](validator-staking.md)
* [AccessManager](access-manager.md)
* [Governance protocol doc](../protocol/governance.md)