Technical Reference on Sankofa Engine Documentation

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.

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:

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).

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:

Technical Reference on Sankofa Engine Documentation

Configuration

Configuration Schema

Default Configuration

Field Reference

Environment Variable Overrides

Libraries & Dependencies

HTTP Framework

Database

Messaging

Authentication and Authorization

Cryptography

Cloud Services

Utilities

Testing

Dependency Management

Data Model

Entities

Transaction

FungibleToken

Error Codes

Response Format

Field Definitions

Error Code Reference

General

Transaction Validation

Token Validation

NFT Validation

Shard and System Validation

Audit and Proof Validation

Timestamp Validation

Error Handling Best Practices

Use status for Response Category

Use `status` for Response Category