Configuração do Ambiente

Este guia orienta você na configuração do seu ambiente de desenvolvimento e na execução do seu primeiro nó PAEBIRU. Conforme a RFC 050, o provisionamento determinístico via Nix é o método recomendado.

1. Método Recomendado (Nix)

O PAEBIRU fornece suporte oficial ao Nix para garantir ambientes reprodutíveis e idênticos para todos os engenheiros.

Usando Flakes (Recomendado): nix develop
Usando Nix Shell Tradicional: nix-shell

Isso configurará automaticamente o Rust, o proxy rtk, todas as bibliotecas de sistema (TPM2, libnfc, eBPF/XDP) e as SDKs de multilingualidade.

2. Instalação Manual (Alternativa)

Se você optar por não usar Nix, certifique-se de ter o seguinte instalado:

RTK (Rust Token Killer): Proxy obrigatório para economia de tokens.
Rust Toolchain: 1.82.0 ou mais recente (gerenciado via rustup).
Cargo-LLVM-COV: Para relatórios de cobertura.
Pre-commit: Para portões automatizados de linting.
Dependências de Sistema:
- Debian/Ubuntu: libbpf-dev, clang, llvm, libtss2-dev, libnfc-dev.
- macOS: Permissões de administração para manipulação do pf (Packet Filter).

3. Compilando e Executando

Compilando

rtk make build

Executando um Nó

rtk cargo run --bin paebiru-node

4. Executando Testes e Qualidade

O PAEBIRU possui uma “Muralha de Qualidade” rigorosa.

Suíte Completa: rtk make test
Lints e Formatação: rtk make lint e rtk make fmt
Pre-commit: rtk make pre-commit (Mandatório antes de PRs)

Os testes usam um padrão de diretório temporário e limparão seu armazenamento após a conclusão.

5. Configurando o NodeConfig

O nó é configurado através da struct NodeConfig em src/node/config.rs. Campos principais incluem:

home_geo: Sua jurisdição local (4 bytes, ex: PEBR).
storage_path: Onde os shards e o ShardStore são persistidos no disco.
identity_path: Onde sua semente (seed) Ed25519 é salva.
dre_settings:
- energy_source: [Solar, Wind, Grid, etc.] para cálculo do DRE.
- hardware_manufacture_date: Para cálculo do bônus de longevidade.
stigmergy_settings:
- enabled_devices: Lista de interfaces NFC/RFID ativas.
- vault_key_path: Caminho para a semente do Secure Rizoma Vault.
ontology_path: Caminho para as definições semânticas (L9).
bootstrap_peers: Multiaddrs de nós conhecidos.
evm_rpc_url: URL para governança on-chain (opcional).
entropy_settings:
- prefer_hardware_rng: true para usar RDRAND/RNDR quando disponível.
- health_monitor_window: Tamanho da janela APT (padrão: 512 bytes).
- puf_enrollment_path: Onde o response PUF enrollado é persistido.
zk_settings:
- proving_key_cache: Diretório local de proving keys ZK.
- max_proof_age_epochs: Cache de provas por época (padrão: 1).
pol_settings:
- anchor_peers: Lista de multiaddrs de nós âncora locais.
- max_position_error_m: Tolerância de erro de trilateração (padrão: 500 m).
- geofence_level: Nível S2 do geofence local (padrão: 13).
compute_settings:
- max_bid_joules: Teto de pagamento para tarefas CoD recebidas.
- verifier_fraction: Fração de tarefas enviadas para verificação (padrão: 0.1).
learning_settings:
- fl_enabled: Participar de rodadas de Federated Learning.
- local_dataset_path: Dataset local para treino (formato HDF5 ou CSV).
- max_local_epochs: Épocas de treino por rodada (padrão: 2).

Injetando Segredos

Nunca escreva chaves privadas diretamente no código. Injete a evm_signing_key via uma variável de ambiente.

5. Integração EVM (Opcional)

Para habilitar a governança on-chain:

Forneça uma evm_rpc_url.
Implante ou use um contrato PaebiruRegistry existente.
Garanta que sua evm_signing_key corresponda a uma EOA com pelo menos 0.01 ETH para staking e heartbeats.

6. Primeiro Teste de Integração

Execute o teste de descoberta “Nó Zero” para verificar seu ambiente local:

cargo test --test discovery

Este teste sobe dois nós e verifica se eles conseguem se encontrar via mDNS e trocar um Ping.

7. Trabalhando com a CLI e SDK

O PAEBIRU fornece ferramentas para facilitar o ciclo de desenvolvimento.

Usando a paebiru-cli

A CLI se comunica com o nó local via API HTTP (porta 1975 por padrão).

Status da Malha: cargo run -p paebiru-cli -- status
Ganhos de Token (RTK): rtk gain (Verifica economia via proxy de tokens).
Visualizador Interativo (TUI): cargo run -p paebiru-cli -- view
Metabolismo Local: cargo run -p paebiru-cli -- metabolism (Visualiza dor/energia/DRE).
Deploy de Módulo: cargo run -p paebiru-cli -- deploy <caminho.wasm> --geo PEBR
Execução de Módulo: cargo run -p paebiru-cli -- run <hash-blake3> --input "dados" --streaming

