Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting started

A brand-new user meets SithBit through one of the four web clients — the webmail app, the Thunderbird extension, the Outlook add-in, or the Chrome extension — and all four walk them through the same five-step onboarding wizard, because they run the same shared core: create or import a wallet, then claim a mailbox (and, if you like, a handle) on-chain in one pass. Nothing here needs the CLI. (If you are comfortable at a terminal, the CLI’s sithbit setup wizard does the same guided pass at the shell, and sithbit earnings gives a configured recipient a read-only snapshot of what their wallet holds and has taken in.)

Web onboarding: the browser wizard

The wizard is what a brand-new user sees first: until it finishes, the client hides its normal wallet manager and mail UI and shows only these five steps.

  1. Welcome — your wallet. Your wallet address is your email address, so the first thing the wizard needs is a wallet. Three paths:

    • Create a new wallet. A fresh Solana keypair is generated entirely in your browser by a WebAssembly module compiled from this workspace’s own crates — the secret never touches a server. The wizard shows that secret key exactly once with a plain warning: save it now, because it is the only copy — lose it and your mailbox is gone forever. You must tick “I have saved my secret key” before you can go on. Copy it somewhere safe (a password manager) before continuing.
    • Import an existing keypair. Paste a Solana keypair file — the same JSON array of 64 numbers sithbit wallet create writes — to reuse a wallet you already own.
    • Connect Phantom or Ledger. If you already run a browser wallet, connect it instead of putting a key in the browser. Your wallet’s signing key never enters the browser — it stays in the extension or on the hardware device, and you approve the mailbox create there. This button only appears when a wallet extension is actually present. Because a hardware wallet cannot itself open sealed mail, this path also creates a separate reading key — see below.

    For the create/import paths you then choose a passphrase, typed twice. The wallet is encrypted under that passphrase before it is stored in the client (PBKDF2 + AES-GCM in the browser’s local storage); the decrypted key lives only in memory for the session, so the client asks for the passphrase again next time. The passphrase is not a recovery phrase — it protects the stored copy, but only the secret key from the create step can restore the wallet elsewhere.

    The second field is a confirmation, and Save stays disabled until the two agree. This is not ceremony: a mistyped passphrase seals the wallet successfully and fails only later, at unlock, by which point the correct passphrase is whatever you typed once, unseen. An eyeball toggle beside each field reveals what you typed, so you can check it before committing.

    The connect-wallet reading key (honest trade-off). SithBit mail is sealed to the recipient, and a Phantom/Ledger wallet can sign but cannot decrypt — its key never leaves the device. So when you connect an external wallet, the wizard generates a separate delegated reading key in your browser and publishes its public half on-chain (senders seal to it). It is revealed once to save, exactly like a fresh keypair, and protected by a passphrase at rest. The trade-offs, stated plainly:

    • Your funds-holding wallet key stays off the browser — only this low-value, mailbox-scoped reading key is browser-held. That is the point of the path.
    • If you lose the reading key, you lose the ability to read already received mail — but not your wallet, your funds, or your mailbox. You can rotate to a new reading key (mailbox set-key) and keep receiving.
    • A recoverable, seed-derived reading key (no separate secret to save) is a planned improvement; for now the reading key is a distinct secret you save, just like a keypair.

  2. Claim your handle. Optionally register a human-readable alias — yourhandle — so senders can mail [email protected] instead of your raw base58 address. Leave it blank and people simply address mail to your wallet directly; you can always claim a handle later. You may also set the sending domain here (blank uses the protocol default, sithbit.com).

  3. Set your price. Choose the default postage — the per-message price, in SOL, that an unknown sender must prepay to reach you. This single number is both your spam defence and your earnings: a high default prices out strangers, and you lower it per sender for people you want to hear from (see Economics for how postage and prepaid stamps work). The default matches the CLI’s — one SOL. An optional checkbox keeps your message bodies off public IPFS (local storage only) from the start.

  4. Review. The wizard shows the handle, domain, and default postage it is about to commit, so you can step back and adjust before anything lands on-chain. If the wallet you chose already owns a mailbox, it says so here rather than trying to create a second one. The wizard also checks the wallet’s on-chain balance at this point: because a mailbox create pays a little SOL (the account rents, plus the alias claim fee when you claimed a handle — length-tiered, so a premium 1–4 character handle raises the figure to match its scarcity price), a wallet that can’t cover it gets a plain-language warning here — naming the wallet, what it holds, and how much more to transfer — instead of a raw chain error at the last step. The warning does not block you: you can fund the wallet out of band and go on.

  5. Finish. One click mints your mailbox on-chain. If you claimed a handle in step 2, the mailbox create and the alias create ride the same transaction — one signature, one confirmation. On the create/import paths the transaction is built and signed client-side in the wasm module and only the finished, signed transaction is relayed; the server never sees your key. On the connect-wallet path the same bundle — mailbox create, the optional alias, and publishing your delegated reading key — is a single approval in Phantom or Ledger; the wallet signs and submits it. When it confirms, the client swaps out of the wizard and into its normal mail-and-settings UI. If the wallet turns out to be unfunded, the create is refused with the same plain-language funding message rather than the node’s raw “debit an account” error.

