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

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.0.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.0.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.0.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. 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