StayChain ID

Decentralized Hospitality Identity & Reputation Protocol

StayChain ID is an open-source decentralized identity and reputation protocol built for the hospitality and tourism industry. Powered by Stellar and Soroban smart contracts, it lets guests own a portable identity — credentials, loyalty memberships, and reputation scores — that works across any participating hotel or booking platform.

Overview

The hospitality industry suffers from fragmented identity systems — hotels repeatedly collect the same guest data, loyalty programs are siloed, and guest reputations don't travel with them. StayChain ID fixes this by giving every guest a self-sovereign Decentralized Identifier (DID) anchored on Stellar, with verifiable credentials issued by hotels and a portable reputation score.

Guests get:

A self-sovereign DID registered on Stellar
Verifiable stay, loyalty, and identity credentials stored in their wallet
A reputation score that follows them across all partner hotels

Hotels get:

One-click guest credential verification
Fraud signal visibility across the network
Swagger-documented APIs to integrate in minutes

Repository Structure

staychain-id/
├── apps/
│   ├── guest-wallet/        # Next.js 15 — guest identity wallet (port 3000)
│   ├── hotel-dashboard/     # Next.js 15 — hotel verification dashboard (port 3001)
│   └── admin-console/       # Next.js 15 — protocol admin & governance (port 3002)
│
├── services/
│   ├── identity-service/    # NestJS — DID registration & resolution (port 4001)
│   ├── credential-service/  # NestJS — VC issuance & verification (port 4002)
│   └── reputation-service/  # NestJS — reputation scoring & history (port 4003)
│
├── packages/
│   ├── sdk-typescript/      # TypeScript SDK (@staychain/sdk-typescript)
│   ├── sdk-rust/            # Rust SDK (staychain-sdk)
│   └── ui-components/       # Shared React component library (@staychain/ui-components)
│
├── contracts/
│   ├── did-registry/        # Soroban — anchors DID hashes on-chain
│   └── reputation-registry/ # Soroban — tamper-proof reputation scores
│
├── docs/
│   ├── architecture/        # System design & data flow
│   ├── api/                 # API reference
│   └── whitepaper/          # Protocol whitepaper
│
└── infrastructure/
    ├── docker/              # docker-compose for local full-stack
    ├── kubernetes/          # K8s manifests
    └── terraform/           # AWS infrastructure (EKS, RDS, VPC)

Tech Stack

Layer	Technology
Frontend	Next.js 15, React 19, Tailwind CSS, Shadcn UI
Backend	NestJS, TypeORM, PostgreSQL 16, Redis 7, Kafka
Blockchain	Stellar SDK, Soroban Smart Contracts (soroban-sdk 21)
Identity	W3C DID, Verifiable Credentials (W3C VC Data Model)
SDK	TypeScript (axios), Rust (reqwest + serde)
Build	pnpm workspaces, Turborepo
Infrastructure	Docker, Kubernetes, Terraform (AWS EKS + RDS), GitHub Actions

Prerequisites

Tool	Version
Node.js	>= 20
pnpm	>= 9
Rust	stable (with `wasm32-unknown-unknown` target)
Docker + Docker Compose	latest stable
Stellar CLI (`stellar`)	>= 21 (for contract deployment)

# Install Rust wasm target
rustup target add wasm32-unknown-unknown

# Install Stellar CLI
cargo install --locked stellar-cli --features opt

Getting Started

1. Clone and install

git clone https://github.com/your-org/staychain-id.git
cd staychain-id
pnpm install

2. Configure environment

# Copy root env template
cp .env.example .env

# Copy per-service env templates
cp services/identity-service/.env.example   services/identity-service/.env
cp services/credential-service/.env.example services/credential-service/.env
cp services/reputation-service/.env.example services/reputation-service/.env

3. Start infrastructure (databases, Redis, Kafka)

docker compose -f infrastructure/docker/docker-compose.yml up -d \
  postgres-identity postgres-credential postgres-reputation redis zookeeper kafka

