> ## 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.

# RoyaltyModule

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

```solidity theme={null}
ILicenseRegistry public immutable LICENSE_REGISTRY
```

The address of the License Registry contract that tracks license terms and tokens.

### DISPUTE\_MODULE

```solidity theme={null}
IDisputeModule public immutable DISPUTE_MODULE
```

The address of the Dispute Module contract that handles dispute resolution.

### licensingModule

```solidity theme={null}
address licensingModule
```

The address of the Licensing Module contract.

### isWhitelistedRoyaltyPolicy

```solidity theme={null}
mapping(address royaltyPolicy => bool isWhitelisted) isWhitelistedRoyaltyPolicy
```

Indicates if a royalty policy is whitelisted.

### isWhitelistedRoyaltyToken

```solidity theme={null}
mapping(address token => bool) isWhitelistedRoyaltyToken
```

Indicates if a royalty token is whitelisted.

### royaltyPolicies

```solidity theme={null}
mapping(address ipId => address royaltyPolicy) royaltyPolicies
```

Maps IP IDs to their royalty policies.

## Functions

### initialize

```solidity theme={null}
function initialize(address accessManager) external initializer
```

Initializer for this implementation contract.

**Parameters:**

* `accessManager`: The address of the protocol admin roles contract.

### setLicensingModule

```solidity theme={null}
function setLicensingModule(address licensing) external restricted
```

Sets the licensing module.

**Parameters:**

* `licensing`: The address of the license module.

### whitelistRoyaltyPolicy

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
function licensingModule() external view returns (address)
```

Returns the licensing module address.

**Returns:**

* The address of the licensing module.

### isWhitelistedRoyaltyPolicy

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
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

```solidity theme={null}
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.