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.