Sankofa Engine on Sankofa Engine Documentation

Authentication

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

The Sankofa Engine supports two authentication models. Most integrations use JWT bearer tokens for API access. Self-custody deployments additionally use ECDSA transaction signing to authorize individual transactions without sharing private keys.

For interactive exploration, see the API Explorer.

JWT Authentication (Default)

Sankofa Labs provisions API credentials (client_id and client_secret) during onboarding. Your application exchanges these credentials for a short-lived JWT token, then includes that token on every request.

1. Obtain a Token

POST /v1/auth/token

Configuration

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

Configuration Schema

The Sankofa Engine is configured via a YAML file (default path: config.yaml). Below is the complete schema with all supported fields.

Default Configuration

shard_count: 4

nats:
 cluster_urls:
 - "nats://localhost:4222"
 jetstream:
 max_message_age_seconds: 220898160 # 7 years

scylladb:
 endpoints:
 - "localhost:9042"
 keyspace: "sankofa_engine"
 read_consistency: "ONE"
 request_timeout: "30s"

kms:
 provider: "local"
 region: "us-east-1"

openbao:
 address: "http://localhost:8200"
 token: "dev-root-token"
 transit_mount: "transit"

service:
 name: "monolith"
 id: ""

Field Reference

Field Path	Type	Default	Description
`shard_count`	integer	`4`	Number of shards for partitioning transactions across workers. Determines the modulus for FNV-1a shard routing.
`nats.cluster_urls`	[]string	`["nats://localhost:4222"]`	List of NATS server URLs for the client to connect to. Supports multiple URLs for cluster failover.
`nats.jetstream.max_message_age_seconds`	integer	`220898160` (7 years)	Maximum age in seconds before JetStream messages are expired. Set to 7 years for long-term audit retention.
`scylladb.endpoints`	[]string	`["localhost:9042"]`	ScyllaDB/Cassandra contact points. The driver discovers additional nodes from these seeds.
`scylladb.keyspace`	string	`"sankofa_engine"`	ScyllaDB keyspace name where all tables reside.
`scylladb.read_consistency`	string	`"ONE"`	Read consistency level. Common values: `ONE`, `QUORUM`, `LOCAL_QUORUM`.
`scylladb.request_timeout`	string	`"30s"`	Timeout for individual ScyllaDB requests. Go duration format (e.g., `30s`, `1m`).
`kms.provider`	string	`"local"`	Key management provider. `"local"` for development, `"aws"` for AWS KMS in production.
`kms.region`	string	`"us-east-1"`	Cloud provider region for the KMS service.
`openbao.address`	string	`"http://localhost:8200"`	OpenBao (Vault-compatible) server address for transit encryption.
`openbao.token`	string	`"dev-root-token"`	Authentication token for OpenBao. Use a provisioned secret in production.
`openbao.transit_mount`	string	`"transit"`	Mount path for the OpenBao transit secrets engine.
`service.name`	string	`"monolith"`	Service identity. Used for logging, metrics, and NATS subject routing. Values: `monolith`, `api`, `shard-worker`.
`service.id`	string	`""`	Unique instance identifier. Used to distinguish multiple instances of the same service.

Environment Variable Overrides

Environment variables take precedence over values in the config file. Use these to configure the engine in containerized or orchestrated environments.

Security Controls

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

This page inventories the security controls implemented in the Sankofa Engine, organized by SOC 2 Trust Service Categories. Each control includes an ID, description, implementation details, and the evidence an auditor would examine to verify the control is operating effectively.

CC6 — Logical and Physical Access Controls

CC6.1 — User Authentication

Attribute	Detail
Control ID	CC6.1
Description	The system authenticates users and services before granting access to protected resources.
Implementation	JWT-based authentication with configurable token lifetime. API keys are provisioned by Sankofa Labs during customer onboarding. Clients exchange `client_id` and `client_secret` for a JWT bearer token via the `/auth/token` endpoint. Token lifetimes are configurable per deployment.
Evidence	JWT validation middleware source code; token lifetime configuration values; API key provisioning records maintained by Sankofa Labs; authentication failure logs showing rejected requests.

CC6.2 — Encryption of Data in Transit

