Royalty

​

RoyaltyClient

​

Methods

• payRoyaltyOnBehalf
• claimableRevenue
• claimAllRevenue
• batchClaimAllRevenue
• getRoyaltyVaultAddress
• batchClaimAllRevenue
• transferToVault

​

payRoyaltyOnBehalf

• request.receiverIpId: The ipId that receives the royalties.
• request.payerIpId: The ID of the IP asset that pays the royalties.
• request.token: The token to use to pay the royalties.
• request.amount: The amount to pay.
• request.wipOptions: [Optional]
  • request.wipOptions.useMulticallWhenPossible: [Optional] Use multicall to batch the WIP calls into one transaction when possible. Default: true
  • request.wipOptions.enableAutoWrapIp: [Optional] By default IP is converted to WIP if the current WIP balance does not cover the fees. Set this to false to disable this behavior. Default: true
  • request.wipOptions.enableAutoApprove: [Optional] Automatically approve WIP usage when WIP is needed but current allowance is not sufficient. Set this to false to disable this behavior. Default: true
• request.erc20Options: [Optional]
  • request.erc20Options.enableAutoApprove: [Optional] Automatically approve ERC20 usage when ERC20 is needed but current allowance is not sufficient. Set this to false to disable this behavior. Default: true

import { WIP_TOKEN_ADDRESS } from "@story-protocol/core-sdk";
import { parseEther, zeroAddress } from "viem";

// In this case, lets say there is a root IPA 'A' and a derivative IPA 'B'.
// Someone wants to pay 'B' for whatever reason (they bought it, they want to tip it, etc).
// Since the payer is not an IP Asset (rather an external user), the `payerIpId` can
// be a zeroAddress. And the receiver is, well, the receiver's ipId which is B.
//
// It's important to note that both 'B' and its parent 'A' will be able
// to claim revenue from this based on the negotiated license terms
const payRoyalty = await client.royalty.payRoyaltyOnBehalf({
  receiverIpId: "0x0b825D9E5FA196e6B563C0a446e8D9885057f9B1", // B's ipId
  payerIpId: zeroAddress,
  token: WIP_TOKEN_ADDRESS,
  amount: parseEther("2"), // 2 $WIP
});
console.log(`Paid royalty at transaction hash ${payRoyalty.txHash}`);

// In this case, lets say there is a root IPA 'A' and a derivative IPA 'B'.
// 'B' earns revenue off-chain, but must pay 'A' based on their negotiated license terms.
// So 'B' pays 'A' what they are due
const payRoyalty = await client.royalty.payRoyaltyOnBehalf({
  receiverIpId: "0x6B86B39F03558A8a4E9252d73F2bDeBfBedf5b68", // A's ipId
  payerIpId: "0x0b825D9E5FA196e6B563C0a446e8D9885057f9B1", // B's ipId
  token: WIP_TOKEN_ADDRESS,
  amount: parseEther("2"), // 2 $WIP
});
console.log(`Paid royalty at transaction hash ${payRoyalty.txHash}`);

​

claimableRevenue

• request.ipId: The id of the royalty vault.
• request.claimer: The address of the royalty token holder. This is most commonly the IP Account, since by default the IP Account is the owner of the royalty tokens.
• request.token: The revenue token to claim.

import { WIP_TOKEN_ADDRESS } from "@story-protocol/core-sdk";

const claimableRevenue = await client.royalty.claimableRevenue({
  ipId: "0x01",
  claimer: "0x01",
  token: WIP_TOKEN_ADDRESS,
});

​

claimAllRevenue

• request.ancestorIpId: The address of the ancestor IP from which the revenue is being claimed.
• request.claimer: The address of the claimer of the currency (revenue) tokens. This is normally the ipId of the ancestor IP if the IP has all royalty tokens. Otherwise, this would be the address that is holding the ancestor IP royalty tokens.
• request.childIpIds[]: The addresses of the child IPs from which royalties are derived.
• request.royaltyPolicies[]: The addresses of the royalty policies, where royaltyPolicies[i] governs the royalty flow for childIpIds[i].
• request.currencyTokens[]: The addresses of the currency tokens in which royalties will be claimed.
• request.claimOptions: [Optional]
  • request.claimOptions.autoTransferAllClaimedTokensFromIp: [Optional] When enabled, all claimed tokens on the claimer are transferred to the wallet address if the wallet owns the IP. If the wallet is the claimer or if the claimer is not an IP owned by the wallet, then the tokens will not be transferred. Set to false to disable auto transferring claimed tokens from the claimer. Default: true
  • request.claimOptions.autoUnwrapIpTokens: [Optional] By default all claimed WIP tokens are converted back to IP after they are transferred. Set this to false to disable this behavior. Default: false

