Come funzionano i pagamenti su Solana

Prima di costruire flussi di pagamento su Solana, è necessario comprendere cinque concetti fondamentali: wallet, stablecoin, token account, commissioni e transazioni. I pagamenti Solana si mappano in modo chiaro ai sistemi di pagamento multi-valuta:

Proprio come un cliente bancario ha una singola identità ma detiene saldi separati per ciascuna valuta, un wallet Solana ha un indirizzo ma un token account distinto per ogni asset che detiene. Analizziamo ogni componente.

Wallet: mittenti e destinatari

Ogni pagamento coinvolge due parti, ciascuna identificata da un indirizzo wallet—una chiave pubblica univoca di 32 byte (ad es., 7EcDhS...).

• Mittente: il wallet che avvia il pagamento. Deve detenere un saldo sufficiente nel token account della stablecoin e firmare la transazione.
• Destinatario: il wallet di destinazione. Non è necessario che firmi o detenga un saldo esistente.
• Pagatore delle commissioni: il wallet opzionale che paga le commissioni. Può essere utilizzato per sovvenzionare o abilitare transazioni solo in stablecoin tra utenti.

Pensa agli indirizzi wallet come ai numeri di conto bancario: pubblici, sicuri da condividere e necessari per inviare o ricevere fondi.

Stablecoin

Le stablecoin sono chiamate "token" su Solana. I token rappresentano un tipo di asset sulla rete. Ogni token ha un identificatore univoco chiamato "indirizzo mint". Quando si costruiscono sistemi di pagamento, si farà riferimento a questi indirizzi mint per identificare l'asset con cui si sta interagendo. Ecco alcuni indirizzi mint di stablecoin comuni sulla mainnet:

Per ulteriori informazioni sulle stablecoin su Solana, consulta la pagina delle soluzioni Stablecoins.

Token account

I wallet non contengono direttamente i token. Invece, ogni wallet ha autorità su un token account per ogni tipo di token che detiene. I pagamenti vengono effettuati trasferendo token dal token account del mittente al token account del destinatario dello stesso mint:

Token account

Un Associated Token Account è un token account deterministico legato a uno specifico wallet e mint. Dato un indirizzo wallet e un mint, l'indirizzo ATA è sempre lo stesso.

1. Un ATA per mint. Un wallet ha esattamente un ATA per USDC, uno per USDT, ecc.
2. Deve esistere prima di ricevere. Non è possibile inviare token a un ATA che non esiste.
3. Tipicamente creato dal mittente. Se l'ATA del destinatario non esiste, il mittente può crearlo come parte della transazione di pagamento.

import { findAssociatedTokenPda } from "@solana-program/token";

const [receiverATA] = await findAssociatedTokenPda({
  mint: USDG_MINT_ADDRESS,
  owner: receiverWallet.address,
  tokenProgram: TOKEN_PROGRAM_ADDRESS
});

Token Program

Su Solana, i program sono logica eseguibile che governa lo stato degli account. I token account sono gestiti da un Token Program—il codice on-chain che verifica i trasferimenti e aggiorna i saldi in modo atomico.

Solana ha due Token Program:

Token-2022 (chiamato anche "Token Extensions") aggiunge funzionalità come transfer hook, commissioni di trasferimento e trasferimenti confidenziali. Entrambi i programmi funzionano in modo simile per i trasferimenti di base, ma è necessario utilizzare quello corretto quando si derivano gli ATA.

Perché è importante

Il Token Program utilizzato per creare un token governa le istruzioni e lo stato dell'account per il token. Se utilizzi il programma sbagliato, non sarai in grado di trasferire il token.

Gli ATA sono derivati da tre input: wallet + mint + token_program. Utilizzare il programma sbagliato produce un indirizzo completamente diverso:

import {
  findAssociatedTokenPda,
  TOKEN_PROGRAM_ADDRESS
} from "@solana-program/token";
import { TOKEN_2022_PROGRAM_ADDRESS } from "@solana-program/token-2022";

// USDC uses Token Program
const [usdcAta] = await findAssociatedTokenPda({
  mint: USDC_MINT,
  owner: walletAddress,
  tokenProgram: TOKEN_PROGRAM_ADDRESS // ✓ Correct
});

// ❌ This will produce a different address because it uses the wrong program
const [wrongUsdcAta] = await findAssociatedTokenPda({
  mint: USDC_MINT,
  owner: walletAddress,
  tokenProgram: TOKEN_2022_PROGRAM_ADDRESS // ❌ Wrong program
});

