🔗 SoWasIt - Technical Documentation

Technical Concepts & Guarantees

SoWasIt is a cryptographic anchoring infrastructure designed to guarantee the absolute integrity of your data through immutable and mathematically verifiable proofs of existence.

Anchoring Mechanism

The uniqueness of SoWasIt lies in its double-layer architecture:

[ Votre App ] -> [ Chaîne Privée ] -> [ Chaîne d'Ancrage Publique ]
      |               |                       |
   Données      Ordre & Contexte        Preuve Globale

Each event from your application is first recorded in your private chain (to keep your data confidential), then immediately anchored in the shared public chain.

Atomicity & Reliability

To ensure a proof exists as soon as an operation is confirmed, SoWasIt uses advanced transaction mechanisms.

Atomic Transactions

Writing to your chain and public anchoring occur within a single, atomic transaction.

Lock Management

The use of system-level locks ensures a perfect sequence of succession for blocks, preventing any race conditions even under high concurrency.

Security & Isolation

Although the infrastructure is shared (Multi-tenant), isolation is hermetic.

• Logical Isolation : Each request is filtered by a tenant_id at the database engine level. A user from tenant A can never, by design, address a chain from tenant B.
• Hashed Secrets : API keys and session tokens are never stored in plain text. Only their SHA-256 hash is kept.
• Idempotence : The system supports idempotency keys. If you resend the same request, SoWasIt detects the duplicate and returns the original proof.

API Reference

The API is RESTful and communicates exclusively in JSON over HTTPS.

Authentication

Use the X-API-Key header for your server calls.

GET /v1/chains
Host: api.sowasit.io
X-API-Key: your_api_key_here

Chain Management

A chain is a logical container for your proofs.

Block Anchoring

This is the primary operation for creating a proof.

POST /v1/chains/{chainId}/blocks
{
  "data": {
    "event": "document_signed",
    "hash": "e3b0c442...",
    "user_id": "user_42"
  }
}

Response : You immediately receive the block's hash and its prev_hash, constituting your proof of existence.

Block Versioning

Update existing data while maintaining immutable history. Create new versions of blocks that link to previous versions through prevState/nextState fields.

How It Works

When you update a block (PUT /chains/{chainId}/blocks/{blockId}), a new block is created with the updated content. The new block's prevState field points to the old block's ID, and the old block's nextState is updated to point to the new block. This creates an unbreakable version chain.

PUT /v1/chains/{chainId}/blocks/{blockId}
{
  "content": {
    "event": "document_updated",
    "version": 2
  }
}

Navigating Versions

Each block returned by the API contains metadata.prevState (ID of the previous block) and metadata.nextState (ID of the next block). A block with nextState set to null is the most recent version. To traverse the history, follow the prevState chain block by block. SDKs to simplify this navigation are planned.

Webhooks (Callbacks)

Automate your workflows by receiving real-time notifications when new blocks are added to your chains.

Step 1 — Create the webhook

Call POST /v1/chains/{chainId}/callbacks with your URL. The API returns a secret (store it securely — it will never be shown again) and a validation_challenge (e.g. "tomato").

POST /v1/chains/{chainId}/callbacks
{
  "url": "https://yourapp.com/webhook"
}

// Response
{
  "data": {
    "secret": "a3f8c2d1...",
    "validation_challenge": "tomato"
  }
}

Step 2 — Prepare your endpoint

Your server must respond to GET requests on your URL with the ?check=true parameter by returning exactly: {"challenge": "tomato"} (replace with your actual challenge).

// GET https://yourapp.com/webhook?check=true
{ "challenge": "tomato" }

Step 3 — Validate the webhook

Call POST /v1/chains/{chainId}/callbacks/{id}/validate. SoWasIt contacts your endpoint, checks the response, and activates the webhook if everything is correct.

Verifying incoming notifications

Each notification includes two headers: X-Callback-Secret (your raw secret) and X-Callback-Signature (HMAC-SHA256 of the body signed with your secret). Recompute the HMAC on your side and compare it to the header to ensure the notification genuinely comes from SoWasIt.

// Node.js example
const crypto = require('crypto');
const sig = req.headers['x-callback-signature'];
const expected = crypto
  .createHmac('sha256', YOUR_SECRET)
  .update(req.rawBody)
  .digest('hex');
if (sig !== expected) return res.status(401).send('Invalid signature');

Idempotency : Each notification contains a unique idempotency_key. Store it and ignore any notification with an already-processed key — SoWasIt retries on failure (3 attempts: 30s, 2min, 10min).