How Nook works

Three places

Everything in Nook lives in one of three places:

There is no Nook server. The app talks to your own node, your node talks to the Swarm network, and payments go to the chain from your node’s wallet. Nook does use a few public services: the Swarm ID site for signing in, public Gnosis RPC endpoints, a block explorer for the Activity list, and GitHub for downloading Bee and checking for updates.

The keys

Nook has two roots of identity, and they do different jobs:

In Swarm terms

• Postage batches (Nook calls them drives) are bought and owned by the node wallet. Regular and encrypted drives are stamped by Bee; deletable drives are stamped by Nook itself, with etherchunk, using the same node key.
• ACT (access control): the node key is the publisher; people you share with are added as grantees by their node’s public key.
• Feeds owned by the node address: each encrypted drive’s metadata feed and each website’s permanent address.
• Feeds owned by the Nook address: your identity feed (it publishes your messaging public key and your node’s public key, so people can find both from one address) and one mailbox feed per person you write to.
• Chequebook: deployed by Bee and funded from the node wallet; Bee pays other nodes for bandwidth with cheques from it.

Storage

• A drive is an immutable postage batch paid upfront for a size and a time. Each size is bought at the smallest depth whose effective volume (bee-js, no encryption, no erasure coding) covers it — the same rule as Beeport and swarm-cli.
• Used space is what every bucket holds, added up, so it includes folder indexes and older website versions. Bee’s own utilization only measures the fullest bucket; Nook still uses that for “almost full”, because a full bucket is when Bee refuses uploads.
• Adding space raises the batch depth. Bee 2.8.3 keeps a new depth only in memory until the next upload, so a restart could lose it; Nook saves it right away.
• Uploads to a regular drive go to your node first, then Bee pushes the chunks to the network; Nook follows the upload tag until every chunk is stored. Encrypted uploads are pushed directly.
• What others can see: a file on a regular drive is public to anyone who has its address, and the nodes storing it can read its chunks. Encrypted drives are unreadable without access.
• Auto-extend tops the batch up when less than 10 days remain, from the node wallet, while Nook is running.
• Deletable drives are stamped on your computer with etherchunk, which keeps a record of every stamp slot. Deleting a file frees its slots for new uploads; copies already stored stay readable until they expire.

Sharing

1. You share an encrypted drive with someone. Nook looks up their node’s public key through their Nook address (their identity feed) and adds it as an ACT grantee.
2. Nook writes the drive’s file list, encrypted with ACT, and points the drive’s metadata feed to it.
3. They get a message with the link (the feed and your node’s public key). Their node reads the feed, decrypts the list with ACT, and opens the files.

One history per drive. Every ACT change — adding or removing someone, writing the file list — creates a new history entry, and the next change has to build on it. Nook keeps each encrypted drive’s current history itself and makes these changes one at a time. File uploads only use it (Bee returns the history an upload was given), so sharing a drive while a file is uploading doesn’t lock the new person out.

Removing someone changes the drive’s ACT key: new files are locked for them, and files already on the drive need a re-publish before anyone added later can open them. Files they already downloaded stay with them.

Because sharing uses node keys, a person who reinstalls Nook has a new node and needs to be shared with again — Nook detects this and offers “Share again”.

Messaging

• Built on swarm-notify, an open-source library for encrypted messaging over Swarm.
• Contacts, your name and how far each conversation was read are kept in Nook’s data folder, per Nook address. A new browser or private window loads whole conversations — your own sent messages come from your own mailbox feeds.
• Mailboxes: every conversation is two append-only feeds, one per direction, each owned and signed by the sender’s Nook address. One message per feed index; nobody else can write into your mailbox to someone.
• Encryption: each message is encrypted with AES-256-GCM using a key from ECDH between the two Nook identity keys.
• First contact: to reach someone who hasn’t added you yet, Nook also sends a short, encrypted invitation to a registry contract on Gnosis Chain, paid from the node wallet.
• Reserved space: messages and your identity feed are stamped with a small batch Nook buys for this (depth 18, one month, about 2.5 xBZZ, extended automatically). When it gets full, Nook buys a new batch instead of making the old one bigger.
• What stays visible: only the two of you can read what you write, but who talks to whom isn’t hidden — anyone who knows both Nook addresses can find the feeds, when messages were written and roughly how long they are. The registry shows when a known address received an invitation. There is no forward secrecy: someone who later obtains either identity key can read past messages.

Publishing

• A website is uploaded as one collection (a manifest with an index page) on a batch of its own.
• Its permanent address is a feed owned by your node, named after the site, plus a feed manifest; updating the site points the feed at the new version, so the address stays the same.
• ENS: linking a name sets its content hash to the permanent address — a transaction on Ethereum from the wallet that owns the name. Gateways such as eth.limo then serve the site by name.

Wallet & automatic spending

• The node wallet holds xDAI for fees and xBZZ for batches and bandwidth. Nook starts the node as an ultra-light node, and switches to a light node once the wallet has a little xDAI.
• Nook spends on its own only for: auto-extend, the reserved messaging space, and refilling the bandwidth chequebook (it keeps at least 0.5 xBZZ in the wallet). Every payment shows in Activity.
• Only on its own node: before any automatic payment Nook checks that the node answering is its own (by its address). If another Bee node is using Nook’s ports, Nook blocks and never uses it or its funds.
• Chain access goes through a small relay inside Nook that switches to a second public Gnosis RPC when the first one throttles — unless you set your own RPC.

Losing or reinstalling

Your Nook address itself survives a reinstall: sign in with the same Swarm ID and it’s derived again.

Known limits

• Drives, sharing and the wallet belong to one node — there are no drives across devices yet.
• Deletable drives can’t be shared yet.
• No forward secrecy for messages, and conversation metadata is visible (above).
• No backup of file lists yet — keep Nook’s data folder safe.
• Nook is beta software. Use small amounts.

Built on

Nook is open source and stands on these open projects:

• Nook — this app’s source code and releases.
• Swarm and its documentation — the storage network and how it works.
• Bee — the Swarm node Nook runs for you.
• bee-js — the JavaScript library Nook uses to talk to Bee.
• Swarm ID (source) — sign-in and the account your Nook address comes from.
• swarm-notify — encrypted messaging, contacts and invitations over Swarm.
• etherchunk — client-side stamping that makes deletable drives possible.
• Multichain widget — adding funds from other chains and tokens.
• Gnosis Chain — where storage, bandwidth and invitations are paid.