Getting Started

TransferChain S4 SDK

Full Technical Specification

1. What is TransferChain S4

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

S4 is not a storage provider. It is a cryptographic enforcement layer that sits between your application and storage infrastructure.

Core guarantees:

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

2. High-Level Architecture

Client / Application
        |
        |  HTTP SDK calls (/v1)
        v
TransferChain S4 (Docker container)
        |
        |  Encrypted + fragmented data
        v
TransferChain File Operation Service
        |
        |  Immutable metadata
        v
TransferChain Blockchain (Medusa v2)

Trust boundaries

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 by design
State is externalized via:
- s4.yaml (identity + key custody)
- Storage backends
- Blockchain ledger

Supported environments:

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

4. Configuration File: `s4.yaml`

The s4.yaml file is the core configuration and security file for TransferChain S4.

It defines:

Authentication and organization identity
Cryptographic key custody
Storage routing
Blockchain connectivity
Runtime behavior
Logging behavior

This file must be protected.

4.1 Full `s4.yaml` Reference

# TransferChain authentication and authorization information.
account:
    api:
        token:
        secret:
        url: https://connect.transferchain.io
    identifier: 0
    mnemonics:
    uuid:

# TransferChain file operation's (storage upload, download, delete) Server URL.
fileoperation:
    host: https://file-operation.transferchain.io

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

# APIs verbose mode. if open showed all log events.
verbose: false

listen: true

logformat: "json" # or text

version: v1

5. Configuration Sections Explained

5.1 `account`

Defines who you are, how you authenticate, and who owns the encryption keys.

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

account.api.token

API key issued by TransferChain
Can be provided via API_KEY environment variable
Used to authenticate S4 to TransferChain control plane

account.api.secret

API secret paired with the token
Can be provided via API_SECRET environment variable

account.api.url

TransferChain authentication endpoint
Typically constant

account.identifier

Organization identifier
Scopes:
- storage
- blockchain transactions
- authorization checks
Usually injected via IDENTIFIER env var

account.uuid

Globally unique organization UUID
Used to bind blockchain records and metadata
Usually injected via UUID env var

account.mnemonics

Cryptographic root of trust
Generated during /v1/account/init
Used to derive encryption keys
Required to restore access to data

Security implications:

Anyone with mnemonics can restore and decrypt all data
Must never be committed to version control
Must be backed up securely

5.2 `fileoperation`

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

Defines the TransferChain service responsible for:

encrypted upload
encrypted download
deletion coordination

Important properties:

Receives only encrypted fragments
Cannot reconstruct files
Does not have access to keys

5.3 `readnode`

Defines blockchain read access.

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

Used for:

Reading immutable transaction records
Verifying integrity
Audit and compliance workflows

Blockchain stores:

metadata only
hashes
timestamps
proofs

No data. No keys.

5.4 `verbose`

verbose: false

Controls logging verbosity.

false
- Production-safe logging
- No internal debug noise
true
- Detailed internal logs
- Request flow
- Debug-level events

Recommendation: Enable only temporarily in controlled environments.

5.5 `listen`

listen: true

Controls whether the S4 HTTP SDK listens for incoming requests.

true
- HTTP API enabled
- Required for normal SDK usage
false
- API disabled
- Advanced embedded or internal use cases only

5.6 `logformat`

logformat: "json"

Defines log output format.

json (recommended)
- Structured
- SIEM-friendly
- Audit-friendly
text
- Human-readable
- Development only

5.7 `version`

version: v1

Configuration schema version
Must match S4 binary expectations
Currently constant

6. Environment Variables

Recommended way to inject secrets and runtime values.

Variable

Purpose

API_KEY

API token

API_SECRET

API secret

IDENTIFIER

Organization identifier

UUID

Organization UUID

PORT

HTTP listen port

LOG_PATH

Log output path

WITHOUT_LISTEN

Advanced runtime flag

7. Service Lifecycle

Container starts
s4.yaml is loaded
Environment variables override config where applicable
Authentication validated
Account state checked
If not initialized:
- /v1/account/init required
HTTP SDK starts listening (if listen: true)
Storage + blockchain services activated

