4NK_node/docs/API.md

Référence API - 4NK_node

Ce guide documente toutes les APIs disponibles dans l'infrastructure 4NK_node, incluant les interfaces RPC, HTTP et WebSocket.

Vue d'Ensemble des APIs

L'infrastructure 4NK_node expose plusieurs interfaces pour différents types d'interactions :

• Bitcoin Core RPC : Interface JSON-RPC pour Bitcoin
• Blindbit HTTP : API REST pour les paiements silencieux
• SDK Relay WebSocket : Interface temps réel pour les clients
• SDK Relay HTTP : API REST pour les opérations de gestion
• SDK Storage HTTP : API REST de stockage clé/valeur TTL

1. API Bitcoin Core RPC

Informations Générales

• Protocole : JSON-RPC
• Port : 18443
• Authentification : Cookie ou credentials
• Réseau : Signet
• Base URL : http://localhost:18443

Authentification

Méthode Cookie (Recommandée)

# Le cookie est automatiquement utilisé par Bitcoin Core
curl -X POST http://localhost:18443 \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc": "1.0", "id": "test", "method": "getblockchaininfo", "params": []}'

Méthode Credentials

curl -X POST http://localhost:18443 \
  -H "Content-Type: application/json" \
  -u "username:password" \
  --data '{"jsonrpc": "1.0", "id": "test", "method": "getblockchaininfo", "params": []}'

Endpoints Principaux

getblockchaininfo

Récupère les informations sur la blockchain.

Requête :

{
  "jsonrpc": "1.0",
  "id": "test",
  "method": "getblockchaininfo",
  "params": []
}

Réponse :

{
  "result": {
    "chain": "signet",
    "blocks": 12345,
    "headers": 12345,
    "bestblockhash": "0000000000000000000000000000000000000000000000000000000000000000",
    "difficulty": 1.0,
    "mediantime": 1234567890,
    "verificationprogress": 1.0,
    "initialblockdownload": false,
    "chainwork": "0000000000000000000000000000000000000000000000000000000000000000",
    "size_on_disk": 123456789,
    "pruned": false,
    "pruneheight": null,
    "automatic_pruning": false,
    "prune_target_size": null,
    "warnings": ""
  },
  "error": null,
  "id": "test"
}

getblock

Récupère les informations d'un bloc spécifique.

Requête :

{
  "jsonrpc": "1.0",
  "id": "test",
  "method": "getblock",
  "params": ["blockhash", 2]
}

Paramètres :

• blockhash : Hash du bloc
• verbosity : Niveau de détail (0, 1, 2)

getrawtransaction

Récupère une transaction brute.

Requête :

{
  "jsonrpc": "1.0",
  "id": "test",
  "method": "getrawtransaction",
  "params": ["txid", true]
}

sendrawtransaction

Envoie une transaction brute au réseau.

Requête :

{
  "jsonrpc": "1.0",
  "id": "test",
  "method": "sendrawtransaction",
  "params": ["hexstring"]
}

getwalletinfo

Récupère les informations du wallet.

Requête :

{
  "jsonrpc": "1.0",
  "id": "test",
  "method": "getwalletinfo",
  "params": []
}

Gestion des Erreurs

Erreur typique :

{
  "result": null,
  "error": {
    "code": -32601,
    "message": "Method not found"
  },
  "id": "test"
}

Codes d'erreur courants :

• -32601 : Méthode non trouvée
• -32602 : Paramètres invalides
• -32603 : Erreur interne
• -1 : Erreur d'authentification

2. API Blindbit HTTP

Informations Générales

• Protocole : HTTP REST
• Port : 8000
• Base URL : http://localhost:8000
• Content-Type : application/json

Endpoints

GET /health

Vérifie la santé du service.

Requête :

curl -X GET http://localhost:8000/health

Réponse :

{
  "status": "healthy",
  "timestamp": "2024-12-19T14:30:00Z",
  "version": "1.1.0"
}

POST /generate-address

Génère une adresse de paiement silencieux.

Requête :

{
  "label": "payment_001",
  "amount": 0.001
}

Réponse :

{
  "address": "bc1p...",
  "label": "payment_001",
  "amount": 0.001,
  "created_at": "2024-12-19T14:30:00Z"
}

GET /payments

Liste les paiements reçus.

Requête :

curl -X GET "http://localhost:8000/payments?limit=10&offset=0"

Paramètres de requête :

• limit : Nombre maximum de résultats (défaut: 10)
• offset : Décalage pour la pagination (défaut: 0)

Réponse :