4. Run the full stack in development

pnpm dev

This starts all three NestJS services and all Next.js apps concurrently via Turborepo.

App / Service	URL
Guest Wallet	http://localhost:3000
Hotel Dashboard	http://localhost:3001
Admin Console	http://localhost:3002
Identity Service	http://localhost:4001
Credential Service	http://localhost:4002
Reputation Service	http://localhost:4003

5. Run via Docker Compose (full stack)

docker compose -f infrastructure/docker/docker-compose.yml up --build

Running Services

Build

pnpm build          # build everything
pnpm build --filter @staychain/identity-service   # single package

Test

pnpm test           # all packages
cargo test          # Soroban contracts (run inside contracts/did-registry etc.)

Lint

pnpm lint

Swagger API Docs

Each NestJS service exposes interactive Swagger docs at /api/docs:

Identity Service: http://localhost:4001/api/docs
Credential Service: http://localhost:4002/api/docs
Reputation Service: http://localhost:4003/api/docs

API Reference

Identity Service — `http://localhost:4001`

Method	Endpoint	Description
`POST`	`/api/identity/create`	Register a new DID
`GET`	`/api/identity/:did`	Resolve a DID document
`GET`	`/api/identity/address/:address`	Find DIDs by Stellar address
`DELETE`	`/api/identity/:did`	Deactivate a DID

Credential Service — `http://localhost:4002`

Method	Endpoint	Description
`POST`	`/api/credential/issue`	Issue a verifiable credential
`POST`	`/api/credential/verify`	Verify a credential
`GET`	`/api/credential/subject/:did`	List credentials for a subject DID
`DELETE`	`/api/credential/:id/revoke`	Revoke a credential

Credential types: stay · identity · loyalty · review

Reputation Service — `http://localhost:4003`

Method	Endpoint	Description
`GET`	`/api/reputation/:did`	Get reputation score (0–100)
`POST`	`/api/reputation/update`	Submit a reputation event
`GET`	`/api/reputation/:did/history`	Get score event history (last 50)

Event types: stay_completed · review_authentic · fraud_flag · loyalty_bonus · manual_adjustment

Quick examples

# Register a DID
curl -X POST http://localhost:4001/api/identity/create \
  -H "Content-Type: application/json" \
  -d '{"stellarAddress":"GABC...XYZ","document":{"@context":["https://www.w3.org/ns/did/v1"],"id":"did:stellar:GABC...XYZ"}}'

# Issue a stay credential
curl -X POST http://localhost:4002/api/credential/issue \
  -H "Content-Type: application/json" \
  -d '{"subjectDid":"did:stellar:GABC...guest","issuerDid":"did:stellar:GDEF...hotel","type":"stay","claims":{"hotelName":"Grand Plaza","checkIn":"2026-07-08","checkOut":"2026-07-10"}}'

# Get reputation score
curl http://localhost:4003/api/reputation/did:stellar:GABC...guest

Soroban Contracts

Both contracts are written in no_std Rust using soroban-sdk 21.

DID Registry (`contracts/did-registry`)

Anchors DID document hashes on-chain.

Function	Description
`initialize(admin)`	One-time setup
`register_did(user, hash)`	Register a DID hash (requires user auth)
`update_did(user, hash)`	Update the DID document hash
`deactivate_did(user)`	Deactivate a DID
`is_active(user) → bool`	Check if a DID is active
`get_did_hash(user) → BytesN<32>`	Retrieve the stored hash

Reputation Registry (`contracts/reputation-registry`)

Maintains tamper-proof reputation scores (stored as integers scaled ×100, e.g. 9400 = score 94.00).

Function	Description
`initialize(admin)`	One-time setup
`get_score(user) → i64`	Returns score (default `5000` = 50.00)
`update_score(issuer, user, delta)`	Adjust score, clamped to 0–10000
`reset_score(admin, user, score)`	Admin override (dispute resolution)

Build & deploy contracts

