Story’s Royalty Module enables automated revenue sharing between IP Assets (IPAs) based on their derivative relationships and license terms. This document explains how revenue flows through the protocol and how IP owners are paid and can claim their share.

Conceptual Overview

In order to learn the Royalty Module, let’s look at a full example just so you can see what it looks like. Then we will walk through each part step-by-step to get a comprehensive understanding.

The Ancestory Graph

IP Assets are connected by their derivative relationships. These relationships are bound via License Terms, which specify things like an initial minting fee or a royalty percentage that must be paid every time revenue is generated.

In this example, let’s say we have 3 IP Assets with the following configurations:

IP AssetRelationshipCommercial Revenue Share
IP Asset 1 (IPA1)Original IP AssetRequires 5% from all derivatives
IP Asset 2 (IPA2)A derivative of IPA1Requires 10% from all derivatives
IP Asset 3 (IPA3)A derivative of IPA2

Royalty Stack

Each IP Asset has what’s called a Royalty Stack. This is a cumulative percentage of revenue that must be paid to ancestors based on the license terms between the IP Assets.

For example, if IPA3 makes 100 $IP, it will eventually only take in 85 $IP because 15 $IP will be paid to its ancestors. This is because the royalty stack is 15% (5% from IPA1 and 10% from IPA2).

IP Royalty Vault

Upon creation, every IP Asset automatically gets a Royalty Vault. This is a vault - separate from the actual IP itself but bound to it - that receives all incoming revenue generated by the IP Asset.

Royalty Tokens

This royalty vault has associated with it, where each token represents the right to 1% of the total revenue generated by the IP Asset and thus deposited to the Royalty Vault.

When an IP Asset is created and a Royalty Vault is deployed, it automatically sends the 100 Royalty Tokens to the IP Asset itself.

These Royalty Tokens can be sent out to other wallets by the IP owner. Then, as stated above, whoever owns them has the right to claim their % due share of the revenue that gets accepted into the Royalty Vault.

This unlocks some really cool DeFi opportunities. For example, selling Royalty Tokens on the secondary market where people can buy them and then claim their share of the revenue when it gets deposited into the Royalty Vault.

Whitelisted Payment Tokens

For a currency to be used in Story’s Royalty Module, it must be whitelisted by our protocol in the RoyaltyModule.sol contract. Here are the whitelisted tokens:

TokenContract AddressExplorerMint
WIP0x1514000000000000000000000000000000000000View here ↗️N/A
MERC200xF2104833d386a2734a4eB3B8ad6FC6812F29E38EView here ↗️Mint ↗️

Initiating a Payment

There are two common scenarios when revenue flow would be initiated:

Payment TypeWhen It HappensPotential Functions Called
Minting a LicenseWhen someone mints a license to use your IP, or registers a derivative of an IP Asset (which requires having a license)mintLicenseTokens, registerDerviative
Paying Revenue DirectlyWhen someone directly sends revenue to an IP Asset either as a tip or to forward due revenue to the chain.payRoyaltyOnBehalf

Let’s see what happens when IP Asset 3 earns money using the payRoyaltyOnBehalf function.

1

Initial Payment

In our example, let’s assume that IP Asset 3 is a video game character that is earning 100 $IP. This payment is made via payRoyaltyOnBehalf, which will initiate the payment process as seen below.

2

Royalty Module Distribution

Next, the Royalty Module will split the payment based on the royalty stack (15%) and distribute the funds to both the IP Asset and the Royalty Policy contract which governs the license terms. Royalty policies will be explained in a different section.

Claiming Revenue

The above walked through what happens when a payment is made. However, in order to actually get the revenue, the revenue must be claimed to whoever holds the Royalty Tokens.

Claiming revenue can be done with the claimAllRevenue function. Let’s see how it works.

Claiming revenue is completely permissionless. Anyone can claim revenue on behalf of any IP Asset.

1

Transfer to IP Royalty Vault

Since IP Asset 3 was paid directly, the revenue automatically went to it’s Royalty Vault. However because IP Asset 1 and 2 earned their revenue from a derivative relationship, the revenue must be transferred from the royalty policy to their Royalty Vaults.

2

Claiming Revenue to Royalty Tokens

In the last step, revenue will be transferred from the Royalty Vault to whoever owns the Royalty Tokens for each associated IP Asset. This example is simple, because each IP Asset is holding all 100 of its Royalty Tokens in the IP itself.