Summary

Integrate gonka.ai, a decentralized AI inference network on a Cosmos-SDK chain that routes LLM requests to a peer-to-peer pool of GPU operators. Two access paths, shipped in two phases:

Phase 1 — GonkaGate (MVP)

CompatibleProvider already speaks OpenAI Chat Completions. Phase 1 is wizard + config + docs only:

• Wizard option "Gonka (decentralized — via GonkaGate)" pre-fills name = "gonkagate", base_url = "https://api.gonkagate.com/v1"
• Vault key: ZEPH_COMPATIBLE_GONKAGATE_API_KEY (existing convention)
• Docs page, default.toml template, spec entry, playbook, coverage-status row

Phase 2 — Native gonka transport

New module crates/zeph-llm/src/gonka/:

• RequestSigner — ECDSA over secp256k1 via k256 crate, bech32 address derivation
• EndpointPool — round-robin over node URLs with fail-skip
• GonkaProvider — wraps OpenAiProvider for body building / response decoding, owns its own signed reqwest send path
• Headers per request: Authorization (base64 ECDSA sig), X-Requester-Address (bech32), X-Timestamp (nanoseconds)
• Signature input: payload_hash_hex || timestamp_ns_str || transfer_address, then sha256 then sign
• Wallet generation stays out of zeph — user runs inferenced keys add and zeph imports the exported private key into the age vault
• New vault keys: ZEPH_GONKA_PRIVATE_KEY, ZEPH_GONKA_ADDRESS

Strategy decisions (recorded)

• Gateway-first: Phase 1 ships as MVP; Phase 2 lands in a follow-up minor release.
• Hybrid wallet: reuse inferenced CLI for key generation (no Cosmos wallet code in zeph for now).
• Issue layout: epic + child issues, one PR per issue, < 30 min review each.

Child issues

Phase 1 — Gateway MVP (release blockers)

• docs(gonka): integration guide for gateway and native paths #3603 — docs(gonka): integration guide for gateway and native paths · M
• feat(wizard): add "Gonka (gateway)" branch to zeph init #3604 — feat(wizard): add "Gonka (gateway)" branch to zeph init · S
• feat(config): provider entry template for gonkagate in default.toml #3605 — feat(config): provider entry template for gonkagate in default.toml · S
• test(playbook): gonka gateway live scenarios + coverage-status row #3606 — test(playbook): gonka gateway live scenarios + coverage-status row · S

Phase 2 — Native transport (release blockers)

• feat(config): add ProviderKind::Gonka and gonka_nodes / gonka_chain_prefix schema #3607 — feat(config): add ProviderKind::Gonka and gonka_nodes / gonka_chain_prefix schema · S
• feat(secrets): resolve ZEPH_GONKA_PRIVATE_KEY and ZEPH_GONKA_ADDRESS from vault #3608 — feat(secrets): resolve ZEPH_GONKA_PRIVATE_KEY and ZEPH_GONKA_ADDRESS from vault · S · depends on feat(config): add ProviderKind::Gonka and gonka_nodes / gonka_chain_prefix schema #3607
• feat(zeph-llm): RequestSigner with k256 + bech32 + Python-derived fixtures #3609 — feat(zeph-llm): RequestSigner with k256 + bech32 + Python-derived fixtures · M
• feat(zeph-llm): EndpointPool round-robin with fail-skip #3610 — feat(zeph-llm): EndpointPool round-robin with fail-skip · S
• feat(zeph-llm): GonkaProvider chat / chat_stream / embed (signed transport) #3611 — feat(zeph-llm): GonkaProvider chat / chat_stream / embed (signed transport) · L · depends on feat(config): add ProviderKind::Gonka and gonka_nodes / gonka_chain_prefix schema #3607 feat(secrets): resolve ZEPH_GONKA_PRIVATE_KEY and ZEPH_GONKA_ADDRESS from vault #3608 feat(zeph-llm): RequestSigner with k256 + bech32 + Python-derived fixtures #3609 feat(zeph-llm): EndpointPool round-robin with fail-skip #3610
• feat(zeph-llm): GonkaProvider chat_with_tools / chat_typed (extract openai/wire.rs) #3612 — feat(zeph-llm): GonkaProvider chat_with_tools / chat_typed (extract openai/wire.rs) · M · depends on feat(zeph-llm): GonkaProvider chat / chat_stream / embed (signed transport) #3611
• feat(core+wizard): build_gonka_provider, AnyProvider::Gonka, native wizard branch with inferenced integration #3613 — feat(core+wizard): build_gonka_provider, AnyProvider::Gonka, native wizard branch with inferenced integration · M · depends on feat(secrets): resolve ZEPH_GONKA_PRIVATE_KEY and ZEPH_GONKA_ADDRESS from vault #3608 feat(zeph-llm): RequestSigner with k256 + bech32 + Python-derived fixtures #3609 feat(zeph-llm): GonkaProvider chat / chat_stream / embed (signed transport) #3611 feat(zeph-llm): GonkaProvider chat_with_tools / chat_typed (extract openai/wire.rs) #3612

Phase 2 — Follow-up (next minor release)

• feat(cli): zeph gonka doctor diagnostic subcommand + live testnet ignored test #3614 — feat(cli): zeph gonka doctor diagnostic subcommand + live testnet ignored test · M · depends on feat(core+wizard): build_gonka_provider, AnyProvider::Gonka, native wizard branch with inferenced integration #3613

Sequencing

Phase 1:  #3603 (parallel) → #3604 → #3605 → #3606 → release
Phase 2:  (#3607 + #3609 + #3610 in parallel) → #3608 → #3611 → #3612 → #3613 → release
Follow-up: #3614 → next minor release

Epic-level acceptance

A fresh user runs zeph init, picks Gonka (gateway), pastes a gp-... API key, and gets a chat reply on the first prompt within 5 minutes. Phase 2 acceptance: a user with inferenced installed runs the wizard's "native" branch and gets a chat reply against node1.gonka.ai.

Reference

• Plan: .local/plan/gonka-ai-structured-bentley.md (in repo, not committed)
• Gonka docs: https://gonka.ai/docs
• Reference SDK: https://github.com/gonka-ai/gonka-openai (MIT)
• GonkaGate: https://gonkagate.com

Risks

1. Signature scheme drift (High) — Python reference may use hybrid_timestamp_ns(); live testnet probe gates issue feat(zeph-llm): RequestSigner with k256 + bech32 + Python-derived fixtures #3609 merge.
2. Body canonicalisation (Medium) — sign byte-identity via reqwest::body(Vec<u8>); fixture tests cover Unicode + nested JSON.
3. Clock skew (Medium) — CI VMs drift; doctor subcommand checks NTP.
4. inferenced CLI breaking changes (Medium) — pin MIN_INFERENCED_VERSION.
5. Testnet bech32 prefix (Low) — gonka_chain_prefix config field exposed.

Out of scope

• Native Rust Cosmos wallet (BIP39/BIP32). Use inferenced externally.
• GNK token purchase / faucet integration.
• Multi-account support per process.
• Vision input (gonka catalog is text-only at launch).