Solana Pay

Το πακέτο @solana-commerce/solana-pay παρέχει πλήρη λειτουργικότητα Solana Pay για τη δημιουργία εμπειριών πληρωμών, συμβατή με τις βιβλιοθήκες gill και @solana/kit. Χειρίζεται την κωδικοποίηση/ανάλυση URLs, τη δημιουργία κωδικών QR με προσαρμοσμένη μορφοποίηση και την κατασκευή συναλλαγών τόσο για μεταφορές SOL όσο και για tokens SPL.

Εγκατάσταση

pnpm add @solana-commerce/solana-pay

Κωδικοποίηση URL

encodeURL(fields)

Δημιουργεί ένα URL Solana Pay που συμμορφώνεται με την προδιαγραφή Solana Pay. Αυτή η συνάρτηση δημιουργεί URLs πρωτοκόλλου solana: που μπορούν να κοινοποιηθούν ως σύνδεσμοι ή να κωδικοποιηθούν ως κωδικοί QR για σάρωση από κινητά πορτοφόλια.

Παράμετροι

• fields (TransferRequestURLFields | TransactionRequestURLFields) - Διαμόρφωση για το URL πληρωμής

TransferRequestURLFields

Χρησιμοποιείται για απλά αιτήματα πληρωμής (άμεσες μεταφορές):

• recipient (Address, υποχρεωτικό) - Η διεύθυνση πορτοφολιού του εμπόρου (δημόσιο κλειδί κωδικοποιημένο σε base58) που θα λάβει την πληρωμή. Μπορεί να είναι string ή τύπου Address από το gill.

• amount (bigint, προαιρετικό) - Ποσό πληρωμής σε lamports (ατομικές μονάδες). Για SOL, 1 SOL = 1.000.000.000 lamports (9 δεκαδικά). Για tokens SPL, χρησιμοποιήστε την ακρίβεια δεκαδικών του token (π.χ., το USDC χρησιμοποιεί 6 δεκαδικά, άρα 1 USDC = 1.000.000).

• splToken (Address, προαιρετικό) - Η διεύθυνση mint του SPL token για πληρωμές με tokens. Αν παραλειφθεί, η πληρωμή θεωρείται ότι γίνεται σε SOL.

• reference (Address | Address[], προαιρετικό) - Μοναδική διεύθυνση(-εις) αναφοράς που χρησιμοποιούνται για την παρακολούθηση πληρωμών. Δημιουργήστε χρησιμοποιώντας την generateKeyPairSigner().address. Η αναφορά προστίθεται ως λογαριασμός μόνο για ανάγνωση στη συναλλαγή, επιτρέποντάς σας να αναζητήσετε πληρωμές χρησιμοποιώντας αυτήν την αναφορά.

• label (string, προαιρετικό) - Αναγνώσιμο από τον άνθρωπο όνομα εμπόρου ή εφαρμογής που εμφανίζεται στον χρήστη στο πορτοφόλι του (π.χ., "Καφετέρια", "Το Κατάστημά μου").

• message (string, προαιρετικό) - Μήνυμα που εμφανίζεται στον χρήστη πριν από την πληρωμή (π.χ., "Ευχαριστούμε για την αγορά σας!", "Φιλοδώρημα για εξαιρετική εξυπηρέτηση").

• memo (string, προαιρετικό) - Σημείωση on-chain που επισυνάπτεται στη συναλλαγή. Αποθηκεύεται μόνιμα στο Solana. Χρήσιμο για αναγνωριστικά παραγγελίας, αριθμούς τιμολογίου ή άλλα μεταδεδομένα πληρωμής.

TransactionRequestURLFields

Χρησιμοποιείται για σύνθετα αιτήματα πληρωμής (συμπεριλαμβανομένων οδηγιών):

• link (URL, απαιτείται) - Ο σύνδεσμος προς τη συναλλαγή (Link). Εάν το URL περιέχει παραμέτρους ερωτήματος, πρέπει να είναι κωδικοποιημένο με URL-encoding.

• label (string, προαιρετικό) - Ευανάγνωστο όνομα εμπόρου ή εφαρμογής που εμφανίζεται στον χρήστη στο πορτοφόλι του (π.χ., "Καφετέρια", "Το Κατάστημά Μου").

