Skip to main content

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.

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

address ipId
The IP ID to which this royalty vault belongs.

​
tokens

EnumerableSet.AddressSet tokens
The set of revenue tokens in the vault.

​
unclaimedRoyaltyTokens

uint32 unclaimedRoyaltyTokens
The amount of unclaimed royalty tokens.

​
lastSnapshotTimestamp

uint256 lastSnapshotTimestamp
The timestamp of the last snapshot.

​
ancestorsVaultAmount

mapping(address token => uint256 amount) ancestorsVaultAmount
Maps token addresses to the amount in the ancestors vault.

​
isCollectedByAncestor

mapping(address ancestorIpId => bool isCollected) isCollectedByAncestor
Indicates whether an ancestor has collected their royalty tokens.

​
claimVaultAmount

mapping(address token => uint256 amount) claimVaultAmount
Maps token addresses to the amount in the claim vault.

​
claimableAtSnapshot

mapping(uint256 snapshotId => mapping(address token => uint256 amount)) claimableAtSnapshot
Maps snapshot IDs and token addresses to the claimable amount at that snapshot.

​
unclaimedAtSnapshot

mapping(uint256 snapshotId => uint32 amount) unclaimedAtSnapshot
Maps snapshot IDs to the amount of unclaimed tokens at that snapshot.

​
isClaimedAtSnapshot

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

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

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

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

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

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

function ipId() external view returns (address)
Returns the IP ID to which this royalty vault belongs. Returns:
  • The IP ID address.

​
unclaimedRoyaltyTokens

function unclaimedRoyaltyTokens() external view returns (uint32)
Returns the amount of unclaimed royalty tokens. Returns:
  • The amount of unclaimed royalty tokens.

​
lastSnapshotTimestamp

function lastSnapshotTimestamp() external view returns (uint256)
Returns the last snapshotted timestamp. Returns:
  • The last snapshot timestamp.

​
ancestorsVaultAmount

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

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

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

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

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

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

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.