A Cosmos SDK blockchain with Zero-Knowledge Proof anonymity, CosmWasm smart contracts, and Multi-Asset DEX
Features • Quick Start • Documentation • Roadmap
Website • Wiki • Whitepaper • Telegram
TrueRepublic is a platform for direct democracy and digital self-determination. Instead of electing representatives, participants make decisions directly through community-governed Domains using Systemic Consensing (rating -5 to +5) and Stones Voting.
The native token PNYX -- named after the hill in Athens where citizens gathered to vote -- powers governance, treasury mechanisms, staking, and a built-in DEX.
For Developers:
For Users:
For Node Operators:
For Security:
| Guide | Audience | Description |
|---|---|---|
| Getting Started | Everyone | Choose your path: user, operator, validator, or developer |
| Installation | Everyone | Quick install guide (Docker / native / web wallet) |
| User Manual | End Users | Wallet, governance, voting, DEX trading |
| Node Operators | Operators | Setup, configuration, monitoring, backup |
| Validator Guide | Validators | PoD consensus, staking, slashing, operations |
| Developer Docs | Developers | Architecture, API reference, CosmJS, smart contracts |
| FAQ | Everyone | Frequently asked questions |
| Glossary | Everyone | Term definitions |
| Whitepaper | Everyone | Full whitepaper |
# Clone
git clone https://github.com/NeaBouli/TrueRepublic.git
cd TrueRepublic
# Option A: Docker (full stack)
cp .env.example .env && make docker-build && make docker-up
# Option B: Build from source
make build && ./build/truerepublicd start
# Option C: Web wallet only
cd web-wallet && npm install && npm startSee INSTALLATION.md for detailed instructions.
| Feature | Description | Docs |
|---|---|---|
| Domains | Community-governed spaces for specific topics | Governance Tutorial |
| Systemic Consensing | Rate proposals -5 to +5 instead of Yes/No | SC Explained |
| Stones Voting | Highlight importance, elect admins, earn rewards | Stones Guide |
| Anonymous Voting | Domain key pairs for unlinkable ratings (WP S4) | Architecture |
| Proof of Domain | Validators must be active domain members | Validator Guide |
| DEX (AMM) | Token swaps with 0.3% fee + 1% PNYX burn | DEX Guide |
| VoteToEarn | Earn PNYX rewards for active participation | Stones Guide |
| Suggestion Lifecycle | Green/yellow/red zones with auto-delete | Governance |
| IBC Transfers | Cross-chain PNYX via ICS-20 (ibc-go v8) | IBC Setup |
React-based web client with full governance and DEX functionality:
cd client-web
npm install
npm run dev- Wallet: Create/import, encrypted storage, send PNYX
- Governance: Browse domains, vote anonymously, create suggestions
- DEX: Swap tokens, provide liquidity, manage LP positions
- Membership: Join domains, 2-step onboarding
- Admin: Domain management, member verification
- Explorer: Network stats, validators, blocks, IBC
See client-web/README.md for details.
TrueRepublic/
├── app.go Cosmos SDK application entry point
├── go.mod / go.sum Go module (SDK v0.50.14, CometBFT v0.38.21)
├── Makefile Build targets (build, test, lint, docker)
├── INSTALLATION.md Quick install guide
├── x/
│ ├── truedemocracy/ Governance module (23 msg types, 419 tests)
│ └── dex/ DEX module (6 msg types, 68 tests)
├── treasury/keeper/ Tokenomics equations 1-5 (31 tests)
├── contracts/ CosmWasm workspace (7 crates, 26 tests)
│ ├── core/ Governance + treasury contracts
│ ├── packages/bindings/ TrueRepublic custom query/msg types
│ ├── packages/testing-utils/ Mock querier, AMM pool, fixtures
│ └── examples/ governance-dao, dex-bot, zkp-aggregator, token-vesting
├── client-web/ React 18 + TypeScript + Vite + CosmJS (v0.4.0)
├── web-wallet/ React 18 + Tailwind + Keplr + CosmJS
├── mobile-wallet/ React Native + Expo
├── docs/
│ ├── getting-started/ Quick start guides
│ ├── user-manual/ End-user documentation (7 guides)
│ ├── node-operators/ Node setup, config, operations (9 guides)
│ ├── validators/ Validator guide with PoD
│ ├── developers/ Architecture, API, integration (8 guides)
│ ├── FAQ.md Frequently asked questions
│ └── GLOSSARY.md Term definitions (60+ terms)
└── .github/ CI/CD workflows (Go, Rust, React, RN)
| Feature | Status | Location |
|---|---|---|
| Domains & Governance | ✅ | x/truedemocracy/keeper.go |
| Systemic Consensing (-5..+5) | ✅ | x/truedemocracy/keeper.go |
| Proof of Domain (PoD) | ✅ | x/truedemocracy/validator.go |
| Validator Slashing | ✅ | x/truedemocracy/slashing.go |
| Tokenomics (eq.1-5) | ✅ | treasury/keeper/rewards.go |
| DEX / AMM (x*y=k) | ✅ | x/dex/keeper.go |
| Multi-Asset DEX (BTC/ETH/LUSD) | ✅ | x/dex/keeper.go (asset registry + trading validation) |
| Node Staking Rewards (10% APY) | ✅ | treasury/keeper/rewards.go (eq.5) |
| Domain Interest (25% APY) | ✅ | treasury/keeper/rewards.go (eq.4) |
| Release Decay | ✅ | treasury/keeper/rewards.go |
| Anonymous Voting (WP S4) | ✅ | x/truedemocracy/anonymity.go |
| Zero-Knowledge Proofs (Groth16) | ✅ | x/truedemocracy/zkp.go |
| CosmWasm Smart Contracts | ✅ | x/truedemocracy/wasm_bindings.go |
| Domain-Bank Bridge | ✅ | x/truedemocracy/treasury_bridge.go |
| IBC Transfer (ICS-20) | ✅ | app.go (ibc-go v8.4.0) |
| Stones Voting (WP S3.1) | ✅ | x/truedemocracy/stones.go |
| VoteToEarn Rewards | ✅ | x/truedemocracy/stones.go |
| Suggestion Lifecycle (WP S3.1.2) | ✅ | x/truedemocracy/lifecycle.go |
| Green/Yellow/Red Zones | ✅ | x/truedemocracy/lifecycle.go |
| Auto-Delete & Fast Delete (2/3) | ✅ | x/truedemocracy/lifecycle.go |
| Admin Election (WP S3.6) | ✅ | x/truedemocracy/governance.go |
| Member Exclusion (2/3 vote) | ✅ | x/truedemocracy/governance.go |
| PoD Transfer Limit (10%, WP S7) | ✅ | x/truedemocracy/validator.go |
| CLI Commands (24 tx + 7 query) | ✅ | x/truedemocracy/cli.go |
| DEX CLI (6 tx + 4 query) | ✅ | x/dex/cli.go |
| CosmWasm Contracts (7 crates) | ✅ | contracts/ (workspace) |
| Web Wallet (React + Keplr) | ✅ | web-wallet/ |
| Mobile Wallet (Expo + RN) | ✅ | mobile-wallet/ |
| CI/CD Workflows | ✅ | .github/workflows/ |
# Blockchain
go mod tidy
go build ./...
go test ./... -race -cover -count=1 -timeout=600s # 533 tests
# Smart contracts
cd contracts && cargo test --workspace # 26 tests
# Web wallet
cd web-wallet && npm install && npm run build
# Mobile wallet
cd mobile-wallet && npm install| Component | Version | Status |
|---|---|---|
| Cosmos SDK | v0.50.14 | Production |
| CometBFT | v0.38.21 | Production |
| CosmWasm | v0.53.3 | Production |
| ibc-go | v8.4.0 | Transfer Active |
| gnark (ZKP) | v0.9.x | Architecture Ready |
| Go | 1.24 | Production |
| Rust | 1.75+ | Contracts |
| React | 18.2 | Web Wallet |
| React Native + Expo | 0.74 / 51.0 | Mobile |
| Keplr + CosmJS | 0.32-0.38 | Wallet |
Known Limitations: IBC staking/upgrade stubbed (PoD used instead), ZKP client integration v0.4.0. See LIMITATIONS.md.
Version: v0.3.0 (100% Complete)
- ✅ 577 tests (533 Go + 26 Rust + 18 Frontend)
- ✅ Core blockchain compiles and runs
- ✅ Whitepaper tokenomics fully implemented (equations 1-5)
- ✅ Complete governance system (domains, proposals, voting, lifecycle)
- ✅ Zero-Knowledge Proofs (Groth16 ZK-SNARKs for anonymous voting)
- ✅ CosmWasm smart contract integration (wasmd v0.53.3)
- ✅ Domain-Bank Bridge (dual accounting, deposit/withdraw)
- ✅ IBC Transfer module (ibc-go v8.4.0, cross-chain PNYX transfers)
- ✅ Multi-Asset DEX: asset registry, trading validation, symbol resolution
- ✅ Cross-Chain Liquidity: multi-hop swaps, pool analytics, slippage protection
- ✅ UI Components: ZKP voting panel, DEX analytics (8 React components)
- ✅ Developer Tooling: 4 CosmWasm example contracts, shared bindings, testing utils
- ✅ DEX with AMM, liquidity pools, swap fees, PNYX burn
- ✅ Web wallet with 3-column governance UI
- ✅ Mobile wallet with bottom-tab navigation
- ✅ Comprehensive documentation (30+ guides)
- ✅ v0.1.x (Feb 2026): Security fixes, documentation, elections
- ✅ v0.2.x (Feb 2026): Governance core — Systemic Consensing, Tokenomics, Elections
- ✅ v0.3.0 (Q1 2026): ZKP Anonymity, CosmWasm, IBC, Multi-Asset DEX (100% COMPLETE)
- ✅ Weeks 1-4: ZKP Anonymity Layer (Groth16, Merkle trees, nullifiers)
- ✅ Week 5: CosmWasm Integration (wasmd v0.53.3, custom bindings)
- ✅ Week 6: Domain-Bank Bridge (dual accounting, deposit/withdraw)
- ✅ Week 7: IBC Integration (ICS-20 transfer, relayer support)
- ✅ Week 8: Multi-Asset DEX (asset registry, trading validation, symbol resolution)
- ✅ Week 9: Cross-Chain Liquidity (multi-hop swaps, analytics)
- ✅ Week 10: UI Components (ZKP voting, DEX analytics)
- ✅ Week 11: Developer Tooling (contract examples, testing utils)
- ✅ Week 12: Complete Documentation (API, deployment, architecture)
- ✅ v0.4.0 (Q1 2026): Web Client (100% COMPLETE)
- ✅ Wallet Foundation (create/import/encrypt/send)
- ✅ Governance UI (domains, issues, suggestions, stones)
- ✅ DEX Interface (swap, liquidity, LP positions)
- ✅ ZKP Anonymous Voting (mock, gnark-wasm ready)
- ✅ Domain Membership & Onboarding
- ✅ Admin Dashboard (member management, stats)
- ✅ Network Explorer (validators, blocks, IBC)
- 📋 v0.5.0 (Q3 2026): Native Apps (iOS/Android)
- 🎯 v1.0.0 (Q4 2026): Production Release — External audit, mainnet launch
v0.3.0 Milestone Achieved! All 12 weeks of the roadmap completed. 577 tests (533 Go + 26 Rust + 18 Frontend), zero regressions.
| Guide | Description |
|---|---|
| API Reference | Complete API overview |
| Deployment Guide | Production setup |
| Architecture | System design |
| Quick Start | 5-minute setup |
| Contributing | Development guide |
- Fork the repository
- Create a feature branch
- Write tests for new functionality
- Ensure all tests pass:
make test - Submit a pull request
See CONTRIBUTING.md for detailed guidelines.
- Telegram: t.me/truerepublic
- Issues: github.com/NeaBouli/TrueRepublic/issues
- Email: p.cypher@protonmail.com
- NeaBouli
Team (BTC multi-sig): bc1qyamf3twgcqckuqrvmwgwnhzupgshxs37eejdgl0ntcqve98qnvhqe6cjl9