Attribute	Detail
Control ID	CC6.2
Description	The system protects data in transit using encryption between all components.
Implementation	Mutual TLS (mTLS) is enforced between all internal services (API Gateway ↔ NATS JetStream, Shard Workers ↔ NATS JetStream, API Gateway ↔ ScyllaDB, etc.). TLS 1.2+ is required for client-to-API Gateway communication. Certificate management uses a `CertificateManager` interface that supports file watching and automatic reload on rotation.
Evidence	TLS configuration in service manifests; mTLS certificate chain; `CertificateManager` source code showing file-watch and auto-reload logic; network policy definitions requiring encrypted transport; TLS handshake logs.

CC6.3 — Role-Based Authorization

Attribute	Detail
Control ID	CC6.3
Description	The system restricts access to resources based on assigned roles and permissions.
Implementation	Casbin v2 RBAC engine with policy-based authorization. Policies define subject (role or user), object (resource), and action (operation). Authorization is enforced at the API Gateway middleware layer before requests reach backend services. Role definitions are maintained in policy files and loaded at startup.
Evidence	Casbin policy files defining roles and permissions; middleware source code enforcing authorization checks; authorization denial logs; role assignment records.

CC6.4 — Infrastructure Access Restrictions

Attribute	Detail
Control ID	CC6.4
Description	Infrastructure-level access is restricted to authorized services and personnel.
Implementation	Kubernetes RBAC controls access to cluster resources. All Sankofa Engine components run in an isolated `sankofa-engine` namespace. Kubernetes NetworkPolicies restrict pod-to-pod communication to only the required paths (e.g., shard workers may communicate with NATS and ScyllaDB but not directly with the API Gateway).
Evidence	Kubernetes RBAC role and role-binding manifests; namespace configuration; NetworkPolicy manifests; `kubectl` output showing effective policies; cluster audit logs.

CC6.5 — API Key Lifecycle Management

Attribute	Detail
Control ID	CC6.5
Description	API keys are managed through a defined lifecycle including provisioning, rotation, and revocation.
Implementation	API keys are provisioned by Sankofa Labs during customer onboarding. Key rotation is supported without downtime — new keys can be issued while old keys remain valid during a configurable grace period. Revocation is immediate upon request. All key lifecycle events are logged.
Evidence	API key provisioning procedures; key rotation records; revocation logs; key lifecycle event audit trail maintained by Sankofa Labs.

CC7 — System Operations

CC7.1 — Health Monitoring and Availability

Attribute	Detail
Control ID	CC7.1
Description	The system is monitored for availability and automatically scales to meet demand.
Implementation	Kubernetes liveness and readiness probes on port 9090 for all services. Horizontal Pod Autoscaler (HPA) automatically scales shard workers based on CPU and memory utilization. Health endpoints expose service status, connection state, and dependency health.
Evidence	Kubernetes deployment manifests showing probe configuration; HPA configuration and scaling event logs; health endpoint responses; uptime monitoring records.

CC7.2 — Event Durability and Retention

Attribute	Detail
Control ID	CC7.2
Description	System events are durably stored and retained for the required period.
Implementation	NATS JetStream provides durable subscriptions for all transaction events. Messages are retained for 7 years by default (`max_message_age_seconds: 220898160`). Full event replay is available from any point in the retention window. Events are append-only and immutable once published.
Evidence	NATS JetStream stream configuration showing retention settings; durable subscription configuration; event replay demonstration; storage utilization metrics.

CC7.3 — Monitoring and Alerting

Attribute	Detail
Control ID	CC7.3
Description	The system provides monitoring data and alerting capabilities for operational awareness.
Implementation	Health endpoints on each service expose operational metrics including connection status, queue depths, and storage utilization. Storage metrics track disk usage, shard distribution, and replication status. Alerting thresholds are configurable per deployment.
Evidence	Health endpoint response samples; monitoring dashboard configuration; alert rule definitions; historical alert records.

CC7.4 — Incident Response

Attribute	Detail
Control ID	CC7.4
Description	Security and operational incidents are identified, reported, and resolved through defined procedures.
Implementation	Incident response is managed by Sankofa Labs. Defined escalation paths cover severity levels from informational to critical. Customers are notified of security incidents affecting their deployment per contractual SLAs. Post-incident reviews produce root cause analysis and remediation actions.
Evidence	Incident response plan documentation; incident ticket history; post-incident review reports; customer notification records.

