Cardano NFT Minter 插件使用教程

🌟 插件简介

Cardano NFT Minter 是一款功能强大的 WordPress 插件，专门为 Cardano 区块链生态系统设计。它让你能够直接在 WordPress 网站上为用户提供完整的 NFT 操作功能，无需任何区块链开发经验。

核心功能一览

1. 系统要求与准备工作 📦

1.1 WordPress 环境要求

• WordPress 版本：5.0 或更高
• PHP 版本：7.4 或更高
• HTTPS：必须启用（钱包连接需要安全连接）

1.2 必需的外部服务账户

在开始使用插件前，你需要准备以下服务的 API 密钥：

1.3 支持的 Cardano 钱包

插件支持所有主流的 CIP-30 兼容钱包：

• 🦊 Nami - 轻量级热门钱包
• 🌙 Eternl - 功能丰富的高级钱包
• ♠️ Flint - 多链支持钱包
• 💎 Lace - IOG 官方开发的钱包
• 🐯 Yoroi - Emurgo 官方钱包
• 🌊 Typhon - 全功能 DeFi 钱包
• ⚡ Gero Wallet - 移动端友好钱包
• 🔮 NuFi - 多功能钱包

💡 提示：建议用户在测试网（Preprod）上进行充分测试后再切换到主网使用。

2. 安装与激活 🛠️

2.1 上传插件文件

将完整的插件文件夹上传到你的 WordPress 安装目录：

/wp-content/plugins/cardano-nft-minter/ 

确保文件结构如下：

cardano-nft-minter/
├── cardano-nft-minter.php      (主插件文件)
├── includes/
│   ├── class-admin.php         (后台管理)
│   ├── class-rest-api.php      (REST API 接口)
│   └── class-shortcode.php     (短代码处理)
├── assets/
│   ├── js/
│   │   ├── minter.js           (铸造前端逻辑)
│   │   ├── sender.js           (发送前端逻辑)
│   │   ├── burner.js           (销毁前端逻辑)
│   │   └── cardano-pure-builder.js (交易构建器)
│   └── css/
│       ├── minter.css │       └── burner.css └── templates/
    ├── minter-template.php     ├── sender-template.php     └── burner-template.php 

2.2 激活插件

1. 登录 WordPress 后台
2. 进入 「插件」→「已安装的插件」
3. 找到 Cardano NFT Minter 并点击 「启用」

2.3 数据库初始化

插件激活时会自动创建一个数据表 wp_cardano_nft_mints，用于记录所有 NFT 铸造历史，包含以下字段：

• 用户 ID 和钱包地址
• 交易哈希（TX Hash）
• Policy ID 和资产名称
• 元数据（JSON 格式）
• IPFS 哈希
• 状态（pending/confirmed/failed）
• 网络（mainnet/preprod/preview）
• 创建时间和确认时间

3. 后台配置详解 ⚙️

激活后，在 WordPress 后台左侧菜单会出现 「Cardano NFT」 选项。

3.1 仪表盘概览

进入 「Cardano NFT」 主页面，你可以看到：

• 📊 统计卡片：总铸造数、已确认数、待确认数
• 🌐 当前网络：显示当前配置的 Cardano 网络
• ✅ 配置状态：Blockfrost 和 Pinata 的连接状态
• 📝 可用短代码：快速参考所有可用的短代码

3.2 API 配置

进入 「Cardano NFT」→「Settings」 进行 API 配置：

🔗 网络选择

⚠️ 重要提示：网络设置必须与用户钱包当前连接的网络一致，否则会显示网络不匹配错误。

🔑 Blockfrost API 配置

1. 访问 blockfrost.io 并注册账户
2. 创建新项目，选择对应的网络（Mainnet 或 Preprod）
3. 复制生成的 Project ID
4. 粘贴到对应的输入框中

配置项说明：

• Blockfrost Mainnet Project ID：主网 API 密钥
• Blockfrost Preprod Project ID：测试网 API 密钥

💡 建议：同时配置两个网络的 API 密钥，方便随时切换。

