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 Asset	Relationship	Commercial Revenue Share
IP Asset 1 (IPA1)	Original IP Asset	Requires 5% from all derivatives
IP Asset 2 (IPA2)	A derivative of IPA1	Requires 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 100 Royalty Tokens 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.

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.

​

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:

​

Initiating a Payment

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

Payment Type	When It Happens	Potential Functions Called
Minting a License	When 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 Directly	When 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.

​

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.