CC8 — Change Management

CC8.1 — Controlled Deployments

Attribute	Detail
Control ID	CC8.1
Description	All changes to the production system are managed through a controlled deployment process.
Implementation	All deployments are managed exclusively by Sankofa Labs. Customers do not have the ability to deploy code or configuration changes to the engine. Changes follow a defined release process with staging validation before production deployment.
Evidence	Deployment records and change logs; release approval records; staging validation results; access control evidence showing customers cannot initiate deployments.

CC8.2 — Version Management

Attribute	Detail
Control ID	CC8.2
Description	Software versions are tracked and documented with clear change history.
Implementation	The Sankofa Engine follows semantic versioning (SemVer). Every release includes a changelog documenting new features, bug fixes, and breaking changes. Release notes are published to customers before upgrades are applied.
Evidence	Version history and changelog; release notes; semantic version tags in source control; customer communication records for version upgrades.

CC8.3 — Automated Testing in CI/CD

Attribute	Detail
Control ID	CC8.3
Description	Changes are validated through automated testing before deployment.
Implementation	CI/CD pipeline executes unit tests, benchmark tests, and end-to-end (e2e) tests on every change. Pipeline must pass all test stages before a release artifact is produced. Test coverage is tracked and regressions block deployment.
Evidence	CI/CD pipeline configuration; test execution logs and results; test coverage reports; pipeline failure records showing blocked deployments.

CC9 — Risk Mitigation

CC9.1 — Network Segmentation

Attribute	Detail
Control ID	CC9.1
Description	Network communication between services is restricted to only what is required.
Implementation	Kubernetes NetworkPolicies define explicit ingress and egress rules for each service. Only required communication paths are permitted (e.g., API Gateway → NATS, Shard Workers → NATS, Shard Workers → ScyllaDB). All other inter-pod traffic is denied by default.
Evidence	NetworkPolicy manifests; `kubectl describe networkpolicy` output; network traffic logs showing denied connections; architecture diagram of permitted communication paths.

CC9.2 — Secret Management

Attribute	Detail
Control ID	CC9.2
Description	Secrets are managed securely with no plaintext storage.
Implementation	OpenBao (a fork of HashiCorp Vault) manages all secrets including database credentials, API keys, encryption keys, and TLS certificates. Secrets are injected into pods at runtime via the OpenBao agent. No plaintext secrets exist in source code, configuration files, or environment variables.
Evidence	OpenBao configuration and policies; Kubernetes pod specs showing secret injection; source code scan results confirming no hardcoded secrets; OpenBao audit logs showing secret access patterns.

CC9.3 — Encryption at Rest

Attribute	Detail
Control ID	CC9.3
Description	Data at rest is encrypted using strong cryptographic algorithms.
Implementation	AES-GCM-256 envelope encryption protects all data at rest. The Key Management Service (KMS) derives Data Encryption Keys (DEKs) which are used to encrypt data. The DEK itself is encrypted by the KMS master key and stored alongside the ciphertext. Per-dataClass key derivation ensures different data classifications use different encryption keys.
Evidence	Encryption implementation source code; KMS configuration; encrypted data samples showing ciphertext format; key derivation logic; dataClass-to-key mapping configuration.

CC9.4 — Tamper Detection

Attribute	Detail
Control ID	CC9.4
Description	Data integrity is protected through cryptographic mechanisms that detect unauthorized modification.
Implementation	Every transaction extends a SHA-256 audit hash chain per account. Each hash incorporates the previous hash, transaction ID, account ID, amount, type, and timestamp — creating an append-only log where any tampering breaks the chain. Additionally, every processed transaction receives an ECDSA P-256 signed receipt that independently verifies integrity.
Evidence	Hash chain implementation source code; hash chain verification tool output; signed receipt samples with signature verification; chain integrity audit reports.

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.

Quickstart

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

This guide walks you through a complete first integration with the Sankofa Engine API. You will authenticate, deposit funds into an account, transfer between accounts, and query balances.

Prerequisites

Before you begin, you need:

