📝 IPA Metadata Standard

This is the JSON metadata that is associated with an IP Asset, and gets stored inside of an IP Account. You must call setMetadata(...) inside of the IP Account in order to set the metadata, and then call metadata() to read it.

​

Attributes & Structure

Below are the important attributes you should provide in your IP metadata. Under the Required For column is what the specific field is required for:

• 🔍 Story Explorer - this field will help display your IP on the Story Explorer
• 🕵️ Commercial Infringement Check - this field is required if your IP is commercial (that is, has commercialUse = true license terms attached). We will use these fields to run an infringement check on your IP.
  • See current limitations.
• 🤖 AI Agents - used for displaying metadata associated with AI Agents

​

Type Definitions

Here are the type definitions for the complex types used in the metadata:

type IpCreator = {
  name: string;
  address: Address;
  contributionPercent: number; // add up to 100
  description?: string;
  image?: string;
  socialMedia?: IpCreatorSocial[];
  role?: string;
};

type IpCreatorSocial = {
  platform: string;
  url: string;
};

​

Media Types

The following media types are allowed for the mediaType field:

​

Hashing Content

To hash content for the imageHash or mediaHash fields, you can use the SHA-256 hashing algorithm. Here’s an example of how to do this in JavaScript:

import { toHex, Hex } from "viem";

// get hash from a file
async function getFileHash(file: File): Promise<Hex> {
  const arrayBuffer = await file.arrayBuffer();
  const hashBuffer = await crypto.subtle.digest("SHA-256", arrayBuffer);
  return toHex(new Uint8Array(hashBuffer), { size: 32 });
}

// get hash from a url
async function getHashFromUrl(url: string): Promise<Hex> {
  const response = await axios.get(url, { responseType: "arraybuffer" });
  const buffer = Buffer.from(response.data);
  return "0x" + createHash("sha256").update(buffer).digest("hex");
}

​

Example Use Cases

{
  "title": "Ippy",
  "description": "Official mascot of Story.",
  "createdAt": "1728401700",
  "image": "https://ipfs.io/ipfs/QmSamy4zqP91X42k6wS7kLJQVzuYJuW2EN94couPaq82A8",
  "imageHash": "0x21937ba9d821cb0306c7f1a1a2cc5a257509f228ea6abccc9af1a67dd754af6e",
  "mediaUrl": "https://ipfs.io/ipfs/QmSamy4zqP91X42k6wS7kLJQVzuYJuW2EN94couPaq82A8",
  "mediaHash": "0x21937ba9d821cb0306c7f1a1a2cc5a257509f228ea6abccc9af1a67dd754af6e",
  "mediaType": "image/png",
  "creators": [
    {
      "name": "Story Foundation",
      "address": "0x67ee74EE04A0E6d14Ca6C27428B27F3EFd5CD084",
      "description": "The World's IP Blockchain",
      "contributionPercent": 100,
      "socialMedia": [
        {
          "platform": "Twitter",
          "url": "https://twitter.com/storyprotocol"
        },
        {
          "platform": "Telegram",
          "url": "https://t.me/StoryAnnouncements"
        },
        {
          "platform": "Website",
          "url": "https://story.foundation"
        },
        {
          "platform": "Discord",
          "url": "https://discord.gg/storyprotocol"
        },
        {
          "platform": "YouTube",
          "url": "https://youtube.com/@storyFDN"
        }
      ]
    }
  ],
  "tags": ["Ippy", "Story", "Story Mascot", "Mascot", "Official"], // experimental field
  "ipType": "Character" // experimental field
}

​

Optional Properties

The following properties are optional but can provide additional context about your IP Asset:

​

Type Definitions

type IpRelationship = {
  parentIpId: Address;
  type: string; // see "Relationship Types" docs below
};

​

Relationship Types

The different relationship types that can be used for the relationships attribute.

​

Story Relationships

1. APPEARS_IN - A character APPEARS_IN a chapter.

2. BELONGS_TO - A chapter BELONGS_TO a book.

3. PART_OF - A book is PART_OF a series.

4. CONTINUES_FROM - A chapter CONTINUES_FROM the previous one.

5. LEADS_TO - An event LEADS_TO a consequence.

6. FORESHADOWS - An event FORESHADOWS future developments.

7. CONFLICTS_WITH - A character CONFLICTS_WITH another character.

8. RESULTS_IN - A decision RESULTS_IN a significant change.

9. DEPENDS_ON - A subplot DEPENDS_ON the main plot.

10. SETS_UP - A prologue SETS_UP the story.

11. FOLLOWS_FROM - A chapter FOLLOWS_FROM the previous one.

12. REVEALS_THAT - A twist REVEALS_THAT something unexpected occurred.

13. DEVELOPS_OVER - A character DEVELOPS_OVER the course of the story.

14. INTRODUCES - A chapter INTRODUCES a new character or element.

15. RESOLVES_IN - A conflict RESOLVES_IN a particular outcome.

16. CONNECTS_TO - A theme CONNECTS_TO the main narrative.

17. RELATES_TO - A subplot RELATES_TO the central theme.

18. TRANSITIONS_FROM - A scene TRANSITIONS_FROM one setting to another.

19. INTERACTED_WITH - A character INTERACTED_WITH another character.

20. LEADS_INTO - An event LEADS_INTO the climax.?
    PARALLEL - story happening in parallel or around the same timeframe

​

AI Relationships

1. TRAINED_ON - A model is TRAINED_ON a dataset.

2. FINETUNED_FROM - A model is FINETUNED_FROM a base model.

3. GENERATED_FROM - An image is GENERATED_FROM a fine-tuned model.

4. REQUIRES_DATA - A model REQUIRES_DATA for training.

5. BASED_ON - A remix is BASED_ON a specific workflow.

6. INFLUENCES - Sample data INFLUENCES model output.

7. CREATES - A pipeline CREATES a fine-tuned model.

8. UTILIZES - A workflow UTILIZES a base model.

9. DERIVED_FROM - A fine-tuned model is DERIVED_FROM a base model.

10. PRODUCES - A model PRODUCES generated images.

11. MODIFIES - A remix MODIFIES the base workflow.

12. REFERENCES - An AI-generated image REFERENCES original data.

13. OPTIMIZED_BY - A model is OPTIMIZED_BY specific algorithms.

14. INHERITS - A fine-tuned model INHERITS features from the base model.

15. APPLIES_TO - A fine-tuning process APPLIES_TO a model.

16. COMBINES - A remix COMBINES elements from multiple datasets.

17. GENERATES_VARIANTS - A model GENERATES_VARIANTS of an image.

18. EXPANDS_ON - A fine-tuning process EXPANDS_ON base capabilities.

19. CONFIGURES - A workflow CONFIGURES a model’s parameters.

20. ADAPTS_TO - A fine-tuned model ADAPTS_TO new data.