Guide de Développement Light Protocol

Créez des applications scalables et rentables sur Solana avec Light Protocol - la plateforme d'infrastructure qui permet les tokens et comptes sans loyer avec la performance et la sécurité de la L1.

Vue d'ensemble

Light Protocol fournit deux technologies complémentaires :

• ZK Compression : Créez des tokens compressés et des PDAs sans loyer en utilisant des preuves à connaissance zéro. Utilise les arbres de Merkle et les preuves de validité pour stocker l'état efficacement.
• Light Token Program : Un standard de token haute performance qui réduit les coûts de mint et de compte de token de 200x par rapport aux tokens SPL.

Avantages clés

IDs des programmes

Démarrage rapide

Installation

# Installer les SDKs TypeScript
npm install @lightprotocol/stateless.js @lightprotocol/compressed-token

# Installer CLI pour le développement local
npm install -g @lightprotocol/zk-compression-cli

Configuration RPC

Light Protocol nécessite un RPC compatible ZK Compression. Utilisez Helius :

import { Rpc, createRpc } from "@lightprotocol/stateless.js";

// Mainnet
const rpc = createRpc(
  "https://mainnet.helius-rpc.com?api-key=<YOUR_API_KEY>",
  "https://mainnet.helius-rpc.com?api-key=<YOUR_API_KEY>"
);

// Devnet
const devnetRpc = createRpc(
  "https://devnet.helius-rpc.com?api-key=<YOUR_API_KEY>",
  "https://devnet.helius-rpc.com?api-key=<YOUR_API_KEY>"
);

Configuration de base

import { Rpc, createRpc } from "@lightprotocol/stateless.js";
import {
  createMint,
  mintTo,
  transfer,
} from "@lightprotocol/compressed-token";
import { Keypair, PublicKey } from "@solana/web3.js";

// Initialiser la connexion RPC
const rpc = createRpc(process.env.RPC_ENDPOINT!, process.env.RPC_ENDPOINT!);

// Charger le portefeuille
const payer = Keypair.fromSecretKey(
  Uint8Array.from(JSON.parse(process.env.PRIVATE_KEY!))
);

console.log("Connecté à Light Protocol");
console.log("Wallet:", payer.publicKey.toBase58());

ZK Compression

ZK Compression permet les tokens compressés sans loyer en utilisant des preuves à connaissance zéro. Les comptes compressés sont stockés dans des arbres de Merkle et vérifiés en utilisant des preuves de validité.

Créer un Mint de token compressé

import { createMint } from "@lightprotocol/compressed-token";
import { Keypair } from "@solana/web3.js";

const payer = Keypair.generate();
const mintAuthority = payer;

// Créer un mint avec un pool de tokens pour la compression
const { mint, transactionSignature } = await createMint(
  rpc,
  payer,           // Fee payer
  mintAuthority.publicKey,  // Mint authority
  9,               // Decimals
);

console.log("Mint créé:", mint.toBase58());
console.log("Transaction:", transactionSignature);

Créer des tokens compressés

import { mintTo } from "@lightprotocol/compressed-token";

const recipient = new PublicKey("...");
const amount = 1_000_000_000; // 1 token avec 9 décimales

const transactionSignature = await mintTo(
  rpc,
  payer,           // Fee payer
  mint,            // Mint avec pool de tokens
  recipient,       // Adresse du destinataire
  mintAuthority,   // Mint authority (signataire)
  amount,          // Quantité à créer
);

console.log("Créé:", transactionSignature);

Créer vers plusieurs destinataires

const recipients = [
  new PublicKey("recipient1..."),
  new PublicKey("recipient2..."),
  new PublicKey("recipient3..."),
];

const amounts = [
  1_000_000_000,
  2_000_000_000,
  3_000_000_000,
];

const transactionSignature = await mintTo(
  rpc,
  payer,
  mint,
  recipients,      // Tableau de destinataires
  mintAuthority,
  amounts,         // Tableau de quantités (doit correspondre à la longueur des destinataires)
);

Transférer des tokens compressés

import { transfer } from "@lightprotocol/compressed-token";

const recipient = new PublicKey("...");
const amount = 500_000_000; // 0,5 token

const transactionSignature = await transfer(
  rpc,
  payer,           // Fee payer
  mint,            // Mint avec pool de tokens
  amount,          // Quantité à transférer
  sender,          // Propriétaire du token (signataire)
  recipient,       // Adresse de destination
);

console.log("Transféré:", transactionSignature);

