Template

2025-08-25 17:27:12 +02:00

14 KiB

Raw Blame History

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

# 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

14 KiB Raw Blame History

Référence API - 4NK Node

Vue d'Ensemble des APIs

1. API Bitcoin Core RPC

Informations Générales

Authentification

Méthode Cookie (Recommandée)

Méthode Credentials

Endpoints Principaux

getblockchaininfo

getblock

getrawtransaction

sendrawtransaction

getwalletinfo

Gestion des Erreurs

2. API Blindbit HTTP

Informations Générales

Endpoints

GET /health

POST /generate-address

GET /payments

GET /payments/{id}

Codes de Statut HTTP

3. API SDK Relay WebSocket

Informations Générales

Connexion

Format des Messages

Types de Messages

Messages de Synchronisation

Messages de Transaction

Commandes Client

Ping

GetStatus

4. API SDK Relay HTTP

Informations Générales

Endpoints

GET /health

GET /status

GET /relays

GET /metrics

POST /sync

5. Gestion des Erreurs

Erreurs WebSocket

Erreurs HTTP

6. Exemples d'Utilisation

Exemple Python - WebSocket

Exemple JavaScript - WebSocket

Exemple cURL - Bitcoin Core RPC

7. Limites et Quotas

Bitcoin Core RPC

Blindbit HTTP

SDK Relay WebSocket

SDK Relay HTTP

8. Sécurité

Authentification

Chiffrement

Bonnes Pratiques

9. Monitoring et Observabilité

Métriques à Surveiller

Logs

Alertes

14 KiB

Raw Blame History