# Miner Bitcoin Signet – Documentation

**Auteur** : Équipe 4NK  
**Date** : 2026-02-02  
**Version** : 1.0

## Vue d’ensemble

Le **miner** est un script Python dérivé de `contrib/signet/miner.py` de Bitcoin Core. Il permet de miner des blocs sur une chaîne Bitcoin Signet custom en produisant des blocs signés avec la clé du signet (PRIVKEY) et en respectant le SIGNETCHALLENGE.

**Emplacement dans le projet :**

- Racine du projet : `/home/ncantu/Bureau/code/bitcoin/`
- Script principal : `miner` (à la racine du projet)
- Imports et framework de test : `miner_imports/` (ce répertoire et son contenu)
- Script shell de boucle de minage : `mine.sh` (à la racine)
- Point d’entrée conteneur : `run.sh` (démarre bitcoind, importe la clé, lance `mine.sh` si `MINERENABLED=1`)

## Rôle de `miner_imports/`

Le répertoire `miner_imports/` contient le **test_framework** utilisé par le script `miner` :

- **test_framework/** : modules Python (messages, blocktools, script, etc.) issus du framework de tests fonctionnels de Bitcoin Core, nécessaires pour construire et sérialiser blocs, transactions et PSBT signet.
- Le script `miner` ajoute `miner_imports` au `sys.path` et importe depuis `test_framework` (blocktools, messages, script, etc.).

Aucun exécutable de minage n’est dans `miner_imports/` : l’exécutable est le fichier `miner` à la racine du projet.

## Invocation du miner

Dans le conteneur Docker (voir `mine.sh` et `run.sh`) :

```bash
bitcoin-cli -rpcwallet=custom_signet getblocktemplate '{"rules": ["segwit", "signet"]}' | \
  miner --cli="bitcoin-cli -datadir=/root/.bitcoin" generate --grind-cmd="bitcoin-util grind" \
  --address=$ADDR --nbits=$NBITS --set-block-time=$(date +%s)
```

- **--cli** : commande `bitcoin-cli` (avec `-datadir` dans le conteneur).
- **generate** : sous-commande pour miner des blocs (boucle getblocktemplate → signer PSBT signet → grind → submitblock).
- **--grind-cmd** : commande pour le proof-of-work (grind du header).
- **--address** : adresse de récompense de bloc.
- **--nbits** : difficulté cible (ex. `1e0377ae`).
- **--set-block-time** : timestamp du bloc.

La variable d’environnement **PRIVKEY** doit être définie (exportée par `mine.sh` depuis `.env`) pour que le miner puisse signer le PSBT signet via `descriptorprocesspsbt` / `walletprocesspsbt`.

## Comportement de `bitcoin-cli` et option `-signet`

Le miner appelle Bitcoin RPC via une fonction interne qui construisait toujours la commande en ajoutant **-signet** aux arguments de `bitcoin-cli`. Lorsque `--cli="bitcoin-cli -datadir=/root/.bitcoin"` est utilisé, la config du datadir (ex. `bitcoin.conf` avec `signet=1`) définit déjà le réseau signet. Ajouter `-signet` en plus pouvait provoquer un échec de connexion RPC (exit 1).

**Correctif appliqué (dans le script `miner`)** : ne pas ajouter `-signet` lorsque la commande cli contient déjà `-datadir=`.

```python
# Quand --cli inclut -datadir=, la config du datadir sélectionne déjà le signet
if not any("-datadir=" in x for x in basecmd):
    basecmd = basecmd + ["-signet"]
cmd = basecmd + args
```

Référence : correctif documenté dans le dépôt (rechercher « bitcoin_cli » et « -signet » dans le fichier `miner`).

## Descriptor wallet et clé P2PK

Le miner signet doit signer des transactions vers le SIGNETCHALLENGE (script P2PK). La clé privée doit être importée dans le wallet comme descriptor **pk()** (P2PK), et non **wpkh()**, pour que `walletprocesspsbt` puisse signer. L’import est fait dans `run.sh` au démarrage du conteneur lorsque `MINERENABLED=1`.

Détails et dépannage : voir **docs/TROUBLESHOOTING_MINING.md** et **docs/SOLUTION_MINING.md** à la racine du projet.

## Références

- **Racine du projet** : `/home/ncantu/Bureau/code/bitcoin/`
- **Script miner** : `miner` (racine)
- **Boucle de minage** : `mine.sh` (racine)
- **Démarrage conteneur** : `run.sh`, **docs/MAINTENANCE.md** (section Mining)
- **Dépannage mining** : **docs/TROUBLESHOOTING_MINING.md**
- **Solution PSBT / descriptor** : **docs/SOLUTION_MINING.md**
- **Configuration** : **docs/ENVIRONMENT.md** (MINERENABLED, BLOCKPRODUCTIONDELAY, NBITS, PRIVKEY, etc.)