DMint 发行指南

Atomicals NFT Container DMint 集合上链教程

名词解释

概述

此教程旨在让项目方快速了解如何在 Atomicals 协议上链 DMint NFT 合集。在 Atomicals 协议上,NFT 合集称为 container,与 NFT collection 大致同等意思。

流程大致分为四大块:

  1. 准备合集的所有数据

  2. 配置 container

  3. 校验 NFT item

  4. 铸造 NFT item

其中作为项目方需要关注 1、2、3 步。

💰 步骤前有 ⛓️ 图标代表该操作上链,需要消耗gas。

准备合集数据

  1. 准备所有 NFT 的数据 (A1, A2......AN)

  2. 准备合集的 dmint 数据 B

  3. 准备合集的其他元数据 C

  4. 用命令行工具本地创建一个新钱包用于隔离所有的 container 操作,避免混乱。

配置 Container

  1. ⛓️ Mint container

  2. ⛓️ 使用合集的数据 B 配置 dmint

  3. ⛓️ 配置其他元数据 C

  4. ⛓️ 所有信息确认后封闭**(最后一步!最后一步!)**

校验 NFT item

  1. 已有 item 数据、Container 已上链且配置 dmint,单独使用 NFT 的数据 A 校验 item 是否与 Container 匹配

  2. Container 已封闭,可获取单个 item 的mint 情况和已 mint 的列表

Mint NFT item

  1. ⛓️ 下载 NFT 数据 A 并使用官方命令行工具进行本地 mint

📌 为了方便你区分不同的文件,我们通过大写英文标识把它们标识了出来。请在每一步操作时留意对应文件。错误的文件可能导致非预期的链上数据。

可以从上述大致步骤中看出,项目方不需要将 NFT 逐个上传到链上,而只需要用户在 Mint 时自行校验并承担其 gas 成本。


操作流程

以下操作均基于 atomicals-js 命令行工具 0.1.46 版本 (@aa34095c)。官方会不定时更新版本,因此操作前请先检查本地 CLI 是否为最新版本或者可用版本。安装和配置请参考:https://github.com/atomicals/atomicals-js#install,过程对于某个命令有疑问请在输入时加上 -h 获取帮助内容。

💡 为了避免操作过程出现失误和预期外的错位,推荐先通过测试网测试全部流程后再进行正式网的任何操作。

❗ 每一步需要往指定地址转账时,请确保只转同样数量的 sats,因为工具不支持找零,会将整个 UTXO 使用掉。

❗ 每一步包含 #container-name 的内容即为 container 名字,必须以 # 开头,否则某些命令会识别出其他类型的 Atomicals。

💰 每一步带有 --satsbyte 的命令的值请自行根据链上 gas 情况填写。


准备合集数据

  1. 准备好一个文件夹,里面放置所有的 NFT 原始文件(图片)。建议提前更改好文件名(例如“序号.png”:“1234.png”),减少之后修改数据的可能性和复杂度。文件名只支持数字和英文以及半角横杠(-且不能以 - 开头),最多64位。

  2. 运行命令生成所有 NFT 的加工数据,完成后会生成新的文件夹。

$ yarn cli prepare-dmint-items "path/to/collection-folder" "path/to/output-folder"
  1. 生成的文件夹为 "output-folder" 加 -时间戳,内有每一个 NFT 对应的 item-*.json。注意此时生成的数据只有 mainHashdata 字段。如果有需要,你可以在 args 中指定 bitworkc/bitworkr,修改后在用户 mint 时会要求使用你声明的 bitwork。

{
  "mainHash": "0099ad5961eff12096b851d9701bedfe09ec3433dad89857bcaddc5ea2172c98",
  "data": {
    "args": {
      "request_dmitem": "test-1",
      "main": "image.jpg",
      "i": true
    },
    "image.jpg": {
      "$b": "ffd8ffe000104a4649460001010100600060000ffd9"
    }
  }
}
  1. 运行以下命令生成 dmint 数据,path/to/folder 为第2步生成的文件夹路径,mintHeight 为起始铸造的区块高度(参考值 0 即发布后即可 mint)。完成后文件夹内会新增一个 "dmint-时间戳.json",同时所有的 NFT 加工数据都会更新。

