💸 Royalty Module
Learn how to pay, route, and claim royalties on Story.
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.
Working Code Examples
A working code example using the TypeScript SDK that shows how to pay and claim royalties.
RoyaltyModule.sol
View the smart contract for the Royalty Module.
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 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:
| Token | Contract Address | Explorer | Mint |
|---|---|---|---|
| WIP | 0x1514000000000000000000000000000000000000 | View here ↗️ | N/A |
| MERC20 | 0xF2104833d386a2734a4eB3B8ad6FC6812F29E38E | View here ↗️ | Mint ↗️ |
| Token | Contract Address | Explorer | Mint |
|---|---|---|---|
| WIP | 0x1514000000000000000000000000000000000000 | View here ↗️ | N/A |
| MERC20 | 0xF2104833d386a2734a4eB3B8ad6FC6812F29E38E | View here ↗️ | Mint ↗️ |
| Token | Contract Address | Explorer | Mint |
|---|---|---|---|
| WIP | 0x1514000000000000000000000000000000000000 | View here ↗️ | N/A |
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.
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.
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.
Pay IP Revenue in the SDK
A tutorial on how to pay an IP revenue using the TypeScript SDK.
Pay IP Revenue using the Smart Contracts
A tutorial on how to pay an IP revenue using the smart contracts.
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.
Why do we separate payment and claiming processes?
Why do we separate payment and claiming processes?
Imagine an IP graph with thousands of ancestors. If we were to pay, distribute, and claim all at once, the transaction would be too large to handle. By separating the payment and claiming processes, we can break down the process into smaller chunks that are more gas efficient.
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.
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.
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.