Mineração OPoI com cs-stratum-bridge

A mineração em pool tradicional (veja Pools de Mineração) só rende recompensas de PoW. Pra participar também do OPoI — o protocolo de proof-of-inference do CS Coin, onde mineradores são pagos por rodar requests de inferência de IA — o seu cs-miner precisa se conectar através do cs-stratum-bridge, em vez de se conectar direto num pool.

O que a bridge faz

O cs-stratum-bridge fica entre o seu cs-miner e todo o resto:

• Tráfego PoW (mining.*) é repassado sem alteração pro pool real upstream — você continua recebendo os pagamentos normais do pool, como antes.
• Tráfego OPoI (opoi.assign / opoi.submit_result) é interceptado e fica totalmente sob responsabilidade da bridge, que fala diretamente com o RPC JSON do seu nó csd pra conduzir o ciclo COMMIT → REVEAL → publicação → pagamento on-chain.

O seu minerador só fala com a bridge — nunca diretamente com o csd ou com o pool.

cs-miner  →  cs-stratum-bridge  →  pool upstream (só mining.* de PoW)
                    │
                    └──  RPC JSON do csd (COMMIT/REVEAL do OPoI, pagamentos)

Pré-requisitos

1. Um nó csd sob seu controle, já rodando e acessível via RPC. A bridge precisa de server=1 e rpcuser/rpcpassword configurados no cs.conf desse nó:

   server=1
   rpcuser=stratumbridge
   rpcpassword=<uma-senha-forte-aleatoria>
   rpcallowip=127.0.0.1
   rpcport=26124

   Reinicie o csd depois de editar o cs.conf pra aplicar.
2. Um endereço OPoI com a chave privada já na wallet desse nó csd. A bridge nunca guarda nem pede uma chave privada — ela só chama o RPC do csd pra assinar, então a chave precisa já estar na wallet do próprio nó:

   # endereço novo — a chave já está na wallet, nada pra importar
   cs-cli getnewaddress
   
   # ou, pra reaproveitar um endereço que você já controla em outro lugar
   cs-cli importprivkey "<chave-privada>"

3. Algum saldo em CS nessa wallet, pra financiar a colateral da stake OPoI (veja Financiando a stake abaixo). Um nó novo tem saldo zero até minerar ou receber as primeiras moedas.

Baixar e rodar

As releases são publicadas publicamente, separadas do código-fonte (que continua fechado). Pegue o tarball mais recente pra sua plataforma na página cs-stratum-bridge-releases, depois:

tar xzf cs-stratum-bridge-vX.Y.Z-linux-x86_64.tar.gz
cd cs-stratum-bridge-vX.Y.Z
./cs-stratum-bridge

Não precisa escrever nenhum .env na mão. Na primeira execução, um assistente interativo detecta o que falta e te guia:

cs-stratum-bridge: incomplete configuration — missing 6 variable(s):
  - UPSTREAM_POOL_ADDR
  - CSD_RPC_URL
  - CSD_RPC_USER
  - CSD_RPC_PASS
  - OPOI_ADDRESSES
  - OPOI_REQUESTER_API_KEY

How would you like to configure it?
  1) Manual — I'll exit here, you edit .env and run again
  2) Automatic — I'll ask for each value, test the connection to csd, and show the available UTXOs for the stake
> 2

Escolha 2 (Automatic), a não ser que prefira editar o .env você mesmo. Ele então pergunta cada valor:

Variável	O que preencher
UPSTREAM_POOL_ADDR	host:porta do pool real que cuida do PoW — pro pool oficial, é 127.0.0.1:3332 se rodar na mesma máquina, ou o host:porta público dele
CSD_RPC_URL	Normalmente http://127.0.0.1:26124 (o padrão já sugerido)
CSD_RPC_USER / CSD_RPC_PASS	O rpcuser/rpcpassword do cs.conf acima
OPOI_ADDRESSES	O endereço do passo 2 dos Pré-requisitos
OPOI_REQUESTER_API_KEY	Aperte Enter pra gerar uma automaticamente — só é necessária se você também for enviar prompts através dessa bridge

Só rode uma instância por vez pra cada .env/diretório de dados. Uma segunda ./cs-stratum-bridge iniciada enquanto outra já está rodando (por exemplo, em outro terminal) vai colidir no Postgres embutido (bridge_pgdata) e nas portas — isso não só falha ao subir, como pode quebrar a conexão de banco da instância que já estava rodando. Confira primeiro com ps aux | grep cs-stratum-bridge; se já tiver uma no ar, use ela (tail -f no log dela, ou chame a API HTTP dela) em vez de subir outra.

Depois disso, ele testa a conexão RPC de verdade:

Testing connection to csd at http://127.0.0.1:26124...
OK — csd responded, current height: 12345

Financiando a stake

O protocolo OPoI exige que seu endereço bloqueie uma quantia pequena de CS como colateral da stake antes de conseguir aceitar trabalho. Logo depois do teste de RPC, o assistente lista as UTXOs disponíveis na sua wallet e deixa você escolher uma:

Fetching UTXOs from the csd wallet to use as stake collateral...

#    txid                                                               vout     amount (CS)   conf  address
1    5f3b2c...                                                          0             10.00000000    120  ta1q...

