Core Concepts & Architecture

Full Technical Specification & Developer Integration Guide

1. What is TransferChain S4

TransferChain S4 (Secure Simple Storage Service) is a self-hosted, Dockerized cryptographic storage enforcement layer that exposes an HTTP SDK for secure object storage.

S4 is not a storage provider.

It is a cryptographic + authorization layer that sits between your application and storage infrastructure, ensuring that no data is ever exposed in plaintext outside the trusted execution boundary.

Core Guarantees

Client-side and service-enforced encryption
Customer-controlled key custody (mnemonics-based)
Data fragmentation and distributed storage
Blockchain-backed immutability and auditability
Zero-knowledge architecture

2. High-Level Architecture

Client / Application
        |
        |  SDK (encryption + signing + chunking)
        v
TransferChain S4 (HTTP SDK - Docker)
        |
        |  Encrypted + fragmented data
        v
TransferChain File Operation Service
        |
        |  Metadata (hashes, references)
        v
TransferChain Blockchain (Medusa v2)

Trust Boundaries

Component

Trust Level

Notes

Client

Trusted

Holds keys

Trusted

Handles crypto + orchestration

Storage

Untrusted

Never sees full file

Blockchain

Trust anchor

Immutable metadata

Critical Guarantees

S4 never stores plaintext at rest
Storage backends never receive full files
Blockchain never stores data or keys
TransferChain cannot decrypt customer data

3. Deployment Model

Runtime: Docker container
Stateless architecture

State is externalized via:

s4.yaml (identity + key custody)
Storage backend (S3 / MinIO / etc.)
Blockchain ledger

Supported Environments

Local development
On-premise
Private cloud
Regulated environments (finance, healthcare, defense)

4. Configuration File: s4.yaml

This is the core security file.

It defines:

Identity
Key custody
Storage routing
Blockchain connectivity
Runtime behavior

⚠️ Critical Warning

s4.yaml contains:

mnemonics (root key)
organization identity

Anyone with this file can access data.

4.1 Full Configuration

account:
    api:
        token:
        secret:
        url: https://connect.transferchain.io
    identifier: 0
    mnemonics:
    uuid:

fileoperation:
    host: https://file-operation.transferchain.io

readnode:
    address: https://read-node-01.transferchain.io
    chain:
        name: medusa
        version: v2
    wsaddress: wss://read-node-01.transferchain.io/ws

verbose: false
listen: true
logformat: "json"
version: v1

5. Configuration Deep Explanation

5.1 account (Root of Trust)

This defines identity + key ownership.

Fields

token / secret → API authentication
identifier → organization scope
uuid → global identity binding
mnemonics → cryptographic root key

Mnemonics - BIP39 (Most Critical Part)

Generated during /v1/account/init
Used to derive:
- encryption keys
- signing keys
Required for:
- restore
- decrypt
- ownership

If lost → data is unrecoverable If leaked → partial compromise

5.2 fileoperation

Handles:

encrypted uploads
encrypted downloads
deletion orchestration

Important:

receives only encrypted fragments
cannot reconstruct files
has no key access

5.3 readnode (Blockchain Layer)

Used for:

verifying transactions
audit trails
compliance

Blockchain stores:

hashes
timestamps
proofs

Never:

file contents
encryption keys

5.4 Runtime Controls

Field

Purpose

verbose

debug logging

listen

enable HTTP SDK

logformat

JSON or text

version

schema

6. Environment Variables

Recommended approach:

API_KEY=
API_SECRET=
IDENTIFIER=
UUID=

Override s4.yaml dynamically.

7. Service Lifecycle

1. Container starts
2. s4.yaml loaded
3. Env overrides applied
4. Authentication validated
5. Account checked
6. If not initialized → /v1/account/init
7. HTTP SDK starts
8. Storage + blockchain connections active

8. HTTP SDK Overview

Base:

http://localhost:8080/v1

9. SDK Internal Architecture (Critical)

S4 is not just API.

It internally performs:

Wallet Layer → Identity + signing
Crypto Layer → Encryption (AES)
Fragmentation Engine → Chunking
Uploader → Distributed upload
Metadata Builder → File mapping
Blockchain Signer → Authorization

10. Cryptographic Flow (Real Core)

Upload Pipeline