API credentials from Sankofa Labs: a client_id and client_secret provisioned during onboarding.
curl (or any HTTP client) installed on your machine.
Test accounts set up in the Sankofa Engine with a registered fungible token (your onboarding contact will provide these).

Sandbox Environment

During development, use the sandbox base URL https://sandbox.api.example.com. All examples in this guide use https://api.example.com — replace this with your environment’s base URL.

Step 1: Authenticate

Exchange your client credentials for a JWT access token.

API Explorer (Swagger UI)

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

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.

Encryption

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

The Sankofa Engine encrypts data both at rest and in transit. This page documents the cryptographic algorithms, key management architecture, and certificate lifecycle used to protect customer data.

Encryption at Rest

All data at rest is protected using AES-GCM-256 envelope encryption. Envelope encryption separates the key that encrypts data (Data Encryption Key, or DEK) from the key that protects the DEK (the KMS master key), providing defense in depth and enabling key rotation without re-encrypting all data.

Libraries & Dependencies

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

The Sankofa Engine is written in Go and requires Go 1.25 or later. Below are all direct dependencies from go.mod, grouped by category.

HTTP Framework

Package	Version	Purpose
`github.com/gofiber/fiber/v3`	v3.1.0	HTTP framework for the REST API

Database

Package	Version	Purpose
`github.com/gocql/gocql`	v1.7.0	ScyllaDB/Cassandra driver
`github.com/jackc/pgx/v5`	v5.9.1	PostgreSQL driver with connection pooling

Messaging

Package	Version	Purpose
`github.com/nats-io/nats.go`	v1.49.0	NATS client for pub/sub and RPC
`github.com/nats-io/nats-server/v2`	v2.12.6	Embedded NATS server for testing

Authentication and Authorization

Package	Version	Purpose
`github.com/golang-jwt/jwt/v5`	v5.3.1	JWT token generation and validation
`github.com/casbin/casbin/v2`	v2.135.0	Role-based access control (RBAC)

Cryptography

Package	Version	Purpose
`golang.org/x/crypto`	v0.49.0	Cryptographic primitives

Cloud Services

Package	Version	Purpose
`github.com/aws/aws-sdk-go-v2/config`	v1.29.5	AWS SDK configuration
`github.com/aws/aws-sdk-go-v2/service/kms`	v1.43.0	AWS KMS for key management

Utilities

Package	Version	Purpose
`github.com/google/uuid`	v1.6.0	UUID generation
`github.com/shirou/gopsutil/v3`	v3.24.5	System metrics collection
`golang.org/x/time`	v0.15.0	Rate limiting
`gopkg.in/yaml.v3`	v3.0.1	YAML configuration parsing

Testing

Package	Version	Purpose
`github.com/stretchr/testify`	v1.11.1	Testing assertions and mocks

Dependency Management

The project uses Go modules (go.mod / go.sum) for dependency management. To update dependencies:

Transaction Flow

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

This guide walks through the complete lifecycle of a transaction in the Sankofa Engine, from the moment a client submits it to the point where the finalized receipt is available for query. Understanding this flow is essential for building reliable integrations, debugging processing delays, and reasoning about failure scenarios.

Overview

Every transaction passes through seven stages:

 Client API Gateway NATS JetStream Shard Worker
 │ │ │ │
 │ POST /v1/transactions│ │ │
 │──────────────────────►│ │ │
 │ │ validate, auth, │ │
 │ │ compute shard │ │
 │ │ │ │
 │ 202 Accepted │ publish to │ │
 │◄──────────────────────│ LEDGER.shard-{N} │ │
 │ │──────────────────────►│ │
 │ │ │ deliver to worker │
 │ │ │──────────────────────►│
 │ │ │ │ validate balance
 │ │ │ │ update in-memory
 │ │ │ │ extend hash chain
 │ │ │ │ sign receipt
 │ │ │ │ write ScyllaDB
 │ │ │◄──────────────────────│ ack
 │ │ │ │
 │ │ │ Projection Service
 │ │ │──────────────────────►│
 │ │ │ receipt event │ update PostgreSQL
 │ │ │ │
 │ GET /v1/transactions/{txn_id} │ │
 │──────────────────────►│ query projection │ │
 │ 200 OK (finalized) │ │ │
 │◄──────────────────────│ │ │

Stage 1: Client Submit

The client sends a POST /v1/transactions request to the API Gateway.

Access Control

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

The Sankofa Engine enforces access control at three layers: application authentication, policy-based authorization, and infrastructure-level isolation. This page documents each layer.

Authentication

API Key Provisioning

API keys are provisioned by Sankofa Labs during customer onboarding. Customers do not self-register or self-provision credentials.

Step	Description
1. Onboarding request	Customer requests access through Sankofa Labs
2. Identity verification	Sankofa Labs verifies the customer’s identity and authorization
3. Key generation	A unique `client_id` and `client_secret` pair is generated
4. Secure delivery	Credentials are delivered through a secure channel
5. Activation	Credentials are activated in the target deployment

JWT Token Exchange

Clients authenticate by exchanging their API key credentials for a JWT bearer token:

Data Model

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

Entities

Transaction

The central entity in the Sankofa Engine. Represents any ledger operation – debits, credits, transfers, exchanges, minting, and burning.

Field	Type	Description
`account_id`	string	Account identifier. ASCII-only, max 128 characters, allowed: `a-zA-Z0-9_.-:`
`amount`	string	Transaction amount (string, not float – see Amounts as Strings). Max 18 integer + 18 decimal digits.
`type`	enum	Transaction type: `debit`, `credit`, `transfer`, `exchange`, `mint`, `burn`
`status`	enum	Processing status: `pending`, `completed`, `failed`
`signature`	string	ECDSA P-256 signature from the submitting client
`shard_id`	uint32	Assigned shard (computed via FNV-1a hash of `account_id`)
`idempotency_key`	string	Client-provided deduplication key
`group_id`	string (optional)	UUID linking related transactions (e.g., both sides of a transfer)
`token_id`	string (optional)	Associated fungible token identifier
`token_class`	string (optional)	Associated NFT class identifier
`audit_hash`	string	SHA-256 hash chain entry for tamper detection
`receipt_signature`	bytes	ECDSA P-256 DER-encoded receipt signature from the engine
`created_at`	datetime	Creation timestamp

FungibleToken

Represents a fungible token definition (e.g., a currency or point system).

Self-Custody Signing

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

This guide explains the self-custody signing model and walks through generating a keypair, signing transactions, and verifying receipts in Go, Python, and JavaScript.

Overview

In the self-custody model, the account holder controls the signing key. Instead of delegating transaction authorization to Sankofa Labs, each transaction is signed with the account’s own ECDSA P-256 private key before submission. The engine verifies the signature against the public key registered during account setup.

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.

Transactions

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

The Transactions API lets you submit financial operations (debits, credits, transfers, exchanges, mints, and burns), check their processing status, and query transaction history. All transactions are processed asynchronously and are immutable once completed.

For interactive exploration, see the API Explorer.

Important

All monetary amounts are represented as strings, not numbers. This avoids IEEE 754 floating-point precision issues. For example, use "100.00" instead of 100.00. Amounts are limited to 18 integer digits and 18 decimal digits.

Request Limits

All POST requests must include the Content-Type: application/json header. The maximum request body size is 1 MB.

Transaction Types

Type	Description	Example Use Case
`credit`	Funds in — increases account balance	Cash deposit, incoming wire
`debit`	Funds out — decreases account balance	Withdrawal, fee deduction
`transfer`	Move between accounts (pair with `group_id`)	Internal account-to-account transfer
`exchange`	Asset swap between token types	Currency conversion
`mint`	Create new token supply	Token issuance
`burn`	Destroy token supply	Token redemption

Single-Leg vs. Multi-Leg Transactions

Single-leg transactions operate on one account with no counterpart — a cash deposit (credit) or withdrawal (debit) where funds enter or leave the system.

Accounts

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

The Accounts API provides read-only access to account state, token balances, and NFT ownership. These endpoints are served from a PostgreSQL projection layer, which means they are fast but eventually consistent with the underlying ledger.

Account ID Format

Account identifiers must be ASCII-only, at most 128 characters, and may only contain: a-zA-Z0-9_.-:. Requests with invalid account IDs are rejected with a 400 Bad Request error.

For interactive exploration, see the API Explorer.

Audit Logging

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

The Sankofa Engine provides cryptographic guarantees of data integrity through three complementary mechanisms: SHA-256 audit hash chains, ECDSA P-256 signed receipts, and immutable event retention. Together, these mechanisms ensure that every transaction is independently verifiable and any tampering is detectable.

SHA-256 Audit Hash Chain

Every transaction processed by the Sankofa Engine extends the account’s audit hash chain. Each hash incorporates the previous hash, creating an append-only cryptographic log where modification of any entry invalidates all subsequent hashes.

Error Codes

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

Response Format

The Sankofa Engine returns errors using the RFC 7807 Problem Details format. Every error response is a JSON object with a consistent structure:

{
 "type": "https://api.sankofa.engine/errors/invalid-request",
 "title": "Bad Request",
 "status": 400,
 "detail": "amount must be a valid positive decimal number",
 "error_codes": ["ERR_INVALID_AMOUNT"]
}

Field Definitions

Field	Type	Description
`type`	string (URI)	A URI that uniquely identifies the error category. Can be used as a stable reference in documentation and client error handling.
`title`	string	A short, human-readable summary of the error category (e.g., “Bad Request”, “Not Found”).
`status`	integer	The HTTP status code for this response. Mirrors the HTTP response status.
`detail`	string	A human-readable explanation specific to this occurrence of the error. Useful for debugging.
`error_codes`	[]string	One or more machine-readable error codes. A single request may trigger multiple validation errors.

Error Code Reference

General

Code	HTTP Status	Description
`ERR_NOT_FOUND`	404	Resource not found
`ERR_CONFLICT`	409	Resource already exists (e.g., duplicate NFT mint, duplicate token symbol)
`ERR_PAYLOAD_TOO_LARGE`	413	Request body exceeds the 1 MB limit
`ERR_UNSUPPORTED_CONTENT_TYPE`	415	Request must use `Content-Type: application/json`
`ERR_SHARD_UNAVAILABLE`	503	Shard ownership in flux — retry with backoff
`ERR_DOWNSTREAM_FAILURE`	503	An internal dependency is temporarily unavailable

Transaction Validation

Code	HTTP Status	Description
`ERR_INVALID_ACCOUNT_ID`	400	Account ID is missing or invalid. Must be ASCII-only, max 128 characters, allowed: `a-zA-Z0-9_.-:`
`ERR_INVALID_AMOUNT`	400	Amount is required and must be a valid positive decimal (max 18 integer + 18 decimal digits)
`ERR_INVALID_TYPE`	400	Transaction type is required and must be a valid enum value (`debit`, `credit`, `transfer`, `exchange`, `mint`, `burn`)
`ERR_INVALID_SIGNATURE`	400	Signature is required
`ERR_INVALID_IDEMPOTENCY_KEY`	400	Idempotency key is required for all transaction submissions
`ERR_INVALID_GROUP_ID`	400	Group ID must be a valid UUID
`ERR_SELF_TRANSFER`	400	Cannot transfer to the same account

Token Validation

Code	HTTP Status	Description
`ERR_INVALID_TOKEN_ID`	400	Token ID is required
`ERR_INVALID_SYMBOL`	400	Symbol is required
`ERR_INVALID_DECIMALS`	400	Decimal precision must be between 0 and 18
`ERR_INVALID_ISSUER`	400	Issuer is required
`ERR_INVALID_TOTAL_SUPPLY`	400	Total supply must be non-negative
`ERR_INVALID_INITIAL_SUPPLY`	400	Initial supply must be non-negative
`ERR_INVALID_BALANCE`	400	Encrypted balance is required

NFT Validation

Code	HTTP Status	Description
`ERR_INVALID_CLASS_ID`	400	NFT class ID is required
`ERR_INVALID_NAME`	400	Name is required
`ERR_INVALID_SCHEMA`	400	Metadata schema is required and must be valid JSON

Shard and System Validation

Code	HTTP Status	Description
`ERR_INVALID_HEALTH_STATE`	400	Invalid shard health state
`ERR_INVALID_TXN_COUNT`	400	Transaction count must be non-negative
`ERR_NO_SHARDS`	503	No shards configured
`ERR_NO_HEALTHY_SHARDS`	503	No healthy shards available

