Skip to content

mintlayer/token-standards

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
mls01
mls01
 
 
mls03
mls03
 
 
README.md
README.md
 
 

Repository files navigation

Token Metadata Standards

This document defines the JSON metadata schemas for tokens on the Mintlayer network.

  • MLS01 — Fungible tokens
  • MLS03 — Non-fungible tokens (NFTs)

Common top-level fields

All token metadata (both MLS01 and MLS03) shares these base fields:

Field Type Description
schema_version string Schema version, e.g. "1.0"
token_type string Discriminator — drives the shape of type_metadata
name string Human-readable token name
symbol string Ticker symbol
description string Short description
logo_uri string Image URI for the token logo
website string Official website
social object Social/community links (twitter, discord, telegram, github, whitepaper)
type_metadata object Type-specific fields — shape varies by token_type
cross_chain array Bridge/cross-chain contract addresses
market object Exchange listings, launch price, data feed IDs
certifications array Third-party certifications (Shariah, ESG, etc.)

MLS01 — Fungible Tokens

token_type values

Value Description Example file
utility General-purpose utility or payment token utility.json
stablecoin Pegged to fiat, commodity, or crypto stablecoin.json
wrapped Wrapped representation of an asset from another chain wrapped.json
governance Token conferring voting rights over a protocol governance.json
lp Liquidity provider token from a DEX pool lp.json
rwa Real-world asset token rwa-bond.json, rwa-real-estate.json, rwa-fund.json, rwa-stock.json, rwa-contract.json
memecoin Community meme token — no utility, fair launch, renounced ownership memecoin.json
commodity Tokenized physical commodity — gold, silver, oil. Redeemable for delivery commodity.json
carbon_credit Fungible verified carbon offset batch. Carries vintage, methodology, retirement flag carbon-credit.json
synthetic Tracks external asset price via oracle. No ownership of underlying synthetic.json
yield_bearing Lending/staking receipt token that accrues interest. Exchange rate increases over time yield-bearing.json
index Market-cap-weighted basket of tokens with monthly rebalancing index.json
fan_token Sports club or creator token with voting on fan decisions and perks fan-token.json
voucher Merchant gift card / coupon redeemable for goods or services voucher.json
insurance DeFi coverage token against smart contract exploits, oracle failures, etc. insurance.json

type_metadata by token type

stablecoin

  • peg.currency — pegged asset (USD, EUR, XAU, BTC)
  • peg.mechanism — fiat_backed | crypto_overcollateralized | commodity_backed | algorithmic | hybrid
  • peg.collateral_ratio — e.g. 1.0 for fully backed
  • peg.issuer — legal entity responsible for reserves
  • peg.reserve_audit_url — link to reserve proof/attestation

wrapped

  • underlying.chain — source chain (e.g. bitcoin, ethereum)
  • underlying.symbol — original asset symbol
  • wrapping_protocol — protocol managing the wrap/unwrap
  • wrapping_ratio — e.g. "1:1"

governance

  • governance.voting_mechanism — token_weighted | quadratic | 1_token_1_vote
  • governance.quorum_threshold — minimum participation to pass a vote
  • governance.proposal_threshold — minimum tokens to submit a proposal
  • governance.timelock_days — delay before execution
  • governance.dao_name / dao_url

lp

  • pool.dex — DEX name
  • pool.address — on-chain pool address
  • pool.fee_tier — e.g. 0.003 for 0.3%
  • pool.tokens — the two assets in the pair

commodity

  • commodity.type — precious_metal | base_metal | energy | agricultural
  • commodity.asset — e.g. gold, silver, crude_oil
  • commodity.unit / units_per_token — e.g. troy_ounce, barrel
  • commodity.grade / purity
  • storage — custodian, locations, insurance, audit frequency
  • redemption — minimum quantity, delivery fee, destination countries
  • price_feed — oracle provider and oracle_uri (URL)

