Claim Revenue - Story Documentation

Completed Code

All of this page is covered in this working code example.

This section demonstrates how to claim due revenue from an IP Asset.

There are two main ways revenue can be claimed:

Scenario #1: Someone pays my IP Asset directly, and I claim that revenue.
Scenario #2: Someone pays a derivative IP Asset of my IP, and I have the right to a % of their revenue based on the commercialRevShare in the license terms.

Prerequisites

There are a few steps you have to complete before you can start the tutorial.

Complete the TypeScript SDK Setup
Have a basic understanding of the Royalty Module
Obviously, there must be a payment to be claimed. Read Pay an IPA

Before We Start

When payments are made, they eventually end up in an IP Asset’s IP Royalty Vault. From here, they are claimed/transferred to whoever owns the Royalty Tokens associated with it, which represent a % of revenue share for a given IP Asset’s IP Royalty Vault.

The IP Account (the smart contract that represents the IP Asset) is what holds 100% of the Royalty Tokens when it’s first registered. So usually, it indeed holds most of the Royalty Tokens.

Quick Note. The below scenarios and examples use a Liquid Absolute Percentage royalty policy. This is currently one of two royalty policies you can use.

Scenario #1

In this scenario, I own IP Asset 3. Someone pays my IP Asset 3 directly, and I claim that revenue. Let’s view this in steps:

As we can see in the below diagram, when someone pays IP Asset 3 100 $WIP, 85 $WIP automatically gets deposited into IP Royalty Vault 3 (based on the license terms, which specifiies a LAP royalty policy and the resulting royalty stack).
Now, IP Asset 3 wants to claim its revenue sitting in the IP Royalty Vault 3. It will look like this:

Below is how IP Asset 3 would claim their revenue, as shown in the image above, with the SDK:

Associated Docs: royalty.claimAllRevenue

Claiming revenue is permissionless. Any wallet can run the claim revenue transaction for an IP.

main.ts

import { WIP_TOKEN_ADDRESS } from "@story-protocol/core-sdk";
// you should already have a client set up (prerequisite)
import { client } from "./client";

async function main() {
  const claimRevenue = await client.royalty.claimAllRevenue({
    // IP Asset 3's ipId
    ancestorIpId: "0x03",
    // the address that owns the royalty tokens,
    // which is the IP Account in this case
    claimer: "0x03",
    currencyTokens: [WIP_TOKEN_ADDRESS],
    childIpIds: [],
    royaltyPolicies: [],
    claimOptions: {
      // If the wallet claiming the revenue is the owner of the
      // IP Account/IP Asset (in other words, the owner of the
      // IP's underlying NFT), `claimAllRevenue` will transfer all
      // earnings to the user's external wallet holding the NFT
      // instead of the IP Account, for convenience. You can disable it here.
      autoTransferAllClaimedTokensFromIp: true,
      // Unwraps the claimed $WIP to $IP for you
      autoUnwrapIpTokens: true,
    },
  });

  console.log(`Claimed revenue: ${claimRevenue.claimedTokens}`);
}

main();

Scenario #2

In this scenario, I own IP Asset 1. Someone pays a derivative IP Asset 3, and I have the right to a % of their revenue based on the commercialRevShare in the license terms. This is exactly the same as Scenario #1, except one extra step is added. Let’s view this in steps:

As we can see in the below diagram, when someone pays IP Asset 3 100 $WIP, 15 $WIP automatically gets deposited to the LAP royalty policy contract to be distributed to ancestors.
Then, in a second step, the tokens are transferred to the ancestors’ IP Royalty Vault based on the negotiated commercialRevShare in the license terms.
Lastly, IP Asset 1 wants to claim their revenue sitting in its associated IP Royalty Vault. It will look like this:

Below is how IP Asset 1 (or 2) would claim their revenue, as shown in the image above, with the SDK:

Associated Docs: royalty.claimAllRevenue

Claiming revenue is permissionless. Any wallet can run the claim revenue transaction for an IP.

main.ts

import { WIP_TOKEN_ADDRESS } from "@story-protocol/core-sdk";
// you should already have a client set up (prerequisite)
import { client } from "./client";

