Executando um nó OpenFiat

1. 01

   Prepare a máquina

   Um servidor Debian ou Ubuntu atual, um firewall e um relógio preciso. O relógio importa mais do que parece: os registros carregam timestamps e horários de expiração, e um relógio desviado faz um nó rejeitar dados válidos.

   shellCopiar

   # 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

   Instale o nó

   Compile a partir do código-fonte e execute o resultado sob systemd — nenhuma versão foi marcada ainda, então essa é a única forma de obter um binário hoje, e o resto deste manual assume isso. Recorra ao Docker só ao testar localmente ou subir um cluster descartável.
3. 03

   Gere a carteira do nó

   Não há um formato de "identidade de nó" separado — a identidade de um nó é um wallet.json real da CLI da Solana, o mesmo arquivo que o solana-keygen produz. Sua seed é reutilizada tanto para a identidade de gossip/par do nó quanto para a chave de assinatura da Solana. Guarde o arquivo — se você o perder, o nó reingressa como um estranho e começa a construir reputação do zero.

   shellCopiar

   # 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

   Defina o ambiente

   O openfiat-node não tem arquivo de configuração próprio — cada ajuste é uma variável de ambiente, lida uma vez na inicialização: onde os dados ficam, em qual endereço escutar, quais pares discar na partida e (opcionalmente) qual endpoint RPC da Solana usar. Os pares de bootstrap devem ser um multiaddr/IP estático, não um nome de host — o bootstrap por DNS não resolve.

   shellCopiar

   # 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

   Abra as portas certas

   Os pares alcançam o nó por UDP porque o QUIC é o transporte principal — essa é a porta que as pessoas mais esquecem. Uma porta TCP serve JSON-RPC, WebSocket, REST, saúde e métricas juntos; mantenha-a privada se você não quiser servir clientes publicamente.

   shellCopiar

   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

   Sirva a rede: torne seu nó alcançável

   Este é o passo que transforma um nó de algo que observa a rede em algo que a carrega. Coloque o nginx na frente e obtenha um certificado, então informe ao nó sua URL pública com --public-rpc-url e ele se anuncia para que carteiras, exploradores e o próprio app web do OpenFiat possam usá-lo. A ordem importa: nginx sobre HTTP simples primeiro, depois o certbot adiciona TLS — uma configuração que já nomeia um certificado não consegue iniciar, então o certbot falha antes de poder emitir aquele que teria resolvido. Um certificado não é enfeite opcional: uma página servida por HTTPS não consegue abrir uma conexão HTTP simples, então um nó sem um é invisível para todo navegador por mais saudável que esteja.

   /etc/nginx/sites-available/openfiat-nodeCopiar

   # /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;
       }
   }

   shellCopiar

   # 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

   Execute-o como serviço

   Sob systemd o nó reinicia após uma queda ou reboot, e ganha um período de encerramento longo o suficiente para o banco de dados esvaziar de forma limpa em vez de ser morto no meio de uma escrita.

   openfiat-node.serviceCopiar

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

   shellCopiar

   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

   Deixe-o alcançar

   Em vez de reproduzir todo o histórico, um nó novo pode descobrir e importar um snapshot anunciado por um par do estado atual do mercado (OFS-1300) — métodos JSON-RPC reais, não uma ferramenta separada: getLatestSnapshot, getCheckpointHeight. Assinatura, versão do protocolo e raiz de estado, todos têm de corresponder antes de se confiar.

   shellCopiar

   # 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

   Verifique que está saudável

   GET /health confirma que o processo está no ar; getChainStatus por JSON-RPC diz se é GossipOnly ou RpcConnected, e seu blockhash atual se for o último.

   shellCopiar

   # 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

    Já faz parte da rede

    Não há um passo de "anunciar" separado — assim que um nó tem pares de bootstrap, ele propaga por gossip e é propagado automaticamente; ninguém o aprova. Fazer stake, publicar metadados no registro de serviços, ingressar em disputas e emitir votos de governança são ações separadas, guiadas por carteira, que um cliente realiza contra o nó em execução — veja o guia de participação relevante para cada uma.

    Um nó faz stake de OPEN para se tornar um participante ativo. Mas o stake não compra reputação: um operador com desempenho ruim não pode compensar fazendo mais stake. A prioridade efetiva combina reputação, stake e o desempenho de rede medido.
11. 11

    Vigie-o

    Os sinais que de fato predizem problema são os pares conectados, o modo da cadeia (GossipOnly vs RpcConnected) e a idade do blockhash. Alerte sobre esses e você saberá antes dos seus usuários.

    prometheus.ymlCopiar

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

    Mantenha-o atual

    Pare, troque o binário, inicie. Os nós atualizam um de cada vez, então a rede nunca precisa de uma parada coordenada, e os eventos de gossip perdidos são reproduzidos na inicialização.

    shellCopiar

    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

    Faça backup do que não pode ser regenerado

    O estado do mercado sempre pode ser ressincronizado a partir de um snapshot. A carteira não pode ser regenerada. Os saldos e a custódia vivem na Solana, não no seu disco.

    shellCopiar

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

Todo nó compatível expõe a mesma superfície de API, então uma interface escrita contra um nó funciona contra todos.