Official0xygen MetaMask NFT Integration
Plug-in Documentation
Updated: 09.14.2023 UE5.2
Prerequisites for this version:
-
REQUIRED: An EVM compatible NFT Contract that has the following properties:
-
IERC-721: All ERC-721 compliant NFT contracts contains contain this core functionality.
-
IERC721Metadata: Almost every contract will contain this functionality.
-
IERC721Enumerable: Many contracts will contain this and it is needed for retrieving tokens contained in a gamer’s wallet.
-
-
REQUIRED: A set of API keys, which can be provided at the sole discretion of Team 0xygen [support@0xygen.io]. Projects will be vetted and you may be asked to verify contract ownership.
-
RECOMMENDED: For testing purposes, it is recommended that you have a MetaMask wallet with browser extension installed (https://metamask.io/) that owns at least one NFT from your collection.
Developing with the Official0xygen Unreal Engine Blueprints:
The Official 0xygen Blueprint nodes are grouped into three primary functions:
A primary function is separated into multiple nodes to give developers increased flexibility and timing control. In general, full utilization of a primary function requires the usage of all of its associated Blueprint Nodes.
Wallet Verification
The Wallet Verification primary function is used to confirm that account details are valid. It utilizes two Blueprint Nodes: Sync Wallet and Verify Wallet.
Sync Wallet Node
The Sync Wallet node is utilized to request confirmation that a given username and password pair is associated with a valid account on the 0xygen server. It creates a Wallet Relay Object to send this request and receive the corresponding response.
INPUT:
-
The Username STRING to be verified as part of a Username/Password pair
-
The Password STRING to be verified as part of a Username/Password pair
OUTPUT:
-
The Wallet Relay Object that has sent the verification request to the server
Verify Wallet Node
The Wallet Verification primary function is used to confirm that account details are valid. It utilizes two Blueprint Nodes: Sync Wallet and Verify Wallet.
The Verify Wallet node is utilized to analyze the response received from a Sync Wallet request. It provides confirmation whether a given username and password pair is associated with a valid account on the 0xygen server.
INPUT:
-
A Wallet Relay Object that was created by a Sync Wallet node
OUTPUT:
-
TRUE if the Username/Password pair is associated with a valid account
-
FALSE if the Username/Password pair is NOT associated with a valid account
Wallet Verification Example
The following is an example snippet for how to use all of the blueprint nodes associated with the Wallet Verification primary function in conjunction. It utilizes a Check Relay Response Loop (detailed below):
Obtaining NFT Metadata
The Obtaining NFT Metadata primary function is used to pull the NFT Metadata associated with user account(s) from the Blockchain into your Unreal Engine project. It utilizes three Blueprint Nodes: Get Metadata, Process Metadata, Build Metadata Map.
Get Metadata Node
The Get Metadata Wallet node is utilized to request the metadata of all NFTs that are from a given API key and owned by a provided list of users. It creates a Metadata Relay Object to send this request and receive the corresponding response.
INPUT:
-
The API Key of the NFTs as a STRING
-
The Users to be checked as an ARRAY of Username STRING
OUTPUT:
-
The Metadata Relay Object that has sent the request to the server
Process Metadata Node
The Process Metadata node is utilized to analyze the response received from a Get Metadata request. It organizes the NFT metadata into several mappings that can be searched for specific values.
INPUT:
-
A Metadata Relay Object that was created by a Get Metadata node
OUTPUT:
-
The Username to TokenID Map
-
The Map Key a valid Username as a STRING. This should be one of the usernames provided in the Users input array of the associated Get Metadata node
-
The Map Value is a comma-separated list of TokenIDs associated with the Username Key given as a single STRING. Can be parsed into an array with the comma delimiter ‘,’
-
-
The TokenID to Metadata Map
-
The Map Key is valid TokenID as a STRING. This should be one of the usernames provided in the Users input array of the associated Get Metadata node.
-
The Map Value is the NFT metadata JSON given as a formatted STRING. Can be parsed into a map with the Build Metadata Map node
-
-
The All Returned TokenIDs Array
-
STRING Array of all TokenIDs returned in the response.
-
Build Metadata Map Node
The Build Metadata Map node is utilized to parse a NFT Metadata JSON from a TokenID to Metadata Map value into a map of trait/value pairs that can be easily searched.
INPUT:
-
An NFT Metadata JSON formatted as a STRING. These are stored as the Values of the TokenID to Metadata Map output by the Process Metadata node.
OUTPUT:
-
A STRING/STRING Map of the trait/value pairs of the NFT
-
Map Key is the NFT Trait as a STRING
-
Map Value is the Value of that NFT Trait as a STRING
-
Obtaining NFT Metadata Examples
The following is a series of example blueprint snippets that go over some of the various use cases of the Obtaining NFT Metadata primary function.
Get and Process Metadata of an array of Users on an API Key (utilizes a Check Relay Response Loop as detailed below:
Build Array of all NFTs owned by a specific User:
Build Metadata Map of Specific NFT:
Build Metadata Map of all NFTs owned by a specific user:
Build Metadata Map of every returned NFT:
Find the Value of Specific trait in an NFT Metadata Map:
Updating Dynamic Metadata
The Updating Dynamic Metadata primary function is used to alter the trait and value metadata of existing dynamic NFTs. Contact the 0xygen team to discuss the Updating Dynamic Metadata feature, which requires special setup for your metadata storage and retrieval.
Update Metadata Node
The Update Metadata node is utilized to update dynamic NFT metadata to the input values. It creates an Update Relay Object to send this request. Currently, there is no need to receive the response.
INPUT:
-
Special API Key associated with the NFT dynamic collection as a STRING
-
TokenID of the NFT as a STRING
-
Trait Types of the NFT Metadata as an Array of STRINGs
-
Trait Values of the NFT Metadata as an Array of STRINGs
-
NFT Name as a STRING
-
NFT Description as a STRING
-
NFT Image URL as a STRING
-
NFT External URL as a STRING.
OUTPUT:
-
The Update Relay Object that has sent the verification request to the server
Server Communication
Several of the Blueprint Nodes communicate with the Official 0xygen external server. This communication requires two components: Relay + Delay as previously noted in the examples. This section does a deep dive into how these work.
Relay
Server communication utilizes an object called a Relay. A Relay can be thought of as a “Request/Response instance”.
Some Nodes (such as Get Metadata) create a Relay when they make a request to the server. This Relay is a return object of that node.
Other Nodes (Such as Process Metadata) take an existing Relay object as input. They then can access the server’s response to that Relay’s request.
In order to prevent accidental miswiring of non compatible nodes, these relay types do not work with nodes outside of their primary function. The one exception to this is the Check Relay Response node which accepts any Relay type as input.
01
Wallet Verification
Wallet Relay
02
Obtaining NFT Metadata
Metadata Relay
03
Updating Dynamic Metadata
Update Relay
Why Delay?
It takes a bit of time to contact the blockchain, retrieve metadata, and do backend processing. This creates a small delay between the sending of a request and the receipt of its associated response. It is important to ensure a response is received before utilizing its content (otherwise you’ll be working with empty/incorrect data).
There are two methods that can be utilized to help ensure a response is received before it is accessed: the Official 0xygen Check Relay Response node (recommended) and Manual Delay.
Check Relay Response Loop (Recommended)
The Check Relay Response node is utilized to check if a Relay has received a response.
INPUT:
-
A Relay Object that has sent a request to the server
OUTPUT:
-
TRUE if the Relay Object has received a response
-
FALSE if the Relay Object has NOT received a response
The Check Relay Response node is utilized as part of a loop to repeatedly check for a response before moving on to the next node:
The Delay between loops is recommended to be set at 0.5 seconds to balance speed and performance. It should be adjusted/optimized as desired.
Be sure that the Response Received Boolen variable is always set to FALSE before entering the loop.
Manual Delay (Not Recommended)
If desired, developers can simply set a manual delay between the sending of a request and the utilization of its response. This should be used at your own risk as it does NOT guarantee the response has been received before use.
Gamer Account Creation Process:
-
Navigate to: https://www.portal.0xygen.io/register and sign up with a new unique Username, Email, and secure password.
2. User will be prompted to login with the new account then will be taken to a simple dashboard:
3. Clicking the CONNECT TO METAMASK button in the web portal will open a Signature Request in your Metamask browser extension to verify your account.
4. After you or the gamer links a wallet, it will show the wallet address in the simple Dashboard.
The 0xygen Team is here to help and discuss with your team if 0xygen is the right blockchain tool for your project.
Connect with us in our Q and A at our Disord.
Connect with us at the Official0xygen Twitter.
