Everything you need to use, run and trust the grid.

Introduction

ZNode Grid is private file storage. Files are encrypted in your browser, then stored as three replicas on independent storage nodes. A coordinator watches those nodes and repairs lost replicas automatically. Storage is paid for once, on-chain, and that payment funds the operators who run the nodes.

Quickstart

Storing your first file takes about two minutes.

1. Get a wallet. Any browser wallet such as MetaMask, set to Robinhood Chain (chain ID 4663) with a little ETH for the payment.
2. Open the vault. Go to /app and click Connect wallet. Sign the login message. No gas is spent.
3. Buy storage. Click Buy storage and confirm the transaction. The price is read from the contract, so you always pay the exact amount.
4. Upload. Drop files onto the upload area. Each one is encrypted before it leaves your device.
5. Download anywhere. Sign in from any browser with the same wallet and your files decrypt locally.

Run a node

A node is a small Node.js server that stores encrypted replicas on disk. One install can run several nodes, each with its own home folder.

1. Create a join token

Open /nodes, connect the wallet that should own the node and receive rewards, enter a name and capacity, and click Create join token. Tokens are single-use and expire after 24 hours.

2. Start the node

$ cd usernode
$ npm install
$ node server.js --token znj_… --port 4001 --capacity 5 --home ./nodes/home-server

On first start the node:

• creates its identity key in <home>/wallet.json;
• signs a join request with your token;
• passes a contact check, where the coordinator calls the node's /health and confirms it reports the same identity;
• saves its assigned ID in <home>/node.json.

Later starts need no token: node server.js --port 4001 --home ./nodes/home-server.

3. Retiring a node

Use Graceful exit in the console. The node stops receiving new data, its replicas are copied to other nodes, and it shuts itself down once it's empty. If no spare node is available, the exit pauses and can be retried.

Architecture

Upload path

Browser encrypts → backend verifies your session and payment → coordinator picks the 3 least-loaded online nodes (different operators first) → copies are written in parallel → backend records which nodes hold the file.

Repair path

Nodes heartbeat every 5 seconds. After about 15 seconds of silence a node is marked offline and the coordinator asks the backend to repair it. Every replica it held is copied from a healthy replica onto a new node, and the file index is updated.

Security model

• Keys. A random 32-byte vault secret, created in your browser, encrypts every file with AES-256-GCM. The backend stores it only in wrapped form, wrapped with a key your browser derives with HKDF-SHA-256.
• Metadata. File names, types, sizes and dates are encrypted too. The server sees only an opaque ID.
• Node isolation. Nodes accept data requests only with the coordinator's session token, and validate file IDs to prevent path traversal.
• Node identity. Every node signs its join and login challenges with its own key. A node cannot claim another node's ID.

Payments

Storage is a one-time purchase made by calling purchaseStorage() with exactlystoragePrice. The contract rejects any other amount and any second purchase from the same wallet.

How the backend verifies a payment

1. The server's RPC and the transaction are both on chain 4663.
2. The transaction succeeded and has the required confirmations.
3. It was sent to the StorageIncentive address by the signed-in wallet.
4. Its call data is exactly purchaseStorage().
5. Its value equals the configured price exactly.
6. The contract emitted a matching StoragePurchased event.

Each transaction hash can be used once. If the hash is missing or stale, the backend falls back to the contract's hasPurchased(wallet), read at a confirmed block.

See the live state and every function on the contracts page.

Node rewards

The coordinator meters three things for every node while it's online:

Getting paid

1. Register your operator wallet once with registerNode().
2. Claim. The coordinator, acting as the contract's settler, calls rewardNode() to move your unclaimed earnings from the reward pool to your balance. A claim is capped at what the pool holds, and the rest stays unclaimed.
3. Withdraw your balance to your wallet at any time with withdraw().

HTTP API

Backend

Authenticated calls send the session in the x-session header.

Coordinator: operators

Operator calls send the session in the x-operator-session header.

Troubleshooting

“Switch your wallet to Robinhood Chain”

Add the network in your wallet: chain ID 4663, RPC https://rpc.mainnet.chain.robinhood.com, currency ETH.

Payment says “not confirmed yet”

Wait a few seconds and click Buy storage again. The same transaction is re-checked and you won't be charged twice.

A node says “Contact check failed”

The coordinator couldn't reach the node at its --url. Make sure the port is reachable and the URL is correct.

Claim is disabled

Register your payout wallet first, make sure unclaimed earnings exceed the minimum, and check that settlement is configured on the coordinator.