Prerequisites
| Tool | Version | Purpose |
|---|
| Node.js | 20+ | Runtime |
| pnpm | 9+ | Package manager (monorepo workspaces) |
| Git | 2.40+ | Version control |
| Docker | 24+ | Optional: PostgreSQL + Redis for persistence |
Local Setup
Clone the Repository
git clone https://github.com/sint-ai/sint-protocol.git
cd sint-protocol
Install Dependencies
This installs dependencies for all 35 workspace projects (24 packages + 5 apps + 6 examples/tools). Build Everything
Uses Turborepo to build 34 tasks in parallel with dependency-aware ordering. Run Tests
Runs 1,363 tests across the entire monorepo. All tests should pass on a clean build. Start the Gateway Server
cd apps/gateway-server
pnpm dev
http://localhost:4100 by default.Turborepo caches build outputs. Subsequent builds only recompile changed packages. Use pnpm build --force to bypass the cache.
Monorepo Structure
sint-protocol/
├── packages/ # 24 publishable packages
│ ├── core/ # @sint/core — types, schemas, constants
│ ├── capability-tokens/ # @sint/gate-capability-tokens
│ ├── policy-gateway/ # @sint/gate-policy-gateway
│ ├── evidence-ledger/ # @sint/gate-evidence-ledger
│ ├── persistence/ # @sint/persistence
│ ├── persistence-postgres/ # @sint/persistence-postgres
│ ├── client/ # @sint/client (TypeScript SDK)
│ ├── bridge-ros2/ # @sint/bridge-ros2
│ ├── bridge-mcp/ # @sint/bridge-mcp
│ ├── bridge-grpc/ # @sint/bridge-grpc
│ ├── bridge-a2a/ # @sint/bridge-a2a
│ ├── bridge-economy/ # @sint/bridge-economy
│ ├── bridge-mqtt-sparkplug/
│ ├── bridge-opcua/
│ ├── bridge-iot/
│ ├── bridge-mavlink/
│ ├── bridge-open-rmf/
│ ├── bridge-swarm/
│ ├── engine-hal/ # Hardware abstraction layer
│ ├── engine-system1/ # Fast reactive subsystem
│ ├── engine-system2/ # Deliberative planning subsystem
│ ├── engine-capsule-sandbox/
│ ├── avatar/ # CSML escalation for avatars
│ └── conformance-tests/ # Compliance test suite
├── apps/
│ ├── gateway-server/ # Hono HTTP server
│ ├── dashboard/ # Admin dashboard (React)
│ ├── sintctl/ # CLI tool
│ ├── sint-mcp/ # MCP bridge server
│ └── sint-mcp-scanner/ # MCP discovery tool
├── sdks/
│ ├── python/ # Python SDK (1,962 lines)
│ └── go/ # Go SDK
├── examples/
│ └── notes-server/ # Example MCP server
├── docs/
│ └── whitepaper-v2.md # Technical whitepaper
├── turbo.json # Turborepo config
├── pnpm-workspace.yaml # Workspace definition
└── package.json # Root config + pnpm overrides
Running Specific Packages
Build a single package
pnpm --filter @sint/core build
Test a single package
pnpm --filter @sint/gate-capability-tokens test
cd packages/conformance-tests
pnpm test
- ROS2 control loop latency (P50/P95/P99 assertions)
- Token lifecycle validation
- Gateway policy evaluation
- Evidence ledger integrity
- Bridge protocol compliance
Environment Variables
Gateway Server
| Variable | Default | Description |
|---|
PORT | 4100 | HTTP server port |
SINT_API_KEY | (none) | Admin endpoint authentication. Required in production. |
SINT_STORE | memory | Evidence store: memory, postgres |
SINT_CACHE | memory | Token cache: memory, redis |
SINT_STRICT_BENCH | false | Enforce strict latency thresholds in conformance tests |
DATABASE_URL | (none) | PostgreSQL connection string (when SINT_STORE=postgres) |
REDIS_URL | (none) | Redis connection string (when SINT_CACHE=redis) |
Docker Development
# Start PostgreSQL + Redis for persistence testing
docker compose up -d
# Run gateway with persistent storage
SINT_STORE=postgres SINT_CACHE=redis pnpm dev
Testing
Test Hierarchy
| Suite | Package | Tests | Focus |
|---|
| Unit | @sint/gate-capability-tokens | Ed25519 crypto, delegation | Cryptographic correctness |
| Unit | @sint/gate-policy-gateway | Intercept pipeline | Policy enforcement |
| Unit | @sint/gate-evidence-ledger | Hash chain, proof receipts | Audit integrity |
| Unit | @sint/client | 12 tests | SDK API surface |
| Integration | conformance-tests | 114 tests | End-to-end protocol compliance |
| Performance | conformance-tests | ROS2 latency benchmark | P50 < 10ms, P95 < 15ms |
Running tests with coverage
SINT_STRICT_BENCH=true pnpm --filter @sint/conformance-tests test
CI/CD
The repository uses GitHub Actions for continuous integration:
- Build: Turborepo parallel build of all 34 tasks
- Test: Full test suite (1,363 tests)
- Audit:
pnpm audit for dependency vulnerabilities
- Lint: TypeScript strict mode across all packages
Always run pnpm build && pnpm test locally before pushing. The CI pipeline catches the same issues but takes longer.
Contributing
Fork the Repository
Fork sint-ai/sint-protocol on GitHub.
Create a Feature Branch
git checkout -b feat/your-feature-name
Make Your Changes
Follow the existing code style. TypeScript strict mode is enforced. Add tests for new functionality.
Build and Test
All 34 build tasks must succeed. All 1,363+ tests must pass. Submit a Pull Request
Open a PR against sint-ai/sint-protocol:main. Include a clear description of changes and any relevant issue numbers.
Code Style
- TypeScript strict mode (
strict: true in tsconfig.json)
- ES modules (
"type": "module" in all packages)
- Vitest for testing
- Zod for runtime validation
- No
any types in production code
Package Naming Convention
| Pattern | Example | Description |
|---|
@sint/core | Core types | Foundation types and schemas |
@sint/gate-* | @sint/gate-capability-tokens | Security gate components |
@sint/bridge-* | @sint/bridge-ros2 | Protocol bridge adapters |
@sint/engine-* | @sint/engine-hal | Runtime engine components |
@sint/persistence-* | @sint/persistence-postgres | Storage adapters |
Useful Commands
# List all workspace packages
pnpm list --depth 0 -r
# Check for dependency vulnerabilities
pnpm audit
# Update all dependencies
pnpm update --recursive
# Generate a keypair (gateway must be running)
curl -X POST http://localhost:4100/v1/keypair
# Check gateway health
curl http://localhost:4100/v1/health
# View OpenAPI spec
curl http://localhost:4100/v1/openapi.json
