Faire tourner un nœud OpenFiat

1. 01

   Préparez la machine

   Un serveur Debian ou Ubuntu à jour, un pare-feu et une horloge précise. L’horloge importe plus qu’il n’y paraît : les enregistrements portent des timestamps et des heures d’expiration, et une horloge dérivée fait rejeter par un nœud des données valides.

   shellCopier

   # Debian 12 / Ubuntu 24.04, as root
   apt update && apt install -y ca-certificates curl gnupg ufw chrony
   
   # Clock drift breaks signature and expiry checks — keep NTP running.
   systemctl enable --now chrony

2. 02

   Installez le nœud

   Compilez depuis les sources et faites tourner le résultat sous systemd — aucune version n’a encore été taguée, c’est donc la seule façon d’obtenir un binaire aujourd’hui, et le reste de ce manuel le suppose. Ne recourez à Docker que pour tester localement ou monter un cluster jetable.
3. 03

   Générez le portefeuille du nœud

   Il n’y a pas de format « d’identité de nœud » distinct — l’identité d’un nœud est un vrai wallet.json de la CLI Solana, le même fichier que produit solana-keygen. Sa seed est réutilisée à la fois pour l’identité de gossip/pair du nœud et pour la clé de signature Solana. Gardez le fichier — si vous le perdez, le nœud rejoint en inconnu et recommence à bâtir sa réputation de zéro.

   shellCopier

   # The node's identity IS a Solana CLI-format wallet.json — the same
   # file "solana-keygen new" produces (its own seed is reused for the
   # node's gossip/P2P keypair too, see crates/cli's load_or_generate_wallet).
   # There is no separate "node identity" format or command.
   solana-keygen new --outfile /etc/openfiat/wallet.json
   chmod 600 /etc/openfiat/wallet.json
   solana-keygen pubkey /etc/openfiat/wallet.json

4. 04

   Définissez l’environnement

   openfiat-node n’a pas de fichier de configuration propre — chaque réglage est une variable d’environnement, lue une fois au démarrage : où vivent les données, sur quelle adresse écouter, quels pairs composer au démarrage et (en option) quel endpoint RPC Solana utiliser. Les pairs de bootstrap doivent être un multiaddr/IP statique, pas un nom d’hôte — le bootstrap par DNS ne résout pas.

   shellCopier

   # There is no config file and no environment variables. Every
   # setting is a flag on the systemd unit's ExecStart below, so
   # "systemctl cat openfiat-node" shows exactly what a running node was
   # given, and "openfiat-node --help" is the whole surface.
   #
   # Try it in the foreground first — the node prints the addresses it is
   # reachable at and whether it reached Solana:
   
   openfiat-node \
     --ledger /var/lib/openfiat \
     --identity /etc/openfiat/wallet.json \
     --rpc-bind-address 0.0.0.0:7080 \
     --gossip-bind-address /ip4/0.0.0.0/udp/4001/quic-v1 \
     --entrypoint /ip4/84.32.223.111/udp/4001/quic-v1/p2p/12D3KooWK9hQ7TwbfvFiaAxUbRFCkdhS7iEpAJDnewNL1anyREQ1 \
     --solana-rpc-url https://api.devnet.solana.com
   
   # Omit --solana-rpc-url to stay GossipOnly, the safe default: the node
   # still serves the marketplace, but its on-chain answers come
   # second-hand from peers. Never put a real endpoint or API key anywhere
   # version controlled — it belongs in the unit file on the server.
   #
   # Add --ipfs-api-url http://127.0.0.1:5001 to pin protocol content and
   # earn the full reward share, and --retention archival to keep the whole
   # history instead of a rolling 30 days.

5. 05

   Ouvrez les bons ports

   Les pairs atteignent le nœud par UDP parce que QUIC est le transport principal — c’est le port que les gens oublient le plus. Un port TCP sert JSON-RPC, WebSocket, REST, santé et métriques ensemble ; gardez-le privé si vous ne voulez pas servir de clients publiquement.

   shellCopier

   ufw default deny incoming
   ufw allow 22/tcp                 # keep your own access
   ufw allow 4001/udp               # libp2p, QUIC — the port people most often forget
   ufw allow 443/tcp                # once nginx terminates TLS in front (see below)
   ufw allow 7080/tcp               # only if the node is exposed directly, without a proxy
   ufw enable && ufw status verbose

