anchorage_layer_simple/features/api-anchorage-skip-if-exists.md

API d'ancrage - Paramètre skipIfExists

Date: 2026-01-28 Auteur: Équipe 4NK

Objectif

Ajouter un paramètre optionnel skipIfExists à l'endpoint /api/anchor/document pour éviter de réancrer des hash déjà ancrés. L'API doit renvoyer le résultat avec un tag old: true/false et les informations de la transaction depuis la base de données sans appel RPC supplémentaire.

Motivations

• Éviter les réancrages inutiles : Si un hash est déjà ancré, ne pas créer une nouvelle transaction
• Performance : Utiliser la base de données comme source de vérité pour éviter les appels RPC coûteux
• Cohérence : Retourner toujours les mêmes informations (txid, confirmations, block_height) qu'un ancrage normal

Impacts

Fonctionnels

• L'endpoint /api/anchor/document accepte maintenant un paramètre optionnel skipIfExists
• Si skipIfExists: true et que le hash existe déjà en base, retourne immédiatement les informations sans créer de transaction
• Toutes les réponses incluent maintenant ok: true et old: true/false
• Les ancres sont automatiquement stockées dans la table anchors après création

Techniques

• Enrichissement de la table anchors : Les ancres sont maintenant stockées automatiquement lors de la création
• Pas d'appel RPC supplémentaire : Les informations sont récupérées directement depuis la base de données
• Compatibilité : Le paramètre est optionnel, le comportement par défaut reste inchangé

Modifications

Fichiers modifiés

1. api-anchorage/src/routes/anchor.js

   • Ajout du paramètre skipIfExists dans le body de la requête
   • Vérification en base de données si le hash existe déjà
   • Retour des informations existantes avec old: true si le hash est trouvé
   • Ajout de ok: true et old: false dans la réponse pour les nouveaux ancrages

2. api-anchorage/src/bitcoin-rpc.js

   • Stockage automatique de l'ancre dans la table anchors après création de la transaction
   • Utilisation de INSERT OR REPLACE pour gérer les cas de mise à jour

3. api-anchorage/README.md

   • Documentation du nouveau paramètre skipIfExists
   • Documentation des nouveaux champs de réponse (ok, old)
   • Exemples d'utilisation avec skipIfExists: true

Structure de la réponse

Nouvel ancrage :

{
  "ok": true,
  "txid": "...",
  "status": "confirmed",
  "confirmations": 0,
  "block_height": 152321,
  "outputs": [...],
  "fee": 0.00001,
  "fee_sats": 1000,
  "old": false
}

Hash déjà ancré (avec skipIfExists: true) :

{
  "ok": true,
  "txid": "...",
  "status": "confirmed",
  "confirmations": 5,
  "block_height": 152316,
  "old": true
}

Modalités de déploiement

1. Vérifier la base de données : S'assurer que la table anchors existe (créée par init-db.mjs)
2. Déployer le code : Les modifications sont rétrocompatibles, aucun changement de schéma requis
3. Tester : Vérifier que les ancres existantes sont bien retournées avec old: true
4. Monitoring : Surveiller les logs pour vérifier que les ancres sont bien stockées en base

Modalités d'analyse

Vérification du fonctionnement

1. Test avec hash nouveau :

   curl -X POST http://localhost:3010/api/anchor/document \
     -H "Content-Type: application/json" \
     -H "x-api-key: your-api-key" \
     -d '{"hash": "nouveau_hash_64_caracteres_hex", "skipIfExists": true}'
   

   • Doit créer une nouvelle transaction
   • Doit retourner old: false
   • Doit stocker l'ancre en base

2. Test avec hash existant :

   curl -X POST http://localhost:3010/api/anchor/document \
     -H "Content-Type: application/json" \
     -H "x-api-key: your-api-key" \
     -d '{"hash": "hash_deja_ancré_64_caracteres_hex", "skipIfExists": true}'
   

   • Ne doit pas créer de nouvelle transaction
   • Doit retourner old: true
   • Doit retourner les informations depuis la base de données

3. Vérification en base :

   SELECT * FROM anchors WHERE hash = 'hash_test';
   

   • Doit contenir l'enregistrement avec txid, block_height, confirmations

Logs à surveiller

• Hash already anchored, returning existing anchor : Hash trouvé en base avec skipIfExists
• Anchor stored in database : Ancre stockée après création
• Error storing anchor in database : Erreur lors du stockage (ne fait pas échouer la transaction)

Notes

• Le paramètre skipIfExists est optionnel et par défaut à false pour maintenir la compatibilité
• Si skipIfExists: false ou non fourni, le comportement reste identique à avant (création systématique)
• Les ancres sont stockées avec INSERT OR REPLACE pour gérer les cas de mise à jour (confirmations, block_height)
• Le stockage en base ne fait pas échouer la transaction si une erreur survient (log warning uniquement)