Audit and Proof Validation

Code	HTTP Status	Description
`ERR_INVALID_PROOF_HASH`	400	Proof hash is required
`ERR_INVALID_REQUESTER`	400	Requester field is required
`ERR_INVALID_PROOF_SYSTEM`	400	Invalid proof system

Timestamp Validation

Code	HTTP Status	Description
`ERR_INVALID_CREATED_AT`	400	`created_at` timestamp is required
`ERR_INVALID_UPDATED_AT`	400	`updated_at` timestamp is required
`ERR_INVALID_TIMESTAMP`	400	Timestamp is required

Error Handling Best Practices

Use `status` for Response Category

Check the HTTP status code to determine the general category of the error:

NFT Lifecycle

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

This guide walks through the complete lifecycle of a non-fungible token (NFT) in the Sankofa Engine: defining a class, minting instances, transferring ownership, querying provenance, and burning instances.

NFTs in the Sankofa Engine are organized into classes and instances. A class defines the schema and metadata structure (like a template), while instances are individual items minted from that class. Each instance has a unique owner and a full provenance chain tracked on the ledger.

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

Compliance Proofs

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

This guide covers generating and verifying zero-knowledge proofs (ZKPs) with the Sankofa Engine’s Compliance API. ZKPs enable privacy-preserving audits – you can demonstrate regulatory compliance without disclosing sensitive ledger data.

What Are Zero-Knowledge Proofs?

A zero-knowledge proof is a cryptographic protocol that lets one party (the prover) convince another party (the verifier) that a statement is true, without revealing any information beyond the truth of the statement itself. The verifier learns nothing about the underlying data – only that the claim is valid.

Data Residency & Retention

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

The Sankofa Engine uses a multi-tier storage architecture to balance performance, cost, and regulatory compliance. This page documents where data resides, how long it is retained, and how it moves between tiers.

Storage Tiers

Tier	Technology	Purpose	Default Retention
Hot	ScyllaDB 6.2	Transaction ledger, account state	Configurable (default 2 years)
Projection	PostgreSQL 16	CQRS read model (balances, query views)	Current state (always up-to-date)
Cold	S3 / Local filesystem	Archived transactions	Long-term (configurable)
Event Log	NATS JetStream	Transaction events, signed receipts	7 years

Tier Descriptions

Hot Tier (ScyllaDB 6.2) The hot tier stores the active transaction ledger and account state. ScyllaDB provides low-latency reads and writes for real-time transaction processing. Data remains in the hot tier for the configured retention period (default 2 years) before becoming eligible for archival.

Tokens & NFTs

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

The Tokens API covers registration and querying of both fungible tokens and non-fungible tokens (NFTs). Fungible tokens represent interchangeable assets (currencies, loyalty points, carbon credits). NFTs represent unique items with individual provenance tracking.

For interactive exploration, see the API Explorer.

Important

All numeric values representing quantities or supplies are encoded as strings to avoid IEEE 754 floating-point precision issues. The decimals field (0-18) defines the token’s precision.

Fungible Tokens

Register a Token

POST /v1/fungible-tokens

Compliance & Attestations

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

The Compliance API enables privacy-preserving audits and verifiable attestations. Using zero-knowledge proofs (ZKPs), the Sankofa Engine can generate cryptographic assertions that prove specific facts about the ledger – such as solvency or asset provenance – without revealing the underlying data. This allows regulated entities to demonstrate compliance to auditors and regulators while preserving the confidentiality of individual account balances and transaction details.

For interactive exploration, see the API Explorer.

Zero-Knowledge Proof Assertions

The assertions API generates ZKP proofs that can be independently verified. Each proof is a cryptographic object that demonstrates a specific claim is true, without disclosing any of the private inputs used to construct it.

v0.2.0-alpha

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

v0.2.0-alpha

Release date: 2026-04-04 Status: Pre-release (Alpha)

Summary

Security hardening, 14 bug fixes, and Settlement Service completion. This release resolves all known limitations from v0.1.0-alpha edge-case testing and hardens the API gateway against injection and abuse.

Security Hardening

