Architecture de passerelle de paiement Stablecoin

Aperçu de l'architecture :

Une passerelle de paiement stablecoin comporte cinq couches principales : (1) la couche d'intention de paiement qui crée et gère les adresses de dépôt par paiement, (2) la couche de surveillance de la chaîne qui surveille la blockchain pour les transferts entrants, (3) le moteur de confirmation qui valide les reçus et déclenche les événements, (4) le grand livre qui enregistre tous les états de paiement et (5) la couche de règlement qui gère la gestion de la off-ramp et de la trésorerie.

Ce guide se concentre sur la conception du système derrière une passerelle de production stablecoin – non seulement sur les composants existants, mais aussi sur la façon dont ils se connectent, où les pannes se produisent et quelles décisions de conception sont importantes pour la fiabilité à grande échelle.

Couche d'intention de paiement

Une intention de paiement est créée lorsqu'un payeur initie un paiement. Il stocke : le montant attendu, le stablecoin et la chaîne, l'adresse de dépôt attribuée, l'heure d'expiration et la référence de la commande ou de la facture en aval.

Dérivation de l'adresse de dépôt

Les adresses de dépôt sont dérivées d'un portefeuille HD utilisant BIP-44. La graine principale est stockée dans un gestionnaire de secrets (AWS Secrets Manager, Vault). Chaque intention de paiement se voit attribuer un indice de chemin de dérivation unique. La passerelle stocke : l'indice de dérivation, le montant attendu, le stablecoin, la chaîne, l'expiration et l'état du paiement.

Sur les chaînes EVM, la même adresse dérivée fonctionne sur toutes les chaînes compatibles EVM. Un seul portefeuille HD peut servir Base, Ethereum, Polygon et Arbitrum avec des indices d'adresse distincts par intention.

Expiration et réutilisation des adresses

Les adresses de dépôt ne doivent pas être réutilisées dans les intentions de paiement. Après expiration ou paiement réussi, l'adresse est désactivée dans la couche de surveillance. Si un paiement en retard arrive à une adresse expirée, la passerelle l'enregistre comme sans correspondance pour un examen manuel.

Couche de surveillance de la chaîne

La couche de surveillance de la chaîne surveille la blockchain pour les événements de transfert ERC-20 (ou équivalent) vers n'importe quelle adresse de dépôt active. La conception doit gérer : un volume d'événements élevé (sur des chaînes occupées), une détection en temps réel, des réorganisations de chaînes et une surveillance simultanée sur plusieurs chaînes.

EVM Surveillance de la chaîne

Subscribe to ERC-20 Transfer events from the stablecoin contract address using WebSocket RPC (Alchemy, QuickNode). Filter by the to address matching any active deposit address. Use a bloom filter or database index on active addresses for O(1) lookup.

Fallback: poll for recent Transfer events every N seconds using eth_getLogs. WebSocket subscriptions are preferred but can drop connections — the polling fallback ensures no missed events.

Surveillance Tron TRC-20

TronGrid API fournit l'historique des transactions pour une adresse. Interrogez l'historique des transferts TRC-20 pour chaque adresse de dépôt active à l'aide de TronGrid REST API. Les abonnements WebSocket sont moins fiables sur Tron : l'interrogation est l'approche standard.

Solana SPL Surveillance des jetons

Solana uses Associated Token Accounts (ATAs) — each wallet address has a corresponding ATA for each SPL token. Monitor the USDC ATA corresponding to each deposit address using WebSocket account subscriptions or polling getSignaturesForAddress.

Moteur de confirmation

Le moteur de confirmation valide les virements détectés et émet des événements de paiement. Principales responsabilités :

Vérification de la profondeur des blocs: Attend que la transaction atteigne la profondeur de confirmation requise avant d'émettre un événement confirmé.

