TAO Passport

A portable identity and reputation layer for Bittensor wallets.

TAO Passport turns a raw TAO wallet address into a readable public profile: validator and miner history, subnet participation, governance activity, achievements, reputation signals, and a timeline of meaningful ecosystem activity.

It is built for the Bittensor ecosystem, where wallet identity alone is not enough to understand trust, role, or long-term participation.

---

What This Is

TAO Passport is an initial full-stack scaffold for a Bittensor wallet reputation product.

Surface	Purpose
Wallet passport	A public profile for a TAO wallet with level, score, summary, and activity history.
Reputation engine	Weighted signals from validator/miner activity, subnet participation, governance and community behavior.
Achievement system	Badges for durable ecosystem participation such as validating, mining, voting, delegating, and contributing to the community.
Timeline	Chronological wallet activity across chain, subnet, governance, and community events.
Leaderboard	Discovery surface for high-signal Bittensor ecosystem participants.

What This Is Not

• It is not a wallet custody app.
• It is not a financial risk score.
• It is not a guarantee that a wallet owner is trustworthy.
• It is not yet connected to production Bittensor indexers.

The current implementation is a realistic product scaffold with demo data, API boundaries, shared types, database schema, and UI flows ready for live integrations.

---

Why TAO Passport

Bittensor activity is spread across wallets, validators, miners, subnets, governance, and community channels. That makes it difficult to answer practical questions:

• Has this wallet participated consistently over time?
• Is this address connected to validator, miner, or delegate activity?
• Which subnets does this participant contribute to?
• What signals explain the reputation score?
• Which achievements or timeline events support the profile?

TAO Passport gives each wallet a portable identity surface so users can inspect reputation instead of guessing from an address.

---

Product Preview

The frontend currently includes:

• Landing page for the Bittensor reputation layer.
• Sample passport profile.
• Achievement grid.
• Trust score breakdown.
• Activity timeline.
• Leaderboard and search surfaces.

Core UI files live under frontend/src/pages and frontend/src/components.

---

Repository Structure

tao-passport/
├── backend/                 # Express API, services, blockchain adapters
├── database/                # PostgreSQL schema, migration, seed data
├── docs/                    # Architecture,scoring, achievements
├── frontend/                # React + Vite passport application
├── packages/
│   ├── shared-types/        # Passport, reputation, achievement contracts
│   └── shared-utils/        # Shared formatting and scoring helpers
├── scripts/                 # Data and maintenance scripts
├── docker-compose.yml       # Local PostgreSQL service
└── package.json             # npm workspace root

---

Quick Start

Requirements:

• Node.js 20+
• npm 10+
• Docker, if running PostgreSQL locally

git clone https://github.com/RenzoMXD/tao-passport.git
cd tao-passport
cp .env.example .env
npm install
npm run dev

Default local services:

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:4000
Health check	http://localhost:4000/health
Interactive API docs (Swagger UI)	http://localhost:4000/api-docs
OpenAPI spec (JSON)	http://localhost:4000/api-docs/openapi.json

Start PostgreSQL when database-backed development is needed:

docker compose up -d postgres

---

Environment Variables

Variable	Purpose	Default
DATABASE_URL	PostgreSQL connection string	postgres://tao_passport:tao_passport@localhost:5432/tao_passport
PORT	Backend API port	4000
CORS_ORIGIN	Allowed frontend origin	http://localhost:5173
VITE_API_URL	Frontend API base URL	http://localhost:4000
BITTENSOR_NETWORK	Target Bittensor network	finney

Copy .env.example before running locally:

cp .env.example .env

---

Development Commands

# Run frontend and backend together
npm run dev

# Build all workspaces
npm run build

# Run lint checks
npm run lint

# Run type checks
npm run typecheck

# Run tests where configured
npm run test

Workspace-specific commands:

npm run dev --workspace frontend
npm run dev --workspace backend
npm run build --workspace frontend
npm run build --workspace backend

---

API Surface

Method	Route	Purpose
GET	/health	API health check.
GET	/api/passport/sample	Returns the demo passport profile.
GET	/api/passport/:walletAddress	Looks up a wallet passport by Substrate-style address.
GET	/api/achievements	Lists available achievement definitions.
GET	/api/reputation/signals	Returns reputation signal metadata.
GET	/api/reputation/leaderboard	Returns ranked reputation profiles.
GET	/api-docs	Interactive Swagger UI for the full API.
GET	/api-docs/openapi.json	Machine-readable OpenAPI 3.0 spec.

Example:

curl http://localhost:4000/api/passport/sample

Interactive API Documentation

The full API is described by an OpenAPI 3.0 specification with request/response schemas, error codes, query parameters, and examples for every endpoint. When the backend is running, browse the interactive docs at http://localhost:4000/api-docs or fetch the raw spec from http://localhost:4000/api-docs/openapi.json.

The JSON spec can be imported directly into Postman, Insomnia, or an OpenAPI code generator to scaffold a typed client:

# Save the spec while the backend is running
curl http://localhost:4000/api-docs/openapi.json -o openapi.json

---

Reputation Model

TAO Passport is designed around explainable reputation. A score should be traceable to specific signals instead of appearing as a black box.

Signal Group	Example Inputs	Why It Matters
Validator reliability	uptime, consistency, subnet performance	Shows operational trust and long-term network contribution.
Miner participation	mining history, subnet role, recent activity	Captures durable work across Bittensor subnets.
Governance activity	proposal voting, participation frequency	Identifies protocol-level engagement.
Subnet participation	subnet breadth, role mix, activity recency	Rewards sustained participation across Bittensor subnet economies.
Community signal	durable non-code contribution, ecosystem support	Adds context outside pure chain metrics.

See docs/reputation-system.md for the starter scoring principles.

---

Architecture

The project uses a TypeScript monorepo with isolated boundaries:

1. The user opens or searches a Bittensor wallet address.
2. The backend resolves passport data through repository and service layers.
3. Blockchain adapters provide a replaceable boundary for live Bittensor queries.
4. Reputation and achievement services transform raw signals into profile data.
5. The frontend renders the passport card, achievements, trust breakdown, timeline, and leaderboard.

Read more in docs/architecture.md.

---

Security and Privacy Notes

• TAO Passport should never require wallet custody or private keys.
• Public profiles should explain signal sources and freshness.
• Reputation scores should be transparent, versioned, and auditable.
• Public endpoints should use validation, rate limits, and cache controls before production use.

---

Docs

• API Reference (OpenAPI 3.0)
• Architecture
• Reputation System
• Achievements
• Contributing

---

🙌 Contributing

TAO passport will flourish via open-source collaboration. In this spirit, we embrace diverse contributions from the community. If you would like to be a part, review our Contribution Guidelines first.

Contributing

---

MIT — see LICENSE.