async function main() {
  const claimRevenue = await client.royalty.claimAllRevenue({
    // IP Asset 1's ipId
    ancestorIpId: "0x01",
    // the address that owns the royalty tokens,
    // which is the IP Account in this case
    claimer: "0x01",
    currencyTokens: [WIP_TOKEN_ADDRESS],
    // IP Asset 3's ipId
    childIpIds: ["0x03"],
    // Aeneid testnet address of RoyaltyPolicyLAP
    royaltyPolicies: ["0xBe54FB168b3c982b7AaE60dB6CF75Bd8447b390E"],
    claimOptions: {
      // If the wallet claiming the revenue is the owner of the
      // IP Account/IP Asset (in other words, the owner of the
      // IP's underlying NFT), `claimAllRevenue` will transfer all
      // earnings to the user's external wallet holding the NFT
      // instead of the IP Account, for convenience. You can disable it here.
      autoTransferAllClaimedTokensFromIp: true,
      // Unwraps the claimed $WIP to $IP for you
      autoUnwrapIpTokens: true,
    },
  });

  console.log(`Claimed revenue: ${claimRevenue.claimedTokens}`);
}

main();

Scenario #3

In this scenario, I own IP Asset 1. Someone pays a derivative IP Asset 3, and I have the right to a % of their revenue based on the commercialRevShare in the license terms. The difference here is that I have previously transferred the royalty tokens in the IP Account to an external wallet, most commonly the wallet that owns the IP. This is exactly the same as Scenario #2, except royalty is being claimed to an external wallet instead of the IP Account. Let’s view this in steps:

As we can see in the below diagram, when someone pays IP Asset 3 100 $WIP, 15 $WIP automatically gets deposited to the LAP royalty policy contract to be distributed to ancestors.
Then, in a second step, the tokens are transferred to the ancestors’ IP Royalty Vault based on the negotiated commercialRevShare in the license terms.
Lastly, IP Asset 1 wants to claim their revenue sitting in its associated IP Royalty Vault. It will look like this:

Below is how IP Asset 1 (or 2) would claim their revenue, as shown in the image above, with the SDK:

Associated Docs: royalty.claimAllRevenue

Claiming revenue is permissionless. Any wallet can run the claim revenue transaction for an IP.

main.ts

import { WIP_TOKEN_ADDRESS } from "@story-protocol/core-sdk";
// you should already have a client set up (prerequisite)
import { client } from "./client";

async function main() {
  // transfer the royalty tokens from the
  // ip account to the external wallet
  // NOTE: this can only be called by the IP owner
  // and only needs to be called once. Any future
  // claims will be to this external wallet
  const royaltyVaultAddress = await client.royalty.getRoyaltyVaultAddress("0x01");
  const transferRoyaltyTokens = await client.ipAccount.transferErc20({
    ipId: "0x01",
    tokens: [
      {
        address: royaltyVaultAddress,
        amount: 100_000_000, // 100% of the royalty tokens
        target: "0x04", // the external wallet
      },
    ],
  });

  // claim the revenue to the external wallet
  const claimRevenue = await client.royalty.claimAllRevenue({
    // IP Asset 1's ipId
    ancestorIpId: "0x01",
    // the address that owns the royalty tokens,
    // which is the external wallet in this case
    claimer: "0x04",
    currencyTokens: [WIP_TOKEN_ADDRESS],
    // IP Asset 3's ipId
    childIpIds: ["0x03"],
    // Aeneid testnet address of RoyaltyPolicyLAP
    royaltyPolicies: ["0xBe54FB168b3c982b7AaE60dB6CF75Bd8447b390E"],
    claimOptions: {
      // If the wallet claiming the revenue is the owner of the
      // IP Account/IP Asset (in other words, the owner of the
      // IP's underlying NFT), `claimAllRevenue` will transfer all
      // earnings to the user's external wallet holding the NFT
      // instead of the IP Account, for convenience. You can disable it here.
      autoTransferAllClaimedTokensFromIp: true,
      // Unwraps the claimed $WIP to $IP for you
      autoUnwrapIpTokens: true,
    },
  });

  console.log(`Claimed revenue: ${claimRevenue.claimedTokens}`);
}

main();

View Completed Code

Congratulations, you claimed revenue using the Royalty Module!

Completed Code

All of this page is covered in this working code example.

Dispute an IP

Now what happens if an IP Asset doesn’t pay their due share? We can dispute the IP on-chain, which we will cover on the next page.