Remarque : Les transferts de tokens compressés utilisent un modèle consume-and-create. Les comptes d'entrée sont consommés et de nouveaux comptes de sortie sont créés avec les soldes mis à jour.

Compresser les tokens SPL

Convertir les tokens SPL existants au format compressé :

import { compress, compressSplTokenAccount } from "@lightprotocol/compressed-token";

// Compresser une quantité spécifique vers un destinataire
const transactionSignature = await compress(
  rpc,
  payer,
  mint,
  amount,
  owner,           // Propriétaire du token SPL
  recipient,       // Destinataire du token compressé
  tokenAccount,    // Compte SPL source
);

// Compresser l'intégralité du compte de token SPL (récupérer le loyer)
const tx = await compressSplTokenAccount(
  rpc,
  payer,
  mint,
  owner,
  tokenAccount,
  // Optionnel : quantité à conserver au format SPL
);

Décompresser vers les tokens SPL

Convertir les tokens compressés au format SPL :

import { decompress } from "@lightprotocol/compressed-token";

const transactionSignature = await decompress(
  rpc,
  payer,
  mint,
  amount,
  owner,           // Propriétaire du token compressé (signataire)
  recipient,       // Destinataire du token SPL
);

Interroger les comptes compressés

// Obtenir tous les comptes de token compressé pour un propriétaire
const tokenAccounts = await rpc.getCompressedTokenAccountsByOwner(
  owner.publicKey,
  { mint }
);

console.log("Comptes de token:", tokenAccounts.items.length);

// Calculer le solde total
const totalBalance = tokenAccounts.items.reduce(
  (sum, account) => sum + BigInt(account.parsed.amount),
  BigInt(0)
);
console.log("Solde total:", totalBalance.toString());

// Obtenir le solde du compte compressé
const balance = await rpc.getCompressedTokenAccountBalance(accountHash);

// Obtenir la preuve de validité pour la transaction
const proof = await rpc.getValidityProof(compressedAccountHashes);

Créer un pool de tokens pour un mint existant

Ajouter le support de compression à un mint SPL existant :

import { createTokenPool } from "@lightprotocol/compressed-token";

// Ajouter un pool de tokens à un mint SPL existant
// Remarque : ne nécessite PAS l'autorité du mint
const transactionSignature = await createTokenPool(
  rpc,
  payer,           // Fee payer
  existingMint,    // Mint SPL existant
);

Light Token Program

Le Light Token Program est un standard de token haute performance séparé qui réduit les coûts sans preuves ZK. Il est optimisé pour les chemins critiques et fournit une interopérabilité wrap/unwrap avec les tokens SPL.

Différences clés par rapport à ZK Compression

Créer un Mint Light Token

import { createLightMint } from "@lightprotocol/light-token";

const { mint, transactionSignature } = await createLightMint(
  rpc,
  payer,
  mintAuthority.publicKey,
  9,  // decimals
);

console.log("Light mint créé:", mint.toBase58());

Créer vers Light-ATA

import { mintToLightAta } from "@lightprotocol/light-token";

const transactionSignature = await mintToLightAta(
  rpc,
  payer,
  mint,
  recipient,
  mintAuthority,
  amount,
);

Wrapper SPL vers Light Token

import { wrapSpl } from "@lightprotocol/light-token";

// Wrapper les tokens SPL vers les tokens Light
const transactionSignature = await wrapSpl(
  rpc,
  payer,
  mint,
  amount,
  owner,
  splTokenAccount,
);

Unwrap Light Token vers SPL

import { unwrapToSpl } from "@lightprotocol/light-token";

// Unwrap les tokens Light vers SPL
const transactionSignature = await unwrapToSpl(
  rpc,
  payer,
  mint,
  amount,
  owner,
  recipient,  // Compte de token SPL
);

Méthodes JSON RPC

Light Protocol fournit 21 méthodes RPC spécialisées pour les comptes compressés. Méthodes clés :

Consultez resources/json-rpc-methods.md pour la documentation complète.

Meilleures pratiques

Limites des transactions

• 4 comptes compressés par transaction : Diviser les opérations volumineuses en plusieurs transactions
• Budget d'unités de calcul : Ajouter des unités de calcul supplémentaires pour la vérification de preuve

import { ComputeBudgetProgram } from "@solana/web3.js";

// Ajouter un budget de calcul pour les transactions complexes
const modifyComputeUnits = ComputeBudgetProgram.setComputeUnitLimit({
  units: 300_000,
});

Opérations par batch

