DEV Community: Pedro Pietroluongo

Os exemplos do repositório

Pedro Pietroluongo — Thu, 29 Oct 2026 14:04:47 +0000

Na série IPFS com o Nabu, os posts anteriores abriram o nó por dentro. Este fecha a série rodando os programas do módulo examples/ deste repositório. O nabu-chat é outro projeto. Aqui o código é examples/src/main/java/examples/.

A proposta

Ler EmbeddedIpfs.build mostra as peças. A proposta dos exemplos é ver duas dessas peças com um CID (Content Identifier, o identificador do conteúdo) na mão: um processo grava, o outro lê. Cada programa de linha de comando faz um só trabalho, em cima de um nó compartilhado. CLI significa command-line interface, o programa que se executa no terminal.

A Demonstração

DemoNode sobe esse nó. Gera uma identidade nova, guarda blocos num RamBlockstore e registros IPNS (InterPlanetary Name System) num RamRecordStore. RAM (Random Access Memory) aqui quer dizer a memória do processo: nada vai para disco. O listener é TCP (Transmission Control Protocol), uma porta só.

Sem --public, o bind é 127.0.0.1, o endereço que só a própria máquina alcança, e a lista de bootstrap é a que você passou em --bootstrap, muitas vezes vazia. Com --public, o bind é 0.0.0.0, todas as interfaces, e o bootstrap são os nós públicos de Config.defaultBootstrapNodes. Os dois modos se excluem: passar os dois lança erro. --public também liga provideBlocks só nos comandos que anunciam. O multiaddr impresso por advertise() é o que o outro processo cola em --bootstrap.

A ordem abaixo segue o que cada CLI pede da rede. Drop não usa DHT (Distributed Hash Table, a tabela de quem tem o CID): o outro processo ganha o multiaddr na saída e pede o bloco àquele par. Find anuncia o CID e o outro lado só precisa desse CID. Name move um nome IPNS. Chat manda HTTP (Hypertext Transfer Protocol) no stream /http. ApiBlocks fala com um daemon já de pé, pela API (Application Programming Interface) do post anterior.

Os scripts em examples/scripts/ sobem os dois processos e conferem a saída. No Windows:

powershell -ExecutionPolicy Bypass -File examples/scripts/all.ps1

Há um par .ps1 e .sh por exemplo: chat, drop, find, name, api. Um script que passa imprime PASS e o nome. all.ps1 e all.sh imprimem PASS all no fim. Antes disso, mvn install na raiz publica o Nabu no Maven local, para o examples/pom.xml compilar. O script da API ainda precisa do jar com dependências, mvn package -DskipTests, porque ele sobe o processo Nabu por esse jar. Os outros quatro chamam mvn -f examples/pom.xml exec:java. O próprio script compila o módulo, então um ajuste no exemplo entra na execução seguinte sem um compile à parte.

Chat, Drop, Find e Name escutam uma porta efêmera, escolhida na hora. Não ocupam 4001 (swarm, as conexões entre pares), 5001 (API) nem 9100 (métricas). O script da API ocupa as três e disca os nós públicos de bootstrap, então a máquina precisa de rede até eles. Se a porta estiver tomada:

powershell -ExecutionPolicy Bypass -File examples/scripts/all.ps1 -SkipApi

No shell, o equivalente é SKIP_API=1. A subida da API espera até três minutos pela linha Starting RPC API server. RPC (Remote Procedure Call) aqui é só o nome dessa linha de log: o servidor HTTP da API subiu. O repositório do daemon é target/example-tests/ipfs-repo, criado de novo a cada execução. Reusar um repositório travado deixa node.start() parado em Starting IPFS.... Os logs ficam em target/example-tests/. Um script que falha imprime a saída do nó e mata os processos que ele mesmo abriu. all tenta o script falho uma segunda vez e então para.

No Nabu

Drop grava um bloco raw e para. Raw, no CID, é o codec dos bytes opacos: não há links dentro do bloco. put chama DemoNode.start(false, lista vazia, false). O primeiro false desliga o anúncio na DHT. A lista vazia é o bootstrap. O último false prende o bind em 127.0.0.1. O bloco sai de DemoNode.payload. Se sobrou um caminho, lê o arquivo inteiro. Senão imprime Text to store: e usa uma linha da entrada. blockstore.put usa Cid.Codec.Raw. A saída traz Listening:, depois CID:, e a frase de que os mesmos bytes produzem esse CID. O outro processo cola o que vier em Other process: get <multiaddr> <cid>.

Drop put [file]
Drop get <multiaddr> <cid>

get sobe outro DemoNode do mesmo jeito, chama remember no multiaddr e fetch com o conjunto daquele único PeerId, timeout de 30 segundos. remember faz addAddrs no caderno. fetch chama ipfs.getBlocks com addToLocal verdadeiro. A linha final é Fetched <cid> from <peerId>. A DHT não entra, porque a lista de pares não está vazia.

Find é o anúncio. put sobe com provideBlocks verdadeiro e, depois do put raw, chama dht.provideBlock com o CID e PeerAddresses.fromHost, e espera o future. A frase na saída diz que o outro lado só precisa do CID, e pede para deixar o processo vivo: o provedor precisa continuar discável. get sobe com provideBlocks falso, lê o CID e chama findProviders pedindo 5 provedores. Imprime cada PeerId e os endereços. remember grava esses endereços no caderno, pulando provedor sem endereço. Em seguida fetch vai com a lista de pares vazia. A busca do bloco passa de novo pela DHT, agora com os endereços já conhecidos, no caminho do BitswapBlockService que tenta os conectados e depois os provedores. Sem registro, a linha é No provider records. Com --public, os dois lados usam a DHT pública. Sem ele, get imprime Start the other process with: put --bootstrap mais o multiaddr local, e os dois formam uma DHT de dois nós.

Name publica IPNS. O comentário da classe pede para subir resolve primeiro e passar o multiaddr dele a publish --bootstrap. publish sobe com provideBlocks verdadeiro. Cada linha da entrada vira um bloco raw. O valor do registro são os bytes UTF-8 do CID em texto, não os bytes do bloco. O sequence começa em 0 e incrementa antes de cada publishValue, então o primeiro anúncio sai com sequence 1. O TTL (Time To Live, a vida que o registro declara) é 24 horas, a constante TTL_HOURS. A saída de cada linha é Publishing sequence ..., o CID e IPNS record stored on N peers., onde N é o inteiro que publishValue devolve, a quantidade de pares que guardaram o registro. resolve sobe sem anunciar, pede o PeerId do publicador e aceita resolve, get <cid> ou quit. resolve chama resolveRecords com minResults 1, imprime IPNS sequence e o CID, e busca o bloco. Sem --public, o conjunto de pares é só o publicador e o timeout é 30 segundos. Com --public, o conjunto vai vazio, o timeout sobe para 120 segundos e a DHT entra. Sem registro, a linha é No IPNS record yet.

Chat sobe com provideBlocks falso e registra o handler incoming. O primeiro prompt pede um PeerId ou um multiaddr, e remember grava o endereço. Cada linha seguinte vira um DefaultFullHttpRequest POST para /, com o texto no corpo. p2pHttp precisa estar presente. dial usa o host, o PeerId e os multiaddrs, e send espera a resposta. Falha de envio imprime Could not send:. O handler remoto lê o corpo e imprime received:. O script chat.ps1 sobe o primeiro sem argumentos e o segundo com --bootstrap no endereço que o primeiro imprimiu.

ApiBlocks é cliente, não nó. O padrão é o multiaddr /ip4/127.0.0.1/tcp/5001. Um argumento só, se começa com /, substitui o multiaddr. Se não começa, é o arquivo a guardar. Dois argumentos são o multiaddr e o arquivo. Sem arquivo, o programa lê uma linha, Text to store:. NabuClient chama id, imprime PeerId:, faz block/put em raw, imprime CID:, faz block/get e compara os bytes. Diferença lança block/get returned different bytes. Sucesso imprime block/get matches block/put. Depois chama dht/findprovs. Sem provedor, a linha é dht/findprovs: no providers. Com provedor, imprime PeerId e endereços.

O que fica de fora: os exemplos não cobrem S3, filtro, UPnP (Universal Plug and Play) nem relay. O blockstore é RAM. Matar o processo apaga blocos e registros. O script da API é o único que fala com a rede pública de bootstrap. Os outros quatro ficam entre si.

Nesta série

O anterior é HTTP entre pares. Este é o último post.

HTTP entre pares

Pedro Pietroluongo — Thu, 29 Oct 2026 14:04:45 +0000

Na série IPFS com o Nabu, a API (Application Programming Interface) HTTP do post anterior escuta na máquina local. Este post leva um pedido HTTP até outro par, sem que esse par tenha um endereço público na internet.

A proposta

Dois programas já sabem falar HTTP (Hypertext Transfer Protocol): um verbo, um caminho, cabeçalhos e um corpo. Um deles está atrás de NAT (Network Address Translation, a reescrita de endereços do roteador). Abrir uma porta no roteador, ou alugar um servidor para os dois se encontrarem, repete o problema que o libp2p já resolve nos posts de transporte e de alcance.

A proposta é carregar o pedido e a resposta HTTP num stream libp2p. O encontro dos pares continua sendo por PeerId (o identificador do par). O conteúdo do stream continua sendo HTTP comum.

A Demonstração