8. HTTP SDK Overview

Base URL:

http://localhost:<PORT>

All endpoints are prefixed with:

/v1

9. Account APIs

9.1 Initialize Account

Creates cryptographic identity and generates mnemonics.

POST /v1/account/init

{
  "force": false
}

Response:

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

Behavior:

Writes mnemonics into s4.yaml
Should be executed once
force: true recreates identity (destructive)

9.2 Restore Account

Restores access using existing mnemonics.

POST /v1/account/restore

{
  "mnemonics": ["word1", "word2", "..."],
  "force": false
}

Used for:

disaster recovery
migration
host loss

10. Storage APIs

10.1 Upload

Encrypts, fragments, distributes, and commits metadata.

POST /v1/storage/upload

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

Response (simplified):

{
  "data": {
    "transactions": [
      {
        "id": "tx_abc123",
        "timestamp": 1700000000
      }
    ]
  }
}

Key points:

Each file produces a transaction ID
Transaction ID is the only retrieval handle
Filenames are not required for download

10.2 List Transactions

GET /v1/storage/

Query params:

limit
last_id

10.3 Get Transaction Details

GET /v1/storage/{txID}

Returns:

storage metadata
blockchain references
non-sensitive cryptographic context

10.4 Download

POST /v1/storage/download/{txID}

{
  "path": "/target/download/path"
}

Behavior:

Fragments reassembled inside S4
Decryption occurs locally
Plaintext never leaves process unprotected

10.5 Delete

Deletes storage references and commits deletion to blockchain.

{
  "tx_id": ["tx_abc123"]
}

Deletion guarantees:

Cryptographic erasure
Immutable deletion record
Irreversibility

11. Blockchain Guarantees

Every operation produces:

Immutable transaction hash
Timestamp
Non-repudiable record

Blockchain stores:

metadata only
no file contents
no encryption keys

12. Security Model

Zero-Knowledge by Design

TransferChain cannot decrypt data
Storage providers cannot reconstruct files
Blockchain cannot infer content

Key Custody

Keys derived from mnemonics
No escrow
No backdoors
Customer-controlled recovery

13. Logging & Observability

Deterministic transaction IDs
Structured JSON logs
Correlatable with blockchain records

Compatible with:

SIEM
SOC tooling
Compliance reporting

14. Failure & Recovery Scenarios

Scenario

Resolution

Container lost

Restore via mnemonics

Storage backend failure

Fragment redundancy

Blockchain node outage

Read-only degradation

Credential rotation

Update env vars

15. Compliance Alignment

Designed to support:

GDPR
HIPAA
PCI-DSS
FIPS
ISO 27001
ISO 27701
High-assurance regulated industries

16. 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 secure storage SDK

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

PreviousAbout NextAuthentication and Access Credentials

Last updated 1 day ago

hashtagTransferChain S4 SDK

hashtag1. What is TransferChain S4

hashtag2. High-Level Architecture

hashtagTrust boundaries

hashtag3. Deployment Model

hashtag4. Configuration File: s4.yaml

hashtag4.1 Full s4.yaml Reference

hashtag5. Configuration Sections Explained

hashtag5.1 account

hashtag5.2 fileoperation

hashtag5.3 readnode

hashtag5.4 verbose

hashtag5.5 listen

hashtag5.6 logformat

hashtag5.7 version

hashtag6. Environment Variables

hashtag7. Service Lifecycle

hashtag8. HTTP SDK Overview

hashtag9. Account APIs

hashtag9.1 Initialize Account

hashtag9.2 Restore Account

hashtag10. Storage APIs

hashtag10.1 Upload

hashtag10.2 List Transactions

hashtag10.3 Get Transaction Details

hashtag10.4 Download

hashtag10.5 Delete

hashtag11. Blockchain Guarantees

hashtag12. Security Model

hashtagZero-Knowledge by Design

hashtagKey Custody

hashtag13. Logging & Observability

hashtag14. Failure & Recovery Scenarios

hashtag15. Compliance Alignment

hashtag16. Final Summary