6. 06

   Servez le réseau : rendez votre nœud atteignable

   C’est l’étape qui transforme un nœud, d’une chose qui observe le réseau en une chose qui le porte. Placez nginx devant et obtenez un certificat, puis indiquez au nœud son URL publique avec --public-rpc-url et il s’annonce pour que portefeuilles, explorateurs et l’app web OpenFiat elle-même puissent l’utiliser. L’ordre compte : nginx sur HTTP simple d’abord, puis certbot ajoute TLS — une configuration qui nomme déjà un certificat ne peut pas démarrer, si bien que certbot échoue avant de pouvoir émettre celui qui aurait résolu le problème. Un certificat n’est pas un ornement optionnel : une page servie en HTTPS ne peut pas ouvrir de connexion HTTP simple, donc un nœud sans certificat est invisible pour tout navigateur, aussi sain soit-il.

   /etc/nginx/sites-available/openfiat-nodeCopier

   # /etc/nginx/sites-available/openfiat-node
   #
   # HTTP only at this stage, with NO TLS directives. certbot --nginx works
   # by running "nginx -t" and editing this file, so a config that already
   # points at a certificate cannot load, nginx will not start, and certbot
   # fails before it can issue the certificate that would have fixed it.
   server {
       listen 80;
       listen [::]:80;
       server_name openfiat.example.com;
   
       location / {
           proxy_pass http://127.0.0.1:7080;
           proxy_http_version 1.1;
   
           # The node serves its WebSocket event stream on the same port;
           # without these the stream downgrades to a plain request and
           # subscriptions silently never deliver.
           proxy_set_header Upgrade    $http_upgrade;
           proxy_set_header Connection "upgrade";
   
           proxy_set_header Host              $host;
           proxy_set_header X-Real-IP         $remote_addr;
           proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
   
           # Do NOT add CORS headers here — the node already sets them, and
           # two Access-Control-Allow-Origin headers on one response make
           # browsers reject it while curl sees a clean 200.
           proxy_read_timeout 300s;
       }
   }

   shellCopier

   # The A record must already resolve for the world — certbot proves
   # control of the name over port 80. Check a public resolver, not your
   # own machine, whose cache can be stale:
   dig +short @8.8.8.8 openfiat.example.com
   
   ln -s /etc/nginx/sites-available/openfiat-node /etc/nginx/sites-enabled/
   nginx -t && systemctl reload nginx
   curl -s http://openfiat.example.com/health    # ok, before any certificate
   
   apt install -y certbot python3-certbot-nginx
   certbot --nginx -d openfiat.example.com
   
   # certbot edits the server block in place: it adds listen 443 ssl, the
   # certificate paths, and a redirect from :80. The location block and its
   # proxy headers carry over. Renewal installs itself as a systemd timer.
   # Do not hand-write a 443 block afterwards — certbot manages that one.
   
   # Then tell the network this node can be reached directly:
   #   openfiat-node --public-rpc-url https://openfiat.example.com

7. 07

   Faites-en un service

   Sous systemd, le nœud redémarre après un plantage ou un reboot, et bénéficie d’un délai d’arrêt assez long pour que la base de données se vide proprement au lieu d’être tuée au milieu d’une écriture.

   openfiat-node.serviceCopier

   # /etc/systemd/system/openfiat-node.service
   [Unit]
   Description=OpenFiat node
   Documentation=https://docs.openfiat.network
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   Type=simple
   User=openfiat
   Group=openfiat
   ExecStart=/usr/local/bin/openfiat-node \
       --ledger /var/lib/openfiat \
       --identity /etc/openfiat/wallet.json \
       --rpc-bind-address 0.0.0.0:7080 \
       --gossip-bind-address /ip4/0.0.0.0/udp/4001/quic-v1 \
       --entrypoint /ip4/84.32.223.111/udp/4001/quic-v1/p2p/12D3KooWK9hQ7TwbfvFiaAxUbRFCkdhS7iEpAJDnewNL1anyREQ1 \
       --solana-rpc-url https://api.devnet.solana.com
   WorkingDirectory=/var/lib/openfiat
   Restart=on-failure
   RestartSec=5s
   
   # openfiat-node handles SIGTERM itself (graceful shutdown) rather than
   # needing systemd to force-kill it; this gives that shutdown path a
   # reasonable window before systemd escalates to SIGKILL.
   TimeoutStopSec=30s
   
   NoNewPrivileges=true
   ProtectSystem=strict
   ProtectHome=true
   ReadWritePaths=/var/lib/openfiat
   PrivateTmp=true
   
   # AF_NETLINK is required, not optional: binding a wildcard address makes
   # libp2p enumerate this host's interfaces, and that goes over a netlink
   # socket. Without it the QUIC listener fails and the gossip actor panics
   # while the HTTP thread survives — so systemd reports the unit active
   # and the node looks healthy while serving nothing.
   RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
   
   [Install]
   WantedBy=multi-user.target

   shellCopier

   useradd --system --create-home --home-dir /var/lib/openfiat --shell /usr/sbin/nologin openfiat
   install -m 755 openfiat-node /usr/local/bin/openfiat-node
   mkdir -p /etc/openfiat
   chown -R openfiat:openfiat /var/lib/openfiat
   
   systemctl daemon-reload
   systemctl enable --now openfiat-node
   journalctl -u openfiat-node -f