yarn cli prepare-dmint "path/to/folder" bitworkc "b1d0"
{
  "dmint": {
    "v": "1",
    "mint_height": 0,
    "merkle": "5c529dacfb37fc24804c550abc851602a9926016a424390387eb23e38de4cca1",
    "immutable": true,
    "rules": [
      {
        "p": ".*",
        "bitworkc": "7baf"
      }
    ]
  }
}
{
  "mainHash": "0099ad5961eff12096b851d9701bedfe09ec3433dad89857bcaddc5ea2172c98",
  "data": {
    "args": {
      "request_dmitem": "test-1",
      "main": "image.jpg",
      "i": true,
      "proof": [
        {
          "p": true,
          "d": "3212c74b3b5083433a8111f80369d8c591711c577e45dacb8ccaf7960d96790f"
        }
      ]
    },
    "image.jpg": {
      "$b": "ffd8ffe000104a4649460001010100600060000ffd9"
    }
  },
  "targetVector": "test-1:any:any:image.jpg:0099ad5961eff12096b851d9701bedfe09ec3433dad89857bcaddc5ea2172c97",
  "targethash": "0099ad5961eff12096b851d9701bedfe09ec3433dad89857bcaddc5ea2172c98"
}

❗ 每一次运行 prepare-dmint 都会生成新的 dmint-时间戳.json 文件,而不是修改旧的。请注意不要使用错误的数据进行后续操作。

  1. 你可以修改 dmint 的 bitwork 规则,在 rules 中的 p 代表 Pattern,即可以用正则来指定不同的 bitworkc。请参考可搜索到的正则表达式资料编写规则。在下方的例子中,举例:

{
  "dmint": {
    "v": "1",
    "mint_height": 0,
    "merkle": "5c529dacfb37fc24804c550abc851602a9926016a424390387eb23e38de4cca1",
    "immutable": true,
    "rules": [
      {
        "p": "1$",
        "bitworkc": "890a"
      },
      {
        "p": ".*",
        "bitworkc": "7baf"
      }
    ]
  }
}

此处 1$ 的规则代表以 1 结尾(比如 test1)的 item 的 bitworkc 需要是 890a,而其他 item(比如 test)则是 7baf。规则按照最小子集(最特殊的规则)到全集(最通用的规则)的顺序排序。

❗ 如果你为 item 单独设置了 bitworkc/bitworkr,你需要手动在 rules 中声明对应的模式和规则,否则它们与基础规则之间是互相矛盾的,正式封闭发布后将无法 mint。工具对此也没有任何提示,修改时请务必小心操作。

  1. 如果你修改了 item 数据,确保每次修改后都重新执行了第4步的命令重新生成。

  2. 从工具目录下的 template/containers/dmint-collection-general-dmint-metadata.json 或者 https://github.com/atomicals/atomicals-js/blob/master/templates/containers/dmint-collection-general-metadata.json 拷贝出一份元数据 dmint-metadata.json,根据自己的内容进行调整。

❗ 该部分可以参考 官方文档 编写,但是请不要声明 attrsitems,对于 dmint 而言它们是错误内容,会导致无法封闭 container。


配置 Container

  1. ⛓️ mint 指定的 container。如果要指定不同的接收地址,请将 "yourWalletAddress" 替换为对应的钱包地址。

$ yarn cli mint-container "#container-name" --initialowner "yourWalletAddress" --satsoutput=1000 --bitworkc="b6cf" --satsbyte=1
  1. ⛓️ 通过之前生成的 dmint-时间戳.json 启用 container 的 dmint 状态。"dmint-json-path.json" 需要替换数据 B【准备合集数据-第2步生成的】文件路径。

❗ 需要等【配置 Container-第1步】完成后的 4 个区块确认(变成 verified 状态)才能操作。你可以在此查询 container 状态:https://wizz.cash/explorer,输入 revealTxid 即可。

$ yarn cli enable-dmint "#container-name" "dmint-json-path.json" --satsbyte=1
  1. ⛓️ 将准备用于 container 封面的资源文件上链,先把文件名改为“logo.png”(图片推荐使用 png、jpg 或 svg 格式),然后执行下述命令即可。

$ yarn run cli store-file "path/of/your_logo.png" "logo.png" --satsbyte=1

