anchorage_layer_simple/docs/INTERFACES.md

Interfaces et IHM Disponibles

Auteur : Équipe 4NK Date : 2026-01-23 Version : 1.0

Vue d'Ensemble

Ce document liste toutes les interfaces et IHM (Interfaces Homme-Machine) disponibles dans le projet Bitcoin Signet Custom.

---

1. API REST d'Ancrage Bitcoin

Description

API REST HTTP/JSON pour ancrer des documents sur la blockchain Bitcoin Signet.

Accès

• URL : https://anchorage.certificator.4nkweb.com (via nginx proxy)
• Machine : 192.168.1.105 (bitcoin)
• Port local : 3010
• Protocole : HTTPS (production) / HTTP (développement)
• Format : JSON

Note : Il existe deux APIs d'ancrage distinctes :

• API Bitcoin : https://anchorage.certificator.4nkweb.com (machine bitcoin 192.168.1.105, port 3010) - API principale
• API LeCoffre : https://certificator.4nkweb.com (machine prod 192.168.1.103, port 3004) - API LeCoffre séparée

Endpoints

GET /

Informations sur l'API

Réponse :

{
  "service": "bitcoin-signet-anchor-api",
  "version": "1.0.0",
  "endpoints": {
    "health": "/health",
    "healthDetailed": "/health/detailed",
    "anchor": "/api/anchor/document",
    "verify": "/api/anchor/verify",
    "lockedUtxos": "/api/anchor/locked-utxos"
  }
}

GET /health

Vérifie l'état de l'API et de la connexion Bitcoin

Authentification : Non requise

Réponse :

{
  "ok": true,
  "service": "anchor-api",
  "bitcoin": {
    "connected": true,
    "blocks": 152321
  },
  "timestamp": "2026-01-23T16:35:27.821Z"
}

GET /health/detailed

Vérifie l'état détaillé de l'API, incluant l'état du mutex, des UTXOs verrouillés et de la connexion Bitcoin

Authentification : Non requise

Réponse (200 OK) :

{
  "ok": true,
  "service": "anchor-api",
  "mutex": {
    "locked": false,
    "waiting": 0,
    "timeout": 180000
  },
  "utxos": {
    "locked": 0,
    "locked_since": null,
    "stale_locks": 0,
    "stale_locks_details": []
  },
  "bitcoin": {
    "connected": true,
    "blocks": 152321,
    "chain": "signet",
    "rpc_timeout": 60000
  },
  "timestamp": "2026-01-23T16:35:27.821Z"
}

Réponse (503 Service Unavailable) : Si UTXOs verrouillés depuis > 10 min ou > 10 UTXOs verrouillés

{
  "ok": false,
  "service": "anchor-api",
  "mutex": {
    "locked": false,
    "waiting": 0,
    "timeout": 180000
  },
  "utxos": {
    "locked": 5,
    "locked_since": "2026-01-23T16:25:00.000Z",
    "stale_locks": 5,
    "stale_locks_details": [
      {
        "txid": "abc123...",
        "vout": 0,
        "minutes_locked": 15.5
      }
    ]
  },
  "bitcoin": {
    "connected": true,
    "blocks": 152321,
    "chain": "signet",
    "rpc_timeout": 60000
  },
  "timestamp": "2026-01-23T16:35:27.821Z"
}

POST /api/anchor/document

Ancre un document sur Bitcoin Signet

Authentification : Requise (header x-api-key)

Body :

{
  "documentUid": "doc-123456",
  "hash": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234567890"
}

Réponse :

{
  "txid": "56504e002d95301ebcfb4b30eaedc5d3fd9a448e121ffdce4f356b8d34169e85",
  "status": "confirmed",
  "confirmations": 0,
  "block_height": 152321
}

POST /api/anchor/verify

Vérifie si un hash est ancré sur Bitcoin Signet

Authentification : Requise (header x-api-key)

Body :

{
  "hash": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234567890",
  "txid": "56504e002d95301ebcfb4b30eaedc5d3fd9a448e121ffdce4f356b8d34169e85"
}

Réponse :

{
  "verified": true,
  "anchor_info": {
    "transaction_id": "56504e002d95301ebcfb4b30eaedc5d3fd9a448e121ffdce4f356b8d34169e85",
    "block_height": 152321,
    "confirmations": 0
  }
}

Documentation

• Fichier : api-anchorage/README.md
• Client de test : api-anchorage/src/test-client.js

Exemple d'utilisation

# Health check
curl https://certificator.4nkweb.com/health