carbon_credit

  • credit.unit — tonne_co2e
  • credit.vintage_year / credit_type (avoidance | removal) / category (e.g. REDD+)
  • project — name, VCS/Gold Standard ID, methodology, location, SDG goals, co-benefits
  • registry — name, standard, serial range, verification body
  • retirement — retired flag, beneficiary, reason — once retired a credit cannot be resold
  • bridge — protocol used to bring the credit on-chain (e.g. Toucan)

synthetic

  • tracks — asset name, ticker, exchange, ISIN, tracking_type, dividends_reflected
  • price_feed — oracle provider, oracle_uri (URL), update frequency, circuit breaker deviation
  • collateral — token, min/safe ratio, liquidation threshold and penalty
  • risk_warnings — array of mandatory disclosures
  • trading_hours — timezone, weekday window, weekend status

yield_bearing

  • underlying — token symbol and address being deposited
  • yield.apy_type (fixed | variable), current_apy, accrual_mechanism (rebasing | exchange_rate)
  • yield.apy_oracle_uri — URL of the APY feed
  • exchange_rate — current redemption rate and oracle_uri (URL)
  • protocol — utilization rate, total supply/borrowed
  • redemption — instant vs delayed, withdrawal fee

index

  • index.methodology — market_cap_weighted | equal_weighted | liquidity_weighted
  • components[] — symbol, address, weight
  • rebalancing — frequency, mechanism (autonomous | governed), last/next date
  • nav — oracle, current NAV in USD
  • protocol.streaming_fee_annual — management fee
  • issuance — mint/redeem contract

fan_token

  • entity — type (sports_club | musician | brand), name, sport, league, country
  • governance.voting_scope[] — list of decisions fans can vote on
  • governance.voting_scope_note — disclaimer on scope limits
  • perks[] — named benefits with descriptions
  • supply — total supply, club reserve vs public split
  • launchpad — platform, initial offering price/date

voucher

  • issuer — legal entity issuing the voucher
  • value — face_value_per_token, currency
  • redeemable_for — description, categories, in_store/online flags
  • acceptance.locations / countries
  • expiry.expires — false for open-ended
  • partial_redemption / combinable / refundable

insurance

  • coverage.against[] — risks covered with descriptions
  • coverage.covered_protocol — name, version, contract address
  • coverage.limit_per_token_usd / payout_token
  • validity — valid_from/until, cooldown period
  • premium — annual rate, token, prepaid vs streaming
  • claims — contract address, assessment body, payout delay
  • pool — total/available capacity, utilization, capital provider APY
  • exclusions[] — what is explicitly not covered

memecoin

  • meme.origin / archetype (animal | person | object | phrase | original)
  • launch.fair_launch, presale, team_allocation_pct, airdrop_pct
  • contract.ownership_renounced, mint_disabled, blacklist_function, pausable
  • liquidity.locked, lock_unlock_date, burned_lp_pct
  • tax.buy_tax_pct / sell_tax_pct
  • social — extended with tiktok, warpcast

rwa — fund sub-type (asset_class: "fund")

  • fund.type — private_credit | private_equity | venture_capital | hedge_fund | money_market | real_estate_fund
  • fund.vintage_year, investment_period_years, fund_life_years, extension_options
  • manager — AUM, regulatory_status per jurisdiction
  • terms — committed/called amounts, nav_per_token, management fee, performance fee, hurdle rate, carried interest
  • liquidity.type (closed_end | open_end), lock-up, secondary market URL, distributions
  • legal.administrator — fund admin entity

rwa — stock sub-type (asset_class: "equity")

  • stock — company name, ticker, exchange, ISIN, CUSIP, tokens_per_share, sector
  • rights.dividends — entitled, pass_through, payment agent
  • rights.voting — typically false; note on proxy voting arrangement
  • issuer_platform — the tokenization platform (separate from the SPV issuer)
  • corporate_actions — splits, dividends, rights issues reflected flag
  • valuation.price_feed_oracle_uri — URL of the real-time price feed

