技术社区分享|Cadence NFT 新标准 MetadataViews 介绍

Created
Feb 22, 2022 10:43 AM
作者
Caos
翻译
/
Tags
Cadence
Metadata
notion image
本文由Flow技术大使Caos撰写。
2022 年 1 月 5 日, Flow NFT 仓库合并了 metadata 的新标准,本次 metadata 标准是由 Versus 与 Find 创始人Bjarte S. Karlsen 和 DapperLabs 工程师 Joshua Hannan 共同在 Flip-Fest 活动中完成,经过了将近三个月的讨论和完善,最终合并至 Flow 官方的 NFT 标准库中,本文将从代码的细节介绍 MetadataView 相关的标准细节。
 
写在前面
  • 本次标准升级是非强制升级的,不会影响 NonFungibleToken 合约,也不会影响原有部署的合约的业务逻辑
  • 已经部署在主网的合约需要升级才能应用新的 Metadata 标准
  • 升级所覆盖的资源会影响到 Collection 继承的类型,也会影响 NFT 资源
  • Metadata 标准定义了一套灵活的接口实现,可以支持任意类型或自定义的 Metadata 格式
  • 支持一个 NFT 拥有多种 Metadata 类型,并提供统一的读取方式
  • Metadata 标准是用一个全新的合约来定义,想要实现标准的合约需要在 NonFungibleToken 之外引入新的名为 MetadataViews 的新合约。
MetadataViews 合约详解
MetadataViews 又两个接口定义和四个推荐的 Metadata struct 组成(后续可能还会增补):
Interface
  • Resolver —— 由 NFT 资源继承
  • ResolverCollection —— 由存储 NFT 集合继承
Struct
  • Display
  • File
  • HTTPFile
  • IPFSFile
■ MetadataViews.Resolver
// A Resolver provides access to a set of metadata views.
//
// A struct or resource (e.g. an NFT) can implement this interface
// to provide access to the views that it supports.
//pub resource interface Resolver {
  pub fun getViews(): [Type]// getViews 返回 NFT 所支持的不同类型的 metadata 数据
  pub fun resolveView(_ view: Type): AnyStruct?// 根据具体的 View 类型获取到 NFT 所实现的 Struct
}
Resolver 需要由 NFT 或 NFT 的数据结构继承,并实现其中定义的两个函数
  • getViews —— 返回数组形式的 View 类型,也是 NFT 所支持的不同类型的 metadata 数据
  • resolveView —— 根据具体的类型,获得 NFT 的 struct 数据
// ExampleNFT// 1. 比原有的实现增加了 MetadataViews.Resolver 接口,并实现了其定义的两个函数pub resource NFT: NonFungibleToken.INFT, MetadataViews.Resolver {
  pub let id: UInt64
// 2. 为实现 MetadataViews.Display 所添加的属性,如果需要实现其他类型的 metadata 需要添加相应的字段  pub let name: String
  pub let description: String
  pub let thumbnail: String

/* init function ... */
  pub fun getViews(): [Type] {
    return [
      Type<MetadataViews.Display>()// 3. 可以定义多个 View 类型
    ]
  }

  pub fun resolveView(_ view: Type): AnyStruct? {
// 4. 根据 view 类型,返回不同的 struct 结构,当然我们也可以自己定义返回结构    switch view {
      case Type<MetadataViews.Display>():
        return MetadataViews.Display(
          name: self.name,
          description: self.description,
          thumbnail: MetadataViews.HTTPFile(
          url: self.thumbnail
        )
      )
    }
    return nil
  }
}
  • 注释一位置我们能看到需要让 NFT 资源实现 MetadataViews.Resolver 接口,实现了其定义的两个函数
  • 注释二位置实现了接口需要 NFT 能够返回指定类型的 Struct ,所以也需要定义返回结构所需要的字段,所以 NFT 增加了 MetadataViews.Display name、description 和 thumbnail
  • 注释三位置getViews 返回一个由类型组成的数组,这里只有一个 MetadataViews.Display 类型,当然我们也可以增加多个类型,比如 File、HTTPFile、IPFSFile,当然也要对应实现其对应的字段。
  • 注释四位置resolveView 会根据传入的 View 类型返回不同的数据结构,如果没有,则直接返回空,所以在编写查询脚本的时候需要先获通过 getViews 获得 NFT 支持的 View 类型,然后根据其支持的类型,调用 resolveView 获得 metadata 数据结构。
 MetadataViews.ResolverCollection
