Story

https://docs.story.foundation
Admin
Story is a purpose-built layer 1 blockchain designed for intellectual property, enabling creators to...
Tokens:267,948
Snippets:1,302
Trust Score:9.8
Update:11 months ago
Show doc for...
Tokens:
Raw
### Test Royalty Setup and Minting in Solidity

Source: https://docs.story.foundation/developers/smart-contracts-guide/claim-revenue

This Solidity test file demonstrates setting up IP assets, registering license terms, and minting license tokens for royalty testing in the Story Foundation ecosystem. It uses Foundry for testing with mocked components and requires a fork connection to Aeneid testnet. The code sets up contracts, mints an NFT, registers it as an IP asset, and prepares for license token minting, but does not execute full claiming; it depends on Story protocol contracts and may require adjustments for production use.

```solidity
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.26;

import { Test } from "forge-std/Test.sol";
// for testing purposes only
import { MockIPGraph } from "@storyprotocol/test/mocks/MockIPGraph.sol";
import { IPAssetRegistry } from "@storyprotocol/core/registries/IPAssetRegistry.sol";
import { LicenseRegistry } from "@storyprotocol/core/registries/LicenseRegistry.sol";
import { PILicenseTemplate } from "@storyprotocol/core/modules/licensing/PILicenseTemplate.sol";
import { RoyaltyPolicyLAP } from "@storyprotocol/core/modules/royalty/policies/LAP/RoyaltyPolicyLAP.sol";
import { PILFlavors } from "@storyprotocol/core/lib/PILFlavors.sol";
import { PILTerms } from "@storyprotocol/core/interfaces/modules/licensing/IPILicenseTemplate.sol";
import { LicensingModule } from "@storyprotocol/core/modules/licensing/LicensingModule.sol";
import { LicenseToken } from "@storyprotocol/core/LicenseToken.sol";
import { RoyaltyWorkflows } from "@storyprotocol/periphery/workflows/RoyaltyWorkflows.sol";
import { RoyaltyModule } from "@storyprotocol/core/modules/royalty/RoyaltyModule.sol";
import { MockERC20 } from "@storyprotocol/test/mocks/token/MockERC20.sol";

import { SimpleNFT } from "../src/mocks/SimpleNFT.sol";

// Run this test:
// forge test --fork-url https://aeneid.storyrpc.io/ --match-path test/5_Royalty.t.sol
contract RoyaltyTest is Test {
    address internal alice = address(0xa11ce);
    address internal bob = address(0xb0b);

    // For addresses, see https://docs.story.foundation/developers/deployed-smart-contracts
    // Protocol Core - IPAssetRegistry
    IPAssetRegistry internal IP_ASSET_REGISTRY = IPAssetRegistry(0x77319B4031e6eF1250907aa00018B8B1c67a244b);
    // Protocol Core - LicenseRegistry
    LicenseRegistry internal LICENSE_REGISTRY = LicenseRegistry(0x529a750E02d8E2f15649c13D69a465286a780e24);
    // Protocol Core - LicensingModule
    LicensingModule internal LICENSING_MODULE = LicensingModule(0x04fbd8a2e56dd85CFD5500A4A4DfA955B9f1dE6f);
    // Protocol Core - PILicenseTemplate
    PILicenseTemplate internal PIL_TEMPLATE = PILicenseTemplate(0x2E896b0b2Fdb7457499B56AAaA4AE55BCB4Cd316);
    // Protocol Core - RoyaltyPolicyLAP
    RoyaltyPolicyLAP internal ROYALTY_POLICY_LAP = RoyaltyPolicyLAP(0xBe54FB168b3c982b7AaE60dB6CF75Bd8447b390E);
    // Protocol Core - LicenseToken
    LicenseToken internal LICENSE_TOKEN = LicenseToken(0xFe3838BFb30B34170F00030B52eA4893d8aAC6bC);
    // Protocol Core - RoyaltyModule
    RoyaltyModule internal ROYALTY_MODULE = RoyaltyModule(0xD2f60c40fEbccf6311f8B47c4f2Ec6b040400086);
    // Protocol Periphery - RoyaltyWorkflows
    RoyaltyWorkflows internal ROYALTY_WORKFLOWS = RoyaltyWorkflows(0x9515faE61E0c0447C6AC6dEe5628A2097aFE1890);
    // Mock - MERC20
    MockERC20 internal MERC20 = MockERC20(0xF2104833d386a2734a4eB3B8ad6FC6812F29E38E);

    SimpleNFT public SIMPLE_NFT;
    uint256 public tokenId;
    address public ipId;
    uint256 public licenseTermsId;
    uint256 public startLicenseTokenId;
    address public childIpId;

    function setUp() public {
        // this is only for testing purposes
        // due to our IPGraph precompile not being
        // deployed on the fork
        vm.etch(address(0x0101), address(new MockIPGraph()).code);

        SIMPLE_NFT = new SimpleNFT("Simple IP NFT", "SIM");
        tokenId = SIMPLE_NFT.mint(alice);
        ipId = IP_ASSET_REGISTRY.register(block.chainid, address(SIMPLE_NFT), tokenId);

        licenseTermsId = PIL_TEMPLATE.registerLicenseTerms(
            PILFlavors.commercialRemix({
                mintingFee: 0,
                commercialRevShare: 10 * 10 ** 6, // 10%
                royaltyPolicy: address(ROYALTY_POLICY_LAP),
                currencyToken: address(MERC20)
            })
        );

        vm.prank(alice);
        LICENSING_MODULE.attachLicenseTerms(ipId, address(PIL_TEMPLATE), licenseTermsId);
        startLicenseTokenId = LICENSING_MODULE.mintLicenseTokens({
            licensorIpId: ipId,
            licenseTemplate: address(PIL_TEMPLATE),
            licenseTermsId: licenseTermsId,
```

