Visão Geral para Programadores

Como começar

Se simplesmente queres saber como publicar programaticamente no Hashiverse — por botão, Python ou linha de comandos — começa aqui. Se, em vez disso, queres saber como o Hashiverse foi construído, continua a ler.

O Hashiverse é uma rede social P2P descentralizada e resistente à computação pós-quântica. As ambições descritas na secção Visão traduzem-se diretamente em decisões técnicas que vale a pena compreender antes de mergulhares no código. Esta secção cobre essas decisões: por que foram tomadas, o que custam e onde vivem no código-fonte.

Estrutura do repositório

hashiverse/
├── hashiverse-rust/                   Workspace Rust (nightly)
│   ├── hashiverse-lib/                Protocolo principal — nativo + WASM
│   ├── hashiverse-server-lib/         Biblioteca do servidor (infra reutilizável)
│   ├── hashiverse-server/             Binário do servidor (wrapper fino)
│   ├── hashiverse-client-wasm/        Wrapper WASM para browser
│   └── hashiverse-integration-tests/  Testes ponto-a-ponto
├── hashiverse-client-web/             SPA TypeScript / React 19
└── www/                               Este site (Astro)

O design em duas camadas

hashiverse-lib é o protocolo. Compila para código nativo (para o servidor) e para WebAssembly (para o cliente do browser). Toda a criptografia, lógica DHT, codificação de publicações e API do cliente vivem aqui. Qualquer plataforma que possa correr WASM ou Rust nativo pode ser um participante completo na rede.

hashiverse-client-web é o cliente de browser de referência — uma SPA React 19 que carrega o cliente WASM num Web Worker, mantendo a thread principal livre. Comunica com o módulo WASM através de uma interface de passagem de mensagens; a lógica de protocolo que invoca é idêntica àquela que corre nativamente no servidor.

Quatro módulos em hashiverse-lib

transport/ — Traits abstratas (TransportFactory, TransportServer, TransportServerHandler) com duas implementações: em memória (para testes) e HTTP/TCP (para produção). Troca de transportes sem alterar a lógica do protocolo.
protocol/ — Codificação/descodificação de pacotes RPC com PoW e compressão, structs de pares, tipos de pedido/resposta, estruturas de dados de publicações e bundles.
client/ — API HashiverseClient, peer tracker, gestão de bundles de publicações, cronologia com travessia recursiva de baldes e traits ClientStorage / KeyLockerManager plugáveis.
tools/ — Tipos centrais (Hash, Id, Signature), primitivos criptográficos, PoW, abstração TimeProvider e configuração do protocolo.

Por onde começar

Se és novo no código-base, os melhores pontos de entrada são:

hashiverse-lib/src/lib.rs — o mapa dos módulos. Quatro módulos de topo, cada um com âmbito claro.
hashiverse-lib/src/client/mod.rs — a API pública do cliente. A superfície com a qual interage um programador que esteja a construir sobre o protocolo.
hashiverse-integration-tests/tests/ — testes ponto-a-ponto que levantam topologias reais de servidores em memória e exercitam toda a stack do protocolo. Lê-los é a forma mais rápida de perceber como as peças encaixam.

As secções deste guia para programadores cobrem cada uma uma área de design específica. Cada uma aponta para os ficheiros de código-fonte relevantes para que possas seguir as ideias diretamente até ao código.

Seguinte Como Começar