O protocolo se chama /http. Um lado disca o outro pelo PeerId, abre um stream e escreve um pedido HTTP completo: método, URL (Uniform Resource Locator) relativo, headers e corpo. O outro lado trata o pedido e devolve o status, os headers e o corpo. O tratamento pode ser a própria aplicação, ou um encaminhamento para um servidor HTTP comum em localhost. Visto de fora, o par remoto parece um servidor. Visto da rede, é mais um protocolo no mesmo host que já fala Bitswap e Kademlia.

Quem chama precisa do endereço do par. Se o caderno já tem multiaddrs, a discagem usa essa lista. Se não tem, a DHT (Distributed Hash Table) procura o par, como no post da Kademlia. Um proxy local traduz um caminho /p2p/<peerid>/http/<caminho> nessa discagem. Um cliente HTTP comum, na mesma máquina, fala com 127.0.0.1 e não precisa saber o que é um PeerId. O proxy corta o PeerId do caminho, acha o par e escreve o resto do caminho no pedido que segue pelo stream.

flowchart LR
  client[localHttpClient] --> proxy[p2pProxy]
  proxy --> dht[addressOrDht]
  dht --> stream[httpStream]
  stream --> app[remoteHandlerOrLocalhost]

No Nabu

HttpProtocol, em src/main/java/org/peergos/protocol/http/HttpProtocol.java, registra o identificador /http no Binding. Há dois construtores de binding. Um recebe um SocketAddress e encaminha cada pedido para esse host e porta. O outro recebe um HttpRequestProcessor, a função da aplicação. O corpo máximo tratado de uma vez é MAX_BODY_SIZE, 8 MiB. O comentário no código marca isso como limite temporário, no lugar de um fluxo contínuo. Sender.send enfileira um future, escreve o FullHttpRequest no stream e completa quando onMessage copia status, headers e corpo para um DefaultFullHttpResponse. O stream fecha em seguida. onClosed, onReadClosed e onException falham os futures que ainda estavam na fila, com a mensagem de stream fechado ou a exceção original.

EmbeddedIpfs.build só acrescenta o protocolo quando a aplicação passa um handler:

Optional<HttpProtocol.Binding> httpHandler = handler.map(HttpProtocol.Binding::new);
httpHandler.ifPresent(protocols::add);

O campo p2pHttp do EmbeddedIpfs fica vazio sem isso. Bitswap e Kademlia seguem normais. Quem for discar mais tarde usa ipfs.p2pHttp.get() e recebe vazio se o build não registrou o protocolo.

No processo Nabu, o handler existe quando o config tem Addresses.ProxyTarget. proxyHandler chama HttpProtocol.proxyRequest para o host e a porta desse multiaddr, e passa o PeerId remoto. O mesmo processo publica HttpProxyHandler em /p2p/, a constante HttpProxyService.API_URL. O comentário do handler descreve o caminho: /p2p/$target_node_id/http/$target_path. O handler corta o prefixo /p2p/, separa o PeerId do caminho que segue, e pede ao HttpProxyService a discagem.

HttpProxyService.getAddresses olha o caderno do host. Se a coleção daquele PeerId não está vazia, devolve esses multiaddrs. Se está vazia, lookupAddresses chama dht.findClosestPeers pedindo um resultado. O comentário do método explica o segundo argumento useCached: a DHT responde uma busca de par a partir do caderno quando pode, e isso não serve para quem está tentando escapar de um endereço morto. useCached falso força a consulta. O resultado fica com o par cujo id coincide com o alvo. Endereço velho, de um par que mudou de rede, faria o proxy insistir num destino que não atende.

O buffer de 128 MiB do yamux, do post de transportes, existe por causa daqui. O yamux limita o buffer por conexão. Uma resposta perto de MAX_BODY_SIZE já ocupa uma fatia grande. Três respostas de 4 MB na mesma conexão estouravam o padrão de 10 MiB, e o muxer resetava os streams. writeAndFlush não devolve future, então o reset aparecia só como resposta que não chegava.

O exemplo mínimo de duas pessoas trocando mensagens por esse caminho é o nabu-chat: os PeerIds se encontram fora da banda, a conexão é libp2p, e as mensagens são pedidos HTTP. O módulo examples deste repositório tem um Chat com a mesma ideia. Cada linha vira um POST / no stream /http, e o handler do outro lado imprime received:. O próximo post o executa.

O que fica de fora: /http não é um gateway de conteúdo IPFS. Ele não resolve CID nem IPNS. Carrega HTTP opaco entre dois pares que já se encontram pelo libp2p. O corpo de 8 MiB é o teto desta implementação. Uma resposta maior precisa de outro desenho.

Nesta série

O anterior é A API HTTP e como rodar o Nabu. O próximo é Os exemplos do repositório.

A API HTTP e como rodar o Nabu

Pedro Pietroluongo — Thu, 29 Oct 2026 14:04:10 +0000

Na série IPFS com o Nabu, o nó já guarda blocos e fala com a rede. Este post é a porta de fora: o processo que sobe sozinho e a biblioteca que outra aplicação embute.

A proposta

Quem opera um nó quer o mesmo tipo de chamada que já usa com o Kubo, a implementação de referência do IPFS em Go: HTTP (Hypertext Transfer Protocol) local, um caminho /api/v0/..., o CID (Content Identifier) na query. Quem escreve uma aplicação quer o contrário: nenhuma porta HTTP, o nó como objeto Java dentro do processo.

A proposta do Nabu é oferecer os dois. A superfície HTTP é de propósito menor que a do Kubo. O objeto embutido expõe o mesmo nó que essa superfície usa por baixo.

A Demonstração

O modo standalone lê um diretório de repositório, no estilo do Kubo. A variável de ambiente ou o argumento IPFS_PATH aponta para ele. Na ausência, o diretório é ~/.ipfs, debaixo do home do usuário. Lá estão o arquivo config e os dados. O config é JSON (JavaScript Object Notation) com a identidade, os endereços e o datastore. O processo abre a API (Application Programming Interface) HTTP no host e na porta que o config chama de Addresses.API.

Uma chamada típica é POST /api/v0/block/get?arg=<cid>. O corpo da resposta são os bytes do bloco. block/put manda os bytes num corpo multipart, o formato em que cada parte traz um arquivo, e recebe de volta um JSON com o campo Hash.

O modo embutido não abre essa porta. A aplicação chama EmbeddedIpfs.build com as peças que escolhe: store de registros, blockstore, se deve anunciar blocos, endereços de swarm, bootstrap, identidade, authoriser e, se quiser, um handler HTTP entre pares. start entra na rede. A partir daí getBlocks, publishValue e o blockstore são chamadas locais, no mesmo processo.

A API compatível com o Kubo cobre bloco, identidade, refs, um pedaço da DHT (Distributed Hash Table) e a leitura IPNS (InterPlanetary Name System). Caminhos de arquivo, add de diretório e pin não estão nessa lista.

No Nabu

A classe do processo é Nabu, em src/main/java/org/peergos/Nabu.java. getIPFSPath lê o argumento IPFS_PATH ou, sem ele, HOME mais .ipfs. readConfig abre config nesse diretório. Se o arquivo não existe, grava um config padrão. O argumento s3.datastore, quando vem na linha de comando, preenche o mount S3 antes dessa gravação. O authoriser é (c, p, a) -> CompletableFuture.completedFuture(true): toda leitura de bloco é autorizada. O store de IPNS é um DatabaseRecordStore em datastore/h2-v2.datastore. O blockstore sai de buildBlockStore. EmbeddedIpfs.build recebe provideBlocks verdadeiro, os endereços de swarm, o bootstrap e a identidade do config.

Se config.addresses.enableUPnP está ligado, enablePortForwarding roda antes de start. start(false) faz o bootstrap de forma síncrona. O endereço da API é o argumento Addresses.API, se foi passado, ou config.addresses.apiAddress. O servidor é com.sun.net.httpserver.HttpServer, com fila de 500 conexões e um pool de 50 threads. O contexto /api/v0/ recebe um APIHandler. Se o config tem Addresses.ProxyTarget, o HTTP entre pares encaminha para esse host e porta, e o servidor ganha o contexto /p2p/. Um shutdown hook para o servidor HTTP com espera de 3 segundos. Métricas, se config.metrics.enabled, sobem noutro endereço, o do MetricsSection.

APIHandler exige que o caminho comece com /api/v0/. O resto entra num switch. Os casos, em src/main/java/org/peergos/net/APIHandler.java:

id devolve JSON com o PeerId em base58, no campo ID.
version devolve o campo Version. A constante do handler é 0.9.0.
block/get exige um arg. Monta um Want com o CID e o auth opcional. peers vira um conjunto de PeerIds. persist vem da query e, se falta, vale verdadeiro. A resposta são os bytes, ou status 400 se a lista volta vazia.
block/put exige format. Lê um único arquivo do multipart, cujo boundary vem do header Content-Type. Recusa tamanho acima de maxBlockSize, o teto da mensagem Bitswap, 2 MiB. O codec sai de Cid.Codec.lookupIPLDName. A resposta JSON traz Hash.
block/rm apaga um CID. Sucesso devolve Hash e Error vazio. Falha responde 400.
block/rm/bulk lê uma lista cids no corpo JSON.
block/stat busca o bloco com persist falso e devolve só Size. A lista de pares vai vazia. Falha responde 400.
block/stat/bulk lê {"wants":[...]}, busca com persist verdadeiro e, para cada bloco, devolve size, os links que não são multihash do tipo identity, e os BATs (Block Access Token, o segredo de leitura) encontrados no bloco. Responde 400 se o número de blocos não fecha com o de wants.
block/has responde os bytes true ou false.
refs/local lista os CIDs de blockstore.refs. O parâmetro use-block-store vale falso se não vier. Cada CID sai num JSON com o campo Ref.
bloom/add chama blockstore.bloomAdd e responde o booleano.
dht/findprovs exige o CID. num-providers positivo substitui o padrão 20. Cada provedor vira ID e Addrs dentro de Responses.
ipns/get exige o argumento signer, um PeerId em base58. Chama resolveRecords pedindo pelo menos um resultado, ordena, e devolve sig e data em hexadecimal do registro de maior sequence. Lista vazia vira Couldn't resolve.

