Wen Open Lab · integrazione aperta

Fase 3: fatture B2B13 verifiche superate

English · Italiano · 中文 · 한국어

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

Wen a Wall Street, regolamento B2B
Regole aziendali dentro il token

Nei pagamenti tra aziende la parte difficile non è spostare denaro ma spostarlo correttamente: alla controparte giusta, con il riferimento giusto, tenendo conto delle commissioni. Token-2022 può portare queste regole dentro il token. Questo modello costruisce un token di regolamento che rifiuta i pagamenti senza memo di fattura e le controparti che nessuno ha approvato.

Il compito

Un gruppo di aziende regola le fatture tra loro. Ogni pagamento deve fare riferimento a una fattura, solo le aziende verificate possono ricevere fondi, e l'operatore della rete trattiene una piccola commissione con un tetto massimo.

Il modello

RegolaEstensione Token-2022Effetto
Commissione di piattaforma 0,25%, con tetto a 50 unitàTransfer FeesIl token trattiene la commissione a ogni trasferimento
Solo aziende approvateDefault Account State = FrozenI nuovi account nascono congelati; l'emittente li scongela dopo i propri controlli KYB
Memo di fattura obbligatorioRequired Memo (sull'account ricevente)Un pagamento senza un memo immediatamente prima viene rifiutato. Il testo del memo non viene controllato on-chain: verifica il numero di fattura in fase di riconciliazione.

Il flusso: l'emittente crea il mint; ogni azienda apre un account ricevente che richiede un memo; l'emittente approva (scongela) le aziende verificate; chi paga invia un memo invoice:INV-… e il trasferimento nella stessa transazione.

Il codice

File: lab/code/src/03-b2b-invoice.ts · Apache-2.0

// Model 3: B2B settlement token with built-in rules (Token-2022, not the WNS program itself):
//   - Transfer Fees: a platform fee taken by the token itself;
//   - Default Account State = Frozen: only accounts the issuer thaws (verified counterparties) can hold it;
//   - Required Memo: the receiving account rejects any payment that carries no memo at all.
//     Token-2022 checks THAT a memo exists, not WHAT it says: a wrong invoice number still passes on-chain.
//     Matching the invoice number is done off-chain, at reconciliation (see matchInvoicePayment below).
// License: Apache-2.0. Example code, not audited. Devnet first. A real stablecoin issuer is a licensed entity.
import { Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction, sendAndConfirmTransaction } from '@solana/web3.js';
import {
  AccountState, ExtensionType, TOKEN_2022_PROGRAM_ID,
  createEnableRequiredMemoTransfersInstruction, createInitializeAccount3Instruction,
  createInitializeDefaultAccountStateInstruction, createInitializeMintInstruction,
  createInitializeTransferFeeConfigInstruction, createThawAccountInstruction,
  createTransferCheckedWithFeeInstruction, getAccountLen, getMintLen,
} from '@solana/spl-token';
import { getConnection, loadKeypair } from './common.js';

export const DECIMALS = 6;

/** The canonical SPL Memo program that Token-2022 checks for "required memo" accounts.
 *  Note: newer @solana/spl-memo releases default to a different program ID, so we build the memo ourselves. */
export const SPL_MEMO_PROGRAM_ID = new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr');

export function memoInstruction(text: string, signer: PublicKey): TransactionInstruction {
  return new TransactionInstruction({
    programId: SPL_MEMO_PROGRAM_ID,
    keys: [{ pubkey: signer, isSigner: true, isWritable: false }],
    data: Buffer.from(text, 'utf8'),
  });
}
export const FEE_BPS: number = 25;                                   // 0.25%
export const FEE_CAP = 50n * 10n ** BigInt(DECIMALS);        // at most 50 units per transfer

export const settlementMintSpace = () => getMintLen([ExtensionType.TransferFeeConfig, ExtensionType.DefaultAccountState]);
export const invoiceAccountSpace = () => getAccountLen([ExtensionType.TransferFeeAmount, ExtensionType.MemoTransfer]);

/** Issuer creates the settlement mint. It keeps the freeze authority: thawing = approving a counterparty. */
export function buildSettlementMint(issuer: PublicKey, mint: PublicKey, rentLamports: number): TransactionInstruction[] {
  return [
    SystemProgram.createAccount({ fromPubkey: issuer, newAccountPubkey: mint, space: settlementMintSpace(), lamports: rentLamports, programId: TOKEN_2022_PROGRAM_ID }),
    createInitializeTransferFeeConfigInstruction(mint, issuer, issuer, FEE_BPS, FEE_CAP, TOKEN_2022_PROGRAM_ID),
    createInitializeDefaultAccountStateInstruction(mint, AccountState.Frozen, TOKEN_2022_PROGRAM_ID),
    createInitializeMintInstruction(mint, DECIMALS, issuer, issuer, TOKEN_2022_PROGRAM_ID),
  ];
}

/** A company opens an account that demands an invoice memo on every incoming payment. */
export function buildInvoiceAccount(company: PublicKey, account: PublicKey, mint: PublicKey, rentLamports: number, requireMemo = true): TransactionInstruction[] {
  return [
    SystemProgram.createAccount({ fromPubkey: company, newAccountPubkey: account, space: invoiceAccountSpace(), lamports: rentLamports, programId: TOKEN_2022_PROGRAM_ID }),
    createInitializeAccount3Instruction(account, mint, company, TOKEN_2022_PROGRAM_ID),
    ...(requireMemo ? [createEnableRequiredMemoTransfersInstruction(account, company, [], TOKEN_2022_PROGRAM_ID)] : []),
  ];
}

/** Issuer approves (thaws) an account after its own KYB checks off-chain. */
export function buildApproveCounterparty(issuer: PublicKey, mint: PublicKey, account: PublicKey): TransactionInstruction[] {
  return [createThawAccountInstruction(account, mint, issuer, [], TOKEN_2022_PROGRAM_ID)];
}

/** Fee the token will take: 0.25% capped at 50 units. Must match the mint config exactly.
 *  Token-2022 rounds the fee UP (ceiling division), and TransferCheckedWithFee rejects any other value.
 *  Example: 401 base units at 25 bps = 1.0025 -> fee 2, not 1.  (Fixed 2026-11-09, reported by a reader.) */
export function expectedFee(amount: bigint): bigint {
  if (amount === 0n || FEE_BPS === 0) return 0n;
  const raw = (amount * BigInt(FEE_BPS) + 9_999n) / 10_000n;
  return raw > FEE_CAP ? FEE_CAP : raw;
}

export const invoiceMemo = (invoiceId: string) => `invoice:${invoiceId}`;

/** Memos written by the Memo program, read from transaction logs. The Memo program logs
 *  'Program log: Memo (len N)' and then the text on the next line (older versions: 'Memo (len N): "text"'). */
export function memosFromLogs(logs: string[]): string[] {
  const out: string[] = [];
  logs.forEach((l, i) => {
    const m = /Memo \(len (\d+)\)(?:: "(.*)")?$/.exec(l);
    if (!m) return;
    if (m[2] !== undefined) out.push(m[2]);
    else if (logs[i + 1]?.startsWith('Program log: ')) out.push(logs[i + 1].slice('Program log: '.length));
  });
  return out;
}

/** Reconciliation (off-chain): the on-chain rule only proves that SOME memo was attached.
 *  Accept a payment for an invoice only if it carries exactly one invoice memo and it is the expected one. */
export function matchInvoicePayment(logs: string[], invoiceId: string): boolean {
  const inv = memosFromLogs(logs).filter(m => m.startsWith('invoice:'));
  return inv.length === 1 && inv[0] === invoiceMemo(invoiceId);
}

/** Pay an invoice: the memo instruction must come right before the transfer. */
export function buildPayInvoice(args: { mint: PublicKey; from: PublicKey; to: PublicKey; payer: PublicKey; invoiceId: string | null; amount: bigint }): TransactionInstruction[] {
  return [
    ...(args.invoiceId ? [memoInstruction(invoiceMemo(args.invoiceId), args.payer)] : []),
    createTransferCheckedWithFeeInstruction(args.from, args.mint, args.to, args.payer, args.amount, DECIMALS, expectedFee(args.amount), [], TOKEN_2022_PROGRAM_ID),
  ];
}

/** Example of sending one step on a real cluster (devnet by default). */
export async function createSettlementMint() {
  const connection = getConnection();
  const issuer = loadKeypair();
  const mint = Keypair.generate();
  const rent = await connection.getMinimumBalanceForRentExemption(settlementMintSpace());
  await sendAndConfirmTransaction(connection, new Transaction().add(...buildSettlementMint(issuer.publicKey, mint.publicKey, rent)), [issuer, mint]);
  return mint.publicKey;
}

Un'insidia reale trovata durante i test: le versioni recenti di @solana/spl-memo usano per impostazione predefinita un ID di programma diverso. Token-2022 controlla il programma SPL Memo canonico (MemoSq4g…), quindi il codice costruisce da sé l'istruzione memo. Controlla sempre gli ID dei programmi, non solo i nomi dei pacchetti.

Cosa è stato verificato

In LiteSVM: il mint viene creato con le regole di commissione e di congelamento predefinito; l'account del venditore richiede un memo; l'emittente finanzia l'acquirente; un pagamento senza memo di fattura viene rifiutato ("No memo in previous instruction"); un pagamento a un'azienda non approvata viene rifiutato ("Account is frozen"); la fattura INV-2026-0042 viene pagata; il numero di fattura è registrato on-chain; il venditore riceve 997,5 su 1.000 con 2,5 trattenuti come commissione; e il tetto della commissione regge a 50 su un pagamento di 100.000. Dal 9 novembre: la commissione arrotonda per eccesso esattamente come Token-2022 (401 unità base pagano una commissione di 2), e un pagamento con un numero di fattura sbagliato passa on-chain ma viene rifiutato dalla riconciliazione.

Dove è utile

  • Reti di fornitori e marketplace con molte piccole fatture.
  • Pagamenti B2B transfrontalieri che richiedono una traccia di audit chiara.
  • Progetti pilota di tesoreria aziendale con depositi tokenizzati o stablecoin (come nel caso Shinhan).

Limiti e rischi

  • Emettere un token di regolamento stabile è un'attività regolamentata; questo è solo lo strato tecnico.
  • L'autorità di congelamento dell'emittente è potente. Usa un multisig e una governance chiara.
  • Un memo è pubblico. Usa numeri di fattura, mai il contenuto delle fatture.
  • Token-2022 controlla che un memo sia presente, non cosa dice. Un numero di fattura sbagliato passa comunque on-chain; riconcilia sempre i pagamenti con il tuo elenco di fatture (matchInvoicePayment).
  • La commissione arrotonda per eccesso. Calcolala con la stessa formula di Token-2022, o leggila dal mint, mai con una semplice divisione intera.
  • Le commissioni trattenute negli account devono essere raccolte dall'autorità delle commissioni; pianifica questa operazione.

Wen in immagini

Wall Street incontra Solana
Finanza tradizionale, nuovi binari
Scrivania di regolamento di mercato di Wen
Fatture che non possono sparire
Portafoglio aziendale di Meow Wen
Solo controparti approvate
Regolamento stabile sui binari di Jupiter
Valore stabile, regole programmabili
Moneta d'affari dorata di Wen
Ogni pagamento con il suo riferimento

Dove si colloca Wen in questo modello

Il token di regolamento qui è un'unità stabile emessa da un soggetto regolamentato; WEN non è pensato come valuta per le fatture. Il ruolo di Wen è la storia: WNS, lo standard dietro l'NFT della poesia di WEN, ha fatto conoscere a molte persone i meccanismi Token-2022 usati da questo modello. Una comunità o una rete d'imprese può comunque regolare in WEN piccole commissioni di servizio o mance tra i membri, fuori dal flusso delle fatture.

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 cammina con una simpatica creatura verde in una città di torri altissime
Affari in città: niente numero di fattura, niente pagamento; solo le aziende approvate possono ricevere.