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

  • Recommended: Use IPAsset.register_derivative_ip_asset(...)
  • Deprecated (will be removed in a future major version):
    • 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(...)

• Link derivatives via unified API

  • Recommended: Use IPAsset.link_derivative(...)
  • Deprecated (will be removed in a future major version):
    • register_derivative(...)
    • register_derivative_with_license_tokens(...)

• Generate license terms via PILFlavor

  • Recommended: Use PILFlavor.*() to generate LicenseTermsInput, then register via License.register_pil_terms(**asdict(terms))
  • Deprecated (will be removed in a future major version):
    • License.register_non_com_social_remixing_pil()
    • License.register_commercial_use_pil(...)
    • License.register_commercial_remix_pil(...)
  • This also enables additional flavors like CC-BY via PILFlavor.creative_commons_attribution(currency=..., royalty_policy=...)