v0.3.15

Story Protocol Python SDK v0.3.15

Stable Release - This is the stable release of Story Protocol Python SDK v0.3.15.

PyPI: https://pypi.org/project/story-protocol-python-sdk/0.3.15/

Overview

This release builds upon the improvements from rc1 and rc2, introducing several powerful new methods across IPAsset, Group, and License modules, enabling smoother workflows for minting, registering, licensing, and reward distribution.

Key highlights include:

• IPAsset Enhancements: streamlined mint–register–license operations and simplified PIL attachment.
• Group Module Updates: new reward claim, royalty collection, and reward query functions.
• Licensing Improvements: enhance licensing configuration management and stricter type safety.

These changes expand SDK functionality while also introducing stricter validation and breaking changes that developers must adapt to.

Note: For detailed information about features introduced in rc1 and rc2, please refer to the v0.3.15-rc.1 and v0.3.15-rc.2 release notes.

What's New

New Methods Overview

IPAsset Module:

• mint_and_register_ip_and_make_derivative_with_license_tokens - Mint NFT and register as derivative IP with license tokens
• register_pil_terms_and_attach - Register PIL terms and attach to IP ID

Group Module:

• collect_royalties - Collect royalties into pool for group members
• claim_rewards - Claim rewards for entire group
• get_claimable_reward - Query claimable rewards for group IPs

License Module:

• get_licensing_config - Retrieve licensing configuration for IP license terms

Detailed Documentation

IPAsset: mint_and_register_ip_and_make_derivative_with_license_tokens

Mint an NFT from a collection and register it as a derivative IP with license tokens (#131).

Code Example:

response = story_client.IPAsset.mint_and_register_ip_and_make_derivative_with_license_tokens(
            spg_nft_contract=nft_collection,
            license_token_ids=[
                mint_and_approve_license_token[0],
                second_license_token_ids["license_token_ids"][0],
            ],
            max_rts=100000000,
        )

IPAsset: register_pil_terms_and_attach

Register Programmable IP License (PIL) terms, attach them to an IP ID, and return RegisterPILTermsAndAttachResponse containing tx_hash and license_terms_ids (#132).

Code Example:

story_client.IPAsset.register_pil_terms_and_attach(
            ip_id=parent_ip_and_license_terms["parent_ip_id"],
            license_terms_data=license_terms_data,
            deadline=10000,
        )

Group: collect_royalties

Collects royalties into the pool, making them claimable by group member IPs (#135).

Code Example:

story_client.Group.collect_royalties(
            group_ip_id=group_ip_id, currency_token=MockERC20
        )

Group: claim_rewards

Claim rewards for the entire group. Returns ClaimRewardsResponse with tx_hash and claimed_rewards (#133).

Code Example:

story_client.Group.claim_rewards(
            group_ip_id=group_ip_id,
            currency_token=MockERC20,
            member_ip_ids=[ip_id],
        )

Group: get_claimable_reward

Query claimable rewards for each IP in the group (#136).

Code Example:

story_client.Group.get_claimable_reward(
            group_ip_id=group_ip_id,
            currency_token=MockERC20,
            member_ip_ids=[ip_id1, ip_id2],
        )

License: get_licensing_config

Retrieve the licensing configuration for a specific license term of an IP (#137).

Code Example:

 story_client.License.get_licensing_config(
            ip_id=ip_id,
            license_terms_id=register_commercial_remix_pil,
            license_template=PIL_LICENSE_TEMPLATE,
        )

Fix: set_licensing_config (#137)

• Fixed incorrect handling of expect_minimum_group_reward_share (was not converted to decimal).
• Converted property naming from camelCase → snake_case.
• Restricted input to the new LicensingConfig type.

Before: 

story_client.License.set_licensing_config(
        ip_id=ip_id,
        license_terms_id=register_commercial_remix_pil,
        licensing_config={
	        "mintingFee": 1,
	        "isSet": True,
	        "licensingHook": "0x0000000000000000000000000000000000000000",
	        "hookData": "0xFcd3243590d29B131a26B1554B0b21a5B43e622e",
	        "commercialRevShare": 0,
	        "disabled": False,
	        "expectMinimumGroupRewardShare": 1,
	        "expectGroupRewardPool": "0x0000000000000000000000000000000000000000",
        },
        license_template=PIL_LICENSE_TEMPLATE,
    )

After:

story_client.License.set_licensing_config(
            ip_id=ip_id,
            license_terms_id=register_commercial_remix_pil,
            licensing_config=LicensingConfig(
                minting_fee=100,
                is_set=True,
                licensing_hook=ZERO_ADDRESS,
                hook_data=b"",
                commercial_rev_share=100,
                disabled=False,
                expect_minimum_group_reward_share=10,
                expect_group_reward_pool=ZERO_ADDRESS,
            ),
            license_template=PIL_LICENSE_TEMPLATE,
        )

Breaking Changes

• set_licensing_config: argument type changed from dict → LicensingConfig
• register_commercial_use_pil and register_commercial_remix_pil: now return dict instead of dict | None (#137)

Other Changes

• Add integration tests for WIP's transferFrom and approve methods (#106)
• Introduced LicensingConfigData to validate licensing configs, convert tuples into LicensingConfig, and export the LicensingConfig type (#137).

Migration Guide

Step 1: 0.3.14 → 0.3.15-rc.1

• Introduced new methods: mint, register_ip_and_attach_pil_terms.
• Added support for custom nonce in transaction options.
• Integrated formatting tools (black, ruff, isort, pre-commit) and type checks (mypy).
• Expanded test coverage and added development documentation.
• No migration changes required — fully backward-compatible.

Step 2: 0.3.15-rc.1 → 0.3.15-rc.2

• Fixed scaling of expect_minimum_group_reward_share.
• Added support for wait_for_receipt and timeout in transaction options.

Breaking Change: AccessPermission Enum

The permission argument in the Permission module now uses the AccessPermission enum instead of numeric values.

Before

story_client.Permission.set_permission(
    ... # other arguments
    permission=1,
)

After

story_client.Permission.set_permission(
    ... # other arguments
    permission=AccessPermission.ALLOW,
)

Step 3: 0.3.15-rc.2 → 0.3.15 (Release)

Breaking Changes

• set_licensing_config: parameter type changed from dict → LicensingConfig.
• Methods such as register_commercial_use_pil and register_commercial_remix_pil now always return dict instead of dict | None.