Collection Implementation in Loopring Layer 2

To properly support NFT collection in Loopring L2, we need to consider that the NFT may be minted on Ethereum L1 and then deposited to Loopring L2; conversely, the NFT may be minted on L2 then withdrawn to L1. In either case, we will make our best efforts to allow the collection’s information to be parsed properly by dApps in both L1 and L2.

A. Gamestop Collection standard

For NFTs minted directly on Loopring L2, we will follow the below standard that is implemented by Gamestop.

Wallets SHOULD inspect the “contract” field of the collection metadata and ensure that it matches the contract that the NFT exists within. If the values do not match, the metadata MAY be used, but the collection membership MUST be ignored. The collection that the NFT belongs to CANNOT be changed after minting.

B. Member of an immutable collection

Example of NFT metadata:

{ 
"name": "GameStop Test NFT",  
"description": "Used for mainnet testing.",  
"image": "ipfs://QmPg1...Q7Z",  
"animation_url": "ipfs://Qmc8M...acc",  
"collection_metadata": "ipfs://Qm7Ys...usd",  
"royalty_percentage": 10,  
"attributes": [...],  
"properties": {...}  
}

(Note the addition of a “collection_metadata” property, pointing to an IPFS URL.)

Example of Collection metadata (Contents of ipfs://Qm7Ys...usd)

{  
"contract": "0x9e1…f0b",  
"thumbnail_uri": "ipfs://Qm8I9...8de",  
"banner_uri": "ipfs://Qm8I9...8de",  
"avatar_uri": "ipfs://Qm8I9...8de",  
"tile_uri": "ipfs://Qm8I9...8de",  
"name": "Test NFTs",  
"description": "NFTs for platform testing.",  
}

Textual metadata about the collection (i.e., name, description) CANNOT be changed after minting.

If the image URIs are IPFS URLs:

  • Image metadata about the collection (i.e., thumbnail, banner, avatar, tile) CANNOT be changed after minting.

If the image URIs are HTTPS URLs:

  • Image metadata about the collection (i.e., thumbnail, banner, avatar, tile) CAN be changed after minting at the whim of the original creator; changes will apply to all NFTs in the collection.

C. Member of a mutable collection

The creator decides at minting time that they want freedom to edit their collection later.

Example of NFT metadata:

{ 
"name": "GameStop Test NFT",  
"description": "Used for mainnet testing.",  
"image": "ipfs://QmPg1...Q7Z",  
"animation_url": "ipfs://Qmc8M...acc",  
"collection_metadata": "https://server/AF0...7D3",  
"royalty_percentage": 10,  
"attributes": [...],  
"properties": {...}  
}

(Note the addition of a collection_metadata property, pointing to an HTTPS URL.)

Example of Collection metadata (Contents of https://server/AF0...7D3)

{  
"contract": "0x9e1…f0b",  
"banner_uri": "https://server/DC6A-...-7FF2",  
"avatar_uri": "https://server/AB61-...-837D",  
"tile_uri": "https://server/67DE-...-98DA",  
"name": "Test NFTs",  
"description": "NFTs for platform testing.",  
}

Textual metadata about the collection (name, description, etc.) CAN be changed after minting at the whim of the original creator; changes will apply to all NFTs in the collection. Image metadata about the collection (thumbnail, banner, avatar, tile) CAN be changed after minting at the whim of the original creator; changes will apply to all NFTs in the collection. Below is the typical pixel setup for collection metadata.

  1. Avatar: 500*500

  2. Banner: 1500*500

  3. Tile: 500*700

Please refer below to better understand the usage of Avatar, Banner and Tile.

  1. Avatar

    • Your collection can have its own avatar, separate from your profile avatar or icon. Collection avatars can be static images or gif/webp files. 

  2. Banner

    • The collection banner sits at the top of your collection page. Collection banners can only be static images.

  3. Tile

    • Also referred to as the cover. Your collection tile displays on your profile and the explore page as a static image or gif/webp animation.

D. How a smart contract is created to bind with a Collection

An NFT collection usually binds with a smart contract. When the NFT is withdrawn from L2 to L1, this smart contract needs to be deployed to Ethereum L1, so that the wallet/marketplace in L1 may access the NFT content correctly. In this context, the L1 front end app will treat the contract owner as the NFT collection owner. If the NFT creator wants to be treated as the collection owner in L1, usually they must be the contract owner of this NFT item when minting. To ensure the compatibility of Ethereum L1 and Loopring L2, Loopring’s official Mint UI will generate various contract addresses for every privately owned collection in L2 and set the contract owner as the wallet owner.

As the collection owner, the creator can connect to OpenSea etc. to further customize the look and feel of this collection in that marketplace.

E. Immediate Deployment vs. Lazy Deployment

The contract that the whole collection of the NFTs exist within only needs deploying on Ethereum L1 once. Loopring officially supports two deployment methods:

Immediate Deployment
Lazy Deployment

When the creator creates the collection, they can choose to deploy the contract in Ethereum Mainnet at that time. By doing so, they are required to pay the deployment fee immediately. Afterwards, all the NFTs belonging to the collection can be properly withdrawn to L1.

When the creator creates the collection, they can choose to delay the real contract deployment to the moment that the 1st NFT of this collection is withdrawn to Ethereum Mainnet. The person who withdraws the 1st NFT of this collection to L1 will be required to pay the contract deployment fee. If the NFTs only exist/circulate in Looping L2, creators can choose Lazy Deployment to save on cost.

F. NFTs minted in L2 and withdrawn to L1

To allow OpenSea etc. to retrieve the proper collection information in L1, it’s better to support the contractURI method in the contract. The returned data can point to the “collection_metadata” discussed in the previous chapter. Please refer to https://docs.opensea.io/v2.0/docs/contract-level-metadata per the below.

You can add a contractURI method to your ERC721 or ERC1155 contract that returns a URL for the storefront-level metadata for your contract. 


contract MyCollectible is ERC721 { 
function contractURI() public view returns (string memory) { 
     return "https://metadata-url.com/my-metadata"; 
} 
}

This URL should return data of the following format: 


{ 
  "name": "OpenSea Creatures", 
  "description": "OpenSea Creatures are adorable aquatic beings primarily for demonstrating what can be done using the OpenSea platform. Adopt one today to try out all the OpenSea buying, selling, and bidding feature set.", 
  "image": "external-link-url/image.png", 
  "external_link": "external-link-url", 
  "seller_fee_basis_points": 100, # Indicates a 1% seller fee. 
  "fee_recipient": "0xA97F337c39cccE66adfeCB2BF99C1DdC54C2D721" # Where seller fees will be paid to. 
}

G. Collection Metadata URI implementation

Loopring will host the collection-related metadata on Loopring HTTPS so that the collection owner is able to further edit the collection-related metadata on the Loopring website. Meanwhile, the contractURI interface of the Loopring NFT contract will return the same URI which points to this collection metadata. As a result, even when the NFT is withdrawn from L2 to L1, OpenSea will recognize the collection related information there.

Please be aware that some of the fields are commonly used in both Ethereum L1 and Loopring L2, such as “name” and “description”. Some of the fields are only recognized and used in L2 by Loopring, whilst some of the fields are only recognized and used in L1 by OpenSea.

To run an NFT marketplace in Loopring L2, the platform can customize the contractURI interface of the NFT contract to align with its collection metadata implementation to point to the proper URI implementation; else the NFT minted in the marketplace won’t be able to parse the collection-related information properly to OpenSea when withdrawn from L2 to L1.

H. NFTs minted in L1 and deposited to L2

For NFTs minted in L1, most likely the “collection_metadata” field is missing in the NFT metadata. All NFTs in the same contract are assumed to be part of the same collection. There are various ways to deal with the collection of those NFTs:

  1. Where wallets are not able to show a proper collection name, image, etc., the contract address will be used to mock up a collection name.

  2. Where wallets attempt to interact with the contractURI interface of the contract successfully, they retrieve the relevant information to display.

PreviousLoopring Layer 2 Mint Metadata ExplanationNextLoopring NFT Platform Implementation Guide

Last updated