rwa — contract sub-type (asset_class: "receivable")

  • contract.type — royalty_stream | lease | invoice | forward | service_agreement
  • contract.reference, governing_law, effective_date, maturity_date
  • counterparties — obligor (with credit rating), originator, SPV
  • cashflows — total_face_value_usd, payment_frequency, minimum_guaranteed_annual_usd, royalty_rate_of_revenue, payment_schedule[], payment_waterfall[]
  • risk_factors[] — explicit list of deal-specific risks
  • valuation.method: "dcf" — discounted cash flow for contract assets

rwa

  • asset_class — real_estate | bond | equity | commodity | fund | receivable | carbon_credit | ip
  • legal — issuer, custodian, auditor, legal counsel (entity + jurisdiction + registration)
  • jurisdictions — array of { country, regulatory_framework, token_classification, status }
  • transfer_restrictions — KYC requirement, accredited-investor-only, geographic allow/blocklist, lockup
  • rights — yield (fixed/variable), voting, redemption terms
  • valuation — method, last value, frequency
  • documents — array of { type, label, url, hash, date } — hash allows integrity verification

Cross-chain / bridge

"cross_chain": [
  {
    "chain": "ethereum",
    "chain_id": 1,
    "address": "0x...",
    "standard": "ERC20",
    "bridge_protocol": "Mintlayer Bridge",
    "bridge_type": "canonical",
    "verified": true
  }
]

bridge_type:

  • canonical — official deployment controlled by the token team
  • bridged — third-party bridge, not controlled by the issuer
  • wrapped — wrapped version with a different custodian

Market data

"market": {
  "launch_date": "2024-01-15",
  "launch_price_usd": 0.05,
  "exchanges": [
    {
      "name": "Binance",
      "type": "cex",
      "pairs": ["MTK/USDT"],
      "url": "https://...",
      "listed_date": "2024-02-01"
    },
    {
      "name": "Uniswap V3",
      "type": "dex",
      "chain": "ethereum",
      "pairs": ["MTK/USDC"]
    }
  ],
  "coingecko_id": "mytoken",
  "coinmarketcap_id": "12345"
}

Certifications

A general array for any third-party certification. The type field drives the optional shariah_details block.

"certifications": [
  {
    "type": "shariah",
    "label": "Shariah Compliant",
    "standard": "AAOIFI",
    "certifying_body": {
      "name": "Amanie Advisors",
      "jurisdiction": "MY",
      "website": "https://..."
    },
    "reference": "FATWA-2024-007",
    "issued_date": "2024-03-01",
    "expiry_date": "2025-03-01",
    "review_frequency": "annual",
    "status": "active",
    "document_url": "https://...",
    "document_hash": "sha256:...",
    "shariah_details": {
      "screening_standard": "AAOIFI",
      "advisory_board": [
        { "name": "Sheikh ...", "institution": "..." }
      ],
      "prohibited_activities_screened": ["riba", "gharar", "maysir", "haram_sectors"],
      "purification_ratio": 0.02,
      "purification_address": "...",
      "sukuk_structure": "ijara"
    }
  }
]

Other supported type values: esg, halal, carbon_neutral, other.

MLS03 — Non-Fungible Tokens

token_type values

Value Description Example file
art Digital artwork, 1/1 or limited edition art.json
collection Container NFT grouping other NFTs into an ordered series, gallery, strip, album, season, dossier, or portfolio collection.json
collectible Generative or curated collection (PFP, series) collectible.json
gaming In-game item, character, or land gaming.json
rwa Tokenized unique real-world asset rwa-property.json
loyalty_points Loyalty program points batch with expiry and redemption terms loyalty-points.json
club_card Membership card with tier, benefits, and access rules club-card.json
video Video NFT with production metadata and licensing rights video.json
notification_legal On-chain legal notice — court summons, regulatory service of process notification-legal.json
ticket Event access with seat, validity window, and resale rules ticket.json
music Audio NFT with master rights, royalty share, and physical companion music.json
credential Soulbound academic or professional qualification credential.json
domain On-chain domain name with multi-chain resolution records domain.json
supply_chain Physical product provenance record with stage-by-stage audit trail supply-chain.json
pet_passport Animal health and travel document — vaccinations, microchip, vet records pet-passport.json
shariah_certificate On-chain Shariah compliance certificate — institutional, product, fund, or transaction scope shariah-certificate.json

