4nk/anchorage_layer_simple
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
anchorage_layer_simple/docs/INTERFACES.md
ncantu 937646cc45 Daily backup to git cron, backup/restore scripts, docs 
**Motivations:**
- Export Signet and mining wallet backups to git with only 2 versions kept
- Document and add backup/restore scripts for signet and mining wallet

**Correctifs:**
- Backup-to-git uses SSH URL for passwordless cron; copy timestamped files only; prune to 2 versions; remove *-latest from backup repo

**Evolutions:**
- data/backup-to-git-cron.sh: daily export to git.4nkweb.com/4nk/backup
- save-signet-datadir-backup.sh, restore-signet-from-backup.sh, export-mining-wallet.sh, import-mining-wallet.sh
- features/backup-to-git-daily-cron.md, docs/MAINTENANCE.md backup section
- .gitignore: data/backup-to-git.log

**Pages affectées:**
- .gitignore, data/backup-to-git-cron.sh, docs/MAINTENANCE.md, features/backup-to-git-daily-cron.md
- save-signet-datadir-backup.sh, restore-signet-from-backup.sh, export-mining-wallet.sh, import-mining-wallet.sh
- Plus autres fichiers modifiés ou non suivis déjà présents dans le working tree
2026-02-04 03:07:57 +01:00

582 lines
13 KiB
Markdown
Raw Blame History

# 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** :
```json
{
"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** :
```json
{
"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)** :
```json
{
"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
```json
{
"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** :
```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 (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
```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")
---
## 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** :
```json
{
"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](./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
Reference in New Issue View Git Blame Copy Permalink