Desenvolvendo Módulos com o SDK

Os módulos devem ser compilados para o target wasm32-wasip1.

Adicione a dependência: paebiru-sdk = { version = "x.y.z" }
Use a macro define_main! para o ciclo metabólico:

#![allow(unused)]
fn main() {
use paebiru_sdk::{Context, define_main, SovereignReceipt};

fn my_app(ctx: Context) -> SovereignReceipt {
    ctx.log("Iniciando Antropofagia Cibernética...");

    // Verifica alinhamento semântico
    if ctx.alignment() < 0.8 {
        return ctx.dissonance("Intento desalinhado com a ontologia local");
    }

    // Processamento/Digestão
    let result = ctx.metabolize("dados_brutos");

    // Excreção Soberana do resultado
    ctx.excrete(format!("Utilidade social produzida: {}", result))
}
define_main!(my_app);
}

Compile: cargo build --target wasm32-wasip1

Usando o cliente x402 (CoD)

O PaebiruClient lida com o ciclo HTTP 402 automaticamente:

#![allow(unused)]
fn main() {
use paebiru_sdk::PaebiruClient;

let client = PaebiruClient::new("http://compute-node:1975")
    .max_joules(10_000);

// POST /compute → 402 → paga → recebe TaskReceipt
let receipt = client.compute(wasm_bytes, input_bytes).await?;
println!("output_hash: {:?}", receipt.output_hash);
println!("joules_used: {}", receipt.joules_used);
println!("landauer_min_joules: {:.2e}", receipt.landauer_ledger.minimum_joules());
}

Participando de Federated Learning

Com fl_enabled = true no config, o LearnerAgent aguarda LEARNING_TRIGGER no bus:

# Verificar rodadas ativas
cargo run -p paebiru-cli -- fl-status

# Forçar participação manual em uma rodada
cargo run -p paebiru-cli -- fl-join --round-id <uuid>

O agente calibra automaticamente pruning e quantização baseado no pain_level atual. Para forçar alta compressão em hardware limitado:

PAEBIRU_FL_MAX_PRUNING=0.9 cargo run --bin paebiru-node

Desenvolvendo com o SDK Go (TinyGo)

Módulos em Go devem ser compilados usando o compilador TinyGo.

Inicialize seu módulo: go mod init my-app
Adicione o SDK: go get github.com/paebiru/paebiru-sdk-go
Exporte a função principal seguindo o metabolismo:

//export paebiru_main
func paebiru_main(a, b int32) int32 {
    ctx := paebiru.NewContext()
    ctx.Log("Devorando fluxos de dados...")

    // Lógica de digestão local
    data := ctx.ReadInput()
    processed := digest(data)

    // Excreção Soberana
    return ctx.ExcreteSovereign(processed)
}

Compile para WASI: tinygo build -o module.wasm -target=wasi main.go

8. Compilação Cruzada (Opcional)

Se você estiver desenvolvendo para hardware específico (ex: Raspberry Pi Zero 2W, ESP32-C3), precisará instalar os toolchains de compilação cruzada.

Alpine Linux (x86_64-unknown-linux-musl)

Para rodar em containers Alpine ou sistemas baseados em musl:

Alpine: apk add build-base git curl libtss2-dev
Outros: rustup target add x86_64-unknown-linux-musl

cargo build --target x86_64-unknown-linux-musl --release

Nix (NixOS / Nix Package Manager)

O PAEBIRU fornece suporte oficial ao Nix para ambientes reprodutíveis.

Usando Flakes (Recomendado): nix develop
Usando Nix Shell Tradicional: nix-shell

Isso configurará automaticamente o Rust, todas as bibliotecas de sistema (TPM2, Vulkan, libnfc) e as SDKs de multilingualidade.

Raspberry Pi Zero 2W (AArch64 Linux)

Para compilar para o gateway em Raspberry Pi, instale o cross-compiler:

Debian/Ubuntu: sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
Fedora: sudo dnf install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
Arch Linux: sudo pacman -S aarch64-linux-gnu-gcc aarch64-linux-gnu-g++
macOS/Windows: Recomendamos o uso de cross ou cargo-zigbuild.

# Usando cargo-zigbuild (Recomendado)
cargo install cargo-zigbuild
cargo zigbuild --target aarch64-unknown-linux-gnu --release

ESP32-C3 e STM32

O PAEBIRU CLI facilita o flash para estes dispositivos, mas requer os targets Rust instalados:

rustup target add riscv32imc-unknown-none-elf thumbv7em-none-eabihf

Para ESP32, você também precisará do espflash: cargo install espflash. Para STM32, instale o probe-rs: cargo install probe-rs-cli.

Keyboard shortcuts