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 RoyaltyModule is the main entry point for handling royalty payments on Story. It allows IP owners to set royalty policies for their IP assets and enables derivative IP owners to pay royalties to their parent IPs.

​
State Variables

​
LICENSE_REGISTRY

ILicenseRegistry public immutable LICENSE_REGISTRY
The address of the License Registry contract that tracks license terms and tokens.

​
DISPUTE_MODULE

IDisputeModule public immutable DISPUTE_MODULE
The address of the Dispute Module contract that handles dispute resolution.

​
licensingModule

address licensingModule
The address of the Licensing Module contract.

​
isWhitelistedRoyaltyPolicy

mapping(address royaltyPolicy => bool isWhitelisted) isWhitelistedRoyaltyPolicy
Indicates if a royalty policy is whitelisted.

​
isWhitelistedRoyaltyToken

mapping(address token => bool) isWhitelistedRoyaltyToken
Indicates if a royalty token is whitelisted.

​
royaltyPolicies

mapping(address ipId => address royaltyPolicy) royaltyPolicies
Maps IP IDs to their royalty policies.

​
Functions

​
initialize

function initialize(address accessManager) external initializer
Initializer for this implementation contract. Parameters:
  • accessManager: The address of the protocol admin roles contract.

​
setLicensingModule

function setLicensingModule(address licensing) external restricted
Sets the licensing module. Parameters:
  • licensing: The address of the license module.

​
whitelistRoyaltyPolicy

function whitelistRoyaltyPolicy(address royaltyPolicy, bool allowed) external restricted
Whitelist a royalty policy. Parameters:
  • royaltyPolicy: The address of the royalty policy.
  • allowed: Indicates if the royalty policy is whitelisted or not.

​
whitelistRoyaltyToken

function whitelistRoyaltyToken(address token, bool allowed) external restricted
Whitelist a royalty token. Parameters:
  • token: The token address.
  • allowed: Indicates if the token is whitelisted or not.

​
onLicenseMinting

function onLicenseMinting(
    address ipId,
    address royaltyPolicy,
    bytes calldata licenseData,
    bytes calldata externalData
) external nonReentrant onlyLicensingModule
Executes royalty related logic on license minting. Parameters:
  • ipId: The ipId whose license is being minted (licensor).
  • royaltyPolicy: The royalty policy address of the license being minted.
  • licenseData: The license data custom to each the royalty policy.
  • externalData: The external data custom to each the royalty policy.

​
onLinkToParents

function onLinkToParents(
    address ipId,
    address royaltyPolicy,
    address[] calldata parentIpIds,
    bytes[] memory licenseData,
    bytes calldata externalData
) external nonReentrant onlyLicensingModule
Executes royalty related logic on linking to parents. Parameters:
  • ipId: The children ipId that is being linked to parents.
  • royaltyPolicy: The common royalty policy address of all the licenses being burned.
  • parentIpIds: The parent ipIds that the children ipId is being linked to.
  • licenseData: The license data custom to each the royalty policy.
  • externalData: The external data custom to each the royalty policy.

​
payRoyaltyOnBehalf

function payRoyaltyOnBehalf(
    address receiverIpId,
    address payerIpId,
    address token,
    uint256 amount
) external nonReentrant whenNotPaused
Allows the function caller to pay royalties to the receiver IP asset on behalf of the payer IP asset. Parameters:
  • receiverIpId: The ipId that receives the royalties.
  • payerIpId: The ipId that pays the royalties.
  • token: The token to use to pay the royalties.
  • amount: The amount to pay.

​
payLicenseMintingFee

function payLicenseMintingFee(
    address receiverIpId,
    address payerAddress,
    address licenseRoyaltyPolicy,
    address token,
    uint256 amount
) external onlyLicensingModule
Allows to pay the minting fee for a license. Parameters:
  • receiverIpId: The ipId that receives the royalties.
  • payerAddress: The address that pays the royalties.
  • licenseRoyaltyPolicy: The royalty policy of the license being minted.
  • token: The token to use to pay the royalties.
  • amount: The amount to pay.

​
licensingModule

function licensingModule() external view returns (address)
Returns the licensing module address. Returns:
  • The address of the licensing module.

​
isWhitelistedRoyaltyPolicy

function isWhitelistedRoyaltyPolicy(address royaltyPolicy) external view returns (bool)
Indicates if a royalty policy is whitelisted. Parameters:
  • royaltyPolicy: The address of the royalty policy.
Returns:
  • isWhitelisted: True if the royalty policy is whitelisted.

​
isWhitelistedRoyaltyToken

function isWhitelistedRoyaltyToken(address token) external view returns (bool)
Indicates if a royalty token is whitelisted. Parameters:
  • token: The address of the royalty token.
Returns:
  • isWhitelisted: True if the royalty token is whitelisted.

​
royaltyPolicies

function royaltyPolicies(address ipId) external view returns (address)
Indicates the royalty policy for a given IP asset. Parameters:
  • ipId: The ID of IP asset.
Returns:
  • royaltyPolicy: The address of the royalty policy.

​
supportsInterface

function supportsInterface(bytes4 interfaceId) public view virtual override(BaseModule, IERC165) returns (bool)
IERC165 interface support. Parameters:
  • interfaceId: The interface identifier.
Returns:
  • Returns true if the interface is supported.

​
Security Considerations

The RoyaltyModule contract implements several security measures:
  1. Access Control: Most administrative functions are restricted to be called only by the protocol admin through the restricted modifier.
  2. Module Interaction Control: Functions like onLicenseMinting and payLicenseMintingFee can only be called by the Licensing Module through the onlyLicensingModule modifier.
  3. Reentrancy Protection: The nonReentrant modifier is used on functions that handle token transfers to prevent reentrancy attacks.
  4. Pausability: The contract can be paused in emergency situations using the whenNotPaused modifier.
  5. Whitelisting Mechanism: The contract implements whitelisting for royalty policies and tokens to ensure that only approved components can interact with the royalty system.
  6. Dispute Resolution Integration: The contract integrates with the Dispute Module to handle any disputes related to royalty payments.