8. 08

   Laissez-le rattraper

   Au lieu de rejouer tout l’historique, un nouveau nœud peut découvrir et importer un snapshot annoncé par un pair de l’état actuel du marché (OFS-1300) — de vraies méthodes JSON-RPC, pas un outil séparé : getLatestSnapshot, getCheckpointHeight. Signature, version du protocole et racine d’état doivent toutes correspondre avant qu’on ne s’y fie.

   shellCopier

   # Snapshot sync (OFS-1300) is real JSON-RPC, not a separate CLI —
   # a new node discovers and imports a peer-announced snapshot instead of
   # replaying all history:
   curl -s -X POST http://localhost:7080/rpc -H 'content-type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"getLatestSnapshot","params":{}}'
   curl -s -X POST http://localhost:7080/rpc -H 'content-type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"getCheckpointHeight","params":{}}'

9. 09

   Vérifiez qu’il est sain

   GET /health confirme que le processus tourne ; getChainStatus par JSON-RPC dit s’il est GossipOnly ou RpcConnected, et son blockhash courant s’il est le dernier.

   shellCopier

   # Is it up, and which mode is it in?
   curl -s http://localhost:7080/health
   # ok
   
   curl -s -X POST http://localhost:7080/rpc -H 'content-type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"getChainStatus","params":{}}'
   # {"jsonrpc":"2.0","id":1,"result":{"mode":"GossipOnly","blockhash":null,"slot":null,"age_ms":null}}
   # ("RpcConnected" with a real blockhash once --solana-rpc-url is set)
   
   # The addresses your node is reachable at are in its own log — give one
   # of these to another operator as their --entrypoint:
   journalctl -u openfiat-node | grep "reachable at a new address"

10. 10

    Il fait déjà partie du réseau

    Il n’y a pas d’étape « annoncer » distincte — dès qu’un nœud a des pairs de bootstrap, il propage par gossip et est propagé automatiquement ; personne ne l’approuve. Mettre en stake, publier des métadonnées dans le registre de services, adhérer à des litiges et émettre des votes de gouvernance sont des actions distinctes, guidées par portefeuille, qu’un client réalise contre le nœud en cours d’exécution — voir le guide de participation correspondant à chacune.

    Un nœud met OPEN en stake pour devenir un participant actif. Mais le stake n’achète pas de réputation : un opérateur peu performant ne peut pas se rattraper en misant davantage. La priorité effective combine réputation, stake et performance réseau mesurée.
11. 11

    Surveillez-le

    Les signaux qui prédisent vraiment les ennuis sont les pairs connectés, le mode de la chaîne (GossipOnly vs RpcConnected) et l’âge du blockhash. Alertez sur ceux-là et vous saurez avant vos utilisateurs.

    prometheus.ymlCopier

    # /etc/prometheus/prometheus.yml — same port as everything else,
    # no separate metrics listener to configure on the node's own side.
    scrape_configs:
      - job_name: openfiat-node
        static_configs:
          - targets: ["127.0.0.1:7080"]

12. 12

    Gardez-le à jour

    Arrêtez, remplacez le binaire, démarrez. Les nœuds se mettent à jour un par un, donc le réseau n’a jamais besoin d’un arrêt coordonné, et les événements de gossip manqués sont rejoués au démarrage.

    shellCopier

    systemctl stop openfiat-node        # SIGTERM, lets RocksDB flush
    # docker: docker compose pull node && docker compose up -d node
    install -m 0755 ./openfiat-node /usr/local/bin/
    systemctl start openfiat-node
    
    # Missed gossip events replay automatically on start.
    journalctl -u openfiat-node -f

13. 13

    Sauvegardez ce qui ne peut pas être régénéré

    L’état du marché peut toujours être resynchronisé depuis un snapshot. Le portefeuille ne peut pas être régénéré. Les soldes et la garde vivent sur Solana, pas sur votre disque.

    shellCopier

    # Back up what cannot be re-derived. Marketplace state can always be
    # re-synced from a snapshot; the wallet cannot be regenerated.
    tar czf openfiat-wallet-$(date +%F).tar.gz /etc/openfiat/wallet.json
    
    # Authoritative financial state lives on Solana, not on the node's own
    # RocksDB volume.

Chaque nœud conforme expose la même surface d’API, si bien qu’une interface écrite contre un nœud fonctionne contre tous.