UTXO number to use as stake collateral (Enter to skip): 1
Using 5f3b2c...:0 as stake collateral.

Se aparecer "No UTXOs available yet", sua wallet está com saldo zero — mande alguns CS pra ela, ou minere alguns blocos, e rode ./cs-stratum-bridge de novo. Como o assistente não faz nada quando o .env já está completo, ele volta a aparecer só pra essa etapa da stake até existir uma stake ativa — não precisa refazer as perguntas anteriores.

Depois que uma stake é escolhida (ou já está ativa), a bridge termina de subir e passa a aceitar conexões de mineradores:

INFO cs_stratum_bridge: cs-stratum-bridge starting listen_addr=0.0.0.0:3532 upstream_pool_addr=127.0.0.1:3332 ...
INFO cs_stratum_bridge: csd reachable height=12345

Conectando seu minerador

Aponte o cs-miner pro LISTEN_ADDR da bridge (padrão 0.0.0.0:3532), em vez de apontar direto pro pool — o resto da configuração do minerador (algoritmo, endereço da wallet, nome do worker) continua igual ao que está em Começando com a Mineração.

Testando na testnet: enviando um request OPoI de verdade

Exige cs-stratum-bridge v0.1.3+. Versões anteriores nunca fazem assignment de um request OPEN que usa um nome de modelo simples, sem manifest registrado (ex: gemma3:4b, usado abaixo) — fica preso pra sempre em assigned_to: null, sem erro nenhum. Pegue a última release se não tiver certeza de qual versão está rodando.

Com o minerador conectado na bridge e registrado (o log dele mostra miner registered 'expert' capability ou similar), dá pra disparar um ciclo OPoI completo, de ponta a ponta, você mesmo — útil pra confirmar que tudo funciona antes de depender disso, e é o mesmo fluxo que uma aplicação requester seguiria. Funciona em -testnet (ou mainnet) — não funciona num nó novo com saldo zero, já que a própria transação REQUEST precisa estar financiada (veja Pré-requisitos — precisa do mesmo tipo de saldo gastável que a colateral da stake precisou).

Você também vai precisar da OPOI_REQUESTER_API_KEY da bridge pro passo 2 — ela foi gerada automaticamente durante o assistente (impressa uma única vez no terminal, como Generated: <chave>) ou é a que você definiu na mão. Se não salvou, dá pra recuperar do próprio .env da bridge:

grep OPOI_REQUESTER_API_KEY .env

1. Publique o REQUEST on-chain. Só o hash SHA-256 do prompt vai pra chain — nunca o texto do prompt em si:

PROMPT="Explique em uma frase o que é blockchain."
HASH=$(printf '%s' "$PROMPT" | sha256sum | cut -d' ' -f1)
REQID=$(cat /proc/sys/kernel/random/uuid)

cs-cli submitopoirequest "$REQID" "gemma3:4b" "$HASH" 128 1.0 <seu-endereco-requester>

gemma3:4b aqui é só um nome de modelo (task type OPEN, o padrão) — não precisa ser um Model Manifest registrado a não ser que você queira execução em shard. 128 é o max_tokens, 1.0 é o pagamento em CS (o piso na testnet — nOPoIFeeBase — é minúsculo, então isso fica bem acima do mínimo).

2. Envie o prompt de verdade pra bridge. Esse é o ÚNICO lugar por onde o texto puro do prompt trafega — via HTTP, direto pra bridge, associado ao REQUEST pelo request_id:

curl -X POST http://<host-da-bridge>:3533/cscoin/opoi/prompt \
  -H "x-opoi-api-key: <sua OPOI_REQUESTER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d "{\"request_id\":\"$REQID\",\"prompt\":\"$PROMPT\"}"

Um 404 request_id not found on-chain aqui significa que a transação do passo 1 ainda não confirmou — espera um bloco e roda de novo esse mesmo comando curl ($REQID/$PROMPT continuam definidos no seu shell desde o passo 1, então o retry já funciona direto). Não rode de novo a linha REQID=$(cat /proc/sys/kernel/random/uuid) antes de tentar de novo — isso sobrescreve $REQID com um UUID novo que nunca foi submetido on-chain, e toda tentativa depois disso vai dar 404 pra sempre, não importa quantos blocos passem. Se você perdeu o UUID que de fato foi publicado, ele está bem ali na resposta JSON do passo 1 ("request_id": "...") — copia ele de volta pra $REQID (ou coloca direto no curl abaixo) em vez de gerar um novo.

3. Acompanhe a resolução:

cs-cli getopoirequest "$REQID"          # estado do request on-chain
curl http://<host-da-bridge>:3533/cscoin/opoi/pending   # fila em andamento da bridge

Se o seu minerador não tiver o modelo disponível de verdade localmente (sem Ollama rodando, modelo nunca baixado), o dispatch/commit ainda exercita a parte on-chain corretamente, mas a geração em si vai falhar — confira o log do próprio minerador pro erro concreto nesse caso.

Próximos passos

• Pools de Mineração — o pool PoW upstream pro qual a bridge repassa
• Solução de Problemas — problemas comuns de mineração
• Comandos RPC — referência completa do RPC do csd