• message (string, προαιρετικό) - Μήνυμα που εμφανίζεται στον χρήστη πριν από την πληρωμή (π.χ., "Ευχαριστούμε για την αγορά σας!", "Φιλοδώρημα για εξαιρετική εξυπηρέτηση").

Πώς Λειτουργεί

Η συνάρτηση εκτελεί διάφορες λειτουργίες για τη δημιουργία ενός έγκυρου URL Solana Pay:

1. Πρόθεμα Πρωτοκόλλου - Δημιουργεί ένα URL με το σχήμα πρωτοκόλλου solana: (παρόμοιο με mailto: ή bitcoin:)

2. Παραλήπτης ως Διαδρομή - Χρησιμοποιεί τη διεύθυνση base58 του παραλήπτη ως διαδρομή URL (π.χ., solana:merchantWalletAddress123...)

3. Μετατροπή Ποσού - Μετατρέπει το ποσό lamport bigint σε δεκαδική αναπαράσταση συμβολοσειράς χωρίς προβλήματα ακρίβειας κινητής υποδιαστολής.

4. Παράμετροι Ερωτήματος - Προσθέτει όλα τα προαιρετικά πεδία και τις αναφορές ως παραμέτρους ερωτήματος με κωδικοποίηση URL

Επιστρέφει

Αντικείμενο URL με το πρωτόκολλο solana: που μπορεί να:

• Μετατραπεί σε συμβολοσειρά με .toString() για κοινοποίηση
• Μεταβιβαστεί στο createQR() για δημιουργία κωδικού QR
• Χρησιμοποιηθεί απευθείας σε ετικέτες anchor: <a href={url.toString()}>Pay with Solana</a>

Παράδειγμα: Βασική Πληρωμή

import { encodeURL } from "@solana-commerce/solana-pay";
import { address } from "gill";

const url = encodeURL({
  recipient: address("merchantWalletAddress123..."),
  amount: 100000000n, // 0.1 SOL (100 million lamports)
  label: "Coffee Shop",
  message: "Thanks for your order!"
});

console.log(url.toString());
// solana:merchantWalletAddress123...?amount=0.1&label=Coffee%20Shop&message=Thanks%20for%20your%20order!

Παράδειγμα: Πληρωμή SPL Token

import { encodeURL } from "@solana-commerce/solana-pay";
import { address } from "gill";

const usdcMint = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

const url = encodeURL({
  recipient: address("merchantWallet..."),
  amount: 25000000n, // 25 USDC (6 decimals)
  splToken: usdcMint,
  label: "USDC Payment",
  message: "Pay with USDC stablecoin"
});

Παράδειγμα: Πληρωμή με Παρακολούθηση

Χρησιμοποιήστε αναφορές για την αναγνώριση συγκεκριμένων πληρωμών:

import { encodeURL } from "@solana-commerce/solana-pay";
import { address } from "gill";
import { Keypair } from "@solana/web3.js";

// Generate unique reference for this order
const orderReference = (await generateKeyPairSigner()).address;

const url = encodeURL({
  recipient: address("merchantWallet..."),
  amount: 500000000n, // 0.5 SOL
  reference: orderReference,
  memo: `Order-${Date.now()}`, // On-chain memo
  label: "E-commerce Store",
  message: "Complete your purchase"
});

// Later, query the blockchain for transactions containing this reference
// to verify payment was made

Ανάλυση URL

parseURL(url)

Αποκωδικοποιεί και επικυρώνει ένα URL Solana Pay, εξάγοντας όλες τις παραμέτρους πληρωμής. Αυτή η συνάρτηση εκτελεί επικύρωση και μετατρέπει ποσά από δεκαδικές συμβολοσειρές πίσω σε bigint lamport.

Παράμετροι

• url (string | URL) - Το URL Solana Pay προς ανάλυση. Μπορεί να είναι συμβολοσειρά ή αντικείμενο URL.

Επιστρέφει

Ένα αναλυμένο αντικείμενο TransferRequestURLFields ή TransactionRequestURLFields.

Παράδειγμα: Ανάλυση και Επικύρωση

import { parseURL, ParseURLError } from "@solana-commerce/solana-pay";