/ A ResolverCollection is a group of view resolvers index by ID.
//
pub resource interface ResolverCollection {
  pub fun borrowViewResolver(id: UInt64): &{Resolver}// 通过 NFT id 获得 Resolver
  pub fun getIDs(): [UInt64]// 获得集合中的 NFT ids
}
ResolverCollection 需要由 Collection 资源继承,并实现其中的两个函数:
  • borrowViewResolver —— 通过具体的 NFT id 获得其支持的 Resolver 可以是任意类型 AnyResource
  • getIDs —— 获得集合中的 NFT ids
// 1. 增加 MetadataViews.ResolverCollection 继承并实现其函数pub resource Collection: ExampleNFTCollectionPublic, NonFungibleToken.Provider, NonFungibleToken.Receiver, NonFungibleToken.CollectionPublic, MetadataViews.ResolverCollection {
  pub var ownedNFTs: @{UInt64: NonFungibleToken.NFT}/* init function and props  */
// getIDs returns an array of the IDs that are in the collection  pub fun getIDs(): [UInt64] {    return self.ownedNFTs.keys  }
/* other function  */// 2. 这里能够返回任意类型的 MetadataViews.Resolver 实现,拥有 getViews 和 resolveView 的方法获得 NFT 的数据  pub fun borrowViewResolver(id: UInt64): &AnyResource{MetadataViews.Resolver} {    let nft = &self.ownedNFTs[id] as auth &NonFungibleToken.NFT    let exampleNFT = nft as! &ExampleNFT.NFT    return exampleNFT as &AnyResource{MetadataViews.Resolver}  }
  destroy() {    destroy self.ownedNFTs  }}
  • 注释一位置: NFT Collection 资源实现 MetadataViews.ResolverCollection 接口,实现了其定义的两个函数:我们一般在查询的时候也是通过获取到用户的 Collection 资源进行详情的查询,包括 getIDs 和获得 Resolver ,后面会在查询接口那里详述。
  • 注释二位置:borrowViewResolver 根据 NFT id 返回任意类型的 View Resolver 中的任意一种类型,其中包含 getViews 与 resolveView 方法
■  View Structs
MetadataViews.Display —— 基础的 metadata 实现,包含 NFT 基本信息
  • name
  • description
  • thumbnail —— 返回任意类型的 File 结构 —— 可以是 HTTPFile 或 IPFSFile
pub struct Display {
// The name of the object.
// This field will be displayed in lists and therefore should
// be short an concise.
  pub let name: String
// A written description of the object.
// This field will be displayed in a detailed view of the object,
// so can be more verbose (e.g. a paragraph instead of a single line).
  pub let description: String
// A small thumbnail representation of the object.
// This field should be a web-friendly file (i.e JPEG, PNG)
// that can be displayed in lists, link previews, etc.
  pub let thumbnail: AnyStruct{File}

  init(
    name: String,
    description: String,
    thumbnail: AnyStruct{File}
  ) {
    self.name = name
    self.description = description
    self.thumbnail = thumbnail
  }
}
MetadataViews.File —— 基础 File 的结构接口,包含 uri 函数返回
// File is a generic interface that represents a file stored on or off chain.
// Files can be used to references images, videos and other media.
pub struct interface File {
  pub fun uri(): String
}
MetadataViews.HTTPFile —— 通过 Http 协议访问的图像 URL 信息
  • 包含 url 信息
// HTTPFile is a file that is accessible at an HTTP (or HTTPS) URL.
pub struct HTTPFile: File {
  pub let url: String

  init(url: String) {
    self.url = url
  }
  pub fun uri(): String {
    return self.url
  }
}
MetadataViews.IPFSFile —— 兼容 IPFS 协议的文件存储,包含 cid 和 path 的返回
  • cid
  • path
// IPFSThumbnail returns a thumbnail image for an object
// stored as an image file in IPFS.
// IPFS images are referenced by their content identifier (CID)
// rather than a direct URI. A client application can use this CID
// to find and load the image via an IPFS gateway.
pub struct IPFSFile: File {
// CID is the content identifier for this IPFS file.
// Ref: <https://docs.ipfs.io/concepts/content-addressing/>
  pub let cid: String
// Path is an optional path to the file resource in an IPFS directory.
// This field is only needed if the file is inside a directory.
// Ref: <https://docs.ipfs.io/concepts/file-systems/>
  pub let path: String?