// Traiter plusieurs destinataires par batch
async function batchMint(
  recipients: PublicKey[],
  amounts: number[],
  batchSize = 4
) {
  const results = [];

  for (let i = 0; i < recipients.length; i += batchSize) {
    const batchRecipients = recipients.slice(i, i + batchSize);
    const batchAmounts = amounts.slice(i, i + batchSize);

    const sig = await mintTo(
      rpc,
      payer,
      mint,
      batchRecipients,
      mintAuthority,
      batchAmounts,
    );

    results.push(sig);
  }

  return results;
}

Gestion des erreurs

try {
  const signature = await transfer(rpc, payer, mint, amount, sender, recipient);
  console.log("Succès:", signature);
} catch (error) {
  if (error.message.includes("TokenPool not found")) {
    // Créer d'abord le pool de tokens
    await createTokenPool(rpc, payer, mint);
  } else if (error.message.includes("Insufficient balance")) {
    // Vérifier le solde avant le transfert
    const accounts = await rpc.getCompressedTokenAccountsByOwner(sender.publicKey, { mint });
    console.log("Solde disponible:", accounts.items);
  } else {
    throw error;
  }
}

Délégation

import { approve, transferDelegated } from "@lightprotocol/compressed-token";

// Approuver un délégué
const approveSig = await approve(
  rpc,
  payer,
  mint,
  amount,
  owner,           // Propriétaire du token
  delegate,        // Clé publique du délégué
);

// Transférer en tant que délégué
const transferSig = await transferDelegated(
  rpc,
  payer,
  mint,
  amount,
  delegate,        // Délégué (signataire)
  recipient,
);

Ressources

Documentation officielle

• ZK Compression Docs
• Light Protocol Whitepaper

Dépôts GitHub

• Light Protocol - Dépôt principal
• Example Node.js Client
• Example Web Client

Communauté

• Discord - Discord Light Protocol
• Helius Discord - Support du fournisseur RPC

Support des portefeuilles

• Phantom - Support natif des tokens compressés
• Backpack - Support natif des tokens compressés

Structure de compétence

light-protocol/
├── SKILL.md                    # Ce fichier
├── resources/
│   ├── program-addresses.md    # IDs des programmes, arbres d'état, endpoints RPC
│   ├── json-rpc-methods.md     # Les 21 méthodes RPC documentées
│   ├── sdk-reference.md        # Référence du SDK TypeScript
│   └── github-repos.md         # Dépôts officiels
├── examples/
│   ├── setup/
│   │   └── example.ts          # Configuration de base
│   ├── zk-compression/
│   │   ├── create-mint.ts      # Créer un mint compressé
│   │   ├── mint-tokens.ts      # Créer des tokens compressés
│   │   ├── transfer-tokens.ts  # Transférer des tokens compressés
│   │   ├── compress-spl.ts     # Compresser les tokens SPL
│   │   └── decompress.ts       # Décompresser vers SPL
│   ├── light-token-program/
│   │   ├── create-light-mint.ts
│   │   ├── mint-light-tokens.ts
│   │   └── wrap-unwrap.ts
│   ├── querying/
│   │   └── fetch-accounts.ts   # Interroger les comptes compressés
│   └── advanced/
│       ├── batch-operations.ts # Opérations multi-destinataires
│       └── delegation.ts       # Approuver et déléguer les transferts
├── templates/
│   └── setup.ts                # Modèle de démarrage complet
└── docs/
    └── troubleshooting.md      # Problèmes courants et solutions

Vérifier

• Un vrai appel RPC/SDK a été émis (mainnet, devnet ou validateur local) et le payload de réponse est capturé dans la transcription, pas seulement paraphrasé
• Chaque transaction a été simulée (simulateTransaction ou équivalent) avant toute étape de signature/envoi ; les logs de simulation sont joints
• Pour toute transaction signée/envoyée, la signature résultante est enregistrée et confirmée on-chain (statut retourné par getSignatureStatuses ou une URL explorer)
• Le slippage, les frais de priorité et les limites d'unités de calcul ont été définis explicitement avec des valeurs numériques concrètes, pas laissés aux défauts de la bibliothèque
• Les adresses de compte, les mints et les IDs de programme utilisés dans l'exécution correspondent aux adresses light-protocol-zk documentées pour le cluster ciblé (pas de mix mainnet/devnet)
• Le chemin d'échec a été exercé au moins une fois (solde insuffisant, oracle obsolète, blockhash expiré, etc.) et la gestion des erreurs de l'agent a produit un message lisible pour l'humain