File
 → Generate fileKey
 → Encrypt (AES-256-GCM)
 → Fragment
 → Upload chunks
 → Build metadata
 → Sign metadata
 → Commit to blockchain

Download Pipeline

txID
 → Fetch metadata
 → Verify blockchain
 → Download fragments
 → Reassemble
 → Decrypt

11. Account APIs

11.1 Initialize

POST /v1/account/init

{
  "force": false
}

Response

{
  "data": {
    "mnemonics": ["word1", "..."],
    "raw": "full phrase"
  }
}

Behavior

Writes mnemonics to s4.yaml
Must run once

11.2 Restore

POST /v1/account/restore

Used for:

migration
disaster recovery

12. Storage APIs

12.1 Upload

POST /v1/storage/upload

{
  "files": ["/absolute/path/file.pdf"]
}

What Actually Happens

File encrypted locally
Split into chunks
Distributed across storage
Metadata created
Metadata signed
Transaction written to blockchain

Response

{
  "data": {
    "transactions": [
      {
        "id": "tx_abc123"
      }
    ]
  }
}

Important Concept

txID = your file reference Filename is irrelevant

12.2 List

GET /v1/storage/

12.3 Details

GET /v1/storage/{txID}

12.4 Download

POST /v1/storage/download/{txID}

{
  "path": "/downloads/"
}

12.5 Delete

POST /v1/storage/delete

{
  "tx_id": ["tx_abc123"]
}

Delete Guarantees

Cryptographic erasure
Blockchain record
Irreversible

13. Deep SDK Implementation (Developer View)

13.1 Encryption

const fileKey = randomBytes(32);

const encrypted = AES_GCM_encrypt(file, fileKey);

13.2 Fragmentation

split(file, chunkSize = 5MB);

13.3 Metadata

{
  "chunks": [...],
  "fileKey": "encrypted",
  "owner": "publicKey"
}

13.4 Signing

signature = sign(hash(metadata), privateKey);

14. Example: Full SDK Upload (Pseudo)

async function upload(file) {
  const fileKey = genKey();

  const encrypted = encrypt(file, fileKey);
  const chunks = split(encrypted);

  const uploaded = await Promise.all(chunks.map(uploadChunk));

  const metadata = buildMetadata(uploaded, fileKey);

  const signature = sign(metadata);

  return sendToS4(metadata, signature);
}

15. Multi-Cloud Distribution

providers = [AWS, GCP, Azure]

chunks[i] → providers[i % n]

16. Security Model (Deep)

Zero-Knowledge

Layer

Can read data?

❌

Storage

❌

TransferChain

❌

Key Custody

derived from mnemonics
never stored centrally
no recovery possible

17. Blockchain Guarantees

Each operation:

transaction hash
timestamp
immutable record

18. Logging & Observability

JSON structured logs
transaction correlation
SIEM compatible

19. Failure & Recovery

Scenario: Lost Server

→ Restore via:

POST /v1/account/restore

Scenario: Lost Mnemonic

→ ❌ Data permanently lost

Scenario: Storage Compromised

→ attacker sees only fragments

20. Performance Considerations

Chunk Size

Size

Impact

Small

higher security

Large

faster

Recommended:

1MB – 20MB

Parallel Upload

Promise.all(chunks.map(upload))

21. Compliance Alignment

Supports:

GDPR
HIPAA
PCI-DSS
ISO 27001 / 27701
FIPS

22. Real Use Case (Your Example - Refined)

A logistics platform stores irsaliye documents:

Files encrypted client-side
Platform owner cannot access contents
Data fragmented across storage
Metadata committed to blockchain
All actions are authorized and validated via blockchain

Result:

No insider risk
No data tampering
Multi-party trust

23. Key Differentiation

Feature

Traditional Storage

Encryption

Server-side

Client-side

Access

Admin-visible

Zero-knowledge

Integrity

Mutable

Blockchain-backed

Storage

Centralized

Fragmented

24. Final Summary

TransferChain S4 is not S3.

It is:

A cryptographic enforcement layer
A key custody system
A blockchain-audited data plane
A zero-knowledge storage SDK

If deployed correctly, no external party including TransferChain can access your data

PreviousS4

NextAuthentication and Access Credentials

Last updated 6 months ago