Validation du montant: Compare le montant reçu au montant attendu. Gère les sous-paiements (indicateur pour examen manuel ou rejet en fonction de la tolérance du produit) et les trop-payés (montant total du crédit, indicateur d'excédent).

Gestion de la réorganisation de la chaîne: Si une transaction précédemment détectée est supprimée lors d'une réorganisation de la chaîne, annulez l'événement payment_detected et repassez dans l'état en attente. Utilisez une profondeur de confirmation courte adaptée au risque de réorganisation de la chaîne.

Idempotence: Chaque hachage de transaction confirmé est stocké. La relecture du même événement de confirmation est un échec.

Conception du grand livre

Le grand livre des paiements fait autorité pour toutes les activités de paiement stables. Il doit s'agir d'un ajout uniquement (pas de mises à jour, uniquement d'insertions) et d'un événement : chaque transition d'état (créée, détectée, confirmée, expirée, balayée) est une écriture du grand livre.

Événement	Déclencheur	Action en aval
paiement.créé	Intention de paiement créée	Retourner l'adresse de dépôt au payeur
paiement.détecté	Transfert vu sur la chaîne, en attente	Aviser le payeur ; afficher le statut en attente
paiement.confirmé	Confirmations requises atteintes	Activer la commande/l'abonnement ; déclencher un webhook
paiement.expiré	Délai d'expiration dépassé, aucun paiement	Adresse de dépôt de libération ; informer le payeur
paiement.sous-payé	Montant inférieur à celui prévu	Signaler pour examen ; manipulation spécifique au produit
paiement.swept	Fonds transférés vers le portefeuille du Trésor	Mettre à jour l'enregistrement de balayage ; réduire le solde des adresses

Gestion du balayage et de la trésorerie

Le portefeuille de trésorerie doit être multi-signature (par exemple Safe/Gnosis Safe) pour les déploiements de production – les opérations de trésorerie critiques nécessitent plusieurs signataires.

Financement du gaz: Chaque adresse de dépôt nécessite un jeton natif (ETH, TRX, etc.) pour couvrir les frais de transaction de balayage. La passerelle maintient un service de financement du gaz qui recharge les adresses de dépôt avant le balayage.

Déclencheur de balayage: Déclenché par le seuil de solde, le calendrier ou manuellement. Les balayages par lots réduisent le coût total du gaz.

Confirmation du balayage: La transaction de balayage est surveillée jusqu'à confirmation. En cas de réussite, l'événement du grand livre de balayage est enregistré.

Architecture d'intégration off-ramp

La off-ramp convertit le stablecoin détenu dans le portefeuille du Trésor en monnaie fiduciaire. Le modèle d'intégration :

Compte fournisseur off-ramp: Le fournisseur de sortie (Bridge, Coinbase Prime, etc.) fournit une adresse de destination stablecoin. L'envoi de USDC à cette adresse déclenche un règlement fiduciaire sur le compte bancaire configuré.

Instruction de transfert: La passerelle construit et signe un transfert du portefeuille de trésorerie vers l'adresse de sortie. Cela nécessite un accès à la clé de signature du portefeuille de trésorerie – nécessite généralement une approbation multi-signatures.

Confirmation du règlement: Les fournisseurs de sortie envoient des webhooks ou fournissent APIs pour confirmer le règlement fiduciaire. La passerelle enregistre l'événement de règlement fiduciaire par rapport au transfert off-ramp.

Considérations relatives à la production

Décisions architecturales importantes pour la fiabilité de la production :

Exécutez des connexions de nœuds RPC redondantes (principal d'Alchemy + secours QuickNode) – des échecs uniques RPC ne devraient pas entraîner de paiements manqués
File d'attente d'événements (Kafka, SQS ou Redis Streams) entre la surveillance de la chaîne et le moteur de confirmation : dissocie l'ingestion du traitement et permet la relecture
Transactions de base de données autour des écritures dans le grand livre : l'événement de confirmation et l'action en aval doivent tous deux être validés ou annulés.
File d'attente de lettres mortes pour les livraisons de webhook ayant échoué : réessayez avec une interruption exponentielle, alerte en cas d'échecs répétés
Surveillance et alerte sur : le retard de surveillance de la chaîne, les paiements non appariés, les échecs de balayage, les retards de règlement off-ramp
Séparez la gestion des clés de signature de la logique d'application de la passerelle : les opérations de trésorerie doivent nécessiter une approbation multi-signatures.

FAQ

La passerelle doit-elle être un service autonome ou intégrée à l’application principale ?

Un service de passerelle autonome est fortement préféré pour la production. Il isole la logique de surveillance et de signature de la chaîne de l'application principale, peut être déployé et mis à l'échelle indépendamment et possède une limite de sécurité claire. La passerelle publie les événements de paiement ; l'application principale les consomme.

Comment gérer les utilisateurs qui envoient un mauvais montant ou un mauvais stablecoin ?

Les mauvais transferts de stablecoins (par exemple DAI au lieu de USDC) vers l'adresse de dépôt sont enregistrés comme sans correspondance et mis en file d'attente pour examen manuel. Les sous-paiements sont signalés : le produit définit s'il doit accepter les paiements partiels, les rejeter ou inviter le payeur à recharger. Les trop-payés peuvent être entièrement crédités avec l’excédent remboursé en chaîne.

Que se passe-t-il si le nœud RPC tombe en panne ?

La couche de surveillance doit fonctionner avec des fournisseurs RPC redondants. Si tout échoue, la passerelle entre dans un état dégradé : les nouvelles confirmations de paiement sont retardées mais pas perdues. Une fois la connectivité restaurée, rejouez à partir du dernier bloc confirmé pour détecter les événements de transfert manqués. La mise en file d'attente des événements entre la surveillance et le moteur de confirmation garantit qu'aucun événement n'est abandonné lors de brèves pannes.

Comment cette architecture s’adapte-t-elle à des volumes élevés ?

Mise à l'échelle horizontale des travailleurs de surveillance de la chaîne (un travailleur par chaîne ou fragment de chaîne). La file d'attente des événements absorbe le volume des rafales. Le moteur de confirmation évolue horizontalement tant que les écritures du grand livre sont idempotentes. Dérivation d'adresses et échelle de recherche avec un index de base de données approprié sur les adresses actives. Le goulot d'étranglement réside généralement dans les limites de débit RPC : prévoyez des points de terminaison dédiés RPC à grande échelle.

Résumé de l'architecture

Cinq couches : intention de paiement (gestion des adresses), surveillance de la chaîne, moteur de confirmation, grand livre et règlement (balayage + off-ramp).

La dérivation de portefeuille HD donne des adresses de dépôt uniques et déterministes sans stocker de clés privées par adresse.

La file d'attente des événements entre le moteur de surveillance et de confirmation est essentielle pour la fiabilité et la relecture.

Ledger doit être uniquement ajouté et généré par des événements : chaque transition d'état est un enregistrement, pas une mise à jour.

L'intégration multi-signatures et de sortie de trésorerie est les composants opérationnels sensibles : conception avec des contrôles de signature appropriés.