Mastering MaidSafe Unofficial
A concept‑first, code‑rich guide to building on the SAFE Network — with mental models, diagrams, and hands‑on labs. This prototype mirrors a pedagogical style popularized by renowned crypto educator (not affiliated).
What’s inside
- Clear analogies → formal definitions
- "Try it" labs with CLI, JS, and Rust
- Threat‑model sidebars on real risks
- Case studies: from file storage to CRDT collab
Last update:
1. The Problem of Centralization
Analogy: The web’s data sits in castles with drawbridges — DNS, CDNs, and cloud accounts — each a control lever. MaidSafe’s vision is to dissolve the drawbridges by addressing data directly in a self‑healing, encrypted network.
- Address content, not servers.
- Users own keys; the network handles location and replication.
- Economics (storage, bandwidth) emerge from protocol incentives.
2. From MaidSafe to the SAFE Network
The SAFE Network aims for privacy, security, and freedom by default. Nodes form a topology in XOR space and replicate data near its address. Client capability tokens authorize actions without revealing identities.
3. Cryptographic Building Blocks
Hashes & addresses
Immutable data is addressed by the hash of its content. That hash doubles as a coordinate in XOR space.
Keys & signatures
Clients sign requests with private keys. Nodes verify signatures and capability tokens.
hash
→ Address → Replication near address. Capabilities limit actions to the minimum required.
# Generate a keypair (illustrative CLI)
safe keypair new --out alice.key
safe keypair show alice.key
4. XOR Space & Routing
Mental model: Distances are bitwise: dist(a,b) = a XOR b
. Each hop forwards to a neighbor closer to the target address, monotonically decreasing the XOR distance.
// JavaScript — compute XOR distance (illustrative)
function xorDistance(hexA, hexB){
const a = Buffer.from(hexA.replace(/^0x/, ''), 'hex');
const b = Buffer.from(hexB.replace(/^0x/, ''), 'hex');
const len = Math.max(a.length, b.length);
const A = Buffer.concat([Buffer.alloc(len - a.length), a]);
const B = Buffer.concat([Buffer.alloc(len - b.length), b]);
const out = Buffer.alloc(len);
for (let i=0;i
// Rust — closest-of-k (illustrative)
use num_bigint::BigUint;
fn xor_distance(a: &[u8], b: &[u8]) -> BigUint {
let v: Vec = a.iter().zip(b.iter()).map(|(x,y)| x ^ y).collect();
BigUint::from_bytes_be(&v)
}
A XOR B
as a BigInt; lower is closer.5. Data Model
- Immutable: address = hash(content). Perfect for versioned snapshots.
- Mutable: pointers that can change under signed authority.
- Append‑only: logs for messaging and event streams.
6. Bootstrapping & Nodes
Start a local testnet, join a public one, and inspect routing tables. Prefer diverse bootstrap peers and rotate periodically to resist eclipses.
# Illustrative workflow
safe net up --profile local
safe node join --peer 203.0.113.42:12000
safe net peers --json | jq '.[] | {addr, age, rtt}'
7. Incentives & Economics
Resource pricing balances supply (storage, bandwidth, uptime) and demand (uploads, retrievals). Reward mechanisms should resist gaming and align with long‑term reliability.
8. Privacy & Security
End‑to‑end encryption, capability tokens, and minimal metadata exposure form the privacy baseline. Avoid correlatable patterns, e.g., fixed request sizes, predictable timing.
9. Reliability & Healing
Nodes churn; the network heals. Replication near the address, opportunistic caching, and periodic audits maintain durability and availability.
10. SDK Tour
Bindings exist for multiple languages. This book uses JavaScript for quick iteration and Rust for performance and control.
// JS — upload a file (illustrative)
import { connect, files } from "@safe/sdk";
const client = await connect();
const id = await files.put("./notes.md");
console.log("safe://"+id);
// Rust — list peers (illustrative)
fn main(){
let peers = safe::net::peers();
for p in peers { println!("{} {}ms", p.addr, p.rtt_ms); }
}
11. Files & Self‑Encryption
Self‑encryption shards and mixes your data so that no single chunk reveals plaintext. A data map records how to reconstruct the file.
- Split file into fixed‑size chunks.
- Hash chunks → derive addresses.
- Encrypt each chunk using keys derived from other chunks’ hashes.
- Upload; the network replicates near each address.
# Inspect a pipeline (illustrative)
safe file put ./photos/vacation.zip --progress --verify
safe file stat safe://<address> --explain
12. Identity & Auth
Use capability tokens with least privilege: scope by resource, operation, and lifetime. Store keys client‑side in hardware‑backed keystores when available.
13. Messaging & Data Flows
Append‑only logs enable pub/sub patterns and tamper‑evident histories. CRDTs allow conflict‑free collaboration at the edge.
14. Hosting Sites without Servers
Host static assets under immutable addresses; point a mutable name to the latest version. For dynamic behavior, push computation to clients and coordinate via append‑only data.
15. Gateways & Bridges
Bridge worlds cautiously: minimize trusted gateways and avoid leaking user identifiers when crossing to Web2 or other networks.
16. Vault Internals
Storage, caching, and replication decisions vary with network conditions. Nodes aim to optimize proximity in XOR space while balancing load.
17. Routing & Consensus Evolution
SAFE’s routing ideas have iterated across prototypes. Anti‑Sybil approaches combine identity costs, diversity requirements, and topology management.
18. Performance & Tuning
Measure before you tune. Capture latency distributions, chunk upload success rates, and tail behavior under churn.
19. Security Audits
Threat‑model your app: enumerate assets, adversaries, and trust boundaries. Verify cryptographic assumptions and check for side channels.
20. Case Study — Decentralized Dropbox
- CLI: add, list, get.
- JS front‑end: progress bars, resumable uploads.
- Rust worker: integrity verification and retry logic.
- Mutable alias for the current folder head.
- Upload a 100MB file; capture chunk map.
- Verify retrieval after simulated node churn.
- Rotate alias to a new version and roll back.
21. Encrypted Photo Sharing
Share via capability links with expiry and revocation. Thumbnails can be generated client‑side to avoid leaking originals.
22. Tamper‑evident Wiki
Each edit appends an entry; readers verify the log head. Moderation = capability rotation and view filters.
23. IoT Data Logger
Constrained devices batch samples, encrypt, and upload opportunistically. Gateways validate and forward with backpressure.
24. Multi‑user Collaboration with CRDTs
Use CRDTs for text and shapes; store snapshots immutably and stream edits append‑only for replayable timelines.
Appendix A — CLI & SDK Quick Reference
CLI
# Keys
safe keypair new --out KEY
safe keypair show KEY
# Files
safe file put ./path
safe file get safe://ADDR ./out
JavaScript
import { connect } from "@safe/sdk";
const client = await connect();
// ...
Appendix B — Key Management Checklists
- Hardware‑backed keys where possible
- Short‑lived capabilities; rotate regularly
- Offline backups; test recovery
Appendix C — Glossary
- XOR Space
- Address space where distance is computed via bitwise XOR.
- Self‑Encryption
- Chunk encryption using keys derived from other chunks’ hashes.
- Capability Token
- Signed grant allowing specific actions for a limited time.
Appendix D — Further Reading
Project documentation, academic papers on DHTs, CRDTs, and privacy‑preserving storage. (Add your org’s canonical links here.)