TrueRepublic

A Cosmos SDK blockchain with Zero-Knowledge Proof anonymity, CosmWasm smart contracts, and Multi-Asset DEX

Features • Quick Start • Documentation • Roadmap

Warning

Recovery audit active: v0.4.0 functionality exists, but production-readiness claims are being re-verified in GitHub issue #4. client-web is the maintained web client. web-wallet and mobile-wallet are legacy clients with unresolved high/critical dependency advisories and must not be used for real keys or production funds.

What is TrueRepublic?

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.

📚 Documentation

📖 Complete Wiki

For Developers:

For Users:

For Node Operators:

For Security:

Additional Docs

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

Quick Start

# 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: Maintained v0.4 web client
cd client-web && npm ci && npm run dev

See INSTALLATION.md for detailed instructions.

Key Features

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 (stacked recovery)	PR #18 adds custody/LP ownership/burns; PR #19 reconciles genesis and checks reserves/shares every block	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

Web Client (v0.4.0)

React-based web client with full governance and DEX functionality:

cd client-web
npm ci
npm run dev

Wallet: Create/import, encrypted storage, send PNYX
Governance: Browse domains and create suggestions; anonymous submission remains disabled until a real prover exists
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.

Repository Structure

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, 484 test cases)
│   └── dex/                    DEX module (7 msg types, 116 test cases)
├── treasury/keeper/            Tokenomics equations 1-5 (36 test cases)
├── 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, configuration, and operations
│   ├── 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)

Implemented Features

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)	🟡 Recovery verified on PR #19	Atomic custody/burns plus exact genesis and every-block reserve/LP invariants
Multi-Asset DEX (BTC/ETH/LUSD)	🟡 Recovery verified on PR #19	Provider LP ownership and chain-authorized registry; recovery implementation merged to `main`
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)	🟡 Recovery verified on PR #22	Chain/rating binding and fail-closed VK; real client prover and external review pending
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)
Maintained Web Client	🟡 Recovery verified	`client-web/`
Legacy Web Wallet	🔴 Deprecated / vulnerable dependencies	`web-wallet/`
Legacy Mobile Wallet	🔴 Deprecated / vulnerable dependencies	`mobile-wallet/`
CI/CD Workflows	✅	`.github/workflows/`

Build & Test

# Blockchain
go mod tidy
./scripts/go-packages.sh go build
./scripts/go-packages.sh go test -race -cover -count=1 -timeout=600s    # 1,316 Go cases

# Smart contracts
cd contracts && cargo test --workspace       # 26 tests

# Maintained web client
cd client-web && npm ci && npm run lint && npm test -- --run && npm run build

Tech Stack

Component	Version	Status
Cosmos SDK	v0.50.14	Production
CometBFT	v0.38.22	Recovery verified
CosmWasm	v0.53.3	Production
ibc-go	v8.7.0	Transfer Active
gnark (ZKP)	v0.14.0	On-chain recovery verified; client disabled
Go	1.26.5	Recovery verified
Rust	1.75+	Contracts
React	18.2	Maintained v0.4 client
React Native + Expo	0.74 / 51.0	Legacy; security migration required
Keplr + CosmJS	0.39	Maintained v0.4 client

Known Limitations: IBC staking/upgrade remains stubbed (PoD is used instead), a real ZKP prover/ceremony review is pending, and the migration-focused harness proves compatible binary replacement and fail-before-open rollback—not consensus-breaking state migration. GH-93 provides a strict synthetic incident-command and rehearsal contract, but a private live operator rehearsal remains pending. GH-85 provides dashboard/application runtime evidence, alert rules, recovery/testnet objectives, and role ownership. GH-89 adds a strict synthetic topology qualification contract. GH-97 adds bounded four-validator load, resource, retention, restart, and ledger evidence; it does not establish production sizing or multi-day soak behavior. GH-101 adds a digest-bound offline deployment-evidence envelope and verifier; it does not prove or perform a live deployment. Real seed/sentry/validator/RPC deployment, firewall/TLS/DNS evidence, external paging drills, private-environment capacity evidence, and independent live operations review remain open. See LIMITATIONS.md.

Current Status

Version: v0.4.0 — recovery audit active; not production-ready

The checklist below records implemented surface area, not a production security approval. Current evidence, risks, and commands are maintained in BRIDGE.md and GitHub issue #4.

🟡 1,388 tests recovery-verified locally and in CI (1,316 Go + 26 Rust + 46 maintained-client), plus separately gated GH-56 rotation, GH-59 slashing, GH-60 inactive-validator genesis, GH-61 legacy-authority migration, GH-93 incident rehearsal, and GH-97 sustained-load process harnesses
✅ Core blockchain compiles and runs
🟡 Tokenomics, exact custom genesis, and every-block ledger invariants are recovery-verified and merged through PR #19
🟡 Governance escrow/auth recovery is verified and merged; independent release review remains open
🟡 Groth16 voting backend tested; reward-recipient binding and real web proof generation remain open
✅ CosmWasm smart contract integration (wasmd v0.53.3)
🟡 Domain-Bank escrow recovery implemented and merged via PR #16
✅ IBC Transfer module (ibc-go v8.4.0, cross-chain PNYX transfers)
🟡 Multi-Asset DEX bank custody, provider LP ownership, authority checks, and canonical burns are recovery-verified and merged via PR #18
🟡 GH-12 genesis/runtime conservation is recovery-verified and merged via PR #19
🟡 PR #23 provides generated CometBFT-key, bank-backed PoD genesis and proves native restart/export; GH-26 makes scripts/init-node.sh delegate only to that supported path. GH-32/GH-41/GH-43/GH-45/GH-53 add four-validator failure/restart/catch-up, partition, state-sync, and sanitized backup/restore gates plus compatible binary upgrade/fail-before-open rollback evidence; consensus-breaking migrations and broader multi-node operations remain open
🟡 ZKP UI is a clearly disabled preview until a compatible real Groth16 prover exists
✅ Developer Tooling: 4 CosmWasm example contracts, shared bindings, testing utils
🟡 DEX burns reduce canonical bank supply via merged PR #18
✅ Canonical v0.4 web client with 3-column governance UI
🔴 Legacy mobile wallet is deprecated and security-blocked
✅ Comprehensive documentation (30+ guides)

