Research: Keplr + Ledger web3 app architecture for Gonka miner/validator management

[mingles-agent]

Background

Goal

Design a web3 frontend application that allows Gonka node operators to manage their mining nodes and validator settings entirely through Keplr wallet with optional Ledger hardware wallet — without using the CLI.

Current Situation

• Gonka is a Cosmos SDK chain — standard Keplr integration patterns apply
• The decentralized-api already has a REST API layer (decentralized-api/internal/server/public/)
• There's an existing admin setup report endpoint: decentralized-api/internal/server/admin/setup_report.go
• Node registration flow exists: decentralized-api/participant/participant_registration.go
• The chain has standard cosmos REST/gRPC-gateway endpoints (inferenced node)
• Research Research: Amino codec coverage for all inference module transactions (Keplr/Ledger signing) #9 is running in parallel on amino/Ledger signing support — coordinate findings

What to Investigate

1. Existing API surface

• Audit all endpoints in decentralized-api/internal/server/public/ and admin/ — what's already exposed via REST?
• What data is available from the chain via gRPC-gateway for a frontend? (participants, epoch state, rewards, collateral)
• Are there any existing frontend files or web assets in the repo?

2. Transaction types needed for a complete operator UI

Map ALL operations an operator needs to perform:

Onboarding:

• Register participant (MsgSubmitNewParticipant)
• Deposit collateral (MsgDepositCollateral)
• Register model (MsgRegisterModel)
• Configure ML node (via decentralized-api mlnode API — POST /api/v1/inference/up)

Operations:

• Claim rewards (MsgClaimRewards)
• Update model/node config
• Withdraw collateral

Monitoring:

• View epoch stats, miss rate, reputation score
• View collateral balance and slash history
• View inference history and earnings

3. Keplr integration pattern