--------------------------------

### Get Licensing Module Address

Source: https://docs.story.foundation/smart-contract-reference/royalty/royaltymodule

Retrieves the currently configured licensing module address. This public view function provides read-only access to the licensing module reference, enabling external contracts and clients to query the module location.

```solidity
function licensingModule() external view returns (address)
```

--------------------------------

### Claim All Revenue with Royalty Module (Solidity)

Source: https://docs.story.foundation/developers/smart-contracts-guide/claim-revenue

Pays MERC20 tokens to a child IP and allows an ancestor IP to claim a share of the revenue. This demonstrates the revenue distribution mechanism where a portion is claimed by the parent IP.

```solidity
function test_claimAllRevenue() public {
        // ADMIN SETUP
        // We mint 100 MERC20 to this contract so it has some money to pay.
        MERC20.mint(address(this), 100);
        // We have to approve the Royalty Module to spend MERC20 on our behalf, which
        // it will do using `payRoyaltyOnBehalf`.
        MERC20.approve(address(ROYALTY_MODULE), 10);

        // This contract pays 10 MERC20 to Bob's IP.
        ROYALTY_MODULE.payRoyaltyOnBehalf(childIpId, address(0), address(MERC20), 10);

        // Now that Bob's IP has been paid, Alice can claim her share (1 MERC20, which
        // is 10% as specified in the license terms)
        address[] memory childIpIds = new address[](1);
        address[] memory royaltyPolicies = new address[](1);
        address[] memory currencyTokens = new address[](1);
        childIpIds[0] = childIpId;
        royaltyPolicies[0] = address(ROYALTY_POLICY_LAP);
        currencyTokens[0] = address(MERC20);

        uint256[] memory amountsClaimed = ROYALTY_WORKFLOWS.claimAllRevenue({
            ancestorIpId: ipId,
            claimer: ipId,
            childIpIds: childIpIds,
            royaltyPolicies: royaltyPolicies,
            currencyTokens: currencyTokens
        });

        // Check that 1 MERC20 was claimed by Alice's IP Account
        assertEq(amountsClaimed[0], 1);
        // Check that Alice's IP Account now has 1 MERC20 in its balance.
        assertEq(MERC20.balanceOf(ipId), 1);
        // Check that Bob's IP now has 9 MERC20 in its Royalty Vault, which it
        // can claim to its IP Account at a later point if he wants.
        assertEq(MERC20.balanceOf(ROYALTY_MODULE.ipRoyaltyVaults(childIpId)), 9);
    }
```

