Guides on Sankofa Engine Documentation

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.

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.

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.

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.

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.