SDK Update (v0.1.10)

​

Key Changes & New Features

​

1. Digital Asset Minting (CulturaDigitalAssetClient)

• BREAKING CHANGE: The mintDigitalAsset function signature has changed:
  • The imageUrl?: string parameter has been removed and replaced by two new mandatory parameters:
    • terms: Record<string, any> | string: Holds asset-specific terms or extended metadata. For derivatives, this often contains licensing terms. Accepts an object (for IPFS upload) or a pre-existing URI string.
    • tokenURI: Record<string, any> | string: Holds the standard ERC721 metadata (name, description, image, etc.). Accepts an object (for IPFS upload) or a pre-existing URI string.
  • Migration: Update all calls to mintDigitalAsset to provide both the terms and tokenURI parameters, even for original assets. For originals, terms can point to general metadata or creator terms distinct from the standard tokenURI metadata.
  Copy

  Ask AI

  // Old:
  // await sdk.culturaDigitalAsset.mintDigitalAsset(to, name, desc, [], optionalImageUrl);
  
  // New (with object upload):
  const termsData = {
    name: assetName,
    description: assetDescription /* ...other terms */,
  };
  const tokenMetadata = {
    name: assetName,
    description: assetDescription,
    image: imageUrl /* ...other ERC721 metadata */,
  };
  await sdk.culturaDigitalAsset.mintDigitalAsset(
    to,
    name,
    desc,
    [],
    termsData,
    tokenMetadata
  );
  
  // New (with object upload):
  const metadata = {
    name: assetName,
    description: assetDescription,
    image: imageUrl,
  };
  await sdk.culturaDigitalAsset.mintDigitalAsset(
    to,
    name,
    desc,
    [],
    metadata,
    metadata
  );
  
  // New (with existing URIs):
  // New (with existing URIs):
  await sdk.culturaDigitalAsset.mintDigitalAsset(
    to,
    name,
    desc,
    [],
    "ipfs://yourTermsCID",
    "ipfs://yourTokenUriCID"
  );
  
• New Validation: mintDigitalAsset now strictly validates that the sum of royaltySplit values in the parentDigitalAssets array equals exactly 75n (representing 75%) when minting derivative assets (i.e., when parentDigitalAssets is not empty). Calls will now fail if the sum is incorrect. Ensure your derivative minting logic adheres to this rule.
• Utility Update: The internal uploadMetadataToIpfs utility function is now more flexible, accepting any Record<string, any> object, aligning with the changes to mintDigitalAsset.

​

2. Royalty System (RoyaltyClient & CRS Contract Updates)

• New Feature: Off-Chain Payment Workflow: The Cultura Royalty System (CRS) contract and the RoyaltyClient now support reporting, accepting, and denying royalty payments made off-chain (e.g., via traditional methods). This allows for tracking and reconciliation within the Cultura ecosystem.
  • New SDK Methods:
    • royalty.reportOffChainPayment(tokenId, periodIndex, amount, metadata): Allows a payer (e.g., licensee) to report an off-chain payment amount for a specific royalty period.
    • royalty.acceptOffChainPayment(tokenId, periodIndex, culturaBoundAccount, signature): Allows the rights holder (via their bound account) to accept a reported off-chain payment, requiring an EIP712 signature.
    • royalty.denyOffChainPayment(tokenId, periodIndex, signature): Allows the rights holder to deny a reported off-chain payment, requiring an EIP712 signature.
  • New Contract Events: Corresponding events (OffChainPaymentReported, OffChainPaymentAccepted, OffChainPaymentDenied) are emitted by the CRS contract.
  • New Contract Errors: Several new error types related to off-chain payment status, signatures, and allowances have been added to the CRS contract for robustness.
• EIP712 Integration: The CRS contract now implements EIP712, providing the necessary domain separator for creating signatures required by acceptOffChainPayment and denyOffChainPayment. The SDK handles signature creation internally where applicable.

​

3. Mock Licensing Protocol (MockLicensingProtocolClient Updates)

• Behavior Change: isLicensedToken(collectionAddress, tokenId) now specifically checks if the currently connected wallet (i.e., walletClient.account.address) has licensed the specified token via an attestation. Previously, it might have only checked for the token’s existence. This makes the check more accurate for verifying if the current user has the necessary license.
• API Update: createLicensedAsset now accepts an optional termsURI?: string parameter, allowing explicit setting of terms during mock licensed asset creation. The licensedAssetDetails input object now also expects an optional imageUrl. Internally, this function now correctly calls the updated mintDigitalAsset with both termsURI and token metadata (including the image URL).
• Example Flow Update: The verified-rights-licensing-flow.ts example demonstrates the updated flow:
  • The licensee (not the minter) now calls licenseDigitalAsset on the parent tokens.
  • Includes checks using the updated isLicensedToken logic before creating the derivative.
  • Shows passing imageUrl within licensedAssetDetails to createLicensedAsset.

​

4. Verifier Module (VerifierModuleClient New Feature)

• New Method: Added getTotalRewards(digitalAssetAddress, digitalAssetId) method. This allows querying the total accumulated rewards (collected verification fees, potentially unclaimed) associated with a specific verified right (identified by its digital asset address and ID) directly from the VerifierModule contract.

​

5. Query Client & Types (QueryClient Data Enhancements)

• Richer Query Data: Subgraph queries have been updated to return more comprehensive data, potentially reducing the need for subsequent calls:
  • digitalAsset.owner now includes the owner’s tokenCount.
  • digitalAsset.verifiedRights (when fetched as part of a digitalAsset query) and verifiedRights (when queried directly) now include a detailed verifications array. Each entry in this array contains information about an individual verification action, including the verifier’s details (address, bond amount, etc.), the bondAmount for that specific verification, and the timestamp.
  • verifiedRights.digitalAsset (when fetched as part of a verifiedRights query) now includes the nested digital asset’s id, tokenId, and full owner information (address, token count).
• Internal Type Reorganization: SDK type definitions have been reorganized into more granular files (e.g., types/query.ts, types/resources/culturaDigitalAsset.ts). This primarily affects internal structure but might impact projects directly importing specific type definitions. The main index.ts export structure remains largely consistent for core functionalities.

​

6. Contract Deployments

• Contract addresses for devnet and testnet have been updated. Ensure your SDK configuration points to the correct environment or manually provide the latest addresses if needed. See Deployments.

​

Migration Guide

• mintDigitalAsset Calls: (Required) Review every call to sdk.culturaDigitalAsset.mintDigitalAsset. Replace the old optional imageUrl parameter with the two new mandatory parameters: terms (object/URI for specific terms/metadata) and tokenURI (object/URI for standard ERC721 metadata including image). Ensure both are provided for original and derivative assets.
• Derivative Minting Validation: (Required) If minting derivative assets (passing non-empty parentDigitalAssets), ensure the sum of royaltySplit values in the array equals exactly 75n. Adjust splits if necessary.
• isLicensedToken Logic: (Review Recommended) If using sdk.mockLicensingProtocol.isLicensedToken, be aware it now checks if the currently connected wallet holds the license attestation. Update application logic if it previously assumed a different check (e.g., just token existence).
• createLicensedAsset Calls: (Optional) If using sdk.mockLicensingProtocol.createLicensedAsset, you can now optionally provide termsURI and include imageUrl in the licensedAssetDetails.
• Query Result Handling: (Optional) Update frontend or backend code that processes query results to leverage the new data fields (e.g., owner.tokenCount, verifiedRights.verifications array) for richer displays or logic.
• Contract Addresses: Ensure your SDK initialization or application configuration uses the updated contract addresses for the target network (testnet/devnet) as listed in the Deployments section.