Merge pull request #105 from OpenZeppelin/feat/copy-docs-for-v3.0.0

Cairo: duplicate 2.x dir for 3.x

Author: ericnordelo

content/contracts-cairo/3.x/access.mdx

@@ -0,0 +1,328 @@
+---
+title: Finance
+---
+
+import { UMBRELLA_VERSION } from "../utils/constants.js";
+
+This crate includes primitives for financial systems.
+
+## Interfaces
+
+### `IVesting` [toc] [#IVesting]
+
+<APIGithubLinkHeader
+  moduleName="IVesting"
+  link={`https://github.com/OpenZeppelin/cairo-contracts/blob/${UMBRELLA_VERSION}/packages/finance/src/vesting/interface.cairo`}
+/>
+
+```rust
+use openzeppelin_finance::vesting::interface::IVesting;
+```
+
+Common interface for contracts implementing the vesting functionality.
+
+Functions
+
+- [`start()`](#IVesting-start)
+- [`cliff()`](#IVesting-cliff)
+- [`duration()`](#IVesting-duration)
+- [`end()`](#IVesting-end)
+- [`released(token)`](#IVesting-released)
+- [`releasable(token)`](#IVesting-releasable)
+- [`vested_amount(token, timestamp)`](#IVesting-vested_amount)
+- [`release(token)`](#IVesting-release)
+
+Events
+
+- [`AmountReleased(token, amount)`](#IVesting-AmountReleased)
+
+#### Functions [!toc] [#IVesting-Functions]
+
+<APIItem
+  functionSignature="start() → u64"
+  id="IVesting-start"
+  kind="external"
+>
+Returns the timestamp marking the beginning of the vesting period.
+</APIItem>
+
+<APIItem
+  functionSignature="cliff() → u64"
+  id="IVesting-cliff"
+  kind="external"
+>
+Returns the timestamp marking the end of the cliff period.
+</APIItem>
+
+<APIItem
+  functionSignature="duration() → u64"
+  id="IVesting-duration"
+  kind="external"
+>
+Returns the total duration of the vesting period.
+</APIItem>
+
+<APIItem
+  functionSignature="end() → u64"
+  id="IVesting-end"
+  kind="external"
+>
+Returns the timestamp marking the end of the vesting period.
+</APIItem>
+
+<APIItem
+  functionSignature="released(token: ContractAddress) → u256"
+  id="IVesting-released"
+  kind="external"
+>
+Returns the already released amount for a given `token`.
+</APIItem>
+
+<APIItem
+  functionSignature="releasable(token: ContractAddress) → u256"
+  id="IVesting-releasable"
+  kind="external"
+>
+Returns the amount of a given `token` that can be released at the time of the call.
+</APIItem>
+
+<APIItem
+  functionSignature="vested_amount(token: ContractAddress, timestamp: u64) → u256"
+  id="IVesting-vested_amount"
+  kind="external"
+>
+Returns the total vested amount of a specified `token` at a given `timestamp`.
+</APIItem>
+
+<APIItem
+  functionSignature="release(token: ContractAddress) → u256"
+  id="IVesting-release"
+  kind="external"
+>
+Releases the amount of a given `token` that has already vested and returns that amount.
+
+May emit an [AmountReleased](#IVesting-AmountReleased) event.
+</APIItem>
+
+#### Events [!toc] [#IVesting-Events]
+
+<APIItem
+  functionSignature="AmountReleased(token: ContractAddress, amount: u256)"
+  id="IVesting-AmountReleased"
+  kind="event"
+>
+Emitted when vested tokens are released to the beneficiary.
+</APIItem>
+
+## [](#vesting)Vesting
+
+### `VestingComponent` [toc] [#VestingComponent]
+
+<APIGithubLinkHeader
+  moduleName="VestingComponent"
+  link={`https://github.com/OpenZeppelin/cairo-contracts/blob/${UMBRELLA_VERSION}/packages/finance/src/vesting/vesting.cairo`}
+/>
+
+```rust
+use openzeppelin_finance::vesting::VestingComponent;
+```
+
+Vesting component implementing the [`IVesting`](#IVesting) interface.
+
+Vesting Schedule Trait Implementations
+
+#### functions [!toc] [#VestingComponent-Vesting-Schedule-functions]
+
+- [`calculate_vested_amount(self, token, total_allocation, timestamp, start, duration, cliff)`](#VestingComponent-calculate_vested_amount)
+
+Embeddable Implementations
+
+#### VestingImpl [!toc] [#VestingComponent-Embeddable-Impls-VestingImpl]
+
+- [`start(self)`](#VestingComponent-start)
+- [`cliff(self)`](#VestingComponent-cliff)
+- [`duration(self)`](#VestingComponent-duration)
+- [`end(self)`](#VestingComponent-end)
+- [`released(self, token)`](#VestingComponent-released)
+- [`releasable(self, token)`](#VestingComponent-releasable)
+- [`vested_amount(self, token, timestamp)`](#VestingComponent-vested_amount)
+- [`release(self, token)`](#VestingComponent-release)
+
+Internal implementations
+
+#### InternalImpl [!toc] [#VestingComponent-InternalImpl]
+
+- [`initializer(self, start, duration, cliff_duration)`](#VestingComponent-initializer)
+- [`resolve_vested_amount(self, token, timestamp)`](#VestingComponent-resolve_vested_amount)
+
+A trait that defines the logic for calculating the vested amount based on a given timestamp.
+
+You can read more about the trait's purpose and how to use it [here](../finance#vesting-schedule).
+
+<APIItem
+  functionSignature="calculate_vested_amount(self: @ContractState, token: ContractAddress, total_allocation: u256, timestamp: u64, start: u64, duration: u64, cliff: u64) → u256"
+  id="VestingComponent-calculate_vested_amount"
+  kind="internal"
+>
+Calculates and returns the vested amount at a given `timestamp` based on the core vesting parameters.
+</APIItem>
+
+#### Functions [!toc] [#VestingComponent-Functions]
+
+<APIItem
+  functionSignature="start(self: @ContractState) → u64"
+  id="VestingComponent-start"
+  kind="external"
+>
+Returns the timestamp marking the beginning of the vesting period.
+</APIItem>
+
+<APIItem
+  functionSignature="cliff(self: @ContractState) → u64"
+  id="VestingComponent-cliff"
+  kind="external"
+>
+Returns the timestamp marking the end of the cliff period.
+</APIItem>
+
+<APIItem
+  functionSignature="duration(self: @ContractState) → u64"
+  id="VestingComponent-duration"
+  kind="external"
+>
+Returns the total duration of the vesting period.
+</APIItem>
+
+<APIItem
+  functionSignature="end(self: @ContractState) → u64"
+  id="VestingComponent-end"
+  kind="external"
+>
+Returns the timestamp marking the end of the vesting period.
+</APIItem>
+
+<APIItem
+  functionSignature="released(self: @ContractState, token: ContractAddress) → u256"
+  id="VestingComponent-released"
+  kind="external"
+>
+Returns the already released amount for a given `token`.
+</APIItem>
+
+<APIItem
+  functionSignature="releasable(self: @ContractState, token: ContractAddress) → u256"
+  id="VestingComponent-releasable"
+  kind="external"
+>
+Returns the amount of a given `token` that can be released at the time of the call.
+</APIItem>
+
+<APIItem
+  functionSignature="vested_amount(self: @ContractState, token: ContractAddress, timestamp: u64) → u256"
+  id="VestingComponent-vested_amount"
+  kind="external"
+>
+Returns the total vested amount of a specified `token` at a given `timestamp`.
+</APIItem>
+
+<APIItem
+  functionSignature="release(ref self: ContractState, token: ContractAddress) → u256"
+  id="VestingComponent-release"
+  kind="external"
+>
+Releases the amount of a given `token` that has already vested and returns that amount.
+
+If the releasable amount is zero, this function won't emit the event or attempt to transfer the tokens.
+
+Requirements:
+
+- `transfer` call to the `token` must return `true` indicating a successful transfer.
+
+May emit an [AmountReleased](#IVesting-AmountReleased) event.
+</APIItem>
+
+#### Internal functions [!toc] [#VestingComponent-Internal-Functions]
+
+<APIItem
+  functionSignature="initializer(ref self: ContractState, start: u64, duration: u64, cliff_duration: u64)"
+  id="VestingComponent-initializer"
+  kind="internal"
+>
+Initializes the component by setting the vesting `start`, `duration` and `cliff_duration`. To prevent reinitialization, this should only be used inside of a contract's constructor.
+
+Requirements:
+
+- `cliff_duration` must be less than or equal to `duration`.
+</APIItem>
+
+<APIItem
+  functionSignature="resolve_vested_amount(self: @ContractState, token: ContractAddress, timestamp: u64) → u256"
+  id="VestingComponent-resolve_vested_amount"
+  kind="internal"
+>
+Returns the vested amount that's calculated using the [VestingSchedule](#VestingComponent-Vesting-Schedule) trait implementation.
+</APIItem>
+
+### `LinearVestingSchedule` [toc] [#LinearVestingSchedule]
+
+<APIGithubLinkHeader
+  moduleName="LinearVestingSchedule"
+  link={`https://github.com/OpenZeppelin/cairo-contracts/blob/${UMBRELLA_VERSION}/packages/finance/src/vesting/vesting.cairo`}
+/>
+
+```rust
+use openzeppelin_finance::vesting::LinearVestingSchedule;
+```
+
+Defines the logic for calculating the vested amount, incorporating a cliff period. It returns 0 before the cliff ends. After the cliff period, the vested amount returned is directly proportional to the time passed since the start of the vesting schedule.
+
+## [](#presets)Presets
+
+### `VestingWallet` [toc] [#VestingWallet]
+
+<APIGithubLinkHeader
+  moduleName="VestingWallet"
+  link={`https://github.com/OpenZeppelin/cairo-contracts/blob/${UMBRELLA_VERSION}/packages/presets/src/vesting.cairo`}
+/>
+
+```rust
+use openzeppelin::presets::VestingWallet;
+```
+
+A non-upgradable contract leveraging [VestingComponent](#VestingComponent) and [OwnableComponent](./access#OwnableComponent).
+
+The contract is intentionally designed to be non-upgradable to ensure that neither the vesting initiator nor the vesting beneficiary can modify the vesting schedule without the consent of the other party.
+
+[Sierra class hash](../presets)
+
+```text
+{{VestingWalletClassHash}}
+```
+
+Constructor
+
+- [`constructor(self, beneficiary, start, duration, cliff_duration)`](#VestingWallet-constructor)
+
+Embedded Implementations
+
+VestingComponent
+
+- [`VestingImpl`](#VestingComponent-Embeddable-Impls-VestingImpl)
+
+OwnableComponent
+
+- [`OwnableMixinImpl`](./access#OwnableComponent-Mixin-Impl)
+
+#### Constructor [!toc] [#VestingWallet-constructor-section]
+
+<APIItem
+  functionSignature="constructor(ref self: ContractState, beneficiary: ContractAddress, start: u64, duration: u64, cliff_duration: u64)"
+  id="VestingWallet-constructor"
+  kind="constructor"
+>
+Initializes the vesting component by setting the vesting `start`, `duration` and `cliff_duration`. Assigns `beneficiary` as the contract owner and the vesting beneficiary.
+
+Requirements:
+
+- `cliff_duration` must be less than or equal to `duration`.
+</APIItem>