TheRelay

Augmented metadata for your NFTs

This article focuses on TheRelay, a tool that improves the indexing and querying of NFT metadata on EVM blockchains as a add-on for TheGraph. Its target audience is TheGraph community, mainly developers creating or using subgraphs, and also IPFS hosting providers.

The NFT industry has suffered substantial losses due to hacking, theft, deception, and poor asset management… emphasizing the requirement for trustworthy and decentralized metadata. To address this, TheRelay’s goal is to streamline access to NFT metadata and ensure its reliability via TheGraph network.

Metadata

Metadata are at the core of NFTs. Although ERC721Metadatais an option in the Ethereum proposal EIP-721, most of NFT collections supports it.

/// @title ERC-721 Non-Fungible Token Standard, optional metadata extension
interface ERC721Metadata /* is ERC721 */ {
    ...
    /// A distinct Uniform Resource Identifier (URI) for a given asset.
    /// The URI may point to a JSON file that conforms 
    /// to the "ERC721 Metadata JSON Schema".
    function tokenURI(uint256 _tokenId) external view returns (string);
}

EIP721Metadata definition https://eips.ethereum.org/EIPS/eip-721

But currently NFT subgraph are missing this metadata information, generally only a reference to the tokenURI pointing to a json file stored either on internet (AWS S3, Google Cloud…) or on decentralized storage (IPFS or ArWeave mainly).

The absence of metadata in subgraphs is due, by nature, to the slowness of metadata fetching, that can’t be done synchronously while blockchain is indexed by TheGraph. Moreover fetching metadata as a offchain process may fail sometimes, due to unreachable storage, to centralized access, or even due to invalid json format.

Solutions

To tackle this problem, work by The Graph Core Development team on « File data sources » is under process .

TheRelay propose a complementary solution via a proxy to enrich NFT subgraph. This solution is quite simple but centralized: it needs a hosted proxy server.

The two solutions are complementary and can be used together. Before full deployment of “File data sources” on all targeted network, TheRelay can be used as a centralized replacement.

Integration of TheRelay with TheGraph client being on the roadmap

TheRelay

TheRelay enables today the enrichment of NFT subgraphs, in a centralized / hosted way. TheRelay can only enrich NFTs having ERC721Medata option, i.e. with tokenURI.

TheRelay acts a json proxy between your GraphQL query and TheGraph network. TheRelay stores json metadata on IPFS if an IPFS server is available or stores it on it’s local filesystem.

Basic example

Let’s demonstrate it with a basic Example

Wighawag’s subgraph (‘wighawag/eip721-subgraph’), will be used as the reference subgraph to query

For example this GraphQL query :

{
  tokens(first: 3, skip: 2000) {
    id
    tokenURI
  }
}

sent to TheGraph at this endpoint:

https://api.thegraph.com/subgraphs/name/wighawag/eip721-subgraph

returns :

{
  "data": {
    "tokens": [
      {
        "id": "0x00000000001ba87a34f0d3224286643b36646d81_2610",
        "tokenURI": "https://dungeonized.com/nfts/2610"
      },
      {
        "id": "0x00000000001ba87a34f0d3224286643b36646d81_2611",
        "tokenURI": "https://dungeonized.com/nfts/2611"
      },
      {
        "id": "0x00000000001ba87a34f0d3224286643b36646d81_2612",
        "tokenURI": "https://dungeonized.com/nfts/2612"
      }
    ]
  }
}

Same query sent via TheRelay at this endpoint (needs TheRelay installed locally):

http:127.0.0.1:4004/api.thegraph.com/subgraphs/name/wighawag/eip721-subgraph

returns :

[
  {
    "id": "0x00000000001ba87a34f0d3224286643b36646d81_2610",
    "tokenURI": "https://dungeonized.com/nfts/2610",
    "metadata": {
      "name": "Dungeonized #2610",
      "image": "https://dungeonized.com/nfts/images/2610.png",
      "description": "Dungeonized is a collection consisting of 3,333 Heroes playable in a web game and inside of BEO. We are a utility based NFT with a plethora of value all delivered on a Free mint. Find out more on our website: https://Dungeonized.com",
      "attributes": [
        {
          "trait_type": "Background",
          "value": "Large Tower"
        },
        {
          "trait_type": "Mouth",
          "value": "No Mouth"
        },
        {
          "trait_type": "Body",
          "value": "Amethyst Purple"
        },
        {
          "trait_type": "Armor",
          "value": "Dark Green Armor"
        },
        {
          "trait_type": "Sword",
          "value": "Falchion Sword"
        },
        {
          "trait_type": "Head",
          "value": "Blue Bandana"
        },
        {
          "trait_type": "Scarf",
          "value": "Purple Scarf"
        },
        {
          "trait_type": "Eyes",
          "value": "Gray Eyes"
        },
        {
          "trait_type": "Pass Type",
          "value": "Regulars"
        }
      ]
    },
    "metadataCid": "bafybeieozp7w3vlhoiwisoi2khyhi7mbwgzdacubrf7p64h22zttmwmvre"
  }
  {
    ...
  }
  {
    ...
  }
]

We can see that in this example that the json metadata describing the NFT has been fetch from the internet and “merged” with the original response to the GraphQL query. No change to your query are needed, only change to the GraphQL endpoint!

To get full instructions on howto install TheRelay locally, and run this query: go to TheRelay GitHub repo

Features

Here is the list of features currently available on TheQuery

TheRelay : subgraph proxy
service acting as json proxy retrieving json answers from TheGraph and adding NFT metadata

• on each NFT query, on each NFT retrieved :
  NFT metadata read from IPFS (or filesystem) if available
  else metadata fetched from the tokenURI
  then optional archive to IPFS
  then optional save to filesystem
• start/stop/status commands available
• can be run as a daemon or inside TheQuery client
• can be run on local desktop or remote server
• manage fetching errors
• manage a database of chainId/collectionAddress/tokenID to metadata IPFS CID
• manage metadata cache on filesystem (locally or remotely)

TheQuery : cli framework

• TheGraph NFT queries : with both wighawag and amxx NFT schemas
• TheGraph NFT queries enriched with metadata via TheRelay (for both NFT schemas)
• GraphQL utility
• IFPS utility
• Ready for multi blockchain queries

Roadmap

New features that can be included on TheQuery

TheRelay

• integration with TheGraph client
• management of json errors
• manage ofinline metadata
• setup a stable remote server, with https, with IPFS pinning service
• transformation of TheRelay from a json relay to a real graphQL relay (then accessible via GraphiQL)

TheQuery

• full support of ENV parameters
• develop and run indexing scripts, to be applied on various blockchains to store / pin IPFS
• target specific position of tokenURI (currently only nfts/uri or nfts/tokenURI in TheGraph results)

Conclusion

This work is still under progress, so would you have any remarks or any specific needs, don’t hesitate to ask or contribute on TheRelay repo on GitHub.

TheRelay project has been developped by the Kredeum team, that develops an NFT Factory, where the need for the such a tool arose. TheRelay project has been granted during TheGraph Grant Wave 4