Blockchain-based Decentralized Cloud Storage —

Full Step‑by‑Step Project Guide (Beginner, 3‑credit)

Goal: Build a working prototype where a client encrypts and splits a file into chunks, uploads
them to IPFS, publishes a manifest CID on a smart contract, and a storage provider accepts
the deal, pins the data, and is paid on successful retrieval confirmation.

0) What you’ll deliver

Code

• Solidity smart contract: simple storage market with escrow & collateral.
• Node.js CLI tools for: upload (encrypt+chunk+IPFS) and download (retrieve+decrypt).
• Hardhat project with tests + deployment scripts.

Demo

• Run everything locally (Hardhat local chain + local IPFS node) with two accounts: client and provider.
• Screen-record or perform a live demo.

Documentation

• 6–10 page report + README: architecture, design choices, instructions, limitations, and future work.

Stretch (optional)

• Minimal React DApp UI (wallet connect + forms). Not required for 3 credits but nice if time allows.

1) Pre-req quick primer

• Blockchain: transactions, contracts, gas, test networks.
• Solidity basics: state, events, modifiers, payable, mappings.
• IPFS: content addressing (CIDs), adding/cat, pinning, gateways.
• Security: don’t ever store encryption keys on-chain.

You do not need PoR/PoRep proofs for this project—just a lightweight escrow & timeout model sufficient
for an academic prototype.

1
2) High-level architecture

+--------------------+ +---------------------------+
+-------------------+
| Client (CLI) | | Smart Contract (L1/L2) | | Storage
Provider |
| - Encrypt & chunk | Manifest CID + price, collateral | | - Runs
IPFS node |
| - Upload to IPFS +-------> | - Escrow & deal registry | <-----+ | - Accepts
deal |
| - Create deal | | - Timers & payouts | ETH | - Pins
chunks |
| - Confirm retrieval| ETH +---------------------------+ | - Stays
online |
+--------------------+
+---------------+
|
|
|
IPFS | IPFS
v
v
(Local IPFS node) <------------------- Content (chunks) -------------->
(Local IPFS node)

Data flow

1. Client encrypts file locally, splits into chunks, uploads each chunk to IPFS. Gets manifest (JSON) and
uploads that to IPFS too → manifest CID.
2. Client calls createDeal with manifest CID, escrow price & specify required provider collateral +
deadline.
3. Provider accepts by staking the collateral.
4. Provider pins chunks. Client retrieves chunks (via their own IPFS) and checks decryption works.
5. Client calls markCompleted → payout (price + collateral returned to provider). If deadline passes
without completion, client can cancel and also take provider’s collateral.

3) Tech stack choices (beginner-friendly)

• Solidity 0.8.x + Hardhat for contracts, local chain, tests, deploy.
• Node.js CLI for crypto & IPFS via ipfs-http-client .
• AES-256-GCM for client-side encryption.
• Local go-ipfs daemon (or use any pinning service if preferred).

2
4) Project milestones (suggested 5–7 weeks)
1. Week 1: Environment setup, repo scaffold, IPFS install & sanity checks.
2. Week 2: Implement StorageMarket.sol + write unit tests.
3. Week 3: Build CLI: encrypt → chunk → IPFS upload → manifest.
4. Week 4: End-to-end on localhost: createDeal → acceptDeal → retrieve → markCompleted.
5. Week 5: Error handling, timeouts/cancel paths; polish README + test cases.
6. Week 6–7 (optional): Simple React UI and/or deploy to Sepolia for a public demo.

5) Environment setup — step by step

1. Install Node.js (≥18), Git, and a code editor (VS Code).
2. Install Hardhat project deps (done automatically when you run npm install in the starter).
3. Install IPFS (choose one):
4. macOS: brew install ipfs → ipfs init → ipfs daemon
5. Windows: choco install ipfs → run ipfs init then ipfs daemon
6. Linux (Snap): sudo snap install ipfs → ipfs init → ipfs daemon
7. Wallets (optional for testnets): MetaMask or private key for Sepolia.

6) Repo layout (provided in the downloadable starter)

.decloud/
contracts/StorageMarket.sol # escrow + deals + deadlines
scripts/deploy.js # deploy to localhost or Sepolia
scripts/createDeal.js # client creates a deal
scripts/acceptDeal.js # provider accepts
scripts/completeDeal.js # client marks complete
test/StorageMarket.test.js # unit tests
ipfs/upload.mjs # encrypt + chunk + upload
ipfs/download.mjs # fetch + decrypt + reassemble
hardhat.config.js
package.json
.env.example
README.md

Download the starter zip from the chat message and unzip it. Then:

cd decloud
npm install

