Pxtly (/pɪkstli/): Px (Price), Tx (Transaction), and Ledger. Compliant asset pricing and execution directly on-chain.

Pxtly is an institutional platform for tokenising Real World Assets on a permissioned Hyperledger Fabric network. It handles the full asset lifecycle from issuance to redemption, with built-in AML/KYC compliance, ZK-KYC identity proofs, FHE-based fraud scoring, and a RAG regulatory agent for MiCA queries.

• Features
• Requirements
• Quick Start
• CLI
• API Reference
• Environment Variables
• Project Structure
• Observability
• License

Pxtly runs a permissioned Hyperledger Fabric network with two organizations (BANK01 and REG01) and CouchDB state databases, synchronized with an application PostgreSQL database for a dual-ledger source of truth. The Go contract is deployed as Chaincode-as-a-Service (CCaaS) and enforces a 2-of-2 endorsement policy. Real-world assets transition through a strict, immutable lifecycle (EN_EMISSION, ACTIF, GELE, REMBOURSE) with all ledger modifications monitored by a resilient gRPC block listener.

The platform embeds regulatory compliance directly into the ledger lifecycle. Sanctions screening features Ed25519-signed manifests with fuzzy PEP matching, while the MiCA compliance engine automatically enforces transaction boundaries (Art. 68) and asset restrictions. Identity verification is handled cryptographically via Zero-Knowledge Proofs (zk-KYC Schnorr proofs) to protect user privacy under GDPR, and confidential AML risk calculations are evaluated over encrypted indicators using Fully Homomorphic Encryption (FHE CKKS via HElib).

Enterprise-grade security is achieved by delegating identity management to Keycloak OIDC (authorization flow with PKCE) and storing Fabric signing keys in HashiCorp Vault (KV v2). To mitigate memory-dump attacks, private keys are cleared from RAM immediately after signature generation using low-level memory operations. Distributed transaction consistency between PostgreSQL and Fabric is guaranteed through the SAGA orchestration pattern, which triggers automated compensating actions on execution failures.

Platform monitoring and auditing are decentralized. A dedicated Tribunal resolves transaction disputes through a three-phase Commit-Reveal voting protocol, applying game-theoretic slashing to penalize dishonest auditors. Real-time updates are streamed to clients via Server-Sent Events (SSE) backed by Redis Pub/Sub, and an automated Celery pipeline compiles certified PDF audit reports and feeds a regulatory RAG agent powered by ChromaDB and Groq.

API

Technology Stack

Step 1: Clone and configure

git clone https://github.com/zak-li/pxtly.git
cd pxtly
cp .env.example .env

Open .env and fill in at minimum DATABASE_URL, REDIS_URL, the FABRIC_* variables, and all KEYCLOAK_* variables.

Step 2: Install dependencies

python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Step 3: Start the Fabric network

cd fabric
# generate crypto material + genesis block, then bring containers up
docker run --rm -v "$PWD:/work" -w /work -e FABRIC_CFG_PATH=/work/config \
    hyperledger/fabric-tools:2.5.4 \
    cryptogen generate --config=config/crypto_config.yaml --output=crypto-config
docker run --rm -v "$PWD:/work" -w /work -e FABRIC_CFG_PATH=/work/config \
    hyperledger/fabric-tools:2.5.4 \
    configtxgen -profile RWAGenesis -outputBlock config/rwa-channel.pb -channelID rwa-channel
docker compose -f docker/docker-compose.yaml up -d
./scripts/deploy-chaincode.sh

Step 4: Deploy Keycloak

cd stack/keycloak
cp .env.keycloak.example .env.keycloak    # fill in admin/DB credentials
bash deploy.sh

The setup-realm.py script prints a KEYCLOAK_CLIENT_SECRET. Copy it into your .env.

Step 5: Start the API and worker

docker compose up -d    # API + Celery worker
# Or without Docker:
uvicorn core.main:app --host 0.0.0.0 --port 8000 --workers 1
celery -A core.core.celery_app worker --loglevel=info -Q celery,compliance,reports,fabric_events

The API is live at http://localhost:8000. Swagger UI at /docs.

Step 6: Authenticate

Authentication uses Keycloak OIDC with PKCE. Open in a browser:

http://localhost:8000/api/v1/auth/login

This redirects to Keycloak's login page. After authentication, the callback sets httpOnly session cookies and returns an access token.

# Use the access token for API calls:
curl -H "Authorization: Bearer <token>" http://localhost:8000/api/v1/assets

Pxtly ships a Python CLI under cli/ that mirrors every REST endpoint. It uses OAuth 2.0 Authorization Code + PKCE by default, stores tokens in the OS keyring, and writes a redacted audit line to ~/.pxtly/audit.log for every command.