// PYUSD uses Token-2022
const [pyusdAta] = await findAssociatedTokenPda({
  mint: PYUSD_MINT,
  owner: walletAddress,
  tokenProgram: TOKEN_2022_PROGRAM_ADDRESS // ✓ Correct
});

Lo stesso principio si applica alle istruzioni di trasferimento. Ogni token program ha la propria istruzione di trasferimento e devi invocare quella corretta:

import { getTransferInstruction } from "@solana-program/token";
import { getTransferInstruction as getTransferInstruction22 } from "@solana-program/token-2022";

// For USDC (Token Program)
const usdcTransferIx = getTransferInstruction({
  source: senderUsdcAta,
  destination: receiverUsdcAta,
  authority: senderWallet,
  amount: 1_000_000n // 1 USDC (6 decimals)
});

// For PYUSD (Token-2022)
const pyusdTransferIx = getTransferInstruction22({
  source: senderPyusdAta,
  destination: receiverPyusdAta,
  authority: senderWallet,
  amount: 1_000_000n // 1 PYUSD (6 decimals)
});

// *Note*: Most token program JS Client functions include the ability
// to specify the token program address. Generally, defining it is a
// good practice to ensure you are fully aware of the program you are using
const usdcTransferIx2 = getTransferInstruction(
  {
    source: senderUsdcAta,
    destination: receiverUsdcAta,
    authority: senderWallet,
    amount: 1_000_000n // 1 USDC (6 decimals)
  },
  { tokenProgram: TOKEN_PROGRAM_ADDRESS }
);

L'invio di un'istruzione di trasferimento al programma sbagliato fallirà. Il programma verifica di possedere i token account coinvolti: gli account creati dal Token Program non possono essere trasferiti tramite Token-2022 e viceversa.

Per verificare quale programma utilizza un token o un token account, recupera il mint o il token account e controlla il suo campo owner:

import { createSolanaRpc, address } from "@solana/kit";

const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
const accountInfo = await rpc.getAccountInfo(address(mintAddress)).send();

// The owner field tells you which program manages this token
const tokenProgram = accountInfo.value?.owner;
// Returns: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA (Token Program)
//      or: TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb (Token-2022)

Per le applicazioni di pagamento, memorizza l'indirizzo del programma corretto insieme a ciascun token supportato:

const SUPPORTED_TOKENS = {
  USDC: {
    mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    program: TOKEN_PROGRAM_ADDRESS,
    decimals: 6
  },
  PYUSD: {
    mint: "2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo",
    program: TOKEN_2022_PROGRAM_ADDRESS,
    decimals: 6
  }
};

Token Extensions

Il Token Extensions Program (Token 2022) fornisce più funzionalità attraverso istruzioni aggiuntive denominate extensions. Le extensions sono funzionalità opzionali che puoi aggiungere a un token mint o a un token account.

Per maggiori informazioni sulle Token Extensions, consulta la documentazione Token Extensions.

Commissioni

I pagamenti su Solana comportano fino a tre componenti di costo:

Costo totale per pagamento: meno di $0,001 per la maggior parte dei trasferimenti. Se si crea un nuovo token account, prevedi un totale di circa $0,40.

Transazioni e istruzioni

Una transazione è l'unità atomica di esecuzione su Solana—o tutte le operazioni hanno successo, o nessuna. Ogni transazione contiene una o più istruzioni, che sono comandi individuali (ad esempio, "trasferisci 10 USDC", "crea token account").

Una tipica transazione di pagamento potrebbe includere due istruzioni: creare il token account del destinatario (se necessario), quindi trasferire i token. Entrambe vengono eseguite atomicamente—nessuno stato parziale. Come vedrai in Payment Processing, puoi raggruppare più pagamenti in una singola transazione per ridurre i costi e aumentare il throughput.

Mettere tutto insieme

Un flusso di pagamento tipico:

1. Raccogliere gli input. Ottenere gli indirizzi dei wallet del mittente e del destinatario e l'indirizzo mint del token da trasferire.
2. Derivare gli ATA. Determinare i token account per entrambe le parti.
3. Costruire e firmare. Costruire la transazione con le istruzioni di trasferimento necessarie, firmare con la chiave del mittente.
4. Inviare e confermare. La transazione si completa in meno di un secondo.

Prossimi passi