On this page

Prerequisites
Before We Start
Scenario #1
Scenario #2
Scenario #3
View Completed Code
Dispute an IP

Completed Code

All of this page is covered in this working code example.

This section demonstrates how to claim due revenue from an IP Asset.

There are two main ways revenue can be claimed:

Scenario #1: Someone pays my IP Asset directly, and I claim that revenue.
Scenario #2: Someone pays a derivative IP Asset of my IP, and I have the right to a % of their revenue based on the commercialRevShare in the license terms.

Prerequisites

There are a few steps you have to complete before you can start the tutorial.

Complete the TypeScript SDK Setup
Have a basic understanding of the Royalty Module
Obviously, there must be a payment to be claimed. Read Pay an IPA

Before We Start

The IP Account (the smart contract that represents the IP Asset) is what holds 100% of the Royalty Tokens when it’s first registered. So usually, it indeed holds most of the Royalty Tokens.

Quick Note. The below scenarios and examples use a Liquid Absolute Percentage royalty policy. This is currently one of two royalty policies you can use.

Scenario #1

In this scenario, I own IP Asset 3. Someone pays my IP Asset 3 directly, and I claim that revenue. Let’s view this in steps:

As we can see in the below diagram, when someone pays IP Asset 3 100 $WIP, 85 $WIP automatically gets deposited into IP Royalty Vault 3 (based on the license terms, which specifiies a LAP royalty policy and the resulting royalty stack).
Now, IP Asset 3 wants to claim its revenue sitting in the IP Royalty Vault 3. It will look like this:

Below is how IP Asset 3 would claim their revenue, as shown in the image above, with the SDK:

Associated Docs: royalty.claimAllRevenue

Claiming revenue is permissionless. Any wallet can run the claim revenue transaction for an IP.

main.ts

import { WIP_TOKEN_ADDRESS } from "@story-protocol/core-sdk";
// you should already have a client set up (prerequisite)
import { client } from "./client";

async function main() {
  const claimRevenue = await client.royalty.claimAllRevenue({
    // IP Asset 3's ipId
    ancestorIpId: "0x03",
    // the address that owns the royalty tokens,
    // which is the IP Account in this case
    claimer: "0x03",
    currencyTokens: [WIP_TOKEN_ADDRESS],
    childIpIds: [],
    royaltyPolicies: [],
    claimOptions: {
      // If the wallet claiming the revenue is the owner of the
      // IP Account/IP Asset (in other words, the owner of the
      // IP's underlying NFT), `claimAllRevenue` will transfer all
      // earnings to the user's external wallet holding the NFT
      // instead of the IP Account, for convenience. You can disable it here.
      autoTransferAllClaimedTokensFromIp: true,
      // Unwraps the claimed $WIP to $IP for you
      autoUnwrapIpTokens: true,
    },
  });

  console.log(`Claimed revenue: ${claimRevenue.claimedTokens}`);
}

main();

Scenario #2

As we can see in the below diagram, when someone pays IP Asset 3 100 $WIP, 15 $WIP automatically gets deposited to the LAP royalty policy contract to be distributed to ancestors.
Then, in a second step, the tokens are transferred to the ancestors’ IP Royalty Vault based on the negotiated commercialRevShare in the license terms.
Lastly, IP Asset 1 wants to claim their revenue sitting in its associated IP Royalty Vault. It will look like this:

Below is how IP Asset 1 (or 2) would claim their revenue, as shown in the image above, with the SDK:

Associated Docs: royalty.claimAllRevenue

Claiming revenue is permissionless. Any wallet can run the claim revenue transaction for an IP.

main.ts

import { WIP_TOKEN_ADDRESS } from "@story-protocol/core-sdk";
// you should already have a client set up (prerequisite)
import { client } from "./client";