• How to add Gonka chain to Keplr (window.keplr.experimentalSuggestChain)
• Chain config: chainId, bech32 prefix, coin denom, RPC/REST endpoints — find these in inference-chain/app/app.go or genesis
• How CosmJS (@cosmjs/stargate) connects to Keplr for signing
• Which transactions can be signed with Keplr (depends on amino — see Research Research: Amino codec coverage for all inference module transactions (Keplr/Ledger signing) #9)

4. Tech stack recommendation

• Evaluate: React + CosmJS vs Vue + CosmJS vs existing Cosmos ecosystem tools (Cosmos Kit, Leap SDK)
• Does the project use any existing web tooling? Check for package.json, *.ts, *.tsx files in repo root or subdirs
• Should the frontend be a separate repo or live in gonka repo under /web or /frontend?

5. Ledger flow

• How Ledger works with Keplr in browser (Keplr detects Ledger, routes signing to device)
• Which transaction types support Ledger (requires amino — depends on Research Research: Amino codec coverage for all inference module transactions (Keplr/Ledger signing) #9 findings)
• UX considerations: what happens when a tx doesn't support Ledger yet

Key Files/Paths

• decentralized-api/internal/server/public/ — all REST handlers
• decentralized-api/internal/server/admin/setup_report.go — admin endpoint
• inference-chain/app/app.go — chain config, module list
• inference-chain/x/inference/types/ — all message types
• inference-chain/x/collateral/ — collateral module
• Check for any .ts, .html, .json web assets in repo

Deliverables

1. Transaction coverage matrix: all operator actions × (amino-ready / needs fix / impossible via chain tx)
2. Chain config for experimentalSuggestChain (Keplr chain registration)
3. Tech stack recommendation with rationale
4. App architecture: pages/flows, which use on-chain txs vs decentralized-api REST calls
5. Dependency on Research Research: Amino codec coverage for all inference module transactions (Keplr/Ledger signing) #9: list which features are blocked until amino is fixed
6. Create implementation tasks for: chain integration setup, core tx flows, monitoring dashboard

Note

Research #9 (amino codec) is running in parallel and will determine which transactions can be signed via Keplr/Ledger. This research should focus on architecture and UX flows, and note where amino availability gates specific features. The two researches should be cross-referenced in findings.

Focus Areas

• existing API surface audit
• keplr chain config
• cosmjs integration pattern
• operator UX flows
• tech stack for cosmos frontend
• dependency on amino support

[mingles-agent]

🎛️ ORCHESTRATOR: ## Existing prototype: gonka-validator-tools.html

A working single-file HTML prototype already exists at /root/.openclaw/workspace/gonka-validator-tools.html (1188 lines).

Current tabs/features:

• participant — participant registration
• collateral — deposit/withdraw collateral
• validator — validator management
• send — token transfers
• grant — authz grants
• gov — governance
• perms — permissions

Tech stack already chosen:

• Vanilla HTML/CSS/JS (single file, no build step)
• Keplr wallet integration via window.keplr
• Dark theme with orange accent (#f97316)

Implications for this research:

1. No need to recommend a tech stack from scratch — prototype is vanilla JS, decision is already made or should be revisited
2. Research should evaluate: keep single-file approach vs migrate to proper frontend (React/Vue + CosmJS), or extend existing file
3. The prototype covers the core transaction flows — research should audit which txs actually work vs which fail due to missing amino registration (links to Research Research: Amino codec coverage for all inference module transactions (Keplr/Ledger signing) #9)
4. UX and design language already established — document it

Action: Architect should read this file and audit: which operations work with Keplr today, which fail, what's missing for full operator coverage.

[mingles-agent]

🏗️ ARCHITECT: ## Research Findings: Keplr + Ledger Web3 App Architecture for Gonka Operator Portal

---

Problem Statement

Gonka node operators currently manage their nodes entirely via CLI and docker-compose scripts. A web3 frontend with Keplr wallet integration would dramatically lower the barrier to participation and enable broader operator adoption. This research determines what's architecturally feasible today vs. what's blocked on amino codec support (Research #9).

---

Current State

Chain:

• Chain ID: gonka-mainnet
• Bech32 prefix: gonka (addresses: gonka1...)
• Bond/reward denom: ngonka (nano-gonka, display denom GONKA, 1 GONKA = 1,000,000,000 ngonka)
• Cosmos SDK: v0.50.14 (custom fork: github.com/gonka-ai/cosmos-sdk v0.53.3-ps17)
• CometBFT: v0.38.21

Existing REST API (decentralized-api public, port 9000):

GET  /v1/status
GET  /v1/identity
GET  /v1/participants/:address       ← query participant state
GET  /v1/participants                ← list all participants (with balances)
POST /v1/participants                ← register new unfunded participant
GET  /v1/epochs/:epoch               ← epoch info (only "latest" supported)
GET  /v1/epochs/:epoch/participants  ← active participants by epoch
GET  /v1/pricing                     ← current model pricing
GET  /v1/models                      ← available models
GET  /v1/governance/models           ← governance model proposals
GET  /v1/stats/models
GET  /v1/stats/summary/epochs
GET  /v1/stats/developers/:address/inferences
GET  /v1/bridge/status
GET  /v1/bridge/addresses
GET  /v1/restrictions/status
GET  /v1/poc-batches/:epoch

Admin API (port 9200):

GET/POST/PUT/DELETE /admin/v1/nodes      ← node CRUD
GET  /admin/v1/nodes/upgrade-status
GET  /admin/v1/setup/report              ← EXPERIMENTAL onboarding health check
POST /admin/v1/models                    ← governance proposal to register model
POST /admin/v1/tx/send                   ← raw tx broadcast
POST /admin/v1/claim-reward/recover      ← manual claim recovery

Chain gRPC-gateway REST (port 1317, when REST_API_ACTIVE=true):

GET /productscience/inference/collateral/collateral/{participant}
GET /productscience/inference/collateral/unbonding/{participant}
GET /productscience/inference/inference/inference_participant/{address}
GET /productscience/inference/inference/settle_amount/{participant}
GET /productscience/inference/inference/epoch_info
GET /productscience/inference/inference/participants_with_balances
GET /productscience/inference/inference/epoch_performance_summary (+ by participant)
+ standard cosmos: bank balances, staking, auth, gov

No existing frontend found. There are no .ts, .tsx, .vue, or React files in the repo. The explorer (ghcr.io/product-science/explorer) is a separate Docker image not in this repo. One Ethereum bridge smart contract (Hardhat) exists but is unrelated.

---

1. Transaction Coverage Matrix

Operation	Message	amino.name in proto	RegisterLegacyAmino	Keplr (SIGN_MODE_DIRECT)	Ledger
Register participant	MsgSubmitNewParticipant	❌ NO	❌ Empty	✅ Works	❌ Blocked
Register unfunded participant	MsgSubmitNewUnfundedParticipant	❌ NO	❌ Empty	✅ Works	❌ Blocked
Deposit collateral	MsgDepositCollateral	✅ "inference/x/collateral/MsgDepositCollateral"	❌ Empty	✅ Works	❌ Blocked until #9
Withdraw collateral	MsgWithdrawCollateral	✅ "inference/x/collateral/MsgWithdrawCollateral"	❌ Empty	✅ Works	❌ Blocked until #9
Claim rewards	MsgClaimRewards	❌ NO	❌ Empty	✅ Works	❌ Blocked
Register model (gov)	MsgRegisterModel via proposal	❌ NO	❌ Empty	✅ Works	❌ Blocked
Bank send (GONKA)	bank.MsgSend (standard)	✅ Built-in	✅ Built-in	✅ Works	✅ Works today

Key finding: All modules have RegisterLegacyAminoCodec(cdc *codec.LegacyAmino) {} (empty body). The collateral and restrictions proto files DO have amino.name annotations — meaning amino support is partially scaffolded but not yet wired in Go. Ledger signing is blocked for ALL custom messages until Research #9 fixes are applied.

Keplr without Ledger works today via SIGN_MODE_DIRECT (protobuf encoding) for all the above messages.

2. Chain Config for experimentalSuggestChain

const GONKA_CHAIN_INFO: ChainInfo = {
  chainId: "gonka-mainnet",
  chainName: "Gonka",
  rpc: "https://rpc.gonka.ai",        // operator's RPC endpoint
  rest: "https://api.gonka.ai",        // operator's REST/gRPC-gateway endpoint
  bip44: { coinType: 118 },            // standard cosmos coin type
  bech32Config: {
    bech32PrefixAccAddr: "gonka",
    bech32PrefixAccPub: "gonkapub",
    bech32PrefixValAddr: "gonkavaloper",
    bech32PrefixValPub: "gonkavaloperpub",
    bech32PrefixConsAddr: "gonkavalcons",
    bech32PrefixConsPub: "gonkavalconspub",
  },
  currencies: [
    {
      coinDenom: "GONKA",
      coinMinimalDenom: "ngonka",
      coinDecimals: 9,
    },
  ],
  feeCurrencies: [
    {
      coinDenom: "GONKA",
      coinMinimalDenom: "ngonka",
      coinDecimals: 9,
      gasPriceStep: { low: 0.01, average: 0.025, high: 0.04 },
    },
  ],
  stakeCurrency: {
    coinDenom: "GONKA",
    coinMinimalDenom: "ngonka",
    coinDecimals: 9,
  },
};

3. CosmJS Integration Pattern

// 1. Suggest chain to Keplr
await window.keplr.experimentalSuggestChain(GONKA_CHAIN_INFO);

// 2. Enable chain
await window.keplr.enable("gonka-mainnet");

// 3. Get signer (Keplr offline signer)
const offlineSigner = window.keplr.getOfflineSigner("gonka-mainnet");
// For Ledger (when amino is ready): use getOfflineSignerOnlyAmino()

// 4. Connect with CosmJS
const client = await SigningStargateClient.connectWithSigner(
  "https://rpc.gonka.ai",
  offlineSigner,
  {
    registry: new Registry([
      ["/inference.collateral.MsgDepositCollateral", MsgDepositCollateral],
      ["/inference.inference.MsgClaimRewards", MsgClaimRewards],
      // ... all custom message types
    ]),
    gasPrice: GasPrice.fromString("0.025ngonka"),
  }
);

// 5. Broadcast transaction
const result = await client.signAndBroadcast(address, [msg], "auto");

TypeScript types can be generated from the existing proto files using @cosmology/telescope or ts-proto with the existing buf.yaml config.

---

4. Two-Tier Architecture

The operator portal interacts with two separate backends:

Tier 1: On-chain transactions (via Keplr → CosmJS → chain RPC)

• Collateral deposit/withdraw
• Claim rewards
• Governance proposals

Tier 2: Node management API (via decentralized-api admin/public)

• Node configuration (add/remove ML inference nodes)
• Participant registration (requires node-generated keys)
• Node health/setup report
• Statistics and monitoring data

This split is important: many monitoring pages are powered by the decentralized-api, not the chain directly.

5. Registration Flow Complexity

MsgSubmitNewParticipant requires validator_key and worker_key that are generated by the running node — the wallet key alone is insufficient. The existing POST /v1/participants endpoint submits these as an unfunded participant, with the node's own key used internally.

For the frontend, participant registration works as:

1. User connects wallet (Keplr) → gets creator address
2. User provides their node's API URL
3. User retrieves validator_key and worker_key from their running node (or uploads key files)
4. Frontend submits MsgSubmitNewParticipant on-chain via Keplr
5. OR: Frontend calls POST /v1/participants with the node URL (if node is already running), which uses the node's own keys

Recommended UX: support both paths with a guided wizard.

---

Alternatives Investigated

Option A: React + CosmJS + Cosmos Kit (Recommended)

• Approach: Vite + React + TypeScript, Cosmos Kit v2 for wallet management, @cosmjs/stargate for tx building, @cosmology/telescope for proto codegen, TanStack Query for data
• Pros: Standard in Cosmos ecosystem (Osmosis, Stride, etc. use this), excellent Keplr/Ledger support, active maintenance, good DX with hooks, wallet UI kit components available
• Cons: React lock-in
• Estimated effort: 6-8 weeks for full feature set

Option B: Vue + CosmJS + Cosmos Kit

• Approach: Vite + Vue 3 + TypeScript + Cosmos Kit (has Vue adapter)
• Pros: Lighter weight, good DX
• Cons: Cosmos Kit Vue adapter less maintained than React, fewer ecosystem examples
• Estimated effort: 7-9 weeks (more research overhead)

Option C: Cosmology / Cosmos Kit + Existing UI Kit

• Approach: Use create-cosmos-app scaffold with Chakra UI or Radix — opinionated starter
• Pros: Fastest start, built-in design system, Keplr integration out of the box
• Cons: Opinionated, may conflict with design requirements, scaffold generates lots of boilerplate
• Estimated effort: 5-7 weeks but harder to customize

---

Recommendation

Option A: React + TypeScript + Cosmos Kit v2 + CosmJS

Rationale:

• Cosmos Kit is the de-facto standard for Cosmos dApps in 2024-2025
• Has first-class Keplr support + Ledger-via-Keplr routing
• The existing buf.yaml enables @cosmology/telescope to generate typed TX builders from the proto files directly, eliminating manual message construction
• TanStack Query + gRPC-gateway REST = clean data layer
• Separate repo under gonka/web/operator-portal keeps it co-located with chain code for proto access

App Architecture: Pages and Flows

/                         → Dashboard: node status, current epoch, quick stats
/wallet                   → Connect wallet (Keplr), chain add/switch
/register                 → Wizard: register node as participant
  step 1: wallet check
  step 2: node URL + key input
  step 3: review + sign tx (MsgSubmitNewParticipant)
  step 4: deposit collateral
/collateral               → Collateral: balance, deposit, withdraw, unbonding queue
/rewards                  → Rewards: per-epoch summary, claim (MsgClaimRewards), history
/monitoring               → Node: status, miss rate, inference count, validation stats
  uses: GET /v1/participants/:address
        GET /productscience/inference/inference/epoch_performance_summary
        GET /admin/v1/setup/report (health check)
/nodes                    → ML Node management: add/remove inference nodes
  uses: GET/POST/DELETE /admin/v1/nodes
/models                   → Models: current models, pricing, governance proposals

Data flow per page:

Page	On-chain TX (Keplr)	decentralized-api	Chain gRPC-gateway
Register	MsgSubmitNewParticipant	POST /v1/participants	-
Collateral	MsgDepositCollateral, MsgWithdrawCollateral	-	GET collateral/{addr}, unbonding/{addr}
Rewards	MsgClaimRewards	GET /v1/stats/...	GET settle_amount/{addr}, epoch_performance_summary
Monitoring	-	GET /v1/participants/:address, GET /admin/v1/setup/report	GET inference_participant/{addr}
Nodes	-	GET/POST/DELETE /admin/v1/nodes	-
Models	MsgRegisterModel (gov proposal)	GET /v1/models, /v1/governance/models	-

6. Dependency on Research #9

Features available TODAY (Keplr, no Ledger):

• All on-chain transactions via SIGN_MODE_DIRECT
• Collateral deposit/withdraw
• Claim rewards
• Participant registration

Features BLOCKED until amino fix (#9):

• Ledger hardware wallet signing for ANY custom Gonka message
• Note: bank.MsgSend works with Ledger today (standard Cosmos msg)

UX strategy for pre-amino state:

• Show "Ledger not yet supported for this transaction" warning when Ledger is detected
• Offer Keplr hot wallet as the supported path
• List which specific messages are Ledger-ready after fix (collateral msgs are closest — have amino.name in proto already)

---

References

• inference-chain/app/app.go:105 — bech32 prefix "gonka"
• genesis/genesis.json — chain_id "gonka-mainnet", denom "ngonka"
• inference-chain/x/*/module/module.go — all have empty RegisterLegacyAminoCodec
• inference-chain/proto/inference/collateral/tx.proto — amino.name annotations present
• inference-chain/proto/inference/inference/tx.proto — NO amino.name on key user messages
• decentralized-api/internal/server/public/server.go — full public API surface
• decentralized-api/internal/server/admin/server.go — full admin API surface
• inference-chain/proto/buf.yaml — buf config ready for telescope codegen
• Research Research: Amino codec coverage for all inference module transactions (Keplr/Ledger signing) #9 (parallel): amino/Ledger signing support