Documentation

SPG Functions in TypeScript

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

  • Setup the client object.

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 { PIL_TYPE } from '@story-protocol/core-sdk';
import { toHex, Address } from 'viem';

const newCollection = await client.nftClient.createNFTCollection({ 
  name: 'Test NFT', 
  symbol: 'TEST', 
  txOptions: { waitForTransaction: true } 
});

const response = await client.ipAsset.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}`);

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 { PIL_TYPE } from '@story-protocol/core-sdk';
import { toHex } from 'viem';

const response = await client.ipAsset.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}`);

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';

const response = await client.ipAsset.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}`);

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 { PIL_TYPE } from '@story-protocol/core-sdk';
import { toHex } from 'viem';

const response = await client.ipAsset.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}`);

export type MintAndRegisterIpAndMakeDerivativeRequest = {
  nftContract: Address;
  derivData: {
    parentIpIds: Address[];
    licenseTermsIds: string[] | bigint[] | number[];
    licenseTemplate?: Address;
  };
  nftMetadata?: string;
  recipient?: Address;
} & IpMetadataAndTxOption;

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

export type RegisterDerivativeResponse = {
  txHash?: string;
  encodedTxData?: EncodedTxData;
  childIpId?: Address;
};

Updated about 22 hours ago