Roadmap

✅ 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): historical feature surface implemented; recovery verification incomplete
- ✅ 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 (recovery audit active since July 2026): Web Client
- ✅ Wallet Foundation (create/import/encrypt/send)
- ✅ Governance UI (domains, issues, suggestions, stones)
- ✅ DEX Interface (swap, liquidity, LP positions)
- 🟡 ZKP Anonymous Voting (on-chain binding verified; mock submission disabled; real prover pending)
- ✅ 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

Historical test count: 577. The authoritative recovery-verified total is 1,388 (1,316 Go + 26 Rust + 46 maintained-client), reproduced from package-scoped JSON output on merged GH-101 and GH-102 router evidence using the established passing-case method.

Developer Documentation

Guide	Description
API Reference	Complete API overview
Deployment Guide	Production setup
Architecture	System design
Quick Start	5-minute setup
Contributing	Development guide

Contributing

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.

Community

Telegram: t.me/truerepublic
Issues: github.com/NeaBouli/TrueRepublic/issues
Email: p.cypher@protonmail.com

Contributors

NeaBouli

Donations

Team (BTC multi-sig): bc1qyamf3twgcqckuqrvmwgwnhzupgshxs37eejdgl0ntcqve98qnvhqe6cjl9

Developer support (BTC): bc1p2kh7reqf7l5zmssk8kdx2fx0q6suzfmsgdrphl9wjsxarns56jkq4tqvjm

Name		Name	Last commit message	Last commit date
Latest commit History 248 Commits
.codex		.codex
.github		.github
assets		assets
capacitypolicy		capacitypolicy
client-web		client-web
configs		configs
contracts		contracts
deploymentevidence		deploymentevidence
docs		docs
healthcheck		healthcheck
incidentpolicy		incidentpolicy
migration		migration
mobile-wallet		mobile-wallet
monitoring		monitoring
networkpolicy		networkpolicy
nginx		nginx
observability		observability
scripts		scripts
token		token
topologypolicy		topologypolicy
treasury/keeper		treasury/keeper
ui		ui
web-wallet		web-wallet
wiki		wiki
x		x
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
BRIDGE.md		BRIDGE.md
CLAUDE.md		CLAUDE.md
CODEX_AUDIT.md		CODEX_AUDIT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
INSTALLATION.md		INSTALLATION.md
Makefile		Makefile
README.md		README.md
RELEASE_NOTES_v0.3.0.md		RELEASE_NOTES_v0.3.0.md
SECURITY.md		SECURITY.md
TrueRepublic_CI_CD_Security.pdf		TrueRepublic_CI_CD_Security.pdf
app.go		app.go
app_metrics_test.go		app_metrics_test.go
capacity_policy_repository_test.go		capacity_policy_repository_test.go
capacity_sustained_load_harness_test.go		capacity_sustained_load_harness_test.go
deployment_evidence_repository_test.go		deployment_evidence_repository_test.go
docker-compose.yml		docker-compose.yml
genesis.go		genesis.go
genesis_integration_test.go		genesis_integration_test.go
go.mod		go.mod
go.sum		go.sum
ibc_stubs.go		ibc_stubs.go
ibc_test.go		ibc_test.go
incident_policy_repository_test.go		incident_policy_repository_test.go
init_node_script_test.go		init_node_script_test.go
legacy_authority_migration_harness_test.go		legacy_authority_migration_harness_test.go
migration_command.go		migration_command.go
migration_command_test.go		migration_command_test.go
multi_validator_harness_test.go		multi_validator_harness_test.go
network_policy_repository_test.go		network_policy_repository_test.go
observability_repository_test.go		observability_repository_test.go
server_lifecycle.go		server_lifecycle.go
server_lifecycle_test.go		server_lifecycle_test.go
start_node_script_test.go		start_node_script_test.go
upgrade_rollback_harness_test.go		upgrade_rollback_harness_test.go
validator_identity_recovery_harness_test.go		validator_identity_recovery_harness_test.go
validator_key_rotation_harness_test.go		validator_key_rotation_harness_test.go
validator_slashing_harness_test.go		validator_slashing_harness_test.go
wasm_stubs.go		wasm_stubs.go

Navigation Menu

Repository files navigation

TrueRepublic

What is TrueRepublic?

📚 Documentation

📖 Complete Wiki

Additional Docs

Quick Start

Key Features

Web Client (v0.4.0)

Repository Structure

Implemented Features

Build & Test

Tech Stack

Current Status

Roadmap

Developer Documentation

Contributing

Community

Contributors

Donations

About

Releases

Packages

Used by

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

TrueRepublic

What is TrueRepublic?

📚 Documentation

📖 Complete Wiki

Additional Docs

Quick Start

Key Features

Web Client (v0.4.0)

Repository Structure

Implemented Features

Build & Test

Tech Stack

Current Status

Roadmap

Developer Documentation

Contributing

Community

Contributors

Donations

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages