v0.3.17

Story Protocol Python SDK v0.3.17

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

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

Overview

This release introduces unified, higher-level IPAsset workflows for registering IPs and derivatives, adds PILFlavor utilities for generating common PIL license terms, and improves workflows.

Key Changes

IPAsset Module Enhancements

register_ip_asset — Register IP assets with one entrypoint (PR #174)

register_ip_asset(...) is now the preferred API for IP registration. It consolidates multiple older "single-purpose" workflows into one method that chooses the correct on-chain workflow based on:

• nft.type ("minted" vs "mint")
• whether license_terms_data is provided
• whether royalty_shares is provided

Deprecated IPAsset methods (use register_ip_asset)

• mint_and_register_ip
• mint_and_register_ip_asset_with_pil_terms
• mint_and_register_ip_and_attach_pil_terms_and_distribute_royalty_tokens
• register
• register_ip_and_attach_pil_terms
• register_ip_and_attach_pil_terms_and_distribute_royalty_tokens

Code Example:

# (A) Mint-on-demand: mint + register as IP + attach PIL terms
resp = story_client.IPAsset.register_ip_asset(
    nft=MintNFT(type="mint", spg_nft_contract=nft_collection),
    license_terms_data=[
        LicenseTermsDataInput(
            terms=PILFlavor.commercial_use(
                default_minting_fee=10,
                currency=WIP_TOKEN_ADDRESS,
                royalty_policy=NativeRoyaltyPolicy.LAP,  # or LRP
            ),
            licensing_config=LicensingConfig(
                is_set=True,
                minting_fee=100,
                licensing_hook=ZERO_ADDRESS,
                hook_data=ZERO_HASH,
                commercial_rev_share=10,
                disabled=False,
                expect_minimum_group_reward_share=0,
                expect_group_reward_pool=ZERO_ADDRESS,
            ),
        )
    ],
)

# (B) Minted NFT: register existing NFT as IP (basic registration)
resp = story_client.IPAsset.register_ip_asset(
    nft=MintedNFT(type="minted", nft_contract=nft_collection, token_id=token_id),
)

# (C) Minted NFT: register + attach terms + distribute royalty tokens
resp = story_client.IPAsset.register_ip_asset(
    nft=MintedNFT(type="minted", nft_contract=nft_collection, token_id=token_id),
    license_terms_data=[
        LicenseTermsDataInput(
            terms=PILFlavor.commercial_remix(
                default_minting_fee=10,
                currency=WIP_TOKEN_ADDRESS,
                commercial_rev_share=10,
                royalty_policy=NativeRoyaltyPolicy.LRP,
            ),
            licensing_config=LicensingConfig(...),
        )
    ],
    royalty_shares=[
        RoyaltyShareInput(recipient=account.address, percentage=40),
        RoyaltyShareInput(recipient=account_2.address, percentage=60),
    ],
)

register_derivative_ip_asset — Register derivative IP assets with one entrypoint (PR #175)

register_derivative_ip_asset is now the preferred API for derivative IP registration. It consolidates multiple older "single-purpose" derivative workflows into one method that selects the correct on-chain workflow based on:

• nft.type ("minted" vs "mint")
• whether deriv_data is provided
• whether license_token_ids is provided
• whether royalty_shares is provided (only valid with deriv_data)

Deprecated IPAsset methods (use register_derivative_ip_asset)

• mint_and_register_ip_and_make_derivative
• mint_and_register_ip_and_make_derivative_with_license_tokens
• mint_and_register_ip_and_make_derivative_and_distribute_royalty_tokens
• register_derivative_ip
• register_ip_and_make_derivative_with_license_tokens
• register_derivative_ip_and_attach_pil_terms_and_distribute_royalty_tokens

Code Example:

# (A) Mint-on-demand: mint + register derivative via deriv_data
resp = story_client.IPAsset.register_derivative_ip_asset(
    nft=MintNFT(type="mint", spg_nft_contract=nft_collection),
    deriv_data=DerivativeDataInput(
        parent_ip_ids=[parent_ip_id],
        license_terms_ids=[license_terms_id],
    ),
)

# (B) Minted NFT: register derivative via license tokens
resp = story_client.IPAsset.register_derivative_ip_asset(
    nft=MintedNFT(type="minted", nft_contract=nft_collection, token_id=token_id),
    license_token_ids=[license_token_id],
)

# (C) Minted NFT: register derivative via deriv_data + distribute royalty tokens
resp = story_client.IPAsset.register_derivative_ip_asset(
    nft=MintedNFT(type="minted", nft_contract=nft_collection, token_id=token_id),
    deriv_data=DerivativeDataInput(
        parent_ip_ids=[parent_ip_id],
        license_terms_ids=[license_terms_id],
    ),
    royalty_shares=[
        RoyaltyShareInput(recipient=account.address, percentage=50),
        RoyaltyShareInput(recipient=account_2.address, percentage=50),
    ],
)

link_derivative — Link derivative IP assets (recommended unified API) (PR #176)

Unifies derivative linking via license terms or license token ids, and deprecates legacy derivative-linking APIs.

Deprecated IPAsset methods (use link_derivative)

• register_derivative
• register_derivative_with_license_tokens

Code Example:

# (A) Link derivative via license terms (parent IP IDs + license terms IDs)
resp = story_client.IPAsset.link_derivative(
    child_ip_id=child_ip_id,
    parent_ip_ids=[parent_ip_id],
    license_terms_ids=[license_terms_id],
    license_template="0x...",  # PIL License Template address
    max_minting_fee=10000,
    max_rts=10,
    max_revenue_share=100,
)

# (B) Link derivative via license token_id
resp = story_client.IPAsset.link_derivative(
    child_ip_id=child_ip_id,
    license_token_ids=[license_token_id],
)

PILFlavor — Utility to generate license terms (PR #177)

PILFlavor is a utility helper for generating common PIL license terms (as LicenseTermsInput). You can then pass the generated terms into License.register_pil_terms or into IP workflows (e.g. IPAsset.register_ip_asset).

New (via PILFlavor): Added a CC-BY (Creative Commons Attribution) license-terms flavor. This license type was not available through the previous License convenience helpers, but can now be generated consistently using PILFlavor.creative_commons_attribution and registered via License.register_pil_terms.

Deprecated License methods (use PILFlavor + register_pil_terms)

• register_non_com_social_remixing_pil() → use register_pil_terms(**asdict(PILFlavor.non_commercial_social_remixing()))
• register_commercial_use_pil(...) → use register_pil_terms(**asdict(PILFlavor.commercial_use(...)))
• register_commercial_remix_pil(...) → use register_pil_terms(**asdict(PILFlavor.commercial_remix(...)))

Code Example:

from dataclasses import asdict

# 1) Non-commercial social remixing (NCSR)
ncsr_terms = PILFlavor.non_commercial_social_remixing()
resp = story_client.License.register_pil_terms(**asdict(ncsr_terms))

# 2) Commercial use
commercial_use_terms = PILFlavor.commercial_use(
    default_minting_fee=10,
    currency=WIP_TOKEN_ADDRESS,
    royalty_policy=NativeRoyaltyPolicy.LAP,
)
resp = story_client.License.register_pil_terms(**asdict(commercial_use_terms))

# 3) Commercial remix
commercial_remix_terms = PILFlavor.commercial_remix(
    default_minting_fee=10,
    currency=WIP_TOKEN_ADDRESS,
    commercial_rev_share=10,
    royalty_policy=NativeRoyaltyPolicy.LRP,
)
resp = story_client.License.register_pil_terms(**asdict(commercial_remix_terms))

# 4) Creative Commons Attribution (CC-BY)
cc_by_terms = PILFlavor.creative_commons_attribution(
    currency=WIP_TOKEN_ADDRESS,
    royalty_policy=NativeRoyaltyPolicy.LAP,
)
resp = story_client.License.register_pil_terms(**asdict(cc_by_terms))

Other Changes

1. LicensingConfig.hook_data input uses str and is converted before sending. (PR #177)
2. PR workflows (external + internal): added GitHub Actions workflows to run unit + integration tests for both external and internal PRs (PR #171).
3. Enhanced integration test (PR #166).
4. Updated CODEOWNERS (PR #168)
5. Added development dependencies to setup.py (PR #170).

Migration Guide

The following methods have been marked as deprecated and will be removed in a future major version. While these methods remain functional in v0.3.17, we strongly recommend migrating to the new unified APIs as soon as possible.

• Register IPs via unified API

  • Recommended: Use IPAsset.register_ip_asset(...)
  • Deprecated (will be removed in a future major version):
    • mint_and_register_ip(...)
    • mint_and_register_ip_asset_with_pil_terms(...)
    • mint_and_register_ip_and_attach_pil_terms_and_distribute_royalty_tokens(...)
    • register(...)
    • register_ip_and_attach_pil_terms(...)
    • register_ip_and_attach_pil_terms_and_distribute_royalty_tokens(...)

• Register derivative IPs via unified API

  • *...

v0.3.16

Story Protocol Python SDK v0.3.16

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

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

Overview

This release introduces enhancements to the IP asset and royalty modules, adding multiple SPG methods for minting and registering IPs. It also expands support for Wrapped IP (WIP) workflows, improves event parsing accuracy, and resolves bugs.

Key Changes

IPAsset Module Enhancements

Batch IP Minting and Registration

Introduced the batch_mint_and_register_ip method to facilitate the batch minting and registration of intellectual properties (IPs), streamlining the process for handling multiple IPs simultaneously([#154](#154)).

Code Example:

  requests = [
            BatchMintAndRegisterIPInput(
                spg_nft_contract=public_nft_collection,
            ),
            BatchMintAndRegisterIPInput(
                spg_nft_contract=private_nft_collection,
            ),
            BatchMintAndRegisterIPInput(
                spg_nft_contract=private_nft_collection,
                ip_metadata=IPMetadataInput(
                    ip_metadata_hash=web3.keccak(text="private-custom-metadata2"),
                    ip_metadata_uri="https://example.com/private-metadata.json",
                ),
            ),
        ]
 response = story_client.IPAsset.batch_mint_and_register_ip(requests)

Register Derivative IP with PIL Terms and Royalty Distribution

Added the register_derivative_ip_and_attach_pil_terms_and_distribute_royalty_tokens method, enabling the registration of derivative IPs, attachment of PIL terms, and distribution of royalty tokens in a single operation([#153](#153)).

Note: The first attached license must be a commercial license for successful royalty distribution.

Code Example:

story_client.IPAsset.register_derivative_ip_and_attach_pil_terms_and_distribute_royalty_tokens(
            nft_contract=nft_collection,
            token_id=token_id,
            deriv_data=DerivativeDataInput(
                parent_ip_ids=[parent_ip_and_license_terms["parent_ip_id"]],
                license_terms_ids=[parent_ip_and_license_terms["license_terms_id"]],
            ),
            royalty_shares=[
            RoyaltyShareInput(recipient=account.address, percentage=40.0),
            RoyaltyShareInput(recipient=account_2.address, percentage=60.0),
        ]
        )

Register IP with PIL Terms and Royalty Distribution

Implemented the register_ip_and_attach_pil_terms_and_distribute_royalty_tokens method, allowing for the registration of IPs with attached PIL terms and the distribution of royalty tokens([#152](#152)).

Note: The first attached license must be a commercial license for successful royalty distribution.

Code Example:

story_client.IPAsset.register_ip_and_attach_pil_terms_and_distribute_royalty_tokens(
            nft_contract=nft_collection,
            token_id=token_id,
            license_terms_data=[
                LicenseTermsDataInput(
                    terms=LicenseTermsInput(
                       ... 
                    ),
                    licensing_config=LicensingConfig(
                      ...
                    ),
                )
            ],
            royalty_shares=[
	            RoyaltyShareInput(recipient=account.address, percentage=30),
              RoyaltyShareInput(recipient=account_2.address, percentage=70),
		        ]
,
        )

Mint and Register IP with PIL Terms and Royalty Distribution

Introduced the mint_and_register_ip_and_attach_pil_terms_and_distribute_royalty_tokens method, combining the minting and registration of IPs with the attachment of PIL terms and distribution of royalty tokens([#150](#150)).

Code Example:

story_client.IPAsset.mint_and_register_ip_and_attach_pil_terms_and_distribute_royalty_tokens(
            spg_nft_contract=nft_collection,
            license_terms_data=[
                LicenseTermsDataInput(
                    terms=LicenseTermsInput(
                      ...
                    ),
                    licensing_config=LicensingConfig(
                      ...
                    ),
                )
            ],
            royalty_shares=[
            RoyaltyShareInput(recipient=account.address, percentage=50),
		        ],
        )

Register IP with Derivative Creation and license tokens

Added the register_ip_and_make_derivative_with_license_tokens method, enabling the registration of IPs along with the creation of derivative works using license tokens([#140](#140)).

Code Example:

story_client.IPAsset.register_ip_and_make_derivative_with_license_tokens(
                nft_contract=nft_contract,
                token_id=token_id,
                license_token_ids=license_token_ids,
            )

Mint and Register IP with Derivative Creation and Royalty Distribution:

Implemented the mint_and_register_ip_and_make_derivative_and_distribute_royalty_tokens method, facilitating the minting and registration of IPs, creation of derivative works, and distribution of royalty tokens([#148](#148)).

Code Example:

story_client.IPAsset.mint_and_register_ip_and_make_derivative_and_distribute_royalty_tokens(
            spg_nft_contract=nft_collection,
            deriv_data=DerivativeDataInput(
                parent_ip_ids=[parent_ip_id],
                license_terms_ids=[license_terms_id],
            ),
            royalty_shares=[
                RoyaltyShareInput(recipient=recipient1, percentage=60),
                RoyaltyShareInput(recipient=recipient2, percentage=40),
            ],
        )

Bug Fixes

• Resolved an issue in the claim_all_revenue method where the "unwrap IP" option was not functioning correctly, ensuring proper revenue claims. (PR [#155](#155))
• Corrected deadline calculation, changing the unit from milliseconds to seconds([#149](#149)).

Breaking Change

Fixed an issue where the deadline signature used milliseconds instead of seconds. The signature expiration time has been shortened.

Migration

• This fix requires no action. No code changes are needed on your side.

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.

v0.3.15-rc.2

Story Protocol Python SDK v0.3.15-rc.2

Release Candidate — This is a release candidate for the upcoming v0.3.15 major version of the Story Protocol Python SDK.

Overview

This release enhances developer experience by providing finer control over transactions, a streamlined IP workflow, and fixing an important reward calculation bug.

Key Changes

Fixed scaling of expect_minimum_group_reward_share

The scaling of the expect_minimum_group_reward_share value has been corrected to align with contract expectations (#117).

Previously, passing 10 would send 10 directly to the contract. Now, it correctly sends 10 * 10**6.

New IPAsset Method: mint_and_register_ip_and_make_derivative

Simplifies the workflow for minting IP, registering it, and creating derivatives in a single call (#119).

Code Example:

response = story_client.IPAsset.mint_and_register_ip_and_make_derivative(
    spg_nft_contract=nft_collection,
    deriv_data=DerivativeDataInput(
        parent_ip_ids=[parent_ip_id],
        license_terms_ids=[license_terms_id],
    ),
)

---

Support for wait_for_receipt and timeout in transaction options

Developers can now customize transaction behavior, including waiting for receipts and specifying a timeout. These options are supported across all SDK methods.

• wait_for_receipt defaults to True (All transactions wait for receipts).
• timeout defaults to 300 seconds. If the timeout elapses before the transaction is included in a block, wait_for_transaction_receipt() raises a web3.exceptions.TimeExhausted exception (#120).

Code Example:

story_client.IPAsset.register(
    nft_contract=MockERC721,
    token_id=token_id,
    ip_metadata=metadata,
    deadline=1000,
    tx_options={"timeout": 200, "wait_for_receipt": True},
)

---

Other Changes

• Added more unit tests, including for mint and register_ip_and_attach_pil_terms methods (#114).
• Fixed register_derivative method failure issue (#109).
• Added DerivativeDataInput and derivative_data for input validation, a get_function_signature helper, common test fixtures, and the new AccessPermission enum for improved permission handling (#109).

Migration Guide

With the introduction of the AccessPermission enum, update the permission argument in the Permission module to use the enum instead of numeric values.

Old Syntax:

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

New Syntax:

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

v0.3.15-rc.1

Story Protocol Python SDK v0.3.15-rc.1

Release Candidate - This is a release candidate for the upcoming v0.3.15 major version of the Story Protocol Python SDK.

Overview

This release candidate introduces significant improvements to code quality, developer experience, and adds new functionality to the Story Protocol Python SDK. The focus has been on enhancing the development workflow and introducing new features for IP asset management.

New Features

New IPAsset method: mint

The mint method for minting an NFT from the nft_contract (#74). The process is only callable when is_public_minting is true Or when the caller is the owner When creating nft_contract by calling nftClient.create_nft_collection .

• allow_duplicates : The default value is false.

Usage Example

  response = story_client.IPAsset.mint(
            nft_contract=nft_collection,
            to_address=account.address,
            metadata_uri=metadata_uri,
            metadata_hash=metadata_hash
        )

New IPAsset method: register_ip_and_attach_pil_terms

The register_ip_and_attach_pil_terms method for registering a given NFT as an IP and attaching Programmable IP License Terms(#72).

Usage Example

result = story_client.IPAsset.register_ip_and_attach_pil_terms(
            nft_contract=nft_collection,
            token_id=token_id,
            deadline=1000,
            license_terms_data=[
                {
                    "terms": license_terms,
                    "licensing_config":licensing_config,
                },
            ],
        )

Custom nonce support enables transaction replacement

The optional transaction of tx_options accept nonce to use a custom nonce value(#108) to avoid nonce conflict. If not provided, nonce will be automatically fetched from web3.eth.get_transaction_count() .
All methods that accept tx_options support custom nonce.

Usage Example

 response = story_client.IPAsset.register(
            nft_contract=MockERC721, token_id=token_id, tx_options={"nonce": 1}
        )

Other changes

• Code formatting: Updated tools included black, ruff ,isort , pre-commit to check and format code style( #100, #101, #102)
• Security: Git-leaks integration for secret detection(#107)
• Static type checker: Add mypy to check type(#103)
• Enhance tests:
  1. Fix permission unit tests (#78)
  2. Generate unit test coverage(#80)
  3. Add common integration fixtures to conftest.py which centralizes common test setup, maintainable, and efficient pytest test suites(#102).
• Documentation: Comprehensive DEVELOPMENT.md to guide the developer on how to set up the environment and develop(#101).
• CODEOWNERS: Added team members to CODEOWNERS file (#79)

Migration Guide

No migration steps required for existing users. The SDK maintains backward compatibility while adding new features and improvements.

Getting Started

For new users, refer to the updated DEVELOPMENT.md for comprehensive setup instructions, including UV package manager installation, pre-commit hooks setup, testing and development workflow, and code formatting standards.

v0.3.14 Release

This release implements enhancements to improve the functionality of the Permission, Dispute, WIP, Group, and Royalty Modules.

Features & Enhancements

Permission Module

• New Functions. #65 Implemented functions to set and verify permissions and generate and validate signatures.:
  • set_permission()
  • set_all_permissions()
  • create_set_permission_signature()
  • _check_is_registered()

Dispute Module

• New Functions. #66 implemented the dispute_assertionfunction to counter a dispute that another party raised

WIP Module

• New Functions. #66 implemented the allowance function that returns the amount of WIP tokens an account can spend on behalf of another.

Group Module

• New Functions. #70 expanded group management capabilities, enhanced royalty handling with vault transfers, and improved permission signature generation to support multiple permissions.
  • register_group()
  • register_group_and_attach_license()
  • mint_and_register_ip_and_attach_license_and_add_to_group()
  • register_ip_and_attach_license_and_add_to_group()
  • register_group_and_attach_license_and_add_ips()
  • collect_and_distribute_group_royalties()

Royalty Module

• New Functions. #70 implemented the transfer_to_vault function to route claimable revenue tokens directly into a designated vault, as determined by a royalty policy.

v0.3.13 Release

SDK Release Notes – v0.3.13

These enhancements improve functionality, expand test coverage, and elevate code maintainability and readability in line with PEP 8 standards.

Features & Enhancements

IPAccount Module

• New Functions. #59 Added functions for setting IP metadata and transferring ERC-20:
  • set_ip_metadata()
  • transfer_erc20()
• Test Coverage. #60 Expanded integration test coverage with the following cases:
  • test_execute_with_sig_wrong_signer
  • test_transfer_erc20_empty_tokens
  • test_transfer_erc20_invalid_token_params

NFT Module

• New Functions. #58 Added functions for querying mint-related details:
  • get_mint_fee()
  • get_mint_fee_token()
• Test Coverage. #61 Expanded integration test coverage with the following cases:
  • test_invalid_mint_fee_values
  • test_parameter_omission
  • test_authorization_errors

Utilities & Testing Infrastructure

• Added private_key to the utils package for use in integration tests. #59

Code Quality Improvements #62

• Removed a duplicate import to clean up code dependencies.
• Standardized naming conventions across the Story Protocol Python SDK:
• Converted method names from camelCase to snake_case to align with Pythonic conventions.
• Updated variable names for improved consistency.
• Centralized constants in utils/constants.py and updated related imports.
• Cleaned up unnecessary whitespace and improved overall formatting.

Documentation

Revised to include newly added IPAccount and NFT module functions, as well as updated to reflect standardized naming conventions (camelCase → snake_case) for improved clarity and consistency with Python best practices.

v0.3.12 Release

This release introduces key foundational modules for Dispute Resolution, WIP token operations, and Royalty Management, as well as internal integration testing improvements and client-side enhancements.

New Features

Dispute Module

• Added raiseDispute() function (excluding dispute_assertion())
• Integration with $IP → $WIP conversion for dispute bonding
• Basic integration test coverage for raiseDispute()

WIP Token Module

• Introduced WIP client with the following functions:
  • approve(), deposit(), transfer(), transferFrom(), withdraw(), balanceOf()
• Added getWalletBalance() to the Story client
• Initial integration tests for:
  • deposit(), transfer(), withdraw(), balanceOf()

Royalty Module Enhancements

• Added claimAllRevenue()
• Updated:
  • payRoyaltyOnBehalf()
  • getRoyaltyVaultAddress()
  • claimableRevenue() and related helpers
• Added MockERC20 client for transfer simulations
• Removed deprecated snapshot logic and other unused code
• Improved integration tests (note: some tests skipped due to incomplete features)

IPAccount Module

• Added owner() read function
• Improved function descriptions for consistency
• Refactored internal helper functions for parameter validation clarity

Testing

• Integration tests added for Dispute, WIP, and Royalty modules
• Some tests (e.g. approve(), transferFrom(), full royalty flow) are pending in future PRs
• owner() function lacks a dedicated test (to be added)

Notes

• Allowance Required: Users must call approve() on the UMA arbitration policy contract to set the correct allowance for dispute bonding.
• Partial Feature Coverage: This release is part of a staged rollout; several modules have incomplete test coverage or are awaiting dependent features.

@story-protocol/python-sdk@0.3.8a1

Key Changes

• Added mainnet support
  • chain_id '1515' is now supported
• Register() Bug Fix
  • Fixed camel case bug so that metadata is properly updated
• New release
  • Manual publish of new version release to PyPi