nicolas.cantu/lecoffre-anchor-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
lecoffre-anchor-api/API_RESPONSES.md
NicolasCantu 924ab8e185 refactor: Replace UUID transaction_id with Bitcoin txid 
**Motivations :**
* transaction_id doit être un identifiant de transaction Bitcoin consultable sur mempool
* Les UUID n'ont pas d'utilité pour identifier une transaction Bitcoin
* Simplification de l'architecture en supprimant la logique de queue inutile

**Root causes :**
* transaction_id était généré comme UUID au lieu d'utiliser le txid Bitcoin
* Logique de queue/job complexe pour gérer des identifiants temporaires
* Réponse HTTP 202 alors que la transaction est créée immédiatement

**Correctifs :**
* transaction_id est maintenant directement le txid Bitcoin (64 hex)
* Suppression complète de la logique de queue et de job (Map, cleanup, etc.)
* Création immédiate de la transaction Bitcoin dans enqueue()
* getStatus() interroge directement Bitcoin au lieu d'une Map en mémoire
* Réponse HTTP 200 OK au lieu de 202 Accepted
* Suppression de la dépendance uuid (plus utilisée)

**Evolutions :**
* API simplifiée : plus de queue, transactions créées directement
* transaction_id consultable immédiatement sur mempool
* Documentation complète des réponses JSON (API_RESPONSES.md)
* Scripts de test mis à jour pour valider le format txid Bitcoin

**Page affectées :**
* src/services/AnchorQueueService.ts : refactor complet, suppression queue
* src/controllers/AnchorController.ts : mise à jour pour txid, status 200
* src/index.ts : suppression cleanup périodique
* test-api-ok.sh : validation format txid, status 200
* test-api.sh : validation format txid, status 200
* README.md : mise à jour exemples avec txid Bitcoin
* API_RESPONSES.md : nouvelle documentation complète des réponses JSON
2025-11-21 08:11:02 +01:00

11 KiB
Raw Permalink Blame History

Documentation des Réponses JSON - LeCoffre Anchor API

📋 Vue d'ensemble

L'API d'ancrage Bitcoin Signet retourne des réponses JSON standardisées. Le transaction_id est maintenant directement le txid Bitcoin (64 caractères hexadécimaux), consultable sur mempool.

🔍 Endpoints et Réponses

1. GET /health

Description : Vérifie l'état de santé de l'API et la connexion Bitcoin.

Réponse 200 OK :

{
  "ok": true,
  "service": "anchor-api",
  "bitcoin": {
    "connected": true,
    "blocks": 141690,
    "network": "signet",
    "explorer": "mempool2.4nkweb.com"
  },
  "context": {
    "api_version": "1.0.0",
    "network": "Bitcoin Signet",
    "explorer_url": "https://mempool2.4nkweb.com/fr/",
    "status": "operational"
  },
  "timestamp": "2025-11-14T10:30:00.000Z"
}

Réponse 503 Service Unavailable (si Bitcoin non connecté) :

{
  "ok": false,
  "service": "anchor-api",
  "error": "Bitcoin connection failed",
  "timestamp": "2025-11-14T10:30:00.000Z"
}

Champs :

  • ok : boolean - État général de l'API
  • service : string - Nom du service
  • bitcoin.connected : boolean - État de la connexion Bitcoin
  • bitcoin.blocks : number - Nombre de blocs dans la blockchain
  • bitcoin.network : string - Réseau Bitcoin (signet)
  • bitcoin.explorer : string - URL de l'explorateur
  • context.status : "operational" | "degraded" - État opérationnel
  • timestamp : string - ISO 8601 timestamp

2. POST /api/anchor/document

Description : Crée une transaction Bitcoin pour ancrer un hash de document.

Headers requis :

x-api-key: your-secure-api-key
Content-Type: application/json

Body :

{
  "documentUid": "doc-12345",
  "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "callback_url": "http://local.4nkweb.com:3001/api/v1/anchors/callback"
}

Réponse 200 OK :