try {
  const parsed = parseURL(
    "solana:merchant123...?amount=1.5&label=Store&reference=ref123..."
  );

  console.log(parsed.recipient); // Address object
  console.log(parsed.amount); // 1500000000n (1.5 SOL in lamports)
  console.log(parsed.label); // "Store"
  console.log(parsed.reference); // [Address]

  // Convert back to human-readable format
  const solAmount = Number(parsed.amount) / 1e9;
  console.log(`Payment of ${solAmount} SOL`);
} catch (error) {
  if (error instanceof ParseURLError) {
    console.error("Invalid Solana Pay URL:", error.message);
  }
}

Παράδειγμα: Συνάρτηση Επικύρωσης URL

import { parseURL, ParseURLError } from "@solana-commerce/solana-pay";

function validateSolanaPayURL(urlString: string): {
  valid: boolean;
  error?: string;
  data?: any;
} {
  try {
    const parsed = parseURL(urlString);
    // Additional business logic validation
    if (parsed.splToken) {
      return {
        valid: false,
        error: "Only SOL payments are supported"
      };
    }
    if (parsed.amount && parsed.amount < 1000000n) {
      return {
        valid: false,
        error: "Amount too small (minimum 0.001 SOL)"
      };
    }
    // etc.

    return {
      valid: true,
      data: {
        recipient: parsed.recipient.toString(),
        amount: parsed.amount ? Number(parsed.amount) / 1e9 : undefined,
        token: parsed.splToken?.toString()
      }
    };
  } catch (error) {
    return {
      valid: false,
      error: error instanceof ParseURLError ? error.message : "Unknown error"
    };
  }
}

Δημιουργία Κωδικού QR

createQR(url, size, background, color)

Δημιουργεί έναν κωδικό QR σε μορφή SVG βελτιστοποιημένο για URLs Solana Pay. Η συνάρτηση παράγει στυλιζαρισμένους, υψηλής ποιότητας κωδικούς QR με στρογγυλεμένες γωνίες και προσαρμόσιμα χρώματα.

Παράμετροι

• url (string | URL) - Το URL Solana Pay για κωδικοποίηση στον κωδικό QR
• size (number, προεπιλογή: 512) - Πλάτος και ύψος σε pixels
• background (string, προεπιλογή: 'white') - Χρώμα φόντου (hex ή ονομαστικό χρώμα). Θα πρέπει να είναι ανοιχτό για συμβατότητα με πορτοφόλια.
• color (string, προεπιλογή: 'black') - Χρώμα προσκηνίου/κουκίδων (hex ή ονομαστικό χρώμα). Θα πρέπει να είναι σκούρο για αντίθεση.

createStyledQRCode(url, options)

Επιστρέφει

Promise<string> - Σήμανση SVG ως συμβολοσειρά που μπορεί να:

• Οριστεί ως src στοιχείου img: <img src={qrCode} />
• Αποθηκευτεί σε αρχείο

Παράδειγμα

import { createQR, encodeURL } from "@solana-commerce/solana-pay";
import { address } from "gill";

async function generatePaymentQR() {
  const url = encodeURL({
    recipient: address("merchant..."),
    amount: 100000000n, // 0.1 SOL
    label: "Coffee Shop"
  });

  const qrCode = await createQR(
    url.toString(),
    400, // 400x400 pixels
    "white", // White background
    "black" // Black foreground
  );

  // Display in browser
  document.getElementById("qr-container").innerHTML = qrCode;

  // Or use as image source
  document.getElementById("qr-image").src = qrCode;
}

Παράδειγμα: Επώνυμος Κωδικός QR

import { createStyledQRCode, encodeURL } from "@solana-commerce/solana-pay";
import { address } from "gill";

async function createBrandedQR() {
  const url = encodeURL({
    recipient: address("merchant..."),
    amount: 25000000n, // 25 USDC (6 decimals)
    splToken: address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"),
    label: "Coffee Shop",
    message: "Scan to pay with USDC"
  });

  const qr = await createStyledQRCode(url.toString(), {
    width: 600,
    margin: 3,
    color: {
      dark: "#9945FF", // Solana purple
      light: "#F5F5DC" // Beige
    },
    errorCorrectionLevel: "H", // Higher correction for logo
    dotStyle: "dots", // Circular dots
    cornerStyle: "extra-rounded",
    logo: "/coffee-logo.png", // Your logo
    logoSize: 120,
    logoBackgroundColor: "#FFFFFF", // White padding behind logo
    logoMargin: 10
  });

  return qr; // SVG string
}

