OpenSea Collection Fix & Minor Refactors

contracts/interfaces/modules/licensing/ILicensingModule.sol

@@ -3,7 +3,7 @@ pragma solidity ^0.8.23;
 
 import { Licensing } from "../../../lib/Licensing.sol";
 import { IModule } from "../base/IModule.sol";
-import { RoyaltyModule } from "../../../modules/royalty-module/RoyaltyModule.sol";
+import { RoyaltyModule } from "../../../modules/royalty/RoyaltyModule.sol";
 import { ILicenseRegistry } from "../../registries/ILicenseRegistry.sol";
 import { IDisputeModule } from "../dispute/IDisputeModule.sol";
 

contracts/interfaces/modules/royalty/IRoyaltyModule.sol

@@ -15,12 +15,6 @@ interface IRoyaltyModule is IModule {
     /// @param allowed Indicates if the royalty token is whitelisted or not
     event RoyaltyTokenWhitelistUpdated(address token, bool allowed);
 
-    /// @notice Event emitted when a royalty policy is set
-    /// @param ipId The ID of IP asset
-    /// @param royaltyPolicy The address of the royalty policy
-    /// @param data The data to initialize the policy
-    event RoyaltyPolicySet(address ipId, address royaltyPolicy, bytes data);
-
     /// @notice Event emitted when royalties are paid
     /// @param receiverIpId The ID of IP asset that receives the royalties
     /// @param payerIpId The ID of IP asset that pays the royalties

contracts/interfaces/modules/royalty/policies/IAncestorsVaultLAP.sol

@@ -17,11 +17,11 @@ interface IAncestorsVaultLAP {
     /// @notice Returns the canonical RoyaltyPolicyLAP
     function ROYALTY_POLICY_LAP() external view returns (IRoyaltyPolicyLAP);
 
-    /// @notice Allows an ancestor IP asset to claim their Royalty NFTs and accrued royalties
-    /// @param ipId The ipId of the IP asset
-    /// @param claimerIpId The ipId of the claimer
-    /// @param ancestors The ancestors of the IP
-    /// @param ancestorsRoyalties The royalties of the ancestors
+    /// @notice Claims all available royalty nfts and accrued royalties for an ancestor of a given ipId
+    /// @param ipId The ipId of the ancestors vault to claim from
+    /// @param claimerIpId The claimer ipId is the ancestor address that wants to claim
+    /// @param ancestors The ancestors for the selected ipId
+    /// @param ancestorsRoyalties The royalties of the ancestors for the selected ipId
     /// @param withdrawETH Indicates if the claimer wants to withdraw ETH
     /// @param tokens The ERC20 tokens to withdraw
     function claim(

contracts/interfaces/modules/royalty/policies/IRoyaltyPolicy.sol

@@ -5,15 +5,15 @@ pragma solidity ^0.8.23;
 interface IRoyaltyPolicy {
     /// @notice Executes royalty related logic on minting a license
     /// @dev Enforced to be only callable by RoyaltyModule
-    /// @param ipId The children ipId that is being linked to parents
+    /// @param ipId The ipId whose license is being minted (licensor)
     /// @param licenseData The license data custom to each the royalty policy
     /// @param externalData The external data custom to each the royalty policy
     function onLicenseMinting(address ipId, bytes calldata licenseData, bytes calldata externalData) external;
 
     /// @notice Executes royalty related logic on linking to parents
     /// @dev Enforced to be only callable by RoyaltyModule
     /// @param ipId The children ipId that is being linked to parents
-    /// @param parentIpIds The selected parent ipIds
+    /// @param parentIpIds The parent ipIds that the children ipId is being linked to
     /// @param licenseData The license data custom to each the royalty policy
     /// @param externalData The external data custom to each the royalty policy
     function onLinkToParents(
@@ -23,9 +23,9 @@ interface IRoyaltyPolicy {
         bytes calldata externalData
     ) external;
 
-    /// @notice Allows the caller to pay royalty to the given IP asset
-    /// @param caller The caller
-    /// @param ipId The ID of the IP asset
+    /// @notice Allows the caller to pay royalties to the given IP asset
+    /// @param caller The caller is the address from which funds will transferred from
+    /// @param ipId The ipId of the receiver of the royalties
     /// @param token The token to pay
     /// @param amount The amount to pay
     function onRoyaltyPayment(address caller, address ipId, address token, uint256 amount) external;

contracts/interfaces/modules/royalty/policies/IRoyaltyPolicyLAP.sol

@@ -7,13 +7,20 @@ import { IRoyaltyPolicy } from "../../../../interfaces/modules/royalty/policies/
 
 /// @title RoyaltyPolicy interface
 interface IRoyaltyPolicyLAP is IRoyaltyPolicy {
+    /// @notice Initializes a royalty policy LAP for a given IP asset
+    /// @param targetAncestors The expected ancestors addresses of an ipId
+    /// @param targetRoyaltyAmount The expected royalties of each of the ancestors for a given ipId
+    /// @param parentAncestors1 The addresses of the ancestors of the first parent
+    /// @param parentAncestors2 The addresses of the ancestors of the second parent
+    /// @param parentAncestorsRoyalties1 The royalties of each of the ancestors of the first parent
+    /// @param parentAncestorsRoyalties2 The royalties of each of the ancestors of the second parent
     struct InitParams {
-        address[] targetAncestors; // the expected ancestors of an ipId
-        uint32[] targetRoyaltyAmount; // the expected royalties of each of the ancestors for an ipId
-        address[] parentAncestors1; // all the ancestors of the first parent
-        address[] parentAncestors2; // all the ancestors of the second parent
-        uint32[] parentAncestorsRoyalties1; // the royalties of each of the ancestors for the first parent
-        uint32[] parentAncestorsRoyalties2; // the royalties of each of the ancestors for the second parent
+        address[] targetAncestors;
+        uint32[] targetRoyaltyAmount;
+        address[] parentAncestors1;
+        address[] parentAncestors2;
+        uint32[] parentAncestorsRoyalties1;
+        uint32[] parentAncestorsRoyalties2;
     }
 
     /// @notice Event emitted when a policy is initialized
@@ -34,11 +41,11 @@ interface IRoyaltyPolicyLAP is IRoyaltyPolicy {
 
     /// @notice Returns the royalty data for a given IP asset
     /// @param ipId The ID of the IP asset
-    /// @return isUnlinkable Indicates if the ipId is unlinkable
-    /// @return splitClone The split clone address
-    /// @return ancestorsVault The ancestors vault address
-    /// @return royaltyStack The royalty stack
-    /// @return ancestorsHash The unique ancestors hash
+    /// @return isUnlinkable Indicates if the ipId is unlinkable to new parents
+    /// @return splitClone The address of the liquid split clone contract for a given ipId
+    /// @return ancestorsVault The address of the ancestors vault contract for a given ipId
+    /// @return royaltyStack The royalty stack of a given ipId is the sum of the royalties to be paid to each ancestors
+    /// @return ancestorsHash The hash of the unique ancestors addresses and royalties arrays
     function royaltyData(
         address ipId
     )
@@ -79,10 +86,12 @@ interface IRoyaltyPolicyLAP is IRoyaltyPolicy {
 
     /// @notice Distributes funds internally so that accounts holding the royalty nfts at distribution moment can
     /// claim afterwards
-    /// @param ipId The ipId
+    /// @dev This call will revert if the caller holds all the royalty nfts of the ipId - in that case can call
+    /// claimFromIpPoolAsTotalRnftOwner() instead
+    /// @param ipId The ipId whose received funds will be distributed
     /// @param token The token to distribute
     /// @param accounts The accounts to distribute to
-    /// @param distributorAddress The distributor address
+    /// @param distributorAddress The distributor address (if any)
     function distributeIpPoolFunds(
         address ipId,
         address token,
@@ -91,22 +100,25 @@ interface IRoyaltyPolicyLAP is IRoyaltyPolicy {
     ) external;
 
     /// @notice Claims the available royalties for a given address
+    /// @dev If there are no funds available in split main contract but there are funds in the split clone contract
+    /// then a distributeIpPoolFunds() call should precede this call
     /// @param account The account to claim for
     /// @param withdrawETH The amount of ETH to withdraw
     /// @param tokens The tokens to withdraw
     function claimFromIpPool(address account, uint256 withdrawETH, ERC20[] calldata tokens) external;
 
     /// @notice Claims the available royalties for a given address that holds all the royalty nfts of an ipId
-    /// @param ipId The ipId
+    /// @dev This call will revert if the caller does not hold all the royalty nfts of the ipId
+    /// @param ipId The ipId whose received funds will be distributed
     /// @param withdrawETH The amount of ETH to withdraw
     /// @param token The token to withdraw
     function claimFromIpPoolAsTotalRnftOwner(address ipId, uint256 withdrawETH, address token) external;
 
-    /// @notice Claims all available royalty nfts and accrued royalties for an ancestor of a given ipId
-    /// @param ipId The ipId
-    /// @param claimerIpId The claimer ipId
-    /// @param ancestors The ancestors of the IP
-    /// @param ancestorsRoyalties The royalties of the ancestors
+    /// @notice Claims available royalty nfts and accrued royalties for an ancestor of a given ipId
+    /// @param ipId The ipId of the ancestors vault to claim from
+    /// @param claimerIpId The claimer ipId is the ancestor address that wants to claim
+    /// @param ancestors The ancestors for the selected ipId
+    /// @param ancestorsRoyalties The royalties of the ancestors for the selected ipId
     /// @param withdrawETH Indicates if the claimer wants to withdraw ETH
     /// @param tokens The ERC20 tokens to withdraw
     function claimFromAncestorsVault(

contracts/modules/licensing/LicensingModule.sol

@@ -18,7 +18,7 @@ import { Errors } from "../../lib/Errors.sol";
 import { DataUniqueness } from "../../lib/DataUniqueness.sol";
 import { Licensing } from "../../lib/Licensing.sol";
 import { IPAccountChecker } from "../../lib/registries/IPAccountChecker.sol";
-import { RoyaltyModule } from "../../modules/royalty-module/RoyaltyModule.sol";
+import { RoyaltyModule } from "../../modules/royalty/RoyaltyModule.sol";
 import { AccessControlled } from "../../access/AccessControlled.sol";
 import { LICENSING_MODULE_KEY } from "../../lib/modules/Module.sol";
 import { BaseModule } from "../BaseModule.sol";

contracts/modules/royalty-module/RoyaltyModule.sol → contracts/modules/royalty/RoyaltyModule.sol

@@ -132,8 +132,8 @@ contract RoyaltyModule is IRoyaltyModule, Governable, ReentrancyGuard, BaseModul
     }
 
     /// @notice Allows the function caller to pay royalties to the receiver IP asset on behalf of the payer IP asset.
-    /// @param receiverIpId The ID of the IP asset that receives the royalties
-    /// @param payerIpId The ID of the IP asset that pays the royalties
+    /// @param receiverIpId The ipId that receives the royalties
+    /// @param payerIpId The ipId that pays the royalties
     /// @param token The token to use to pay the royalties
     /// @param amount The amount to pay
     function payRoyaltyOnBehalf(

contracts/modules/royalty-module/policies/AncestorsVaultLAP.sol → contracts/modules/royalty/policies/AncestorsVaultLAP.sol

@@ -15,7 +15,7 @@ import { ArrayUtils } from "../../../lib/ArrayUtils.sol";
 import { Errors } from "../../../lib/Errors.sol";
 
 /// @title Liquid Absolute Percentage Policy Ancestors Vault
-/// @notice The ancestors vault allows parents and grandparents to claim their share
+/// @notice The ancestors vault allows parents and grandparents to claim their share of
 ///         the royalty nfts of their children and grandchildren along with any accrued royalties.
 contract AncestorsVaultLAP is IAncestorsVaultLAP, ERC1155Holder, ReentrancyGuard {
     using SafeERC20 for IERC20;
@@ -32,12 +32,11 @@ contract AncestorsVaultLAP is IAncestorsVaultLAP, ERC1155Holder, ReentrancyGuard
         ROYALTY_POLICY_LAP = IRoyaltyPolicyLAP(royaltyPolicyLAP);
     }
 
-    // TODO: double check everything given this is a permissionless call
-    /// @notice Allows an ancestor IP asset to claim their Royalty NFTs and accrued royalties
-    /// @param ipId The ipId of the IP asset
-    /// @param claimerIpId The ipId of the claimer
-    /// @param ancestors The ancestors of the IP
-    /// @param ancestorsRoyalties The royalties of the ancestors
+    /// @notice Claims all available royalty nfts and accrued royalties for an ancestor of a given ipId
+    /// @param ipId The ipId of the ancestors vault to claim from
+    /// @param claimerIpId The claimer ipId is the ancestor address that wants to claim
+    /// @param ancestors The ancestors for the selected ipId
+    /// @param ancestorsRoyalties The royalties of the ancestors for the selected ipId
     /// @param withdrawETH Indicates if the claimer wants to withdraw ETH
     /// @param tokens The ERC20 tokens to withdraw
     function claim(

contracts/modules/royalty-module/policies/RoyaltyPolicyLAP.sol → contracts/modules/royalty/policies/RoyaltyPolicyLAP.sol

@@ -27,8 +27,8 @@ contract RoyaltyPolicyLAP is IRoyaltyPolicyLAP, Governable, ERC1155Holder, Reent
     /// @param isUnlinkableToParents Indicates if the ipId is unlinkable to new parents
     /// @param splitClone The address of the liquid split clone contract for a given ipId
     /// @param ancestorsVault The address of the ancestors vault contract for a given ipId
-    /// @param royaltyStack The royalty stack for a given ipId is the sum of the royalties to be paid to all its parents
-    /// @param ancestorsHash The hash of the unique ancestors array
+    /// @param royaltyStack The royalty stack of a given ipId is the sum of the royalties to be paid to each ancestors
+    /// @param ancestorsHash The hash of the unique ancestors addresses and royalties arrays
     struct LAPRoyaltyData {
         bool isUnlinkableToParents;
         address splitClone;
@@ -103,7 +103,7 @@ contract RoyaltyPolicyLAP is IRoyaltyPolicyLAP, Governable, ERC1155Holder, Reent
 
     /// @notice Executes royalty related logic on minting a license
     /// @dev Enforced to be only callable by RoyaltyModule
-    /// @param ipId The children ipId that is being linked to parents
+    /// @param ipId The ipId whose license is being minted (licensor)
     /// @param licenseData The license data custom to each the royalty policy
     /// @param externalData The external data custom to each the royalty policy
     function onLicenseMinting(
@@ -146,7 +146,7 @@ contract RoyaltyPolicyLAP is IRoyaltyPolicyLAP, Governable, ERC1155Holder, Reent
     /// @notice Executes royalty related logic on linking to parents
     /// @dev Enforced to be only callable by RoyaltyModule
     /// @param ipId The children ipId that is being linked to parents
-    /// @param parentIpIds The selected parent ipIds
+    /// @param parentIpIds The parent ipIds that the children ipId is being linked to
     /// @param licenseData The license data custom to each the royalty policy
     /// @param externalData The external data custom to each the royalty policy
     function onLinkToParents(
@@ -162,8 +162,8 @@ contract RoyaltyPolicyLAP is IRoyaltyPolicyLAP, Governable, ERC1155Holder, Reent
 
     /// @dev Initializes the royalty policy for a given IP asset.
     /// @dev Enforced to be only callable by RoyaltyModule
-    /// @param ipId The ipId
-    /// @param parentIpIds The selected parent ipIds
+    /// @param ipId The to initialize the policy for
+    /// @param parentIpIds The parent ipIds that the children ipId is being linked to (if any)
     /// @param licenseData The license data custom to each the royalty policy
     /// @param externalData The external data custom to each the royalty policy
     function _initPolicy(
@@ -216,9 +216,9 @@ contract RoyaltyPolicyLAP is IRoyaltyPolicyLAP, Governable, ERC1155Holder, Reent
         );
     }
 
-    /// @notice Allows the caller to pay royalty to the given IP asset
-    /// @param caller The caller
-    /// @param ipId The ID of the IP asset
+    /// @notice Allows the caller to pay royalties to the given IP asset
+    /// @param caller The caller is the address from which funds will transferred from
+    /// @param ipId The ipId of the receiver of the royalties
     /// @param token The token to pay
     /// @param amount The amount to pay
     function onRoyaltyPayment(address caller, address ipId, address token, uint256 amount) external onlyRoyaltyModule {
@@ -228,10 +228,12 @@ contract RoyaltyPolicyLAP is IRoyaltyPolicyLAP, Governable, ERC1155Holder, Reent
 
     /// @notice Distributes funds internally so that accounts holding the royalty nfts at distribution moment can
     /// claim afterwards
-    /// @param ipId The ipId
+    /// @dev This call will revert if the caller holds all the royalty nfts of the ipId - in that case can call
+    /// claimFromIpPoolAsTotalRnftOwner() instead
+    /// @param ipId The ipId whose received funds will be distributed
     /// @param token The token to distribute
     /// @param accounts The accounts to distribute to
-    /// @param distributorAddress The distributor address
+    /// @param distributorAddress The distributor address (if any)
     function distributeIpPoolFunds(
         address ipId,
         address token,
@@ -242,6 +244,8 @@ contract RoyaltyPolicyLAP is IRoyaltyPolicyLAP, Governable, ERC1155Holder, Reent
     }
 
     /// @notice Claims the available royalties for a given address
+    /// @dev If there are no funds available in split main contract but there are funds in the split clone contract
+    /// then a distributeIpPoolFunds() call should precede this call
     /// @param account The account to claim for
     /// @param withdrawETH The amount of ETH to withdraw
     /// @param tokens The tokens to withdraw
@@ -250,7 +254,8 @@ contract RoyaltyPolicyLAP is IRoyaltyPolicyLAP, Governable, ERC1155Holder, Reent
     }
 
     /// @notice Claims the available royalties for a given address that holds all the royalty nfts of an ipId
-    /// @param ipId The ipId
+    /// @dev This call will revert if the caller does not hold all the royalty nfts of the ipId
+    /// @param ipId The ipId whose received funds will be distributed
     /// @param withdrawETH The amount of ETH to withdraw
     /// @param token The token to withdraw
     function claimFromIpPoolAsTotalRnftOwner(address ipId, uint256 withdrawETH, address token) external nonReentrant {
@@ -287,10 +292,10 @@ contract RoyaltyPolicyLAP is IRoyaltyPolicyLAP, Governable, ERC1155Holder, Reent
     }
 
     /// @notice Claims all available royalty nfts and accrued royalties for an ancestor of a given ipId
-    /// @param ipId The ipId
-    /// @param claimerIpId The claimer ipId
-    /// @param ancestors The ancestors of the IP
-    /// @param ancestorsRoyalties The royalties of the ancestors
+    /// @param ipId The ipId of the ancestors vault to claim from
+    /// @param claimerIpId The claimer ipId is the ancestor address that wants to claim
+    /// @param ancestors The ancestors for the selected ipId
+    /// @param ancestorsRoyalties The royalties of the ancestors for the selected ipId
     /// @param withdrawETH Indicates if the claimer wants to withdraw ETH
     /// @param tokens The ERC20 tokens to withdraw
     function claimFromAncestorsVault(