{
  "transaction_id": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "status": "pending",
  "confirmations": 0,
  "block_height": null,
  "txid": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "documentUid": "doc-12345",
  "context": {
    "network": "Bitcoin Signet",
    "explorer": "mempool2.4nkweb.com",
    "api_version": "1.0.0",
    "request_timestamp": "2025-11-14T10:30:00.000Z",
    "document_uid": "doc-12345",
    "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "status": "pending"
  },
  "explorer_url": "https://mempool2.4nkweb.com/fr/tx/7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825"
}

Réponse 400 Bad Request (champs manquants) :

{
  "error": "Missing required fields: documentUid, hash"
}

Réponse 400 Bad Request (format hash invalide) :

{
  "error": "Invalid hash format (must be 64 hex characters)"
}

Réponse 500 Internal Server Error :

{
  "error": "Internal server error",
  "message": "Insufficient funds for anchoring transaction"
}

Champs :

  • transaction_id : string - TXID Bitcoin (64 hex) - Identifiant de transaction consultable sur mempool
  • status : "pending" | "confirmed" - État de la transaction
  • confirmations : number - Nombre de confirmations (0 si pending)
  • block_height : number | null - Hauteur du bloc (null si non confirmé)
  • txid : string - TXID Bitcoin (identique à transaction_id)
  • hash : string - Hash du document ancré (64 hex)
  • documentUid : string - Identifiant du document
  • explorer_url : string | null - URL de la transaction sur mempool
  • context : object - Informations contextuelles

Note importante : Le transaction_id est maintenant directement le txid Bitcoin, plus d'UUID.

3. GET /api/anchor/status/:transactionId

Description : Récupère le statut d'une transaction d'ancrage par son transaction_id (txid Bitcoin).

Headers requis :

x-api-key: your-secure-api-key

Réponse 200 OK :

{
  "transaction_id": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "status": "confirmed",
  "confirmations": 6,
  "block_height": 141690,
  "txid": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "documentUid": "doc-12345",
  "explorer_url": "https://mempool2.4nkweb.com/fr/tx/7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "network": "signet",
  "timestamp": "2025-11-14T10:25:00.000Z",
  "fee": -0.00000234,
  "size": 250,
  "anchor_info": {
    "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "document_uid": "doc-12345",
    "op_return_data": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "anchored_at": "2025-11-14T10:25:00.000Z",
    "block_height": 141690,
    "confirmations": 6,
    "explorer_url": "https://mempool2.4nkweb.com/fr/tx/7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
    "network": "signet"
  }
}

Réponse 400 Bad Request :

{
  "error": "Missing transaction_id"
}

Réponse 404 Not Found :

{
  "error": "Transaction not found"
}

Réponse 500 Internal Server Error :

{
  "error": "Internal server error",
  "message": "Bitcoin RPC error"
}

Champs :

  • transaction_id : string - TXID Bitcoin (64 hex)
  • status : "pending" | "confirmed" - État de la transaction
  • confirmations : number - Nombre de confirmations
  • block_height : number | null - Hauteur du bloc
  • txid : string - TXID Bitcoin (identique à transaction_id)
  • hash : string - Hash du document ancré
  • documentUid : string - Identifiant du document
  • explorer_url : string - URL mempool
  • network : string - Réseau Bitcoin (signet)
  • timestamp : string | undefined - ISO 8601 timestamp de la transaction
  • fee : number | undefined - Frais de transaction en BTC
  • size : number | undefined - Taille de la transaction en bytes
  • anchor_info : object - Informations détaillées sur l'ancrage

4. POST /api/anchor/verify

Description : Vérifie si un hash est ancré dans la blockchain Bitcoin.

Headers requis :

x-api-key: your-secure-api-key
Content-Type: application/json

Body :

{
  "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "txid": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825"
}

Réponse 200 OK (hash vérifié) :