--------------------------------

### Pay Royalty to IP Asset in Solidity

Source: https://docs.story.foundation/developers/smart-contracts-guide/claim-revenue

This function pays royalty on behalf of a user to a child IP Asset using the Royalty Module, transferring a specified amount of whitelisted revenue tokens (like MockERC20) to the IP Royalty Vault for distribution. It automates revenue sharing based on negotiated commercial terms with parent IP Assets. Requires prior approval of the Royalty Module to spend the tokens; otherwise, the transaction will fail.

```solidity
ROYALTY_MODULE.payRoyaltyOnBehalf(childIpId, address(0), address(MERC20), 10);
```

--------------------------------

### Process Royalty Payment Between IP Assets

Source: https://docs.story.foundation/smart-contract-reference/royalty/royaltymodule

Enables payment of royalties from one IP asset to another on behalf of a payer. Includes reentrancy protection and pausable functionality for security, allowing flexible royalty settlement between protocol participants.

```solidity
function payRoyaltyOnBehalf(
    address receiverIpId,
    address payerIpId,
    address token,
    uint256 amount
) external nonReentrant whenNotPaused
```

--------------------------------

### Handle Royalty on Parent Linking

Source: https://docs.story.foundation/smart-contract-reference/royalty/royaltymodule

Manages royalty operations when a derivative IP links to parent IPs. Processes multiple parent relationships and validates royalty policy consistency across all licenses being burned during the linking process.

```solidity
function onLinkToParents(
    address ipId,
    address royaltyPolicy,
    address[] calldata parentIpIds,
    bytes[] memory licenseData,
    bytes calldata externalData
) external nonReentrant onlyLicensingModule
```

--------------------------------

### Pay License Minting Fee

Source: https://docs.story.foundation/smart-contract-reference/royalty/royaltymodule

Handles payment of minting fees during license creation. Restricted to the licensing module, it transfers fees from the payer address to the receiver IP, supporting the protocol's economic model for license issuance.

```solidity
function payLicenseMintingFee(
    address receiverIpId,
    address payerAddress,
    address licenseRoyaltyPolicy,
    address token,
    uint256 amount
) external onlyLicensingModule
```

--------------------------------

### RoyaltyModule State Variables

Source: https://docs.story.foundation/smart-contract-reference/royalty/royaltymodule

Defines immutable registry references and mutable state mappings for tracking whitelisted royalty policies, tokens, and IP policy assignments. These variables form the core storage structure of the RoyaltyModule contract, enabling secure reference to external modules and maintaining protocol configuration state.

```solidity
ILicenseRegistry public immutable LICENSE_REGISTRY
IDisputeModule public immutable DISPUTE_MODULE
address licensingModule
mapping(address royaltyPolicy => bool isWhitelisted) isWhitelistedRoyaltyPolicy
mapping(address token => bool) isWhitelistedRoyaltyToken
mapping(address ipId => address royaltyPolicy) royaltyPolicies
```

--------------------------------

### Handle Royalty on License Minting

Source: https://docs.story.foundation/smart-contract-reference/royalty/royaltymodule

Executes royalty-related operations when a license is minted. Restricted to the licensing module with reentrancy protection, it processes license data and external data specific to the royalty policy for the given IP.