{
  "payments": [
    {
      "id": "payment_001",
      "address": "bc1p...",
      "amount": 0.001,
      "txid": "txid...",
      "block_height": 12345,
      "created_at": "2024-12-19T14:30:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

GET /payments/{id}

Récupère les détails d'un paiement spécifique.

Requête :

curl -X GET http://localhost:8000/payments/payment_001

Réponse :

{
  "id": "payment_001",
  "address": "bc1p...",
  "amount": 0.001,
  "txid": "txid...",
  "block_height": 12345,
  "confirmations": 6,
  "created_at": "2024-12-19T14:30:00Z",
  "status": "confirmed"
}

Codes de Statut HTTP

• 200 : Succès
• 201 : Créé
• 400 : Requête invalide
• 404 : Ressource non trouvée
• 500 : Erreur serveur

3. API SDK Relay WebSocket

Informations Générales

• Protocole : WebSocket/WSS
• Port : 8090
• URL : ws://localhost:8090 ou wss://localhost:8090
• Format : JSON

Connexion

const ws = new WebSocket('ws://localhost:8090');

ws.onopen = function() {
    console.log('Connexion WebSocket établie');
};

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    console.log('Message reçu:', message);
};

ws.onerror = function(error) {
    console.error('Erreur WebSocket:', error);
};

ws.onclose = function() {
    console.log('Connexion WebSocket fermée');
};

Format des Messages

Tous les messages suivent le format JSON suivant :

{
  "type": "message_type",
  "id": "unique_message_id",
  "timestamp": 1234567890,
  "data": {
    // Données spécifiques au type de message
  }
}

Types de Messages

Messages de Synchronisation

StateSync :

{
  "type": "StateSync",
  "id": "state_001",
  "timestamp": 1234567890,
  "data": {
    "relay_id": "relay-1",
    "state": "running",
    "version": "1.1.0",
    "uptime": 3600
  }
}

HealthSync :

{
  "type": "HealthSync",
  "id": "health_001",
  "timestamp": 1234567890,
  "data": {
    "relay_id": "relay-1",
    "status": "healthy",
    "uptime": 3600,
    "cpu_usage": 15.5,
    "memory_usage": 45.2
  }
}

MetricsSync :

{
  "type": "MetricsSync",
  "id": "metrics_001",
  "timestamp": 1234567890,
  "data": {
    "relay_id": "relay-1",
    "messages_sent": 1000,
    "messages_received": 950,
    "sync_errors": 5,
    "connected_relays": 3
  }
}

Messages de Transaction

TransactionReceived :

{
  "type": "TransactionReceived",
  "id": "tx_001",
  "timestamp": 1234567890,
  "data": {
    "txid": "txid...",
    "amount": 0.001,
    "address": "bc1p...",
    "block_height": 12345,
    "confirmations": 1
  }
}

BlockScanned :

{
  "type": "BlockScanned",
  "id": "block_001",
  "timestamp": 1234567890,
  "data": {
    "block_height": 12345,
    "block_hash": "hash...",
    "transactions_count": 150,
    "silent_payments_found": 2
  }
}

Commandes Client

Ping

{
  "type": "ping",
  "id": "ping_001",
  "timestamp": 1234567890,
  "data": {}
}

Réponse :

{
  "type": "pong",
  "id": "ping_001",
  "timestamp": 1234567890,
  "data": {
    "relay_id": "relay-1"
  }
}

GetStatus

{
  "type": "get_status",
  "id": "status_001",
  "timestamp": 1234567890,
  "data": {}
}

Réponse :

{
  "type": "status",
  "id": "status_001",
  "timestamp": 1234567890,
  "data": {
    "relay_id": "relay-1",
    "status": "running",
    "uptime": 3600,
    "connected_relays": 3,
    "last_block_height": 12345
  }
}

4. API SDK Relay HTTP

Informations Générales

• Protocole : HTTP REST
• Port : 8091
• Base URL : http://localhost:8091
• Content-Type : application/json

Endpoints

GET /health

Vérifie la santé du relais.

Requête :

curl -X GET http://localhost:8091/health

Réponse :

{
  "status": "healthy",
  "relay_id": "relay-1",
  "uptime": 3600,
  "version": "1.1.0",
  "connected_relays": 3
}

GET /status

Récupère le statut détaillé du relais.

Requête :

curl -X GET http://localhost:8091/status

Réponse :

{
  "relay_id": "relay-1",
  "status": "running",
  "uptime": 3600,
  "version": "1.0.0",
  "connected_relays": 3,
  "last_block_height": 12345,
  "sync_metrics": {
    "messages_sent": 1000,
    "messages_received": 950,
    "sync_errors": 5
  }
}

GET /relays

Liste les relais connectés.

Requête :

curl -X GET http://localhost:8091/relays

Réponse :

{
  "relays": [
    {
      "relay_id": "relay-2",
      "address": "sdk_relay_2:8090",
      "status": "connected",
      "connected_since": 1234567890,
      "last_heartbeat": 1234567890
    },
    {
      "relay_id": "relay-3",
      "address": "sdk_relay_3:8090",
      "status": "connected",
      "connected_since": 1234567890,
      "last_heartbeat": 1234567890
    }
  ]
}

GET /metrics

Récupère les métriques de synchronisation.

Requête :

curl -X GET http://localhost:8091/metrics

Réponse :

{
  "messages_sent": 1000,
  "messages_received": 950,
  "sync_errors": 5,
  "last_sync_timestamp": 1234567890,
  "connected_relays": 3,
  "mesh_health": 0.95
}

POST /sync

Force une synchronisation manuelle.

Requête :

{
  "sync_type": "StateSync",
  "target_relay": "relay-2"
}

Réponse :

{
  "success": true,
  "message": "Synchronisation initiée",
  "sync_id": "sync_001"
}

5. API SDK Storage HTTP

Informations générales

• Protocole : HTTP REST
• Port interne : 8081 (proxifié)
• Base URL via proxy : https://<hôte>/storage/
• Content-Type : application/json

Endpoints

POST /storage/store

Corps JSON : { key: string(hex64), value: string(hex), ttl?: number(seconds) }

Réponses :

• 200 OK : { "message": "Data stored successfully." }
• 400/409 : message d’erreur explicite

GET /storage/retrieve/{key}

Paramètre key : hex 64 caractères.

Réponses :

• 200 OK : { key, value } avec value en hex
• 400/404 : message d’erreur

Notes :

• Sans ttl, si l’application est lancée avec --permanent, la donnée est permanente; sinon TTL par défaut 86400s.
• Les données sont stockées sur volume persistant sdk_storage_data.

6. Gestion des Erreurs

Erreurs WebSocket

Erreur de connexion :

{
  "type": "error",
  "id": "error_001",
  "timestamp": 1234567890,
  "data": {
    "code": "CONNECTION_ERROR",
    "message": "Impossible de se connecter au relais",
    "details": "Connection refused"
  }
}

Erreur de message :

{
  "type": "error",
  "id": "error_002",
  "timestamp": 1234567890,
  "data": {
    "code": "INVALID_MESSAGE",
    "message": "Format de message invalide",
    "details": "Missing required field 'type'"
  }
}

Erreurs HTTP

Erreur 400 :

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Requête invalide",
    "details": "Missing required parameter 'relay_id'"
  }
}