# Build WASM
cd contracts/did-registry
cargo build --target wasm32-unknown-unknown --release

# Deploy to testnet
stellar contract deploy \
  --wasm target/wasm32-unknown-unknown/release/did_registry.wasm \
  --network testnet \
  --source <YOUR_SECRET_KEY>

After deploying, add the contract IDs to your .env files:

DID_REGISTRY_CONTRACT_ID=C...
REPUTATION_REGISTRY_CONTRACT_ID=C...

Environment Variables

Root `.env`

Variable	Description	Default
`STELLAR_NETWORK`	`testnet` or `mainnet`	`testnet`
`STELLAR_HORIZON_URL`	Horizon API URL	`https://horizon-testnet.stellar.org`
`SOROBAN_RPC_URL`	Soroban RPC URL	`https://soroban-testnet.stellar.org`
`DID_REGISTRY_CONTRACT_ID`	Deployed DID registry contract ID	—
`REPUTATION_REGISTRY_CONTRACT_ID`	Deployed reputation registry contract ID	—

Per-service

Each service under services/*/ has its own .env.example with:

Variable	Description
`PORT`	Service port (4001 / 4002 / 4003)
`NODE_ENV`	`development` / `production` / `test`
`DB_HOST`	PostgreSQL host
`DB_PORT`	PostgreSQL port (default `5432`)
`DB_USER`	Database user
`DB_PASS`	Database password
`DB_NAME`	Database name

CI / CD

GitHub Actions runs on every push to main / develop and on all PRs:

Job	What it does
`lint`	Runs `pnpm lint` + `pnpm build` (type-check)
`test-services`	Runs NestJS unit tests against a live PostgreSQL container
`test-contracts`	Runs `cargo test` for both Soroban contracts
`docker`	Builds Docker images for all three services

Roadmap

Phase 1 (current)

Phase 2

Reputation scoring on-chain integration
Fraud detection pipeline (Kafka-based)
Loyalty credential support

Phase 3

Global partner onboarding
DAO governance module
Decentralized trust network

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
.vscode		.vscode
apps		apps
contracts		contracts
docs		docs
infrastructure		infrastructure
packages		packages
services		services
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
package.json		package.json
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
turbo.json		turbo.json

Navigation Menu

Repository files navigation

StayChain ID

Table of Contents

Overview

Repository Structure

Tech Stack

Prerequisites

Getting Started

1. Clone and install

2. Configure environment

3. Start infrastructure (databases, Redis, Kafka)

4. Run the full stack in development

5. Run via Docker Compose (full stack)

Running Services

Build

Test

Lint

Swagger API Docs

API Reference

Identity Service — `http://localhost:4001`

Credential Service — `http://localhost:4002`

Reputation Service — `http://localhost:4003`

Quick examples

Soroban Contracts

DID Registry (`contracts/did-registry`)

Reputation Registry (`contracts/reputation-registry`)

Build & deploy contracts

Environment Variables

Root `.env`

Per-service

CI / CD

Roadmap

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

StayChain ID

Table of Contents

Overview

Repository Structure

Tech Stack

Prerequisites

Getting Started

1. Clone and install

2. Configure environment

3. Start infrastructure (databases, Redis, Kafka)

4. Run the full stack in development

5. Run via Docker Compose (full stack)

Running Services

Build

Test

Lint

Swagger API Docs

API Reference

Identity Service — http://localhost:4001

Credential Service — http://localhost:4002

Reputation Service — http://localhost:4003

Quick examples

Soroban Contracts

DID Registry (contracts/did-registry)

Reputation Registry (contracts/reputation-registry)

Build & deploy contracts

Environment Variables

Root .env

Per-service

CI / CD

Roadmap

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Identity Service — `http://localhost:4001`

Credential Service — `http://localhost:4002`

Reputation Service — `http://localhost:4003`

DID Registry (`contracts/did-registry`)

Reputation Registry (`contracts/reputation-registry`)

Root `.env`