  init(cid: String, path: String?) {
    self.cid = cid
    self.path = path
  }
// This function returns the IPFS native URL for this file.
// Ref: <https://docs.ipfs.io/how-to/address-ipfs-on-web/#native-urls>
  pub fun uri(): String {
    if let path = self.path {
      return "ipfs://".concat(self.cid).concat("/").concat(path)
    }
    return "ipfs://".concat(self.cid)
    }
}
查询脚本
查询脚本需要进一步的对资源进行类型转换,才能获得基础的 metadata 信息,这里我们以 ExampleNFT 的查询脚本为例
import ExampleNFT from "../../contracts/ExampleNFT.cdc"
import MetadataViews from "./MetadataViews.cdc"

// 1. 定义 NFT 数据的读取结构,为脚本函数的返回值定义类型pub struct NFT {
  pub let name: String
  pub let description: String
  pub let thumbnail: String
  pub let owner: Address
  pub let type: String


  init(
    name: String,
    description: String,
    thumbnail: String,
    owner: Address,
    nftType: String,
  ) {
    self.name = name
    self.description = description
    self.thumbnail = thumbnail
    self.owner = owner
    self.type = nftType
  }
}

// 2. 脚本执行函数,返回之前定义的 NFT 结构,传入地址 + NFT id 参数获取 NFT 数据  pub fun main(address: Address, id: UInt64): NFT {
    let account = getAccount(address)

// 借用用户账户下的 Collection 资源    let collection = account
    .getCapability(ExampleNFT.CollectionPublicPath)
    .borrow<&{ExampleNFT.ExampleNFTCollectionPublic}>()
    ?? panic("Could not borrow a reference to the collection")

// 通过 NFT id 获取到 NFT 资源    let nft = collection.borrowExampleNFT(id: id)!


// Get the basic display information for this NFT// 3. 因为我们的 NFT 已经实现了 MetadataViews.Resolver 接口, 所以这里调用 resolveView 能够获取到具体的 View 类型
    let view = nft.resolveView(Type<MetadataViews.Display>())!

// 将返回的 `AnyStruct` 转换成具体的 struct    let display = view as! MetadataViews.Display// 补充 NFT 所需要的额外信息    let owner: Address = nft.owner!.address!// 获得 NFT 类型    let nftType = nft.getType()

// 返回 NFT 结构    return NFT(
      name: display.name,
      description: display.description,
      thumbnail: display.thumbnail.uri(),
      owner: owner,
      nftType: nftType.identifier,
    )
}
  • 注释一位置:定义了一个 NFT 的数据结构,作为查询脚本的返回值
  • 注释二位置: 通过传入地址和 NFT id 作为参数,查询 NFT 的 metadata,这里需要我们提前知道该地址下所拥有的的 NFT IDs,通过 getIDs 就能获取到当前用户拥有的 NFT ids 然后查询
  • 注释三位置:因为我们的 NFT 已经实现了 MetadataViews.Resolver 接口, 所以这里调用 resolveView 能够获取到具体的 View 类型,在这之前也需要我们知道 NFT 具体实现了哪些 Struct,所以也需要我们通过 getViews 来获取。示例中因假设我们知道 NFT 实现了 MetadataViews.Display,所以使用了强制转换符号 ! 将 AnyStruct 转换成 view as! MetadataViews.Display
在实际使用的过程中,代码也许会更复杂一些,这里只是针对简单的 Example NFT 的实现进行针对性的查询,在整合的过程中还是需要具体的情况做具体的处理。
总结
新版的 Metadata 标准对 NFT 的影响很大,这也是为什么笔者决定特意写一篇介绍的原因,它可以帮助合约开发者、第三方的应用还有基础服务开发者按照统一的接口和规范实现 NFT 资产的数据查询。在以往没有标准的情况下,NFT 资产的多样性会导致查询复杂度提升,基于实现了 MetadataViews 标准的 NFT 合约,能够减轻基于 NFT 资产业务开发的复杂度,降低整合的成本,提高创新业务的开发效率,最重要的是能够让打开 NFT 资产可组合性的空间,类似于 ERC20 标准对 DeFi 的促进一样,Metadata 标准能够在资产可组合性上提供更多的可能。
更多细节可以参考JacobBjarte S. Karlsen现场英文视频讲解。
视频链接:https://www.youtube.com/watch?v=rgJRTozG3cw&t=404s&ab_channel=JacobTucker