# Core Concepts & Architecture

## 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                     |
| S4         | 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

1. File encrypted locally
2. Split into chunks
3. Distributed across storage
4. Metadata created
5. Metadata signed
6. 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? |
| ------------- | -------------- |
| S4            | ❌              |
| 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 | S4                |
| ---------- | ------------------- | ----------------- |
| 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**