{
  "verified": true,
  "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "anchor_info": {
    "transaction_id": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
    "block_height": 141690,
    "confirmations": 6,
    "timestamp": "2025-11-14T10:25:00.000Z",
    "fee": -0.00000234,
    "size": 250,
    "explorer_url": "https://mempool2.4nkweb.com/fr/tx/7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
    "network": "signet",
    "op_return_data": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "anchored_at": "2025-11-14T10:25:00.000Z"
  },
  "context": {
    "network": "Bitcoin Signet",
    "explorer": "mempool2.4nkweb.com",
    "api_version": "1.0.0",
    "verification_timestamp": "2025-11-14T10:30:00.000Z"
  }
}

Réponse 200 OK (hash non trouvé) :

{
  "verified": false,
  "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "context": {
    "network": "Bitcoin Signet",
    "explorer": "mempool2.4nkweb.com",
    "api_version": "1.0.0",
    "verification_timestamp": "2025-11-14T10:30:00.000Z",
    "message": "Hash not found in blockchain"
  }
}

Réponse 400 Bad Request :

{
  "error": "Missing required field: hash"
}

Réponse 400 Bad Request (format invalide) :

{
  "error": "Invalid hash format (must be 64 hex characters)"
}

Champs :

  • verified : boolean - Si le hash est ancré dans la blockchain
  • hash : string - Hash vérifié
  • anchor_info : object | undefined - Présent uniquement si verified: true
    • transaction_id : string - TXID Bitcoin
    • block_height : number - Hauteur du bloc
    • confirmations : number - Nombre de confirmations
    • timestamp : string | undefined - ISO 8601 timestamp
    • fee : number | undefined - Frais en BTC
    • size : number | undefined - Taille en bytes
    • explorer_url : string - URL mempool
    • network : string - Réseau (signet)
    • op_return_data : string - Données OP_RETURN
    • anchored_at : string | undefined - ISO 8601 timestamp
  • context : object - Informations contextuelles
    • message : string | undefined - Message explicatif si non vérifié

🔑 Points importants

Transaction ID

  • Avant : UUID généré (ex: 4b38a41d-f429-4844-b6bd-01dfc5c42625)
  • Maintenant : TXID Bitcoin direct (ex: 7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825)
  • Format : 64 caractères hexadécimaux
  • Consultable : Directement sur mempool avec l'URL https://mempool2.4nkweb.com/fr/tx/{transaction_id}

Statuts

  • pending : Transaction créée mais non encore confirmée (0 confirmations)
  • confirmed : Transaction confirmée dans un bloc (≥1 confirmation)

Codes HTTP

  • 200 : Succès
  • 202 : Accepté (plus utilisé, maintenant 200) → 200 OK (transaction créée immédiatement)
  • 400 : Erreur de validation (champs manquants, format invalide)
  • 401 : Non autorisé (API key invalide)
  • 404 : Transaction non trouvée
  • 500 : Erreur serveur interne
  • 503 : Service indisponible (Bitcoin non connecté)

📝 Exemples d'utilisation

Créer un ancrage

curl -X POST http://dev3.4nkweb.com:3002/api/anchor/document \
  -H "x-api-key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "documentUid": "doc-12345",
    "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "callback_url": "http://local.4nkweb.com:3001/api/v1/anchors/callback"
  }'

Vérifier le statut

curl -X GET "http://dev3.4nkweb.com:3002/api/anchor/status/7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825" \
  -H "x-api-key: your-secure-api-key"

Vérifier un hash

curl -X POST http://dev3.4nkweb.com:3002/api/anchor/verify \
  -H "x-api-key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "txid": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825"
  }'

🔄 Callbacks

Si un callback_url est fourni lors de l'ancrage, l'API envoie une requête POST avec :

{
  "transaction_id": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "document_uid": "doc-12345",
  "status": "pending",
  "txid": "7b6f473879b3993812bc5eda39d801c1fd3f918cd35c9f6d922f1c3e95db9825",
  "confirmations": 0,
  "block_height": null
}

Le callback est envoyé en arrière-plan et n'affecte pas la réponse de l'API.