0
# Finance
1

2
Token vesting and financial management contracts for controlled token distribution over time.
3

4
## Capabilities
5

6
### Vesting Wallet
7

8
Linear and cliff-based token vesting with customizable schedules and beneficiary management.
9

10
```solidity { .api }
11
/**
12
 * Vesting wallet that releases tokens linearly over time
13
 */
14
contract VestingWallet is Context, Ownable {
15
    constructor(address beneficiary, uint64 startTimestamp, uint64 durationSeconds);
16
    function start() public view virtual returns (uint256);
17
    function duration() public view virtual returns (uint256);
18
    function end() public view virtual returns (uint256);
19
    function released() public view virtual returns (uint256);
20
    function released(address token) public view virtual returns (uint256);
21
    function releasable() public view virtual returns (uint256);
22
    function releasable(address token) public view virtual returns (uint256);
23
    function release() public virtual;
24
    function release(address token) public virtual;
25
    function vestedAmount(uint64 timestamp) public view virtual returns (uint256);
26
    function vestedAmount(address token, uint64 timestamp) public view virtual returns (uint256);
27
}
28
```
29

30
**Usage Examples:**
31

32
```solidity
33
import "@openzeppelin/contracts/finance/VestingWallet.sol";
34

35
// Create a 4-year vesting wallet
36
VestingWallet vestingWallet = new VestingWallet(
37
    beneficiary,
38
    block.timestamp,  // Start immediately
39
    4 * 365 * 24 * 60 * 60  // 4 years in seconds
40
);
41

42
// Fund the vesting wallet
43
vestingWallet.transfer(1000 ether);
44

45
// Release vested tokens
46
vestingWallet.release();
47

48
// Check releasable amount
49
uint256 releasable = vestingWallet.releasable();
50
```
51

52
### Vesting Wallet with Cliff
53

54
Enhanced vesting wallet with cliff period functionality.
55

56
```solidity { .api }
57
/**
58
 * Vesting wallet with cliff period before any tokens are released
59
 */
60
contract VestingWalletCliff is VestingWallet {
61
    constructor(address beneficiary, uint64 startTimestamp, uint64 durationSeconds, uint64 cliffSeconds);
62
    function cliff() public view virtual returns (uint256);
63
    function vestedAmount(uint64 timestamp) public view virtual override returns (uint256);
64
    function vestedAmount(address token, uint64 timestamp) public view virtual override returns (uint256);
65
}
66
```
67

68
**Usage Examples:**
69

70
```solidity
71
import "@openzeppelin/contracts/finance/VestingWalletCliff.sol";
72

73
// Create vesting with 1-year cliff, 4-year total
74
VestingWalletCliff cliffVesting = new VestingWalletCliff(
75
    beneficiary,
76
    block.timestamp,
77
    4 * 365 * 24 * 60 * 60,  // 4 years total
78
    1 * 365 * 24 * 60 * 60   // 1 year cliff
79
);
80

81
// Before cliff: releasable amount is 0
82
// After cliff: linear vesting begins
83
```
84

85
## Finance Utilities
86

87
### Vesting Schedule Management
88

89
Utilities for managing complex vesting schedules and calculations.
90

91
```solidity { .api }
92
/**
93
 * Vesting calculation utilities
94
 */
95
library VestingUtils {
96
    function calculateVestedAmount(uint256 totalAllocation, uint64 start, uint64 duration, uint64 cliff, uint64 timestamp) internal pure returns (uint256);
97
    function calculateReleasableAmount(uint256 totalAllocation, uint256 released, uint64 start, uint64 duration, uint64 cliff, uint64 timestamp) internal pure returns (uint256);
98
    function isCliffReached(uint64 start, uint64 cliff, uint64 timestamp) internal pure returns (bool);
99
    function getVestingProgress(uint64 start, uint64 duration, uint64 timestamp) internal pure returns (uint256 progress);
100
}
101
```
102

103
## Types
104

105
```solidity { .api }
106
/**
107
 * Vesting schedule information
108
 */
109
struct VestingSchedule {
110
    address beneficiary;
111
    uint64 start;
112
    uint64 duration;
113
    uint64 cliff;
114
    uint256 totalAmount;
115
    uint256 released;
116
    bool revocable;
117
}
118

119
/**
120
 * Token release events
121
 */
122
event EtherReleased(uint256 amount);
123
event ERC20Released(address indexed token, uint256 amount);
124

125
/**
126
 * Vesting errors
127
 */
128
error VestingInvalidBeneficiary(address beneficiary);
129
error VestingInvalidDuration(uint64 duration);
130
error VestingInvalidCliff(uint64 cliff);
131
error VestingNoTokensReleasable();
132
error VestingInsufficientBalance(uint256 available, uint256 required);
133
```