You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Verifiable Event Sync (VES) v1.0 service for deterministic event ordering, state projection, cryptographic commitments, and zero-knowledge compliance proofs.
Overview
The StateSet Sequencer is the central truth clock for distributed commerce systems, bridging AI agents with cryptographically verifiable infrastructure. It implements the complete VES v1.0 protocol specification.
Key Features
Deterministic Event Ordering: Monotonic sequence numbers per (tenant, store) pair
Exactly-Once Delivery: Idempotent event ingestion with event_id and command_id deduplication
Cryptographic Commitments: Merkle trees with domain-separated hashing for audit trails
Agent Signatures: Ed25519 signature verification for event authenticity
STARK Compliance Proofs: Zero-knowledge proofs for regulatory compliance
On-Chain Anchoring: Ethereum L2 commitment anchoring for trustless verification
Offline-First: SQLite outbox pattern for local CLI agents
Payload Encryption: AES-GCM encryption at rest with key rotation support
Schema Validation: JSON Schema validation for event payloads
# Start the sequencer and PostgreSQL
docker-compose up -d
# Check health
curl http://localhost:8080/health
# Check readiness (verifies database connectivity)
curl http://localhost:8080/ready
# Example: Get head sequence (with bootstrap admin key)
curl -H "Authorization: ApiKey dev_admin_key" \
"http://localhost:8080/api/v1/head?tenant_id=<uuid>&store_id=<uuid>"
Local Development
# Build the project
cargo build
# Set required environment variablesexport DATABASE_URL="postgres://sequencer:sequencer@localhost:5433/stateset_sequencer"export BOOTSTRAP_ADMIN_API_KEY="dev_admin_key"# Run the server (migrations run automatically)
cargo run
# Or run migrations manually
cargo run --bin stateset-sequencer-admin -- migrate
# Backfill VES state roots (if upgrading from older versions)
cargo run --bin stateset-sequencer-admin -- backfill-ves-state-roots
# List commitments
GET /api/v1/ves/commitments?tenant_id=<uuid>&store_id=<uuid># Create commitment for sequence range
POST /api/v1/ves/commitments
{
"tenant_id": "uuid",
"store_id": "uuid",
"sequence_start": 1,
"sequence_end": 100
}
# Anchor commitment on-chain
POST /api/v1/ves/commitments/{batch_id}/anchor
VES Proofs
# Submit validity proof (batch ZK proof)
POST /api/v1/ves/validity-proofs
{
"batch_id": "uuid",
"proof_type": "stark",
"proof_data": "base64-encoded-proof",
"public_inputs": { ... }
}
# Submit compliance proof (per-event encrypted proof)
POST /api/v1/ves/compliance-proofs
{
"event_id": "uuid",
"proof_type": "stark",
"encrypted_payload": "base64-encoded",
"public_inputs": { ... }
}
# Get inclusion proof for an event
GET /api/v1/ves/inclusion-proofs/{event_id}
Agent Key Management
# Register agent public key
POST /api/v1/agent-keys
{
"tenant_id": "uuid",
"agent_id": "uuid",
"public_key": "base64-encoded-ed25519-public-key",
"valid_from": "2025-01-01T00:00:00Z",
"valid_until": "2026-01-01T00:00:00Z"
}
# List agent keys
GET /api/v1/agent-keys?tenant_id=<uuid>&agent_id=<uuid># Revoke agent key
DELETE /api/v1/agent-keys/{key_id}
Legacy Endpoints
# Get events (legacy format)
GET /api/v1/events?tenant_id=<uuid>&store_id=<uuid>&from=0&limit=100
# Get head sequence
GET /api/v1/head?tenant_id=<uuid>&store_id=<uuid># Get entity history
GET /api/v1/entities/{entity_type}/{entity_id}?tenant_id=<uuid>&store_id=<uuid>
Health & Metrics
GET /health # Basic health check
GET /ready # Readiness check (database connectivity)
GET /metrics # Prometheus metrics
Gap-Free Sequences: No missing sequence numbers within a stream
Linearizable Ordering: Total ordering via PostgreSQL SELECT FOR UPDATE
Verifiable History: Merkle proofs for event inclusion verification
Domain Separation: All hashes include domain separators per VES spec
Immutable Log: Append-only event storage with no mutations
Testing
# Run all tests
cargo test# Run ignored integration tests (requires PostgreSQL and DATABASE_URL)
cargo test --workspace --tests -- --ignored
# Run with output
cargo test -- --nocapture
# Run benchmarks
cargo bench
Admin CLI
# Run migrations
cargo run --bin stateset-sequencer-admin -- migrate
# Backfill VES state roots
cargo run --bin stateset-sequencer-admin -- backfill-ves-state-roots
# Dry run (preview changes)
cargo run --bin stateset-sequencer-admin -- backfill-ves-state-roots --dry-run