📌 Pinata IPFS 配置

1. 访问 pinata.cloud 并注册账户
2. 进入 API Keys 页面
3. 创建新的 API Key，选择 Admin 权限
4. 复制生成的 JWT Token（注意：这是一个很长的字符串，通常超过 1000 个字符）
5. 粘贴到 Pinata JWT Token 输入框

⚠️ 注意：JWT Token 是一个非常长的字符串，请确保完整复制，不要遗漏任何字符。

3.3 收藏品设置

📁 Collection Name（收藏品名称）

为你的 NFT 系列设置一个统一的名称，此名称会自动添加到所有铸造的 NFT 元数据中。

💰 版税设置（CIP-27）

插件支持 CIP-27 版税标准，允许你在 NFT 二次销售时获得版税收入：

• Royalty Address：接收版税的 Cardano 钱包地址
• Royalty Percentage：建议的版税比例（如 5 表示 5%）

📖 CIP-27 说明：这是一个建议性标准，实际版税支付取决于市场平台是否遵循此标准。

4. NFT 铸造功能 🖼️

4.1 功能概述

NFT 铸造模块允许用户通过简单的表单界面在 Cardano 区块链上铸造 NFT。

支持的功能：

• ✅ 单个 NFT 铸造
• ✅ 批量 NFT 铸造（同一策略下多个 NFT）
• ✅ 空投铸造（铸造并直接发送到指定地址）
• ✅ 自定义属性（Traits）
• ✅ CIP-25 元数据标准
• ✅ CIP-27 版税标准（可选）

4.2 策略脚本类型

插件支持两种类型的原生脚本（Native Script）：

Policy ID 模式

• Unique（唯一）：每次铸造生成新的 Policy ID（通过添加时间锁实现）
• Reusable（可复用）：相同签名的铸造共享同一个 Policy ID

4.3 铸造流程详解

步骤一：连接钱包

1. 用户访问包含铸造短代码的页面
2. 系统自动检测已安装的 Cardano 钱包扩展
3. 用户点击选择要使用的钱包
4. 在钱包中确认连接请求
5. 连接成功后显示钱包地址和 ADA 余额

步骤二：填写 NFT 信息

步骤三：配置策略

1. 选择 Policy ID Mode（唯一或可复用）
2. 选择 Policy Type（签名或时间锁）
3. 如选择时间锁，设置 Policy Expiry（过期时间，以小时计）
4. 设置 Mint Quantity（铸造数量）
5. 可选：启用 CIP-27 Royalty

步骤四：执行铸造

1. 点击 「Mint NFT」 按钮
2. 等待图片上传到 IPFS（如已配置 Pinata）
3. 系统构建交易
4. 在钱包中签名确认交易
5. 交易提交到区块链
6. 等待确认，查看结果

4.4 批量铸造

对于需要同时铸造多个 NFT 的场景：

1. 启用 Batch Mode 开关
2. 填写第一个 NFT 的信息
3. 点击 「Add to Batch」 添加到队列
4. 重复以上步骤添加更多 NFT
5. 在批量队列中确认所有 NFT
6. 点击 「Mint Batch」 一次性铸造所有 NFT

💡 费用优化：批量铸造在单笔交易中完成，相比多次单独铸造可节省交易费用。

4.5 空投铸造

结合批量铸造和空投功能，可以实现铸造并直接发送到指定地址：

1. 启用 Batch Mode 和 Airdrop Mode
2. 上传 CSV 文件，格式为每行一个地址
3. 添加 NFT 到批量队列（数量应与地址数量匹配）
4. 系统自动将 NFT 配对到对应地址
5. 执行铸造，NFT 直接发送到目标钱包

5. NFT 发送功能 📤

5.1 功能概述

NFT 发送模块允许用户将钱包中的 NFT 批量发送到多个地址，非常适合：

• 🎁 NFT 空投活动
• 🏆 社区奖励分发
• 🔄 NFT 批量转移

5.2 发送流程

步骤一：连接钱包并加载 NFT

