From 524d23481e13c46b50aac3a066c70cea21d215e0 Mon Sep 17 00:00:00 2001 From: Bonnie Date: Fri, 14 Feb 2025 17:01:57 +0800 Subject: [PATCH] Add default value for DerivativeData and LicenseConfig Add default value for LicenseConfig Update the doc about multiple line Update the doc Update event with link Update zero address Modify licenseConfig logic Refactor via comments Enhance LicenseTermsData type Make licensingConfig required in the setLicensingConfig method Update default show style --- packages/core-sdk/src/resources/group.ts | 111 +----- packages/core-sdk/src/resources/ipAsset.ts | 351 ++---------------- packages/core-sdk/src/resources/license.ts | 58 +-- packages/core-sdk/src/types/common.ts | 14 +- .../core-sdk/src/types/resources/group.ts | 33 +- .../core-sdk/src/types/resources/ipAsset.ts | 107 ++++-- .../core-sdk/src/types/resources/license.ts | 11 +- .../src/utils/getIpMetadataForWorkflow.ts | 4 + .../src/utils/validateLicenseConfig.ts | 34 +- .../core-sdk/test/integration/ipAsset.test.ts | 12 +- .../test/unit/{utils => }/mockData.ts | 1 + .../test/unit/resources/dispute.test.ts | 2 +- .../test/unit/resources/ipAsset.test.ts | 57 ++- .../test/unit/resources/license.test.ts | 2 +- .../test/unit/{ => utils}/feeUtils.test.ts | 4 +- .../unit/utils/validateLicenseConfig.test.ts | 14 + 16 files changed, 286 insertions(+), 529 deletions(-) rename packages/core-sdk/test/unit/{utils => }/mockData.ts (84%) rename packages/core-sdk/test/unit/{ => utils}/feeUtils.test.ts (99%) diff --git a/packages/core-sdk/src/resources/group.ts b/packages/core-sdk/src/resources/group.ts index 7e64ed193..e1e50987b 100644 --- a/packages/core-sdk/src/resources/group.ts +++ b/packages/core-sdk/src/resources/group.ts @@ -27,7 +27,7 @@ import { getPermissionSignature, getDeadline } from "../utils/sign"; import { chain, getAddress } from "../utils/utils"; import { ChainIds } from "../types/config"; import { - InnerLicenseData, + ValidatedLicenseData, LicenseData, MintAndRegisterIpAndAttachLicenseAndAddToGroupRequest, MintAndRegisterIpAndAttachLicenseAndAddToGroupResponse, @@ -107,36 +107,9 @@ export class GroupClient { handleError(error, "Failed to register group"); } } - /** Mint an NFT from a SPGNFT collection, register it with metadata as an IP, attach license terms to the registered IP, and add it to a group IP. - * @param request - The request object containing necessary data to mint and register Ip and attach license and add to group. - * @param request.nftContract The address of the NFT collection. - * @param request.groupId The ID of the group IP to add the newly registered IP. - * @param request.maxAllowedRewardShare The maximum reward share percentage that can be allocated to each member IP. - * @param {Array} request.licenseData licenseData The data of the license and its configuration to be attached to the new group IP. - * @param request.licenseData.licenseTermsId The ID of the registered license terms that will be attached to the new group IP. - * @param request.licenseData.licenseTemplate [Optional] The address of the license template to be attached to the new group IP, default value is Programmable IP License. - * @param request.licenseData.licensingConfig The licensing configuration for the IP. - * @param {Object} request.licenseTermsData.licensingConfig The PIL terms and licensing configuration data to attach to the IP. - * @param request.licenseTermsData.licensingConfig.isSet Whether the configuration is set or not. - * @param request.licenseTermsData.licensingConfig.mintingFee The minting fee to be paid when minting license tokens. - * @param request.licenseTermsData.licensingConfig.licensingHook The hook contract address for the licensing module, or address(0) if none - * @param request.licenseTermsData.licensingConfig.hookData The data to be used by the licensing hook. - * @param request.licenseTermsData.licensingConfig.commercialRevShare The commercial revenue share percentage. - * @param request.licenseTermsData.licensingConfig.disabled Whether the licensing is disabled or not. - * @param request.licenseTermsData.licensingConfig.expectMinimumGroupRewardShare The minimum percentage of the group’s reward share (from 0 to 100%, represented as 100 * 10 ** 6) that can be allocated to the IP when it is added to the group. - * If the remaining reward share in the group is less than the minimumGroupRewardShare,the IP cannot be added to the group. - * @param request.licenseTermsData.licensingConfig.expectGroupRewardPool The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, or address(0) if the IP does not want to be added to any group. - * @param request.allowDuplicates Set to true to allow minting an NFT with a duplicate metadata hash. - * @param request.recipient [Optional] The address of the recipient of the minted NFT,default value is your wallet address. - * . @param request.deadline [Optional] The deadline for the signature in seconds, default value is 1000s. - * @param {Object} request.ipMetadata - [Optional] The desired metadata for the newly minted NFT and newly registered IP. - * @param request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP. - * @param request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP. - * @param request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT. - * @param request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT. - * @param request.txOptions [Optional] This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property. - * @returns A Promise that resolves to a transaction hash, and if encodedTxDataOnly is true, includes encoded transaction data, and if waitForTransaction is true, includes IP ID, token ID. - * @emits IPRegistered (ipId, chainId, tokenContract, tokenId, resolverAddr, metadataProviderAddress, metadata) + /** Mint an NFT from a SPGNFT collection, register it with metadata as an IP, attach license terms to the registered IP, and add it to a group IP. + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/registries/IIPAssetRegistry.sol | IIPAssetRegistry} + * for a list of on-chain events emitted when an IP is minted and registered, license terms are attached to an IP, and it is added to a group. */ public async mintAndRegisterIpAndAttachLicenseAndAddToGroup( request: MintAndRegisterIpAndAttachLicenseAndAddToGroupRequest, @@ -209,34 +182,8 @@ export class GroupClient { } /** Register an NFT as IP with metadata, attach license terms to the registered IP, and add it to a group IP. - * @param request - The request object containing necessary data to register ip and attach license and add to group. - * @param request.spgNftContract The address of the NFT collection. - * @param request.tokenId The ID of the NFT. - * @param request.maxAllowedRewardShare The maximum reward share percentage that can be allocated to each member IP. - * @param request.groupId The ID of the group IP to add the newly registered IP. - * @param {Array} request.licenseData licenseData The data of the license and its configuration to be attached to the new group IP. - * @param request.licenseData.licenseTermsId The ID of the registered license terms that will be attached to the new group IP. - * @param request.licenseData.licenseTemplate [Optional] The address of the license template to be attached to the new group IP, default value is Programmable IP License. - * @param request.licenseData.licensingConfig The licensing configuration for the IP. - * @param {Object} request.licenseTermsData.licensingConfig The PIL terms and licensing configuration data to attach to the IP. - * @param request.licenseTermsData.licensingConfig.isSet Whether the configuration is set or not. - * @param request.licenseTermsData.licensingConfig.mintingFee The minting fee to be paid when minting license tokens. - * @param request.licenseTermsData.licensingConfig.licensingHook The hook contract address for the licensing module, or address(0) if none - * @param request.licenseTermsData.licensingConfig.hookData The data to be used by the licensing hook. - * @param request.licenseTermsData.licensingConfig.commercialRevShare The commercial revenue share percentage. - * @param request.licenseTermsData.licensingConfig.disabled Whether the licensing is disabled or not. - * @param request.licenseTermsData.licensingConfig.expectMinimumGroupRewardShare The minimum percentage of the group’s reward share (from 0 to 100%, represented as 100 * 10 ** 6) that can be allocated to the IP when it is added to the group. - * If the remaining reward share in the group is less than the minimumGroupRewardShare,the IP cannot be added to the group. - * @param request.licenseTermsData.licensingConfig.expectGroupRewardPool The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, or address(0) if the IP does not want to be added to any group. - * . @param request.deadline [Optional] The deadline for the signature in seconds, default is 1000s. - * @param {Object} request.ipMetadata - [Optional] The desired metadata for the newly minted NFT and newly registered IP. - * @param request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP. - * @param request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP. - * @param request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT. - * @param request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT. - * @param request.txOptions [Optional] This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property. - * @returns A Promise that resolves to a transaction hash, and if encodedTxDataOnly is true, includes encoded transaction data, and if waitForTransaction is true, includes IP ID, token ID. - * @emits IPRegistered (ipId, chainId, tokenContract, tokenId, resolverAddr, metadataProviderAddress, metadata) + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/registries/IIPAssetRegistry.sol | IIPAssetRegistry} + * for a list of on-chain events emitted when an IP is registered, license terms are attached to an IP, and it is added to a group. */ public async registerIpAndAttachLicenseAndAddToGroup( request: RegisterIpAndAttachLicenseAndAddToGroupRequest, @@ -345,25 +292,8 @@ export class GroupClient { } } /** Register a group IP with a group reward pool and attach license terms to the group IP. - * @param request - The request object containing necessary data to register group and attach license. - * @param request.groupPool The address specifying how royalty will be split amongst the pool of IPs in the group. - * @param {Object} request.licenseData licenseData The data of the license and its configuration to be attached to the new group IP. - * @param request.licenseData.licenseTermsId The ID of the registered license terms that will be attached to the new group IP. - * @param request.licenseData.licenseTemplate [Optional] The address of the license template to be attached to the new group IP, default value is Programmable IP License. - * @param request.licenseData.licensingConfig The licensing configuration for the IP. - * @param {Object} request.licenseTermsData.licensingConfig The PIL terms and licensing configuration data to attach to the IP. - * @param request.licenseTermsData.licensingConfig.isSet Whether the configuration is set or not. - * @param request.licenseTermsData.licensingConfig.mintingFee The minting fee to be paid when minting license tokens. - * @param request.licenseTermsData.licensingConfig.licensingHook The hook contract address for the licensing module, or address(0) if none - * @param request.licenseTermsData.licensingConfig.hookData The data to be used by the licensing hook. - * @param request.licenseTermsData.licensingConfig.commercialRevShare The commercial revenue share percentage. - * @param request.licenseTermsData.licensingConfig.disabled Whether the licensing is disabled or not. - * @param request.licenseTermsData.licensingConfig.expectMinimumGroupRewardShare The minimum percentage of the group’s reward share (from 0 to 100%, represented as 100 * 10 ** 6) that can be allocated to the IP when it is added to the group. - * If the remaining reward share in the group is less than the minimumGroupRewardShare,the IP cannot be added to the group. - * @param request.licenseTermsData.licensingConfig.expectGroupRewardPool The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, or address(0) if the IP does not want to be added to any group. - * @param request.txOptions [Optional] transaction. This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property. - * @returns A Promise that resolves to a transaction hash, and if encodedTxDataOnly is true, includes encoded transaction data, and if waitForTransaction is true, includes group id. - * @emits PGroupRegistered (groupId, groupPool); + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/modules/grouping/IGroupingModule.sol | IGroupingModule} + * for a list of on-chain events emitted when a group IP is registered, license terms are attached to a group IP . */ public async registerGroupAndAttachLicense( request: RegisterGroupAndAttachLicenseRequest, @@ -394,27 +324,8 @@ export class GroupClient { } } /** Register a group IP with a group reward pool, attach license terms to the group IP, and add individual IPs to the group IP. - * @param request - The request object containing necessary data to register group and attach license and add ips. - * @param request.ipIds The IP IDs of the IPs to be added to the group. - * @param request.groupPool The address specifying how royalty will be split amongst the pool of IPs in the group. - * @param request.maxAllowedRewardShare The maximum reward share percentage that can be allocated to each member IP. - * @param {Object} request.licenseData licenseData The data of the license and its configuration to be attached to the new group IP. - * @param request.licenseData.licenseTermsId The ID of the registered license terms that will be attached to the new group IP. - * @param request.licenseData.licenseTemplate [Optional] The address of the license template to be attached to the new group IP, default value is Programmable IP License. - * @param request.licenseData.licensingConfig The licensing configuration for the IP. - * @param {Object} request.licenseTermsData.licensingConfig The PIL terms and licensing configuration data to attach to the IP. - * @param request.licenseTermsData.licensingConfig.isSet Whether the configuration is set or not. - * @param request.licenseTermsData.licensingConfig.mintingFee The minting fee to be paid when minting license tokens. - * @param request.licenseTermsData.licensingConfig.licensingHook The hook contract address for the licensing module, or address(0) if none - * @param request.licenseTermsData.licensingConfig.hookData The data to be used by the licensing hook. - * @param request.licenseTermsData.licensingConfig.commercialRevShare The commercial revenue share percentage. - * @param request.licenseTermsData.licensingConfig.disabled Whether the licensing is disabled or not. - * @param request.licenseTermsData.licensingConfig.expectMinimumGroupRewardShare The minimum percentage of the group’s reward share (from 0 to 100%, represented as 100 * 10 ** 6) that can be allocated to the IP when it is added to the group. - * If the remaining reward share in the group is less than the minimumGroupRewardShare,the IP cannot be added to the group. - * @param request.licenseTermsData.licensingConfig.expectGroupRewardPool The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, or address(0) if the IP does not want to be added to any group. - * @param request.txOptions [Optional] transaction. This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property. - * @returns A Promise that resolves to a transaction hash, and if encodedTxDataOnly is true, includes encoded transaction data, and if waitForTransaction is true, includes group id. - * @emits PGroupRegistered (groupId, groupPool); + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/modules/grouping/IGroupingModule.sol | IGroupingModule} + * for a list of on-chain events emitted when a group IP is registered, license terms are attached to a group IP, and individual IPs are added to a group. */ public async registerGroupAndAttachLicenseAndAddIps( request: RegisterGroupAndAttachLicenseAndAddIpsRequest, @@ -472,7 +383,7 @@ export class GroupClient { } } - private getLicenseData(licenseData: LicenseData[] | LicenseData): InnerLicenseData[] { + private getLicenseData(licenseData: LicenseData[] | LicenseData): ValidatedLicenseData[] { const isArray = Array.isArray(licenseData); if ((isArray && licenseData.length === 0) || !licenseData) { throw new Error("License data is required."); diff --git a/packages/core-sdk/src/resources/ipAsset.ts b/packages/core-sdk/src/resources/ipAsset.ts index 64b5fb10d..d75a2792c 100644 --- a/packages/core-sdk/src/resources/ipAsset.ts +++ b/packages/core-sdk/src/resources/ipAsset.ts @@ -60,6 +60,7 @@ import { LicenseTermsData, DerivativeData, CommonRegistrationHandlerParams, + ValidatedLicenseTermsData, } from "../types/resources/ipAsset"; import { AccessControllerClient, @@ -100,11 +101,7 @@ import { import { getRevenueShare, validateLicenseTerms } from "../utils/licenseTermsHelper"; import { getDeadline, getPermissionSignature, getSignature } from "../utils/sign"; import { AccessPermission } from "../types/resources/permission"; -import { - InnerLicensingConfig, - LicenseTerms, - RegisterPILTermsRequest, -} from "../types/resources/license"; +import { LicenseTerms, RegisterPILTermsRequest } from "../types/resources/license"; import { MAX_ROYALTY_TOKEN, royaltySharesTotalSupply } from "../constants/common"; import { getFunctionSignature } from "../utils/getFunctionSignature"; import { LicensingConfig } from "../types/common"; @@ -458,16 +455,6 @@ export class IPAssetClient { * The license terms must be attached to the parent IP before calling this function. * All IPs attached default license terms by default. * The derivative IP owner must be the caller or an authorized operator. - * @param request - The request object that contains all data needed to register derivative IP. - * @param request.childIpId The derivative IP ID. - * @param {Array} request.parentIpIds The parent IP IDs. - * @param {Array} request.licenseTermsIds The IDs of the license terms that the parent IP supports. - * @param request.maxMintingFee The maximum minting fee that the caller is willing to pay. if set to 0 then no limit. - * @param request.maxRts The maximum number of royalty tokens that can be distributed to the external royalty policies (max: 100,000,000). - * @param request.maxRevenueShare The maximum revenue share percentage allowed for minting the License Tokens. Must be between 0 and 100,000,000 (where 100,000,000 represents 100%). - * @param request.licenseTemplate [Optional] The license template address, default value is Programmable IP License. - * @param request.txOptions - [Optional] transaction. This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property. - * @returns A Promise that resolves to a transaction hash, and if encodedTxDataOnly is true, includes encoded transaction data. */ public async registerDerivative( request: RegisterDerivativeRequest, @@ -553,9 +540,9 @@ export class IPAssetClient { arg.licenseTermsIds.map((id) => BigInt(id)), arg.licenseTemplate || this.licenseTemplateClient.address, zeroAddress, - BigInt(arg.maxMintingFee), - Number(arg.maxRts), - getRevenueShare(arg.maxRevenueShare), + BigInt(arg.maxMintingFee || 0), + Number(arg.maxRts || MAX_ROYALTY_TOKEN), + getRevenueShare(arg.maxRevenueShare || 100), ], }); const { result: state } = await ipAccount.state(); @@ -652,48 +639,10 @@ export class IPAssetClient { } /** * Mint an NFT from a collection and register it as an IP. - * @param request - The request object that contains all data needed to mint and register ip. - * @param request.spgNftContract The address of the NFT collection. - * @param request.allowDuplicates Indicates whether the license terms can be attached to the same IP ID or not. - * @param {Array} request.licenseTermsData The PIL terms and licensing configuration data to be attached to the IP. - * @param {Object} request.licenseTermsData.terms The PIL terms to be used for the licensing. - * @param request.licenseTermsData.terms.transferable Indicates whether the license is transferable or not. - * @param request.licenseTermsData.terms.royaltyPolicy The address of the royalty policy contract which required to StoryProtocol in advance. - * @param request.licenseTermsData.terms.mintingFee The fee to be paid when minting a license. - * @param request.licenseTermsData.terms.expiration The expiration period of the license. - * @param request.licenseTermsData.terms.commercialUse Indicates whether the work can be used commercially or not, Commercial use is required to deploy a royalty vault. - * @param request.licenseTermsData.terms.commercialAttribution Whether attribution is required when reproducing the work commercially or not. - * @param request.licenseTermsData.terms.commercializerChecker Commercializers that are allowed to commercially exploit the work. If zero address, then no restrictions is enforced. - * @param request.licenseTermsData.terms.commercializerCheckerData The data to be passed to the commercializer checker contract. - * @param request.licenseTermsData.terms.commercialRevShare Percentage of revenue that must be shared with the licensor. - * @param request.licenseTermsData.terms.commercialRevCeiling The maximum revenue that can be generated from the commercial use of the work. - * @param request.licenseTermsData.terms.derivativesAllowed Indicates whether the licensee can create derivatives of his work or not. - * @param request.licenseTermsData.terms.derivativesAttribution Indicates whether attribution is required for derivatives of the work or not. - * @param request.licenseTermsData.terms.derivativesApproval Indicates whether the licensor must approve derivatives of the work before they can be linked to the licensor IP ID or not. - * @param request.licenseTermsData.terms.derivativesReciprocal Indicates whether the licensee must license derivatives of the work under the same terms or not. - * @param request.licenseTermsData.terms.derivativeRevCeiling The maximum revenue that can be generated from the derivative use of the work. - * @param request.licenseTermsData.terms.currency The ERC20 token to be used to pay the minting fee. the token must be registered in story protocol. - * @param request.licenseTermsData.terms.uri The URI of the license terms, which can be used to fetch the offchain license terms. - * @param {Object} request.licenseTermsData.licensingConfig The PIL terms and licensing configuration data to attach to the IP. - * @param request.licenseTermsData.licensingConfig.isSet Whether the configuration is set or not. - * @param request.licenseTermsData.licensingConfig.mintingFee The minting fee to be paid when minting license tokens. - * @param request.licenseTermsData.licensingConfig.licensingHook The hook contract address for the licensing module, or address(0) if none - * @param request.licenseTermsData.licensingConfig.hookData The data to be used by the licensing hook. - * @param request.licenseTermsData.licensingConfig.commercialRevShare The commercial revenue share percentage. - * @param request.licenseTermsData.licensingConfig.disabled Whether the licensing is disabled or not. - * @param request.licenseTermsData.licensingConfig.expectMinimumGroupRewardShare The minimum percentage of the group’s reward share (from 0 to 100%, represented as 100 * 10 ** 6) that can be allocated to the IP when it is added to the group. - * If the remaining reward share in the group is less than the minimumGroupRewardShare,the IP cannot be added to the group. - * @param request.licenseTermsData.licensingConfig.expectGroupRewardPool The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, or address(0) if the IP does not want to be added to any group. - * @param {Object} request.ipMetadata - [Optional] The desired metadata for the newly minted NFT and newly registered IP. - * @param request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP. - * @param request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP. - * @param request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT. - * @param request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT. - * @param request.recipient [Optional] The address of the recipient of the minted NFT,default value is your wallet address. - * @param request.txOptions [Optional] This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property. - * @returns A Promise that resolves to a transaction hash, and if encodedTxDataOnly is true, includes encoded transaction data, and if waitForTransaction is true, including IP ID, Token ID, License Terms Ids. - * @emits IPRegistered (ipId, chainId, tokenContract, tokenId, name, uri, registrationDate) - * @emits LicenseTermsAttached (caller, ipId, licenseTemplate, licenseTermsId) + * it emits IPRegistered (ipId, chainId, tokenContract, tokenId, name, uri, registrationDate). + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/registries/IIPAssetRegistry.sol | IIPAssetRegistry} + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/modules/licensing/ILicensingModule.sol | ILicensingModule} + * for a list of on-chain events emitted when an IP is minted and registered, and license terms are attached to an IP. */ public async mintAndRegisterIpAssetWithPilTerms( request: MintAndRegisterIpAssetWithPilTermsRequest, @@ -768,13 +717,13 @@ export class IPAssetClient { * @param {Object} request.args.licenseTermsData.licensingConfig The PIL terms and licensing configuration data to attach to the IP. * @param request.args.licenseTermsData.licensingConfig.isSet Whether the configuration is set or not. * @param request.args.licenseTermsData.licensingConfig.mintingFee The minting fee to be paid when minting license tokens. - * @param request.args.licenseTermsData.licensingConfig.licensingHook The hook contract address for the licensing module, or address(0) if none + * @param request.args.licenseTermsData.licensingConfig.licensingHook The hook contract address for the licensing module, or zero address if none * @param request.args.licenseTermsData.licensingConfig.hookData The data to be used by the licensing hook. * @param request.args.licenseTermsData.licensingConfig.commercialRevShare The commercial revenue share percentage. * @param request.args.licenseTermsData.licensingConfig.disabled Whether the licensing is disabled or not. * @param request.args.licenseTermsData.licensingConfig.expectMinimumGroupRewardShare The minimum percentage of the group’s reward share (from 0 to 100%, represented as 100 * 10 ** 6) that can be allocated to the IP when it is added to the group. * If the remaining reward share in the group is less than the minimumGroupRewardShare,the IP cannot be added to the group. - * @param request.args.licenseTermsData.licensingConfig.expectGroupRewardPool The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, or address(0) if the IP does not want to be added to any group. + * @param request.args.licenseTermsData.licensingConfig.expectGroupRewardPool The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, or zero address if the IP does not want to be added to any group. * @param {Object} request.args.ipMetadata - [Optional] The desired metadata for the newly minted NFT and newly registered IP. * @param request.args.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP. * @param request.args.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP. @@ -839,48 +788,9 @@ export class IPAssetClient { } } /** - * Register a given NFT as an IP and attach Programmable IP License Terms.R. - * @param request - The request object that contains all data needed to mint and register ip. - * @param request.nftContract The address of the NFT collection. - * @param request.tokenId The ID of the NFT. - * @param {Array} request.licenseTermsData The PIL terms and licensing configuration data to be attached to the IP. - * @param {Object} request.licenseTermsData.terms The PIL terms to be used for the licensing. - * @param request.licenseTermsData.terms.transferable Indicates whether the license is transferable or not. - * @param request.licenseTermsData.terms.royaltyPolicy The address of the royalty policy contract which required to StoryProtocol in advance. - * @param request.licenseTermsData.terms.mintingFee The fee to be paid when minting a license. - * @param request.licenseTermsData.terms.expiration The expiration period of the license. - * @param request.licenseTermsData.terms.commercialUse Indicates whether the work can be used commercially or not, Commercial use is required to deploy a royalty vault. - * @param request.licenseTermsData.terms.commercialAttribution Whether attribution is required when reproducing the work commercially or not. - * @param request.licenseTermsData.terms.commercializerChecker Commercializers that are allowed to commercially exploit the work. If zero address, then no restrictions is enforced. - * @param request.licenseTermsData.terms.commercializerCheckerData The data to be passed to the commercializer checker contract. - * @param request.licenseTermsData.terms.commercialRevShare Percentage of revenue that must be shared with the licensor. - * @param request.licenseTermsData.terms.commercialRevCeiling The maximum revenue that can be generated from the commercial use of the work. - * @param request.licenseTermsData.terms.derivativesAllowed Indicates whether the licensee can create derivatives of his work or not. - * @param request.licenseTermsData.terms.derivativesAttribution Indicates whether attribution is required for derivatives of the work or not. - * @param request.licenseTermsData.terms.derivativesApproval Indicates whether the licensor must approve derivatives of the work before they can be linked to the licensor IP ID or not. - * @param request.licenseTermsData.terms.derivativesReciprocal Indicates whether the licensee must license derivatives of the work under the same terms or not. - * @param request.licenseTermsData.terms.derivativeRevCeiling The maximum revenue that can be generated from the derivative use of the work. - * @param request.licenseTermsData.terms.currency The ERC20 token to be used to pay the minting fee. the token must be registered in story protocol. - * @param request.licenseTermsData.terms.uri The URI of the license terms, which can be used to fetch the offchain license terms. - * @param {Object} request.licenseTermsData.licensingConfig The PIL terms and licensing configuration data to attach to the IP. - * @param request.licenseTermsData.licensingConfig.isSet Whether the configuration is set or not. - * @param request.licenseTermsData.licensingConfig.mintingFee The minting fee to be paid when minting license tokens. - * @param request.licenseTermsData.licensingConfig.licensingHook The hook contract address for the licensing module, or address(0) if none - * @param request.licenseTermsData.licensingConfig.hookData The data to be used by the licensing hook. - * @param request.licenseTermsData.licensingConfig.commercialRevShare The commercial revenue share percentage. - * @param request.licenseTermsData.licensingConfig.disabled Whether the licensing is disabled or not. - * @param request.licenseTermsData.licensingConfig.expectMinimumGroupRewardShare The minimum percentage of the group’s reward share (from 0 to 100%, represented as 100 * 10 ** 6) that can be allocated to the IP when it is added to the group. - * If the remaining reward share in the group is less than the minimumGroupRewardShare,the IP cannot be added to the group. - * @param request.licenseTermsData.licensingConfig.expectGroupRewardPool The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, or address(0) if the IP does not want to be added to any group. - * @param {Object} request.ipMetadata - [Optional] The desired metadata for the newly minted NFT and newly registered IP. - * @param request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP. - * @param request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP. - * @param request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT. - * @param request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT. - * @param request.deadline [Optional] The deadline for the signature in seconds, default is 1000s. - * @param request.txOptions - [Optional] transaction. This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property. - * @returns A Promise that resolves to a transaction hash, if waitForTransaction is true, including IP ID, token ID and License terms IDs. - * @emits LicenseTermsAttached (caller, ipId, licenseTemplate, licenseTermsId) + * Register a given NFT as an IP and attach Programmable IP License Terms. + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/modules/licensing/ILicensingModule.sol | ILicensingModule} + * for a list of on-chain events emitted when an ip is registered and license terms are attached to it. */ public async registerIpAndAttachPilTerms( request: RegisterIpAndAttachPilTermsRequest, @@ -974,22 +884,8 @@ export class IPAssetClient { } /** * Register the given NFT as a derivative IP with metadata without using license tokens. - * @param request - The request object that contains all data needed to register derivative IP. - * @param request.nftContract The address of the NFT collection. - * @param request.tokenId The ID of the NFT. - * @param {Object} request.derivData The derivative data to be used for registerDerivative. - * @param {Array} request.derivData.parentIpIds The IDs of the parent IPs to link the registered derivative IP. - * @param {Array} request.derivData.licenseTermsIds The IDs of the license terms to be used for the linking. - * @param request.derivData.licenseTemplate [Optional] The address of the license template to be used for the linking, default value is Programmable IP License. - * @param {Object} request.ipMetadata - [Optional] The desired metadata for the newly minted NFT and newly registered IP. - * @param request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP. - * @param request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP. - * @param request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT. - * @param request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT. - * @param request.deadline [Optional] The deadline for the signature in seconds, default is 1000s. - * @param request.txOptions - [Optional] transaction. This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property. - * @returns A Promise that resolves to a transaction hash, and if encodedTxDataOnly is true, includes encoded transaction data, and if waitForTransaction is true, included IP ID, Token ID. - * @emits IPRegistered (ipId, chainId, tokenContract, tokenId, name, uri, registrationDate) + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/registries/IIPAssetRegistry.sol | IIPAssetRegistry} + * for a list of on-chain events emitted when a derivative IP is registered. */ public async registerDerivativeIp( request: RegisterIpAndMakeDerivativeRequest, @@ -1063,26 +959,8 @@ export class IPAssetClient { } /** * Mint an NFT from a collection and register it as a derivative IP without license tokens. - * @param request - The request object that contains all data needed to mint and register ip and make derivative. - * @param request.spgNftContract The address of the NFT collection. - * @param request.allowDuplicates Set to true to allow minting an NFT with a duplicate metadata hash. - * @param {Object} request.derivData The derivative data to be used for registerDerivative. - * @param {Array} request.derivData.parentIpIds The IDs of the parent IPs to link the registered derivative IP. - * @param {Array} request.derivData.licenseTermsIds The IDs of the license terms to be used for the linking. - * @param request.derivData.licenseTemplate [Optional] The address of the license template to be used for the linking, default value is Programmable IP License. - * @param request.derivData.royaltyContext The address of the royalty context to be used for the linking, default value is zero address. - * @param request.derivData.maxMintingFee The maximum minting fee that the caller is willing to pay. if set to 0 then no limit. - * @param request.derivData.maxRts The maximum number of royalty tokens that can be distributed to the external royalty policies (max: 100,000,000). - * @param request.derivData.maxRevenueShare The maximum revenue share percentage allowed for minting the License Tokens. Must be between 0 and 100,000,000 (where 100,000,000 represents 100%). - * @param {Object} request.ipMetadata - [Optional] The desired metadata for the newly minted NFT and newly registered IP. - * @param request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP. - * @param request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP. - * @param request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT. - * @param request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT. - * @param request.recipient [Optional] The address of the recipient of the minted NFT,default value is your wallet address. - * @param request.txOptions - [Optional] transaction. This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property. - * @returns A Promise that resolves to a transaction hash, and if encodedTxDataOnly is true, includes encoded transaction data, and if waitForTransaction is true, includes child IP ID and token ID. - * @emits IPRegistered (ipId, chainId, tokenContract, tokenId, name, uri, registrationDate) + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/registries/IIPAssetRegistry.sol | IIPAssetRegistry} + * for a list of on-chain events emitted when a derivative IP is minted and registered. */ public async mintAndRegisterIpAndMakeDerivative( request: MintAndRegisterIpAndMakeDerivativeRequest, @@ -1223,41 +1101,8 @@ export class IPAssetClient { } /** * Register Programmable IP License Terms (if unregistered) and attach it to IP. - * @param request - The request object that contains all data needed to attach license terms. - * @param request.ipId The ID of the IP. - * @param {Array} request.licenseTermsData The PIL terms and licensing configuration data to be attached to the IP. - * @param {Object} request.licenseTermsData.terms The PIL terms to be used for the licensing. - * @param request.licenseTermsData.terms.transferable Indicates whether the license is transferable or not. - * @param request.licenseTermsData.terms.royaltyPolicy The address of the royalty policy contract which required to StoryProtocol in advance. - * @param request.licenseTermsData.terms.mintingFee The fee to be paid when minting a license. - * @param request.licenseTermsData.terms.expiration The expiration period of the license. - * @param request.licenseTermsData.terms.commercialUse Indicates whether the work can be used commercially or not, Commercial use is required to deploy a royalty vault. - * @param request.licenseTermsData.terms.commercialAttribution Whether attribution is required when reproducing the work commercially or not. - * @param request.licenseTermsData.terms.commercializerChecker Commercializers that are allowed to commercially exploit the work. If zero address, then no restrictions is enforced. - * @param request.licenseTermsData.terms.commercializerCheckerData The data to be passed to the commercializer checker contract. - * @param request.licenseTermsData.terms.commercialRevShare Percentage of revenue that must be shared with the licensor. - * @param request.licenseTermsData.terms.commercialRevCeiling The maximum revenue that can be generated from the commercial use of the work. - * @param request.licenseTermsData.terms.derivativesAllowed Indicates whether the licensee can create derivatives of his work or not. - * @param request.licenseTermsData.terms.derivativesAttribution Indicates whether attribution is required for derivatives of the work or not. - * @param request.licenseTermsData.terms.derivativesApproval Indicates whether the licensor must approve derivatives of the work before they can be linked to the licensor IP ID or not. - * @param request.licenseTermsData.terms.derivativesReciprocal Indicates whether the licensee must license derivatives of the work under the same terms or not. - * @param request.licenseTermsData.terms.derivativeRevCeiling The maximum revenue that can be generated from the derivative use of the work. - * @param request.licenseTermsData.terms.currency The ERC20 token to be used to pay the minting fee. the token must be registered in story protocol. - * @param request.licenseTermsData.terms.uri The URI of the license terms, which can be used to fetch the offchain license terms. - * @param {Object} request.licenseTermsData.licensingConfig The PIL terms and licensing configuration data to attach to the IP. - * @param request.licenseTermsData.licensingConfig.isSet Whether the configuration is set or not. - * @param request.licenseTermsData.licensingConfig.mintingFee The minting fee to be paid when minting license tokens. - * @param request.licenseTermsData.licensingConfig.licensingHook The hook contract address for the licensing module, or address(0) if none - * @param request.licenseTermsData.licensingConfig.hookData The data to be used by the licensing hook. - * @param request.licenseTermsData.licensingConfig.commercialRevShare The commercial revenue share percentage. - * @param request.licenseTermsData.licensingConfig.disabled Whether the licensing is disabled or not. - * @param request.licenseTermsData.licensingConfig.expectMinimumGroupRewardShare The minimum percentage of the group’s reward share (from 0 to 100%, represented as 100 * 10 ** 6) that can be allocated to the IP when it is added to the group. - * If the remaining reward share in the group is less than the minimumGroupRewardShare,the IP cannot be added to the group. - * @param request.licenseTermsData.licensingConfig.expectGroupRewardPool The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, or address(0) if the IP does not want to be added to any group. - * @param request.deadline [Optional] The deadline for the signature in milliseconds, default is 1000s. - * @param request.txOptions [Optional] This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property. - * @returns A Promise that resolves to a transaction hash, and if encodedTxDataOnly is true, includes encoded transaction data, and if waitForTransaction is true, returns an array containing the license terms ID. - * @emits LicenseTermsAttached (caller, ipId, licenseTemplate, licenseTermsId) + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/modules/licensing/ILicensingModule.sol | ILicensingModule} + * for a list of on-chain events emitted when a license terms is attached to an IP. */ public async registerPilTermsAndAttach( request: RegisterPilTermsAndAttachRequest, @@ -1495,51 +1340,9 @@ export class IPAssetClient { /** * Register the given NFT and attach license terms and distribute royalty tokens. In order to successfully distribute royalty tokens, the first license terms attached to the IP must be * a commercial license. - * @param request - The request object that contains all data needed to register ip and attach license terms and distribute royalty tokens. - * @param request.nftContract The address of the NFT collection. - * @param request.tokenId The ID of the NFT. - * @param {Array} request.licenseTermsData The PIL terms and licensing configuration data to be attached to the IP. - * @param {Object} request.licenseTermsData.terms The PIL terms to be used for the licensing. - * @param request.licenseTermsData.terms.transferable Indicates whether the license is transferable or not. - * @param request.licenseTermsData.terms.royaltyPolicy The address of the royalty policy contract which required to StoryProtocol in advance. - * @param request.licenseTermsData.terms.mintingFee The fee to be paid when minting a license. - * @param request.licenseTermsData.terms.expiration The expiration period of the license. - * @param request.licenseTermsData.terms.commercialUse Indicates whether the work can be used commercially or not, Commercial use is required to deploy a royalty vault. - * @param request.licenseTermsData.terms.commercialAttribution Whether attribution is required when reproducing the work commercially or not. - * @param request.licenseTermsData.terms.commercializerChecker Commercializers that are allowed to commercially exploit the work. If zero address, then no restrictions is enforced. - * @param request.licenseTermsData.terms.commercializerCheckerData The data to be passed to the commercializer checker contract. - * @param request.licenseTermsData.terms.commercialRevShare Percentage of revenue that must be shared with the licensor. - * @param request.licenseTermsData.terms.commercialRevCeiling The maximum revenue that can be generated from the commercial use of the work. - * @param request.licenseTermsData.terms.derivativesAllowed Indicates whether the licensee can create derivatives of his work or not. - * @param request.licenseTermsData.terms.derivativesAttribution Indicates whether attribution is required for derivatives of the work or not. - * @param request.licenseTermsData.terms.derivativesApproval Indicates whether the licensor must approve derivatives of the work before they can be linked to the licensor IP ID or not. - * @param request.licenseTermsData.terms.derivativesReciprocal Indicates whether the licensee must license derivatives of the work under the same terms or not. - * @param request.licenseTermsData.terms.derivativeRevCeiling The maximum revenue that can be generated from the derivative use of the work. - * @param request.licenseTermsData.terms.currency The ERC20 token to be used to pay the minting fee. the token must be registered in story protocol. - * @param request.licenseTermsData.terms.uri The URI of the license terms, which can be used to fetch the offchain license terms. - * @param {Object} request.licenseTermsData.licensingConfig The PIL terms and licensing configuration data to attach to the IP. - * @param request.licenseTermsData.licensingConfig.isSet Whether the configuration is set or not. - * @param request.licenseTermsData.licensingConfig.mintingFee The minting fee to be paid when minting license tokens. - * @param request.licenseTermsData.licensingConfig.licensingHook The hook contract address for the licensing module, or address(0) if none - * @param request.licenseTermsData.licensingConfig.hookData The data to be used by the licensing hook. - * @param request.licenseTermsData.licensingConfig.commercialRevShare The commercial revenue share percentage. - * @param request.licenseTermsData.licensingConfig.disabled Whether the licensing is disabled or not. - * @param request.licenseTermsData.licensingConfig.expectMinimumGroupRewardShare The minimum percentage of the group’s reward share (from 0 to 100%, represented as 100 * 10 ** 6) that can be allocated to the IP when it is added to the group. - * If the remaining reward share in the group is less than the minimumGroupRewardShare,the IP cannot be added to the group. - * @param request.licenseTermsData.licensingConfig.expectGroupRewardPool The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, or address(0) if the IP does not want to be added to any group. - * @param {Object} request.ipMetadata - [Optional] The desired metadata for the newly minted NFT and newly registered IP. - * @param request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP. - * @param request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP. - * @param request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT. - * @param request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT. - * @param {Array} request.royaltyShares Authors of the IP and their shares of the royalty tokens. - * @param request.royaltyShares.recipient The address of the recipient. - * @param request.royaltyShares.percentage The percentage of the royalty share, 10 represents 10%. - * @param request.deadline [Optional] The deadline for the signature in seconds, default is 1000s. - * @param request.txOptions [Optional] This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property, without encodedTxData option. - * @returns A Promise that resolves to a transaction hashes, IP ID, IP royalty vault and an array containing the license terms ID. - * @emits IPRegistered (ipId, chainId, tokenContract, tokenId, name, uri, registrationDate) - * @emits IpRoyaltyVaultDeployed (ipId, ipRoyaltyVault) + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/registries/IIPAssetRegistry.sol | IIPAssetRegistry} + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/modules/royalty/IRoyaltyModule.sol| IRoyaltyModule} + * for a list of on-chain events emitted when an IP is registered, license terms are attached to an IP, and royalty tokens are distributed. */ public async registerIPAndAttachLicenseTermsAndDistributeRoyaltyTokens( request: RegisterIPAndAttachLicenseTermsAndDistributeRoyaltyTokensRequest, @@ -1644,29 +1447,9 @@ export class IPAssetClient { /** * Register the given NFT as a derivative IP and attach license terms and distribute royalty tokens. In order to successfully distribute royalty tokens, the license terms attached to the IP must be * a commercial license. - * @param request - The request object that contains all data needed to register derivative IP and distribute royalty tokens. - * @param request.nftContract The address of the NFT collection. - * @param request.tokenId The ID of the NFT. - * @param {Object} request.derivData The derivative data to be used for registerDerivative. - * @param {Array} request.derivData.parentIpIds The IDs of the parent IPs to link the registered derivative IP. - * @param request.derivData.licenseTemplate [Optional] The address of the license template to be used for the linking, default value is Programmable IP License. - * @param {Array} request.derivData.licenseTermsIds The IDs of the license terms to be used for the linking. - * @param request.derivData.maxMintingFee The maximum minting fee that the caller is willing to pay. if set to 0 then no limit. - * @param request.derivData.maxRts The maximum number of royalty tokens that can be distributed to the external royalty policies (max: 100,000,000). - * @param request.derivData.maxRevenueShare The maximum revenue share percentage allowed for minting the License Tokens. Must be between 0 and 100,000,000 (where 100,000,000 represents 100%). - * @param {Object} request.ipMetadata - [Optional] The desired metadata for the newly minted NFT and newly registered IP. - * @param request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP. - * @param request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP. - * @param request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT. - * @param request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT. - * @param {Array} request.royaltyShares Authors of the IP and their shares of the royalty tokens. - * @param request.royaltyShares.recipient The address of the recipient. - * @param request.royaltyShares.percentage The percentage of the royalty share, 10 represents 10%. - * @param request.deadline [Optional] The deadline for the signature in seconds, default is 1000s. - * @param request.txOptions - [Optional] transaction. This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property, without encodedTxData option. - * @returns A Promise that resolves to a transaction hashes, IP ID and IP royalty vault, token ID. - * @emits IPRegistered (ipId, chainId, tokenContract, tokenId, name, uri, registrationDate) - * @emits IpRoyaltyVaultDeployed (ipId, ipRoyaltyVault) + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/registries/IIPAssetRegistry.sol | IIPAssetRegistry} + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/modules/royalty/IRoyaltyModule.sol| IRoyaltyModule} + * for a list of on-chain events emitted when a derivative IP is registered, license terms are attached to an IP, and royalty tokens are distributed. */ public async registerDerivativeIpAndAttachLicenseTermsAndDistributeRoyaltyTokens( request: RegisterDerivativeAndAttachLicenseTermsAndDistributeRoyaltyTokensRequest, @@ -1776,51 +1559,9 @@ export class IPAssetClient { /** * Mint an NFT and register the IP, attach PIL terms, and distribute royalty tokens. - * @param request - The request object that contains all data needed to mint an NFT and register the IP, attach PIL terms, and distribute royalty tokens. - * @param request.spgNftContract The address of the SPG NFT contract. - * @param request.allowDuplicates Set to true to allow minting an NFT with a duplicate metadata hash. - * @param {Array} request.licenseTermsData The PIL terms and licensing configuration data to attach to the IP. - * @param {Object} request.licenseTermsData.terms The PIL terms to be attached. - * @param request.licenseTermsData.terms.transferable Indicates whether the license is transferable or not. - * @param request.licenseTermsData.terms.royaltyPolicy The address of the royalty policy contract which required to StoryProtocol in advance. - * @param request.licenseTermsData.terms.mintingFee The fee to be paid when minting a license. - * @param request.licenseTermsData.terms.expiration The expiration period of the license. - * @param request.licenseTermsData.terms.commercialUse Indicates whether the work can be used commercially or not, Commercial use is required to deploy a royalty vault. - * @param request.licenseTermsData.terms.commercialAttribution Whether attribution is required when reproducing the work commercially or not. - * @param request.licenseTermsData.terms.commercializerChecker Commercializers that are allowed to commercially exploit the work. If zero address, then no restrictions is enforced. - * @param request.licenseTermsData.terms.commercializerCheckerData The data to be passed to the commercializer checker contract. - * @param request.licenseTermsData.terms.commercialRevShare Percentage of revenue that must be shared with the licensor. - * @param request.licenseTermsData.terms.commercialRevCeiling The maximum revenue that can be generated from the commercial use of the work. - * @param request.licenseTermsData.terms.derivativesAllowed Indicates whether the licensee can create derivatives of his work or not. - * @param request.licenseTermsData.terms.derivativesAttribution Indicates whether attribution is required for derivatives of the work or not. - * @param request.licenseTermsData.terms.derivativesApproval Indicates whether the licensor must approve derivatives of the work before they can be linked to the licensor IP ID or not. - * @param request.licenseTermsData.terms.derivativesReciprocal Indicates whether the licensee must license derivatives of the work under the same terms or not. - * @param request.licenseTermsData.terms.derivativeRevCeiling The maximum revenue that can be generated from the derivative use of the work. - * @param request.licenseTermsData.terms.currency The ERC20 token to be used to pay the minting fee. the token must be registered in story protocol. - * @param request.licenseTermsData.terms.uri The URI of the license terms, which can be used to fetch the offchain license terms. - * @param {Object} request.licenseTermsData.licensingConfig The PIL terms and licensing configuration data to attach to the IP. - * @param request.licenseTermsData.licensingConfig.isSet Whether the configuration is set or not. - * @param request.licenseTermsData.licensingConfig.mintingFee The minting fee to be paid when minting license tokens. - * @param request.licenseTermsData.licensingConfig.licensingHook The hook contract address for the licensing module, or address(0) if none - * @param request.licenseTermsData.licensingConfig.hookData The data to be used by the licensing hook. - * @param request.licenseTermsData.licensingConfig.commercialRevShare The commercial revenue share percentage. - * @param request.licenseTermsData.licensingConfig.disabled Whether the licensing is disabled or not. - * @param request.licenseTermsData.licensingConfig.expectMinimumGroupRewardShare The minimum percentage of the group’s reward share (from 0 to 100%, represented as 100 * 10 ** 6) that can be allocated to the IP when it is added to the group. - * If the remaining reward share in the group is less than the minimumGroupRewardShare,the IP cannot be added to the group. - * @param request.licenseTermsData.licensingConfig.expectGroupRewardPool The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, or address(0) if the IP does not want to be added to any group. - * @param {Object} request.ipMetadata - [Optional] The desired metadata for the newly minted NFT and newly registered IP. - * @param request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP. - * @param request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP. - * @param request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT. - * @param request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT. - * @param {Array} request.royaltyShares Authors of the IP and their shares of the royalty tokens. - * @param request.royaltyShares.recipient The address of the recipient. - * @param request.royaltyShares.percentage The percentage of the royalty share, 10 represents 10%. - * @param request.recipient - [Optional] The address to receive the minted NFT,default value is your wallet address. - * @param request.txOptions [Optional] This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property, without encodedTxData option. - * @returns A Promise that resolves to a transaction hash, IP ID, IP royalty vault, Token ID, and an array containing the license terms ID. - * @emits IPRegistered (ipId, chainId, tokenContract, tokenId, name, uri, registrationDate) - * @emits IpRoyaltyVaultDeployed (ipId, ipRoyaltyVault) + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/registries/IIPAssetRegistry.sol | IIPAssetRegistry} + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/modules/royalty/IRoyaltyModule.sol| IRoyaltyModule} + * for a list of on-chain events emitted when an IP is minted and registered, PIL terms are attached to an IP, and royalty tokens are distributed. */ public async mintAndRegisterIpAndAttachPilTermsAndDistributeRoyaltyTokens( request: MintAndRegisterIpAndAttachPILTermsAndDistributeRoyaltyTokensRequest, @@ -1881,28 +1622,8 @@ export class IPAssetClient { } /** * Mint an NFT and register the IP, make a derivative, and distribute royalty tokens. - * @param request - The request object that contains all data needed to mint an NFT and register the IP, make a derivative, and distribute royalty tokens. - * @param request.spgNftContract The address of the SPG NFT collection. - * @param request.derivData The derivative data to be used for registerDerivative. - * @param {Array} request.derivData.parentIpIds The IDs of the parent IPs to link the registered derivative IP. - * @param request.derivData.licenseTemplate [Optional] The address of the license template to be used for the linking, default value is Programmable IP License. - * @param {Array} request.derivData.licenseTermsIds The IDs of the license terms to be used for the linking. - * @param request.derivData.maxMintingFee The maximum minting fee that the caller is willing to pay. if set to 0 then no limit. - * @param request.derivData.maxRts The maximum number of royalty tokens that can be distributed to the external royalty policies (max: 100,000,000). - * @param request.derivData.maxRevenueShare The maximum revenue share percentage allowed for minting the License Tokens. Must be between 0 and 100,000,000 (where 100,000,000 represents 100%). - * @param {Object} request.ipMetadata - [Optional] The desired metadata for the newly minted NFT and newly registered IP. - * @param request.ipMetadata.ipMetadataURI [Optional] The URI of the metadata for the IP. - * @param request.ipMetadata.ipMetadataHash [Optional] The hash of the metadata for the IP. - * @param request.ipMetadata.nftMetadataURI [Optional] The URI of the metadata for the NFT. - * @param request.ipMetadata.nftMetadataHash [Optional] The hash of the metadata for the IP NFT. - * @param {Array} request.royaltyShares Authors of the IP and their shares of the royalty tokens. - * @param request.royaltyShares.recipient The address of the recipient. - * @param request.royaltyShares.percentage The percentage of the royalty share, 10 represents 10%. - * @param request.allowDuplicates Set to true to allow minting an NFT with a duplicate metadata hash. - * @param request.recipient - [Optional] The address to receive the minted NFT,default value is your wallet address. - * @param request.txOptions - [Optional] transaction. This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property, without encodedTxData option.. - * @returns A Promise that resolves to a transaction hash, IP ID and token ID. - * @emits IPRegistered (ipId, chainId, tokenContract, tokenId, name, uri, registrationDate) + * @see {@link https://github.com/storyprotocol/protocol-core-v1/blob/main/contracts/interfaces/registries/IIPAssetRegistry.sol | IIPAssetRegistry} + * for a list of on-chain events emitted when an IP is minted and registered, a derivative IP is made, and royalty tokens are distributed. */ public async mintAndRegisterIpAndMakeDerivativeAndDistributeRoyaltyTokens( request: MintAndRegisterIpAndMakeDerivativeAndDistributeRoyaltyTokensRequest, @@ -2102,9 +1823,9 @@ export class IPAssetClient { getAddress(derivativeData.licenseTemplate, "derivativeData.licenseTemplate")) || this.licenseTemplateClient.address, royaltyContext: zeroAddress, - maxMintingFee: BigInt(derivativeData.maxMintingFee), - maxRts: Number(derivativeData.maxRts), - maxRevenueShare: getRevenueShare(derivativeData.maxRevenueShare), + maxMintingFee: BigInt(derivativeData.maxMintingFee || 0), + maxRts: Number(derivativeData.maxRts || MAX_ROYALTY_TOKEN), + maxRevenueShare: getRevenueShare(derivativeData.maxRevenueShare || 100), }; if (internalDerivativeData.parentIpIds.length === 0) { throw new Error("The parent IP IDs must be provided."); @@ -2159,10 +1880,10 @@ export class IPAssetClient { licenseTermsData: LicenseTermsData[], ): Promise<{ licenseTerms: LicenseTerms[]; - licenseTermsData: LicenseTermsData[]; + licenseTermsData: ValidatedLicenseTermsData[]; }> { const licenseTerms: LicenseTerms[] = []; - const processedLicenseTermsData: LicenseTermsData[] = []; + const processedLicenseTermsData: ValidatedLicenseTermsData[] = []; for (let i = 0; i < licenseTermsData.length; i++) { const licenseTerm = await validateLicenseTerms(licenseTermsData[i].terms, this.rpcClient); const licensingConfig = validateLicenseConfig(licenseTermsData[i].licensingConfig); diff --git a/packages/core-sdk/src/resources/license.ts b/packages/core-sdk/src/resources/license.ts index d601532da..ab43e1812 100644 --- a/packages/core-sdk/src/resources/license.ts +++ b/packages/core-sdk/src/resources/license.ts @@ -43,10 +43,11 @@ import { getRevenueShare, validateLicenseTerms, } from "../utils/licenseTermsHelper"; -import { chain, getAddress } from "../utils/utils"; +import { chain, getAddress, validateAddress } from "../utils/utils"; import { ChainIds } from "../types/config"; import { calculateLicenseWipMintFee, contractCallWithFees } from "../utils/feeUtils"; import { Erc20Spender } from "../types/utils/wip"; +import { validateLicenseConfig } from "../utils/validateLicenseConfig"; export class LicenseClient { public licenseRegistryClient: LicenseRegistryEventClient; @@ -538,23 +539,6 @@ export class LicenseClient { /** * Sets the licensing configuration for a specific license terms of an IP. If both licenseTemplate and licenseTermsId are not specified then the licensing config apply to all licenses of given IP. - * @param request - The request object that contains all data needed to set licensing config. - * @param request.ipId The address of the IP for which the configuration is being set. - * @param request.licenseTermsId The ID of the license terms within the license template. - * @param request.licenseTemplate The address of the license template used, If not specified, the configuration applies to all licenses. - * @param request.licensingConfig The licensing configuration for the license. - * @param request.licensingConfig.isSet Whether the configuration is set or not. - * @param request.licensingConfig.mintingFee The minting fee to be paid when minting license tokens. - * @param request.licensingConfig.hookData The data to be used by the licensing hook. - * @param request.licensingConfig.licensingHook The hook contract address for the licensing module, or address(0) if none. - * @param request.licensingConfig.commercialRevShare The commercial revenue share percentage. - * @param request.licensingConfig.disabled Whether the license is disabled or not. - * @param request.licensingConfig.expectMinimumGroupRewardShare The minimum percentage of the group’s reward share (from 0 to 100%, represented as 100 * 10 ** 6) that can be allocated to the IP when it is added to the group. - * If the remaining reward share in the group is less than the minimumGroupRewardShare, the IP cannot be added to the group. - * @param request.licensingConfig.expectGroupRewardPool The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, - * or address(0) if the IP does not want to be added to any group. - * @param request.txOptions [Optional] This extends `WaitForTransactionReceiptParameters` from the Viem library, excluding the `hash` property. - * @returns A Promise that resolves to a transaction hash, and if encodedTxDataOnly is true, includes encoded transaction data, and if waitForTransaction is true, includes success. */ public async setLicensingConfig( request: SetLicensingConfigRequest, @@ -562,56 +546,36 @@ export class LicenseClient { try { const req: LicensingModuleSetLicensingConfigRequest = { ipId: request.ipId, - licenseTemplate: getAddress(request.licenseTemplate, "request.licenseTemplate"), + licenseTemplate: validateAddress(request.licenseTemplate), licenseTermsId: BigInt(request.licenseTermsId), - licensingConfig: { - isSet: request.licensingConfig.isSet, - mintingFee: BigInt(request.licensingConfig.mintingFee), - hookData: request.licensingConfig.hookData, - licensingHook: request.licensingConfig.licensingHook, - disabled: request.licensingConfig.disabled, - commercialRevShare: getRevenueShare(request.licensingConfig.commercialRevShare), - expectGroupRewardPool: getAddress( - request.licensingConfig.expectGroupRewardPool, - "request.licensingConfig.expectGroupRewardPool", - ), - expectMinimumGroupRewardShare: Number( - request.licensingConfig.expectMinimumGroupRewardShare, - ), - }, + licensingConfig: validateLicenseConfig(request.licensingConfig), }; - if (req.licensingConfig.mintingFee < 0) { - throw new Error("The minting fee must be greater than 0."); - } - if ( - request.licenseTemplate === zeroAddress && - request.licensingConfig.commercialRevShare !== 0 - ) { + if (req.licenseTemplate === zeroAddress && req.licensingConfig.commercialRevShare !== 0) { throw new Error( "The license template cannot be zero address if commercial revenue share is not zero.", ); } const isLicenseIpIdRegistered = await this.ipAssetRegistryClient.isRegistered({ - id: getAddress(request.ipId, "request.ipId"), + id: validateAddress(req.ipId), }); if (!isLicenseIpIdRegistered) { - throw new Error(`The licensor IP with id ${request.ipId} is not registered.`); + throw new Error(`The licensor IP with id ${req.ipId} is not registered.`); } const isExisted = await this.piLicenseTemplateReadOnlyClient.exists({ licenseTermsId: req.licenseTermsId, }); if (!isExisted) { - throw new Error(`License terms id ${request.licenseTermsId} do not exist.`); + throw new Error(`License terms id ${req.licenseTermsId} do not exist.`); } - if (request.licensingConfig.licensingHook !== zeroAddress) { + if (req.licensingConfig.licensingHook !== zeroAddress) { const isRegistered = await this.moduleRegistryReadOnlyClient.isRegistered({ - moduleAddress: request.licensingConfig.licensingHook, + moduleAddress: req.licensingConfig.licensingHook, }); if (!isRegistered) { throw new Error("The licensing hook is not registered."); } } - if (request.licenseTemplate === zeroAddress && request.licenseTermsId !== 0n) { + if (req.licenseTemplate === zeroAddress && req.licenseTermsId !== 0n) { throw new Error("The license template is zero address but license terms id is not zero."); } diff --git a/packages/core-sdk/src/types/common.ts b/packages/core-sdk/src/types/common.ts index 8de88073a..f04e28426 100644 --- a/packages/core-sdk/src/types/common.ts +++ b/packages/core-sdk/src/types/common.ts @@ -9,25 +9,33 @@ export type TypedData = { }; export type IpMetadataAndTxOptions = WithTxOptions & { + /** The desired metadata for the newly minted NFT and newly registered IP. */ ipMetadata?: Partial; }; - export type LicensingConfig = { + /** Whether the configuration is set or not */ isSet: boolean; + /** The minting fee to be paid when minting license tokens. */ mintingFee: bigint | string | number; + /** The hook contract address for the licensing module, or zero address if none. */ licensingHook: Address; + /** The data to be used by the licensing hook. */ hookData: Hex; + /** The commercial revenue share percentage (from 0 to 100%, represented as 100_000_000). */ commercialRevShare: number | string; + /** Whether the licensing is disabled or not. */ disabled: boolean; + /** The minimum percentage of the group’s reward share (from 0 to 100%, represented as 100_000_000) that can be allocated to the IP when it is added to the group. */ expectMinimumGroupRewardShare: number | string; + /** The address of the expected group reward pool. The IP can only be added to a group with this specified reward pool address, or zero address if the IP does not want to be added to any group. */ expectGroupRewardPool: Address; }; -export type InnerLicensingConfig = { +export type ValidatedLicensingConfig = LicensingConfig & { mintingFee: bigint; commercialRevShare: number; expectMinimumGroupRewardShare: number; -} & LicensingConfig; +}; /** * Input for token amount, can be bigint or number. diff --git a/packages/core-sdk/src/types/resources/group.ts b/packages/core-sdk/src/types/resources/group.ts index 81f15e3a9..e14cfd5f8 100644 --- a/packages/core-sdk/src/types/resources/group.ts +++ b/packages/core-sdk/src/types/resources/group.ts @@ -2,27 +2,35 @@ import { Address } from "viem"; import { TxOptions } from "../options"; import { EncodedTxData } from "../../abi/generated"; -import { InnerLicensingConfig, IpMetadataAndTxOptions, LicensingConfig } from "../common"; +import { IpMetadataAndTxOptions, LicensingConfig, ValidatedLicensingConfig } from "../common"; export type LicenseData = { licenseTermsId: string | bigint | number; - licensingConfig: LicensingConfig; + licensingConfig?: LicensingConfig; licenseTemplate?: Address; }; -export type InnerLicenseData = { +export type ValidatedLicenseData = { licenseTermsId: bigint; - licensingConfig: InnerLicensingConfig; + licensingConfig: ValidatedLicensingConfig; licenseTemplate: Address; }; - export type MintAndRegisterIpAndAttachLicenseAndAddToGroupRequest = { spgNftContract: Address; + /** The ID of the group IP to add the newly registered IP. */ groupId: Address; + /** Set to true to allow minting an NFT with a duplicate metadata hash. */ allowDuplicates: boolean; + /** The maximum reward share percentage that can be allocated to each member IP. */ maxAllowedRewardShare: number | string; + /** The data of the license and its configuration to be attached to the new group IP. */ licenseData: LicenseData[]; + /** The address of the recipient of the minted NFT. If not provided, the function will use the user's own wallet address. */ recipient?: Address; + /** + * The deadline for the signature in seconds. + * @default 1000 + */ deadline?: string | number | bigint; } & IpMetadataAndTxOptions; @@ -42,13 +50,19 @@ export type RegisterGroupResponse = { encodedTxData?: EncodedTxData; groupId?: Address; }; - export type RegisterIpAndAttachLicenseAndAddToGroupRequest = { nftContract: Address; tokenId: bigint | string | number; + /** The ID of the group IP to add the newly registered IP. */ groupId: Address; + /** + * The deadline for the signature in seconds. + * @default 1000 + */ deadline?: bigint; + /** The data of the license and its configuration to be attached to the new group IP. */ licenseData: LicenseData[]; + /** The maximum reward share percentage that can be allocated to each member IP. */ maxAllowedRewardShare: number | string; } & IpMetadataAndTxOptions; @@ -59,7 +73,9 @@ export type RegisterIpAndAttachLicenseAndAddToGroupResponse = { tokenId?: bigint; }; export type RegisterGroupAndAttachLicenseRequest = { + /** The address specifying how royalty will be split amongst the pool of IPs in the group. */ groupPool: Address; + /** The data of the license and its configuration to be attached to the new group IP. */ licenseData: LicenseData; txOptions?: TxOptions; }; @@ -69,11 +85,14 @@ export type RegisterGroupAndAttachLicenseResponse = { encodedTxData?: EncodedTxData; groupId?: Address; }; - export type RegisterGroupAndAttachLicenseAndAddIpsRequest = { + /** The address specifying how royalty will be split amongst the pool of IPs in the group. */ groupPool: Address; + /** The IP IDs of the IPs to be added to the group. */ ipIds: Address[]; + /** The data of the license and its configuration to be attached to the new group IP. */ licenseData: LicenseData; + /** The maximum reward share percentage that can be allocated to each member IP. */ maxAllowedRewardShare: number | string; txOptions?: TxOptions; }; diff --git a/packages/core-sdk/src/types/resources/ipAsset.ts b/packages/core-sdk/src/types/resources/ipAsset.ts index 928153279..fb89a9844 100644 --- a/packages/core-sdk/src/types/resources/ipAsset.ts +++ b/packages/core-sdk/src/types/resources/ipAsset.ts @@ -1,17 +1,31 @@ import { Address, Hash, Hex, TransactionReceipt } from "viem"; import { TxOptions, WithWipOptions } from "../options"; -import { RegisterPILTermsRequest } from "./license"; +import { LicenseTerms, RegisterPILTermsRequest } from "./license"; import { EncodedTxData } from "../../abi/generated"; -import { IpMetadataAndTxOptions, LicensingConfig } from "../common"; +import { IpMetadataAndTxOptions, LicensingConfig, ValidatedLicensingConfig } from "../common"; import { IpMetadataForWorkflow } from "../../utils/getIpMetadataForWorkflow"; export type DerivativeData = { parentIpIds: Address[]; + /** The IDs of the license terms that the parent IP supports. */ licenseTermsIds: bigint[] | string[] | number[]; - maxMintingFee: bigint | string | number; - maxRts: number | string; - maxRevenueShare: number | string; + /** + * The maximum minting fee that the caller is willing to pay. if set to 0 then no limit. + * @default 0 + */ + maxMintingFee?: bigint | string | number; + /** + * The maximum number of royalty tokens that can be distributed to the external royalty policies (max: 100,000,000). + * @default 100_000_000 + */ + maxRts?: number | string; + /** + * The maximum revenue share percentage allowed for minting the License Tokens. Must be between 0 and 100 (where 100% represents 100_000_000). + * @default 100 + */ + maxRevenueShare?: number | string; + /** The license template address, default value is Programmable IP License. */ licenseTemplate?: Address; }; export type InternalDerivativeData = { @@ -54,16 +68,26 @@ export type RegisterDerivativeResponse = { txHash?: Hex; encodedTxData?: EncodedTxData; }; -export type LicenseTermsData = { +export type LicenseTermsData = { terms: T; - licensingConfig: U; + licensingConfig?: C; +}; + +export type ValidatedLicenseTermsData = Omit< + LicenseTermsData, + "licensingConfig" +> & { + licensingConfig: ValidatedLicensingConfig; }; + export type MintAndRegisterIpAssetWithPilTermsRequest = { spgNftContract: Address; + /** Indicates whether the license terms can be attached to the same IP ID or not. */ allowDuplicates: boolean; - licenseTermsData: LicenseTermsData[]; + /** The data of the license and its configuration to be attached to the IP. */ + licenseTermsData: LicenseTermsData[]; + /** The address to receive the minted NFT. If not provided, the function will use the user's own wallet address. */ recipient?: Address; - royaltyPolicyAddress?: Address; } & IpMetadataAndTxOptions & WithWipOptions; @@ -79,13 +103,13 @@ export type MintAndRegisterIpAssetWithPilTermsResponse = { export type RegisterIpAndMakeDerivativeRequest = { nftContract: Address; tokenId: string | number | bigint; + /** + * The deadline for the signature in seconds. + * @default 1000 + */ deadline?: string | number | bigint; + /** The derivative data to be used for register derivative. */ derivData: DerivativeData; - sigMetadataAndRegister?: { - signer: Address; - deadline: bigint | string | number; - signature: Hex; - }; } & IpMetadataAndTxOptions & WithWipOptions; @@ -100,7 +124,12 @@ export type RegisterIpAndMakeDerivativeResponse = { export type RegisterIpAndAttachPilTermsRequest = { nftContract: Address; tokenId: bigint | string | number; - licenseTermsData: LicenseTermsData[]; + /** The data of the license and its configuration to be attached to the IP. */ + licenseTermsData: LicenseTermsData[]; + /** + * The deadline for the signature in seconds. + * @default 1000 + */ deadline?: bigint | number | string; } & IpMetadataAndTxOptions; @@ -111,11 +140,13 @@ export type RegisterIpAndAttachPilTermsResponse = { licenseTermsIds?: bigint[]; tokenId?: bigint; }; - export type MintAndRegisterIpAndMakeDerivativeRequest = { spgNftContract: Address; + /** The derivative data to be used for register derivative. */ derivData: DerivativeData; + /** The address to receive the minted NFT. If not provided, the function will use the user's own wallet address. */ recipient?: Address; + /** Set to true to allow minting an NFT with a duplicate metadata hash. */ allowDuplicates: boolean; } & IpMetadataAndTxOptions & WithWipOptions; @@ -221,10 +252,13 @@ export type MintAndRegisterIpRequest = { recipient?: Address; allowDuplicates: boolean; } & IpMetadataAndTxOptions; - export type RegisterPilTermsAndAttachRequest = { ipId: Address; - licenseTermsData: LicenseTermsData[]; + /** The data of the license and its configuration to be attached to the IP. */ + licenseTermsData: LicenseTermsData[]; + /** The deadline for the signature in seconds. + * @default 1000 + */ deadline?: string | number | bigint; txOptions?: TxOptions; }; @@ -296,12 +330,17 @@ export type BatchRegisterResponse = { spgTxHash?: Hex; results?: IpIdAndTokenId<"nftContract">[]; }; - export type RegisterIPAndAttachLicenseTermsAndDistributeRoyaltyTokensRequest = { nftContract: Address; tokenId: bigint | string | number; - licenseTermsData: LicenseTermsData[]; + /** The data of the license and its configuration to be attached to the new group IP. */ + licenseTermsData: LicenseTermsData[]; + /** + * The deadline for the signature in seconds. + * @default 1000 + */ deadline?: string | number | bigint; + /** Authors of the IP and their shares of the royalty tokens. */ royaltyShares: RoyaltyShare[]; txOptions?: Omit; } & IPMetadataInfo; @@ -321,7 +360,12 @@ export type DistributeRoyaltyTokens = { txOptions?: Omit; }; export type RoyaltyShare = { + /** The address of the recipient. */ recipient: Address; + /** + * The percentage of the total royalty share. For example, a value of 10 represents 10% of max royalty shares, which is 10,000,000. + * @example 10 + */ percentage: number; }; export type IpIdAndTokenId = T extends undefined @@ -331,9 +375,16 @@ export type IpIdAndTokenId = T extends undefined export type RegisterDerivativeAndAttachLicenseTermsAndDistributeRoyaltyTokensRequest = { nftContract: Address; tokenId: bigint | string | number; + /** + * The deadline for the signature in seconds. + * @default 1000 + */ deadline?: string | number | bigint; + /** The derivative data to be used for register derivative.*/ derivData: DerivativeData; + /** Authors of the IP and their shares of the royalty tokens. */ royaltyShares: RoyaltyShare[]; + /** The desired metadata for the newly minted NFT and newly registered IP. */ ipMetadata?: IpMetadataForWorkflow; txOptions?: Omit; } & WithWipOptions; @@ -345,15 +396,16 @@ export type RegisterDerivativeAndAttachLicenseTermsAndDistributeRoyaltyTokensRes tokenId: bigint; ipRoyaltyVault: Address; }; - export type MintAndRegisterIpAndAttachPILTermsAndDistributeRoyaltyTokensRequest = { + /** The address of the SPG NFT contract. */ spgNftContract: Address; + /** Set to true to allow minting an NFT with a duplicate metadata hash. */ allowDuplicates: boolean; - licenseTermsData: { - terms: RegisterPILTermsRequest; - licensingConfig: LicensingConfig; - }[]; + /** The data of the license and its configuration to be attached to the new group IP. */ + licenseTermsData: LicenseTermsData[]; + /** Authors of the IP and their shares of the royalty tokens */ royaltyShares: RoyaltyShare[]; + /** The address to receive the minted NFT. If not provided, the function will use the user's own wallet address. */ recipient?: Address; txOptions?: Omit; } & IPMetadataInfo & @@ -366,11 +418,16 @@ export type MintAndRegisterIpAndAttachPILTermsAndDistributeRoyaltyTokensResponse ipRoyaltyVault?: Address; tokenId?: bigint; }; + export type MintAndRegisterIpAndMakeDerivativeAndDistributeRoyaltyTokensRequest = { spgNftContract: Address; + /** The derivative data to be used for register derivative. */ derivData: DerivativeData; + /** Authors of the IP and their shares of the royalty tokens. */ royaltyShares: RoyaltyShare[]; + /** Set to true to allow minting an NFT with a duplicate metadata hash. */ allowDuplicates: boolean; + /** The address to receive the minted NFT. If not provided, the function will use the user's own wallet address. */ recipient?: Address; txOptions?: Omit; } & IPMetadataInfo & diff --git a/packages/core-sdk/src/types/resources/license.ts b/packages/core-sdk/src/types/resources/license.ts index f2a815906..4195d4d80 100644 --- a/packages/core-sdk/src/types/resources/license.ts +++ b/packages/core-sdk/src/types/resources/license.ts @@ -139,16 +139,15 @@ export type PredictMintingLicenseFeeRequest = { txOptions?: TxOptions; }; -export type InnerLicensingConfig = { - mintingFee: bigint; - commercialRevShare: number; - expectMinimumGroupRewardShare: number; -} & LicensingConfig; export type SetLicensingConfigRequest = { + /** The address of the IP for which the configuration is being set. */ ipId: Address; + /** The ID of the license terms within the license template. */ licenseTermsId: string | number | bigint; - licensingConfig: LicensingConfig; + /** The address of the license template used. */ licenseTemplate: Address; + /** The licensing configuration for the license. */ + licensingConfig: LicensingConfig; txOptions?: TxOptions; }; diff --git a/packages/core-sdk/src/utils/getIpMetadataForWorkflow.ts b/packages/core-sdk/src/utils/getIpMetadataForWorkflow.ts index 964672feb..d27b739ad 100644 --- a/packages/core-sdk/src/utils/getIpMetadataForWorkflow.ts +++ b/packages/core-sdk/src/utils/getIpMetadataForWorkflow.ts @@ -1,9 +1,13 @@ import { Hex, zeroHash } from "viem"; export type IpMetadataForWorkflow = { + /** The URI of the metadata for the IP. */ ipMetadataURI: string; + /** The hash of the metadata for the IP. */ ipMetadataHash: Hex; + /** The URI of the metadata for the NFT. */ nftMetadataURI: string; + /** The hash of the metadata for the IP NFT. */ nftMetadataHash: Hex; }; diff --git a/packages/core-sdk/src/utils/validateLicenseConfig.ts b/packages/core-sdk/src/utils/validateLicenseConfig.ts index f3ccf2d24..62f68eba3 100644 --- a/packages/core-sdk/src/utils/validateLicenseConfig.ts +++ b/packages/core-sdk/src/utils/validateLicenseConfig.ts @@ -1,19 +1,33 @@ -import { LicensingConfig } from "../types/common"; -import { InnerLicensingConfig } from "../types/resources/license"; +import { zeroAddress } from "viem"; + +import { LicensingConfig, ValidatedLicensingConfig } from "../types/common"; import { getRevenueShare } from "./licenseTermsHelper"; -import { getAddress } from "./utils"; +import { validateAddress } from "./utils"; -export const validateLicenseConfig = (licensingConfig: LicensingConfig): InnerLicensingConfig => { +export const validateLicenseConfig = ( + licensingConfig?: LicensingConfig, +): ValidatedLicensingConfig => { + if (!licensingConfig) { + return { + isSet: false, + mintingFee: 0n, + licensingHook: zeroAddress, + hookData: zeroAddress, + commercialRevShare: 0, + disabled: false, + expectMinimumGroupRewardShare: 0, + expectGroupRewardPool: zeroAddress, + }; + } const licenseConfig = { - ...licensingConfig, expectMinimumGroupRewardShare: Number(licensingConfig.expectMinimumGroupRewardShare), commercialRevShare: getRevenueShare(licensingConfig.commercialRevShare), mintingFee: BigInt(licensingConfig.mintingFee), - expectGroupRewardPool: getAddress( - licensingConfig.expectGroupRewardPool, - "licensingConfig.expectGroupRewardPool", - ), - licensingHook: getAddress(licensingConfig.licensingHook, "licensingConfig.licensingHook"), + expectGroupRewardPool: validateAddress(licensingConfig.expectGroupRewardPool), + licensingHook: validateAddress(licensingConfig.licensingHook), + hookData: licensingConfig.hookData, + isSet: licensingConfig.isSet, + disabled: licensingConfig.disabled, } as const; if (isNaN(licenseConfig.expectMinimumGroupRewardShare)) { throw new Error(`The expectMinimumGroupRewardShare must be a valid number.`); diff --git a/packages/core-sdk/test/integration/ipAsset.test.ts b/packages/core-sdk/test/integration/ipAsset.test.ts index 1b6e276f1..64d98185e 100644 --- a/packages/core-sdk/test/integration/ipAsset.test.ts +++ b/packages/core-sdk/test/integration/ipAsset.test.ts @@ -934,7 +934,7 @@ describe("IP Asset Functions", () => { expect(result.tokenId).to.be.a("bigint"); }); - it("should mint and register IP and attach PIL terms and distribute royalty tokens", async () => { + it("should mint and register IP and attach PIL terms and distribute royalty tokens without licensing config", async () => { const result = await client.ipAsset.mintAndRegisterIpAndAttachPilTermsAndDistributeRoyaltyTokens({ spgNftContract: nftContract, @@ -960,16 +960,6 @@ describe("IP Asset Functions", () => { currency: wrappedIpAddress[aeneid], uri: "test case", }, - licensingConfig: { - isSet: true, - mintingFee: 10000n, - licensingHook: zeroAddress, - hookData: zeroAddress, - commercialRevShare: 0, - disabled: false, - expectMinimumGroupRewardShare: 0, - expectGroupRewardPool: zeroAddress, - }, }, ], royaltyShares: [ diff --git a/packages/core-sdk/test/unit/utils/mockData.ts b/packages/core-sdk/test/unit/mockData.ts similarity index 84% rename from packages/core-sdk/test/unit/utils/mockData.ts rename to packages/core-sdk/test/unit/mockData.ts index d1d2cba39..18b73c41a 100644 --- a/packages/core-sdk/test/unit/utils/mockData.ts +++ b/packages/core-sdk/test/unit/mockData.ts @@ -1,2 +1,3 @@ export const txHash = "0x063834efe214f4199b1ad7181ce8c5ced3e15d271c8e866da7c89e86ee629cfb"; export const ipId = "0x73fcb515cee99e4991465ef586cfe2b072ebb512"; +export const aeneid = 13_15; diff --git a/packages/core-sdk/test/unit/resources/dispute.test.ts b/packages/core-sdk/test/unit/resources/dispute.test.ts index 596a4a85e..1c3477719 100644 --- a/packages/core-sdk/test/unit/resources/dispute.test.ts +++ b/packages/core-sdk/test/unit/resources/dispute.test.ts @@ -1,6 +1,6 @@ import * as sinon from "sinon"; import { createMock } from "../testUtils"; -import { ipId, txHash } from "../utils/mockData"; +import { ipId, txHash } from "../mockData"; import chai, { expect } from "chai"; import chaiAsPromised from "chai-as-promised"; import { PublicClient, WalletClient } from "viem"; diff --git a/packages/core-sdk/test/unit/resources/ipAsset.test.ts b/packages/core-sdk/test/unit/resources/ipAsset.test.ts index ba31b367a..e55100076 100644 --- a/packages/core-sdk/test/unit/resources/ipAsset.test.ts +++ b/packages/core-sdk/test/unit/resources/ipAsset.test.ts @@ -710,6 +710,34 @@ describe("Test IpAssetClient", () => { expect(res.encodedTxData!.data).to.be.a("string").and.not.empty; }); + + it("should call with default values of maxMintingFee, maxRts, maxRevenueShare when registerDerivative given maxMintingFee, maxRts, maxRevenueShare is not provided", async () => { + sinon + .stub(ipAssetClient.ipAssetRegistryClient, "isRegistered") + .onCall(0) + .resolves(true) + .onCall(1) + .resolves(true); + sinon + .stub(ipAssetClient.licenseRegistryReadOnlyClient, "hasIpAttachedLicenseTerms") + .resolves(true); + const registerDerivativeStub = sinon + .stub(ipAssetClient.licensingModuleClient, "registerDerivative") + .resolves("0x129f7dd802200f096221dd89d5b086e4bd3ad6eafb378a0c75e3b04fc375f997"); + sinon.stub(ipAssetClient.licenseRegistryReadOnlyClient, "getRoyaltyPercent").resolves({ + royaltyPercent: 100, + }); + + await ipAssetClient.registerDerivative({ + childIpId: "0x1daAE3197Bc469Cb97B917aa460a12dD95c6627c", + parentIpIds: ["0xd142822Dc1674154EaF4DDF38bbF7EF8f0D8ECe4"], + licenseTermsIds: ["1"], + licenseTemplate: "0x1daAE3197Bc469Cb97B917aa460a12dD95c6627c", + }); + expect(registerDerivativeStub.args[0][0].maxMintingFee).equal(0n); + expect(registerDerivativeStub.args[0][0].maxRts).equal(MAX_ROYALTY_TOKEN); + expect(registerDerivativeStub.args[0][0].maxRevenueShare).equal(MAX_ROYALTY_TOKEN); + }); }); describe("Test ipAssetClient.registerDerivativeWithLicenseTokens", async () => { @@ -924,7 +952,6 @@ describe("Test IpAssetClient", () => { ], allowDuplicates: false, recipient: "0x73fcb515cee99e4991465ef586cfe2b072ebb512", - royaltyPolicyAddress: zeroAddress, ipMetadata: { ipMetadataURI: "", ipMetadataHash: toHex(0, { size: 32 }), @@ -1709,6 +1736,34 @@ describe("Test IpAssetClient", () => { }); expect(result.txHash).to.equal(txHash); }); + + it("should call with default values of licensingConfig when registerPilTermsAndAttach given licensingConfig is not provided", async () => { + const registerPilTermsAndAttachStub = sinon + .stub(ipAssetClient.licenseAttachmentWorkflowsClient, "registerPilTermsAndAttach") + .resolves(txHash); + sinon.stub(ipAssetClient.ipAssetRegistryClient, "isRegistered").resolves(true); + + await ipAssetClient.registerPilTermsAndAttach({ + ipId: "0x1daAE3197Bc469Cb97B917aa460a12dD95c6627c", + licenseTermsData: [ + { + terms: licenseTerms, + }, + ], + }); + expect( + registerPilTermsAndAttachStub.args[0][0].licenseTermsData[0].licensingConfig, + ).to.deep.equal({ + isSet: false, + mintingFee: 0n, + licensingHook: zeroAddress, + hookData: zeroAddress, + commercialRevShare: 0, + disabled: false, + expectMinimumGroupRewardShare: 0, + expectGroupRewardPool: zeroAddress, + }); + }); }); describe("Test ipAssetClient.mintAndRegisterIpAndMakeDerivativeWithLicenseTokens", async () => { diff --git a/packages/core-sdk/test/unit/resources/license.test.ts b/packages/core-sdk/test/unit/resources/license.test.ts index c0d4aa07e..63d3f3ae8 100644 --- a/packages/core-sdk/test/unit/resources/license.test.ts +++ b/packages/core-sdk/test/unit/resources/license.test.ts @@ -1098,7 +1098,7 @@ describe("Test LicenseClient", () => { }); } catch (error) { expect((error as Error).message).equal( - "Failed to set licensing config: The minting fee must be greater than 0.", + "Failed to set licensing config: The mintingFee must be greater than 0.", ); } }); diff --git a/packages/core-sdk/test/unit/feeUtils.test.ts b/packages/core-sdk/test/unit/utils/feeUtils.test.ts similarity index 99% rename from packages/core-sdk/test/unit/feeUtils.test.ts rename to packages/core-sdk/test/unit/utils/feeUtils.test.ts index 9968b7a4d..732717e79 100644 --- a/packages/core-sdk/test/unit/feeUtils.test.ts +++ b/packages/core-sdk/test/unit/utils/feeUtils.test.ts @@ -10,9 +10,9 @@ import { erc20Address, } from "../../../src/abi/generated"; import { createMock, generateRandomAddress, generateRandomHash } from "../testUtils"; -import { txHash } from "./mockData"; +import { aeneid, txHash } from "../mockData"; import { contractCallWithFees } from "../../../src/utils/feeUtils"; -import { TEST_WALLET_ADDRESS, aeneid } from "../../integration/utils/util"; +import { TEST_WALLET_ADDRESS } from "../../integration/utils/util"; import { WIP_TOKEN_ADDRESS } from "../../../src/constants/common"; import { ContractCallWithFees } from "../../../src/types/utils/wip"; import { ERC20Client, WIPTokenClient } from "../../../src/utils/token"; diff --git a/packages/core-sdk/test/unit/utils/validateLicenseConfig.test.ts b/packages/core-sdk/test/unit/utils/validateLicenseConfig.test.ts index 9f265428f..cc515b587 100644 --- a/packages/core-sdk/test/unit/utils/validateLicenseConfig.test.ts +++ b/packages/core-sdk/test/unit/utils/validateLicenseConfig.test.ts @@ -77,4 +77,18 @@ describe("validateLicenseConfig", () => { "The mintingFee must be greater than 0.", ); }); + + it("should throw default value when licensingConfig is not provided", () => { + const result = validateLicenseConfig(); + expect(result).to.deep.equal({ + isSet: false, + mintingFee: 0n, + licensingHook: zeroAddress, + hookData: zeroAddress, + commercialRevShare: 0, + disabled: false, + expectMinimumGroupRewardShare: 0, + expectGroupRewardPool: zeroAddress, + }); + }); });