block/get com peers vazio deixa o BitswapBlockService tentar os conectados e depois a DHT. persist falso busca sem gravar no store local.

O cliente Java dessa API é NabuClient, em src/main/java/org/peergos/client/NabuClient.java. O construtor de host e porta assume /api/v0/. O construtor de multiaddr, por exemplo /ip4/127.0.0.1/tcp/5001, lê host e porta dali. Timeout de conexão: 10 segundos. Timeout de leitura: 60 segundos. Os exemplos do último post usam esse cliente contra um daemon.

Embutir segue o trecho do README. A identidade pode ser gerada na hora:

HostBuilder builder = new HostBuilder().generateIdentity();
PrivKey privKey = builder.getPrivateKey();
PeerId peerId = builder.getPeerId();
IdentitySection identity = new IdentitySection(privKey.bytes(), peerId);

EmbeddedIpfs.build recebe o RamRecordStore ou um store durável, o FileBlockstore, a lista de swarm e de bootstrap, e o authoriser. ipfs.start() bloqueia até o host escutar, o identify estar registrado e o bootstrap da tabela ter corrido. getBlocks devolve List<HashedBlock>. Cada item traz o CID e o byte[].

O que fica de fora: a API não replica o Kubo inteiro. Não há files, dag, name/publish HTTP, nem gateway de conteúdo no estilo ipfs.io. O campo Addresses.Gateway existe no config e é lido por AddressesSection. O handler que sobe é o da API, mais o proxy /p2p/ quando há alvo. O pacote Maven publicado pelo JitPack é com.github.peergos:nabu.

Nesta série

O anterior é Onde o bloco mora. O próximo é HTTP entre pares.

Onde o bloco mora

Pedro Pietroluongo — Thu, 29 Oct 2026 14:04:09 +0000

Na série IPFS com o Nabu, o CID (Content Identifier, o identificador do conteúdo) já nomeia o bloco e o Bitswap já o transporta. Este post é o lugar onde os bytes ficam quando o processo guarda uma cópia.

A proposta

Um bloco chega e precisa sobreviver ao reinício. A pergunta "eu tenho este CID?" acontece o tempo todo: a cada want do Bitswap, o motor olha o store. Ir ao disco, ou a um serviço de objetos, para cada pergunta fica caro quando a resposta quase sempre é não. O store também precisa listar os CIDs que tem, para o anúncio periódico da DHT (Distributed Hash Table), e lembrar tamanho e links, para a API (Application Programming Interface) HTTP não abrir o bloco inteiro só para medir.

A proposta é uma interface pequena, dois fundos intercambiáveis e camadas opcionais por cima: um filtro aproximado na frente e uma tabela de metadados ao lado.

A Demonstração

A interface é has, get, put, rm, refs, bloomAdd. A chave de arquivo deriva do multihash em base32, o alfabeto de 32 símbolos, sem o padding =. O diretório reparte os arquivos para uma única pasta não guardar milhões de entradas.

Dois fundos implementam o contrato. O de arquivo escreve cada bloco num .data sob blocks/. O de S3 (Simple Storage Service, o armazenamento de objetos no estilo da AWS) usa o mesmo contrato contra um bucket: uma região, um endpoint, um prefixo dentro do bucket. As credenciais podem vir do JSON (JavaScript Object Notation) de config, das variáveis AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY, ou de ~/.aws/credentials.

Por cima do fundo entra um filtro. Ele responde "não tenho" sem tocar o fundo quando o CID está fora de um conjunto aproximado. Um bloom filter é uma tabela de bits. Cada CID liga alguns bits. Se algum bit que o CID exigiria está apagado, o CID com certeza não foi inserido. Se todos estão acesos, o CID talvez esteja: outro CID pode ter acendido os mesmos bits. Essa coincidência é o falso positivo, e a taxa é configurável. O InfiniFilter é um quotient filter que cresce. Em vez de ser recriado do zero quando enche, aumenta a estrutura e alonga a impressão digital (fingerprint) de cada chave. Os dois podem dizer que um CID talvez esteja presente. Só o fundo confirma. Um segundo filtro pequeno guarda ausências recentes, para não repetir a ida ao disco logo depois de um has negativo.

Os metadados ficam à parte, numa tabela H2 aberta por JDBC (Java Database Connectivity, a API Java de bancos relacionais): tamanho, links, o que block/stat precisa. O bloco em si continua no fundo.

No Nabu

EmbeddedIpfs.buildBlockStore escolhe o fundo pelo prefixo do config, em src/main/java/org/peergos/EmbeddedIpfs.java. flatfs.datastore monta um FileBlockstore no diretório IPFS e o embrulha num CachingBlockMetadataStore junto com o metadata JDBC. Se updateMetadb é verdadeiro, updateMetadataStoreIfEmpty percorre os blocos quando a tabela ainda está vazia. s3.datastore faz o análogo com S3Blockstore, lendo região, bucket, rootDirectory e regionEndpoint dos parâmetros do mount. Outro prefixo lança Unrecognized datastore prefix.

O caminho de arquivo está em FileBlockstore.getFilePath. hashToKey codifica o multihash em base32 e corta no primeiro =. A pasta são os dois caracteres imediatamente anteriores ao último. O arquivo é a chave mais .data, e a raiz é o diretório blocks/ criado no construtor se ainda não existe:

String key = hashToKey(cid);
String folder = key.substring(key.length() -3, key.length()-1);
String filename = key + BLOCK_FILE_SUFFIX;

put grava com TRUNCATE_EXISTING e CREATE, e devolve o CID versão 1 com SHA-256 (Secure Hash Algorithm de 256 bits), como no primeiro post. has é file.exists(). hasAny procura o mesmo multihash sob os codecs DagCbor, Raw e DagProtobuf, montando um CID versão 1 para cada um. get lê o arquivo inteiro para um byte[], ou devolve vazio se o arquivo não está.

filteredBlockStore embrulha o fundo se config.datastore.filter.type for BLOOM ou INFINI, com a taxa de falso positivo do config. NONE devolve o fundo direto. Outro tipo é erro. FilteredBlockstore.has só chama o fundo quando o filtro de presentes responde sim e o de ausências responde não. Se o fundo diz não, o CID entra no filtro de ausências. Esse filtro recomeça depois de 10.000 ausências, com um CidInfiniFilter de 1.000 entradas e taxa 0,001. get segue a mesma porta: fora do filtro de presentes, devolve vazio sem ler o fundo. put grava no fundo e só então chama present.add. rm apaga no fundo e não mexe no filtro de presentes. Um CID removido pode continuar "talvez presente" até o filtro ser refeito. O has seguinte vai ao fundo, recebe não, e registra a ausência.

bloomAdd insere o CID no filtro de presentes, sem gravar bytes. É o que a API bloom/add faz. Sem isso, um CID que já está no fundo e ficou de fora do filtro seria invisível: has e get nem consultariam o disco. Se o fundo não tem o bloco, has responde falso e o CID entra no filtro de ausências. O filtro sozinho não afirma a posse.

O metadata nasce em buildBlockMetadata. A URL JDBC é jdbc:h2: mais o caminho de nabu-blockmetadata.sql, com MODE=PostgreSQL. A conexão fica embrulhada em UncloseableConnection para um close acidental não derrubar o banco, e o auto-commit fica ligado. TypeLimitedBlockstore entra por último, quando allowedCodecs não está vazio. put e rm de um codec fora da lista lançam Unsupported codec. get de um codec fora da lista devolve vazio, sem chamar o fundo.

Os exemplos usam RamBlockstore: um mapa na memória do processo, sem arquivo, sem S3 e sem filtro. O processo Nabu usa arquivo ou S3.

O que fica de fora: não há Badger, LevelDB nem outro sharding além da pasta de dois caracteres. O filtro pode afirmar presença à toa, dentro da taxa configurada. A ausência confirmada pelo fundo é a resposta que vale. O InfiniFilter do código segue o artigo de Pagh, cresce por gerações de fingerprint, e a série não reproduz a matemática. O ponto prático é que has barato continua correto o bastante para não ir ao S3 em todo want.

Nesta série

O anterior é IPNS, um nome que muda. O próximo é A API HTTP e como rodar o Nabu.

IPNS, um nome que muda

Pedro Pietroluongo — Thu, 29 Oct 2026 14:03:34 +0000

Na série IPFS com o Nabu, o CID (Content Identifier) é permanente: os mesmos bytes, o mesmo nome. Este post é o nome que pode passar a apontar para outro CID.

A proposta

