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 multi-layered envelope encryption scheme to ensure only you can access your files. Even the computer storing your data cannot read it.

Key Hierarchy

Passphrase
  ↓ PBKDF2-SHA256 (100,000 iterations + random salt)
Master Key (256-bit)
  ↓ HKDF-SHA256 (per-file info)
KEK (Key Encryption Key) — wraps the DEK
  ↓
DEK (Data Encryption Key) — random per file, encrypts chunks
  ↓ HKDF-SHA256 (per-chunk index)
Per-Chunk Key — unique AES-256-GCM key for each chunk

Encryption Pipeline

1. Key Derivation — Your passphrase is run through PBKDF2-SHA256 (100,000 iterations) with a random salt to produce a 256-bit master key.
2. Envelope Creation — Each file gets a random DEK (Data Encryption Key). The DEK is wrapped (encrypted) by a KEK derived from your master key. The wrapped DEK is stored as a KeyEnvelope alongside the file metadata.
3. Per-Chunk Keys — Each chunk gets its own key, derived from the DEK using HKDF-SHA256 with the chunk index. This provides defense-in-depth: compromising one chunk key does not compromise others.
4. Encryption — Each chunk is encrypted with AES-256-GCM using a random 12-byte nonce. Output: [Nonce (12B) | Ciphertext | Auth Tag (16B)]
5. Integrity Hash — A BLAKE3 hash of each sealed chunk is computed. Storage nodes use this to verify integrity without decrypting.

Secure Memory Handling

All key material uses SecureKey types that are automatically zeroized in memory when dropped. Keys never persist in plaintext beyond their scope.

Zero-Knowledge Storage

Centram is zero-knowledge by design. Storage nodes hold encrypted chunks but have absolutely no ability to decrypt them — even the operator of the storage node cannot read the data on their own computer.

How It Works

1. Client-side encryption — All encryption happens on the file owner's device before chunks are sent to the network.
2. No key transmission — Encryption keys are never sent to storage nodes. Nodes receive only ciphertext + integrity hashes.
3. Envelope separation — The KeyEnvelope (wrapped DEK) is stored separately from chunk data. Even with both, you need the master key to unwrap the DEK.
4. Storage node verification — Nodes can verify chunk integrity via BLAKE3 hashes without any access to plaintext or keys.

Tamper Detection

Every sealed chunk includes a BLAKE3 integrity hash. If a storage node (or attacker) modifies even a single byte of the ciphertext, the hash check fails, and the AES-GCM authentication tag will also reject the data. Tampering is detected at two independent layers.

Key Sharing (X25519)

Centram uses X25519 Elliptic Curve Diffie-Hellman for secure file sharing between users, without ever exposing encryption keys to the network.

How File Sharing Works

1. Every Centram user has an X25519 keypair (public + secret key).
2. When Alice wants to share a file with Bob, she computes a shared secret: ECDH(Alice_secret, Bob_public)
3. Alice wraps the file's DEK with the shared secret using AES-256-GCM, creating a KeyGrant.
4. The KeyGrant is sent to Bob (can be transmitted publicly — only Bob can unwrap it).
5. Bob computes the same shared secret: ECDH(Bob_secret, Alice_public) and recovers the DEK.

Key Grants

A KeyGrant contains: the wrapped DEK, the sender's public key, the file ID, and an optional expiry timestamp. Grants can be revoked by the file owner by re-encrypting the file with a new DEK.

Wallet Integration

Centram nodes can derive their cryptographic identity from existing cryptocurrency wallets, linking your blockchain address to your Centram node.

Supported Wallets

How Wallet Linking Works

1. The Centram app presents a deterministic message for signing.
2. You sign the message with your wallet (no funds are transferred).
3. The signature is used as seed material for HKDF, deriving three Centram keys:
   • X25519 key — for file sharing and key exchange
   • Ed25519 key — for node identity and signing
   • Master key — for envelope encryption
4. Your Ethereum/Solana address is linked to your Centram node identity.

Supported Chains

Ethereum Mainnet (1), Polygon (137), Arbitrum (42161), Optimism (10), Base (8453), BSC (56), and Solana.

Node Tiers

Every Centram node is automatically classified into a tier based on its hardware specifications. Higher tiers can store more data types, share more bandwidth, and earn higher rewards.

Content Type Restrictions

• Light — Text, Metadata, Config only
• Standard — + Images, Documents, Archives
• Power — + Video, Audio, Datasets
• Enterprise — + ML Models, Relay, CDN Cache (all types)

Tiers are re-evaluated in real time based on system metrics. Your tier may change as your CPU load, available disk space, or network conditions change.

Category Quotas

To prevent any single data type from dominating a node's storage, Centram enforces per-category quotas. Each of the 12 content categories has a maximum percentage of a node's total capacity.

When a category reaches its quota, new chunks of that type are routed to other nodes with available capacity. The node continues to accept other categories normally.

Anti-Concentration Placement

Centram's placement engine prevents data from concentrating on a small number of nodes, ensuring network resilience and fair distribution.

