Wen Open Lab · integrazione aperta

Fase 1: ricevute e certificati di garanzia12 verifiche superate

English · Italiano · 中文 · 한국어

Tradotto dall’inglese da Wen insieme all’AI. Il riferimento è la pagina inglese; le correzioni sono benvenute.

Il gatto Wen e la ricevuta alla cassa
Ogni ordine, una ricevuta unica

Una ricevuta di carta sbiadisce, un PDF si può modificare e il database di un negozio può sparire. Una ricevuta coniata come NFT non si può falsificare e resta all'acquirente. Questo modello ne emette una per ordine, usando esattamente il layout introdotto da WNS: zero decimali, offerta bloccata a uno, metadati salvati dentro il token stesso.

Il compito

Dare a ogni cliente una prova d'acquisto che il negozio non può perdere, che il cliente non può falsificare e che non rivela nulla di privato su una catena pubblica. Facoltativamente, legare una garanzia a quell'unico acquirente, così che non possa essere venduta separatamente dalla persona che ha comprato l'articolo.

Il modello

  1. Il negozio calcola l'hash dell'ordine (id, prodotto, prezzo, data) con SHA-256. Solo l'hash va on-chain; l'ordine resta nel sistema del negozio e al cliente.
  2. Viene creato un nuovo mint Token-2022 con l'estensione Metadata Pointer, così nome, simbolo, link e campi extra vivono dentro il mint. Non serve un account di metadati esterno — l'approccio WNS.
  3. Campi extra: order_hash, warranty_until, sku.
  4. L'estensione facoltativa Non-Transferable rende la ricevuta soulbound: la garanzia appartiene all'acquirente e non può essere spostata.
  5. Un token viene coniato all'acquirente, poi l'autorità di conio viene rimossa. L'offerta resta bloccata a esattamente uno per sempre.

Per verificare una garanzia, chiunque calcola l'hash dell'ordine presentato dal cliente e lo confronta con order_hash on-chain. Una corrispondenza prova l'acquisto; il campo data prova la durata.

Il codice

File: 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 };
}

Cosa è stato verificato

In LiteSVM, sia per la versione soulbound sia per quella trasferibile: la ricevuta viene coniata; l'offerta è esattamente 1 con 0 decimali e nessuna autorità di conio; nome, hash dell'ordine e data di garanzia vengono riletti dall'interno del mint; l'acquirente la detiene; una ricevuta soulbound si rifiuta di muoversi (rifiutata da Token-2022 stesso), una trasferibile può essere regalata o rivenduta; e nessuno può coniarne una seconda copia. Vedi il registro delle verifiche.

Video 01/10: una ricevuta che nessuno può falsificare, in trenta secondi. Il player si carica da YouTube solo dopo che premi play.

Dove è utile

  • Elettronica ed elettrodomestici: richieste di garanzia senza carta.
  • Beni in edizione limitata e da collezione: provenienza dalla prima vendita.
  • Mercati dell'usato: una ricevuta trasferibile mostra l'origine dell'articolo al proprietario successivo.
  • Programmi fedeltà: la ricevuta stessa diventa la tessera.

Limiti e rischi

  • Ogni ricevuta costa un affitto (un piccolo deposito in SOL) e una commissione di rete. Raggruppa o comprimi per volumi elevati.
  • Non inserire mai dati personali (nome, indirizzo, telefono) nei metadati: la catena è pubblica e permanente.
  • L'hash prova solo ciò di cui il negozio ha calcolato l'hash. Concorda un formato d'ordine fisso prima di iniziare.
  • L'acquirente ha bisogno di un portafoglio. Per la grande distribuzione, prevedi un'opzione di portafoglio custodial o integrato.

Wen in immagini

Wen cliente con prova d'acquisto
Prova d'acquisto nel portafoglio
Giocattolo Wen con certificato di garanzia
Una garanzia che viaggia con l'articolo
Ricevute della collezione di peluche Wen
Beni fisici, prova digitale
Lista della spesa di Wen su Solana
Dal carrello alla catena
Ecco Wen, custode delle ricevute
La fedeltà comincia con una ricevuta

Dove si colloca Wen in questo modello

Un negozio può premiare chi detiene i suoi NFT-ricevuta con piccole mance in WEN o un bonus fedeltà, oppure accettare WEN alla cassa tramite la Fase 4. La ricevuta stessa usa il layout WNS reso famoso da Wen: il primo NFT WNS è stata la poesia di Meow, e la stessa struttura ora porta una prova d'acquisto.

Il filo di Wen: un contratto, ovunque

Ogni modello del Lab è gratuito e aperto, e ognuno porta la stessa firma: il contratto del token $WEN. Copialo, ripetilo nei tuoi documenti e verificalo sempre su un explorer prima di usarlo.

WENWENvqqNya429ubCdR81ZmD69brwQaaBYY6p3LCpk

Verifica: Solana Explorer · come trovare l'ID del contratto

Politica di uso aperto

  • Gratuito e aperto. Tutto il codice del Lab è rilasciato con licenza Apache 2.0, la stessa della Wen Program Library. Usalo, modificalo, distribuiscilo, a fini commerciali o no; mantieni l'avviso di licenza.
  • Solo strumenti aperti. Costruito su strumenti pubblici e documentati: Solana SPL Token-2022 (Token Extensions), il layout dei token del Wen New Standard (WNS), Solana Pay e LiteSVM per i test locali.
  • La regola: verifica sempre il tuo modello. Esegui i test, inizia sulla devnet, leggi la documentazione ufficiale, rivedi ogni account e importo e ottieni un audit indipendente prima di qualsiasi uso su mainnet. Un modello non verificato non è un modello, è un'ipotesi.
  • Non sottoposto ad audit, non è una consulenza. Questi sono esempi didattici. Non costituiscono consulenza finanziaria, legale o fiscale, né un prodotto di pagamento o bancario autorizzato. Pagamenti, stablecoin e acquiring sono attività regolamentate nella maggior parte dei paesi.
  • Sicurezza. Non incollare mai una chiave privata in un sito web. Non installare il pacchetto npm @wen-community/wen-new-standard: npm lo ha rimosso perché malevolo. Costruisci da fonti ufficiali.

Parla Wen, per la comunità. Altro nella nostra politica editoriale e sui dati.

Wen Open Lab · roadmap · tutto il codice · Wen Program Library su GitHub

Wen controlla le casse di carico in un hangar di astronavi mentre i robot caricano scatole
Ogni cassa con la sua ricevuta: un certificato di garanzia soulbound che resta nel portafoglio dell'acquirente e non si può falsificare.