Um site, um perfil ou a cabeça de um feed mudam. Publicar de novo gera outro CID. Quem já guardou o CID antigo continua no conteúdo antigo, que é o combinado do endereçamento por conteúdo. Falta um nome estável, controlado por alguém, que diga "a versão atual é este CID".

A proposta do IPNS (InterPlanetary Name System, o sistema de nomes interplanetário) é esse ponteiro. O nome não muda. O valor muda, e a mudança é assinada por quem tem a chave.

A Demonstração

A chave do registro é o PeerId de quem publica, prefixada pelos bytes de /ipns/. O valor é um registro assinado pela chave privada correspondente. Quem quiser verifica a assinatura sem perguntar a um servidor. O registro traz o valor (em geral o caminho ou o CID atual, em bytes), um sequence, um prazo de validade e um TTL (Time To Live, por quanto tempo uma cópia pode ser reutilizada sem perguntar de novo).

O sequence é um contador. IpnsRecord.compareTo coloca o sequence maior depois do menor. No empate, o registro cuja validade acaba antes vem primeiro. Se a validade deste não acaba antes da do outro, a comparação devolve zero. resolveValue ordena a lista e fica com o último, portanto com o sequence mais alto. Um registro vencido deixa de ser a resposta na validação do prazo. Como o CID do conteúdo continua imutável, a história antiga segue endereçável para quem guardou o CID. O IPNS só move o ponteiro.

A publicação usa a mesma DHT (Distributed Hash Table) do post anterior. O registro é gravado nos pares mais próximos da chave /ipns/ mais o PeerId. Resolver é perguntar a esses pares e ficar com o registro de maior sequence que ainda valida.

No Nabu

IPNS.getKey monta a chave: escreve os bytes de /ipns/ e em seguida os bytes do multihash do publicador. createSignedRecord, em src/main/java/org/peergos/protocol/ipns/IPNS.java, monta o protobuf IpnsEntry. O corpo assinado é um mapa CBOR (Concise Binary Object Representation) com as chaves TTL, Value, Sequence, Validity e ValidityType. A validade é uma data no formato RFC 3339 com nanossegundos, em UTC, produzida por formatExpiry. A assinatura cobre o prefixo ASCII ipns-signature: mais esses bytes CBOR, e vai no campo SignatureV2. Para Ed25519 a chave pública já está no PeerId, e o registro não repete pubKey. Para outros tipos, o registro inclui a pública em protobuf. Dado extra da aplicação entra no mapa com o prefixo _ mais o sufixo que o chamador passou. O tamanho máximo aceito na validação é MAX_RECORD_SIZE, 10 KiB. Entrada maior, ou sem SignatureV2 e sem Data, é descartada por parseAndValidateIpnsEntry.

EmbeddedIpfs.publishValue é o atalho da aplicação. O publicador é o multihash do PeerId derivado da chave privada. O prazo é LocalDateTime.now() mais hoursTtl. O TTL em nanossegundos é hoursTtl vezes 3.600.000.000.000. O método assina e chama a DHT:

byte[] signedRecord = IPNS.createSignedRecord(value, expiry, sequence, ttlNanos, extraDataKeySuffix, extraData, priv);
return dht.publishValue(pub, signedRecord, node);

O inteiro devolvido é quantos pares guardaram o registro. Há também publishPresignedRecord, para quem já traz os bytes assinados. resolveValue pede resolveRecords e devolve o value do último item depois de sorted(). IpnsRecord.compareTo ordena pelo sequence. O último é o mais novo. Lista vazia vira o erro Couldn't resolve IPNS value.

Kademlia.publishValue valida antes de espalhar. parseAndValidateIpnsEntry precisa devolver um registro, e o publicador desse registro precisa ser a chave pedida. Se já existe um registro local e o novo não é maior na comparação, o antigo permanece. A busca mira pelo menos 30 pares próximos da chave (minPublishes), com 3 consultas em paralelo (queryParallelism). A chave de roteamento é o SHA-256 dos bytes /ipns/ mais o publicador, não o PeerId cru.

No processo standalone o store é DatabaseRecordStore, H2, no caminho datastore/h2-v2.datastore dentro do diretório IPFS. A tabela se chama records. O valor cabe em 10 KiB (SIZE_OF_VAL), o mesmo teto do registro, e o PeerId em 100 bytes na coluna. RamRecordStore existe para testes e para os exemplos, que não precisam do registro depois que o processo morre. A interface é RecordStore: ler, gravar e fechar. EmbeddedIpfs.stop fecha o store.

O que fica de fora: o Nabu não cria uma chave IPNS separada do PeerId por conta própria. A chave de publicação é a chave que a aplicação passa, e no fluxo de publishValue ela é a identidade cujo PeerId entra na chave /ipns/. Não há resolução IPNS por DNS. Um nome ipns:// no navegador fica com o cliente. A API HTTP expõe ipns/get, descrito no post da API, e não expõe publicação.

Nesta série

O anterior é A DHT Kademlia. O próximo é Onde o bloco mora.

A DHT Kademlia

Pedro Pietroluongo — Thu, 29 Oct 2026 14:03:32 +0000

Na série IPFS com o Nabu, o Bitswap já sabe pedir um bloco a um par conhecido. Este post é como achar esse par quando ninguém passou o PeerId (o identificador do par).

A proposta

Não existe um servidor central com a lista "quem tem este CID" (Content Identifier, o identificador do conteúdo). Cada nó só conhece uma fatia dos outros. A proposta da DHT (Distributed Hash Table, tabela de hash distribuída) é uma resposta que caiba nessa fatia e, ainda assim, chegue perto de quem publicou o anúncio.

Kademlia é o formato dessa tabela no IPFS. A mesma estrutura serve para achar um par a partir do PeerId e para guardar os registros IPNS (InterPlanetary Name System) do próximo post.

A Demonstração

Kademlia organiza os pares por distância XOR (exclusive or, o ou exclusivo bit a bit). A chave de um par é o hash do PeerId, 256 bits. A distância entre duas chaves é o XOR dos bits. Quanto mais cedo o primeiro bit diferente, mais distantes. Duas chaves que só diferem no último bit são vizinhas. Duas que diferem no primeiro bit estão em metades opostas do espaço.

Cada nó guarda uma tabela de roteamento: k-buckets, baldes de pares, um balde para cada faixa de distância. O nó conhece muita gente perto de si e poucos representantes de cada região longe. Com isso, qualquer chave é alcançável em poucos saltos. Cada salto pergunta a alguém mais próximo da chave do que o nó atual.

Publicar um provedor é escrever, nos nós mais próximos da chave do CID, o registro "este PeerId tem este CID, nestes endereços". Procurar é perguntar, de balde em balde, pelos nós mais próximos dessa mesma chave, até alguém devolver o registro. O anúncio expira. Quem continua com o bloco anuncia de novo. Quem acabou de gravar um bloco anuncia logo, sem esperar o ciclo.

O protocolo na rede pública é /ipfs/kad/1.0.0. Existe um identificador de DHT local, /ipfs/lan/kad/1.0.0, para uma tabela que não sai da rede de casa. O nó que o EmbeddedIpfs monta fala a rede pública.

No Nabu

Kademlia em src/main/java/org/peergos/protocol/dht/Kademlia.java escolhe o identificador no construtor. localOnly verdadeiro seleciona LAN_DHT_ID. Falso seleciona WAN_DHT_ID, a constante /ipfs/kad/1.0.0. EmbeddedIpfs.build passa false, e também as flags de QUIC e TCP calculadas a partir dos endereços de escuta. setAddressBook repassa o caderno ao KademliaEngine.

A tabela mora em KademliaEngine. O roteador é criado com o hash de 256 bits do PeerId deste nó:

this.router = new Router(Id.create(ourPeerId.bareMultihash().toBytes(), 256), 2, 2, 2);

O construtor de Router documenta os três inteiros: branchesPerLevel (quantos ramos nascem quando um k-bucket se divide), maxNodesPerBucket (quantos pares cabem no balde) e maxCacheNodesPerBucket (quantos cabem na cache do balde). Aqui os três valem 2. O identificador base tem 256 bits, e 2 divide 256, que é a condição que o construtor exige para a árvore fechar no último nível.

Os provedores ficam num RamProviderStore de 10.000 entradas, criado em EmbeddedIpfs.build e entregue ao engine junto com o RecordStore de IPNS e o Optional do blockstore. Reiniciar esquece quem anunciou o quê para este nó. getProviders lê dessa memória. Os registros IPNS usam o outro store, o do post seguinte.

bootstrapRoutingTable resolve dnsaddr (o multiaddr que ainda é um nome DNS), grava os endereços no caderno e disca, com 5 segundos de timeout por par. bootstrap então preenche a tabela a partir desses vizinhos. BOOTSTRAP_PERIOD_MILLIS vale 300.000, e a thread de startBootstrapThread repete o ciclo a cada esse intervalo.

findProviders(Multihash block, Host us, int desiredCount) é a busca. BitswapBlockService só a chama quando a aplicação não passou PeerIds. Nesse caso o serviço primeiro pergunta aos pares já conectados, com espera de 10 segundos. O que faltar segue para findProviders do primeiro CID da lista, pedindo até 5 provedores, e o Bitswap busca o restante nesses pares. Se a aplicação passou PeerIds, a DHT não entra. É o caminho mais rápido que o README descreve. EmbeddedIpfs.getBlocks recebe o conjunto e o repassa ao BlockService. A API dht/findprovs chama o mesmo método com num-providers, padrão 20.

