Suivi de portefeuille Sui

Un outil de suivi de portefeuille en temps réel pour Sui, qui utilise Quicknode GraphQL pour récupérer les soldes et l'historique des transactions, ainsi que le streaming gRPC pour détecter l'activité en direct sur la blockchain.

Consulter le dépôt

Framework/bibliothèque front-end :

Node.js

Langue :

TypeScript

Outil de compilation/serveur de développement :

tsx

Aperçu

Cette application d'exemple est un outil de suivi de portefeuille en mode terminal destiné à la blockchain Sui. Elle combine deux couches de l'API Sui de Quicknode: GraphQL pour les requêtes avancées sur les soldes et les transactions, et le streaming gRPC pour les notifications de points de contrôle en temps réel. Pour un guide pas à pas, consultez le guide d'accompagnement.

Au démarrage, l'application récupère les soldes initiaux des cryptomonnaies et les transactions récentes via GraphQL. Elle établit ensuite une connexion gRPC persistante vers S'abonner à Checkpoints sur Sui's Service d'abonnement, en recevant un nouveau point de contrôle toutes les 400 à 500 ms environ. Lorsque le flux détecte une activité sur la blockchain pour une adresse suivie, il déclenche une nouvelle requête GraphQL (avec suppression des rebonds) afin de mettre à jour l'état affiché.

Architecture

Startup
  Application -> Quicknode GraphQL (HTTPS/443)
    -> GetBalances + GetTransactions
      -> Afficher l'état initial

Mises à jour en temps réel
  Application -> Quicknode gRPC (:9000)
    -> SubscribeCheckpoints (flux persistant)
      -> détecter l'adresse dans l'expéditeur ou les modifications de solde
        -> délai de rebond de 2 s -> nouvelle requête GraphQL -> réaffichage

Fonctionnalités

Requêtes GraphQL pour consulter les soldes des cryptomonnaies (tous types confondus) et les 20 transactions les plus récentes au démarrage
gRPC S'abonner à Checkpoints flux pour la détection basée sur les événements (environ 400 ms par point de contrôle)
Mise en place d'un mécanisme anti-rebond pour la récupération GraphQL après les points de contrôle pertinents, afin d'éviter les requêtes redondantes lors des pics de trafic
Affichage en temps réel de l'évolution du solde pour chaque point de contrôle pertinent (type de pièce, sens, montant)
Suivi multi-adresses : un seul flux gRPC, filtrage côté client sur l'ensemble des adresses
Reconnexion automatique gRPC avec délai d'attente exponentiel (jusqu'à 30 s)
Affichage en deux parties : panneau « Solde/Transactions » fixe en haut, flux en temps réel défilant en dessous

Prérequis

Node.js 20 et plus
pnpm (npm install -g pnpm)
Un point de terminaison du réseau principal Quicknode Sui

Structure du projet

src/
  index.ts          # Point d'entrée, orchestration du démarrage, rendu
  graphql.ts        # Requêtes GraphQL : GetBalances, GetTransactions
  grpc-stream.ts    # Abonnement au flux gRPC et traitement des points de contrôle
  portfolio.ts      # Gestion de l'état du portefeuille et rendu dans le terminal
  types.ts          # Définitions de types TypeScript
protos/             # Fichiers proto Sui (clonés depuis MystenLabs/sui-apis)

Variables d'environnement

Copier .env.example to .env et complétez :

QN_ENDPOINT_URL=https://your-endpoint.sui-mainnet.quiknode.pro
QN_ENDPOINT_TOKEN=votre-jeton-ici
SUI_ADDRESS=0x...

Variable	Description
`QN_ENDPOINT_URL`	URL du point de terminaison du réseau principal Quicknode Sui (sans barre oblique finale ni jeton)
`QN_ENDPOINT_TOKEN`	Jeton d'authentification (la partie du chemin d'accès située après le nom d'hôte dans l'URL de votre point de terminaison)
`SUI_ADDRESS`	Adresse(s) Sui à surveiller. Séparer les adresses multiples par des virgules.

Comment trouver votre jeton : L'URL de votre point de terminaison Quicknode se présente comme suit : https://abc123xyz.sui-mainnet.quiknode.pro/abcdef1234567890. Le jeton correspond au segment de chemin situé après le nom d'hôte : abcdef1234567890.

Pour suivre plusieurs adresses, séparez-les par des virgules :

SUI_ADDRESS=0xabc...,0xdef...,0x123...

Remarque : GraphQL utilise le jeton dans le chemin d'accès de l'URL ; gRPC l'utilise comme un x-token en-tête de métadonnées. Ces deux valeurs proviennent du même point de terminaison Quicknode.

Démarrer

1. Cloner le dépôt

git clone https://github.com/quiknode-labs/qn-guide-examples.git
cd qn-guide-examples/sui/sui-portfolio-tracker

2. Cloner les fichiers Sui proto

Le client gRPC nécessite les définitions protobuf de Sui :

git cloner https://github.com/MystenLabs/sui-apis.git protos

3. Installer les dépendances

pnpm installer

4. Configurer l'environnement

cp .env.example .env

Saisissez les valeurs indiquées dans la section « Variables d'environnement » ci-dessus.

5. Exécuter

pnpm démarrer

Scripts

Commande	Description
`pnpm start`	Exécuter avec tsx (recommandé)
`pnpm dev`	Exécuter avec surveillance des fichiers
`pnpm build`	Compiler TypeScript
`pnpm start : compilé`	Exécuter le résultat de la compilation