Placement Algorithm

1. Filter — Exclude nodes that cannot accept the chunk (quota full, category disallowed, or node holds >10% of network data).
2. Score — Rank remaining nodes: lower fill ratio (35%), lower category fill (35%), higher trust score (20%), higher tier (10%).
3. Diversify — Select top nodes from different network segments first, then fill remaining slots regardless of segment.
4. Replicate — Ensure minimum replication factor per category (critical data: 5 copies, standard: 3–4 copies).

Network Share Limit

No single node may hold more than 10% of the network's total chunks. Nodes exceeding this limit are flagged for redistribution, with overloaded chunks migrated to emptier nodes.

Replication Factors

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

Decentralized Cybersecurity Force

Centram includes a fully decentralized cybersecurity system where network peers collectively detect, vote on, and block malicious actors. All security actions are recorded on a SHA-256 hash chain, creating an immutable audit trail.

How It Works

1. Detection — Sentinel nodes monitor peer connections in real time, analyzing connection rates, subnet density, and disconnection patterns to identify threats (DDoS, Sybil attacks, Eclipse attacks, etc.).
2. Reporting — Detected threats are broadcast to the network and recorded on the security blockchain with a SHA-256 hash linking each block to the previous.
3. Voting — Peers with sufficient trust scores vote to block or unblock suspicious nodes. Consensus is required before any peer is blocked network-wide.
4. Defense — When a node is attacked, nearby nodes in the same region automatically form a defense coalition, lending bandwidth and processing power to absorb the threat.

Threat Types Detected

• DDoS — Connection flood detection based on rate thresholds
• Sybil Attack — Multiple fake identities from the same subnet
• Eclipse Attack — Rapid peer disconnections indicating node isolation attempts
• Data Tampering — Chunk integrity failures during replication verification
• Unauthorized Access — Brute-force authentication patterns
• Malware Injection — Suspicious payloads in pipeline data streams

Security Blockchain

Every security action (threat report, vote result, peer block/unblock, sentinel reward) is recorded as a block on a dedicated security chain. Each block contains:

Block {
  blockHash:        SHA-256(prevHash + action + target + consensus + timestamp + nonce)
  prevBlockHash:    SHA-256 hash of the previous block
  actionType:       "threat_report" | "block_peer" | "unblock_peer" | "vote_result" | ...
  target:           Peer ID or IP address
  consensusPercent: Percentage of voters who agreed
  timestamp:        Unix timestamp (ms)
  nonce:            Random nonce for hash uniqueness
}

Sentinel Nodes

A Sentinel Node is a specialized node role focused on network security. Sentinels earn rewards for accurate threat detection and participate in community voting.

Detection Sensitivity

Sentinel nodes support three sensitivity levels that control how aggressively threats are flagged:

• Low — Connection rate threshold: 20/min, subnet density: 10. Fewer false positives.
• Medium (default) — Connection rate: 10/min, subnet density: 5. Balanced detection.
• High — Connection rate: 5/min, subnet density: 3. Maximum detection, more false positives.

Real-Time System Monitoring

The security system reads real system resources from the host machine:

• CPU — Core count and real-time usage percentage (via Electron IPC or navigator.hardwareConcurrency)
• Memory — Total and free RAM (via os.totalmem() / os.freemem())
• Disk — Total and free disk space (via check-disk-space or navigator.storage.estimate())
• Network — Available bandwidth (via navigator.connection.downlink), interface enumeration (via os.networkInterfaces())

Collective Defense

When a node is attacked, other nodes in the same blockchain region automatically rally to defend it. This is Centram's "immune system" — decentralized, automatic, and proportional to the threat.

How Coalitions Form

1. A threat is detected targeting a specific node
2. The threat report is broadcast via gossipsub to regional peers
3. Nearby sentinel nodes evaluate the threat and join the defense coalition
4. Each defender contributes bandwidth (Mbps) and processing power (%)
5. The coalition absorbs the attack traffic until the threat is mitigated or the attacker is blocked via consensus vote

Resource Contribution

Each defending node contributes based on its available resources, read directly from the host system:

• Bandwidth — Available network capacity in Mbps
• Processing — Spare CPU capacity (100% minus current usage)
• Memory — Free RAM available for threat mitigation buffers
• Disk — Free storage for logging and evidence collection

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 using per-chunk keys derived from your personal master key. Storage nodes only hold sealed ciphertext + BLAKE3 integrity hashes. Even the node operator cannot decrypt the data on their own machine.

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.

Can I use my existing crypto wallet?

Yes. Centram supports MetaMask, Trust Wallet, Coinbase Wallet, Ledger, Phantom (Solana), and any WalletConnect-compatible wallet. Your wallet signs a message to derive your Centram identity — no funds are transferred and no private keys leave your wallet.

How do I share an encrypted file with someone?

Centram uses X25519 key exchange. You create a KeyGrant that wraps the file's encryption key with a shared secret derived from your key and the recipient's public key. Only the intended recipient can unwrap it. No central key server is needed.