Wen Open Lab · 开放集成

第 1 阶段:收据与保修卡12 项检查通过

English · Italiano · 中文 · 한국어

由 Wen 与 AI 一起从英文译出。以英文页面为准;欢迎指正。

Wen 猫的结账收据
每笔订单,一张独一无二的收据

纸质收据会褪色,PDF 可以被编辑,商店的数据库也可能消失。而铸造为 NFT 的收据无法伪造,并始终留在买家手中。这个模型为每笔订单发放一张,完全采用 WNS 引入的代币布局:零位小数、供应量锁定为一、元数据存放在代币本身之中。

任务

给每位顾客一份购买凭证:商店不会弄丢,顾客无法伪造,放在公链上也不泄露任何隐私。还可以选择把保修绑定到这位买家本人,使其无法与购买者分开出售。

模型

  1. 商店用 SHA-256 对订单(编号、商品、价格、日期)计算哈希。只有哈希上链;订单本身留在商店系统和顾客手中。
  2. 创建一个带 Metadata Pointer 扩展的新 Token-2022 铸币,名称、符号、链接和额外字段都存放在铸币内。无需外部元数据账户——这就是 WNS 的做法。
  3. 额外字段:order_hash、warranty_until、sku。
  4. 可选的 Non-Transferable 扩展让收据成为灵魂绑定:保修属于买家,不能转移。
  5. 向买家铸造一枚代币,然后移除铸币权限。供应量永远锁定为恰好一枚。

要核验保修,任何人都可以对顾客出示的订单计算哈希,并与链上的 order_hash 比较。匹配即证明购买;日期字段证明期限。

代码

文件:lab/code/src/01-receipt-nft.ts · Apache-2.0

// Model 1: digital receipt and warranty card as a Token-2022 NFT (the same on-chain layout WNS uses:
// zero decimals, supply locked at 1, metadata stored inside the mint).
// License: Apache-2.0. Example code, not audited. Devnet first.
import {
  Keypair, PublicKey, SystemProgram, Transaction, sendAndConfirmTransaction, type TransactionInstruction,
} from '@solana/web3.js';
import {
  AuthorityType, ExtensionType, LENGTH_SIZE, TOKEN_2022_PROGRAM_ID, TYPE_SIZE,
  createAssociatedTokenAccountIdempotentInstruction, createInitializeMetadataPointerInstruction,
  createInitializeMintInstruction, createInitializeNonTransferableMintInstruction,
  createMintToInstruction, createSetAuthorityInstruction, getAssociatedTokenAddressSync, getMintLen,
} from '@solana/spl-token';
import { createInitializeInstruction, createUpdateFieldInstruction, pack, type TokenMetadata } from '@solana/spl-token-metadata';
import { createHash } from 'node:crypto';
import { getConnection, loadKeypair } from './common.js';

export interface Order {
  orderId: string;
  sku: string;
  priceMinorUnits: number;      // e.g. cents
  currency: string;             // e.g. "USD"
  purchasedAt: string;          // ISO date
  warrantyMonths: number;
}

/** Hash the order so the chain stores proof of purchase, not the customer's personal data. */
export function orderHash(order: Order): string {
  return createHash('sha256').update(JSON.stringify(order)).digest('hex');
}

export interface ReceiptOptions { soulbound: boolean; uri: string }

/** Everything needed to size and build the receipt mint. */
export function receiptLayout(order: Order, mint: PublicKey, merchant: PublicKey, opts: ReceiptOptions) {
  const warrantyUntil = new Date(order.purchasedAt);
  warrantyUntil.setMonth(warrantyUntil.getMonth() + order.warrantyMonths);
  const metadata: TokenMetadata = {
    mint, updateAuthority: merchant,
    name: `Receipt ${order.orderId}`,
    symbol: 'RCPT',
    uri: opts.uri,                                // JSON with public, non-personal details
    additionalMetadata: [
      ['order_hash', orderHash(order)],
      ['warranty_until', warrantyUntil.toISOString().slice(0, 10)],
      ['sku', order.sku],
    ],
  };
  // A soulbound receipt cannot be transferred: good for a warranty tied to one buyer.
  const extensions = [ExtensionType.MetadataPointer, ...(opts.soulbound ? [ExtensionType.NonTransferable] : [])];
  const mintLen = getMintLen(extensions);
  const metadataLen = TYPE_SIZE + LENGTH_SIZE + pack(metadata).length;
  return { metadata, mintLen, rentSpace: mintLen + metadataLen };
}