Account ID validation – rejects Unicode homoglyphs, zero-width characters, SQL/CQL injection attempts. IDs must be ASCII-only, max 128 characters, allowed characters: a-zA-Z0-9_.-:
Amount precision limits – amounts are validated to a maximum of 18 integer digits and 18 decimal digits
Content-Type enforcement – POST endpoints reject non-application/json bodies
Body size limit – reduced from 10 MB to 1 MB to match NATS max payload
Error sanitization – internal error details (NATS, gocql, infrastructure) are never leaked in API responses. Downstream failures return 503 with a safe message.
Error code matching – switched from substring (Contains) to prefix (HasPrefix) matching to prevent partial-match information leaks
Query parameter validation – account_id, amount_min, amount_max, date_from, date_to, and page_token are validated on the transaction query endpoint. Dates must be RFC 3339; amounts must be valid decimals; page tokens are capped at 512 characters.
Pagination cap – page_size is capped at 1000 across all list endpoints

Bug Fixes

KMS DEK cache pointer aliasing – callers could mutate the shared cached DEK entry; now returns a copy
NATS health check was a no-op – readiness endpoint always reported NATS as healthy; now wired to actual connection status via IsConnected()
Unnecessary ALLOW FILTERING – removed from partition-key-only ScyllaDB queries (GetTokenBySymbol, ListBalancesForAccount); added secondary indexes for txn_id, symbol, and account_id
GetTransaction full-table scan – created a secondary index on transactions(txn_id) to replace ALLOW FILTERING
NFT InsertInstance not idempotent – now uses IF NOT EXISTS (LWT); duplicate mints return an error instead of silently succeeding
NFT class duplicate name – returns 409 Conflict instead of 500 Internal Server Error
Shard consumer unbounded goroutines – per-account processing goroutines are now capped with a CPU-bound semaphore
Status batch update not retried – added 3-attempt retry with 100ms backoff for status persistence
Shard retry returned 404 – changed to 503 shard_unavailable during ownership flux (404 is reserved for genuinely non-existent accounts)
Shard pool size – increased from 4 to 16 connections per shard session
Debit from zero balance – no longer loops indefinitely; the transaction is acked and marked as failed
Missing RPC handlers – added handlers for RPC.account.query.transactions, attestation RPCs, and storage metrics

Settlement Service

The Settlement Service is no longer a skeleton. It now provides:

v0.1.0-alpha

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

v0.1.0-alpha

Release date: 2026-04-03 Status: Pre-release (Alpha)

Summary

Initial alpha release of the Sankofa Engine — a sharded, privacy-preserving financial ledger engine for digital assets.

Features

Core Ledger

Sharded transaction processing with FNV-1a hash-based routing
Block-based transaction batching with in-memory balance cache
SHA-256 audit hash chain per account
ECDSA P-256 signed transaction receipts
Exactly-once processing via NATS JetStream deduplication and idempotency keys

Multi-Asset Support

Fungible token registration, minting, burning, and transfer
NFT class registration, instance minting, transfer, burn, and provenance tracking

Privacy & Compliance

AES-GCM-256 envelope encryption with KMS-derived keys
Zero-knowledge proof generation: proof-of-liabilities, proof-of-provenance, proof-of-compliance
Proof verification endpoint
Asset attestation support

API

REST API via Fiber v3 with JWT authentication
ECDSA P-256 transaction signing for self-custody model
RFC 7807 Problem Details error format
Casbin v2 RBAC authorization

Infrastructure

8 microservices: API Gateway, Shard Worker, Shard Orchestrator, Projection, Compliance, Settlement, Archival, DevCtl
Kubernetes-native deployment with HPA, health probes, network policies
ScyllaDB (ledger), PostgreSQL (projections), NATS JetStream (messaging), OpenBao (key management)
Hot/cold tier archival with configurable retention policies

Known Issues

OpenBao KMS service integration is in progress
ZKP backend is placeholder — proof generation logic is stubbed
Durable Local Queue (NATS failover buffer) is not implemented — messages published while NATS is disconnected will be lost until reconnection

Dependencies

Go 1.25+
ScyllaDB 6.2
PostgreSQL 16
NATS 2.11+ with JetStream
OpenBao (Vault fork)

Breaking Changes

None — initial release.