1. 连接 Cardano 钱包
2. 系统自动加载钱包中的所有 NFT
3. 在 NFT 列表中点击选择要发送的 NFT

步骤二：配置收件人

手动模式：

1. 点击 「Add Recipient」 添加收件人条目
2. 从下拉列表选择要发送的 NFT
3. 输入收件人的 Cardano 地址
4. 重复以上步骤添加更多收件人

CSV 模式：

1. 切换到 CSV 标签

2. 准备 CSV 文件，格式如下：

   csv

   address,policyId,assetName
   addr_test1...,abc123...,MyNFT001
   addr_test1...,abc123...,MyNFT002

3. 上传 CSV 文件
4. 预览并确认发送列表

步骤三：确认并发送

1. 查看摘要信息（NFT 数量、预估费用）
2. 点击 「Send NFTs」 按钮
3. 在钱包中签名确认
4. 等待交易确认

5.3 费用估算

发送 NFT 的费用包括：

• 交易费：约 0.2 ADA（基础费用）+ 0.005 ADA × NFT 数量
• 最小 UTXO：每个接收输出约 1.2 ADA（这部分发送给收件人）

6. NFT 销毁与置换功能 🔥

6.1 功能概述

Burn & Swap 功能允许用户在单笔交易中同时销毁旧 NFT 并铸造新 NFT，这是一项高级功能，适用于：

• 📈 NFT 版本升级
• 🔄 系列迁移
• 🎨 艺术品更新
• 🎮 游戏道具进化

6.2 可销毁性判断

并非所有 NFT 都可以销毁。NFT 是否可销毁取决于其铸造策略：

6.3 Burn & Swap 流程

步骤一：连接钱包并选择 NFT

1. 连接 Cardano 钱包
2. 系统加载钱包中的所有 NFT，并标注可销毁状态
3. 点击可销毁的 NFT 添加到销毁队列
4. 不可销毁的 NFT 点击时会显示原因提示

步骤二：配置新 NFT

自动模式（推荐）：

• 设置 Name Prefix（名称前缀）
• 设置 Name Suffix（名称后缀）
• 例如：原名 "MyNFT" → 新名 "MyNFT_V2"

手动模式：

• 为每个被销毁的 NFT 单独指定新名称

可选设置：

• 上传新图片（所有新 NFT 使用同一图片）
• 选择新 NFT 的策略类型
• 启用版税设置

步骤三：确认并执行

1. 查看摘要：销毁列表、铸造列表、费用估算
2. 点击 「Execute Burn & Swap」 按钮
3. 弹出确认对话框，显示详细信息
4. 点击 「Confirm Burn & Swap」 确认
5. 在钱包中签名
6. 等待交易确认

6.4 费用与退款

Burn & Swap 的费用计算：

• 新 NFT 成本：约 1.5 ADA × 新 NFT 数量
• 销毁退款：约 1.5 ADA × 销毁 NFT 数量（返还锁定的最小 ADA）
• 净费用：约 0.3 ADA（主要是交易手续费）

💡 经济优势：由于销毁 NFT 会返还其锁定的最小 UTXO，实际净费用非常低。

7. 短代码使用指南 📝

7.1 可用短代码

7.2 参数说明

通用参数

Minter 专属参数

7.3 使用示例

基础铸造页面：

[cardano_nft_minter]

允许游客使用的铸造页面：

[cardano_nft_minter require_login="false"]

不显示历史的铸造页面：

[cardano_nft_minter show_history="false"]

批量发送/空投页面：

[cardano_nft_sender]

游客可用的发送页面：

[cardano_nft_sender require_login="false"]

NFT 销毁与置换页面：

[cardano_nft_burner]

游客可用的销毁页面：

[cardano_nft_burner require_login="false"]

8. CIP 标准支持 📜

插件遵循 Cardano 改进提案（CIP）标准，确保铸造的 NFT 具有良好的兼容性：

8.1 CIP-25 元数据标准

所有铸造的 NFT 都遵循 CIP-25 元数据标准，结构如下：