pip install -r cli/requirements.txt
python -m cli.main --help                      # 12 sub-apps
python -m cli.main auth login                  # PKCE flow (browser)
python -m cli.main assets list --status ACTIF
python -m cli.main events stream               # live SSE tail
python -m cli.main dashboard                   # full-screen Textual TUI

Configuration precedence: PXTLY_* env vars, then ~/.pxtly/config.json, then defaults. Sub-apps: auth, assets, tx, audit, compliance, zkp, tribunal, orgs, agent, events, system, dashboard.

REST root: /api/v1. Every endpoint requires a valid OIDC access token unless marked public.

Authentication (OIDC / PKCE)

Assets

Compliance, KYC, ZKP

Audit, Transactions, Events, Tribunal

Agent and Organisations

Required

Optional

The full list lives in .env.example.

The repository is organised by responsibility: application code, the Fabric consortium, side services, persistence, and tooling each live under their own top-level directory.

core/                         # FastAPI + Celery, application backend
├── main.py                   # ASGI entry, middleware, metrics
├── config.py                 # pydantic-settings root
├── features/
│   ├── assets/               # Asset lifecycle (issue, transfer, freeze)
│   ├── compliance/           # AML / KYC / MiCA rules
│   ├── audit/                # On-chain trail, integrity, PDF reports
│   ├── auth/                 # Keycloak OIDC + PKCE + GDPR
│   ├── zkp/                  # ZK-KYC Schnorr proofs
│   ├── fhe/                  # HElib CKKS fraud scorer
│   └── agent/                # RAG pipeline + ChromaDB
├── fabric_client/            # Wallet, events, retry, circuit breaker
├── grpc_server/              # gRPC servicers
└── grpc_generated/           # protoc-generated stubs

chaincode/                    # Go smart contract (rwa-token, CCaaS)

cli/                          # Pxtly CLI (Typer + Rich + Textual)
├── api/                      # One client per REST resource
├── commands/                 # One Typer sub-app per domain
├── http/                     # Transport + auto-refresh on 401
├── security/                 # Keyring tokens, PKCE, audit log
└── ui/                       # Rich console, REPL, dashboard

fabric/                       # Hyperledger Fabric 2.5 network
├── config/                   # configtx, connection profile, MSP material
├── docker/                   # Peers, orderer, CouchDB compose
└── scripts/                  # deploy-chaincode.sh

stack/                        # Side services (run alongside the API)
├── keycloak/                 # Compose, TLS, identity-first flow
├── monitoring/               # Prometheus, Grafana, Loki, Promtail
└── vault/                    # Policy + hcl config

db/                           # Schema, seeds, Alembic migrations
├── migrations/               # alembic env + versions/
├── sql/                      # 01_schema to 08_zkp_tables
└── fixtures/                 # csv/, json/ (sanctions manifest)

proto/                        # gRPC service definitions (.proto)

scripts/                      # Operational scripts (Python + bash)
├── benchmarks/               # fhe.py, zkp.py
├── simulations/              # dashboard.py, full.py, jitter.py, game_theory.py
├── seed_db.py                # Apply SQL seeds + compliance fixtures
├── health_check.py           # Liveness probe for CI / oncall
├── generate_report.py        # Build a sample audit PDF locally
├── generate_protos.sh        # Regenerate Python gRPC stubs
└── install_latex.sh          # Install LaTeX deps (TeX Live)

tests/                        # pytest suite + fixtures

.github/ (assets + CI), .env.example, Dockerfile, docker-compose.yml, requirements.txt, pyproject.toml, alembic.ini, plus the metadata files (README.md, CHANGELOG.md, CONTRIBUTING.md, SECURITY.md, LICENSE).

Pxtly ships a full monitoring stack deployed via Docker Compose. Prometheus scrapes twelve targets: the API itself, Fabric peers (BANK01 + REG01), CouchDB for each peer, Keycloak, Vault, Redis, PostgreSQL, node-exporter, the Celery exporter, and Prometheus itself. Grafana renders one curated dashboard covering service health, API throughput / latency percentiles, infrastructure utilisation, datastores, blockchain activity, and compliance metrics. Loki aggregates structured JSON logs from the API container, Celery worker, Fabric peers, and the host's systemd journal.

The dashboard is auto-provisioned from stack/monitoring/grafana_dashboard.json via the file provider in stack/monitoring/grafana-provisioning/. Datasource UIDs are pinned (ffgx1hbr25a0wc for Prometheus, loki for Loki) so the dashboard JSON is portable across deployments.

Custom metrics exposed at /metrics:

This project is licensed under the Apache License 2.0. Vulnerability reports: see SECURITY.md. Contributions: see CONTRIBUTING.md.