Centram Documentation

Welcome to the Centram documentation. This guide covers everything from initial setup to advanced configuration, economic incentives, and policies.

System Requirements

Installation

Desktop

Download the latest release for your platform:

Mobile

Install from your device's app store or sideload the APK / IPA directly from the releases page.

From Source

git clone https://github.com/centram/centram.git
cd centram

npm install

cd daemon
pip install -e .

cd core
mkdir build && cd build
cmake ..
make

Quick Start

centram-daemon

# Desktop (Electron)
npm run start:electron

# Desktop (JavaFX)
cd desktop && ./gradlew run

# Web Monitor
cd web-monitor/frontend && npm run dev

# Android
npm run build:android && npm run open:android

Daemon Configuration

The daemon reads its configuration from ~/.centram/config.json. If the file doesn't exist, defaults are used.

Default Configuration

{
  "api_host": "127.0.0.1",
  "api_port": 9740,
  "p2p_port": 9741,
  "data_dir": "~/.centram",
  "reserved_gb": 50,
  "node_type": "storage",
  "subscription_cost": 0.0,
  "accept_24_7_policy": false,
  "bluetooth_fallback": false,
  "bootstrap_peers": []
}

Configuration Options

Node Types

Every Centram node operates as one of three types. Your node type affects allocation priority, trust rewards, and uptime requirements.

Storage Configuration

Data Directory

All Centram data is stored under ~/.centram/ by default:

~/.centram/
  chunks/               Encrypted file chunks (256-way fan-out)
  chain/                Blockchain data
  trust_scores.json     Peer trust records
  config.json           Your configuration

Chunk Storage

Files are split into 4 MB chunks, encrypted individually, and stored in a fan-out directory structure. The first two hex characters of each chunk's SHA-256 hash determine the subdirectory (256 possible directories), ensuring efficient file system lookup.

Reserved Space

The reserved_gb setting (default: 50 GB) tells Centram how much disk space to leave free for the operating system and other applications. Only space beyond this reserve is available for the network.

Replication

Every chunk is replicated to 3 independent peers. The replication manager checks for under-replicated chunks every 60 seconds and automatically repairs them by pushing copies to new peers.

Networking

Connecting to Peers

Centram discovers peers through:

• Bootstrap peers — configured in config.json or via the API
• Peer exchange — connected peers share their known peer lists
• DHT discovery — Kademlia distributed hash table for decentralized lookup

Firewall

If you're behind a firewall or NAT, ensure port 9741 (P2P) is open for incoming connections. The API port (9740) only needs to be accessible from localhost.

CenTrust Score

CenTrust is Centram's reputation system. Every peer starts with a score of 50 (range: 0–100). Your score reflects your reliability on the network.

How Your Score Changes

Trust Levels

Benefits of High Trust

• Gas discounts — up to 50% off all transaction fees
• Allocation priority — your node is chosen first for new chunk storage
• Network reputation — visible on the trust leaderboard

Gas Fees

Every storage transaction incurs a 5% base gas fee. This fee is paid to the block miner who validates the transaction.

How Gas is Calculated

Base gas rate:       5%
Trust discount:      (your_score / 100) × 50%
Effective rate:      5% × (1 - trust_discount)

Example (trust score = 80):
  Trust discount  = (80 / 100) × 50% = 40%
  Effective rate  = 5% × (1 - 0.40) = 3%
  On a 100 unit tx: gas = 3 units, you pay 97

Subscription Pricing

As a storage sharer, you set your own price per GB per month. This is the amount peers pay you for storing their data on your node.

Setting Your Price

• Go to Cloud / Node Settings in any client
• Enter your desired price in the Subscription Price field
• Your price is advertised to the network automatically

Pricing Strategy

• $0.00 — Free storage. Generous to the network, earns trust.
• $0.01 – $0.10 — Competitive pricing. Attracts allocations.
• $0.10+ — Premium pricing. May reduce allocations unless you have high trust and uptime.

Marketplace

The Centram marketplace lists all peers offering storage. It's accessible through the web monitor or any client's Economics section.

Each listing shows:

• Peer ID (anonymized)
• Node type (Storage / Server / Database)
• Trust score
• Price per GB/month
• Available storage capacity

Encryption

Centram uses a layered encryption scheme to ensure only you can access your files:

Encryption Pipeline

1. Key Derivation — Your passphrase is run through PBKDF2-SHA256 (100,000 iterations) with a random 16-byte salt to produce a 256-bit master key.
2. Per-Chunk Keys — Each chunk gets its own key, derived from the master key using HKDF-SHA256 with the chunk index as info parameter.
3. Encryption — Each chunk is encrypted with AES-256-GCM using a random 12-byte IV. The output is: [IV (12B) | Ciphertext | Auth Tag (16B)]

