SDK — `paebiru-sdk`

Referência da SDK Rust para escrever Plasmídeos WASM soberanos e construir clientes nativos que falam com nós PAEBIRU.

Detalhe granular em crates/sdk/README.md. Esta página é a visão de referência consolidada.

Quando usar

Cenário	Componente
Escrever um plasmídeo WASM que roda dentro de `MacrophageVM`	`Context` + macro `define_main!`
Construir um cliente externo que consome `POST /compute`	`PaebiruClient` (feature `client`)
Gerar/verificar Range Proofs sem rodar o nó	`PaebiruZkClient` (feature `zk`)

Ciclo metabólico do plasmídeo

Todo plasmídeo segue o ciclo soberano Ingerir → Metabolizar → Excretar. O resultado é um SovereignReceipt:

SovereignReceipt::Success(bytes) — execução normal.
SovereignReceipt::Dissonance(reason) — recusa argumentada (não é erro técnico; é dissenso semântico, base do alinhamento L9).
SovereignReceipt::AwaitingConvergence(ticket) — indica que o plasmídeo disparou uma ação que requer assinatura de limiar (FROST) e está aguardando a coleta assíncrona de $K$ assinaturas parciais na malha.

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

fn my_plasmid(ctx: Context) -> SovereignReceipt {
    let input = ctx.read_input();
    if ctx.alignment() < 0.5 {
        return ctx.dissonance("Alinhamento insuficiente");
    }
    ctx.excrete(format!("Processado: {:?}", input))
}

define_main!(my_plasmid);
}

A macro define_main! gera o entry-point WASM extern "C" fn run() que o WasmExecutor (contexto Economia) chama.

API do `Context` (FFI segura)

Método	Propósito
`ctx.read_input() -> Vec<u8>`	Lê o payload que o host injetou
`ctx.log(&str)`	Loga via host (entra no event bus)
`ctx.alignment() -> f32`	Proof-of-Alignment local (consulta L9)
`ctx.layer9_granularity() -> Mode`	Consulta o modo de granularidade atual
`ctx.excrete(impl Into<Vec<u8>>) -> SovereignReceipt::Success`	Devolve resultado soberano
`ctx.dissonance(reason) -> SovereignReceipt::Dissonance`	Recusa argumentada

Cliente nativo (`PaebiruClient`)

Feature client — embute reqwest + Tokio. Cuida automaticamente do fluxo HTTP 402 Payment Required (API.md) e do polling de recibos assíncronos:

use paebiru_sdk::PaebiruClient;
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = PaebiruClient::new("http://localhost:1975");

    // Consulta a granularidade da Camada 9 para ajustar expectativas de latência
    let granularity = client.get_layer9_granularity().await?;
    println!("Modo Layer 9: {:?}", granularity);

    let result = client.submit_compute_job(
        json!({"task": "analyze_signal", "payload": "..."}),
        Some("ML-DSA")  // negocia suíte PQ
    ).await?;
```,old_string:
    // Se o resultado for AwaitingConvergence, o cliente pode aguardar a finalização
    let final_receipt = client.wait_for_convergence(result).await?;
    println!("{:?}", final_receipt);
    Ok(())
}

O cliente:

Faz POST /compute.
Recebe 402 com X-Payment-Required (ask em Joules, nonce, recipient).
Constrói e assina JouleTransfer (PQ via ML-DSA).
Retransmite com header X-Payment.
Recebe TaskReceipt e devolve ao chamador.

Configurável via PaebiruClient::with_max_joules(N) — recusa requests cuja ask supera o teto.

Zero-Knowledge (`PaebiruZkClient`, feature `zk`)

Range proofs Groth16 (BLS12-381):

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

let proof = PaebiruZkClient::prove_range(value, bits)?;
assert!(PaebiruZkClient::verify_proof(&proof)?);
}

Provas têm ~128 bytes; verificação < 2 ms. Sem expor value. Para STARK (PQC-safe, transparente) usar paebiru-zk diretamente — STARKs ainda não são roteadas pela SDK em v1.

Features Cargo

Feature	Inclui
default	apenas `Context` + `SovereignReceipt` (`no_std`-friendly em WASM)
`client`	`PaebiruClient`, `reqwest`, `tokio`
`zk`	`PaebiruZkClient`, vinculação com `paebiru-zk`

Padrões reutilizáveis

Opaque Handle — toda struct exposta para FFI é um handle opaco; nunca o cliente manipula ponteiros brutos. Aplica-se também aos 12 bindings (bindings/README.md).
402 Auto-Negotiation — sempre delegue o handshake econômico para PaebiruClient; jamais reimplemente.
Mais padrões em PATTERNS.md.

Cross-references

API.md — endpoints HTTP que a SDK consome.
ECONOMY.md — WasmExecutor que roda o plasmídeo.
SDK_RELEASE_GUIDE.md — distribuição multi-linguagem.
ASYNC_DESIGN_RATIONALE.md — modelo async dos bindings.
crates/sdk/README.md — referência local granular.

Keyboard shortcuts