Overview on Sankofa Engine Documentation

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

What is Sankofa Engine

Sankofa Engine is a sharded, privacy-preserving financial ledger engine purpose-built for digital assets. It delivers cryptographically auditable transaction processing with zero-knowledge proof capabilities, enabling organizations to operate compliant, high-throughput ledger infrastructure without exposing sensitive financial data.

Traditional ledger systems force a choice between transparency and privacy. Sankofa Engine eliminates that trade-off: every transaction is recorded in a tamper-evident hash chain and signed with a cryptographic receipt, while encrypted balances and ZKP assertions ensure that only authorized parties can observe account state.

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Architectural Style

Sankofa Engine follows Hexagonal Architecture (Ports & Adapters) combined with Domain-Driven Design (DDD). This separation ensures the business logic remains independent of infrastructure concerns and can be tested, reviewed, and evolved without touching database drivers, message brokers, or HTTP frameworks.

The codebase is organized into four layers:

Layer	Path	Responsibility
Domain Core	`internal/core/`	Pure business logic and domain models. Zero infrastructure dependencies.
Ports	`internal/core/port/`	Go interfaces that define contracts between the domain and the outside world (e.g., `LedgerRepository`, `EventPublisher`).
Adapters	`internal/adapter/`	Concrete implementations of ports — ScyllaDB repositories, NATS publishers, OpenBao key providers, etc.
Services	`internal/service/`	Application services that orchestrate domain operations, coordinate across ports, and enforce transaction boundaries.

Dependencies always point inward: adapters depend on ports, ports depend on domain types, and the domain core depends on nothing external.

Services

Mon, 01 Jan 0001 00:00:00 +0000

Sankofa Engine is composed of seven microservices plus a shared health-check contract. Each service is independently deployable and communicates with other services exclusively through NATS JetStream.

API Gateway

Property	Value
Port	8080 (HTTP) / 9090 (health)
Replicas	2 + HPA
Dependencies	NATS

The API Gateway is the public REST API entry point for all client interactions with the Sankofa Engine.

Key Responsibilities:

Request validation against JSON schemas
JWT authentication and ECDSA request signature verification
RBAC policy enforcement via Casbin
Rate limiting per tenant and per endpoint
FNV-1a shard routing — deterministically maps account_id to the correct shard subject
NATS RPC proxying — publishes validated requests to JetStream and returns signed receipts to callers

Shard Worker

Property	Value
Port	9090 (health only)
Replicas	3 + HPA
Dependencies	NATS, ScyllaDB, OpenBao

Shard Workers are the core transaction-processing units. Each worker is assigned one or more shards by the Shard Orchestrator and processes all transactions routed to those shards.

Security Overview

Mon, 01 Jan 0001 00:00:00 +0000

The Sankofa Engine implements defense-in-depth security across authentication, authorization, encryption, and audit logging. This page provides a high-level overview — for detailed documentation, see the Security & Compliance section.

Security Architecture Summary

Layer	Implementation
Authentication	JWT tokens via API key exchange, ECDSA P-256 transaction signing for self-custody
Authorization	Casbin v2 RBAC with policy-based access control
Encryption at Rest	AES-GCM-256 envelope encryption with KMS-derived keys
Encryption in Transit	mTLS between services, TLS for client connections
Audit Trail	SHA-256 hash chains per account, ECDSA P-256 signed receipts
Key Management	OpenBao (Vault fork) transit backend, AWS KMS support
Infrastructure	Kubernetes namespace isolation, network policies, secret scoping

Detailed Documentation

Security Controls — SOC 2 Trust Service Criteria mapping
Encryption — Encryption at rest, in transit, and key management
Access Control — Authentication, authorization, and infrastructure access
Audit Logging — Hash chains, signed receipts, and event retention
Data Residency — Storage tiers, retention policies, and archival