Zero-Knowledge Design

Storage nodes hold encrypted chunks but have no ability to decrypt them. They don't know what files the chunks belong to, what the content is, or who uploaded them. Only the file owner with the correct passphrase can reconstruct and decrypt the data.

Storage Proofs

Centram uses Proof of Storage (PoSt) to verify that peers actually hold the data they claim. This prevents free-riding and ensures data integrity.

How It Works

1. A challenge is derived from the previous block hash and a chunk hash
2. The challenged node must produce a proof by hashing the challenge with the actual chunk data
3. The proof is verified by miners and recorded on the blockchain
4. Successful proofs increase your trust score; failures decrease it

Blockchain

Centram's blockchain is a lightweight chain optimized for storage operations. It records all allocations, storage proofs, trust updates, and economic transactions.

Consensus

Blocks are mined using Proof of Storage rather than Proof of Work. This means mining rewards go to nodes that prove they store data, not nodes that waste energy on hash puzzles.

What Gets Recorded On-Chain

• Storage proofs (chunk possession verification)
• Chunk allocations (which peers hold which chunks)
• Capacity advertisements
• File registrations
• Subscription pricing changes
• Trust score updates
• Node type declarations
• Gas fee payments

Privacy Policy

Data We Never Collect

• Your files, filenames, or file contents
• Your encryption passphrase or keys
• Personal information (name, email, phone)
• Browsing history or usage analytics

Data That Exists on the Network

• Peer ID — a randomly generated identifier (SHA-256 hash). Not linked to your identity.
• IP Address — visible to peers you connect to directly. This is inherent to any P2P network.
• Trust Score — your reputation score is public to other peers.
• Subscription Price — your storage pricing is advertised to the network if you're a sharer.
• Storage Proofs — recorded on-chain, proving you hold specific chunks (but not revealing their content).

Encryption Guarantee

All file data is encrypted client-side before leaving your device. No peer, relay, or server on the network can read your files. Even if every other node on the network colluded, they could not access your data without your passphrase.

Terms of Use

Acceptable Use

By using Centram, you agree to:

• Not store illegal content on the network
• Not attempt to attack, overload, or disrupt the network
• Not impersonate other peers or manipulate trust scores
• Accept that Centram is decentralized software provided "as is" with no warranty

Liability

Centram is open-source software. The developers are not responsible for data loss, service interruption, or any damages arising from the use of this software. You are solely responsible for your passphrase and data backups.

Data Responsibility

As a storage sharer, you store encrypted chunks on behalf of other peers. You cannot see or access the content of these chunks. You are not responsible for their content.

24/7 Uptime Policy

Server and Database nodes must accept the 24/7 Uptime Policy. This is a commitment to keep your node online at all times.

Requirements

• Your node must remain reachable and responsive 24 hours a day, 7 days a week
• Heartbeat responses must be sent within 90 seconds of each challenge
• Scheduled maintenance windows are acceptable if brief

Penalties

• -2.0 trust per hour of downtime
• Extended downtime may result in chunks being re-allocated to other peers
• Severe or repeated downtime degrades your trust score significantly

Opting Out

You can switch back to a Storage node at any time, which removes the 24/7 requirement. However, this also reduces your allocation priority.

API Reference

The daemon exposes a REST API at http://127.0.0.1:9740. All endpoints are prefixed with /api.

Status & Info

Node Configuration

Trust & Economics

Blockchain

WebSocket

Real-time events are available at ws://127.0.0.1:9740/ws.

Ports & Endpoints

FAQ

Can I recover my files if I lose my passphrase?

No. Centram is zero-knowledge by design. Your passphrase is never stored anywhere. Without it, your encryption keys cannot be derived and your files are permanently lost.

What happens if peers storing my data go offline?

Every chunk is replicated to 3 peers. If one goes offline, the replication manager automatically detects the under-replication and pushes the chunk to a new peer. Your data is safe as long as at least one copy remains available.

Can storage nodes read my files?

No. All chunks are encrypted with AES-256-GCM before they leave your device. Storage nodes only hold encrypted blobs. They cannot determine what file a chunk belongs to, its content, or who uploaded it.

How much can I earn by sharing storage?

Earnings depend on your subscription price, available capacity, trust score, and network demand. You set your own price and the marketplace determines how competitive it is.

Do I need a static IP address?

No. Centram supports relay connections for peers behind NAT or firewalls. However, a static IP or open port 9741 will improve your connectivity and peer discovery.

Is there a minimum storage requirement?

No. You can share as little or as much as you want. The reserved_gb setting ensures your OS always has enough space.

What's the difference between the Electron app and the JavaFX app?

Both are full desktop clients. The Electron app wraps the web-based React UI for a familiar experience. The JavaFX app is a fully native desktop interface. Both connect to the same daemon backend.