> ## Documentation Index > Fetch the complete documentation index at: https://docs.story.foundation/llms.txt > Use this file to discover all available pages before exploring further. # IPRoyaltyVault The IPRoyaltyVault contract manages the claiming of royalty and revenue tokens for a given IP. It allows token holders to claim their share of revenue tokens based on snapshots, and ancestors to collect their royalty tokens. ## State Variables ### ipId ```solidity theme={null} address ipId ``` The IP ID to which this royalty vault belongs. ### tokens ```solidity theme={null} EnumerableSet.AddressSet tokens ``` The set of revenue tokens in the vault. ### unclaimedRoyaltyTokens ```solidity theme={null} uint32 unclaimedRoyaltyTokens ``` The amount of unclaimed royalty tokens. ### lastSnapshotTimestamp ```solidity theme={null} uint256 lastSnapshotTimestamp ``` The timestamp of the last snapshot. ### ancestorsVaultAmount ```solidity theme={null} mapping(address token => uint256 amount) ancestorsVaultAmount ``` Maps token addresses to the amount in the ancestors vault. ### isCollectedByAncestor ```solidity theme={null} mapping(address ancestorIpId => bool isCollected) isCollectedByAncestor ``` Indicates whether an ancestor has collected their royalty tokens. ### claimVaultAmount ```solidity theme={null} mapping(address token => uint256 amount) claimVaultAmount ``` Maps token addresses to the amount in the claim vault. ### claimableAtSnapshot ```solidity theme={null} mapping(uint256 snapshotId => mapping(address token => uint256 amount)) claimableAtSnapshot ``` Maps snapshot IDs and token addresses to the claimable amount at that snapshot. ### unclaimedAtSnapshot ```solidity theme={null} mapping(uint256 snapshotId => uint32 amount) unclaimedAtSnapshot ``` Maps snapshot IDs to the amount of unclaimed tokens at that snapshot. ### isClaimedAtSnapshot ```solidity theme={null} mapping(uint256 snapshotId => mapping(address claimer => mapping(address token => bool isClaimed))) isClaimedAtSnapshot ``` Indicates whether a claimer has claimed a token at a specific snapshot. ## Functions ### initialize ```solidity theme={null} function initialize( string memory name, string memory symbol, uint256 totalSupply, uint32 royaltyStack, address ipId_ ) external initializer ``` Initializer for this implementation contract. **Parameters:** * `name`: The name of the royalty token. * `symbol`: The symbol of the royalty token. * `totalSupply`: The total supply of the royalty token. * `royaltyStack`: The royalty stack of the IP asset. * `ipId_`: The IP ID to which this royalty vault belongs. ### addIpRoyaltyVaultTokens ```solidity theme={null} function addIpRoyaltyVaultTokens(address token) external nonReentrant whenNotPaused returns (bool) ``` Adds a token to the royalty vault. **Parameters:** * `token`: The token address to add. **Returns:** * `isAdded`: True if the token was added, false if it was already in the vault. ### snapshot ```solidity theme={null} function snapshot() external whenNotPaused returns (uint256) ``` Takes a snapshot of the claimable revenue and royalty token amounts. **Returns:** * `snapshotId`: The ID of the snapshot. ### claimRevenueToken ```solidity theme={null} function claimRevenueToken(uint256[] calldata snapshotIds, address token) external nonReentrant whenNotPaused ``` Allows token holders to claim their share of revenue tokens. **Parameters:** * `snapshotIds`: The snapshot IDs to claim from. * `token`: The revenue token to claim. ### collectRoyaltyTokens ```solidity theme={null} function collectRoyaltyTokens(address ancestorIpId) external nonReentrant whenNotPaused ``` Allows ancestors to claim the royalty tokens and any accrued revenue tokens. **Parameters:** * `ancestorIpId`: The IP ID of the ancestor to whom the royalty tokens belong. ### ipId ```solidity theme={null} function ipId() external view returns (address) ``` Returns the IP ID to which this royalty vault belongs. **Returns:** * The IP ID address. ### unclaimedRoyaltyTokens ```solidity theme={null} function unclaimedRoyaltyTokens() external view returns (uint32) ``` Returns the amount of unclaimed royalty tokens. **Returns:** * The amount of unclaimed royalty tokens. ### lastSnapshotTimestamp ```solidity theme={null} function lastSnapshotTimestamp() external view returns (uint256) ``` Returns the last snapshotted timestamp. **Returns:** * The last snapshot timestamp. ### ancestorsVaultAmount ```solidity theme={null} function ancestorsVaultAmount(address token) external view returns (uint256) ``` Returns the amount of revenue token in the ancestors vault. **Parameters:** * `token`: The address of the revenue token. **Returns:** * The amount of revenue token in the ancestors vault. ### isCollectedByAncestor ```solidity theme={null} function isCollectedByAncestor(address ancestorIpId) external view returns (bool) ``` Indicates whether the ancestor has collected the royalty tokens. **Parameters:** * `ancestorIpId`: The ancestor IP ID address. **Returns:** * True if the ancestor has collected the royalty tokens. ### claimVaultAmount ```solidity theme={null} function claimVaultAmount(address token) external view returns (uint256) ``` Returns the amount of revenue token in the claim vault. **Parameters:** * `token`: The address of the revenue token. **Returns:** * The amount of revenue token in the claim vault. ### claimableAtSnapshot ```solidity theme={null} function claimableAtSnapshot(uint256 snapshotId, address token) external view returns (uint256) ``` Returns the amount of revenue token claimable at a given snapshot. **Parameters:** * `snapshotId`: The snapshot ID. * `token`: The address of the revenue token. **Returns:** * The amount of revenue token claimable at the snapshot. ### unclaimedAtSnapshot ```solidity theme={null} function unclaimedAtSnapshot(uint256 snapshotId) external view returns (uint32) ``` Returns the amount of unclaimed revenue tokens at the snapshot. **Parameters:** * `snapshotId`: The snapshot ID. **Returns:** * The amount of unclaimed revenue tokens at the snapshot. ### isClaimedAtSnapshot ```solidity theme={null} function isClaimedAtSnapshot(uint256 snapshotId, address claimer, address token) external view returns (bool) ``` Indicates whether the claimer has claimed the revenue tokens at a given snapshot. **Parameters:** * `snapshotId`: The snapshot ID. * `claimer`: The address of the claimer. * `token`: The address of the revenue token. **Returns:** * True if the claimer has claimed the revenue tokens at the snapshot. ### tokens ```solidity theme={null} function tokens() external view returns (address[] memory) ``` Returns the list of revenue tokens in the vault. **Returns:** * The array of revenue token addresses. ## Security Considerations The IPRoyaltyVault contract implements several security measures: 1. **Access Control**: Functions for adding tokens, taking snapshots, and claiming tokens are protected with appropriate modifiers. 2. **Reentrancy Protection**: The `nonReentrant` modifier is used on functions that handle token transfers to prevent reentrancy attacks. 3. **Pausability**: The contract can be paused in emergency situations using the `whenNotPaused` modifier. 4. **Snapshot Mechanism**: The contract uses a snapshot mechanism to ensure fair distribution of revenue tokens based on holdings at specific points in time. 5. **Claim Verification**: The contract tracks claimed tokens to prevent double-claiming by the same address.