Fase 3: fatture B2B13 verifiche superate
- 0 · Roadmap
- 1 · Ricevute e garanzia
- 2 · Royalty per i creatori
- 3 · Fatture B2B
- 4 · Ponte pagamenti
- 5 · Simulatore
- 6 · Devnet: ripetilo
- 7 · Cassa
- 7.1 · Sicurezza
- ✓ · Catena della fiducia
- ★ · Vantaggi e usi
- ✎ · Dieci guide
- ▶ · Video
- ? · Scoperte dei lettori

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
| Regola | Estensione Token-2022 | Effetto |
|---|---|---|
| Commissione di piattaforma 0,25%, con tetto a 50 unità | Transfer Fees | Il token trattiene la commissione a ogni trasferimento |
| Solo aziende approvate | Default Account State = Frozen | I nuovi account nascono congelati; l'emittente li scongela dopo i propri controlli KYB |
| Memo di fattura obbligatorio | Required 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





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