Quem deve anunciar passa por ProvidingBlockstore. Se provideBlocks é verdadeiro, EmbeddedIpfs.build embrulha o blockstore. O put grava no fundo e, no thenApply, coloca o CID em toPublish, uma LinkedBlockingDeque. O construtor de EmbeddedIpfs cria o PeriodicBlockProvider com essa fila, o intervalo 22 * 3600_000 milissegundos (22 horas) e um fornecedor que chama blockstore.refs(false). start liga duas threads, CidReprovider e NewCidProvider. A primeira percorre os CIDs já guardados e republica. A segunda publica o que acabou de entrar na fila. As duas só existem quando provideBlocks é verdadeiro.

Na conexão, o handler de identify do HostBuilder abre um stream Kademlia com um par novo que anuncia /ipfs/kad/1.0.0. A condição é newPeer: o caderno estava vazio antes do identify. Assim a tabela cresce também com quem chega, não só com o bootstrap.

O que fica de fora: a DHT do Nabu não é um banco de blocos. Ela guarda ponteiros para pares e registros IPNS. Os bytes continuam no Bitswap. O store de provedores é memória. Não há persistência de provider records entre reinícios.

Nesta série

O anterior é Bitswap, o pedido de um bloco. O próximo é IPNS, um nome que muda.

Bitswap, o pedido de um bloco

Pedro Pietroluongo — Thu, 29 Oct 2026 14:02:58 +0000

Na série IPFS com o Nabu, o nó já está na rede. Este post é a troca do bloco: como um CID (Content Identifier, o identificador do conteúdo) vira bytes.

A proposta

Saber o CID não entrega os bytes. Algum par os tem, talvez vários. Pedir o arquivo inteiro a um desconhecido é frágil: a conexão cai no meio, e o que já chegou não tem nome próprio. A proposta do IPFS é pedir bloco a bloco. Cada bloco cabe numa mensagem e se verifica sozinho, porque o CID é o hash.

O protocolo que carrega esse pedido se chama Bitswap. Os dois lados usam a mesma mensagem. Enquanto este nó pede, pode atender o pedido de quem está do outro lado.

A Demonstração

A mensagem carrega três coisas. Um want é o CID que este nó quer, com um segredo opcional. Um have, ou a ausência dele (dont-have), diz se o outro lado tem esse CID. Um block são os bytes, junto com um prefixo do CID para o receptor conferir.

O want pode ir a pares que a aplicação já nomeou. Se a lista vem vazia, o serviço pergunta primeiro a quem já está conectado e, para o que ninguém entregou em 10 segundos, pede provedores à DHT (Distributed Hash Table, a tabela distribuída de "quem tem este CID"). O post da Kademlia é essa descoberta. O Bitswap é o transporte dos bytes.

Há um gancho de autorização. Antes de colocar os bytes na resposta, o nó pergunta a um BlockRequestAuthoriser se aquele par pode ler aquele CID. A resposta negativa vira um dont-have, mesmo com o bloco no disco. O Peergos usa isso com um BAT (Block Access Token), um segredo de 32 bytes que viaja no want. O processo Nabu standalone autoriza todo mundo.

flowchart LR
  want[wantCid] --> local[localBlockstore]
  local -->|hit| done[hashedBlock]
  local -->|miss| peers[knownPeersOrDht]
  peers --> bitswap[bitswapWant]
  bitswap --> auth[authoriser]
  auth --> done

No Nabu

O identificador está em Bitswap, em src/main/java/org/peergos/protocol/bitswap/Bitswap.java:

public static int MAX_MESSAGE_SIZE = 2*1024*1024;
public static final String PROTOCOL_ID = "/ipfs/bitswap/1.2.0";

2 MiB é o teto de uma mensagem. O construtor que EmbeddedIpfs.build usa aceita outro identificador e outro teto. O padrão é esse protocolo e Bitswap.MAX_MESSAGE_SIZE. O quarto argumento de BitswapEngine, blockAggressivePeers, vai false nesse build. Com ele verdadeiro, allowConnection recusa PeerIds que o motor já marcou em blockedPeers.

EmbeddedIpfs.getBlocks separa o trabalho antes do protocolo. Para cada Want, blockstore.has decide a lista local ou a remota. A local é lida com get. Falha ou ausência manda o want de volta para a lista remota. A lista remota segue para BitswapBlockService.get.

Bitswap.get percorre os wants e pula CID cujo multihash é do tipo identity: nesse tipo o "hash" já são os bytes, e não há bloco a transferir. Os demais entram em engine.getWant, que devolve o future já existente se o mesmo want está em voo, ou cria um WantResult novo. sendWants empurra os pedidos. Um DownloadManager por conjunto de pares, guardado numa cache de 100 entradas, mantém o envio vivo.

BitswapBlockService é quem decide a quem pedir. Se a aplicação passou PeerIds, a chamada é direta: bitswap.get(hashes, us, peers, addToBlockstore) e cada future é esperado com join. Se a lista vem vazia, o serviço usa bitswap.getBroadcastAudience(), os pares de conexões que este nó iniciou, com espera de 10 segundos por future. Want que completou sai da lista. O que falta chama dht.findProviders só com o primeiro CID, pedindo 5 provedores, e o Bitswap busca o restante nesses PeerIds.

BitswapEngine guarda os wants locais num mapa e, ao receber uma mensagem, decide o que devolver. O trecho que importa está em src/main/java/org/peergos/protocol/bitswap/BitswapEngine.java:

