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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.transferchain.io/transferchain-sdk/s4/core-concepts-and-architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.