Concepts on-chain

Nul besoin d’être ingénieur blockchain pour utiliser CowriePay, mais quatre comportements des blockchains publiques traversent toute API bâtie dessus. Chacun ci-dessous décrit ce que cette plateforme fait réellement, et non ce qui se pratique en général.

Détecté n’est pas confirmé

Un dépôt passe par DETECTED, CONFIRMING, puis CONFIRMED. Ces états ne sont pas cosmétiques :

• DETECTED : la transaction a été vue sur la blockchain et se situe sous le seuil de confirmations.
• CONFIRMING : elle accumule des confirmations.
• CONFIRMED : le seuil est atteint, et c’est seulement là que la consolidation (le « sweep » : le transfert des fonds vers la garde CowriePay, signalé par l’événement DEPOSIT_SWEPT) est déclenchée.

Créditez votre client sur CONFIRMED, jamais sur DETECTED. Une transaction détectée peut encore disparaître si le bloc qui la portait cesse d’appartenir à la chaîne canonique.

N’inscrivez pas le seuil en dur : lisez-le sur le dépôt. Chaque dépôt porte required_confirmations à côté de confirmations : 7 / 19 est donc une fraction de progression que vous pouvez afficher directement.

Ce champ est fixé lorsque le dépôt est vu pour la première fois, et n’est jamais modifié ensuite. Si un opérateur relève le seuil d’une blockchain, les dépôts déjà en vol conservent la valeur avec laquelle ils ont commencé : une barre de progression ne peut donc jamais reculer. La nouvelle valeur ne vaut que pour les dépôts suivants.

À titre indicatif, les seuils actuellement déployés sont de 19 sur TRON et de 12 sur BSC et Ethereum, mais considérez ces valeurs comme celles du jour et le champ comme l’engagement.

Ce que fait une réorganisation de la blockchain

Si la transaction d’un dépôt confirmé cesse plus tard d’appartenir à la chaîne canonique, CowriePay le détecte et lève une alerte interne. Le solde n’est pas annulé automatiquement.

C’est un choix délibéré : à ces profondeurs de confirmation, une réorganisation est quasiment impossible sur les blockchains prises en charge ici, et annuler automatiquement un solde déjà crédité produit des erreurs comptables pires que l’événement qu’il prétend réparer. C’est un humain qui instruit le cas.

Ce que cela implique pour vous : la gestion des réorganisations n’est pas à implémenter de votre côté, mais elle n’est ni instantanée ni silencieuse. Si cela survenait sur votre workspace, vous seriez contacté.

La poussière sous le minimum de consolidation

Consolider un dépôt coûte du gas. En dessous d’un certain montant, ce gas représente une part trop importante de la valeur : le dépôt reste alors sur son adresse de dépôt au lieu d’être consolidé. Il n’est ni perdu ni absorbé ; il attend que la consolidation devienne économique.

Les planchers sont fixés par actif, dans l’unité propre de l’actif, et ils sont plus élevés sur Ethereum parce que le gas y est cher :

Actif	Minimum de consolidation
USDT_TRON	1
USDT_BSC	1
USDT_ETH	20
USDC_ETH	20
EURC_ETH	20
ETH	0.005
BNB	0.02

Ce sont les valeurs par défaut déployées, surchargeables par déploiement. Si votre produit accepte de petits paiements, prévoyez le cas où un paiement arrive, se confirme, et n’est pas encore consolidé.

Une blockchain doit être ouverte avant usage

Une blockchain est fermée par défaut et n’accepte wallets clients et retraits qu’une fois activée par un opérateur. Créer un wallet sur une blockchain non activée renvoie 422 CHAIN_NOT_ENABLED.

Appelez List the chains open for new operations avant d’afficher un sélecteur de blockchain ou d’actif, pour qu’un client ne puisse jamais choisir une option qui échouera à la création du wallet.

La simulation d’échec en Sandbox n’existe pas encore

Il n’existe aujourd’hui aucun moyen de déclencher de façon déterministe un scénario d’échec en Sandbox. L’exposé complet de ce que la Sandbox est, et n’est pas, se trouve dans La sandbox et le faucet.