Documentation

SPG Functions in React

Suggest Edits

A group of functions provided by the Story Protocol Gateway (SPG) contract, which is essentially a way to combine independent operations like Register an NFT as an IP Asset and Attach License Terms to an IP Asset into one transaction to make your life easier.

Prerequisites

Mint + Register + Attach Terms

This function allows you to do all of the following: Mint an NFT ▶️ Register an NFT as an IP Asset ▶️ Attach License Terms to an IP Asset

📘

Before You Use this Function

The address of nftContract must implement ISPGNFT in order to work.

An easy way to create a collection that implements ISPGNFT is to call the createCollection function in the SPG contract.

📘

NFT Metadata

Note that this function will also set the underlying NFT's tokenUri to whatever is passed under ipMetadata.nftMetadataURI.

import { toHex } from 'viem';
import { useIpAsset, useNftClient, PIL_TYPE } from "@story-protocol/react-sdk";

export default async function RegisterIPA() {
  const { createNFTCollection } = useNftClient();
  const { mintAndRegisterIpAssetWithPilTerms } = useIpAsset();
  
  const newCollection = await createNFTCollection({ 
    name: 'Test NFT', 
    symbol: 'TEST', 
    txOptions: { waitForTransaction: true } 
  });
  
  const response = await mintAndRegisterIpAssetWithPilTerms({
    nftContract: newCollection.nftContract as Address, // an NFT contract address created by the SPG
    pilType: PIL_TYPE.NON_COMMERCIAL_REMIX,
    // https://docs.story.foundation/docs/ipa-metadata-standard
    ipMetadata: {
      ipMetadataURI: 'test-uri',
      ipMetadataHash: toHex('test-metadata-hash', { size: 32 }),
      nftMetadataHash: toHex('test-nft-metadata-hash', { size: 32 }),
      nftMetadataURI: 'test-nft-uri',
    },
    txOptions: { waitForTransaction: true }
  });
  
  console.log(`
    Completed at transaction hash ${response.txHash},
    NFT Token ID: ${response.tokenId}, 
    IPA ID: ${response.ipId}, 
    License Terms ID: ${response.licenseTermsId}
  `);
  
  return (
    {/* */} 
  )
}

export type CreateIpAssetWithPilTermsRequest = {
  nftContract: Address;
  pilType: PIL_TYPE;
  currency?: Address;
  mintingFee?: string | number | bigint;
  recipient?: Address;
  commercialRevShare?: number;
  nftMetadata?: string;
} & IpMetadataAndTxOption;

type IpMetadataAndTxOption = {
  ipMetadata?: {
    ipMetadataURI?: string;
    ipMetadataHash?: Hex;
    nftMetadataURI?: string;
    nftMetadataHash?: Hex;
  };
  txOptions?: TxOptions;
};

export type CreateIpAssetWithPilTermsResponse = {
  txHash?: string;
  encodedTxData?: EncodedTxData;
  ipId?: Address;
  tokenId?: bigint;
  licenseTermsId?: bigint;
};

Register + Attach Terms

This function allows you to do all of the following: Register an NFT as an IP Asset ▶️ Attach License Terms to an IP Asset

import { toHex } from 'viem';
import { useIpAsset } from "@story-protocol/react-sdk";

export default async function RegisterIPA() {
  const { registerIpAndAttachPilTerms } = useIpAsset();
  
  const response = await registerIpAndAttachPilTerms({
    nftContract: "0xd516482bef63Ff19Ed40E4C6C2e626ccE04e19ED", // your NFT contract address
    tokenId: '127',
    pilType: PIL_TYPE.NON_COMMERCIAL_REMIX,
    // https://docs.story.foundation/docs/ipa-metadata-standard
    ipMetadata: {
      ipMetadataURI: 'test-uri',
      ipMetadataHash: toHex('test-metadata-hash', { size: 32 }),
      nftMetadataHash: toHex('test-nft-metadata-hash', { size: 32 }),
      nftMetadataURI: 'test-nft-uri',
    },
    txOptions: { waitForTransaction: true }
  });

  console.log(`
    Completed at transaction hash ${response.txHash},
    IPA ID: ${response.ipId},
    License Terms ID: ${response.licenseTermsId}
  `);
  
  return (
    {/* */} 
  )
}

export type RegisterIpAndAttachPilTermsRequest = {
  nftContract: Address;
  tokenId: bigint | string | number;
  pilType: PIL_TYPE;
  mintingFee: string | number | bigint;
  currency: Address;
  deadline?: bigint | number | string;
  commercialRevShare?: number;
} & IpMetadataAndTxOption;

type IpMetadataAndTxOption = {
  ipMetadata?: {
    ipMetadataURI?: string;
    ipMetadataHash?: Hex;
    nftMetadataURI?: string;
    nftMetadataHash?: Hex;
  };
  txOptions?: TxOptions;
};