/** Build all instructions: create mint, store metadata, mint 1 to the buyer, lock supply. */
export function buildReceiptInstructions(args: {
  order: Order; mint: PublicKey; merchant: PublicKey; buyer: PublicKey; opts: ReceiptOptions; rentLamports: number;
}): { instructions: TransactionInstruction[]; buyerAta: PublicKey } {
  const { order, mint, merchant, buyer, opts } = args;
  const { metadata, mintLen } = receiptLayout(order, mint, merchant, opts);
  const buyerAta = getAssociatedTokenAddressSync(mint, buyer, false, TOKEN_2022_PROGRAM_ID);
  const instructions = [
    SystemProgram.createAccount({
      fromPubkey: merchant, newAccountPubkey: mint, space: mintLen, lamports: args.rentLamports, programId: TOKEN_2022_PROGRAM_ID,
    }),
    // Metadata lives inside the mint itself: no external metadata account.
    createInitializeMetadataPointerInstruction(mint, merchant, mint, TOKEN_2022_PROGRAM_ID),
    ...(opts.soulbound ? [createInitializeNonTransferableMintInstruction(mint, TOKEN_2022_PROGRAM_ID)] : []),
    createInitializeMintInstruction(mint, 0, merchant, null, TOKEN_2022_PROGRAM_ID),
    createInitializeInstruction({
      programId: TOKEN_2022_PROGRAM_ID, metadata: mint, updateAuthority: merchant, mint, mintAuthority: merchant,
      name: metadata.name, symbol: metadata.symbol, uri: metadata.uri,
    }),
    ...metadata.additionalMetadata.map(([field, value]) => createUpdateFieldInstruction({
      programId: TOKEN_2022_PROGRAM_ID, metadata: mint, updateAuthority: merchant, field, value,
    })),
    createAssociatedTokenAccountIdempotentInstruction(merchant, buyerAta, buyer, mint, TOKEN_2022_PROGRAM_ID),
    createMintToInstruction(mint, buyerAta, merchant, 1, [], TOKEN_2022_PROGRAM_ID),
    // Lock supply at exactly 1: zero decimals + no mint authority = an NFT, as in WNS.
    createSetAuthorityInstruction(mint, merchant, AuthorityType.MintTokens, null, [], TOKEN_2022_PROGRAM_ID),
  ];
  return { instructions, buyerAta };
}

/** Send on a real cluster (devnet by default). */
export async function mintReceipt(order: Order, buyer: PublicKey, opts: ReceiptOptions) {
  const connection = getConnection();
  const merchant = loadKeypair();
  const mint = Keypair.generate();
  const { rentSpace } = receiptLayout(order, mint.publicKey, merchant.publicKey, opts);
  const rentLamports = await connection.getMinimumBalanceForRentExemption(rentSpace);
  const { instructions, buyerAta } = buildReceiptInstructions({ order, mint: mint.publicKey, merchant: merchant.publicKey, buyer, opts, rentLamports });
  const signature = await sendAndConfirmTransaction(connection, new Transaction().add(...instructions), [merchant, mint]);
  return { mint: mint.publicKey.toBase58(), buyerAta: buyerAta.toBase58(), signature };
}

已验证的内容

在 LiteSVM 中,对灵魂绑定版和可转让版分别验证:收据被铸造;供应量恰为 1、小数位为 0、无铸币权限;名称、订单哈希和保修日期可从铸币内部读回;买家持有它;灵魂绑定收据拒绝转移(由 Token-2022 本身拒绝),可转让收据可以赠送或转售;且任何人都无法铸造第二份。见核验记录。

视频 01/10:30 秒看懂一张无法伪造的收据。播放器只会在你点击播放后才从 YouTube 加载。

用在哪里

  • 电子产品和家电:无纸化保修索赔。
  • 限量商品和收藏品:从首次销售起的来源证明。
  • 二手市场:可转让收据向下一任主人展示物品的来历。
  • 会员计划:收据本身就是会员卡。

局限与风险

  • 每张收据都需要租金(少量 SOL 押金)和网络费。大批量时请批处理或压缩。
  • 切勿把个人数据(姓名、地址、电话)写进元数据:链是公开且永久的。
  • 哈希只能证明商店所哈希的内容。开始前请约定固定的订单格式。
  • 买家需要一个钱包。面向大众零售时,请规划托管钱包或嵌入式钱包方案。

图说 Wen

持有购买凭证的 Wen 顾客
钱包里的购买凭证
带保修卡的 Wen 玩具
随物品一起流转的保修
Wen 毛绒玩具系列的收据
实物商品,数字凭证
Solana 上的 Wen 购物清单
从购物车到链上
认识一下 Wen,收据守护者
忠诚始于一张收据

Wen 在此模型中的位置

商店可以用少量 WEN 小费或忠诚度奖励回馈持有其收据 NFT 的顾客,也可以通过第 4 阶段在结账时接受 WEN。收据本身采用因 Wen 而闻名的 WNS 布局:第一个 WNS NFT 就是 Meow 的诗,而同样的结构如今承载着购买凭证。

Wen 的主线:一个合约,处处可见

实验室的每个模型都免费且开放,并带着同一个签名:$WEN 代币合约。复制它,在你自己的文档中重复它,使用前务必在浏览器上核验。

WENWENvqqNya429ubCdR81ZmD69brwQaaBYY6p3LCpk

核验:Solana Explorer · 如何找到合约 ID

开放使用政策

  • 免费且开放。实验室的全部代码以 Apache License 2.0 发布,与 Wen Program Library 相同。无论是否商用,都可以使用、修改、发布;请保留许可声明。
  • 只用开放工具。基于公开且有文档的工具构建:Solana SPL Token-2022(Token Extensions)、Wen New Standard(WNS)的代币布局、Solana Pay,以及用于本地测试的 LiteSVM。
  • 规则:始终核验你自己的模型。运行测试,从 devnet 开始,阅读官方文档,检查每个账户和金额,并在任何主网使用之前获得独立审计。未经核验的模型不是模型,而是猜测。
  • 未经审计,不构成建议。这些是教学示例,不构成金融、法律或税务建议,也不是持牌的支付或银行产品。在大多数国家,支付、稳定币和收单都是受监管的活动。
  • 安全。切勿把私钥粘贴到任何网站。不要安装 npm 包 @wen-community/wen-new-standard:npm 已因恶意将其移除。请从官方来源构建。

由 Wen 为社区讲述。更多内容见我们的编辑与数据政策。

Wen Open Lab · 路线图 · 全部代码 · GitHub 上的 Wen Program Library

Wen 在星舰机库里检查货箱,机器人在装箱
每个货箱都有自己的收据:一张灵魂绑定的保修卡,留在买家钱包里,无法伪造。