# 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

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

### Accès
- **URL** : `https://certificator.4nkweb.com` (via nginx proxy)
- **Port local** : `3010`
- **Protocole** : HTTPS (production) / HTTP (développement)
- **Format** : JSON

### Endpoints

#### GET `/`
Informations sur l'API

**Réponse** :
```json
{
  "service": "bitcoin-signet-anchor-api",
  "version": "1.0.0",
  "endpoints": {
    "health": "/health",
    "anchor": "/api/anchor/document",
    "verify": "/api/anchor/verify"
  }
}
```

#### GET `/health`
Vérifie l'état de l'API et de la connexion Bitcoin

**Authentification** : Non requise

**Réponse** :
```json
{
  "ok": true,
  "service": "anchor-api",
  "bitcoin": {
    "connected": true,
    "blocks": 152321
  },
  "timestamp": "2026-01-23T16:35:27.821Z"
}
```

#### POST `/api/anchor/document`
Ancre un document sur Bitcoin Signet

**Authentification** : Requise (header `x-api-key`)

**Body** :
```json
{
  "documentUid": "doc-123456",
  "hash": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234567890"
}
```

**Réponse** :
```json
{
  "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** :
```json
{
  "hash": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234567890",
  "txid": "56504e002d95301ebcfb4b30eaedc5d3fd9a448e121ffdce4f356b8d34169e85"
}
```

**Réponse** :
```json
{
  "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

```bash
# 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
```bash
# É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
```bash
# É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
```bash
# 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
```bash
bitcoin-cli -rpcconnect=192.168.1.103 -rpcport=38332 \
  -rpcuser=bitcoin -rpcpassword=bitcoin \
  getblockchaininfo
```

### Documentation
- **Référence complète** : [Bitcoin Core RPC API](https://developer.bitcoin.org/reference/rpc/)
- **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** :
```bash
# 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** :
```bash
./logtail.sh
```

#### `update-signet.sh`
Script de mise à jour du Bitcoin Signet

**Utilisation** :
```bash
./update-signet.sh [version]
./update-signet.sh --help
```

#### `mine.sh`
Script de mining (utilisé automatiquement par le conteneur)

**Utilisation** :
```bash
# 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** :
```bash
ZMQPUBRAWBLOCK=tcp://0.0.0.0:28332
```

#### `ZMQPUBRAWTX` (port 28333)
Publication des transactions brutes

**Configuration** :
```bash
ZMQPUBRAWTX=tcp://0.0.0.0:28333
```

#### `ZMQPUBHASHBLOCK` (port 28334)
Publication des hash de blocs

**Configuration** :
```bash
ZMQPUBHASHBLOCK=tcp://0.0.0.0:28334
```

### Utilisation

**Exemple Python** :
```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](https://github.com/bitcoin/bitcoin/blob/master/doc/zmq.md)

---

## 5. Interface Docker

### Description
Commandes Docker pour gérer le conteneur Bitcoin Signet.

### Commandes Principales

#### Gestion du Conteneur
```bash
# Démarrer
sudo docker run --env-file .env -d \
  --name bitcoin-signet-instance \
  -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
```bash
# 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
```bash
# 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
```bash
BLOCKPRODUCTIONDELAY=600
MINERENABLED=1
NBITS=1e0377ae
PRIVKEY=cVCKcgQf2ewV5miairzhrHJCPv4kMbMMBZeJvW5SMhFMSWVtCvXS
MINETO=
SIGNETCHALLENGE=5121028b8d4cea1b3d8582babc8405bc618fbbb281c0f64e6561aa85968251931cd0a651ae
```

#### RPC
```bash
RPCUSER=bitcoin
RPCPASSWORD=bitcoin
RPCBIND=0.0.0.0:38332
RPCALLOWIP=0.0.0.0/0
```

#### ZMQ
```bash
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
```bash
# Logs du conteneur
sudo docker logs bitcoin-signet-instance

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

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

#### Logs API
```bash
# 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")

---

## Résumé des Ports

| Port | Protocole | Interface | Description |
|------|-----------|-----------|-------------|
| 3010 | HTTP/HTTPS | API REST | API d'ancrage (via nginx) |
| 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 |

---

## 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-23