async function main() {
  const claimRevenue = await client.royalty.claimAllRevenue({
    // IP Asset 1's ipId
    ancestorIpId: "0x01",
    // the address that owns the royalty tokens,
    // which is the IP Account in this case
    claimer: "0x01",
    currencyTokens: [WIP_TOKEN_ADDRESS],
    // IP Asset 3's ipId
    childIpIds: ["0x03"],
    // Aeneid testnet address of RoyaltyPolicyLAP
    royaltyPolicies: ["0xBe54FB168b3c982b7AaE60dB6CF75Bd8447b390E"],
    claimOptions: {
      // If the wallet claiming the revenue is the owner of the
      // IP Account/IP Asset (in other words, the owner of the
      // IP's underlying NFT), `claimAllRevenue` will transfer all
      // earnings to the user's external wallet holding the NFT
      // instead of the IP Account, for convenience. You can disable it here.
      autoTransferAllClaimedTokensFromIp: true,
      // Unwraps the claimed $WIP to $IP for you
      autoUnwrapIpTokens: true,
    },
  });

  console.log(`Claimed revenue: ${claimRevenue.claimedTokens}`);
}

main();

Scenario #3

As we can see in the below diagram, when someone pays IP Asset 3 100 $WIP, 15 $WIP automatically gets deposited to the LAP royalty policy contract to be distributed to ancestors.
Then, in a second step, the tokens are transferred to the ancestors’ IP Royalty Vault based on the negotiated commercialRevShare in the license terms.
Lastly, IP Asset 1 wants to claim their revenue sitting in its associated IP Royalty Vault. It will look like this:

Below is how IP Asset 1 (or 2) would claim their revenue, as shown in the image above, with the SDK:

Associated Docs: royalty.claimAllRevenue

Claiming revenue is permissionless. Any wallet can run the claim revenue transaction for an IP.

main.ts

import { WIP_TOKEN_ADDRESS } from "@story-protocol/core-sdk";
// you should already have a client set up (prerequisite)
import { client } from "./client";

async function main() {
  // transfer the royalty tokens from the
  // ip account to the external wallet
  // NOTE: this can only be called by the IP owner
  // and only needs to be called once. Any future
  // claims will be to this external wallet
  const royaltyVaultAddress = await client.royalty.getRoyaltyVaultAddress("0x01");
  const transferRoyaltyTokens = await client.ipAccount.transferErc20({
    ipId: "0x01",
    tokens: [
      {
        address: royaltyVaultAddress,
        amount: 100_000_000, // 100% of the royalty tokens
        target: "0x04", // the external wallet
      },
    ],
  });

  // claim the revenue to the external wallet
  const claimRevenue = await client.royalty.claimAllRevenue({
    // IP Asset 1's ipId
    ancestorIpId: "0x01",
    // the address that owns the royalty tokens,
    // which is the external wallet in this case
    claimer: "0x04",
    currencyTokens: [WIP_TOKEN_ADDRESS],
    // IP Asset 3's ipId
    childIpIds: ["0x03"],
    // Aeneid testnet address of RoyaltyPolicyLAP
    royaltyPolicies: ["0xBe54FB168b3c982b7AaE60dB6CF75Bd8447b390E"],
    claimOptions: {
      // If the wallet claiming the revenue is the owner of the
      // IP Account/IP Asset (in other words, the owner of the
      // IP's underlying NFT), `claimAllRevenue` will transfer all
      // earnings to the user's external wallet holding the NFT
      // instead of the IP Account, for convenience. You can disable it here.
      autoTransferAllClaimedTokensFromIp: true,
      // Unwraps the claimed $WIP to $IP for you
      autoUnwrapIpTokens: true,
    },
  });

  console.log(`Claimed revenue: ${claimRevenue.claimedTokens}`);
}

main();

View Completed Code

Congratulations, you claimed revenue using the Royalty Module!

Completed Code

All of this page is covered in this working code example.

Dispute an IP

Now what happens if an IP Asset doesn’t pay their due share? We can dispute the IP on-chain, which we will cover on the next page.

On this page

Prerequisites
Before We Start
Scenario #1
Scenario #2
Scenario #3
View Completed Code
Dispute an IP

Completed Code

​Prerequisites

​Before We Start

​Scenario #1

​Scenario #2

​Scenario #3

​View Completed Code

Completed Code

​Dispute an IP

Overview

Completed Code

​Prerequisites

​Before We Start

​Scenario #1

​Scenario #2

​Scenario #3

​View Completed Code

Completed Code

​Dispute an IP

Prerequisites

Before We Start

Scenario #1

Scenario #2

Scenario #3

View Completed Code

Dispute an IP

Prerequisites

Before We Start

Scenario #1

Scenario #2

Scenario #3

View Completed Code

Dispute an IP