if (blockPresent && authoriser.allowRead(c, sourcePeerId, auth.orElse("")).join()) {
    MessageOuterClass.Message.Block blockP = MessageOuterClass.Message.Block.newBuilder()
            .setPrefix(ByteString.copyFrom(prefixBytes(c)))
            .setAuth(ByteString.copyFrom(ArrayOps.hexToBytes(auth.orElse(""))))
            .setData(ByteString.copyFrom(store.get(c).join().get()))
            .build();

store.has vem antes. Se o bloco existe e o authoriser aceita, os bytes entram na mensagem, com o prefixo do CID e o auth em bytes. Se a soma passa de maxMessageSize, o motor descarrega o que já juntou e recomeça a mensagem. Se o bloco existe e o authoriser recusa, o want vai para deniedWants (uma cache de 10.000) e a resposta é dont-have. O log diz Rejecting auth. Auth inválido repetido também é recusado, com outra linha de log.

A interface do authoriser é uma função:

CompletableFuture<Boolean> allowRead(Cid block, Cid sourceNodeId, String auth);

O Want carrega o CID e um authHex opcional. String vazia vira Optional.empty(). Na API HTTP, o parâmetro auth de block/get preenche esse campo, e peers limita a quem pedir. persist falso pede o bloco sem gravá-lo no store local. O padrão da API é gravar.

O BAT em si está em src/main/java/org/peergos/blockstore/auth/Bat.java. São 32 bytes. Comprimento diferente lança Invalid BAT length. O comentário da classe o descreve como a chave secreta de uma assinatura no estilo AWS S3 V4 (Simple Storage Service, assinatura versão 4), usada para autorizar a leitura do bloco. O processo Nabu passa o authoriser (c, p, a) -> CompletableFuture.completedFuture(true). Quem embute o nó troca essa função pela política da aplicação.

O que fica de fora: o Nabu implementa Bitswap 1.2.0 com o campo de auth que o Peergos usa. Não há um mercado de blocos nem pagamento dentro do protocolo. Um bloco maior que o teto da mensagem não cabe numa resposta.

Nesta série

O anterior é Entrar na rede. O próximo é A DHT Kademlia.

Entrar na rede

Pedro Pietroluongo — Thu, 29 Oct 2026 14:02:57 +0000

Na série IPFS com o Nabu, o host já sabe escutar. Este post é o que acontece quando o processo chama start: achar outros pares e descobrir se o resto da rede consegue discar de volta.

A proposta

Um nó novo não conhece ninguém. O caderno de endereços começa vazio. Mesmo depois de conhecer alguém, o endereço em que ele escuta pode ser inútil para o mundo. 0.0.0.0 é um bind local, não um destino. Um NAT (Network Address Translation) residencial reescreve o IP (Internet Protocol) e a porta de saída. Os pares de fora precisam de um endereço que de fato atenda. Enquanto isso não existe, o nó só fala com quem ele mesmo disca.

A proposta é uma sequência. Primeiro, alguns pares já conhecidos enchem a tabela. Depois, o nó descobre o próprio endereço externo. Se continuar inalcançável, pede emprestado o caminho de um par que é público e tenta furar o NAT.

A Demonstração

A entrada tem quatro movimentos.

O bootstrap é a lista de pares já conhecidos, em geral os nós públicos do libp2p. Um endereço /dnsaddr/bootstrap.libp2p.io/... ainda não é discável. DNS (Domain Name System) é o sistema que traduz nomes em endereços. O componente dnsaddr consulta o registro TXT (um texto publicado no DNS) de _dnsaddr. mais o domínio e troca aquilo por multiaddrs concretos, com IP, transporte e PeerId. O nó disca esses pares e pede à Kademlia os vizinhos mais próximos. A tabela de roteamento deixa de estar vazia. DHT (Distributed Hash Table) é essa tabela, repartida entre os pares.

O mDNS (multicast DNS) procura pares na rede local, sem passar pela internet. O anúncio usa o nome de serviço _ipfs-discovery._udp.local.. Quem estiver na mesma rede e escutar esse nome responde com o PeerId e os multiaddrs.

O alcance responde à pergunta "alguém de fora consegue me discar?". O identify já entrega o observed address, o endereço que o outro par viu. O AutoNAT pede a um par que tente discar de volta num candidato. Se a discagem volta, o endereço é público. UPnP (Universal Plug and Play) e NAT-PMP (NAT Port Mapping Protocol) pedem ao roteador de casa um mapeamento da porta de swarm para uma porta externa. Swarm é a lista de portas em que o nó aceita conexões. O endereço mapeado entra na lista de candidatos.

Quando nada disso torna o nó discável, o circuit relay empresta o caminho de um par público. O multiaddr ganha o componente /p2p-circuit: primeiro o endereço do relay, depois o PeerId de destino. O DCUtR (Direct Connection Upgrade through Relay) usa essa conexão emprestada para combinar um furo simultâneo. Os dois lados discam um ao outro ao mesmo tempo, e o NAT de cada um aceita o pacote porque acabou de ver saída para aquele destino. Se der certo, a conversa deixa o relay.

flowchart LR
  boot[bootstrap] --> dht[routingTable]
  mdns[mdns] --> dht
  observe[identifyObservedAddr] --> nat[autonatDialback]
  upnp[upnpOrNatPmp] --> nat
  nat --> relay[circuitRelayIfPrivate]
  relay --> dcutr[directUpgrade]

No Nabu

EmbeddedIpfs.start faz a sequência, em src/main/java/org/peergos/EmbeddedIpfs.java. Registra um shutdown hook que chama stop. Sobe o host com node.start(). Registra o identify já com a lista announce convertida em multiaddrs. Se bootstrap está vazio, o log avisa que o nó não entra na DHT global. dht.bootstrapRoutingTable recebe um filtro que descarta qualquer endereço cuja string contém /wss/ (WebSocket seguro, um transporte que este host não registra). Em seguida, se o chamador não pediu bootstrap assíncrono, dht.bootstrap caminha a Kademlia. startBootstrapThread repete o trabalho.

O mDNS usa MDnsDiscovery com o serviço _ipfs-discovery._udp.local. e intervalo de 60 segundos. No handler, o PeerId do anúncio passa por um recorte que o código comenta como ajuste do valor recebido. Se não somos nós mesmos, o nó abre um stream Kademlia com dial, pede closerPeers a partir do nosso PeerId e grava os endereços do anúncio no caderno com addAddrs.

DnsAddr.resolve, em src/main/java/org/peergos/protocol/dnsaddr/DnsAddr.java, só age quando a string começa com /dnsaddr/. O restante da lista de bootstrap passa intacto. O domínio vai para uma consulta TXT em _dnsaddr. mais o nome. O sufixo do multiaddr original é reaplicado, e /ipfs/ também é aceito como /p2p/. bootstrapRoutingTable faz essa resolução em paralelo, grava cada endereço resolvido no caderno e disca com timeout de 5 segundos por futuro. O retorno é a contagem de discagens que completaram.

O redirecionamento de porta é opt-in. enablePortForwarding precisa ser chamado antes de start. O processo Nabu faz isso quando o config traz Addresses.UPnP verdadeiro. startPortForwarders só corre se a flag está ligada e já existem swarmAddresses e ReachabilityManager. PortForwarder.forSwarm abre um mapeador por porta distinta de TCP (Transmission Control Protocol) ou UDP (User Datagram Protocol), com vida de 3600 segundos e nova tentativa a cada 60 segundos se o roteador falhar. O multiaddr externo volta para reachability.addLocalCandidate e também entra no caderno do próprio nó.

O AutoNAT v2 sobe dentro de HostBuilder.build quando o protocolo está na lista, e EmbeddedIpfs.build inclui new AutonatProtocol.Binding() e AutonatV2.protocols(). O cliente monta candidatos em externalAddressCandidates. Entram os endereços que pares já observaram, o IP observado casado com a porta TCP de escuta, os mapeamentos que o ReachabilityManager guardou como candidatos locais, e os endereços de escuta que PeerAddresses.isPublic aceita e que não contêm p2p-circuit. O comentário no código registra uma assimetria. A discagem QUIC reaproveita a porta de escuta, então o observed address do QUIC já é o mapeamento real. A discagem TCP ainda sai de porta efêmera, e o candidato TCP é uma previsão: IP observado mais a porta em que o nó escuta.

Relay e DCUtR também entram em EmbeddedIpfs.build, pelas chamadas enableRelay(Relay.candidateRelaySource(dht)) e enableDcutr(). enableRelay cria um GatingRelayManager.reachabilityGated com limite de 5 reservas simultâneas. Esse manager só concede reserva enquanto o próprio nó está publicamente alcançável, para um nó atrás de NAT não se anunciar como relay. A reserva padrão cabe 1 MiB e dura 120 segundos. O comentário explica o tamanho: o padrão da biblioteca, 4096 bytes, mal completa multistream, Noise e yamux, e não sobra espaço para o DCUtR. O AutoRelay, ainda em HostBuilder.build, escuta o ReachabilityManager. No estado PRIVATE pede duas reservas e chama ensureEnoughCurrentRelays. No estado PUBLIC zera o pedido.

O DCUtR abre o stream /libp2p/dcutr no lado que recebeu a conexão, e só se o endereço remoto contém p2p-circuit. O lado de dentro da conexão relayed envia CONNECT com os endereços discáveis, mede a ida e volta até a resposta e, meio RTT (round-trip time, o tempo de ida e volta) depois, disca. O outro lado disca ao receber SYNC. O resultado do furo volta para ReachabilityManager.recordHolePunchOutcome.

O que fica de fora: o README ainda lista circuit relay, DCUtR e AutoRelay como trabalho futuro. O build do host já liga os três. Não há relay v1.

Nesta série

O anterior é Transportes, criptografia e multiplexação. O próximo é Bitswap, o pedido de um bloco.

Transportes, criptografia e multiplexação

Pedro Pietroluongo — Thu, 29 Oct 2026 14:02:22 +0000

Na série IPFS com o Nabu, o par já tem PeerId (o identificador estável) e multiaddr (o endereço em camadas). Este post é a conexão em si: o que atravessa o fio antes de qualquer bloco.

A proposta

Bitswap, Kademlia, identify e HTTP (Hypertext Transfer Protocol) entre pares precisam falar ao mesmo tempo com o mesmo par. Abrir uma conexão TCP (Transmission Control Protocol) por protocolo repetiria o handshake e atravessaria o NAT (Network Address Translation, a tradução de portas do roteador) várias vezes. O fio também é público. Os bytes precisam de sigilo e de autenticação: no fim do handshake, cada lado sabe o PeerId do outro.

A proposta da pilha libp2p é empilhar três trabalhos distintos. Um carrega bytes. Outro cifra e autentica. O terceiro reparte a conexão cifrada em conversas paralelas.

A Demonstração

O transporte carrega bytes. TCP é um fluxo confiável: o que se perde é retransmitido, e a ordem se preserva. UDP (User Datagram Protocol) entrega datagramas, sem essa garantia. QUIC, escrito quic-v1 no multiaddr, anda sobre UDP, traz criptografia própria e já multiplexa várias conversas no mesmo fluxo. O nome QUIC deixou de ser sigla. Nasceu como Quick UDP Internet Connections. O Nabu escuta TCP e QUIC quando o endereço de swarm pede os dois. Swarm, aqui, é a lista de endereços em que o nó aceita conexões de outros pares. Um endereço típico de TCP é /ip4/0.0.0.0/tcp/4001. O de QUIC é /ip4/0.0.0.0/udp/4001/quic-v1.

O canal seguro autentica o PeerId. No TCP, isso é uma camada à parte, porque o TCP sozinho não cifra. O Noise XX faz o handshake, deriva chaves de sessão e amarra a chave pública do par. XX é o padrão do handshake: as duas identidades são transmitidas e cifradas no meio da troca. No QUIC a criptografia já vem no transporte. O host registra ECDSA (Elliptic Curve Digital Signature Algorithm) como o provedor que o QUIC do jvm-libp2p usa nessa pilha.

O muxer reparte uma conexão TCP cifrada em vários streams. Cada protocolo abre o seu, como várias ligações dentro de um único cano. Yamux é o muxer principal. Mplex continua registrado para falar com pares que só oferecem esse. Um stream é barato em relação a uma conexão nova. É por isso que identify, Bitswap e Kademlia convivem depois de um único handshake. A abertura de cada stream negocia um identificador de protocolo, uma string como /ipfs/bitswap/1.2.0. Os dois lados precisam anunciar a mesma string.

flowchart TB
  app[bitswapAndDhtAndHttp] --> mux[yamuxOrMplex]
  mux --> secure[noiseOnTcp]
  secure --> tcp[tcp]
  app --> quic[quicV1]

No Nabu

HostBuilder.build monta a pilha em src/main/java/org/peergos/HostBuilder.java. Se ninguém passou muxers, entram yamux e mplex, nessa ordem:

if (muxers.isEmpty())
    muxers.addAll(List.of(StreamMuxerProtocol.getYamux(MAX_BUFFERED_CONNECTION_WRITES),
            StreamMuxerProtocol.getMplex()));

MAX_BUFFERED_CONNECTION_WRITES vale 128 MiB. O comentário no código explica o número. O yamux limita o buffer de escrita por conexão, não por stream, e um stream que estoura o buffer é resetado em vez de esperar. O padrão de 10 MiB cabia mal uma resposta HTTP de 4 MB. Três respostas grandes na mesma conexão derrubavam umas às outras: numa medida do próprio código, 1053 de 15740 respostas sobreviviam, contra 100% com duas. Stream.writeAndFlush não devolve um future, então o estouro era invisível para quem chamava. 128 MiB é um teto, não uma alocação. A constante fica acima de HttpProtocol.MAX_BODY_SIZE vezes o número de respostas grandes esperadas em voo para um único par.

Dentro do builder do jvm-libp2p, o método olha a lista de multiaddrs já convertidos. QUIC só é registrado se algum endereço tem o componente quic-v1. TCP entra sempre, com TcpTransport::new. O canal seguro acrescentado é NoiseXXSecureChannel. A linha do TLS (Transport Layer Security) está comentada:

if (toListen.stream().anyMatch(a -> a.has(Protocol.QUICV1)))
    b.getSecureTransports().add(QuicTransport::ECDSA);
b.getTransports().add(TcpTransport::new);
b.getSecureChannels().add(NoiseXXSecureChannel::new);
//            b.getSecureChannels().add(TlsSecureChannel::new);

O README ainda cita TLS com negociação antecipada de muxer via ALPN (Application-Layer Protocol Negotiation, a escolha do próximo protocolo durante o handshake TLS). O host que build devolve hoje cifra TCP com Noise. QUIC cifra por conta própria, pelo transporte registrado acima.

Depois da cifra, o método percorre os ProtocolBinding que EmbeddedIpfs.build juntou: ping, AutoNAT, Bitswap, Kademlia, e o HTTP se houver handler. Cada binding entra em b.getProtocols(). Se o protocolo implementa AddressBookConsumer, recebe o caderno. Se implementa ConnectionHandler, entra na lista de handlers da conexão. Em seguida o host escuta cada string de listenAddrs.

EmbeddedIpfs.build ainda calcula duas flags antes de criar a Kademlia: quicEnabled se algum swarm addr tem QUICV1, tcpEnabled se algum tem TCP. A Kademlia guarda as flags. hasTransportOverlap aceita um endereço se ele tem TCP e este nó fala TCP, ou se tem QUIC sem o componente WebTransport e este nó fala QUIC. O conjunto ainda recusa endereço que contém p2p-circuit. O circuit relay entra por outro caminho, no post seguinte.

O que fica de fora: WebTransport e WebSockets não são registrados. O bootstrap chega a descartar endereços que contêm /wss/. Não há configuração para desligar o Noise e ligar o TLS. Quem quiser só TCP, ou só QUIC, escolhe isso na lista de multiaddrs de escuta.

Nesta série

O anterior é Identidade e endereços. O próximo é Entrar na rede.

Identidade e endereços

Pedro Pietroluongo — Thu, 29 Oct 2026 14:02:21 +0000

Na série IPFS com o Nabu, o bloco já tem um CID (Content Identifier, o identificador do conteúdo). Falta nomear quem o guarda e onde esse par pode ser encontrado agora.

A proposta

Um CID diz o que o bloco é. Não diz quem o tem. A rede precisa de outra identidade: a do processo que fala libp2p, a pilha de rede par a par. Esse processo muda de IP (Internet Protocol, o endereço da máquina), abre outra porta e atravessa um NAT (Network Address Translation, a reescrita de endereços que o roteador faz entre a rede de casa e a internet).

A proposta é separar as duas coisas. O nome do par sobrevive à mudança de rede. O endereço de rede é uma lista que se atualiza.

A Demonstração

A identidade é um par de chaves. A chave pública vira o PeerId. A chave privada assina o que só aquele par pode afirmar, entre outras coisas o registro IPNS (InterPlanetary Name System) de um post seguinte. O Nabu gera Ed25519 por padrão, um esquema de assinatura de chave pequena e rápida. Um PeerId também pode nascer de RSA (Rivest–Shamir–Adleman, o esquema clássico de chave pública). Os dois cabem no mesmo formato porque o PeerId é um multihash da chave pública: o tipo da chave e o digest viajam juntos. Quem vê o PeerId sabe qual algoritmo esperar na hora de verificar uma assinatura.

O lugar onde o par escuta é um multiaddr, uma sequência de protocolos escritos num só texto. /ip4/203.0.113.4/tcp/4001 diz IPv4, TCP (Transmission Control Protocol, o fluxo confiável) e a porta 4001. /ip4/0.0.0.0/udp/4001/quic-v1 diz "escute em todas as interfaces", UDP (User Datagram Protocol) e QUIC versão 1. O 0.0.0.0 é um bind local: serve para abrir o socket, e não é um destino que o resto da internet disca. O mesmo PeerId anuncia vários multiaddrs ao mesmo tempo. Trocar de rede troca a lista. O PeerId fica.

Como a lista muda, cada nó guarda um caderno de endereços: PeerId para os multiaddrs vistos por último. A lista chega de três jeitos. O outro par diz, no protocolo identify, em quais endereços escuta. Uma conexão que nós mesmos discamos traz o endereço que acabou de funcionar. A DHT (Distributed Hash Table), mais adiante, devolve endereços quando perguntamos por um par.

O identify também devolve o observed address, o endereço que o outro par observou em nós. Um nó atrás de NAT usa isso para descobrir o IP externo. O post sobre entrar na rede continua a partir daí.

No Nabu

HostBuilder.generateIdentity, em src/main/java/org/peergos/HostBuilder.java, cria a chave e deriva o PeerId.

public HostBuilder generateIdentity() {
    return setPrivKey(Ed25519Kt.generateEd25519KeyPair().getFirst());
}

public HostBuilder setPrivKey(PrivKey privKey) {
    this.privKey = privKey;
    this.peerId = PeerId.fromPubKey(privKey.publicKey());
    return this;
}

generateIdentity pede um par Ed25519 à biblioteca e guarda só a metade privada. setPrivKey deriva a pública e chama PeerId.fromPubKey. A partir daí getPeerId() e getPrivateKey() devolvem os dois lados. setIdentity(byte[]) faz o caminho inverso: KeyKt.unmarshalPrivateKey lê os bytes já gravados e passa por setPrivKey.

O processo standalone persiste isso em IdentitySection, no arquivo de config. O JSON (JavaScript Object Notation) tem PeerID em base58, o alfabeto que o IPFS usa para PeerIds, e PrivKey em base64. fromJson decodifica os dois. Na subida, EmbeddedIpfs.build chama setIdentity(identity.privKeyProtobuf) e compara builder.getPeerId() com identity.peerId. Se divergirem, lança PeerId invalid e o nó não sobe. A chave e o identificador anunciado têm de ser o mesmo par.

O caderno padrão é RamAddressBook, passado no construtor do HostBuilder. Ele vive na memória do processo. Protocolos que precisam dele implementam AddressBookConsumer. No fim de build, cada protocolo da lista recebe setAddressBook. Bitswap e Kademlia fazem isso, e repassam o caderno aos motores internos.

O identify está no handler de conexão de HostBuilder.build, registrado para toda conexão nova. O fluxo, na ordem do código:

Lê o PeerId remoto da sessão já cifrada, connection.secureSession().getRemoteId(). Nesse ponto o handshake já amarrou a chave.
Consulta o caderno. Se a lista daquele par está vazia, ele é novo.
Se fomos nós que discamos (connection.isInitiator()), grava o endereço remoto dessa conexão com addAddrs. Esse endereço acabou de ser discável.
Abre um stream do protocolo identify e chama id.
Dos listenAddrs que o remoto devolve, grava a lista no caderno. Esses são os endereços em que ele escuta, não a porta efêmera de uma conexão que chegou de fora. Guardar a porta de origem deixaria no caderno um destino que ninguém escuta.
Se a resposta traz observed address, entrega a ReachabilityManager.observeAddress, junto com o hash do par que observou.
Se a lista de protocolos do remoto contém /ipfs/kad/1.0.0 e este nó ainda não o tinha discado, abre um stream Kademlia. A tabela de roteamento cresce com quem chega.

O que fica de fora: o caderno não é um banco. Reiniciar o processo esquece os endereços aprendidos. A identidade, no processo Nabu, sobrevive porque está no config. Um EmbeddedIpfs montado pela aplicação guarda a chave só se a aplicação a passar de novo em IdentitySection.

Nesta série

O anterior é O que é IPFS. O próximo é Transportes, criptografia e multiplexação.

O que é IPFS

Pedro Pietroluongo — Thu, 29 Oct 2026 14:01:42 +0000

Este post abre a série IPFS com o Nabu. IPFS significa InterPlanetary File System. O assunto é o endereço do conteúdo: um bloco se chama pelo hash dos próprios bytes.

A proposta

A proposta do IPFS é trocar o "onde" pelo "o quê". Um URL (Uniform Resource Locator) da web diz em que servidor e em que caminho buscar um arquivo. Se o servidor sai do ar, ou se alguém troca o arquivo e mantém o caminho, o URL continua igual e o conteúdo muda. Quem recebe os bytes precisa confiar em quem os enviou.

O IPFS propõe o contrário. O nome do dado é uma função dos bytes. Quem recebe calcula a função de novo. Se o resultado bate com o nome pedido, os bytes são aqueles, qualquer que seja o par que os entregou.

A Demonstração

Pegue a frase olá. Os bytes UTF-8 passam por SHA-256 (Secure Hash Algorithm, 256 bits), uma função que espalha qualquer entrada num número de tamanho fixo. Um byte diferente muda o número. O mesmo texto produz sempre o mesmo número. Esse número, mais um rótulo de como ler os bytes, vira o CID (Content Identifier, identificador de conteúdo).

Na prática os dados são partidos em blocos. Cada bloco ganha um CID. Um bloco pode conter links para outros blocos, também na forma de CIDs. O conjunto forma um DAG (Directed Acyclic Graph, grafo dirigido sem ciclos): as setas saem de um bloco para os filhos, e não há caminho que volte ao início. A raiz tem o seu próprio CID. Pedir a raiz e seguir os links reconstrói o conjunto.

Um CID versão 1 junta três escolhas. A versão diz qual é o formato do identificador. O codec diz como os bytes estão organizados: raw são bytes opacos, dag-cbor é um mapa CBOR (Concise Binary Object Representation, um formato binário compacto) com links, dag-pb é o protobuf usado pelos arquivos clássicos do IPFS. Essas formas de organizar bytes com links fazem parte do IPLD (InterPlanetary Linked Data). O multihash diz qual função de hash foi usada e traz o digest. Por isso os mesmos bytes com codecs diferentes têm CIDs diferentes. O hash sozinho identifica os bytes. O CID identifica os bytes mais a forma de lê-los.

O Nabu guarda e troca esses blocos. Um caminho de arquivo Unix fica para a aplicação que monta o DAG por cima.

flowchart LR
  bytes[bytes] --> hash[sha256]
  hash --> cid[cidV1]
  cid --> link[linksInsideOtherBlocks]

No Nabu

HashedBlock, em src/main/java/org/peergos/HashedBlock.java, é o par que a rede devolve: o CID e os bytes.

public class HashedBlock {
    public final Cid hash;
    public final byte[] block;
}

Quem grava um bloco calcula o CID. Não há uma tabela à parte de "nome para bytes". FileBlockstore.put faz a conta com CID versão 1 e SHA-256:

public CompletableFuture<Cid> put(byte[] block, Cid.Codec codec) {
    Cid cid = new Cid(1, codec, Multihash.Type.sha2_256, Hash.sha256(block));

O primeiro argumento, 1, é a versão do CID. codec vem de quem chama: a API HTTP pede o nome IPLD em format e traduz com Cid.Codec.lookupIPLDName. Multihash.Type.sha2_256 escolhe a função. Hash.sha256(block) é o digest. Os bytes iguais com Raw e com DagCbor produzem CIDs diferentes, e os dois podem coexistir no mesmo store.

A interface Blockstore oferece has(Cid), get(Cid), put(byte[], Codec) e rm(Cid). has responde se a cópia local existe. get devolve Optional<byte[]>, vazio quando o CID não está aqui. put devolve o CID calculado, não um caminho. rm apaga essa cópia local. O conteúdo com o mesmo CID continua válido em qualquer outro par que ainda o tenha.

EmbeddedIpfs.getBlocks aplica a regra na hora de buscar. Para cada Want (o pedido: um CID e, se houver, um segredo de autorização), o método pergunta blockstore.has. O que já está local entra numa lista e é lido com blockstore.get. Se o has disse sim e o get veio vazio, ou se o get lançou, o pedido volta para a lista remota. Se essa lista termina vazia, o método devolve só o que achou no disco. Se sobra pedido e não há BlockService, lança Blocks not found locally. Com o serviço presente, que no nó completo é o Bitswap, concatena os blocos locais com os que a rede devolver.

O que fica de fora aqui: o Nabu não implementa o sistema de arquivos FUSE (Filesystem in Userspace) do Kubo, nem ipfs add de um diretório. A API HTTP cobre operações de bloco, refs locais, um pedaço da DHT (Distributed Hash Table, a tabela que aponta quem tem o CID) e a leitura IPNS (InterPlanetary Name System, o nome mutável). Quem quiser um diretório endereçado por conteúdo monta os blocos e os links na aplicação.

Nesta série

O anterior é A série IPFS com o Nabu. O próximo é Identidade e endereços.

A série IPFS com o Nabu

Pedro Pietroluongo — Thu, 29 Oct 2026 14:01:40 +0000

Esta série apresenta o IPFS (InterPlanetary File System, o sistema de arquivos interplanetário) para quem está chegando agora, usando o Nabu como implementação concreta e minha versão https://github.com/pedropietro/nabu. O Nabu é um nó IPFS em Java, usado em produção pelo Peergos. Cada post explica o conceito, soletra as siglas e, no fim, percorre a classe que o realiza.

A proposta

A proposta da série é separar um nó em peças que dá para ler uma de cada vez. Na documentação, IPFS, libp2p, CID, DHT e Bitswap aparecem juntos. Libp2p é a biblioteca de rede par a par em que o IPFS se apoia: conexão, identidade e protocolos. CID (Content Identifier) é o identificador do conteúdo, o nome de um bloco. DHT (Distributed Hash Table) é a tabela de hash distribuída que responde "quem tem isto?". Bitswap é o protocolo que pede e entrega os bytes desse bloco.

Um processo real faz tudo isso ao mesmo tempo: escuta endereços, troca blocos, anuncia conteúdo e guarda registros de nomes. A série propõe uma ordem. Cada post entrega uma sigla com o nome por extenso e o trecho de Java que a implementa.

A Demonstração

O caminho de um bloco, do nome até a chamada HTTP (Hypertext Transfer Protocol, o protocolo da web):

O endereço do conteúdo. O hash dos bytes vira um CID.
A identidade de quem guarda o bloco: uma chave, um PeerId (identificador do par) e um multiaddr (o endereço de rede em camadas).
A conexão: TCP (Transmission Control Protocol), QUIC (transporte sobre UDP, User Datagram Protocol), cifra e vários protocolos no mesmo fio.
A entrada na rede: achar outros pares e descobrir se eles conseguem discar de volta, atravessando NAT (Network Address Translation, a tradução de endereços que o roteador de casa faz).
O pedido do bloco, via Bitswap.
A descoberta de quem tem o bloco, via DHT Kademlia.
Um nome que muda, o IPNS (InterPlanetary Name System), apontando para o CID atual.
O disco, ou o S3 (Simple Storage Service), onde a cópia fica.
A API (Application Programming Interface) HTTP local, no estilo do Kubo, a implementação de referência do IPFS em Go.
HTTP carregado dentro do libp2p, de um par para outro.
Os programas de exemplo do repositório, que exercitam os passos anteriores.

flowchart LR
  intro[whatIsIpfs] --> id[identity]
  id --> transports[transports]
  transports --> reachability[reachability]
  reachability --> bitswap[bitswap]
  bitswap --> dht[dht]
  dht --> ipns[ipns]
  ipns --> store[blockstore]
  store --> api[api]
  api --> http[p2pHttp]
  http --> examples[examples]

Os arquivos têm nome em inglês de propósito. Uma tradução futura copia docs/artigos/pt/ para docs/artigos/en/ e reescreve a prosa. Os links relativos, os blocos de código e os identificadores de protocolo permanecem. O vocabulário travado está em docs/artigos/glossary.yml. Títulos e descrições nos dois idiomas estão em docs/artigos/series.yml.

No Nabu

O nó inteiro cabe em EmbeddedIpfs, em src/main/java/org/peergos/EmbeddedIpfs.java. Os campos públicos são o mapa da série:

public final Host node;
public final Blockstore blockstore;
public final Optional<BlockService> blockRetriever;
public final RecordStore records;
public final Kademlia dht;
public final Optional<HttpProtocol.Binding> p2pHttp;

node é o host libp2p: identidade, transportes e a lista de protocolos. blockstore guarda os blocos e responde has, get e put por CID. blockRetriever pede à rede o que o store local não tem. No nó completo ele é um BitswapBlockService. records guarda registros IPNS. dht é a Kademlia, protocolo /ipfs/kad/1.0.0. p2pHttp é o HTTP entre pares, protocolo /http, e só existe quando a aplicação registra um handler.

EmbeddedIpfs.build monta esse conjunto numa ordem fixa. Recebe o store de registros, o blockstore, a flag provideBlocks (se este nó anuncia os CIDs que grava), os multiaddrs de escuta, o bootstrap, a IdentitySection e o BlockRequestAuthoriser. Por dentro cria um RamAddressBook, restaura a chave, instancia KademliaEngine com um RamProviderStore de 10.000 entradas, e registra ping, AutoNAT (o protocolo que testa se o nó é discável de fora), Bitswap, a DHT e, se houver handler, o HTTP. Em seguida chama enableRelay e enableDcutr. start sobe o host, faz o bootstrap e liga o mDNS (multicast DNS, a descoberta na rede local).

Dois pontos em que o README e o código divergem, e a série segue o código. HostBuilder.create e EmbeddedIpfs.build chamam enableRelay e enableDcutr. DCUtR significa Direct Connection Upgrade through Relay: um furo de NAT combinado por uma conexão emprestada. O canal seguro registrado em HostBuilder.build é Noise. A linha que registraria TLS (Transport Layer Security) está comentada.

Nesta série

Não há post anterior. O próximo é O que é IPFS.