import { WIP_TOKEN_ADDRESS } from "@story-protocol/core-sdk";

const claimRevenue = await client.royalty.claimAllRevenue({
  // IP Asset 1's (parent) ipId
  ancestorIpId: "0x089d75C9b7E441dA3115AF93FF9A855BDdbfe384",
  // whoever owns the royalty tokens associated with IP Royalty Vault 1
  // (most likely the associated ipId, which is IP Asset 1's ipId)
  claimer: "0x089d75C9b7E441dA3115AF93FF9A855BDdbfe384",
  currencyTokens: [WIP_TOKEN_ADDRESS],
  // IP Asset 2's (child) ipId
  childIpIds: ["0xDa03c4B278AD44f5a669e9b73580F91AeDE0E3B2"],
  // testnet address of RoyaltyPolicyLAP
  royaltyPolicies: ["0xBe54FB168b3c982b7AaE60dB6CF75Bd8447b390E"],
});

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

​

batchClaimAllRevenue

• request.ancestorIps[]: An array of ancestor IP information from which the revenue is being claimed.
  • request.ancestorIps[].ipId: The address of the ancestor IP from which the revenue is being claimed.
  • request.ancestorIps[].claimer: The address of the claimer of the currency (revenue) tokens. This is normally the ipId of the ancestor IP if the IP has all royalty tokens. Otherwise, this would be the address that is holding the ancestor IP royalty tokens.
  • request.ancestorIps[].childIpIds[]: The addresses of the child IPs from which royalties are derived.
  • request.ancestorIps[].royaltyPolicies[]: The addresses of the royalty policies, where royaltyPolicies[i] governs the royalty flow for childIpIds[i].
  • request.ancestorIps[].currencyTokens[]: The addresses of the currency tokens in which royalties will be claimed.
• request.claimOptions: [Optional]
  • request.claimOptions.autoTransferAllClaimedTokensFromIp: [Optional] When enabled, all claimed tokens on the claimer are transferred to the wallet address if the wallet owns the IP. If the wallet is the claimer or if the claimer is not an IP owned by the wallet, then the tokens will not be transferred. Set to false to disable auto transferring claimed tokens from the claimer. Default: true
  • request.claimOptions.autoUnwrapIpTokens: [Optional] By default all claimed WIP tokens are converted back to IP after they are transferred. Set this to false to disable this behavior. Default: false
• request.options: [Optional]
  • request.options.useMulticallWhenPossible: [Optional] Use multicall to batch the calls claimAllRevenue into one transaction when possible. If only 1 ancestorIp is provided, multicall will not be used. Default: true

import { WIP_TOKEN_ADDRESS } from "@story-protocol/core-sdk";

const claimRevenue = await client.royalty.batchClaimAllRevenue({
  ancestorIps: [
    {
      ipId: "0x089d75C9b7E441dA3115AF93FF9A855BDdbfe384",
      claimer: "0x089d75C9b7E441dA3115AF93FF9A855BDdbfe384",
      currencyTokens: [WIP_TOKEN_ADDRESS],
      childIpIds: ["0xDa03c4B278AD44f5a669e9b73580F91AeDE0E3B2"],
      royaltyPolicies: ["0xBe54FB168b3c982b7AaE60dB6CF75Bd8447b390E"],
    },
  ],
});

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

​

getRoyaltyVaultAddress

• ipId: the ipId associated with the royalty vault.

​

transferToVault

• request.royaltyPolicy: The royalty policy to use.
• request.ipId: The ID of the IP asset that pays the royalties.
• request.ancestorIpId: The ID of the ancestor IP asset.
• request.token: The token address to transfer.

export type TransferToVaultRequest = {
  royaltyPolicy: RoyaltyPolicyInput;
  ipId: Address;
  ancestorIpId: Address;
  token: Address;
};