Because your wallet is your account, there is no “sign up” step and no server-side password — the five steps above are the whole account. A returning user never sees the wizard: a client that already has a stored wallet asks only for the passphrase to unlock it (and reconnects the extension, on the connect-wallet path), and a wallet that already owns a mailbox goes straight to the normal UI. The per-client specifics of that routing — and where each client reads its server and RPC endpoints — are on the webmail, Thunderbird, Outlook, and Chrome pages.

Onboarding a second wallet from inside a client. The wizard is not only a first-run flow. Once you are signed in, each mail client’s dashboard carries an “Add another wallet” button that re-opens the wizard for a fresh wallet — so an existing user can stand up a second mailbox (a new keypair, or another connected wallet) without forgetting the one they already use. Finishing the new wallet returns you to the normal UI, now able to switch between them.

A standalone get-started page

The same wizard is also served on its own, as a standalone get-started page you can point a brand-new user at directly — a single shareable URL, with no mail client installed. It runs the identical five steps and, like the standalone marketplace page, is served by account_api from its [static] root (same origin as the API, so no CORS). When the mailbox lands, the page confirms the wallet is live and points the user at any SithBit client to sign in. It offers the same three wallet paths as the in-client wizard — create a fresh keypair, import one you already hold, or connect a Phantom/Ledger wallet (with the browser-held reading key described above) — so a brand-new user can complete onboarding end-to-end from this one page, with no mail client installed.

Self-service pages for refused senders

The same bundle carries two more standalone pages, aimed not at new users but at senders whose mail a SithBit server just refused — the pages the refusal replies link when the operator sets self_service_base_url:

  • fund.html — the funding page. Reached from a postage refusal (450 4.7.0 out of stamps / 550 5.7.0 no frombox). It resolves the recipient and quotes the stamp price trustlessly off the chain — postage plus the settlement surcharge plus the live protocol fee — then lets the sender connect Phantom or Ledger and buy stamps on the spot, creating the frombox if needed.
  • dnd.html — the schedule page. Reached from a do-not-disturb refusal (450 4.2.1). It answers whether the recipient is accepting mail right now, and shows the away windows only for recipients who opted in to sharing them.

What each page tells the sender — and why refusing beats an autoreply in the first place — is on Do not disturb.

Both read their endpoints from two <meta> tags in the page head — sithbit-rpc-url (the Solana RPC node; both pages) and sithbit-api-url (the account API; the schedule page) — which an operator edits in the staged copy. Left empty, the pages fall back to the webmail app’s localStorage config keys and then the loopback dev defaults; the API default is the page’s own origin, so the normal deployment — the bundle served by account_api from its [static] root, like the get-started page above — needs no setting at all.