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, contributions, 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, contribution quality, or long-term participation.
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, GitTensor, and community behavior. |
| Achievement system | Badges for durable ecosystem participation such as validating, mining, voting, building, and contributing. |
| Timeline | Chronological wallet activity across chain, subnet, contribution, and community events. |
| Leaderboard | Discovery surface for high-signal Bittensor ecosystem participants. |
- 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.
Bittensor activity is spread across wallets, validators, miners, subnets, governance, GitHub/GitTensor contributions, 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 builder 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.
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.
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
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 devDefault local services:
| Service | URL |
|---|---|
| Frontend | http://localhost:5173 |
| Backend API | http://localhost:4000 |
| Health check | http://localhost:4000/health |
Start PostgreSQL when database-backed development is needed:
docker compose up -d postgres| 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# 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 testWorkspace-specific commands:
npm run dev --workspace frontend
npm run dev --workspace backend
npm run build --workspace frontend
npm run build --workspace backend| 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. |
Example:
curl http://localhost:4000/api/passport/sampleTAO 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. |
| GitTensor contribution | merged PRs, reviews, issue work, recency | Rewards builder activity and open-source contribution. |
| Community signal | durable non-code contribution, ecosystem support | Adds context outside pure chain metrics. |
See docs/reputation-system.md for the starter scoring principles.
The project uses a TypeScript monorepo with isolated boundaries:
- The user opens or searches a Bittensor wallet address.
- The backend resolves passport data through repository and service layers.
- Blockchain adapters provide a replaceable boundary for live Bittensor queries.
- Reputation and achievement services transform raw signals into profile data.
- The frontend renders the passport card, achievements, trust breakdown, timeline, and leaderboard.
Read more in docs/architecture.md.
- TAO Passport should never require wallet custody or private keys.
- Public profiles should explain signal sources and freshness.
- GitHub or GitTensor integrations should avoid exposing private contribution context.
- Reputation scores should be transparent, versioned, and auditable.
- Public endpoints should use validation, rate limits, and cache controls before production use.
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.
MIT — see LICENSE.