Erreur 500 :

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Erreur interne du serveur",
    "details": "Database connection failed"
  }
}

6. Exemples d'Utilisation

Exemple Python - WebSocket

import asyncio
import websockets
import json

async def connect_to_relay():
    uri = "ws://localhost:8090"
    async with websockets.connect(uri) as websocket:
        # Envoyer un ping
        ping_message = {
            "type": "ping",
            "id": "ping_001",
            "timestamp": int(time.time()),
            "data": {}
        }
        await websocket.send(json.dumps(ping_message))

        # Écouter les messages
        async for message in websocket:
            data = json.loads(message)
            print(f"Message reçu: {data}")

asyncio.run(connect_to_relay())

Exemple JavaScript - WebSocket

const ws = new WebSocket('ws://localhost:8090');

ws.onopen = function() {
    // Envoyer un ping
    const pingMessage = {
        type: 'ping',
        id: 'ping_001',
        timestamp: Date.now(),
        data: {}
    };
    ws.send(JSON.stringify(pingMessage));
};

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    console.log('Message reçu:', message);
};

Exemple cURL - Bitcoin Core RPC

# Récupérer les informations de la blockchain
curl -X POST http://localhost:18443 \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "1.0",
    "id": "test",
    "method": "getblockchaininfo",
    "params": []
  }'

# Récupérer un bloc spécifique
curl -X POST http://localhost:18443 \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "1.0",
    "id": "test",
    "method": "getblock",
    "params": ["blockhash", 2]
  }'

7. Limites et Quotas

Bitcoin Core RPC

• Taux limite : 1000 requêtes/minute par défaut
• Taille des requêtes : 32MB maximum
• Connexions simultanées : 125 par défaut

Blindbit HTTP

• Taux limite : 100 requêtes/minute
• Taille des requêtes : 10MB maximum
• Connexions simultanées : 50

SDK Relay WebSocket

• Connexions simultanées : 1000 par relais
• Taille des messages : 1MB maximum
• Heartbeat : 30 secondes

SDK Relay HTTP

• Taux limite : 200 requêtes/minute
• Taille des requêtes : 5MB maximum
• Connexions simultanées : 100

8. Sécurité

Authentification

• Bitcoin Core : Cookie d'authentification
• Blindbit : À définir selon les besoins
• SDK Relay : Authentification WebSocket (optionnelle)

Chiffrement

• RPC Bitcoin : HTTP (non chiffré en local)
• HTTP Blindbit : HTTP (non chiffré en local)
• WebSocket SDK Relay : WSS (chiffré)

Bonnes Pratiques

• Utiliser HTTPS/WSS en production
• Implémenter l'authentification appropriée
• Valider toutes les entrées
• Limiter les taux de requêtes
• Monitorer les accès

9. Monitoring et Observabilité

Métriques à Surveiller

• Latence des APIs : Temps de réponse
• Taux d'erreur : Pourcentage d'erreurs
• Débit : Requêtes par seconde
• Utilisation des ressources : CPU, mémoire, réseau

Logs

• Logs d'accès : Requêtes et réponses
• Logs d'erreur : Erreurs et exceptions
• Logs de performance : Métriques de performance

Alertes

• Erreurs 5xx : Erreurs serveur
• Latence élevée : Temps de réponse > 1s
• Taux d'erreur élevé : > 5%
• Services indisponibles : Health checks en échec