3
7) Build the smart contract — step by step
1. Open contracts/StorageMarket.sol and study the code (already included).
2. Key ideas:
3. createDeal(manifestCid, providerCollateral, duration) is payable (client escrows the
price in ETH).
4. acceptDeal(id) is payable (provider stakes exactly providerCollateral ).
5. markCompleted(id) releases price + collateral to provider.
6. cancel(id) returns funds to client; if already accepted and deadline passed, client also gets
slashed collateral.
7. Run tests:

npm test

You should see happy-path and cancel-path tests pass.

8) Deploy locally & get an address

1. In one terminal: npm run node (starts Hardhat local blockchain).
2. In a second terminal: npm run deploy:local → copy the contract address it prints (e.g.,
0xABC... ). You’ll use this for deal scripts.

9) Set up IPFS and upload encrypted chunks

1. Start IPFS: ipfs init (first time only) and ipfs daemon (keep it running).
2. In your project folder, run:

npm run upload -- --file ./path/to/anyfile.bin --chunk-bytes 1048576

3. The upload script will:

4. Generate a random AES-256 key (base64 printed to console — save it!).
5. Chunk, encrypt (AES-GCM), and upload each chunk to your local IPFS node.
6. Create a manifest JSON (chunk CIDs, IVs) and upload it too.
7. Print the Manifest CID.

Important: The manifest is not encrypted (for simplicity), but it contains only IVs and chunk CIDs—not the
key. Without the key, chunks are useless.

10) Create, accept, and complete a deal

Client (uses the contract address from deploy):

4
 # price = 0.1 ETH, providerCollateral = 0.02 ETH, duration = 1 hour
node scripts/createDeal.js <CONTRACT_ADDR> <MANIFEST_CID> 20000000000000000
3600 0.1

This prints a deal id.

Provider:

node scripts/acceptDeal.js <CONTRACT_ADDR> <DEAL_ID> 20000000000000000

Now provider should pin chunks (they can just run the same download.mjs to validate retrieval or add
the CIDs to their node).

Client retrieval & verification (confirms decryption works):

node ipfs/download.mjs --manifest <MANIFEST_CID> --key <BASE64_KEY> --out ./

recovered.bin

Confirm the recovered file matches the original (size/hash).

Client marks complete:

node scripts/completeDeal.js <CONTRACT_ADDR> <DEAL_ID>

Provider receives price + collateral.

If provider doesn’t deliver by deadline:

• After duration seconds from acceptance, client can run cancel (add a quick script similarly to
completeDeal.js ) to get price + slashed collateral back.

11) (Optional) Minimal React DApp

If you have time, create a tiny UI (Vite + React + ethers.js):

• Pages: Upload (encrypt+chunk → IPFS), Create Deal, Deal List, Retrieval.

• Wallet: Connect with MetaMask, read/write to the contract.
• UX: Show manifest CID + copy buttons, QR codes for CIDs (bonus), progress bars for upload.

Not mandatory for this course credit but great for your portfolio.

5
12) Testing plan
• Unit tests: Provided tests for create/accept/complete/cancel.
• Integration: End-to-end on localhost covering:
• Upload → manifest → createDeal
• Accept → retrieve → decrypt → markCompleted
• Timeout path: accept and wait > duration → cancel, verify balances
• Security checks:
• Only client can complete/cancel their own deals
• Correct ETH amounts (escrow + collateral) enforced
• No reentrancy in payout flows (we keep flows minimal and single-call)

13) Evaluation rubric (suggested)

• Functionality (40%): end-to-end working, all flows.
• Code quality (20%): clear, commented Solidity & JS, tests pass.
• Security & design (20%): reasonable escrow model, no keys on-chain.
• Documentation & demo (20%): README, report clarity, live demo or video.

14) Limitations & ethics (state clearly in your report)

• Not production secure: no real proof-of-storage; relies on client verification + collateral.
• Manifest is unencrypted (simple prototype); could be encrypted in future.
• No reputation system or multi-provider erasure coding.
• ETH price volatility; testnets recommended for public demos.

15) Extensions (future work)

• Encrypt the manifest (hybrid encryption with recipient’s public key).
• Multi-provider deals + erasure coding (e.g., Reed–Solomon) for resilience.
• Reputation & slashing history (on-chain records per provider).
• Off-chain monitoring service (a bot) that auto-cancels and alerts.
• Integrate with Filecoin/Lighthouse/web3.storage for real incentives.
• NFTs as storage receipts; subgraph indexing and explorer UI.

16) Troubleshooting cheat sheet

• Hardhat not found → npx hardhat test or npm install again.
• IPFS conn refused → ensure ipfs daemon running and scripts use correct API URL.

6
 • Out of gas → increase gas limit or use correct network.
• Different accounts → in Hardhat localhost, account[0] is client by default in scripts; modify scripts to
choose signers if needed.
• Balances → use console.log(await ethers.provider.getBalance(addr)) in tests to
inspect.

17) Report template (short)

1. Abstract (you already have it).
2. Introduction: centralization problems & your proposal.
3. Related Work: IPFS