export type RegisterIpAndAttachPilTermsResponse = {
  txHash?: string;
  encodedTxData?: EncodedTxData;
  ipId?: Address;
  licenseTermsId?: bigint;
};

Register + Derivative

This function allows you to do all of the following: Register an NFT as an IP Asset ▶️ Register an IPA as a Derivative

import { toHex } from 'viem';
import { useIpAsset } from "@story-protocol/react-sdk";

export default async function RegisterDerivative() {
  const { registerDerivativeIp } = useIpAsset();
  
  const response = await registerDerivativeIp({
    nftContract: "0xd516482bef63Ff19Ed40E4C6C2e626ccE04e19ED", // your NFT contract address
    tokenId: '127',
    derivData: {
      parentIpIds: ['0x4c1f8c1035a8cE379dd4ed666758Fb29696CF721'],
      licenseTermsIds: ['13']
    },
    // https://docs.story.foundation/docs/ipa-metadata-standard
    ipMetadata: {
      ipMetadataURI: 'test-uri',
      ipMetadataHash: toHex('test-metadata-hash', { size: 32 }),
      nftMetadataHash: toHex('test-nft-metadata-hash', { size: 32 }),
      nftMetadataURI: 'test-nft-uri',
    },
    txOptions: { waitForTransaction: true }
  });

  console.log(`Completed at transaction hash ${response.txHash}, IPA ID: ${response.ipId}`);
  
  return (
    {/* */} 
  )
}

export type RegisterIpAndMakeDerivativeRequest = {
  nftContract: Address;
  tokenId: string | number | bigint;
  deadline?: string | number | bigint;
  derivData: {
    parentIpIds: Address[];
    licenseTermsIds: string[] | bigint[] | number[];
    licenseTemplate?: Address;
  };
} & IpMetadataAndTxOption;

type IpMetadataAndTxOption = {
  ipMetadata?: {
    ipMetadataURI?: string;
    ipMetadataHash?: Hex;
    nftMetadataURI?: string;
    nftMetadataHash?: Hex;
  };
  txOptions?: TxOptions;
};

export type RegisterIpAndMakeDerivativeResponse = {
  txHash?: string;
  encodedTxData?: EncodedTxData;
  ipId?: Address;
};

Mint + Register + Derivative

This function allows you to do all of the following: Mint an NFT ▶️ Register an NFT as an IP Asset ▶️ Register an IPA as a Derivative

📘

Before You Use this Function

The address of nftContract must implement ISPGNFT in order to work.

An easy way to create a collection that implements ISPGNFT is to call the createCollection function in the SPG contract.

📘

NFT Metadata

Note that this function will also set the underlying NFT's tokenUri to whatever is passed under ipMetadata.nftMetadataURI.

import { toHex } from 'viem';
import { useIpAsset } from "@story-protocol/react-sdk";

export default async function RegisterDerivative() {
  const { mintAndRegisterIpAndMakeDerivative } = useIpAsset();
  
  const response = await mintAndRegisterIpAndMakeDerivative({
    nftContract: "0xd516482bef63Ff19Ed40E4C6C2e626ccE04e19ED", // your NFT contract address
    derivData: {
      parentIpIds: ['0x4c1f8c1035a8cE379dd4ed666758Fb29696CF721'],
      licenseTermsIds: ['13']
    },
    // https://docs.story.foundation/docs/ipa-metadata-standard
    ipMetadata: {
      ipMetadataURI: 'test-uri',
      ipMetadataHash: toHex('test-metadata-hash', { size: 32 }),
      nftMetadataHash: toHex('test-nft-metadata-hash', { size: 32 }),
      nftMetadataURI: 'test-nft-uri',
    },
    txOptions: { waitForTransaction: true }
  });

  console.log(`Completed at transaction hash ${response.txHash}, IPA ID: ${response.ipId}`);
  
  return (
    {/* */} 
  )
}

export type RegisterIpAndMakeDerivativeRequest = {
  nftContract: Address;
  tokenId: string | number | bigint;
  deadline?: string | number | bigint;
  derivData: {
    parentIpIds: Address[];
    licenseTermsIds: string[] | bigint[] | number[];
    licenseTemplate?: Address;
  };
} & IpMetadataAndTxOption;

type IpMetadataAndTxOption = {
  ipMetadata?: {
    ipMetadataURI?: string;
    ipMetadataHash?: Hex;
    nftMetadataURI?: string;
    nftMetadataHash?: Hex;
  };
  txOptions?: TxOptions;
};

export type RegisterIpAndMakeDerivativeResponse = {
  txHash?: string;
  encodedTxData?: EncodedTxData;
  ipId?: Address;
};

Updated about 23 hours ago