{
  "721": {
    "<policy_id>": {
      "<asset_name>": {
        "name": "NFT Name",
        "image": "ipfs://Qm...",
        "mediaType": "image/png",
        "description": "Description text",
        "collection": "Collection Name",
        "<custom_trait>": "<value>"       }
    }
  }
}

注意事项：

• 超过 64 字节的字符串会自动分割成数组（CIP-25 要求）
• 图片使用 ipfs:// 协议链接

8.2 CIP-27 版税标准

当启用版税功能时，元数据会包含版税信息：

{
  "777": {
    "<policy_id>": {
      "rate": "0.05",
      "addr": "addr1..."     }
  }
}

• rate：版税比例（如 "0.05" 表示 5%）
• addr：接收版税的地址

8.3 CIP-30 钱包连接

插件使用 CIP-30 标准与钱包交互，支持：

• enable() - 连接钱包
• getNetworkId() - 获取网络
• getUsedAddresses() - 获取地址
• getBalance() - 获取余额
• getUtxos() - 获取 UTXOs
• signTx() - 签名交易
• submitTx() - 提交交易

9. 常见问题解答 ❓

Q1：钱包连接失败怎么办？

可能原因与解决方案：

1. ❌ 网站未启用 HTTPS
   • ✅ 解决：配置 SSL 证书，使用 https:// 访问
2. ❌ 钱包网络不匹配
   • ✅ 解决：确保钱包网络与插件配置一致（都是 Mainnet 或都是 Preprod）
3. ❌ 浏览器扩展未授权
   • ✅ 解决：检查钱包扩展权限设置

Q2：IPFS 上传失败？

检查步骤：

1. 确认 Pinata JWT Token 已正确配置（应超过 1000 字符）
2. 检查文件大小是否超过 50MB 限制
3. 确认文件类型是否支持（PNG、JPG、GIF、WebP、SVG、MP4、MP3、WAV）
4. 检查 Pinata 账户是否有足够的存储配额

Q3：交易提交失败：ValueNotConserved？

原因：交易输入输出不平衡

解决方案：

1. 刷新页面重新获取 UTXOs
2. 检查 ADA 余额是否充足（至少需要 3 ADA）
3. 如使用批量铸造，尝试减少每批 NFT 数量

Q4：为什么我的 NFT 无法销毁？

可能原因：

Q5：如何获取测试网 ADA（tADA）？

访问 Cardano Testnet Faucet：

• Preprod：testnets.cardano.org/en/testnets/cardano/tools/faucet/

输入你的测试网钱包地址即可获取免费 tADA。

10. 故障排除 🔧

10.1 开发者调试

打开浏览器开发者工具（F12），查看 Console 标签页获取详细错误信息。

常见错误代码：

10.2 日志位置

• 前端日志：浏览器 Console
• 后端日志：WordPress 调试日志（需启用 WP_DEBUG）

10.3 联系支持

如遇到无法解决的问题，请收集以下信息后联系开发者：

1. WordPress 版本和 PHP 版本
2. 使用的钱包类型和版本
3. 配置的网络（Mainnet/Preprod）
4. 完整的错误信息（Console 截图）
5. 操作步骤复现描述

🎉 总结

恭喜你完成了 Cardano NFT Minter 插件的学习！现在你可以：

• ✅ 在 WordPress 网站上铸造 Cardano NFT
• ✅ 批量发送和空投 NFT
• ✅ 执行 NFT 升级和置换
• ✅ 遵循 CIP-25 和 CIP-27 标准
• ✅ 支持多种主流 Cardano 钱包

📚 延伸阅读

• CIP-25 NFT Metadata Standard
• CIP-27 CNFT Community Royalties
• CIP-30 Wallet Connector
• Blockfrost API Documentation
• Pinata IPFS Documentation

🔗 相关资源

• Cardano 官方文档：docs.cardano.org
• Blockfrost 控制台：blockfrost.io
• Pinata 控制台：pinata.cloud
• CardanoScan 区块浏览器：cardanoscan.io