v1.4.1

TypeScript SDK v1.4.1 Release Notes

This patch release includes fixes for issues affecting royalty share calculations and precision loss.

Fixes

1. Resolved the precision loss issue by correcting the handling of the following fields (#642):
   • RevShareType
   • royaltyShares
   • expectMinimumGroupRewardShare
2. Corrected royalty share scaling in the mintAndRegisterIpAndMakeDerivativeAndDistributeRoyaltyTokens method when multicall is enabled (#642).

Migration from v1.3.x

If you are upgrading from v1.3.x, please refer to the migration guide.

v1.4.0

TypeScript SDK v1.4.0 Release Notes

This is the stable release of the Story Protocol SDK v1.4.0.

This version introduces a comprehensive update, including:

• A major redesign of IP Asset registration and derivative workflows, consolidating previously fragmented methods into three general-purpose entry points
• New IP Asset module methods, such as batchMintAndRegisterIp for batch NFT minting and automatic IP registration
• Relocation of licensing logic to the license module
• Introduction of the PILFlavor class for flexible license term generation
• Stricter type safety with numeric fields and new type aliases (LicenseTermsIdInput, DeadlineInput, RevShareInput, FeeInput)
• Default values for key parameters to simplify method calls (maxMintingFee, maxRts, maxRevenueShare, maxAllowedRewardShare)
• Enhanced developer ergonomics and testing coverage, including commercialRevShare validations and IP signature verification

These improvements streamline IP asset management, strengthen reliability, and improve the overall developer experience.

Migration Guide

Breaking Changes

Changes from rc.2 to stable:

• registerPilTermsAndAttach has been moved to the license module
• Numeric fields that previously accepted string now only accept number or bigint
• registerDerivative and registerDerivativeWithLicenseTokens now return LinkDerivativeResponse (aligned with linkDerivative)

Migrating from v1.3.x

• Please refer to the migration guide.

Key Changes

IP Asset Client Methods

IP Asset Registration Redesign

Three general-purpose methods now handle IP asset creation and derivative management, consolidating multiple older workflows while maintaining backward compatibility. All methods support automatic token handling for minting fees, license terms, royalty tokens, and derivative data.

1. registerIpAsset — Create a new IP asset (minted or mint-on-demand), including licenseTermsData and royaltyShares. See #628, #630 for details.

Replaces workflows previously handled by:

• registerIPAndAttachLicenseTermsAndDistributeRoyaltyTokens
• registerIpAndAttachPilTerms
• register
• mintAndRegisterIpAndAttachPilTermsAndDistributeRoyaltyTokens
• mintAndRegisterIpAssetWithPilTerms
• mintAndRegisterIp

Usage Example:

await client.ipAsset.registerIpAsset({
          nft: { type: "minted", nftContract, tokenId},
          licenseTermsData,
          royaltyShares: [
            {
              recipient: TEST_WALLET_ADDRESS,
              percentage: 100,
            },
          ],
          deadline: 1000n,
        });

2. registerDerivativeIpAsset — Create a derivative IP asset with optional derivData, royaltyShares, and licenseTokenIds. See #629 for details.

Replaces workflows previously handled by:

• registerDerivativeIpAndAttachLicenseTermsAndDistributeRoyaltyTokens
• registerDerivativeIp
• registerIpAndMakeDerivativeWithLicenseTokens
• mintAndRegisterIpAndMakeDerivativeAndDistributeRoyaltyTokens
• mintAndRegisterIpAndMakeDerivative
• mintAndRegisterIpAndMakeDerivativeWithLicenseTokens

Usage Example:

await client.ipAsset.registerDerivativeIpAsset({
          nft: { type: "mint", spgNftContract },
          derivData,
          royaltyShares: [
            {
              recipient: TEST_WALLET_ADDRESS,
              percentage: 100,
            },
          ],
        });

3. linkDerivative — Link an existing IP asset as a derivative using the parent IP's license terms or license tokens. See #633 for details.

Replaces workflows previously handled by:

• registerDerivative
• registerDerivativeWithLicenseTokens

Usage Example:

await client.ipAsset.linkDerivative({
        childIpId: childIpId,
        licenseTokenIds: [mintLicenseTokensResult.licenseTokenIds![0]],
        maxRts: 5 * 10 ** 6,
  })

batchMintAndRegisterIp

• Enables batch minting of NFTs from SPGNFT collections and automatically registers them as IP assets. See #615 for details.

License Module Refactor

Moved registerPilTermsAndAttach into the license module. See #636 for details.

Export PIL Flavor class

Introduced the PILFlavor class to generate different license terms, such as nonCommercialSocialRemixing, commercialUse, commercialRemix, and creativeCommonsAttribution. See #605 for details.

Type System Improvements

• Stricter numeric input types — Only number or bigint are allowed; strings are no longer accepted
• Added new type aliases: LicenseTermsIdInput, DeadlineInput, RevShareInput, FeeInput. See #635 for details.

Add default values

Added default values for key parameters to simplify method calls. See #638 for details.

The following fields are now optional and have the indicated default values:

• maxMintingFee: 0
• maxRts: 100_000_000
• maxRevenueShare: 100_000_000
• maxAllowedRewardShare: 100_000_000

Other Changes

• Enhanced test coverage and validation for commercialRevShare. See #621 for details.
• Added IP account signature validation test cases. See #623 for details.
• Fixed scaling of expectMinimumGroupRewardShare. See #612 for details.
• Added git-leaks pre-commit hook to detect secrets. See #610 for details.
• Added GitHub CodeQL security scanning badge to README. See #549 for details.

This version provides a robust, safer, and more ergonomic SDK for IP asset management, licensing, and derivative workflows, while consolidating multiple previous methods into intuitive, general-purpose APIs.

v1.4.0-rc.2

TypeScript SDK v1.4.0-rc.2 Release Notes

Release Candidate - This is a release candidate for the upcoming v1.4.0 major version of the Story Protocol TypeScript SDK.

This release focuses on test enhancements and validation improvements, providing comprehensive test coverage for commercialRevShare operations and IP account signature validation.

Migration Guide

No breaking changes in this release. This is a patch release that maintains full backward compatibility with rc.1.

Key Changes

Enhanced commercialRevShare Testing and Validation

Added comprehensive test coverage and improved validation for commercialRevShare operations (#621).

Enhanced IP Account Signature Validation Tests

Added test cases for IP account signature validation functionality, serving as a reference implementation for signature generation (#623).

v1.4.0-rc.1

TypeScript SDK v1.4.0-rc.1 Release Notes

Release Candidate - This is a release candidate for the upcoming v1.4.0 major version of the Story Protocol TypeScript SDK.

This release introduces a refactored PILFlavor class for license term management, a new batchMintAndRegisterIp method, improvements to licensing config handling, and security enhancements.

Migration Guide

Breaking Changes: Several license methods are deprecated and will be removed. See Key Changes below for details.

Migrating from v1.2.x

Please refer to the 1.3.0-rc.1 release notes first.

Key Changes

Export PIL Flavor class

Introduced the PILFlavor class to generate different license terms,
such as nonCommercialSocialRemixing, commercialUse, commercialRemix, and creativeCommonsAttribution. See #605 for details.

The following methods are deprecated and will be removed. Developers should migrate to the PILFlavor class for license creation going forward.

• LicenseClient.registerNonComSocialRemixingPIL
• LicenseClient.registerCommercialUsePIL
• LicenseClient.registerCommercialRemixPIL
• LicenseClient.registerCreativeCommonsAttributionPIL

Old Syntax:

await client.license.registerCommercialUsePIL({
  defaultMintingFee: "1",
  currency: WIP_TOKEN_ADDRESS,
});

await client.license.registerCreativeCommonsAttributionPIL({
  currency: WIP_TOKEN_ADDRESS,
  royaltyPolicyAddress: royaltyPolicyLapAddress[aeneid],
});

New Syntax:

await client.license.registerPILTerms(
  PILFlavor.commercialUse({
    defaultMintingFee: 1,
    currency: WIP_TOKEN_ADDRESS,
  })
);
await client.license.registerPILTerms(
  PILFlavor.creativeCommonsAttribution({
    currency: WIP_TOKEN_ADDRESS,
    royaltyPolicy: royaltyPolicyLapAddress[aeneid],
  })
);

In the SDK, there is the LicenseTermsDataInput type, which has a terms property. Previously, you needed to pass all license term properties manually.

Now you can use PILFlavor to generate license terms, while still being able to customize them by overriding specific properties.

await client.ipAsset.mintAndRegisterIpAssetWithPilTerms({
  spgNftContract: spgNftContractWithPrivateMinting,
  allowDuplicates: false,
  licenseTermsData: [
    {
      terms: PILFlavor.commercialUse({
        defaultMintingFee: 8n,
        currency: WIP_TOKEN_ADDRESS,
        override: { commercialRevShare: 10 },
      }),
      licensingConfig: licensingConfig,
    },
  ],
});

New IPAsset Method: batchMintAndRegisterIp

Enables batch minting of NFTs from SPGNFT collections and automatically registers them as IP assets. See #615 for details.

Key features:

• Automated fee handling: Wraps IP tokens into WIP tokens if balances are insufficient, and manages allowance checks/approvals for all spenders.
• Configurable multicall & token handling: Controlled via the wipOptions parameter.
• Optimized transaction flow: Groups multiple requests and selects the most efficient multicall strategy:
  • Uses SPG's multicall for private minting contracts.
  • Falls back to standard multicall for other cases.

Usage Example:

await client.ipAsset.batchMintAndRegisterIp({
  requests: [{ spgNftContract: spgNftContract }],
  wipOptions: {
    useMulticallWhenPossible: false, // default true
    enableAutoWrapIp: false, // default true
    enableAutoApprove: false, // default true
  },
});

Fixed scale expectMinimumGroupRewardShare value

Fixed scaling of the expectMinimumGroupRewardShare value to align with contract expectations. See #612 for details.

Previously, if you passed 10, the SDK would send 10 directly to the contract. Now it correctly sends 10 * 10**6.

If you want to update a previously set expectMinimumGroupRewardShare , you can call client.license.setLicensingConfig.

Usage Example:

await client.license.setLicensingConfig({
  ipId: ipId,
  licenseTermsId: licenseId,
  licensingConfig: {
    ...licensingConfig,
    expectMinimumGroupRewardShare: 90,
  },
});

Other Changes

• Added a pre-commit configuration with git-leaks to automatically detect and block commits containing secrets, API keys, passwords, or other sensitive information. See #610 for details.
• Added GitHub CodeQL security scanning badge to README for enhanced security visibility. See #549 for details.

New Contributors

• @Olexandr88 – #549

v1.3.3

TypeScript SDK v1.3.3 Release Notes

Version 1.3.3 introduces license token limit controls, adds new license management methods, and includes developer experience improvements. This release primarily focuses on enhancing license management capabilities while maintaining backward compatibility with minimal breaking changes.

Features & Enhancements

• Adds comprehensive support for license token limits. The SDK now supports setting total license token limits through the maxLicenseTokens parameter in LicenseTermsDataInput, which automatically configures the TotalLicenseTokenLimitHook. Additionally, introduces the new setMaxLicenseTokens method in the License module for setting limits on existing license terms(#572). The following methods support license token limiting:
  • mintAndRegisterIpAssetWithPilTerms
  • registerIpAndAttachPilTerms
  • registerPilTermsAndAttach
  • registerIPAndAttachLicenseTermsAndDistributeRoyaltyTokens
  • mintAndRegisterIpAndAttachPilTermsAndDistributeRoyaltyTokens
  • batchRegisterIpAssetsWithOptimizedWorkflows
  • batchMintAndRegisterIpAssetWithPilTerms
  • setMaxLicenseTokens (new method)
• Improves code quality by enabling ESLint between unit and integration tests and resolving all lint issues across the codebase(#563).

Breaking Changes

• In the IP Asset module, the response field ipIdAndTokenId in batchRegisterIpAssetsWithOptimizedWorkflows has been renamed to ipAssetsWithLicenseTerms for better semantic clarity(#572).

New Features Usage Examples

Setting License Token Limits:

// When registering IP with PIL terms
const result = await client.ipAsset.mintAndRegisterIpAssetWithPilTerms({
  spgNftContract: nftContractAddress,
  licenseTermsData: [
      ...
      maxLicenseTokens: 100, // Limit this license to 100 tokens
    },
  ],
});

// Setting limits for existing license terms
const setLimitResult = await client.license.setMaxLicenseTokens({
  ipId: ipIdAddress,
  licenseTermsId: licenseTermsId,
  maxLicenseTokens: 100,
});

Migration Guide

Migrating from v1.3.2 to v1.3.3

• Update references to the response field in batchRegisterIpAssetsWithOptimizedWorkflows:

Old syntax:

const result = await client.ipAsset.batchRegisterIpAssetsWithOptimizedWorkflows({
  requests: requests,
});
// Accessing: result.ipIdAndTokenId

New syntax:

const result = await client.ipAsset.batchRegisterIpAssetsWithOptimizedWorkflows({
  requests: requests,
});
// Accessing: result.ipAssetsWithLicenseTerms

Migrating from v1.2.x

• Please refer to the 1.3.0-rc.1 release notes.

v1.3.2

SDK v1.3.2 Release Notes

Version 1.3.2 introduces support for new license types, standardizes dispute handling, and simplifies transaction flows with auto-await behavior. It also includes key architectural improvements, such as unified option handling and stricter chainId typing. Some changes require updates to existing implementations. See the Migration Guide below for details.

Features & Enhancements

• Adds the registerCreativeCommonsAttributionPIL function to the License module. PR(#515)
• Refactored the License module to support the registration of multiple license types by extracting shared logic into a common registerPILTermsHelper method. PR(#515)
• The Royalty module now returns claimedTokens when claimAllRevenue is called from a non-owner account PR(#526)
• All transactions are now automatically awaited; waitForTransaction is no longer supported or required. This simplifies transaction handling, avoids issues with multi-TX flows, and improves the default developer experience. PR(#548)

Breaking Changes

• Updates the RaiseDisputeRequest enum in the Dispute module so it can be used instead of a string for the targetTag property. PR(#521)
• In the Royalty module, royaltyVaultIpId was renamed to ipId. PR(#523)
• Improves chainId handling by changing its type from string to number and updating how getPermissionSignature and getSignature retrieve it. PR(#527)
• The txHash field in all modules has changed from string to Hash. PR(#545)
• Consolidates all option parameters (e.g., wipOptions, erc20Options) into a single optional options object. All public client methods that accept options now use this unified property. PR(#547)

Migration Guide

Migrating from v1.2.x

• Please refer to the 1.3.0-rc.1 release notes.

Migration from v1.3.x

• Change the chainId parameter type to ChainIds in the getPermissionSignature and getSignature methods, replacing the previous string | number | bigint type.
• Update the ChainIds definition from string literals ("1315" | "1514") to numeric literals (1315 | 1514) when initializing the Story client.
• In the Royalty module, when using the ClaimableRevenueRequest the royaltyVaultIpId field should now be ipId.

Old Syntax:

const x = await client.royalty.claimableRevenue({
        royaltyVaultIpId: PARENT_IP_ID,
        claimer: PARENT_IP_ID,
        token: WIP_TOKEN_ADDRESS,
    })

New Syntax:

const x = await client.royalty.claimableRevenue({
        ipId: PARENT_IP_ID,
        claimer: PARENT_IP_ID,
        token: WIP_TOKEN_ADDRESS,
    })

• Developers must now move wipOptions and erc20Options into the unified options object when using client methods. Example:

Old syntax:

await client.ipAsset.batchRegisterIpAssetsWithOptimizedWorkflows({
        requests: requests,
        wipOptions: {
          useMulticallWhenPossible: false,
        },
      });

New syntax:

 await client.ipAsset.batchRegisterIpAssetsWithOptimizedWorkflows({
        requests: requests,
        options: {
          wipOptions: {
            useMulticallWhenPossible: false,
          },
        },
      });

• In all modules, the txHash field must be changed from a string to a Hex.

v1.3.1

SDK Release Notes – v1.3.1

Version 1.3.1 introduces optimized workflows for registering IP Assets. This update also includes new methods for retrieving licensing configurations associated with a specific IP and adding one or more IPs to an existing IP group.

Features & Enhancements

• Adds the batchRegisterIpAssetsWithOptimizedWorkflows function to the IPAsset module. PR(#505)
• Adds the getLicensingConfig function to the License module. PR(#500)
• Adds the addIpsToGroup function to the Group module. PR(#504)
• Adds the setTokenURI function to the NFTClient module. It allows token owners to modify the metadata URI of their tokens while maintaining proper access control. It also gets the token URI for a specific token ID. PR(#507)
• Adds a check to verify if public minting is enabled. Prevents multicall usage when SPG NFT public minting is turned off to ensure proper role-based access control. This protection maintains minter role verification integrity since multicall would make the contract (not the original caller) appear as the transaction sender, breaking the necessary msg.sender verification. PR(#508)
• Adds the removeIpsFromGroup function to the Group module. PR(#511)
• Adds the claimReward function to the Group module. PR(#512)
• Adds the getClaimableReward function to the Group module. PR(#513)
• Adds the collectingRoyalties function to the Group module. PR(#514)

Bug Fixes

• Fix the issue in the mintAndRegisterIp function that arises when using multicall. PR(#505)

Migration Guide

Migrating from v1.2.x

• Please refer to the 1.3.0-rc.1 release notes.

v1.3.1-beta

SDK Release Notes – v1.3.1-beta

Version 1.3.1-Beta introduces optimized workflows for registering IP Assets. This update also includes new methods for retrieving licensing configurations associated with a specific IP and adding one or more IPs to an existing IP group.

Features & Enhancements

• Adds the batchRegisterIpAssetsWithOptimizedWorkflows function to the IPAsset module. #505
• Adds the getLicensingConfig function to the License module. #500
• Adds the addIpsToGroup function to the Group module. #504

Bug Fixes

• Fix the issue in the mintAndRegisterIp function that arises when using multicall. #505

Migration Guide

Migrating from v1.2.x

• Please refer to the 1.3.0-rc.1 release notes.

v1.3.0

SDK Release Notes – v1.3.0

Version 1.3.0 of the Story Protocol SDK has been released, featuring significant enhancements, key bug fixes, and improvements to developer experience and documentation.

Features & Enhancements

• Enhance mintLicenseTokens by enforcing license term attachment rules with exceptions for default terms and IP owners. #485
• Increase integration test coverage for Dispute, License, and Royalty modules to validate batchClaimAllRevenue behavior with additional test cases. #493
• Add minimum bond check in the Dispute module and make the bond parameter optional, defaulting to the required minimum value. #494
• Data field in the Cancel and Resolve Dispute methods is now optional. #490
• getDerivedStoryClient method from the BIP32 utility module, now returns the address in addition to the client. #493

Bug Fixes

• Fix tagIfRelatedIpInfringed to correctly handle multiple data entries when useMulticallWhenPossible is false, preventing nonce collisions due to concurrent execution. The issue arose because the SDK only tested single-entry cases in this configuration.#484
• Update integration tests to comply with the Dispute Module’s new minimum bond requirement of 0.1 IP, as zero-value bonds are no longer supported. #487 #494
• Fix incorrect spender assignment in registerDerivative, changing from royaltyTokenDistributionWorkflows to royaltyModule. #488
• Verify that approve transaction in the Dispute module is properly awaited before proceeding, preventing race conditions in subsequent function executions. Integration tests were also properly updated. #482
• It fixes a bugh when calling predictMintingLicenseFee to estimate license fees with default license terms. #485

Migration Guide

Migrating from v1.2.x

• Please refer to the 1.3.0-rc.1 release notes

Documentation

• Improved code comments across the Client and Dispute modules, along with enhancements to config file documentation for clarity and maintainability. #491
• Updated README by moving setup and testing instructions to the CONTRIBUTING.md file, and streamline content based on feedback for improved clarity. #492

New Contributors

• @holazz – #415
• @Dimitrolito – #369

@story-protocol/core-sdk@1.3.0-rc.3

Migration Guide

Migrating from 1.3.0-rc.2 to 1.3.0-rc.3

No changes.

Migrating from v1.2.x

Please refer to the 1.3.0-rc.1 release notes.

Key Changes

New Group Client Method: collectAndDistributeGroupRoyalties

This method collects royalties for the entire group and distribute the rewards to each member IP's royalty vault. See POC function.

Usage Example

const result = await storyClient.groupClient.collectAndDistributeGroupRoyalties({
  groupIpId: groupIpId,
  currencyTokens: [WIP_TOKEN_ADDRESS],
  memberIpIds: ipIds,
  txOptions: { waitForTransaction: true },
});

New Royalty Client Method: transferToVault

Transfers to vault an amount of revenue tokens claimable via a royalty policy.

Usage Example

const result = await storyClient.royalty.transferToVault({
  royaltyPolicy: NativeRoyaltyPolicy.LAP,
  ipId,
  ancestorIpId,
  token: WIP_TOKEN_ADDRESS,
  txOptions: { waitForTransaction: true },
});

Bug Fixes

• Fixed an issue with disputeAssertion in dispute client where the approval call is not properly handled. #482.