# Ancrer un document
curl -X POST https://certificator.4nkweb.com/api/anchor/document \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "documentUid": "doc-123",
    "hash": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234567890"
  }'

---

2. Interface RPC Bitcoin Core

Description

Interface JSON-RPC pour contrôler et interagir avec le nœud Bitcoin Signet.

Accès

• Port : 38332
• Protocole : HTTP
• Format : JSON-RPC 2.0
• Authentification : Basic Auth (RPCUSER/RPCPASSWORD)

Commandes Principales

Informations sur la Blockchain

# État de la blockchain
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo

# Dernier bloc
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getbestblockhash

# Informations sur un bloc
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblock <hash>

Informations sur le Réseau

# État du réseau
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnetworkinfo

# Connexions actives
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getconnectioncount

Gestion du Wallet

# Informations sur le wallet
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getwalletinfo

# Solde
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getbalance

# Nouvelle adresse
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getnewaddress

# Transactions
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin listtransactions

Accès depuis l'Extérieur

bitcoin-cli -rpcconnect=192.168.1.103 -rpcport=38332 \
  -rpcuser=bitcoin -rpcpassword=bitcoin \
  getblockchaininfo

Documentation

• Référence complète : Bitcoin Core RPC API
• Documentation locale : docs/MAINTENANCE.md (section "Accès RPC et API")

---

3. Interface Ligne de Commande (CLI)

Description

Scripts shell et commandes pour interagir avec le système.

Scripts Disponibles

bitcoin-cli

Interface en ligne de commande pour Bitcoin Core

Utilisation :

# Depuis le conteneur
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin <commande>

# Exemples
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo
sudo docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getwalletinfo

logtail.sh

Visualisation des logs en temps réel

Utilisation :

./logtail.sh

update-signet.sh

Script de mise à jour du Bitcoin Signet

Utilisation :

./update-signet.sh [version]
./update-signet.sh --help

mine.sh

Script de mining (utilisé automatiquement par le conteneur)

Utilisation :

# Modifier le délai de production
sudo docker exec bitcoin-signet-instance bash -c "echo 60 > /root/.bitcoin/BLOCKPRODUCTIONDELAY.txt"

Documentation

• Scripts : Voir les fichiers .sh à la racine du projet
• Documentation : docs/MAINTENANCE.md

---

4. Interface ZMQ (ZeroMQ)

Description

Interface de messagerie pour recevoir des événements en temps réel du nœud Bitcoin.

Accès

• Ports : 28332, 28333, 28334
• Protocole : TCP
• Format : Messages binaires

Topics Disponibles

ZMQPUBRAWBLOCK (port 28332)

Publication des blocs bruts

Configuration :

ZMQPUBRAWBLOCK=tcp://0.0.0.0:28332

ZMQPUBRAWTX (port 28333)

Publication des transactions brutes

Configuration :

ZMQPUBRAWTX=tcp://0.0.0.0:28333

ZMQPUBHASHBLOCK (port 28334)

Publication des hash de blocs

Configuration :

ZMQPUBHASHBLOCK=tcp://0.0.0.0:28334

Utilisation

Exemple Python :

import zmq

context = zmq.Context()
socket = context.socket(zmq.SUB)
socket.connect("tcp://192.168.1.103:28332")
socket.setsockopt(zmq.SUBSCRIBE, b"rawblock")

while True:
    topic, body = socket.recv_multipart()
    print(f"Received block: {body.hex()}")

Documentation

• Référence : Bitcoin Core ZMQ

---

5. Interface Docker

Description

Commandes Docker pour gérer le conteneur Bitcoin Signet.

Commandes Principales

Gestion du Conteneur

# Démarrer (volume persistant pour conserver la chaîne)
sudo docker run --env-file .env -d \
  --name bitcoin-signet-instance \
  -v signet-bitcoin-data:/root/.bitcoin \
  -p 38332:38332 -p 38333:38333 \
  -p 28332:28332 -p 28333:28333 -p 28334:28334 \
  bitcoin-signet

# Arrêter
sudo docker stop bitcoin-signet-instance

# Redémarrer
sudo docker restart bitcoin-signet-instance

# Supprimer
sudo docker rm bitcoin-signet-instance

Logs

# Voir les logs
sudo docker logs bitcoin-signet-instance

# Suivre les logs en temps réel
sudo docker logs -f bitcoin-signet-instance

# Dernières lignes
sudo docker logs bitcoin-signet-instance --tail 50

Accès au Shell

# Accéder au shell du conteneur
sudo docker exec -it bitcoin-signet-instance bash

