lecoffre_node/docs/miner_relay_rewards.md

Partage des Rewards entre Miner et Relay

Vue d'ensemble

Cette fonctionnalité permet au miner signet de partager automatiquement les rewards de bloc avec le relay. Quand le miner gagne un bloc, il envoie une partie des rewards (configurable) au relay.

Configuration

Variables d'environnement

Dans le fichier miner/miner.env :

# Adresse du miner pour recevoir sa part des rewards
COINBASE_ADDRESS=tb1qminer123456789012345678901234567890

# Adresse du relay pour recevoir sa part des rewards
RELAY_ADDRESS=tb1qrelay123456789012345678901234567890

# Ratio de partage (0.0 = 0%, 0.5 = 50%, 1.0 = 100%)
REWARD_SPLIT_RATIO=0.5

Paramètres de ligne de commande

Le miner accepte également ces paramètres :

--relay-address ADDRESS     # Adresse du relay
--reward-split-ratio RATIO  # Ratio de partage (0.0-1.0)

Fonctionnement

Mécanisme de partage

1. Détection du bloc : Le miner détecte qu'il a gagné un bloc
2. Calcul des rewards : Le reward total est divisé selon le ratio configuré
3. Création de la coinbase : La transaction coinbase est créée avec deux sorties :
   • Sortie 1 : Reward pour le miner (1 - ratio)
   • Sortie 2 : Reward pour le relay (ratio)

Exemple de partage

Avec REWARD_SPLIT_RATIO=0.5 et un reward de bloc de 5 BTC :

• Miner : 2.5 BTC (50%)
• Relay : 2.5 BTC (50%)

Code modifié

Fonction create_coinbase

def create_coinbase(height, value, spk, miner_tag='', relay_spk=None, reward_split_ratio=0.5):
    # ... code existant ...

    # Diviser les rewards entre miner et relay si relay_spk est fourni
    if relay_spk is not None and reward_split_ratio > 0:
        miner_value = int(value * (1 - reward_split_ratio))
        relay_value = int(value * reward_split_ratio)
        cb.vout = [
            CTxOut(miner_value, spk),      # Reward pour le miner
            CTxOut(relay_value, relay_spk) # Reward pour le relay
        ]
        logging.info(f"Coinbase split: miner={miner_value} sat, relay={relay_value} sat")
    else:
        cb.vout = [CTxOut(value, spk)]

    return cb

Gestion des adresses

Le miner gère automatiquement les cas où :

• L'adresse du relay n'est pas dans le wallet du miner
• L'adresse du relay est invalide
• Le wallet du relay n'est pas accessible

Dans ces cas, le miner utilise une adresse simple pour éviter les erreurs.

Logs

Le miner affiche des logs détaillés :

2025-09-20 02:03:20 INFO Coinbase split: miner=2500000000 sat, relay=2500000000 sat

Tests

Test de base

1. Démarrer le miner avec REWARD_SPLIT_RATIO=0.5
2. Vérifier les logs pour confirmer le partage
3. Vérifier que la transaction coinbase a deux sorties

Test avec différents ratios

• REWARD_SPLIT_RATIO=0.0 : Pas de partage (comportement original)
• REWARD_SPLIT_RATIO=0.5 : Partage égal (50/50)
• REWARD_SPLIT_RATIO=1.0 : Tout au relay (100%)

Avantages

1. Automatique : Le partage se fait automatiquement à chaque bloc
2. Configurable : Le ratio peut être ajusté selon les besoins
3. Robuste : Gestion des erreurs et des cas limites
4. Transparent : Logs détaillés pour le suivi

Limitations

1. Adresses externes : Les adresses du relay doivent être valides
2. Wallet du miner : Le miner doit avoir accès à son wallet
3. Réseau : Fonctionne uniquement en mode signet

Utilisation

Pour activer le partage des rewards :

1. Configurer RELAY_ADDRESS dans miner/miner.env
2. Définir REWARD_SPLIT_RATIO (ex: 0.5 pour 50%)
3. Redémarrer le miner
4. Surveiller les logs pour confirmer le fonctionnement

Exemple de configuration complète

# miner/miner.env
COINBASE_ADDRESS=tb1qminer123456789012345678901234567890
RELAY_ADDRESS=tsp1qqfzxxz9fht9w8pg9q8z0zseynt2prapktyx4eylm4jlwg5mukqg95qnmm2va956rhggul4vspjda368nlzvufahx70n67z66a2vgs5lspytmuvty
REWARD_SPLIT_RATIO=0.5

Cette configuration partagera 50% des rewards avec le relay à chaque bloc miné.