type_metadata highlights (MLS03)

art — edition (number/total), medium (digital | physical_backed), ai_generated, license (CC0/commercial/personal/custom)

collection — collection_type (art_series | gallery | comic_strip | photography_series | anthology | curated), concept, curator (name, role, note), complete, series_order_significant, date_range, exhibitions[] (venue, country, year, section), press[], items[] (ordered list of member NFTs — each with order, token_id, name, image, description), bundle_policy (individual vs bundle pricing), provenance.mixed_custody

loyalty_points — program, points, points_unit, expiry_date, redeemable_for, transfer_policy, soulbound, rollover_policy

club_card — membership.program_name, tier, tier_hierarchy, member_since, valid_until, benefits[], transfer_policy, soulbound, kyc_required

video — media (duration, resolution, codec, audio tracks), production (director, ISRC, festival selections), edition, license (broadcast/streaming/theatrical rights, sublicensable)

notification_legal — notice_type, sender (court/regulator + jurisdiction), recipient, case (reference, type, subject), legal_basis (framework, article, on-chain recognition), timeline (served_at, response_deadline), acknowledgement_required

ticket — event (venue + coordinates, performance datetime), ticket (id, category, zone, seat, perks), validity (valid_from/until, used), resale (allowed, deadline, max price)

music — track (ISRC, ISWC, BPM, key), audio (master format, sample rate, bit depth), rights (master royalty share, sync licensing, streaming revenue share), physical_companion (acetate, claim deadline)

credential — credential_type, issuer (type, accreditation), holder, degree (title, field, ECTS, grade, thesis), verification (W3C VC standard, revocation registry), soulbound

domain — domain (full_name, tld, punycode), registration (expiry, auto_renew), resolution.records[] (ML/BTC/ETH/email/content/url), subdomains_enabled

supply_chain — product (sku, certifications), provenance_chain[] (stage, actor, location, coordinates, date, document_hash), current_custodian, redeemable, redemption (delivers_physical, shipping_destinations)

pet_passport — animal (species, breed, microchip_id), owner, passport (number, regulatory_framework, issuing_vet), vaccinations[] (disease, batch, valid_until), parasite_treatments[], health_certificates[], travel_history[], transfer_requires_vet_update

shariah_certificate — certificate_id (e.g. FDQ-2026-000412), scope (institutional | product | fund | transaction), methodology_version, standard (AAOIFI | IFSB | OIC_FIQH | custom), certifying_body (name, website, registry_address, jurisdiction), subject (type, name, registration_number, jurisdiction), certification_scope (areas[], product_categories[], geographic_coverage[]), screening (prohibited_activities_checked[], financial_ratios_checked, purification_required, purification_ratio), review_process (due_diligence_days, site_visit_conducted, scholars_count, approval_mechanism, evidence_hash, audit_trail_url), scholars[] (name, institution, chapter), multisig_approval (signatories_required, council_size, approval_transaction, approved_at), validity (issued_date, expiry_date, renewal_frequency, status), predecessor_certificate / predecessor_token_id (renewal chain — null for first issuance), documents[] (type: certificate | fatwa | due_diligence_report), soulbound: true

Additional base fields (MLS03 only)

Field Type Description
image string Primary media URI
image_mime_type string e.g. image/png, image/svg+xml
animation_url string Secondary media for video/audio/interactive
animation_mime_type string e.g. video/mp4, audio/mp3
external_url string Link to the asset's page on the issuer's site
attributes array Traits: [{ trait_type, value, display_type? }]
collection object { name, description, symbol, image, total_supply }
creator object { address, royalty_percentage, royalty_address }

About

MLS01 and MLS03 sub-standards

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors