A decentralised register platform for secure, multi-participant data flow orchestration.
Sorcha lets organizations define structured workflows — called blueprints — where multiple parties exchange, validate, and record data with cryptographic guarantees. Every transaction is signed, every change is immutable, and every participant sees only what they're authorized to access.
| Capability | Description |
|---|---|
| Blueprint Workflows | Define multi-step, multi-party data flows as declarative JSON with conditional routing, schema validation, and business logic evaluation |
| Distributed Ledger | Immutable, append-only transaction registers with chain validation, Merkle-tree dockets, and DID URI addressing |
| Cryptographic Wallets | HD wallet management (BIP32/39/44) with ED25519, P-256, RSA-4096, and post-quantum algorithms (ML-DSA, ML-KEM, SLH-DSA) |
| Field-Level Encryption | Envelope encryption with per-recipient key wrapping — participants see only the fields they're authorized to access |
| Multi-Tenant Identity | JWT authentication with OAuth2 client credentials, participant identity registry, and wallet address linking |
| Peer Network | gRPC-based P2P topology for register replication across nodes |
| Real-Time Notifications | SignalR hubs for live action notifications, inbound transaction alerts, and workflow state changes |
| AI Integration | MCP Server for AI assistant interaction + AI-assisted blueprint design with unified chat / diagram / preview shell |
Sorcha implements DAD (Disclosure, Alteration, Destruction):
- Disclosure — Field-level encryption and selective disclosure via JSON Pointers ensure participants see only what they're authorized to access
- Alteration — Every data change is recorded as a cryptographically signed transaction on an immutable ledger
- Destruction — Peer network replication eliminates single-point-of-failure data loss
For the full quickstart (every prerequisite with version constraint, every common failure mode with documented fix, the verify-installation curl), see docs/quickstart.md. That document is agent-runnable end-to-end and is the canonical setup reference.
The short version:
- Docker Engine ≥ 24 (or Docker Desktop on macOS / Windows)
- Docker Compose v2 (the
docker composeplugin — v1 standalone is end-of-life and rejected by the setup script) - OpenSSL or Python 3 (for JWT key generation)
- Git
- PowerShell 7.5+ (optional — only needed for
walkthroughs/)
Ports 80, 443, and 8080 must be free.
git clone https://github.com/Sorcha-Platform/Sorcha.git
cd Sorcha
# Interactive setup — checks prerequisites, generates .env, pulls images, starts services
./scripts/sorcha-setup.sh
# Or manual setup:
cp .env.example .env # Edit with your settings
docker compose up -d # Start all servicesOn success the script prints [sorcha-setup] success — gateway reachable at http://localhost. Verify with curl -s http://localhost/api/health — every service should report Healthy.
| Service | URL | Description |
|---|---|---|
| Sorcha UI | http://localhost/app | Main application interface |
| Blueprint Designer | http://localhost/app/designer/blueprint | Unified designer — AI / Diagram / Preview tabs |
| API Gateway | http://localhost/ | REST API entry point |
| API Documentation | http://localhost/scalar/ | Interactive Scalar API docs |
| Health Check | http://localhost/api/health | Aggregated service health |
| Aspire Dashboard | http://localhost:18888 | Observability and telemetry |
After first run, the system creates a default organization and admin user:
| Field | Value |
|---|---|
admin@sorcha.local |
|
| Password | Dev_Pass_2025! |
Change these immediately in production. See Authentication Setup for production configuration.
Blueprints are JSON documents that describe multi-party workflows:
{
"title": "Invoice Approval",
"participants": [
{ "role": "submitter", "description": "Submits invoices" },
{ "role": "approver", "description": "Reviews and approves" }
],
"actions": [
{
"title": "Submit Invoice",
"assignedTo": "submitter",
"schema": { "type": "object", "properties": { "amount": { "type": "number" } } }
},
{
"title": "Review Invoice",
"assignedTo": "approver",
"routing": { "conditions": [{ "if": { ">": [{ "var": "amount" }, 1000] }, "then": "escalate" }] }
}
]
}See the blueprints/ directory for ready-to-use templates across finance, healthcare, supply chain, and government domains.
Blueprints are published to registers — distributed ledgers that record every transaction immutably. Each register has its own chain of cryptographically signed dockets.
Participants complete actions in sequence. The engine validates schemas, evaluates business logic, routes to the next participant, and records everything on the ledger.
Every transaction is signed, timestamped, and chained. The full history is available via the REST API or CLI tool.
The sorcha CLI provides administrative access to the platform:
# Authenticate
sorcha auth login
# Manage organizations
sorcha org list
sorcha org create --name "Acme Corp" --subdomain acme
# Wallet operations
sorcha wallet list
sorcha wallet create --name "Signing Key" --algorithm ED25519
# Register and transaction management
sorcha register list
sorcha tx submit --register-id reg-123 --payload '{"type":"invoice","amount":1500}'See the CLI documentation for the full command reference.
graph TD
UI["Sorcha UI<br/><small>Blazor WASM</small>"]
GW["API Gateway<br/><small>YARP Reverse Proxy</small>"]
BP["Blueprint Service<br/><small>Workflows + SignalR</small>"]
REG["Register Service<br/><small>Distributed Ledger</small>"]
TEN["Tenant Service<br/><small>Auth + Identity</small>"]
WAL["Wallet Service<br/><small>Crypto + Signing</small>"]
VAL["Validator Service<br/><small>Consensus + Dockets</small>"]
PEER["Peer Service<br/><small>gRPC Replication</small>"]
PG1[(PostgreSQL)]
PG2[(PostgreSQL)]
MONGO[(MongoDB)]
REDIS[(Redis)]
UI --> GW
GW --> BP
GW --> REG
GW --> TEN
BP --> WAL
REG --> VAL
VAL --> PEER
BP --- PG1
TEN --- PG2
WAL --- PG2
REG --- MONGO
VAL --- REDIS
BP -. SignalR .-> UI
| Service | Purpose |
|---|---|
| API Gateway | YARP reverse proxy — single entry point for all API traffic |
| Blueprint Service | Workflow management, execution engine, SignalR notifications |
| Register Service | Distributed ledger, transaction storage, OData queries |
| Wallet Service | Cryptographic key management, signing, encryption |
| Tenant Service | Multi-tenant auth, JWT issuer, participant identity |
| Validator Service | Transaction validation, consensus, docket building |
| Peer Service | P2P network topology, gRPC replication |
All configuration is managed through environment variables. See .env.example for a fully documented template with every variable explained.
Key settings:
| Variable | Purpose | Default |
|---|---|---|
JWT_SIGNING_KEY |
256-bit key for JWT tokens | Generated by setup script |
POSTGRES_USER / POSTGRES_PASSWORD |
PostgreSQL credentials | sorcha / sorcha_dev_password |
MONGO_USERNAME / MONGO_PASSWORD |
MongoDB credentials | sorcha / sorcha_dev_password |
ANTHROPIC_API_KEY |
AI blueprint design (optional) | Empty |
Sorcha publishes a machine-readable surface so AI agents, AI coding assistants, and integrators picking up the platform can find, parse, and reason over it without out-of-band documentation. The four published documents are the canonical agent-facing reference and live alongside the standards file and the well-known endpoints:
| Surface | Purpose |
|---|---|
llms.txt |
One-screen factual summary, llmstxt.org-conforming |
STANDARDS.md |
Single source of truth for every standard the platform implements |
docs/quickstart.md |
Agent-runnable setup against a clean Docker host |
docs/architecture.md |
Architectural overview — services, evidence flow, discovery surface |
docs/openid4vc-haip-integration.md |
Wallet ecosystem boundary (OpenID4VCI / OpenID4VP / HAIP 1.0) |
docs/applicability.md |
Regulatory-pull domains (DPP, trade finance, IPC-1782, municipal) |
docs/security-model.md |
Selective disclosure, post-quantum posture, honest gaps |
docs/mcp-server.md |
Connecting an AI agent via the Model Context Protocol |
docs/llms-full.txt |
Long-form machine-readable narrative |
GET /.well-known/openapi.json (running gateway) |
Aggregated OpenAPI 3.1 surface with info.x-mcp-server and info.x-standards |
GET /.well-known/openapi.yaml (running gateway) |
YAML form of the same document |
GET /.well-known/mcp.json (running gateway) |
MCP server manifest — transports, authentication, tool catalogue |
These surfaces are gated by the ai-discoverability-check CI workflow on every pull request to master.
| Document | Description |
|---|---|
| Docker Quick Start | Getting started with Docker |
| Authentication Setup | JWT and auth configuration |
| API Documentation | REST and gRPC endpoint reference |
| Blueprint Quick Start | Creating your first blueprint |
| Port Configuration | Service ports and networking |
| Architecture | System design and data flows |
| Deployment Guide | Production deployment |
| Troubleshooting | Common issues and solutions |
Interactive demos in the walkthroughs/ directory:
| Walkthrough | Description |
|---|---|
BlueprintStorageBasic/ |
Docker startup, bootstrap, JWT authentication |
PingPong/ |
Simple two-party workflow |
ConstructionPermit/ |
Multi-step approval process |
MedicalEquipmentRefurb/ |
Healthcare equipment workflow |
OrganizationPingPong/ |
Multi-organization data exchange |
RegisterCreationFlow/ |
Register lifecycle management |
See walkthroughs/README.md for the full list and setup instructions.
For building from source, running tests, project structure, coding conventions, and contributing — see DEVELOPMENT.md.
MIT License — see LICENSE for details.
Built with .NET 10 and .NET Aspire