```solidity
function onLicenseMinting(
    address ipId,
    address royaltyPolicy,
    bytes calldata licenseData,
    bytes calldata externalData
) external nonReentrant onlyLicensingModule
```

--------------------------------

### Whitelist Royalty Policy

Source: https://docs.story.foundation/smart-contract-reference/royalty/royaltymodule

Enables administrators to add or remove royalty policies from the protocol whitelist. Only whitelisted policies can be used by IP assets for royalty management, ensuring quality control and security.

```solidity
function whitelistRoyaltyPolicy(address royaltyPolicy, bool allowed) external restricted
```

--------------------------------

### Register Derivative IP with License Tokens (Solidity)

Source: https://docs.story.foundation/developers/smart-contracts-guide/claim-revenue

Registers a child IP as a derivative of a parent IP using provided license tokens. This function utilizes the IP Asset Registry and Licensing Module to establish the derivative relationship.

```solidity
function testRegisterDerivativeWithLicenseTokens() public {
        // Registers a child IP (owned by Bob) as a derivative of Alice's IP.
        uint256 childTokenId = SIMPLE_NFT.mint(bob);
        childIpId = IP_ASSET_REGISTRY.register(block.chainid, address(SIMPLE_NFT), childTokenId);

        uint256[] memory licenseTokenIds = new uint256[](1);
        licenseTokenIds[0] = startLicenseTokenId;

        vm.prank(bob);
        LICENSING_MODULE.registerDerivativeWithLicenseTokens({
            childIpId: childIpId,
            licenseTokenIds: licenseTokenIds,
            royaltyContext: "", // empty for PIL
            maxRts: 0
        });
    }
```

--------------------------------

### Whitelist Royalty Payment Token

Source: https://docs.story.foundation/smart-contract-reference/royalty/royaltymodule

Allows administrators to whitelist tokens that can be used for royalty payments. This ensures only approved ERC-20 tokens are accepted by the protocol, preventing spam or malicious tokens.

```solidity
function whitelistRoyaltyToken(address token, bool allowed) external restricted
```

--------------------------------

### Retrieve Royalty Policy for IP Asset in Solidity

Source: https://docs.story.foundation/smart-contract-reference/royalty/royaltymodule

The royaltyPolicies function fetches the royalty policy address associated with a specific IP asset ID. It takes the IP ID as input and returns the corresponding policy address. This view operation assumes the IP asset exists in the system and may return zero address if none is set, with dependencies on IP registration.

```solidity
function royaltyPolicies(address ipId) external view returns (address)
```

--------------------------------

### Set Licensing Module Address

Source: https://docs.story.foundation/smart-contract-reference/royalty/royaltymodule

Updates the licensing module address stored in state. This restricted function allows protocol administrators to modify the licensing module reference, ensuring flexibility while maintaining security through access control.

```solidity
function setLicensingModule(address licensing) external restricted
```

--------------------------------

### Check Whitelisted Royalty Token in Solidity

Source: https://docs.story.foundation/smart-contract-reference/royalty/royaltymodule

The isWhitelistedRoyaltyToken function verifies if a given token address is approved and whitelisted for royalty payments. It accepts the token address as parameter and returns true if whitelisted. As a view function, it relies on the contract's whitelisting data without state modifications, and is limited to approved tokens only.

```solidity
function isWhitelistedRoyaltyToken(address token) external view returns (bool)
```

--------------------------------

### Check Whitelisted Royalty Policy in Solidity

Source: https://docs.story.foundation/smart-contract-reference/royalty/royaltymodule

The isWhitelistedRoyaltyPolicy function determines if a specified royalty policy address is whitelisted for use in the system. It requires the royalty policy address as input and returns a boolean value indicating whitelisting status. This view function depends on the contract's internal whitelisting mechanism and has no outputs beyond the boolean result, with no known limitations beyond access restrictions.

```solidity
function isWhitelistedRoyaltyPolicy(address royaltyPolicy) external view returns (bool)
```
Tokens:
Raw