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 20 hours ago

hashtag1. What is TransferChain S4

hashtagCore Guarantees

hashtag2. High-Level Architecture

hashtagTrust Boundaries

hashtagCritical Guarantees

hashtag3. Deployment Model

hashtagSupported Environments

hashtag4. Configuration File: s4.yaml

hashtag⚠️ Critical Warning

hashtag4.1 Full Configuration

hashtag5. Configuration Deep Explanation

hashtag5.1 account (Root of Trust)

hashtagFields

hashtagMnemonics - BIP39 (Most Critical Part)

hashtag5.2 fileoperation

hashtag5.3 readnode (Blockchain Layer)

hashtag5.4 Runtime Controls

hashtag6. Environment Variables

hashtag7. Service Lifecycle

hashtag8. HTTP SDK Overview

hashtag9. SDK Internal Architecture (Critical)

hashtag10. Cryptographic Flow (Real Core)

hashtagUpload Pipeline

hashtagDownload Pipeline

hashtag11. Account APIs

hashtag11.1 Initialize

hashtagResponse

hashtagBehavior

hashtag11.2 Restore

hashtag12. Storage APIs

hashtag12.1 Upload

hashtagWhat Actually Happens

hashtagResponse

hashtagImportant Concept

hashtag12.2 List

hashtag12.3 Details

hashtag12.4 Download

hashtag12.5 Delete

hashtagDelete Guarantees

hashtag13. Deep SDK Implementation (Developer View)

hashtag13.1 Encryption

hashtag13.2 Fragmentation

hashtag13.3 Metadata

hashtag13.4 Signing

hashtag14. Example: Full SDK Upload (Pseudo)

hashtag15. Multi-Cloud Distribution

hashtag16. Security Model (Deep)

hashtagZero-Knowledge

hashtagKey Custody

hashtag17. Blockchain Guarantees

hashtag18. Logging & Observability

hashtag19. Failure & Recovery

hashtagScenario: Lost Server

hashtagScenario: Lost Mnemonic

hashtagScenario: Storage Compromised

hashtag20. Performance Considerations

hashtagChunk Size

hashtagParallel Upload

hashtag21. Compliance Alignment

hashtag22. Real Use Case (Your Example - Refined)

hashtag23. Key Differentiation

hashtag24. Final Summary

1. What is TransferChain S4

Core Guarantees

2. High-Level Architecture

Trust Boundaries

Critical Guarantees

3. Deployment Model

Supported Environments

4. Configuration File: s4.yaml

⚠️ Critical Warning

4.1 Full Configuration

5. Configuration Deep Explanation

5.1 account (Root of Trust)

Fields

Mnemonics - BIP39 (Most Critical Part)

5.2 fileoperation

5.3 readnode (Blockchain Layer)

5.4 Runtime Controls

6. Environment Variables

7. Service Lifecycle

8. HTTP SDK Overview

9. SDK Internal Architecture (Critical)

10. Cryptographic Flow (Real Core)

Upload Pipeline

Download Pipeline

11. Account APIs

11.1 Initialize

Response

Behavior

11.2 Restore

12. Storage APIs

12.1 Upload

What Actually Happens

Response

Important Concept

12.2 List

12.3 Details

12.4 Download

12.5 Delete

Delete Guarantees

13. Deep SDK Implementation (Developer View)

13.1 Encryption

13.2 Fragmentation

13.3 Metadata

13.4 Signing

14. Example: Full SDK Upload (Pseudo)

15. Multi-Cloud Distribution

16. Security Model (Deep)

Zero-Knowledge

Key Custody

17. Blockchain Guarantees

18. Logging & Observability

19. Failure & Recovery

Scenario: Lost Server

Scenario: Lost Mnemonic

Scenario: Storage Compromised

20. Performance Considerations

Chunk Size

Parallel Upload

21. Compliance Alignment

22. Real Use Case (Your Example - Refined)

23. Key Differentiation

24. Final Summary