Δημιουργία Συναλλαγών

createTransfer(rpc, sender, fields)

Δημιουργεί ένα πλήρες μήνυμα συναλλαγής Solana για μεταφορά πληρωμής. Αυτή η συνάρτηση ανιχνεύει αυτόματα αν πρέπει να δημιουργηθεί μεταφορά SOL ή SPL token βάσει της παραμέτρου splToken, και κατασκευάζει όλες τις απαραίτητες οδηγίες. Η συνάρτηση ορίζει μια διάρκεια ζωής blockhash για τη συναλλαγή χρησιμοποιώντας το πιο πρόσφατο blockhash από τον πελάτη RPC και επιστρέφει μια πλήρη, ανυπόγραφη συναλλαγή έτοιμη για υπογραφή και υποβολή στο RPC (τύπος TransactionMessageWithBlockhashLifetime, συμβατός με Solana Kit/Gill).

Παράμετροι

• rpc (Rpc<SolanaRpcApi>) - Πελάτης Solana RPC από το gill. Δημιουργήστε με το createSolanaClient(rpcUrl).rpc.

• sender (Address) - Η διεύθυνση πορτοφολιού του πληρωτή. Πρέπει να είναι ένας λογαριασμός με κεφάλαια που θα υπογράψει τη συναλλαγή.

• fields (CreateTransferFields) - Ρύθμιση μεταφοράς:

  • recipient (Address, υποχρεωτικό) - Διεύθυνση πορτοφολιού προορισμού
  • amount (bigint, υποχρεωτικό) - Ποσό σε lamports (SOL) ή ατομικές μονάδες token (SPL)
  • splToken (Address, προαιρετικό) - Διεύθυνση mint του SPL token. Εάν παραληφθεί, δημιουργεί μεταφορά SOL.
  • reference (Address | Address[], προαιρετικό) - Διεύθυνση(-εις) αναφοράς για παρακολούθηση
  • memo (string, προαιρετικό) - Κείμενο σημείωσης on-chain

Επιστρέφει

Promise<TransactionMessageWithBlockhashLifetime> - Πλήρες μήνυμα συναλλαγής με:

• Μορφή έκδοσης 0 (υποστηρίζει πίνακες αναζήτησης διευθύνσεων)
• Διάρκεια ζωής blockhash (η συναλλαγή λήγει μετά από ~60 δευτερόλεπτα)
• Όλες τις απαραίτητες οδηγίες (μεταφορά + προαιρετική σημείωση)
• Έτοιμο να υπογραφεί με πορτοφόλι και να υποβληθεί στο RPC

Διαχείριση Σφαλμάτων

Ρίχνει CreateTransferError με συγκεκριμένα μηνύματα:

• "sender not found" - Ο λογαριασμός αποστολέα δεν υπάρχει
• "recipient not found" - Ο λογαριασμός παραλήπτη δεν υπάρχει

Παράδειγμα: Πληρωμή SOL

import { createTransfer } from "@solana-commerce/solana-pay";
import { createSolanaClient } from "gill";
import { address } from "gill";

const rpc = createSolanaClient("https://api.mainnet-beta.solana.com").rpc;

// Build SOL transfer transaction
const txMessage = await createTransfer(rpc, address("sender-wallet-address"), {
  recipient: address("merchant-wallet-address"),
  amount: 100000000n, // 0.1 SOL
  memo: "Coffee purchase"
});

// Transaction is ready to sign and send
// (wallet signing is handled separately)
console.log("Transaction ready:", txMessage);

Παράδειγμα: Πληρωμή USDC

import { createTransfer } from "@solana-commerce/solana-pay";
import { createSolanaClient } from "gill";
import { address } from "gill";

const rpc = createSolanaClient("https://api.mainnet-beta.solana.com").rpc;
const usdcMint = address("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");

const txMessage = await createTransfer(rpc, address("sender-wallet"), {
  recipient: address("merchant-wallet"),
  amount: 25000000n, // 25 USDC (6 decimals)
  splToken: usdcMint,
  reference: [address("unique-ref-123...")],
  memo: "Order #12345"
});