......
filesData {
  'logo.png': <Buffer 89 50 4e 47 0d 0a 1a 0a 00 00 00 0d 49 48 44 52 00 00 00 18 00 00 00 18 08 06 00 00 00 e0 77 3d f8 00 00 00 9d 49 44 41 54 78 da 63 60 18 05 54 04 ff ... 164 more bytes>
}
Payload CBOR Size (bytes):  235
Payload Encoded:  {
  'logo.png': <Buffer 89 50 4e 47 0d 0a 1a 0a 00 00 00 0d 49 48 44 52 00 00 00 18 00 00 00 18 08 06 00 00 00 e0 77 3d f8 00 00 00 9d 49 44 41 54 78 da 63 60 18 05 54 04 ff ... 164 more bytes>
}

...
Success sent tx:  f26bbf1833d6af0ca533cfdd7401f8074375490120164e6d0a680aca4bacf7af
{
  "success": true,
  "data": {
    "commitTxid": "c931d7a337eef91f5f6f2b3430c78aaac0e7f11752e15576a1a4881b344457c5",
    "revealTxid": "f26bbf1833d6af0ca533cfddbbb1f8074375490120164e6d0a680aca4bacf7af",
    "dataId": "f26bbf1833d6af0ca533cfdd7401f8074375490120164e6d0a680aca4bacf7afi0"
  }
}
  Done in 81.41s.

完成后我们使用文件名和输出的 dataId,拼接为:atom:btc:dat:{dataId}/logo.png,并作为 image 字段填入元数据 C【准备合集数据-第7步生成的】文件里。

{
  "name": "container-name",
  "desc": "A test container."
  "image": "atom:btc:dat:1a29d1ed20c36a95f6b5c20977a5f1035cc0cd5f55327692149a5710d1d75e9bi0/logo.png",
  ...
}
  1. ⛓️ 修改好元数据 C 后,将其设置到 container。

$ yarn cli set-container-data "#container-name" "path/to/container-dmint-metadata.json" --satsbyte=1
  1. 执行封闭 container 的命令。

此操作不可逆! 在封闭前,请先完成【校验 NFT item】中的验证 item 的操作。确保所有的 item 都已经被校验过且都正确。

$ yarn cli seal "#container-name" --satsbyte=1

校验 NFT item

由于 Merkle 验证的特殊性,我们不需要将每一个 NFT 都提前上链,只需要验证它们是否与 container 匹配即可。在 container 的不同状态或者生命周期里,你可以使用不同的方法来验证 NFT item 的有效性。

  • 要验证某一个 item 是否有效,你需要 container 的名字、item 的名字及【准备合集数据-第2步生成的】json 文件:(path/to/item-3.json 替换为 item 的文件路径)

$ yarn cli validate-container-item "#container-name" "test-item-3" "path/to/item-3.json"
  • 其结果会返回以下内容,proof_validtrue 则代表验证通过,applicable_rule 返回了完整的规则则代表规则配置正确:

{
  "success": true,
  "response": {
    "result": {
      "status": null,
      "candidate_atomical_id": null,
      "atomical_id": null,
      "candidates": [],
      "type": "item",
      "applicable_rule": {
        "p": ".*",
        "bitworkc": "a91b"
      },
      "proof_valid": true,
      "target_vector": "test-item-3:any:any:image.jpg:3b0bcfe26b7521e83e595f5838d04ea25a45931a849ab5f0db134eb9a4a7cec2",
      "target_hash": "8d800be8cb6b418d986a99b9d2fd23994fa712f3c76ef9a3c8306298d2af2ba4",
      "dmint": {
        "v": "1",
        "rules": [
          {
            "p": ".*",
            "bitworkc": "a91b"
          }
        ],
        "merkle": "b68ace0edff5f81a92acc57e493d6d3cfa7cfc038bfe0397dfb81d082bd3b9d0",
        "immutable": true,
        "mint_height": 0
      }
    }
  }
}

❗ 建议每一个 item 都进行验证,确保全部数据的有效性。

Mint NFT item

Container 发布后,用户可以在能获取到 item 的 json 文件的情况下,使用命令行工具对对应的 NFT 进行 mint。

$ yarn cli mint-item "#container-name" "item-name" "path/to/item-name.json" --satsbyte=1

可选操作

在 container 已经封闭,即可以开始让用户 mint。在已经有 item 被 mint 的情况下:

查询单个 item 的状态

get-container-item

$ yarn cli get-container-item "#container-name" "test-item-4"

查询已 mint 的 item

get-container-items 查询已 mint 的 item(limit 条目数量,参考值 10offset 从哪一条开始查询,参考值 0)。

$ yarn cli get-container-items "#container-name" limit offset

Last updated