@animoca/f1dt-core_metadata

Core metadata for F1 Delta Time. Usable in node and browser.


License
MIT
Install
npm install @animoca/f1dt-core_metadata@2.2.1

Documentation

F1 Delta Time, Core Metadata library

Core metadata

Core attributes

An F1 Delta Time NFT comes with a number of core attributes embedded within the value of the token identifier. These attributes comprise what we call the token's Core Metadata. There are two main benefits for using this structure:

  1. the core attributes are set at creation and forever immutable,
  2. the tokens can be interpreted on-chain. For example, a contract could provide a service in exchange for a token but only if this token is a Car with a rarity between 7 and 9.

Here is the current list of the core attributes:

Attribute Name Binary Position Data Type Required Season Specific Collection Identifier Description
nonFungibleFlag 255 bit no no yes Used to distinguish fungible and non-fungible tokens. A value of 1 represents a non-fungible token.
padding1 248 uint7 no N/A yes Reserved for later use.
typeId 240 uint8 yes no yes Numerical representation of the type of the token, for example Car, Driver or Gears.
subTypeId 232 uint8 no yes yes Numerical representation of the subType of the token, when applicable. For example Gears have different possible subTypes such as Helmet or Gloves.
seasonId 224 uint8 yes no yes Numerical representation of the season of the token, for example 2019.
padding2 212 uint32 no N/A no Reserved for later use.
trackId 200 uint8 no yes no Numerical representation of the track of the token, for example Circuit de Monaco.
modelId 192 uint8 no yes no Numerical representation of the model of the token, for example Satsuma.
teamId 184 uint8 no yes no Numerical representation of the team of the token, for example Alfa Romeo Racing.
rarity 176 uint8 yes no no The rarity level of the token.
countryId 168 uint8 no yes no Numerical representation of the country of the token, for example Monaco.
labelId 152 uint16 no no no Numerical representation of label of the token. Label are used for specific tokens and is intended to be used for collection and gamfication.
driverId 136 uint16 no no no The driver number for a Driver.
stat1 120 uint16 no yes no The Top Speed of a Car/Part/Tyre or the Stamina of a Driver/Gear.
stat2 104 uint16 no yes no The Acceleration of a Car/Part/Tyre or the Aggression of a Driver/Gear.
stat3 88 uint16 no yes no The Grip of a Car/Part/Tyre or the Concentration of a Driver/Gear.
luck 72 uint16 no yes no The luck of the token.
effect 64 uint8 no yes no The effect of the token.
special1 56 uint8 no yes no The first special of the token.
special2 48 uint8 no yes no The second special of the token.
counter 0 uint48 no yes no Field used to ensure unicity of the tokens in case 2 tokens would have exactly the same other attributes.

Required indicates whether the attribute must have a value different from zero.

Season Specific indicates whether the attribute's interpretation can vary between seasons.

Collection Identifier indicates whether the attribute is part of the collection identifier. Collection identifiers are primarily composed of the typeId, subTypeId and seasonId. For example Car 2019 or Intermediate Tyres 2020.

Some attributes may or may not be needed, depending on the type, subType and season of the token (refer to the season-specific mapping files for more details).

Mapped core attributes

Core attributes are encoded as numerical values. Those which name ends with Id are unmapped and can be mapped to their text value using the mappings contained in this library. For example, typeId 1 can be mapped to the text value Car.

Library usage

module.metadata object

A set of functions which help with the manipulation of token identifiers and metadata objects.

coreMetadataFromId(id) and fullMetadataFromId(id, [network]) functions

Build metadata objects from token identifiers.

const { coreMetadataFromId, fullMetadataFromId } = require('@animoca/f1dt-core_metadata').metadata;

const tokenId = '57897811519642769433138067471762254623735906850517137802921006713614358282351'; // the 1-1-1
const coreMetadata = coreMetadataFromId(tokenId);
console.log(coreMetadata);
const fullMetadata = fullMetadataFromId(tokenId);
console.log(fullMetadata);

idFromCoreMetadata(coreMetadata) function

Build token identifiers from core attributes (mapped and/or unmapped).

const { idFromCoreMetadata } = require('@animoca/f1dt-core_metadata').metadata;
const tokenId1 = idFromCoreMetadata({
    typeId: '1', // Car
    subTypeId: '0',
    seasonId: '2', // 2019
});
const tokenId2 = idFromCoreMetadata({
    typeId: '1', // Car
    subTypeId: '0',
    season: '2019',
});
const tokenId3 = idFromCoreMetadata({
    type: 'Car',
    subTypeId: 'None',
    seasonId: '2019',
});
console.log(tokenId1, tokenId2, tokenId3);
// tokenId1 == tokenId2 == tokenId3

module.constants object

Some project constants such as the bits layout object and the fixed number of bits in the collection identifiers.

module.mappings object

All the mappings necessary to manipulate metadata divided in common mappings and season-specific mappings.

Retrieve the name of a team from its id for season 2019:

const seasonMappings = require('@animoca/f1dt-core_metadata').mappings['2019'];

Retrieve the Tier for a rarity:

module.collections object

The lists of existing collections.

Scripts

Generate metadata from a token identifier

node scripts/metadataFromId.js -i <id> -n <network> [--full]