What you need to know
Five ideas that show up everywhere in the dapp. Read this once and the rest of the guides make sense without footnotes.
1. Your wallet is your key
A Sui wallet is the only identity Waldrop knows about. There's no username, no email, no password. When you "sign in," you're proving you own a wallet — once by signing a short challenge message (free, off-chain), then again each time you do something on-chain (subscribe, register a blob, share access).
The dapp stores a 1-hour session token in your browser so you don't have to sign every page-load. If the session expires (or you reject a popup), the badge in the top-right flips from Verified to Try Again — click it and re-sign.
Off-chain signature (session login): proves you own the wallet. Free, doesn't touch the chain. On-chain transaction signature (subscribe, upload, share): a real Sui transaction that costs gas and updates state.
2. The BlobStore is your folder
When you upload your first file, Waldrop creates a BlobStore — a Sui object that's basically your folder on Walrus. It tracks:
The on-chain truth for how much of your plan's quota you're using.
One row per blob you've uploaded, with its Walrus blob id + your original filename.
Other wallet addresses you've granted decrypt permission to. Per-blob, revocable any time.
16-byte tags that let SEAL-encrypted blobs be unlocked for each viewer without leaking your master key.
One BlobStore per wallet. It's a shared Sui object (every blob's metadata
lives inside it), and you keep an AdminCap in your wallet that proves you
own it.
3. Epochs (≈ 24 hours)
Walrus measures storage time in epochs, not days. One epoch is roughly 24 hours on testnet and 14 days on mainnet — the actual length comes from on-chain config, so the dapp computes "expires in N epochs ≈ M days" live from current network state.
You pick the epoch count when you upload:
| Epochs | Testnet ≈ | Mainnet ≈ |
|---|---|---|
| 1 | 1 day | 14 days |
| 7 | 1 week | ~3 months |
| 26 | ~3.5 weeks | ~1 year |
| 53 | ~7 weeks | ~2 years |
Storage cost scales with size × epochs. The dapp's wizard shows a live estimate before you click Upload.
When a blob's epochs run out, Walrus stops serving its bytes and reclaims the storage. You can extend an existing blob (renew its epochs) any time before it expires.
4. SEAL encryption
Most files you upload are public — anyone with the Walrus blob id can fetch the bytes. For private files, the dapp uses SEAL, Sui's threshold encryption system.
What SEAL does: encrypts your file's bytes with a key that's split across two independent servers (a 2-of-2 threshold). Neither server alone can decrypt; only the combined response, signed by your wallet, can.
What it protects: the file contents. What it doesn't hide: filename, size, owner address, timestamps — all of those still live on-chain in plaintext.
The dapp auto-encrypts when:
- Your plan supports it (Starter and above), AND
- You have a BlobStore (created on your first upload)
Free-tier blobs are public. If you need encryption, subscribe to Starter.
Reading an encrypted blob needs a fresh wallet signature each session (the dapp asks for one when you click a blob in History). That signature is what unlocks the SEAL session key for ~1 hour.
5. Sharing is per-blob
Once a blob is encrypted, only your wallet can decrypt it by default. You grant other wallets access on a per-blob basis:
Sharing is recorded in your BlobStore's on-chain shares table. The wallet you added can revoke their own access at any time, and you can revoke theirs from the Sharing page. All atomic on-chain.
6. How a file actually flows
End-to-end, from "click Upload" to "blob on chain":
Bytes loaded into memory. SHA-256 hash computed for verification.
Fetches a key share from both key servers, encrypts locally. A 16-byte
seal_marker is recorded for sharing later.
Small JSON request. Engine mints a 5-minute JWT bound to your file size.
Direct upload with the JWT as a bearer token. Publisher encodes into slivers, stores across storage nodes, returns a content-addressed blob id.
A Sui transaction that records (blob id, size, expiry, your filename) inside your BlobStore. This is the one signature you see during the upload — everything else is automatic.