# Exécuter une commande
sudo docker exec bitcoin-signet-instance <commande>

Documentation

• Documentation : docs/MAINTENANCE.md (section "Gestion du Conteneur")

---

6. Interface de Configuration (.env)

Description

Fichier de configuration pour personnaliser le comportement du système.

Accès

• Fichier : .env (à la racine du projet)
• Format : Variables d'environnement (KEY=VALUE)

Variables Principales

Mining

BLOCKPRODUCTIONDELAY=600
MINERENABLED=1
NBITS=1e0377ae
PRIVKEY=cVCKcgQf2ewV5miairzhrHJCPv4kMbMMBZeJvW5SMhFMSWVtCvXS
MINETO=
SIGNETCHALLENGE=5121028b8d4cea1b3d8582babc8405bc618fbbb281c0f64e6561aa85968251931cd0a651ae

RPC

RPCUSER=bitcoin
RPCPASSWORD=bitcoin
RPCBIND=0.0.0.0:38332
RPCALLOWIP=0.0.0.0/0

ZMQ

ZMQPUBRAWBLOCK=tcp://0.0.0.0:28332
ZMQPUBRAWTX=tcp://0.0.0.0:28333
ZMQPUBHASHBLOCK=tcp://0.0.0.0:28334

Documentation

• Exemple : env.example
• Documentation : docs/MAINTENANCE.md (section "Configuration")

---

7. Interface de Logs

Description

Système de logs pour surveiller l'activité du nœud.

Accès

Logs Docker

# Logs du conteneur
sudo docker logs bitcoin-signet-instance

# Logs en temps réel
sudo docker logs -f bitcoin-signet-instance

Logs Bitcoin Core

# Logs de debug Bitcoin
sudo docker exec bitcoin-signet-instance tail -f /root/.bitcoin/signet/debug.log

Logs API

# Logs de l'API d'ancrage (si déployée avec PM2)
pm2 logs anchor-api

Documentation

• Script : logtail.sh
• Documentation : docs/MAINTENANCE.md (section "Monitoring")

---

8. Interface Mempool (Explorateur Blockchain)

Description

Interface web et API REST pour explorer la blockchain Bitcoin Signet.

Accès

• URL Web : http://localhost:3015 (local) ou https://mempool.4nkweb.com (production, machine bitcoin)
• API Backend : http://localhost:8999/api/v1/
• Protocole : HTTP/HTTPS
• Format : HTML (web) / JSON (API)

Endpoints API Principaux

GET /api/v1/backend-info

Informations sur le backend Mempool.

Réponse :

{
  "isElectrs": false,
  "network": "signet",
  "mempoolSize": 0,
  "blockCount": 716,
  "lastBlockHash": "...",
  "lastBlockTime": 1234567890
}

GET /api/v1/blocks

Liste des blocs récents.

GET /api/v1/blocks/:hash

Informations sur un bloc spécifique.

GET /api/v1/tx/:txid

Informations sur une transaction.

GET /api/v1/mempool

État actuel de la mempool.

Documentation Complète

Voir MEMPOOL.md pour la documentation complète.

---

Résumé des Ports

Port	Protocole	Interface	Description
3010	HTTP/HTTPS	API REST	API d'ancrage (via nginx)
3015	HTTP/HTTPS	Web	Mempool (explorateur blockchain)
3020	HTTP/HTTPS	Web	Dashboard de supervision
3021	HTTP/HTTPS	API REST	API Faucet
38332	HTTP	RPC Bitcoin	Interface JSON-RPC
38333	TCP	P2P Bitcoin	Réseau peer-to-peer
28332	TCP	ZMQ	Publication blocs bruts
28333	TCP	ZMQ	Publication transactions brutes
28334	TCP	ZMQ	Publication hash de blocs
8999	HTTP	API REST	Mempool Backend API (interne)

---

Recommandations d'Utilisation

Pour les Développeurs

• API REST : Pour intégrer l'ancrage dans des applications
• RPC Bitcoin : Pour des opérations avancées sur la blockchain
• CLI : Pour la maintenance et le dépannage

Pour les Administrateurs

• Docker CLI : Pour gérer le conteneur
• RPC Bitcoin : Pour surveiller l'état du nœud
• Logs : Pour le dépannage et le monitoring

Pour les Intégrations

• API REST : Interface principale pour les applications externes
• ZMQ : Pour recevoir des événements en temps réel
• RPC Bitcoin : Pour des opérations spécifiques non couvertes par l'API

---

Dernière mise à jour : 2026-01-24