Welcome

Your inbox has never known peace. Now the fight pays you.

Email promised quiet correspondence and delivered an arms race — filters guessing at spam forever while your address, your archive, and your attention belong to someone else. SithBit doesn’t negotiate a truce. It is a decentralized mail protocol on Solana that changes the balance of power: postage paid by the sender and earned by you — roughly 90% of it lands in your wallet — addresses tied to your wallet instead of a rented domain, and mail encrypted end-to-end and stored off-chain on IPFS. No token: it runs on the SOL you already hold. Standard SMTP, IMAP, and POP3 underneath, so the inbox you already use just works.

Read the Prelude → Skip to the Introduction

Curious how sender-paid postage ended up solving a fifty-year-old email problem? Start with the Prelude for the story of how SithBit came to be, or jump straight to the Introduction for how the economics actually work.

Prelude: A Solution in Search of a Problem

This project began, like a surprising number of things, in lockdown.

When the world shut its doors in 2020, it handed a lot of people something they hadn’t had in years: time, and nowhere to spend it. Some baked bread. Some learned an instrument. A great many, stuck indoors and watching the markets, discovered crypto — and arrived just in time for the moment programmable blockchains grew up. Chains that could run real smart contracts were coming online, fast and cheap enough to be interesting, and they were dazzling: a genuinely new kind of computer, one no single party owned or could switch off.

They were also, for the most part, a brilliant solution in search of a problem. The technology was extraordinary. What it was for was far less clear.

Every technology waits for its killer app

That’s not a knock — it’s just how these things go. A new platform arrives years before anyone knows what it’s really for, and then one application comes along that makes the whole thing suddenly, undeniably worth having. The industry has a name for it: the killer app.

The personal computer had the spreadsheet. VisiCalc, and then Lotus 1-2-3, were so useful that people bought the hardware just to run the software — a beige box justified by a grid of numbers. The internet had one too, and it wasn’t the web browser. Years before Netscape, before anyone said “surfing,” the thing that pulled people online was email. Instant, free, global, personal. Correspondence at the speed of light. It was the internet’s first killer app, and for a long stretch it was the internet to most of the people using it.

Then someone realized you could advertise through it.

The flaw was in the economics, not the code

Email’s fatal weakness was never a bug. It was a price: sending a message costs the sender essentially nothing. That single fact — wonderful for correspondence — turned inevitably, mechanically, into spam. If reaching one more inbox is free, then reaching a hundred million of them is nearly free too, and the math only ever points one direction.

What followed was one of the great arms races of the computing era. To hold the tide back, engineers taught machines to read — to weigh words and patterns and guess, message by message, what was junk. Some of the earliest large-scale machine learning ever put into production was pointed squarely at your inbox. The decades of research and the fortunes poured into telling ham from spam seeded techniques for classifying human language at scale — an unmistakable ancestor of the models behind today’s AI revolution. Spam, of all things, helped teach the machines to understand us.

And still, after all of it, the problem was never actually solved. Filters treat the symptom. The incentive to send spam has never once been touched, and the volume climbs every year regardless. Worse, the same free-to-send flaw now carries phishing and invoice fraud measured in billions a year — and the machines the spam wars trained have learned to write the bait, so the filters that judge content are losing to content they can no longer tell apart.

The other problem: we gave it all away

Somewhere along the way a second flaw came into focus, quieter but deeper. The open internet had quietly re-centralized. A handful of companies came to own our identities, our archives, our address books — and our mail. Your address lives on someone else’s domain; your messages sit, readable, on someone else’s servers; and all of it can be revoked, mined, or discontinued at their discretion. People began calling the fix Web 3.0: a web you own rather than rent, built on exactly the ownerless computers the pandemic-era crypto boom had just made real.

The revolution came for money, for art, for identity, for storage. It never quite came for email — the web’s very first killer app, still running on infrastructure and an economic model designed in the 1970s.

Email, again

That is the gap SithBit was built to close, and it turns out the blockchain supplies the two things email always lacked. It can put a real, sender-paid, recipient-set price on a message — dismantling the economics of spam at the root instead of forever guessing at its symptoms. And it can carry identity and settlement with no company in the middle to own your address or read your mail — the Web 3.0 promise, finally delivered to the place it started.

A solution in search of a problem, meet a problem the world gave up on solving. The oldest killer app on the internet was, it turns out, waiting for the newest platform all along.

Welcome to email with postage.

Introduction

Spam isn’t a filtering problem. It’s an economics problem, and email has never fixed it. Sending mail costs a spammer essentially nothing, so even a 1-in-12,500,000 response rate still nets about $7,000 USD/day at scale. Multiply that incentive across the internet and you get the numbers today: an estimated 362 billion emails sent daily, with 45-60% of it spam. No amount of machine-learning spam detection can win that fight permanently — filters treat the symptom, and the number of spam emails keeps climbing precisely because the incentive to send it was never touched.

The same free-to-send flaw now powers something worse than junk. The FBI’s 2025 Internet Crime Report counts business email compromise — the “our bank details have changed” message — at roughly $3 billion in reported losses in a single year, and phishing as the most-reported crime of all. And the filters are losing faster than they used to: security vendors now report that most phishing mail is written by AI, with click rates that match a human expert’s. A filter judges the content of a message, and content is exactly what a machine can now make indistinguishable from the real thing.

A price is different. Postage doesn’t care how well the message is written. That’s the whole idea behind SithBit: it charges the sender, not the recipient, and lets you set the price — content-blind, so there is nothing for a better forgery to get past. And it does so without asking you to abandon email itself: the reference servers speak standard SMTP, IMAP, and POP3 to the letter, so your existing mail client just works. See Standards and RFC coverage for exactly which RFCs each server implements.

Sender-pays postage

In the earliest days of U.S. postage, letters were paid for by the recipient, and the system was so inefficient it collapsed under its own volume. Email never got past that stage — you still bear the cost of your inbox, either directly through a subscription or indirectly through the ads and data-mining that fund “free” accounts. Stamps fixed postal mail over a century ago by putting the cost on the sender instead. SithBit does the same for email, and takes it a step further: instead of one central post office setting one universal price, every mailbox owner sets their own price, per sender if they want to.

That single change is what makes spam uneconomical rather than merely harder to get away with:

• You price out spam, not guess at it. Every message to your mailbox costs the sender real SOL. A new mailbox starts at 1 SOL per message from anyone you haven’t priced yet — deliberately a wall, not a price list — and you lower it, per sender or for everyone, to whatever your attention is actually worth. Spam has to be profitable after your price, not just after a filter’s guess.
• Strangers pay; friends don’t. Each correspondent gets their own prepaid postage balance for mail to you (a “frombox” — see Fromboxes). Allow-listing someone just means funding theirs yourself: the protocol waives its fee on that purchase, and the value round-trips back to you as their mail arrives, so recognizing someone you trust is free beyond ordinary transaction fees.
• You only ever pay for mail you mean to send. As a sender, there’s no subscription and no ad-supported inbox trade-off — postage is the price of the message you chose to send, nothing more.

Get paid to be emailed

Postage from strangers doesn’t go to a provider. It goes to you.

• You keep roughly 90 % of it. When a message settles, the postage lands in your wallet; the operator whose domain carried it takes a 10 % share by protocol default (see Economics for the exact split). You’re compensated for the inbox space you were already defending, instead of paying a provider or letting them monetize your data.
• Advertisers pay you too — only if you ask them to. Publish a beacon naming topics you’ll hear about, and campaigns pay your postage to land in your inbox plus a bounty when you reply. You keep the postage whether or not you answer, and closing the beacon takes you out of the pool and returns its deposit.
• You can see what your inbox made. sithbit earnings is the read-only snapshot of what your wallet holds and has taken in.

Paid is delivered

The sender’s side of the bargain is just as real. The big mailbox providers now reject bulk mail outright unless it clears an authentication and complaint-rate bar, and even fully compliant senders watch a share of legitimate mail land in spam. Delivery has become a reputation lottery, and a whole industry sells tickets to it.

A funded frombox is not a lottery. If the sender has postage for you, the message is delivered and recorded on-chain — there is no reputation score in the path to lose. Two things make that safe rather than a spammer’s dream:

• Reputation lowers the price for the honest, not the wall for everyone. Under reputation-scaled first-contact pricing, a wallet that has paid and behaved pays less to reach someone new; a burner wallet pays your full default. An organization can go further and attest a verified sender — prove once, by DNS, who stands behind its wallet, and pay the floor price on first contact ever after.
• Campaigns reach only people who opted in. An advertiser can quote the whole campaign before a lamport moves, and every recipient is a real, funded wallet — a bot farm costs real SOL to build.

No token

If you’ve been anywhere near crypto, you already know the pattern: a project launches its own token, and your upside depends on a team you don’t control — one that can pre-mine a chunk for themselves, unlock more supply later, or simply walk away with the liquidity. SithBit doesn’t ask you to take that bet. There is no SithBit token. Postage, stamps, and every payout described above move in native SOL — the same SOL you already hold to pay transaction fees on Solana for anything else. No mint anyone controls, no allocation for insiders to dump, nothing to “rug”: if you hold SOL, you already hold everything the protocol needs from you.

Note — only on Solana: pricing every message individually only works if the settlement layer can keep up. To support even a small fraction of global email traffic, an on-chain mail system needs to clear millions of transactions per second — throughput only the Solana blockchain provides today.

Your address is yours, and your mail is sealed

Fighting spam with filters costs you twice over. Your provider has to open and read every message to classify it, so you’re trusting a third party with your mail’s contents — and increasingly they do more than classify: regulators have fined the largest provider for advertising inside the inbox without consent.¹ That provider usually also owns the domain your address lives on, so your identity on the internet is rented, not owned — and an automated “security hold” can take it away for days or months with no one to appeal to.

SithBit removes both dependencies:

• Your address is your wallet. It’s not tied to a domain someone else controls, so nobody can revoke it out from under you. It’s not permanently tied to any one domain either — you can move it to a different domain at any time, keeping your wallet, mail history, and identity intact.
• Your mail is sealed to your key. Message bodies are encrypted by the sender straight to your wallet and stored on the Interplanetary File System ( IPFS), so no central authority ever holds your mail in the clear — see IPFS storage: benefits to users. With Lockbox the seal is applied on your own device before a message leaves it, so even your operator only ever sees ciphertext. Taken together, two SithBit addresses can exchange mail using only the chain for settlement and IPFS for storage — bypassing the internet’s SMTP relay infrastructure entirely.
• We tell you exactly what’s public. The envelope — who mailed whom, when, and for how much — lives on a public ledger and is permanent. That is a real trade-off, and What’s public and private spells it out rather than hiding it.

Anyone with a domain can run one

SithBit isn’t a single proprietary email service with one company behind it — it’s a protocol. Running the mail servers (sithbitd, the combined SMTP/IMAP/POP daemon — see Running a mail server) takes no special permission: authorize your own domain on-chain, point its MX record at your server, and you’re a first-class mail operator on the same footing as anyone else on the network.

Hosting isn’t charity, either — it’s the third profitable role in the system, alongside senders and recipients:

• You earn a cut of every message you relay. For each mail settled on a mailbox under your domain, your operator wallet collects a share of that message’s postage — 10% by protocol default (see Economics for the exact split) — so the more mail your domain carries, the more it earns, turning what used to be a pure hosting cost into a revenue line that can offset it.
• No permission needed — a DNS record and 0.01 SOL. Authorizing a domain costs 0.01 SOL paid on-chain once, verified against your domain’s DNS TXT record. No central provider decides who’s allowed to run a mail server.
• Your outbound to other SithBit users never touches an IP blocklist. Self-hosting conventional mail has become effectively gated by IP reputation: a perfectly authenticated message from a rented server range is still refused on the address it came from. Mail between SithBit mailboxes settles on-chain and is stored on IPFS, with no IP reputation anywhere in the path; the domain’s on-chain authorization replaces the gatekeeper.
• Names are assets, not rentals. A domain authorization and an alias never expire and carry no renewal fee; both can be transferred, listed, or auctioned on the name marketplace, and the seller keeps 90% of the proceeds.

Find your path

Everything above serves one of four kinds of reader. Start where you fit:

• You want an inbox that pays you — Getting started claims a mailbox in five steps; Economics traces every lamport; What’s public and private and Lockbox cover what stays yours.
• You want to reach people who chose to be reachable — Fromboxes explains stamps and the price you are quoted; Campaigns is paid outreach to an opted-in audience; Verified-sender attestation earns your organization the floor price on first contact.
• You hold a domain or a name, and want it to earn — Running a mail server and Domains for operators; Aliases and Trading names for name owners.
• You’re building on it — the sithbit CLI is the whole protocol as typed commands; Program & PDA reference documents the three on-chain programs and every instruction; Standards and RFC coverage says what a conforming server speaks.

1. The same report describes tracking pixels and the regulator’s proposal that tracking needs a consent of its own. SithBit’s answers — a reader that never fetches the pixel, an on-chain delivery record in place of an open receipt, a reply bounty in place of an engagement score, and a beacon as separate, revocable consent to advertising — are taken point by point in Tracking pixels, consent, and the paid inbox. ↩

The Components at a Glance

From the outside, SithBit looks like ordinary email: you open a mail app, read what arrived, and write to people by address. Under the hood, four groups of pieces cooperate to make that work without a central provider:

• On-chain programs — the shared rulebook, living on Solana where anyone can read it.
• Servers — the post-office machinery that anyone with a domain can run.
• Graphical clients — the apps and extensions most people actually use.
• The command line and the console — terminal tools for developers and operators.

This page introduces each group in plain terms, then puts them together on one map. Nothing here is required reading to use SithBit — it’s the orientation tour, with links into the deeper chapters when you want more.

The on-chain programs — the shared rulebook

A blockchain “program” is a small piece of software that lives on the blockchain itself, where everyone can see it and no one can quietly change it. Think of it as a vending machine for rules: put in a correctly-formed request, and it does exactly what its published rules say — the same for everybody, every time.

SithBit is built on three such programs, running on Solana:

• The mail program is the heart of the protocol. It keeps the record of every mailbox and its prices, holds each sender’s prepaid postage balance (a frombox), and moves the SOL when a message is delivered — sender pays, recipient collects. It also hosts the postoffice, the one shared account that records protocol-wide settings.
• The alias program maps human-readable names (aliases) to wallet addresses, so mail can go to pat@example.com instead of a long string of characters.
• The domain program keeps the registry of domains whose owners have proven, via DNS, that they control the name — and runs the marketplace where aliases and domains are bought and sold.

Two things make this arrangement matter. First, everyone consults the same three programs — every server and every app, no matter who runs it, reads and writes the same shared record, which is what makes SithBit a protocol rather than a company. Second, your messages are not on the blockchain: the chain holds only small delivery records and balances, while the message body itself is encrypted by the sender and stored on IPFS, a distributed storage network. What’s visible to whom is laid out in What’s public and private.

The servers — the machinery an operator runs

The on-chain programs can’t answer a mail app’s call on their own — somebody has to speak the languages your mail apps already know. That somebody is a mail operator: anyone who owns a domain, authorizes it on-chain, and runs the SithBit services. The full set is described in Running a mail server; the short version:

• sithbitd, the mail daemon, is the big one. It accepts and delivers mail (SMTP), lets your apps read it ( IMAP and POP), and runs the behind-the-scenes workers that encrypt each message, store it on IPFS, and settle its postage on-chain.
• account-api handles sign-in and account settings — you prove you own your wallet, it hands your apps a session.
• mail-grpc is the operator’s gateway to the three on-chain programs: postage checks, delivery records, name lookups.
• domain-sithbit verifies domain ownership against DNS so a domain can be authorized on-chain.
• sithbit-ipfsd and sithbit-gateway are the IPFS storage plumbing — a shared storage node for a fleet of servers, and a read-only window for fetching stored mail over plain HTTP.

The crucial point for a newcomer: operators are interchangeable. Because prices, balances, and delivery records live in the on-chain programs rather than inside any operator’s database, no operator owns your identity or your mail. Operators compete to carry traffic — and earn a share of the postage on every message they relay.

The graphical clients — where most people live

Most people never touch a terminal or a server, and never need to. SithBit ships a family of GUI clients:

• The webmail app — a full mail client in your browser, installable as an app on desktop and phone.
• The Chrome extension, the Outlook add-in, and the Thunderbird extension — the same account tools, embedded in the mail software you may already use.

All of them run one shared core, so a screen behaves identically wherever you meet it — and everything that must be signed with your wallet key is signed on your device. The server only ever relays already-signed requests; it never holds your key. That shared core also includes the guided first-run wizard that creates or imports a wallet and claims your mailbox, and the browser name marketplace for buying and selling aliases and domains.

And because the servers speak standard mail protocols to the letter, any ordinary mail app works too: point your favorite client at a SithBit server over IMAP or POP and read your mail with no SithBit software installed at all. The GUI clients earn their place with the parts standard apps can’t do — wallet sign-in, pricing your senders, and trustless reading, where your browser checks the chain and IPFS directly instead of taking the server’s word for it.

The command line and the console — power tools

Two terminal tools round out the set, for the people who want them — typical users never need either:

• The sithbit CLI is the developer’s tool: the full protocol surface as typed commands. It talks directly to the on-chain programs — no SithBit server required — so everything from claiming a mailbox to pricing a sender to sending and reading mail can be done from a terminal. If you’re building on SithBit, this is your surface: the whole protocol is three small programs with documented instruction semantics, reachable from the CLI, its C library, the gRPC gateway, or WebAssembly in a browser — paid, spam-proof messaging between any two wallets, with standard email on the other end.
• The sithbit-console TUI is the operator’s dashboard: a keyboard-driven console for inspecting accounts and mailboxes, watching the mail queues, and unsticking failed jobs. It talks only to the account API’s admin surface, never to the operator’s database directly.

How the pieces fit together

Put the four groups on one map and the shape of the protocol appears. Follow a single message through it:

1. You write mail in a client — a GUI client or any standard mail app — and it hands the message to your operator’s sithbitd the same way email always has.
2. The servers do the protocol work: sithbitd checks through mail-grpc that the sender has postage for you, encrypts the body so only you can read it, stores it on IPFS, and records the delivery on-chain — the moment your postage is collected.
3. The chain and IPFS hold the truth: the mail program’s record says a message exists and was paid for; IPFS holds the sealed body. Any operator’s servers — or none at all — can show it to you from there.
4. You read it in whatever window you prefer: webmail, your usual mail app over IMAP or POP, the CLI straight from the chain, or trustless webmail verifying every step itself.

The division of labor, in one breath: the programs are the rulebook, the servers are the machinery, the clients are the windows — and because the rulebook is shared and public, the machinery is replaceable and the windows are many. Ready to go deeper? Start with Addresses for the core concepts, or jump straight to Getting started.

Standards and RFC coverage

SithBit reinvents email’s economics — sender-paid postage settled on-chain, addresses you own outright — but it deliberately reinvents almost nothing about the wire. Your existing mail client already speaks SMTP, IMAP, and POP3, and SithBit’s servers speak them back, to the letter of the specifications that have carried email for four decades. That is the whole point: you get a postage economy that finally works — spam, phishing, and deliverability priced instead of guessed at — without throwing away Thunderbird, Outlook, Apple Mail, or the mobile client already on your phone. Keep your client; change only who pays.

Standards-completeness matters more for email than for almost any other protocol. Email’s interoperability is adversarial — a message crosses servers written by strangers, in languages you’ll never see, and a single misread reply code or dropped capability turns into a silently lost message or an open relay. So the reference servers don’t implement “enough of” each protocol to pass a smoke test; they implement the published grammar, advertise exactly the capabilities they honor, and reject out-of-sequence commands structurally rather than hoping clients behave. Where a specification is only partially implemented, this page says so plainly in the Notes column — no overclaiming.

The tables below enumerate every RFC each SithBit server and subsystem implements, grouped by the component that owns it. Each links to the canonical text at the RFC Editor. If you are weighing a from-scratch server or an existing MTA against simply running sithbitd, this is the coverage you’d be matching — and if you are building a product on the protocol rather than a server, it is the guarantee that whatever you build talks to every mail client already in the world.

SMTP — sending and relaying mail

The SMTP surface is the sans-io smtp_session state machine (the wire grammar and its extensions) driven by the smtp_server binary (STARTTLS, SASL, delivery, and the SithBit sender-authentication policies). Enhanced status codes are structural: the class digit is derived from the reply code so a mismatch is unrepresentable.

IMAP — reading and managing mail

The IMAP surface is the sans-io imap_session semantics core over the typed imap-types AST, driven by imap_server over the imap-next flow layer. The baseline is IMAP4rev1; the rev2 extensions SithBit implements are advertised individually rather than by claiming rev2 as a whole.

POP3 — simple mailbox download

The POP3 surface is the sans-io pop3_proto typestate machine driven by pop_server. Commands invalid for the current session state are unrepresentable rather than merely rejected at runtime.

Authentication (SASL)

SASL mechanisms are shared by all three protocol servers through server_common. Wallet-signature SASL PLAIN is verified against the connecting address with no stored secret; CRAM-MD5/APOP serve clients limited to challenge-response.

The LOGIN mechanism (widely deployed, never standardized as an RFC) is also supported for legacy clients. DIGEST-MD5 and NTLM are deliberately dropped.

Message format and abuse-report handling

Message parsing and generation are adopted rather than hand-rolled — every consumer names one set of versions through mail_message, which itself owns only the RFC 5321 envelope layer (source routes, the null reverse-path, the domainless postmaster recipient) that the format crates don’t model.

Anti-abuse and transport hardening

Connection-level abuse policy, plus the TLS posture shared by all three servers (through the server_common acceptors) and the outbound relay.

Beyond these wire standards, the on-chain layer is where SithBit’s own contribution lives: the MailInstruction ABI, PDA derivations, and sealed-box encryption described in the Program & PDA reference and How sealed-box encryption works. Any server that speaks the RFCs above and those on-chain conventions is a first-class participant — see Protocol conformance for custom mail servers.

Addresses

An “address” is the public key portion of a Solana cryptographic key pair.¹ The public key is typically represented as a case-sensitive string about 45 characters in length .²

For example: 85FZrun1Eb5bdkbFCDjaFSTLnBfnx6sUFHa5BiYH2Q03.

Every SithBit client can create a key pair (also known as a “wallet”) for you: the getting-started wizard in your browser creates or imports one on its first step, and each of the GUI clients offers the same on first run.³

Once you create a keypair, the public key can serve dual purposes: it can be the source or target of cryptocurrency coin transfers, but can also act as an RFC822-compliant internet email address.

By default, a public key is not associated with an email domain until you create a mailbox for it — the getting-started wizard claims one in a single signed transaction, and every GUI client embeds the same wizard — or update its existing mailbox from the client’s Mailbox pane.⁴ Once you associate the public key with a domain, it becomes the case-sensitive “local” portion of the RFC822-compliant email address (i.e., the part of the address before the ‘@’ symbol, which separates the domain portion of the address).

For example: 85FZrun1Eb5bdkbFCDjaFSTLnBfnx6sUFHa5BiYH2Q03@sithbit.com

A domain is only required when email is routed through SMTP, but without a domain, emails can only be sent directly through the program, where both the “from” and “to” addresses are public keys without a domain portion of the email.

Trusting a “from” address

The “to” side of an email is always an on-chain wallet address, but the “from” side doesn’t have to be — it’s an arbitrary off-chain RFC822-compliant string (e.g. jane_doe@sithbit.com), which raises the obvious question: what stops anyone from sending mail claiming to be any “from” address they like?

• Only a recipient’s own domain authority can deliver into their mailbox. Every SendMail instruction requires the transaction signer to be the active, registered authority for the recipient’s (“to”) domain — the same wallet named in that domain’s on-chain MailDomain account. The comparison is part of the instruction itself, not an operator policy anyone can relax: a signer that doesn’t match is rejected (IllegalAuthority) and the whole transaction fails. This is not a check on the “from” domain — it’s what stops a stranger from injecting mail directly into someone else’s mailbox at all, regardless of what “from” address they claim.
• Domain authority is DNS-gated, not self-asserted. A domain’s authority is set either by the postoffice’s delegate directly, or (self-service) by the domain-sithbit service after it verifies a _solana.authority.<domain> DNS TXT record matches the claimed key — see Create a domain. Controlling a domain on-chain requires controlling that domain’s DNS, the same trust root traditional email anti-spoofing and anti-phishing defenses (SPF⁵/DKIM⁶) relies on.
• A domain-less from address must match the signer’s own wallet. If the recipient address has no @domain at all (a direct, unrouted on-chain send), the program instead requires the signer to be the exact address named in the “from” field — so a bare public-key “from” can only ever be sent by its own keypair. There is no relaying at all in this case.
• One MX relay signs as one set of domains. The gRPC gateway that submits SendMail on behalf of an MX server signs every transaction with a single configured keypair, so a given mail server deployment can only deliver into mailboxes on the domain(s) it actually holds the authority key for — it can’t inject mail into a domain’s mailboxes that it doesn’t operate.
• The “from” domain itself is not independently re-checked on-chain. Once a signer clears the checks above, the “from” string it submits is otherwise free-form (format-validated for length only). The chain trusts that the recipient’s own domain operator already verified the claim — which is exactly what SPF/DKIM/DMARC⁷ do, off-chain, before that trusted operator ever submits SendMail. An operator who has misconfigured that off-chain authentication — or turned it off entirely — is the actual point of failure for “from”-domain spoofing, not the on-chain program.
• Postage adds economic friction on top. Every send burns a stamp from a frombox keyed on (from string, recipient wallet), priced by the recipient — see Economics. This doesn’t block spoofing by itself, but it means even a fabricated “from” string costs the actual sender lamports, at a price the recipient controls.
• Inbound SMTP mail is checked with SPF/DKIM/DMARC before it ever reaches the chain pipeline — see Configuration for the operator settings that govern how strictly it is applied. This is the layer that actually authenticates a “from” domain’s claim; the chain only enforces who may deliver to a given recipient.
• Casing can’t be used to dodge any of the above. Domain names are lowercased both when a MailDomain account is created and every time one is looked up. Each operation that touches a domain — the delivery authority check, plus creating, transferring, deactivating and closing a domain — lowercases the name independently, so there is no path that skips the normalization and no caller who can opt out of it. SithBit.Com and sithbit.com are therefore the same account, and there’s no shadow-domain trick via casing. A frombox’s “from” key is normalized the same way — the domain half of a domain-qualified address is lowercased — so pricing set for jane@sithbit.com also applies to Jane@SithBit.Com. Bare wallet addresses are deliberately left case-sensitive, since a base58 pubkey’s case is part of its identity, not a stylistic variation.

What’s not enforced on-chain is the authenticity of the “from” domain itself, and the local part under any authorized recipient domain: a domain’s authority can write any “from” string it likes for mail delivered to its own mailboxes, the same trust a real domain’s mail server holds for traditional email — the protocol’s guarantee is that only a recipient’s own trusted operator can deliver to them, not that every “from” claim has been independently re-verified.

Since public key addresses usually appear as long random strings that are hard to remember, it is also possible to create one or more friendly aliases for an address via the alias program — the getting-started wizard claims your first handle as part of onboarding.⁸ Aliases are globally-unique identifiers for public key addresses. Once created, they represent public keys across all domains.

Instead of using 85FZrun1Eb5bdkbFCDjaFSTLnBfnx6sUFHa5BiYH2Q03@sithbit.com, you might create the alias myalias, and use myalias@sithbit.com as your public email address.

Unlike public key addresses, aliases are case-insensitive. So myalias@sithbit.com, MYALIAS@SITHBIT.COM, and MyAlias@Sithbit.com are all aliases for the same public key address.

1. A keypair (or “wallet”) in the Solana blockchain is specifically a public key and its associated private key derived from the ED 25519 elliptic curve. ↩

2. The 32 bytes of the key are base58 encoded to produce the string. ↩

3. Power users can also create one from the terminal with the SithBit CLI — see Creating a wallet. And since ED25519 key pairs are created by a publicly well-known algorithm used by multiple blockchains, there are actually many tools that can create them — including the Solana CLI’s own solana-keygen, if you already have it installed. ↩

4. From the terminal: Create a mailbox and Update a mailbox. ↩

5. For the formal specification, see RFC 7208 (Sender Policy Framework); dmarc.org’s overview explains how SPF, DKIM, and DMARC work together in practice. ↩

6. For the formal specification, see RFC 6376 (DomainKeys Identified Mail). ↩

7. For the formal specification, see RFC 9989 (Domain-based Message Authentication, Reporting, and Conformance), which obsoletes the earlier RFC 7489; its reporting halves are specified separately, in RFC 9990 (aggregate, rua) and RFC 9991 (failure, ruf). dmarc.org also has practical deployment guidance. ↩

8. Registering additional aliases (and transferring them) is CLI territory today — see Create an alias. ↩

Mailboxes

What is a mailbox

A mailbox is an account on Solana that stores email settings for an address. An address must have an associated mailbox created before participating in the email system, and an address can only have one mailbox.

Every GUI client shows a mailbox’s settings in its Mailbox pane — see the webmail, Chrome, Thunderbird, or Outlook client pages.¹

Mailbox settings

A mailbox holds the following settings:

• Mail count. The total number of emails sent to the mailbox since it was created.
• Default Postage. The default price of a stamp in lamports to send an email to the mailbox. When you create a new frombox, this value is used initially for the stamp price for the frombox unless otherwise specified. New mailboxes start at 1 SOL: deliberately a wall that keeps spam, phishing, and every other free-to-send abuse out, which you then lower — per sender, or for everyone — to what your attention is actually worth. Strangers pay it and you keep roughly 90%; senders you fund yourself write for free.
• Domain. The program address that represents the internet domain associated with the mailbox. You can change the domain for your account at any time, but in order for email to be properly routed to your mailbox, the owner of the domain must have registered the domain with the email program. In addition, the domain must host MX servers that support the email program protocol.
• No IPFS. Whether the owner has opted out of public IPFS body storage — see IPFS storage: benefits to users. When enabled, delivered bodies are kept in the operator’s own store and the on-chain message carries a local-only marker instead of a fetchable CID. Defaults to disabled.²
• Funder. The wallet that paid the mailbox’s rent: yourself on a normal create, or the sponsoring domain authority on a sponsored create. When the mailbox is closed (every GUI client has a Close-mailbox action³), its rent refunds to the funder — and only ever the rent, because a mailbox never accumulates earnings (stamp value settles from the sender’s frombox through the message account to you on delete).

Creating a mailbox also claims an alias

Creating a mailbox does one more thing besides writing these settings: it automatically registers your wallet’s own address string as a self-alias pointing back at you. That claim is a namespace reservation: aliases are one global, case-folded namespace, and the self-alias takes your address’s spelling out of it so nobody else can ever hold a name that reads as your wallet. It is not what routes your mail — every SithBit resolver treats a string that is a wallet address as that wallet before it consults the alias registry at all, so an alias registered under an address’s spelling never redirects mail sent to the address. See Aliases for the resolution rule from the alias side, including why most users never need to register an alias by hand.

Sponsored mailboxes: a domain provisions for its users

Normally the wallet that signs a mailbox create is the wallet the mailbox belongs to. A domain’s on-chain authority may additionally provision a mailbox for a different owner — an employer setting up receiving mailboxes for its staff’s wallets under the corporate domain before those wallets have ever transacted. Three guards keep this from becoming a spam or squatting vector:

• Only the named domain’s registered on-chain authority may pay for another owner’s mailbox; anyone else is refused.
• The new mailbox’s default postage is forced to the 1-SOL spam floor, whatever the sponsor asked for — a sponsor cannot open cheap send channels into a stranger’s mailbox. The owner lowers prices for known senders afterwards, exactly as with a self-created mailbox.
• No self-alias is bundled (the sponsor must not squat the owner’s address string); the owner claims their own alias when they first act.

The sponsor is recorded on-chain as the mailbox’s funder, and closing the mailbox refunds its rent to the sponsor rather than the owner. In every other way the mailbox belongs wholly to the owner from the moment it exists: the sponsor keeps no control over it.⁴

Opting out of IPFS storage

A mailbox’s no-IPFS setting (above) is off by default, meaning delivered bodies are pinned to public IPFS and the on-chain message carries a fetchable CID. Turning it on is a deliberate trade: your operator keeps the sealed body in its own store instead, and decentralized clients like the trustless viewer can no longer read it — availability then depends entirely on that one operator. See IPFS storage: benefits to users for the full trade-off, and Create a mailbox or Update a mailbox for how to set it.

Mail is sealed to your wallet by default

Mail bodies are encrypted before they are pinned to IPFS, so that only the mailbox owner can read them, and this needs no setup at all by default. A wallet address is an Ed25519 public key, and its X25519 twin is a valid encryption key: mail servers seal every message straight to the recipient’s wallet address as a libsodium sealed box — no published key, no key account, no rent. See Appendix: How sealed-box encryption works for a full walkthrough of the protocol, with diagrams. Decrypting is just a matter of having the wallet keypair file.

Hardware and browser wallets are the exception: they only sign, and never reveal the secret needed to derive the wallet’s decryption key. Such users instead generate a delegated X25519 keypair client-side and publish its public key on-chain as an optional mailbox setting; mail servers then seal to the published key instead of deriving one from the wallet address, and the delegated key file (not the wallet keypair) opens the mail. Every GUI client’s Encryption-key pane publishes, rotates, and clears the delegated key — see the Chrome or Outlook client pages.⁵

1. From the terminal: Looking up a mailbox. ↩

2. Set it at create or update time from the terminal: Create a mailbox or Update a mailbox. ↩

3. From the terminal: Close a mailbox. ↩

4. Sponsors are typically domain operators scripting provisioning — see Create a mailbox — sponsored creation for the command. ↩

5. From the terminal: Mailbox keys. ↩

Fromboxes

What is a frombox

A frombox is an on-chain account for one (sender “from” address, recipient “to” wallet) pair. It holds a prepaid balance of “stamps” and the postage price of a single stamp — sending one email always costs exactly one stamp, so this is the per-email price for that particular sender writing to that particular recipient. Where a mailbox is 1:1 with a recipient, a frombox is 1:1 with a specific sender-recipient relationship — the same mailbox owner can have a different frombox (and a different stamp price) for every sender who writes to them.

Every GUI client’s Balances pane shows your fromboxes’ prices and stamp balances — see the webmail, Chrome, or Outlook client pages.¹

Default postage and pricing

New, never-before-seen senders don’t have a frombox at all: the recipient’s mailbox default postage (also a per-stamp price) applies instead, and that default is normally set high specifically to price out spam from unknown senders. Once a recipient knows and trusts a sender, they create a frombox for that sender and set a lower, negotiated stamp price.

The default is not entirely one-size-fits-all, though: a sender wallet with a real on-chain track record — cumulative postage spent reaching other recipients, or a verified-sender attestation from its domain — pays a scaled share of the default at first contact, down to a tuned floor. Spam economics are unchanged (a burner wallet has no record and pays full price), and a price the recipient sets is never scaled — see Reputation-scaled first-contact pricing.

The anti-spam lever

A frombox’s per-stamp price — the required_postage a sender pays for each email — is the recipient’s core lever against spam and phishing alike: a price is content-blind, so there is nothing for a better-written forgery to get past. A freshly created frombox inherits the recipient’s mailbox’s high default price (1 SOL on a new mailbox — a wall, not a going rate), and the recipient can drop it for a sender they trust, or raise it — even above the mailbox’s own default — for one who has become a nuisance. Friends are free: when the recipient funds a correspondent’s frombox themselves, the per-stamp protocol fee is waived and the value round-trips back as that correspondent’s mail arrives.

Only the recipient can change this price: the update must be signed by the recipient (“to”) keypair, and the on-chain program checks that signer against the mailbox owner, so a sender can never discount their own postage.

That same ownership underpins an owner exception: normally opening a brand-new, empty frombox with zero stamps is refused (see the prepayment rule below), but the recipient may set a price for a sender’s frombox before that frombox — or any purchase from the sender — exists at all. Because the signer setting the price is the mailbox owner, the on-chain guard allows this one stampless create; a third party can never open an empty frombox this way. The frombox starts at the recipient’s chosen price with zero stamps, so the sender still can’t reach them until it holds at least one stamp, funded by either side.

Reprice a sender from your client’s Balances pane — see the webmail or Outlook client pages.²

Prepaying with stamps

Stamps are the currency of delivery: sending one email always burns exactly one stamp, so a frombox with no stamps left can’t receive mail from that sender until it is topped up. Buying stamps prepays postage into a frombox, creating the frombox on the spot if it does not exist yet: a newly created frombox always inherits the recipient’s mailbox’s current default postage as its per-stamp price — the deliberately high value that prices out spam. Buying stamps never sets a custom price on its own; giving a trusted sender a cheaper rate is a separate step, done either afterwards or up front, as described in the anti-spam lever above.

This first-purchase behavior is bounded by the prepayment rule: a third party — a sender funding their own frombox to someone else, or anyone other than the recipient — must buy at least one stamp on that first purchase. An on-chain guard refuses a zero-stamp create from a non-owner payer, so a spammer cannot litter the chain with empty fromboxes for free — for anyone but the recipient, opening one always costs at least one stamp of postage. The only way to open a stampless frombox is for the recipient to do it while setting the price, as described above.

Buy stamps from your client’s postage form — the webmail Balances pane, the compose card’s inline prepay when a send is refused for stamps, or the self-service funding page a refusal reply links you to.³

The price you are quoted is the price you pay

A recipient can reprice a sender at any time, so the rate you were shown is not guaranteed to still be the rate when your purchase lands. Every purchase therefore carries a price ceiling: the per-stamp figure the client quoted you. If the price has moved above it in the meantime, the program refuses the purchase instead of charging you the new rate, and you can re-quote and decide again.

The ceiling is read fresh at the moment you buy, not when the quote was displayed — so it holds even if you left the page open, and it applies whether or not you asked for a quote first. It covers only the per-stamp postage; the protocol fee, the settlement surcharge and the one-off account rent are set by the protocol rather than the recipient, and cannot move under you the same way.

Getting unspent postage back

Prepaid postage is a deposit, not a payment: until a stamp is actually spent on a delivery, the lamports behind it are still sitting in the frombox. Two people can take them back out, and which one you are decides how.

The recipient can close the frombox outright, which reclaims the whole balance — the rent they put up plus whatever stamp value is left. That is their remedy against a sender who stockpiled cheap stamps before a price rise.

The sender can withdraw their own unspent postage without disturbing the account, provided the frombox is keyed on their wallet address rather than an email address. The stamp count drops to zero, the lamports return to the sender’s wallet, and the frombox stays open at the price the recipient set. A frombox keyed on an email string hashes text no wallet key can reproduce, so it has no sender-side withdrawal and stays the recipient’s to close.⁴

Withdraw from the webmail Balances pane: quote the recipient you prepaid, and a Reclaim unspent button appears beside the buy buttons once the frombox is shown to hold stamps. The button is offered only when you are sending as your own wallet address, because that is the only frombox the withdrawal can address — send as an alias or an email address and it is simply not there, rather than there and failing.

Because the recipient’s close still sweeps any residual left behind, the sender’s withdrawal is a way to move first, not an exclusive claim — see frombox custody for the reasoning behind that ordering.

1. From the terminal: Looking up a frombox. The CLI additionally annotates prices with a best-effort USD value (fail-soft — a rate-API outage just drops the annotation), mirroring sithbit earnings. ↩

2. From the terminal: Update a frombox. ↩

3. From the terminal: Add stamps. ↩

4. From the terminal: Reclaiming unspent stamps. ↩

Aliases

An alias is a short, human-readable name — like john_doe — that resolves to a wallet address, the same way a person’s name in your phone’s contacts resolves to a phone number. Aliases are globally unique across the whole system (not per-domain), case-insensitive (John_Doe and john_doe are the same alias), and are lowercased and stripped of any domain suffix at creation. An alias is yours outright: it never expires and carries no renewal fee, and it is a transferable on-chain asset you can sell — through an escrowed offer, a fixed-price listing, or an auction — keeping 90% of the proceeds (see Trading names). Short names are explicitly scarce: there will only ever be 36 one-character aliases, and the one- to four-character tiers carry scarcity-priced claim fees. See Addresses for how aliases fit into the address system as a whole.

Note: creating a mailbox automatically registers your wallet’s own address string as an alias for you. This is a namespace reservation: the alias namespace is global and case-folded, and the self-alias keeps anyone else from holding a name that reads as your wallet. It is not what protects your mail — resolution is literal-first: a string that already is a wallet address names that wallet, full stop, and the alias registry is only consulted for text that is not an address. So an alias registered under an address’s lowercased spelling can never redirect mail sent to the address, whether or not the owner claimed the self-alias. Most users never need to create an alias by hand — the getting-started wizard claims an optional friendlier handle as part of onboarding, and every client’s Aliases pane lists the names pointing at your wallet.¹

One namespace, and why

There is exactly one alias namespace, and it is domain-blind: any @domain suffix is parsed off and discarded before resolution, so alice, alice@acme.com, and alice@anything.example all resolve to whoever holds the global alice. Assigning your address to a domain binds which MX relays your mail; it confers no claim on any name. Only you can repoint a name you hold.

That is a deliberate guarantee, not a simplification. Because lockbox sealing follows resolution in the sender’s browser, anyone who could redefine which wallet an address names would thereby choose which key a sender seals to — reaching inside an end-to-end-encrypted body. Keeping one holder-controlled namespace is what forecloses that.

Issuing addresses to an organization’s staff therefore works by handing over real ownership rather than by carving out a suffix: reserve the names in bulk with alias create, then transfer each to its holder — a two-party consent hand-off, after which the employee holds the name outright and the organization cannot silently take it back.

Listing all aliases (the alias indexer)

Alias names are not recoverable from chain state: an alias account stores only the holder’s address, and the name itself exists on-chain only as a blake3 hash inside the PDA seed. “Which aliases point at wallet X?” is therefore answered by the gRPC gateway (mail-grpc), which maintains an off-chain index of the alias program’s transaction history — every Create/Transfer/Close instruction carries the plaintext name — and serves it through the ListAliases RPC.

• Names are returned in their canonical (lowercased) form, sorted.
• The index lives in a local SQLite file beside the gateway — the operator chooses its location, and an operator who doesn’t want the feature can turn the indexer off entirely — and is fed by polling the chain every few seconds.
• On first start the gateway backfills the program’s full history; ListAliases answers UNAVAILABLE until that backfill completes, and restarts resume from a stored cursor instead of re-scanning.
• The index reads at finalized commitment, so a freshly created alias appears after finalization plus one poll interval.

Transferring an alias

Moving an alias to a new wallet is a deliberate two-party consent ceremony — the current holder initiates the offer, and it only changes hands once the named recipient separately accepts — never a unilateral push. See Trading names: aliases & domains for the escrowed-transfer-for-a-fee marketplace mechanics.

Selling an alias

A listing is a different disposal mechanism from a transfer: it puts the alias up at a fixed price that whoever pays first takes, rather than a transfer’s negotiated two-party consent naming one specific recipient. An auction is a third option: instead of one fixed price or one named recipient, buyers bid the price up over a window and the high bidder wins at the deadline. See Trading names: aliases & domains for the full marketplace mechanics — listings, auctions, and escrowed transfers alike.

1. From the terminal: Create an alias registers additional aliases, Get an alias looks one up, and Transfer an alias moves one to a new address. ↩

Domains

What is a domain

A domain is a claimed, protocol-authorized mail suffix — like sithbit.com — that a mailbox references so that MX servers know how to route mail to it over SMTP. Domains are registered and administered on-chain: someone must claim a domain and have the postoffice’s delegate authorize it before mailboxes on that domain can send or receive mail through the normal MX/SMTP path. The whole domain registry — the domain accounts, their lifecycle, and the marketplace — lives in its own dedicated on-chain domain program.

A domain is also the operator’s revenue line: its authority collects 10% of the postage on every message settled to a mailbox under it (protocol default — see Economics), plus a share of stamp fees and reply bounties. Authorizing one costs 0.01 SOL once, proven by a DNS record rather than granted by a gatekeeper, and the authorization never expires. Mail between SithBit mailboxes settles on-chain and is stored on IPFS, so your outbound to other SithBit users never touches an IP blocklist — the reputation gate that keeps most self-hosted mail out of conventional inboxes.

The marketplace web page shows the domains listed for sale, and each client’s Domains pane shows the ones your wallet holds.¹

Active and inactive domains

Every registered domain is either active or inactive. An active domain is fully usable: mailboxes may register against it, and mail may be sent to or deleted from mailboxes that reference it. An inactive domain — one whose deactivation has been finalized — blocks both: it refuses new or updated mailbox registrations, and it blocks sending and deleting mail for the mailboxes that already reference it. A mailbox’s domain must be a registered, active domain (or no domain at all), so deactivating a domain locks it down from new registrations too, not just mail flow.

Who can create a domain

Claiming a domain involves up to three distinct roles, and signing authority over each is separate from the others:

• Authority — the mail server’s signing key for the domain. SendMail into a mailbox is only accepted when the transaction signer is the recipient domain’s recorded authority, and that authority collects the operator share of DeleteMail settlement — 10% of postage by protocol default (see Economics). Transferring, deactivating, and closing a domain are delegate operations, not authority ones — holding a domain’s authority key lets you operate mail for it, not dispose of it.
• Delegate — must always sign a domain’s creation; only the postoffice’s standing delegate can authorize a new domain. A signer that isn’t the delegate is refused outright.
• Payer — funds the new account’s rent; defaults to the delegate when no separate payer is given.

Domain identity is scarce and protocol-wide in a way a mailbox or alias isn’t: claiming sithbit.com grants standing to receive mail for an entire suffix, so the postoffice — not any individual key holder — decides who gets to claim it, which is why the delegate’s signature is mandatory even though the authority and payer roles are flexible. Because domain accounts are keyed by the domain name alone rather than by who created them, one authority key can still hold any number of domains: a mail-server deployment serving several domains registers each of them with the same authority key.

Asking the delegate holder to sign by hand isn’t the only route to authorization, though — see DNS setup for a self-service alternative that proves domain ownership instead.

Deactivating a domain isn’t instant

Deactivating a domain blocks sending and deleting mail for every mailbox that references it, and it also blocks new mailbox registrations against that domain — a network-wide halt for everyone whose address lives on it. Because that’s such a disruptive action, the protocol never lets it happen with a single signature. Instead it runs on a deactivation timelock: a waiting period between the moment deactivation is requested and the moment it actually takes effect. The domain stays fully active — mail keeps flowing normally — for the entire window.

The point of the wait is to give everyone with a stake in the domain a chance to notice and object before the cutoff lands. The delegate is a single hot admin key (see the threat model), so a compromised or coerced delegate that could deactivate a domain instantly could take its relayed mail down without warning. Splitting the action into a request that only starts a clock, followed by a separate step that finalizes it, turns that into a notice-and-veto window: the domain’s authority, or anyone else monitoring delegate activity, sees that deactivation is pending and has time to intervene — including cancelling the request outright — before it ever affects mail flow. Reversing course in the safe direction, reactivating a domain, is never subject to this delay; only the destructive direction is.

While a domain is in this state it is described as having a pending deactivation: the request has been made and the clock is running, but the domain itself is still active in every respect until the waiting period elapses and the deactivation is carried through. A pending deactivation can still be called off before that happens, which simply cancels the clock and leaves the domain untouched, as if nothing had been requested. Because deactivation reaches every mailbox on the domain at once, requesting, finalizing, and cancelling it are all delegate-only actions, the same standing authority that must approve a domain’s creation in the first place.

Requesting, finalizing, cancelling, and reversing a deactivation are delegate operations run from the terminal.²

Transferring a domain

A domain’s authority is the key that mail-serving control belongs to: it’s the only signer SendMail into a mailbox on that domain will accept, and it’s the key that earns the operator’s share of settlement when mail is deleted (see Economics). Transferring a domain reassigns that one role to a different wallet — nothing else about the domain moves. The domain’s name, its active/inactive status, and every mailbox that already references it are all untouched by a transfer: mail keeps flowing under the new authority exactly as it did under the old one, without interruption and without any mailbox needing to re-register.

Because a domain’s authority is a role over a shared, protocol-scarce resource rather than personal property, the current authority holder cannot simply hand it off unilaterally — the same standing that must approve a domain’s creation is required to reassign it. See Who can create a domain for why that authority is concentrated in the postoffice’s delegate rather than left to individual key holders: transferring a domain is a delegate-only operation for exactly the same reason creating one is.

Reassigning a domain’s authority is likewise a delegate operation run from the terminal.³

What buying a domain does — and does not — buy

A domain can also change hands on the open marketplace rather than by delegate-signed transfer. For how that sale is priced, timed, and settled — listings, the binding window, the 90/10 split — see Trading names: aliases & domains; this section covers only what a purchase conveys, not how the sale itself works.

A marketplace domain sale conveys protocol authority, nothing more. Concretely, the buyer’s wallet becomes:

• The domain’s mail-injection key. SendMail into a mailbox on the domain is only accepted when the transaction signer is the domain’s recorded authority — buying puts that signing right, the on-chain half of running the domain’s inbound relay, in the buyer’s hands.
• The domain’s settlement collector. The buyer earns the operator share of every DeleteMail settlement (see Economics) for mailboxes on the domain from that moment on.

It does not convey anything off-chain:

• Not DNS. The DNS name is owned at the registrar, entirely outside the protocol; a sale never moves it. Whoever holds the registration keeps the zone — the MX records, the _solana.authority.<domain> TXT record, all of it.
• Not hosting. No MX server, sithbitd deployment, or IPFS infrastructure changes hands.
• Not DKIM. Signing keys live in the operator’s DNS zone and filesystem, never on-chain.

A buyer who wants to operate the domain — actually receive its mail, not just collect its settlement share — must separately obtain the DNS name (or the cooperation of whoever holds it) and stand up their own MX. Do that diligence before paying: the on-chain state is easy to check,¹ but only the DNS zone shows who controls the name itself. For what can go wrong when on-chain authority and DNS ownership sit in different hands — lockouts, proof replay, and authority drift — see The marketplace sells protocol authority; DNS remains separately owned in the threat model.

Buy a listed domain from the marketplace web page’s For-sale tab, and list your own from its listing form or your client’s Domains pane.⁴

1. From the terminal: Looking up a domain inspects any domain’s registration and status. ↩ ↩2

2. See Deactivating a domain for the commands. ↩

3. See Transferring a domain for the command. ↩

4. From the terminal: List a domain for sale covers sithbit domain sell/buy. ↩

Authorize a domain by proof

Every SithBit domain is really a DNS domain — the same name that shows up in a browser’s address bar, governed by the same domain-name system the rest of the internet already answers to. Normally, claiming that identity on chain means asking the postoffice’s delegate to authorize it by hand: a human administrator has to trust that you actually control the domain and sign a transaction saying so. See Who can create a domain for that delegate-signed path.

There’s a second option: prove it yourself, and skip the administrator entirely. If you already control a domain’s DNS records, you can generate a cryptographic proof that shows exactly that — and the chain checks the proof itself, on the spot, rather than trusting a human’s say-so. No delegate signature is needed, and the proof doesn’t even have to be submitted by you personally: whoever ends up holding it can send the transaction (and pay for it), because the proof itself carries the authority, not whoever happens to click submit.

This works because SithBit treats DNS as the ultimate root of trust for who owns a name. On-chain possession of a domain is never final or self-sufficient on its own — it always answers to whoever genuinely controls the domain in the real DNS system. That cuts both ways: if a domain’s on-chain record ever falls out of sync with reality — after a change of hands at the registrar, say, or a stale claim left over from before — the domain’s rightful DNS owner can prove control again and reclaim the on-chain authority outright. The chain defers to DNS, not the other way around.

For the cryptography under the hood — how the proof is built, staged, and verified on chain, and the exact commands to run — see Authorize a domain by proof.

Verified-sender attestation

Every message a wallet sends is signed, but a signature only proves which wallet sent it — not who stands behind the wallet. For an organization that sends mail at any scale (receipts, notifications, a newsletter), that gap is a credibility problem: nothing on chain connects its sending wallet to the name its recipients actually recognize — and the same gap is what invoice fraud and lookalike-sender phishing live in, where a message that reads like the real company asks for a payment to go somewhere new. A verified-sender attestation closes the gap. It is an on-chain record in which a DNS domain vouches for a wallet address as a legitimate sender — “acme.com stands behind this wallet” — and anyone, MX operator or mail client alike, can look the binding up and verify it.

The vouching works the same way authorizing a domain by proof does: whoever controls the domain’s DNS generates a cryptographic proof of that control, and the chain checks the proof itself, on the spot — no administrator signs anything, and no delegate is in the loop. The organization proves domain control once, pays a one-time fee, and the attestation stands until revoked. The cost sits entirely on the sender’s side, matching the protocol’s positioning everywhere else: senders pay to be credible, recipients never pay anything. For a legitimate organization the payoff is delivery on its own terms — prove you’re you once, and pay the floor price on first contact under reputation-scaled pricing instead of a stranger’s full default, with no mailbox provider’s reputation score standing between you and the inbox.

An attestation is deliberately less than domain authorization, and independent of it. It confers no serving rights: an attested wallet gains no ability to route, inject, or operate mail for the domain, and the domain itself gains no standing as a mail suffix. It is a freestanding record — a domain that has never been registered as a SithBit mail domain at all can still attest its sending wallets, because attesting requires only proven DNS control, not an on-chain domain account. And it is not exclusive: a domain may attest any number of wallets, one record per (domain, wallet) pair, each independently revocable.

The fee is a flat, one-time charge to the postoffice — 0.01 SOL by default, tunable by the delegate up to a hard on-chain cap of 0.1 SOL (see the tunable-constants table). A proof that fails to verify charges nothing.

Revocation belongs to the attested wallet itself: it can close its own attestation at any time and reclaim the record’s rent. No other key — not even the domain’s — can reach the record, because its on-chain address derives from the attested wallet.

Since v0.39.0 an attestation also buys a concrete economic advantage: reputation-scaled first-contact pricing prices an attested sender’s first contact with any stranger at the discount floor immediately — the cheapest rate any reputation earns — instead of the mailbox’s full default postage. Proven domain control substitutes for a long postage spending record; a recipient-set price is never affected.

The binding is otherwise consumed from the terminal and by servers: the read-only sithbit domain attestation lookup and the gateway’s GetSenderAttestation call answer “is this wallet attested for this domain, and since when”. A verified-sender badge in the mail clients is planned but has not shipped yet.

For the commands — attesting, looking a record up, revoking, and tuning the fee — see Attest a verified sender.

Email

This section covers the mechanics of the mail operations themselves — sending, getting, pinning, and deleting a message, plus the reply-bounty incentive that rides on top of a send — as they happen against the chain and IPFS. In everyday use your mail client performs these for you; this page is for understanding exactly what happens underneath.¹ See Addresses for how wallet addresses double as email addresses, and Economics for the money side.

“Pinning”, in plain terms: IPFS keeps a message body only while some computer on the network has agreed to hold a copy — agreeing to hold one is called pinning it, and releasing it is unpinning. Who holds that copy, and how to add one you control, is explained for non-technical readers in What does pinning mean?

The split model: body off-chain, envelope on-chain

A SithBit message is deliberately split in two so that nothing sensitive and nothing large ever touches the chain:

• The body lives on IPFS. The message body (headers, subject, and text) is sealed to the recipient’s encryption key and pinned to IPFS as an opaque blob. It is content-addressed: the blob’s hash is its address, its content identifier (CID).
• The envelope lives on-chain. Only a small envelope goes on-chain as a SendMail instruction — the sender, the recipient, a timestamp, and that CID. The chain never sees the plaintext, and never stores more than a hash and a pointer, so on-chain cost stays flat no matter how large the mail is.

Because the CID is a hash of the sealed bytes, the two halves are tamper-evident against each other: given the on-chain CID, anyone fetching the body from any IPFS source can hash what they got and confirm it is exactly the body the sender committed to. Nothing else can hash to that CID.

The lifecycle of a message

The end-to-end path, from a sealed compose to the settling delete:

1. Send (figure steps 1a–1c) — seals the body, pins it to IPFS, and writes the envelope (with its CID) on-chain via SendMail. Postage — the frombox price for that sender, or the mailbox default — gates whether the send is allowed at all, and the postage the sender pays funds the new message account.
2. Get (figure step 2) — reads the on-chain envelope, fetches the sealed body from IPFS by its CID, and decrypts it with the recipient’s wallet (or a delegated key).
3. Pin (figure step 3, optional) — re-pins a verified body to a pinning provider the recipient controls, so a message stays retrievable even if the operator that originally pinned it stops.
4. Delete (figure step 4) — settles the message: it pays the postage out (to the recipient, with a share to the domain operator), refunds the prepaid fees, and reaps the on-chain message account so its rent is returned.

Deletion is the settlement trigger, not just a cleanup step — a message account holds the sender’s postage until it is deleted. See Deleting mail and Economics for the exact split.

Note: in normal operation, MX/SMTP servers and your mail client handle sending and receiving mail for you — see Running a mail server. The operations documented here talk to the chain and IPFS directly, which is useful for testing, scripting, or understanding exactly what a mail server does on your behalf.

Sending mail

The send operation records a delivery on-chain: it burns one stamp from the sender’s frombox and writes a new message account for the recipient pointing at the body’s IPFS CID. It does not move any bytes around — the encrypted body must already exist on IPFS. This is the low-level primitive an MX server runs on the sender’s behalf after it has sealed and pinned an incoming message; end users normally send through an ordinary mail client, not this command.

Want a faster answer? Attach a reply bounty and put SOL behind your question — the recipient collects it the moment they reply, no separate escrow to set up. See Reply bounties for the full mechanics.

See Sending mail for the full command reference, its preconditions, and what reaches the chain.²

Reading mail

The get operation is the receive side of send: it reads a mailbox’s message accounts from the chain, prints their on-chain listing, and — when a body is fetched — pulls the encrypted bytes from an IPFS gateway and (optionally) decrypts them with your key. It is the primitive an IMAP/ POP server runs to materialize a mailbox; end users normally read mail through an ordinary client rather than this command. Reading is read-only: a get never signs a transaction and never settles postage — that is delete’s job.

See Getting mail for the full command reference, the on-chain listing format, and decrypting a fetched body separately.

Pinning to IPFS

A message body never lives on-chain — only its content identifier (CID) does. The bytes live on IPFS, pinned by whichever mail server received the message. That is convenient, but it means the availability of your own mail depends on an operator continuing to pin it. If that operator stops — or you simply want to hold your own copy — you can pin the body to a provider you control. That is what the pin operation does: it fetches each message body, proves it against the on-chain CID, and re-pins the verified bytes somewhere of your choosing, so the mail stays retrievable no matter what the operator does.

See Pinning mail for provider choices, message selection, keeping mail pinned continuously, and the verify guarantee.

Deleting mail

Deleting a message is how a received email is settled and its on-chain account reclaimed. A mail message lives on-chain as its own account — a small envelope (sender, recipient, timestamp, and the IPFS CID of the sealed body) funded with the postage the sender paid to deliver it. That account sits open until someone deletes it. Deletion is the single event that pays the postage out, refunds the prepaid transaction fees, and closes (reaps) the message account so its rent is returned rather than left locked on-chain forever.

See Deleting mail for who may delete, the exact settlement order, and the delete-vs-refund distinction.

Reply bounties

A reply bounty turns postage’s pay-for-attention into pay-for-an-answer: the sender escrows extra lamports on the message itself, and the recipient collects them by replying before a deadline. No reply by the deadline and the sender takes the money back. The bounty rides the message account — there is no separate escrow account to create, fund, or clean up.

Attach a bounty from the compose card in any GUI client, and claim or refund one from its Bounties pane — see Replying, and attaching a bounty.³

1. The sithbit CLI drives each of these operations directly from the terminal; each section below links its full command reference. ↩

2. End users normally never run these commands — an ordinary mail client and its MX server perform the same operations on your behalf. ↩

3. From the terminal: Reply bounties covers attaching, linking a reply, and claiming or refunding. ↩

Do not disturb

A SithBit account can carry an away schedule — do-not-disturb windows managed through any of the GUI clients (or the account service directly) and evaluated in the account’s own timezone. While a window is active, the recipient’s sithbitd does something deliberately different from the classic vacation autoresponder: it refuses the mail up front, at RCPT time, with a transient 450 4.2.1 — instead of accepting the message and firing an “I’m away” reply back at the sender.

450 4.2.1 Recipient alice is away (do not disturb); try again later

That one design choice does most of the work of this page, so it is worth spelling out.

Why refuse instead of autoreply

• The sender’s mail server does the waiting. A 450 is SMTP for “not now”: the sender’s MTA queues the message and retries on its own schedule, transparently, for days. When the away window ends, the queued mail simply arrives — the sender resends nothing and installs nothing. An autoresponder cannot offer this; it accepts the mail and leaves the sender to guess whether anyone will read it.
• Nothing piles up while you are away. Accept-and-autoreply means coming home to a stack of stale unread mail — and, on SithBit, to a stack of postage decisions with it, since every delivered message carries prepaid postage that settles when you delete it. It also means the pile is there, one login away, for the whole vacation. Refusing at the door keeps the mailbox genuinely quiet: no backlog to triage on return, and no temptation to “just check” business mail from the beach.
• The sender learns at send time. An autoreply may arrive, may be eaten by a spam filter, or may never have been configured — the classic bounce-or-silence lottery. A refusal reaches the sender through their own mail server’s queue notice the moment they send, while the message is still fresh in their mind.
• A refusal costs the sender nothing. The refusal happens before the message is accepted, so no stamp is burned and nothing needs refunding. (The postage gate still runs first — the away check only fires for a sender who could otherwise deliver.)

Two honest caveats. The schedule lives in the operator’s account store and is enforced by the recipient’s sithbitd — this is server-side behavior, not an on-chain guarantee. And DND fails open: if the store hiccups mid-lookup, the server accepts the mail rather than refusing something deliverable — do-not-disturb is a courtesy, not a security boundary.

What the refused sender sees

Out of the box, the refusal is the single line above and nothing more. When the operator sets a self-service base URL, the same line also carries a link to a schedule page the sender can open in a browser:

450 4.2.1 Recipient alice is away (do not disturb); try again later; schedule at https://mail.example.com/dnd.html?to=alice%40sithbit.net

The page answers the question the refusal raises — when should I expect delivery? — as far as the recipient allows:

• Accepting now. If the away window has already ended, the page says so: the sender’s MTA is retrying on its own, so the mail is on its way (or a resend delivers immediately).
• Away, schedule private (the default). The page confirms the recipient is temporarily not accepting mail but cannot say when the window ends — the sender’s server keeps retrying regardless.
• Away, schedule shared. If the recipient opted in to sharing, the page lists the away windows — and, when the schedule ever reopens, adds “accepting mail again at …” with the exact resume instant shown in the sender’s own local time (the account service computes it in the recipient’s timezone and ships it as UTC; the page localizes it to the viewer’s clock). The windows themselves still read in the recipient’s local time. A recurring schedule covering the whole week around the clock never reopens, so no instant exists — the page then shows the windows alone.

Sharing is the recipient’s choice, off by default: the account’s expose_dnd_schedule flag (a toggle in the clients’ DND settings, or PATCH /v1/account on the account API) controls whether the anonymous schedule check returns the windows themselves — plus, while away, the resume instant — or only the yes/no “away right now” answer. Your calendar is yours; the protocol only ever needs the boolean.

Stamp refusals: the funding page

The same setting links a second page from the two postage refusals — the gate every unknown sender meets before DND is even consulted:

• 450 4.7.0 — the sender’s frombox exists but holds no stamps. Transient: the sender’s MTA queues and retries, so once the frombox is funded the queued mail delivers on its own — no resend needed.
• 550 5.7.0 — no frombox exists for this sender/recipient pair at all. Permanent: the message bounced for good, so after funding the sender must send it again.

With the base URL set, both append ; fund it at {base}/fund.html?to=<recipient>&from=<sender> — a funding page where the sender fixes the shortage themselves, with no account and no operator in the loop:

1. The page resolves the recipient and quotes the price straight off the chain — the recipient’s per-stamp postage, the fixed settlement surcharge, and the live per-stamp protocol fee (waived on-chain when a recipient funds their own frombox). Nothing is trusted server-side; the quote is read from the same accounts the program enforces.
2. The sender connects a Phantom or Ledger wallet, picks a stamp count (one stamp = one email), and buys. A first purchase creates the frombox in the same transaction — the same create-or-top-up path every client uses.
3. The page confirms the purchase and tells the sender what happens next: after a 450, waiting is enough; after a 550, resend.

This closes the loop postage opens: pricing out strangers only works as spam defence if a legitimate stranger has a way to pay, and the refusal itself now hands them one.

For operators: one setting, two pages

Everything above is off by default — leaving the setting unset keeps every refusal byte-identical to the linkless text. A single SMTP setting turns both links on: the public base URL the two pages are served from (for example https://mail.example.com). There is nothing else to configure — the paths and query strings are built for you.

See the configuration reference for the details, and Self-service pages for refused senders for how the two pages are hosted (they ship in the onboarding web bundle, normally served by the account API’s static-file root). The standalone smtp-server dev binary carries only the funding link — the DND gate is sithbitd’s.

Related

• Getting mail — the receive side the away schedule protects.
• Add stamps — the CLI flavor of what the funding page does, and the exact per-stamp price breakdown.
• Economics — why postage prices out spam, and where the protocol fee goes.
• account-api: the account service — the DND schedule routes and the expose_dnd_schedule opt-in.
• Configuration reference — the operator setting.

The Marketplace

SithBit is not just a way to send mail — it is a small open economy, and three kinds of value change hands on it. Every trade settles in SOL, on-chain, with no platform sitting in the middle taking a cut of the principal:

• Alias names — short, memorable, globally-unique handles that resolve to a wallet. A good name has value, so names can be listed, auctioned, or sold to a specific buyer.
• Domains — the on-chain authority to carry a DNS mail domain’s inbound mail. Selling a domain sells its future settlement income along with the name.
• Attention — through campaigns, you can opt in to be reached by advertisers who pay for the privilege. Your inbox becomes an income stream instead of a spam target.

The first two are the name marketplace: an asset changes owner. The third is the participant pool: nothing changes owner — you rent out your attention, one message at a time, and keep earning. They share a home here because they are the ways SithBit lets you turn what you own — a name, a domain, or your own inbox — into SOL. On a name sale the seller keeps roughly 90% of the proceeds, with a small settlement cut to the postoffice; on campaign mail the recipient keeps the postage and roughly 90% of any bounty.

Why it works this way

Traditional mail gives value in one direction only: a provider monetizes your data and attention, and you pay for the privilege of being marketed to. SithBit inverts that. Because every message already carries sender-paid postage and a name is a real on-chain asset, the same machinery that prices out spam also lets honest value flow back to the people who create it — the name holder, the domain operator, and the recipient.

Nothing here is mandatory. You never have to list a name or join the pool; these are levers you reach for when you want to, and the base experience of owning an address and receiving mail stays exactly as cheap as before. What the marketplace adds is upside.

The two surfaces

Everything below is reachable two ways, backed by the same on-chain accounts:

• In the browser — the marketplace pane (standalone, or mounted inside the webmail/Outlook/Thunderbird clients) lets you browse names for sale, buy with a click, list your own, and browse the participant pool by topic.
• From the terminal — the sithbit CLI drives the same operations: alias sell/buy, domain sell/buy, and the whole sithbit campaign tree for the participant pool.

Where to go next

• Trading names — list, auction, or sell an alias or a domain, and buy names other people are offering.
• Beacons — the small public sign that opts you in: what it says, what it costs to reach you, and how to take it down.
• Campaigns — opt in to earn from your inbox, or run a bountied campaign to reach an opted-in audience.
• Economics — the same flows traced lamport by lamport: who pays, who collects, and where SOL parks along the way.

Trading names: aliases & domains

An alias is a short human name that resolves to a wallet; a domain is the on-chain authority to carry a DNS mail domain. Both are real, transferable on-chain assets that never expire and carry no renewal fee — which means both have a resale market, and the seller keeps 90% of every sale. This page is the map of that market; the mechanics of each move live in the per-name how-tos it links to.

Three ways to sell

A name can leave your hands three ways, depending on whether you have a buyer in mind and how you want price discovery to work:

A listing and an auction name nobody in particular — the market decides who wins. An escrowed transfer is a private, two-party deal: you name the buyer and the price, and only they can take it. All three settle in SOL and take the standard 90/10 split between the seller and the postoffice on the sale proceeds.

What a domain sale actually sells

Buying an alias buys a name. Buying a domain buys a revenue stream: the authority that carries a DNS domain’s inbound mail also collects that domain’s share of every settlement its mail produces, so a domain listing is really an offer to sell that future income. The Economics chapter traces exactly what a domain authority earns.

Buying a name

Browsing and buying is the mirror image: the marketplace pane lists every name currently offered, and a click buys one (signed with your own browser or hardware wallet).² Purchases are public — the buyer, the price, and the transaction are all on-chain (see What’s public and private).

Beyond names: renting your attention

Selling a name is a one-time transfer of an asset you own. If you would rather keep earning from something you don’t give up — your own inbox — that is what campaigns are for: opt into the participant pool and advertisers pay you, message by message, to reach you.

1. From the terminal: List for sale (alias sell --price) / domain sell. ↩

2. From the terminal, alias buy / domain buy take a name that is currently listed. ↩

Beacons

A beacon is a small public sign you put up next to your mailbox that says: you may mail me about these topics, at my usual price. It is how you opt in to campaigns — paid outreach from advertisers — and it is the only thing that makes you findable by one. No beacon, no campaign mail: a wallet that never published one is simply not in the pool, and nothing changes about the mail it already gets.

Think of it as a small classified ad you place about yourself, rather than a profile somebody else builds about you.

What a beacon says

Three things, and deliberately nothing more:

• The topics you’ll hear about. You pick labels from a fixed, shared list — interests, skills, and broad bands such as an age range or a region. There is no free-text box, so there is nothing to over-share in: the labels are coarse on purpose, and everyone’s labels come from the same list.
• What it costs to reach you. Your price isn’t a separate setting on the beacon at all — it is whatever your mailbox already charges a stranger, its default postage. Opting in says “if you’ll pay my going rate, you may reach me”, so there is never a second price to keep in step.
• Optionally, a pointer to a longer profile. If the labels are too coarse to describe you, you can write a fuller profile, encrypt it, store it off to the side, and put only the address of that encrypted file on your beacon. Anyone can see that you have one; nobody can read it unless you hand over the key — and the way they ask for it is to mail you, paying your postage like anyone else. You share it only if you want to.

Because a beacon advertises a mailbox’s price, you need a mailbox before you can publish one.

One beacon per wallet, and publishing replaces it

A wallet has at most one beacon, so publishing again doesn’t add a second sign — it replaces the whole one you had. Whatever you publish becomes the complete new contents: topics you leave unpicked are dropped, and leaving the profile pointer blank clears a pointer you had published before.

The practical habit: when you change a beacon, state everything you want it to say, not just the part you’re changing.

How advertisers find you

An advertiser searching the pool names the topics they care about and gets back the wallets carrying every one of them — naming more topics narrows the result, it never widens it. What they see is your wallet address, your labels, and whether you advertise an encrypted profile.

Finding you is free; reaching you is not. Sending you a campaign message is a separate, paid step: the advertiser pays your postage so the message lands, and can attach a reply bounty you claim if you answer in time. Campaigns walks through that whole flow and who pays for what.

What’s public, and what isn’t

A beacon is a public notice — that is its job, and the reason it is designed to carry so little. Anyone can read your wallet address, the topics you picked, the fact that you published an encrypted profile, and when you last changed any of it. Like everything else on the chain, that record is permanent: it outlives the beacon itself, so closing one later does not un-publish the history.

What stays private is the content of the encrypted profile. Only people you hand the key to can read it — and a key you hand out can be passed on, so keep anything out of that profile whose onward sharing would hurt.

Two habits follow, and they’re the whole privacy story here:

• Pick only labels you’re comfortable being publicly known by, forever.
• Treat the encrypted profile as “shared with whoever I gave the key to”, not as a secret.

For the wider picture, see What’s public and private and its field reference.

Turning it off: disable vs. close

There are two ways to stop being reachable, and they are not the same thing:

• Disable is a convenience of the browser pane, not something the chain itself knows about. It republishes your beacon with no topics; since a search has to match at least one topic, a topic-less beacon drops out of every search. The beacon and its rent deposit stay put. The pane remembers the topics you switched off in that browser only, so Re-enable puts back exactly the set you had — on another browser, or after clearing your browser data, there’s nothing to restore and the pane says so; pick your topics again and publish an update instead.
• Close is the real exit. It removes the beacon entirely, you disappear from every search, and the deposit that kept it on the chain is refunded to your wallet. Opting out is one click, costs you nothing, and leaves nothing behind — and you can always publish a fresh beacon later. Postage you already earned from campaign mail stays yours whether or not you ever replied.

Neither one touches your mailbox, your mail, or your postage price. Ordinary mail keeps arriving exactly as before; you have only stopped advertising that you’re open to campaigns.

Where beacons show up

• In the browser, the marketplace pane’s Participants tab browses the pool by topic, and its My beacon section publishes, updates, disables, or closes your own.
• From the terminal, the sithbit campaign commands do the same three things, and are also the way to encrypt and store a longer profile rather than pasting a ready-made pointer.

Where to go next

• Campaigns — what a beacon opts you into: who pays, what you earn, and how a reply bounty works.
• What’s public and private — the same public/private split across the whole system.
• The participant-pool design note — why beacons carry coarse labels and a sealed profile rather than a rich public one.

Campaigns

A campaign is paid outreach that runs the usual advertising bargain in reverse. Instead of blasting messages at people who never asked and hoping a few don’t mind, an advertiser reaches only wallets that opted in to hear about a topic — and pays each of them for the reach, plus a bounty for a reply. Nobody is contacted uninvited, nobody is contacted for free, and the money flows to the person whose attention is being spent.

This is the same sender-pays idea that prices out spam, pointed at a new use: turning your inbox from something you defend into something you earn from.

Why campaigns exist

Ordinary email advertising is adversarial. Senders want reach; recipients want quiet; the middle fills with spam filters, list brokers, and tracking. SithBit already made unsolicited mail cost the sender real SOL. Campaigns take the next step: they let a recipient advertise their own availability — “I’ll happily hear about gaming and pay-per-response research” — so an advertiser can find willing people directly and compensate them, with no list broker and no guessing.

Everyone is better off in the honest case: the advertiser reaches an audience that wants the message, and the recipient is paid for attention they chose to give.

For advertisers: reach an audience that opted in

If you run outreach — a marketer, a survey researcher, a business with an offer — a campaign gives you something a mailing list never could: a targeted audience that has agreed to be reached, and a built-in incentive for them to respond.

• Target by topic, not by scraped data. Participants tag themselves with coarse interests, skills, and broad demographic bands. You filter to the wallets carrying every tag you care about (a logical AND) — e.g. interest.gaming and region.apac — and the match is exact: what people declared about themselves, never a lookalike model inferred from tracked behaviour.
• Pay only for real reach. You fund each message yourself: the recipient’s postage (so it actually lands) and a reply bounty (paid only if they answer in time). No impressions you can’t verify, no bot traffic — every recipient is a real wallet that chose to be reachable.
• Price it before you commit. A campaign quote reads each matched recipient’s live chain state — a standing frombox price, prepaid stamps, or the reputation-scaled first-contact price — and itemizes message rent, postage, bounty, and fees per class, so you see the whole campaign’s total before a single lamport moves. The same quote marks the matched wallets the send will skip — and never bills you for them: no mailbox, postage over your --max-postage cap, or a mailbox carrying the IPFS opt-out. Your real reach is on screen before you decide; the send reference states the exclusion rule exactly.
• Every recipient is a real, funded wallet. Compare the alternatives a Web3 launch usually gets: an ad platform’s impressions, or a community channel’s shilling, neither of which can prove a human on the other end. Here a bot farm has to hold real SOL in a real mailbox to appear in your search, and it costs it postage to stay there.
• Get responses, not just deliveries. The reply bounty is the hook: a recipient who answers your survey or offer claims it, so your call-to-action carries its own reward.

The whole advertiser flow — search, quote, send — is chain-direct and scriptable from the sithbit campaign CLI. A campaign send is direct-signed only: your funded wallet signs every delivery locally, so no mail server ever holds the keys to a paid campaign.

For participants: earn from your inbox

If you just want to receive mail, you never have to think about any of this. But if you’re willing to hear from advertisers about things you actually care about, opting in turns your inbox into an income stream — and you stay in control the whole time.

• You choose what you’ll hear about. You publish a small on-chain beacon listing coarse tags — interests, skills, broad bands like an age range or region. Advertisers can only find you through the topics you chose.
• You set the price. Your participation price is simply your mailbox’s default postage — the same price that already prices out strangers. Opting in doesn’t add a new fee to manage; it says “if you’ll pay my going rate, you may reach me.”
• You get paid twice. When a campaign message arrives you keep the postage — you were paid just to be reached. Reply before the window closes and you also claim the bounty (split 90% to you, 10% to your domain authority — or to the postoffice when no active domain resolves for your mailbox). Ignore it and you simply keep the postage — you are never paid less for not replying.
• Your privacy is built into the design. Only coarse, self-chosen tags go on chain — never free text, never precise personal values. A richer profile, if you attach one, is encrypted; an advertiser who wants it has to mail you and ask, and you hand over the key only if you want to. See What’s public and private.
• You can leave any time. Closing your beacon is the opt-out — you drop out of every search immediately, and the account’s rent is refunded to you.

How it works

1. Opt in. A participant publishes a beacon listing the tags they’ll accept mail on. Their mailbox must already exist — the advertised price is its default postage.
2. Discover. An advertiser runs a trustless search for beacons carrying every tag they want, and gets back each match’s sendable wallet.
3. Quote. The advertiser prices the matched set, itemized per recipient, and sees which matches the send will skip, before committing funds.
4. Send. The advertiser sends one bountied message to each remaining match — the loop continues past any single failure so one bad address can’t strand a paid batch.
5. Earn. The participant keeps the postage on delivery, and — if they reply before the window closes — claims the reply bounty. Anything unclaimed is refundable to the advertiser after it expires.

For the exact commands, flags, and quote output, see the sithbit campaign CLI reference. For the money traced lamport by lamport, see Economics → Campaigns. For the design rationale behind the coarse-tag beacon and the mail-gated detail profile, see the participant-pool marketplace design note.

Where campaigns show up

• In the browser, the marketplace pane’s Participants tab lets anyone browse the opt-in pool by topic.
• From the terminal, the sithbit campaign tree drives both sides — a participant’s create/update/close and an advertiser’s search/quote/send.

What’s public and private

SithBit puts the envelope on a public ledger — the Solana blockchain, where it is public and permanent — and keeps the letter sealed. That split shapes its privacy model in a way ordinary email does not, and this page tells you exactly which side of it every piece of your mail lands on. Your message body and subject are encrypted so only the recipient can read them; almost everything around the body — who mailed whom, when, and for how much — is world-readable and stays that way forever.

This page is the plain-language map of that split. For the exact field-by-field inventory of every account and what it exposes, see What’s public and private: the field reference. For the adversarial framing, see the trust assumptions and threat model.

The one-line summary

The rest of this page unpacks each row.

On-chain: public and permanent

Everything an on-chain account holds is stored in the clear in a world-readable Solana account — anyone can read it, and history outlives deletion. What that means for you:

• Your wallet address is your public identity. It doubles as your email address (see Addresses), so it is inherently public — anyone you mail, and anyone watching the chain, sees it.
• Your account settings are readable. Your mailbox’s default stamp price, your published encryption key, your no_ipfs preference, your alias-to-wallet mapping, and any domain you authorize (its cleartext DNS name and authority) are all on-chain and public.
• Every send records metadata. Sending mail writes a message account keyed to the recipient wallet, holding the sender wallet, a blake3 hash of the from address (never the string) and a timestamp — and the rest of the account with them, down to the body’s storage locator, listed field by field in the Email row. So a chain observer learns which wallet mailed which wallet, and when — the address book, not the message. This is deliberate and covered in depth under message metadata is hashed, not hidden. It is permanent: this history survives even after you delete the mail.
• Money is visible. SOL balances, stamp purchases, and every transfer are public, as on any Solana account.
• Marketplace purchases are public. Listing an alias or domain for sale, the asking price, the winning bid, and the buyer’s wallet are all on-chain — an observer can see who bought which name and for how much.
• Opting in to campaigns is public. Publishing a beacon puts your wallet in the campaign pool on-chain, together with the topic tags you picked — and the rest of the beacon account with them, down to the timestamps, listed field by field in the ParticipantBeacon row. The profile’s contents stay sealed; the fact that you have one does not.

Off-chain: the sealed body and your operator

The message body never touches the chain. It is sealed with crypto_box_seal to your wallet (or a delegated key — see Mailbox Keys) and stored off-chain. That keeps the plaintext private, but “off-chain” is not automatically “hidden”:

• The plaintext body and subject are private. They are encrypted before they are ever stored, and only your wallet key (or delegated key) opens them. The readable From:/To:/Subject: headers live only inside this sealed body.
• But the ciphertext on IPFS is public. By default the sealed body is pinned to IPFS, where anyone holding its content ID can fetch it. They get ciphertext, not plaintext — but a public copy of your ciphertext exists. That is a harvest-now, decrypt-later exposure: an adversary can archive the ciphertext today and decrypt it years from now if the sealing crypto is ever broken. If that trade-off matters to you, the no_ipfs opt-out keeps the ciphertext off public infrastructure (at the cost of decentralized availability).
• Your operator sees more than the chain does. Whoever runs your mail server handles your mail at delivery and at read time, holds your IMAP / POP credentials, and — for mail relayed through them — sees the SMTP envelope and headers in the clear. A relaying domain operator is a trusted party; see the domain authority is fully trusted for relayed mail. How much of your mail they can read afterwards, from their own store, depends on how your account authenticates — the next section unpacks it.

What your operator holds

The server that delivers your mail keeps its own copy so IMAP, POP, and webmail can serve it back to you. For accounts without a stored mail password — wallet-signature login only — that copy can be envelope-encrypted at rest¹: each delivered body is sealed once under a fresh per-message key (AES-256-GCM), and that key is wrapped to your account’s reading key with the same sealed-box construction that seals mail to your wallet. The reading secret is derived in your client, travels only at login — appended to the wallet-signature password over IMAP/POP, or as a field on the account API’s token exchange — is held in memory for the session, and is scrubbed when the session ends. A session that didn’t supply it gets a clear “log in again with your reading key” refusal; the server never hands back raw ciphertext pretending it is a message. A session that did supply it reads normally throughout — the summaries in your message list and your search hits are decrypted for it too, not only the message you open — while an unkeyed session still gets its list and its search, with the bodies it cannot open shown as locked rather than blank or silently missing.

This at-rest sealing is automatic on chain-connected deployments — there is no operator switch to forget. Any sithbitd or account API with a chain gateway configured seals password-less accounts’ mail at spool time; only a chain-less development stack (which has no way to resolve reading keys) stores plaintext. The one thing that opts an account out is setting a stored mail password. Your reading secret is accepted only where reading happens — IMAP, POP, and the account API’s login. The SMTP submission service refuses a wallet-signature login that carries it: sending mail never requires your decryption secret, so a client configured to ship it there fails loudly instead of leaking it.

Be clear-eyed about what it does and does not buy you. What it protects against:

• A stolen disk, a leaked backup, a store snapshot or dump — none of them contain your plaintext, only the envelope-sealed bytes.
• After-the-fact browsing — an administrator paging through the store (or its backups) later cannot read sealed bodies without your reading key.

What it does not protect against:

• A live, malicious operator. The running server necessarily sees your reading secret at login and the decrypted plaintext at read time — a hostile operator can capture either in-process. At-rest sealing protects data at rest, not from the operator while you use their server. If that is your threat, the answer is no server at all — see Trustless webmail.
• Accounts with a stored mail password. They keep a readable copy by design: challenge-response logins (CRAM-MD5, APOP) never transmit a reading secret, so the server must be able to serve those sessions from a copy it can read itself.
• Metadata. Who mailed whom, when, message sizes, folder activity, and the SMTP envelope of relayed mail all stay visible to the operator — sealing covers bodies, not traffic.
• The public copies. The body pinned to IPFS and referenced on-chain was ciphertext all along — sealed to your wallet, a separate model this section changes nothing about; see IPFS storage: benefits to users.

The same at-rest-versus-operator distinction applies to any per-recipient pin-provider credentials you register: sealed on disk, readable by the running server.

What you control

• no_ipfs — keep your sealed bodies out of public IPFS, stored only by your operator. Removes the public-ciphertext exposure; re-centralizes availability onto one operator. See Opting out of IPFS storage.
• A delegated encryption key — publish an X25519 key so senders seal to it instead of your signing wallet; see Mailbox Keys. The key itself is public (it is a public key); the point is key separation, not hiding.
• Skipping the stored mail password — wallet-signature login (with a reading key) is what keeps your server-side copies sealed at rest on chain-connected deployments; see What your operator holds. A stored mail password trades that away for CRAM-MD5/APOP compatibility: it is recoverable in plaintext by your operator, and every message delivered to you while you hold one is stored readable. Some operators disable stored passwords entirely for that reason, in which case setting one is refused and the choice is already made for you.
• Sharing your DND schedule (expose_dnd_schedule) — by default, anyone probing the anonymous do-not-disturb check learns only whether you are away right now, never your calendar; the away windows themselves appear only if you opt in. See What the refused sender sees and the account API.
• Alias vs raw wallet — an alias is a friendly public label for a wallet; it does not add privacy (the mapping is on-chain), it adds memorability.

The honest limitations

SithBit hides message contents well and message metadata poorly — by design, because it settles on a public chain. Say this before anyone else does: your social graph is public.

1. The social graph is public and permanent. Who mails whom, how often, and when is readable on-chain forever, even though the messages themselves are sealed. Traffic analysis is possible; the plaintext is not.
2. Public ciphertext is a long-horizon risk. Default IPFS storage means your encrypted bodies are publicly archivable — safe against today’s cryptography, a bet against tomorrow’s. no_ipfs is the lever if you don’t want to make that bet.
3. Your purchases are visible. Marketplace buys tie your wallet to the names you acquire, publicly.
4. Opting in to campaigns is itself public. Publishing a beacon puts your wallet and the topic tags you picked in the on-chain campaign pool, along with every other field of the beacon account — the profile you attach stays sealed, your participation does not.

None of these are bugs — they are the cost of a trustless, operator-independent system. Knowing them lets you decide what to route through SithBit and what to keep elsewhere.

Further reading

• What’s public and private: the field reference — the exact per-account inventory.
• Trust assumptions and threat model — the adversarial view.
• How sealed-box encryption works and IPFS storage: benefits to users — why publishing ciphertext is safe, and how to opt out.
• The split model: body off-chain, envelope on-chain.

1. “At rest” contrasts with in transit: TLS protects mail moving on the wire, at-rest sealing protects the copy sitting in the operator’s storage. Neither covers the moment the running server handles plaintext — that is the live-operator caveat below. ↩

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 yourhandle@sithbit.com 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: strangers pay it and you keep roughly 90% of what they pay, while you lower it per sender — or waive it — for people you want to hear from (see Economics for how postage and prepaid stamps work). The default matches the CLI’s — one SOL — and it is deliberately a wall rather than a price list: it keeps strangers out until you decide otherwise. If you want to be reachable by people you don’t know yet, or findable by campaigns that pay you to be reached, set a lower default here. 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 a [[static]] mount whose root is the built webclients/onboarding/staging bundle (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. The purchase is pinned to the price the page quoted, so a repricing between the quote and the click makes the buy refuse rather than charge the new rate.
• 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 a [[static]] mount, like the get-started page above — needs no setting at all.

GUI clients

Not everyone lives at a terminal. Alongside the sithbit CLI, SithBit ships four graphical clients — the webmail app, the Chrome extension, the Outlook add-in, and the Thunderbird extension — as the non-CLI ways to use your account. Each one wraps the same account-management surface in a different host, so which one you reach for is a matter of where you already read your mail, not what you can do.

They are not four separate apps that happen to look alike: all four run the same shared core (webclients/shared/), so a pane behaves identically wherever you meet it. Everything that must be signed is signed client-side by a WebAssembly module compiled from this workspace’s own crates — the server only relays already-signed transactions and never holds your key.

Because they share that core, they also share the same first-run experience: every one walks a brand-new user through the identical five-step browser onboarding wizard — create or import a wallet, then claim a mailbox (and, optionally, a handle) on-chain in one pass. Once you are set up, the same wizard is reachable again from each client’s dashboard to onboard a second wallet.

Pick the client that fits your setup:

• webmail app — a standalone browser app, nothing to install.
• Chrome extension — an installable browser-toolbar popup for account onboarding and wallet management.
• Outlook add-in — for Microsoft Outlook.
• Thunderbird extension — for the Thunderbird desktop mail client.

The three extension pages each open with an Installing from the store section (Chrome, Outlook, Thunderbird) alongside the build-and-sideload path — note the store listings are placeholders until the extensions are published.

Reading and sending mail itself is otherwise unchanged across all four: it flows over ordinary IMAP/POP/SMTP, exactly as it does for the CLI. The one exception is the biggest reason to pick a plugin over a generic mail app: the Thunderbird extension and Outlook add-in also carry Lockbox, automatic end-to-end encryption that seals a message on your device before it ever reaches a server — including your own mail operator’s. Lockbox works over any existing email account and needs no funded wallet and no on-chain mailbox, so it is also the lowest-commitment way to try SithBit: install the plugin, seal your mail, and claim a mailbox later if you want an address that pays you. Everything else these clients do is the account-management and onboarding surface, not a replacement for your mail app.

Operators: everything on these pages is written for the person using a client. The server side — what each one needs of account-api, and how the webmail and marketplace bundles are built and mounted — is Serving the browser clients in the technical reference.

The webmail app

A plain-browser webmail client: the folder rail, a newest-first message list with per-folder search, a sandboxed reader, and a compose pane — plus the same wallet login and settings panes the Thunderbird and Outlook clients carry, because all three hosts run the same shared core (webclients/shared/). Everything that must be signed is signed in the page by a WebAssembly module compiled from this workspace’s own crates; the server only relays already-signed transactions and never holds your key.

Navigation is hash-only — #/mail (the three-pane mail view) and #/settings (the shared dashboard panes). There is no build framework and no CDN: the bundle is static files served by account-api itself.

The server is optional, though: clearing the API URL in the connection settings switches the app into trustless mode — wallet-only unlock, on-chain mail read and sent with nothing but a Solana RPC node and an IPFS gateway/pin daemon.

Operators: building this bundle, mounting it under account-api, and the config the compose pane needs are covered in Serving the browser clients. A reader who was handed a URL needs none of it.

Install as an app (PWA)

The webmail bundle is an installable progressive web app. Once it is served over its origin, the browser offers its native install prompt on the desktop (Chrome/Edge’s address-bar install button) and Add to Home Screen on mobile, giving you a standalone SithBit Mail window with its own icon and no browser chrome — tinted the brand teal.

A service worker precaches the static shell (HTML, CSS, JS, and the wasm module), so the app loads offline — the login, unlock, and dashboard frames paint with no network. Your mail itself stays live: the service worker never caches the account API (/v1/*), so every message, folder count, and send always hits the server. Open the app with the server down and you get the shell; you reach your mail again the moment it is back.

First run and onboarding

A brand-new visitor — no wallet stored in this browser yet — lands directly in the shared five-step onboarding wizard: create or import a wallet (the create branch shows your secret key once, with the save it — it is the only copy gate), claim an optional handle, set your default postage, review, and mint your mailbox on-chain. Until that finishes the app hides its mail and settings views and shows only the wizard. Every transaction is built and signed in the page by the wasm module; the server only relays it.

The app decides which of four views to paint from the session it probes on load:

• Onboarding wizard — no wallet stored yet, or an unlocked wallet that owns no mailbox (a returning user finishing setup).
• Unlock — a wallet is stored but locked this run; the app asks for its passphrase (the key is encrypted with that passphrase before it lands in the browser’s localStorage, and is asked for again each time you open the app).
• Dashboard — a fully set-up account: unlocked and mailbox-registered — the normal #/mail, #/settings and #/market views below.
• (a brief loading view while it probes.)

Because the webmail bundle is served same-origin from account-api, it needs no endpoint configuration at all: the API base URL is simply the page’s own origin. The onboarding create relays through that same API, so its on-chain reach follows the API’s [chain] config exactly as the compose path does above.

Using it

The #/mail view is three panes. The folder rail opens with a pinned section in a fixed order — INBOX, then Sent, then Drafts, each hoisted with whatever nests under it — and a rule divides it from the rest of your folders. A special-use folder draws a small icon for what it is (Sent, Drafts, Archive, Trash, and Junk or Spam); INBOX and folders of your own draw none. Either section renders as a tree with unseen counts: names nest on the / separator (a folder named Projects/Alpha shows as Alpha under Projects), a parent row’s triangle folds its subtree shut and open, and a nested folder whose parent does not exist shows flat under its literal full name — the rail never invents a parent row the server did not list. A folder holding unread mail renders its name bold — the same cue as an unread message row, keyed to each folder’s own count, never bubbled up to a parent.

Long folder lists fold. When the section below the rule holds more than five top-level folders, the rail draws the first five — each with its own subtree — and a More link appears beside New folder; clicking it shows the rest and the link reads Less while they are showing. Only that section is ever cut: the More link never hides the pinned three, and never hides the folder you are currently reading either, even when it sorts past the cut — though a subtree you folded yourself stays folded in both sections, so your own fold can still hide the folder you are reading. The link is there only while a row is genuinely hidden, so an account one folder over the line with that folder selected draws everything and offers no link at all. In the shot above, More stands for Spam and Trash.

The middle column stacks per-folder search over the message list (keyset-paged, newest first); the reader marks messages read on open, toggles text/HTML/raw views (HTML render in a fully sandboxed iframe that blocks scripts and remote loads), downloads attachments, flags, moves, and deletes. A ✓ Verified trust mark appears beside the From line when the sender holds an on-chain verified-sender attestation from its domain — here it checks the sender the (ingress-authenticated) From header names, while the trustless viewer’s badge binds the program-verified on-chain envelope signer. No mark simply means “not attested”; it is never a warning. Compose floats bottom-right: To/Cc take comma-separated addresses — aliases, user@domain, or bare wallet addresses — and the reader’s Reply action opens it prefilled (sender as To, Re: subject, threading header). A successful send files an already-read copy in Sent and refreshes the folder counts; recipient problems (unknown alias, no stamps on your frombox) surface on the pane with your draft intact.

The rail also manages your folders. New folder under the list opens a small dialog with a Nest under picker — any listed folder, or the top level — and each row’s ⋮ menu (shown when you hover the row, or reach the button with the keyboard) offers Rename, Delete, and New subfolder. Creating a folder navigates to it: the rail reloads, unfolds any parent you nested it under, and selects the new folder — so one created past the More cut is drawn rather than hidden behind it. That selection closes whatever message the reader had open, exactly as picking any folder does. Rename edits the folder’s full name, so changing the path part re-parents it, and its subfolders move along with it (the dialog says so when it has any). Delete asks first, then removes that one folder and its messages and keeps its subfolders: a child whose parent is gone shows flat under its literal full name, exactly the orphan rendering described above. A placeholder row the server lists as unselectable (a parent an earlier delete left behind) offers only New subfolder — there is no real mailbox there to rename or delete.

The #/settings view is the shared dashboard: mail password — typed, or derived from a wallet signature with the pane’s Derive mail password button (available while the wallet is unlocked; see The mail password) — timezone, do-not-disturb, aliases, balances, delegated encryption-key management, domain trading (list a domain you hold for sale on the open marketplace, or buy a listed one by name and authority), settling reply bounties (claim one on a message you received and replied to, or refund one you placed that expired unclaimed), pinning leases (escrow a refundable deposit asking operators to keep a message’s pinned body past the default retention — create a lease by the message’s CID and id, check a CID for your wallet’s lease, or close it anytime to reclaim the deposit), claiming and configuring your mailbox (the handle, sending domain, default postage, and on-chain-only opt-out), and closing the mailbox — a two-step, 7-day timelocked flow, so the request only starts a clock (the mailbox stays open and receiving, nothing is refunded), a cancel is available throughout, and the rents return only when you come back after the wait and finish the close. Where they return depends on who paid: for a mailbox you created yourself both rents come back to you, while for a sponsored mailbox the mailbox rent goes back to the sponsor who funded it and you keep the pending-close rent. The pane says which happened. All of it behaves exactly as documented for the Thunderbird extension. The trustless viewer’s Lease this message button (beside Reply, shown once a body has rendered) prefills the pinning-leases create form with the open message’s CID and id and routes the shell straight here — the URL hash becomes #/settings and the settings strip opens its Services tab, so the browser’s back button returns to the mail view. You still review the deposit and submit, and entering a CID by hand works as before.

Three of those controls decide how your mail clients get into the account — Set password, removing a stored password, and rotating the wallet-derived one — and each of them asks your wallet to sign a one-time confirmation as it goes through. The pane says so where it asks (the mail password field’s own line reads “Saving it asks your wallet to sign a one-time confirmation.”), and the signature is per change: applying two of them is two confirmations. With an in-app wallet the app signs and you see nothing; with a Phantom or Ledger wallet it is the usual approval prompt. Being signed in is no longer enough for these three, which is the point — a session someone else picked up cannot change your mail credentials without your wallet. The account-api reference has the wire-level contract.

The settings view: five tabs

The #/settings view is the shared dashboard the other clients mount too. Since v0.86.0 the panes sit under a five-tab strip so the dashboard fits without scrolling: Wallet (Balances, Encryption key), Mailbox (Mailbox, Do not disturb, Close mailbox), Names (Aliases, Domains), Services (Reply bounties, Pinning leases) and Sign-in (Settings — the mail password — plus the certificate and connection sections described below). Hovering a tab for half a second shows a one-line note of what it holds. The topbar’s Mail / Settings / Marketplace links pick the view.

Sealed rows and your reading key

On a deployment that keeps your stored mail sealed at rest, the app can only show you a message it can decrypt. A row it could not open is drawn as locked rather than blank: (sealed) where the sender goes, (sealed — sign in with your reading key) where the subject goes, and no snippet. Its date is real — dates come off the mailbox row, not the body — so the list still sorts and pages exactly as usual, and opening a locked row answers with a readable sign in again with your wallet’s reading key message rather than a broken reader. Search skips them too: a message this session cannot open never appears in results, rather than matching its ciphertext.

Sign in with your reading key and the lock simply is not there — those rows list, search, and open like any other, with nothing marking them out. The app works out which key your mailbox is read with at unlock — it looks up what, if anything, your mailbox has published on-chain, then derives that secret itself — and hands it to the server only on the login exchange; there is no setting to turn on and nothing extra to type. Treat it as a secret, not as a password: a mail password only proves who you are, while this key opens mail — anyone holding it reads every message sealed to that wallet, the old ones as well as the ones still to arrive. That is why it lives in the page for the length of a session, is never written to the browser’s vault, and rides nothing but the login.

Which accounts have that key today. Four cases:

• A browser-generated account that has published no encryption key — the default for a wallet the in-page wizard created — yes. Its stored mail is wrapped to the wallet’s own encryption twin, and unlocking the wallet is what produces that secret, so every sealed row opens — the mail already in the account included, because the twin is the key it was always wrapped to. Nothing to publish, nothing to save, no button to press. (Until this release those rows stayed locked: the page held the wallet, but nothing handed the app the wallet’s twin secret.)
• A connect-wallet account (Phantom, Ledger, or any wallet extension taken through the web wizard) — yes. The wizard generated a delegated reading key and published it, and your browser holds its secret, so every sealed row opens.
• An account that published the recoverable, wallet-derived key (the recoverable reading key, published from the command line with sithbit mailbox set-key --derive since no pane offers it) — yes. Unlocking reproduces that key from the wallet itself, and the app signs in with it rather than with the twin because it can see that this is the key your mailbox published — so every sealed row opens, on any device you hold the wallet on, with nothing to save or paste. (Until this release these accounts read nothing sealed here: the app signed in with the twin while your operator wrapped to the derived key.)
• A browser-generated account that published a fresh random delegated key — the Encryption key pane’s Generate & publish a delegated key button — yes for the mail sealed to that key, while the tab stays open. Publishing signs this session in again with the new key on the spot, so mail that arrives from then on opens without your locking and unlocking first; and because a session reads with one key, the mail already in the account — sealed to the wallet twin, before the publish — is what lists as locked for the rest of that session. That key is random, so nothing about your wallet reproduces it: the app keeps the copy the pane just published only for as long as the tab stays open, and it is never written to the browser’s vault, the one-time export the pane shows you being the only lasting copy. So a reload signs in with the wallet twin again — the older mail reads, and rows sealed to the published key list as locked. Keep that export; handing it back to the app at sign-in is filed follow-up work.

Publishing or closing a key takes effect at once. Either way the app signs this session in again with whatever reads your mail from that moment — the key you just published, or your wallet’s own key again once a delegated key is closed — so there is no lock-and-unlock step to remember, and no stretch of the session where your operator holds a key nothing is sealed to. If that second sign-in cannot reach the server the pane tells you in as many words (“…but this session still reads with the previous key. Lock and unlock to finish switching.”): the on-chain half already happened and is not undone, it is only this session that is still on the old key.

So the Encryption key pane is about key separation — keeping the key that reads your mail distinct from the key that signs your transactions — not about unlocking anything in the browser. Publish a random key when you want that separation, save the secret it shows you, and expect the trade above; leave the mailbox key-free, or publish the wallet-derived key, and this app reads everything. None of this arises on a development stack with no chain gateway (nothing is sealed at rest there), nor for an account with a stored mail password — see what your operator holds and the account-api reference for the wire-level contract.

Locking and signing out

Lock, beside your address at the top of the app, is how you leave: it drops the active wallet’s unlocked key and this browser’s session token, and the app falls back to the passphrase gate. The wallet stays imported for next time, and your reading key goes with the session — it only ever lived in the page.

It signs you out of your mail server in the same breath. The reading key you signed in with sits in the server’s memory for that token’s life, and Lock ends that session there and then — POST /v1/auth/logout, which drops the reading key and every summary decrypted under it, so nothing sealed can be opened with that token again. The Lock button in the shared wallet manager that the Thunderbird, Outlook and Chrome clients carry does the same thing per wallet: locking one of two unlocked wallets there signs that one out of the server and leaves the other alone.

It locks either way, whatever the server answered — so locking still works with the server down or the machine offline, and a sign-out that could not be delivered passes without a word rather than an alarm over a lock that did work. What your server keeps even after a clean sign-out is the other half of this, and is worth knowing: the session token is a stateless bearer credential that nothing revokes. It stops being accepted when it expires; locking removes this browser’s only copy of it, and the key that made it useful is gone from the server’s memory — but the token itself stays valid to the letter until it runs out.

Removing the stored mail password

A stored mail password is optional, and it is not a one-way door: #/settings can hand it back. The Remove the stored mail password block appears only when there is actually one stored — an account on wallet-signature login never sees it — and it opens by saying what you are trading: removing it leaves this account on wallet-signature mail login, so your mail client authenticates with the wallet-derived password instead, and you can set a stored password again whenever you like.

The gesture is the same deliberate two-step as rotation below it. Remove the stored mail password… arms the change rather than making it, and arming replaces the button with a warning and two answers: Remove it now, or Keep my stored password. The warning is the part to read twice: every mail app set up with the stored password will stop connecting until you give it a new one, and the server keeps only a hash of that password, so it can never be shown to you again. There is no recovery afterwards — a client still holding the old value has to be given a new password, either a fresh stored one or the wallet-derived one. The warning closes by telling you what happens next: your wallet signs a one-time confirmation as you continue — silently with an in-app wallet, as an approval prompt on a Phantom or Ledger one.

Removing takes effect at once. The block disappears — there is nothing left to remove — and a notice takes its place telling you where your mail clients now stand: they authenticate with the wallet-derived mail password instead, so derive that value and paste it into each one, or set a new stored password at any time. Derive mail password, in the section just below, is where that value comes from.

What a removal does not do is worth as much as what it does, and it is the mirror of the three the rotation warning heads off:

• It does not rotate the wallet-derived password. Your account’s auth epoch is untouched, so every copy of the wallet-derived password keeps authenticating exactly as before. Retiring that credential is rotation’s job; the two levers are independent, and neither implies the other.
• It does not sign you out. Your session token is untouched and stays valid to its expiry, exactly as after Lock. Only mail apps configured with the removed password need attention; this page, and any other client holding a live session, carry on.
• It does not revoke a client-certificate login. SASL EXTERNAL proves who you are from the certificate presented in the TLS handshake, not from any password, so removing a stored one leaves that door exactly as it was. The only lever on it is the operator’s client_cert_auth setting.

It does exactly one thing: it deletes the stored secret. The account is back where a fresh one starts, and Set password puts a new one in place whenever you want it. Note that setting the password to an empty value is not a way to clear one — that only declares the wallet-signature state and leaves any existing secret in place; removal is this control, and nothing else. Underneath it is one call, DELETE /v1/account/password, which takes no argument that could point it at anybody else’s account and is idempotent — a double-click is a second no-op, not an error. The same block rides the shared Settings pane in the Thunderbird, Outlook and Chrome clients.

Rotating the wallet mail password

The wallet-derived mail password has no expiry of its own — it is a signature over a fixed challenge, so anyone who copied it once could use it forever. #/settings is where you take it back. Under Rotate the wallet mail password the pane shows the account’s current auth epoch — a counter mixed into the challenge your wallet signs — beside a Rotate the wallet mail password… button that arms the change rather than making it. Arming replaces the button with the warning above and two answers: Rotate it now, or Keep my current password. Rotating adds one to the epoch (the pane names the new value), which changes the bytes a valid password must sign over — so every copy of the old password stops authenticating at that instant, on every SMTP, IMAP and POP listener at once.

The gesture is two-step because the cost lands immediately: every mail app already set up with the wallet-derived password will stop connecting until you paste the new value into it. The warning’s last line is the other half of the gesture: your wallet signs a one-time confirmation as you continue. Arming the control does not spend it — the signature is asked for when you press Rotate it now, once, for this rotation only, and a Phantom or Ledger wallet shows its approval prompt at that moment. Declining it leaves the epoch exactly where it was. Derive the replacement right there — Derive mail password always signs for the epoch the pane just read — or offline with sithbit mailbox credentials --epoch <N>, where <N> is the epoch this pane shows.

What a rotation does not do matters as much as what it does, and the pane says all three on the warning rather than leaving you to find out:

• It does not clear a stored mail password. Rotation is scoped to the wallet-derived credential. If the account also set a stored password, that password is untouched and still logs in — this is not a “revoke every way in” button. Clearing the stored one is its own control, a section up: Removing the stored mail password.
• It does not sign you out. Your session token is untouched and stays valid to its expiry, exactly as it does after Lock. Only mail apps need re-provisioning; this page, and any other client holding a live session, carry on.
• It does not revoke a client-certificate login. SASL EXTERNAL proves who you are from the certificate presented in the TLS handshake, not from a signature over the epoch, so a bump leaves that door exactly as it was. The only lever on it is the operator’s — turning client_cert_auth off for the listener.

The control appears only once the app has actually read your account, so it can never offer to bump an epoch it could not see; if you are not signed in it says so instead. Underneath it is one call, POST /v1/account/auth-epoch, which always acts on your own wallet and takes no argument that could point it at anybody else’s. The same control rides the shared Settings pane in the Thunderbird, Outlook and Chrome clients, and the operator-hosted enrollment page.

Balances: quotes before you buy

The Balances pane covers both directions of postage, and they are not the same thing. Sender stamps looks inbound — what a given sender holds with you, and the price you charge them. Buy stamps to send looks outbound — postage you prepay toward someone else.

On the outbound side, Quote reads the live per-stamp price for the pair in the form: the price that recipient has set for you if you already have a frombox with them, otherwise their default rate for a new sender. The same figure becomes the price ceiling your purchase is pinned to, so a repricing between quoting and buying makes the purchase refuse rather than overcharge. Buying without quoting first is still guarded — the ceiling is read again at the moment you buy either way.

Once a quote shows a frombox with stamps still in it, a Reclaim unspent button appears beside the buy buttons and returns that postage to your wallet, leaving the frombox open at the recipient’s price. It is offered only when the sender address in the form is your own wallet, since that is the only frombox the withdrawal can address — see getting unspent postage back.

The compose loop is exercised headlessly by the env-gated live suite webclients/webmail/test/e2e-webmail.test.js — the bundle served from a real account-api, a real send to a throwaway wallet, and the message read back from the recipient’s INBOX (the runbook lives in webclients/README.md).

Trustless webmail

The webmail app normally rides its account API for everything: login, folders, compose, settings. Trustless mode is the same app with the mail server removed from the loop entirely — leave the API URL blank in the connection settings pane and, from the next load, the wallet alone unlocks the session (no login challenge, no JWT) and every on-chain read and write goes straight to a Solana JSON-RPC node. PDA derivation, account decoding, sealing, and signing all happen in the page, in the same WebAssembly module the normal mode uses; no server ever sees your key, and now no server has to exist at all.

Note the default is not blank: the app is normally served same-origin by account-api, and an absent setting means “this origin”. Trustless mode is the explicitly cleared field — the deliberate statement that there is no account API.

What it needs instead

Three endpoints, all in the connection settings pane (dev defaults in parentheses — the local development stack):

• Solana RPC URL (http://127.0.0.1:8899, a surfpool dev validator) — every chain read and the transaction submit path.
• IPFS gateway URL (http://127.0.0.1:8183, sithbit-gateway) — GET /ipfs/{cid} for reading sealed bodies.
• IPFS pin service URL (http://127.0.0.1:8182, sithbit-ipfsd, plus its optional bearer token) — where sending pins outbound bodies. Only sending needs it; reading works with the first two alone.

One sithbit-ipfsd can serve both IPFS roles: its pin surface is POST /pins/… and it answers GET /ipfs/{cid} for anything it holds, so pointing the gateway and pin URLs at the same daemon is a complete single-node setup.

What works, and what doesn’t

Everything on-chain works: wallet unlock, the trustless inbox (your mailbox’s message count enumerated newest-first, straight off the message accounts), the trustless reader (fetch the sealed body from the gateway, unseal with the wallet in the page, render), balances, delegated encryption-key management, and the trustless compose described below.

Everything that lives on a server doesn’t, and the app hides those surfaces rather than degrade them: the server mail view (folders, search, the Sent copy), compose through the server (and with it any delivery to non-SithBit addresses — trustless send is on-chain only, there is no plaintext fallback), account settings (mail password, timezone, do-not-disturb), and the marketplace and alias listings — those ride the gateway’s off-chain index, which a raw RPC node cannot answer. Resolving an alias you send to still works: that is a plain account read.

Sending without a server

The trustless compose card follows the same path sithbit mail send takes, client-side:

1. Resolve the recipient — a wallet address or alias — and their published encryption key from the chain.
2. Check their mailbox. A mailbox with the no_ipfs opt-out refuses the send outright: the flag means “my mail never touches public IPFS”, a trustless client cannot deliver any other way, and the opt-out is honored client-side before anything is pinned.
3. Check your frombox toward them. No frombox yet? The card quotes the postage and points at the Balances pane to buy stamps — your draft stays intact.
4. Seal the message to the recipient’s key in the page, pin the sealed bytes to your configured pin service, then sign and submit the SendMail transaction and poll it to commitment.

The signing step follows your session’s wallet flavor. An unlocked in-page wallet signs the transaction right in the page. A connected external wallet (Phantom or Ledger) is asked to approve the same transaction instead — the page builds it unsigned with your wallet as the fee payer, your wallet extension signs and broadcasts it, and the page polls the returned signature to commitment. Either way the sealing happens in the page before anything leaves it; the external wallet only ever sees the finished transaction.

Replying, and attaching a bounty

The trustless reader’s Reply on-chain action seeds this compose card: the To field takes the decrypted sender (for a local-only message, the sealed envelope’s sender), the subject gets its Re: prefix, and the draft carries the parent message’s account address — the same privacy-preserving linkage --reply-to makes, so only its blake3 hash reaches the chain. A chip on the card shows the linkage; Clear drops it and keeps the draft. Replying does not require a bounty.

Nor does replying require trustless mode: even with an account API configured, opening a message in the trustless viewer and clicking Reply on-chain opens this card, prefilled the same way — it floats in the corner exactly like the server compose pane. (Earlier releases seeded the draft but left the card hidden in API mode, so the click appeared to do nothing.)

The card’s Attach a reply bounty fields escrow SOL on the message exactly like --bounty/--bounty-window: an amount in SOL (blank = plain send) and a claim window in days (default 7, the CLI’s default window). A window that would make the bounty born expired is refused in the page before anything is pinned — the same rule the chain enforces. Both signing flavors author bounties; what doesn’t is compose through a mail server, which stays bounty-less by design — bounty authoring is a direct-signed surface.

No frombox yet? Prepay inline

When step 3 finds no frombox toward the recipient, the card holds your draft and quotes the purchase instead of failing: a stamp-count input (default 1 — the on-chain prepayment rule: a non-owner’s first purchase is at least one stamp) and the exact funding math per stamp — the recipient’s posted postage, the fixed settlement surcharge, and the postoffice’s live per-stamp protocol fee, read off the chain rather than assumed from its genesis default (it is waived only when you buy toward your own mailbox), plus the account rent the chain adds on a first purchase.

Prepay & send buys the stamps with whichever wallet flavor your session runs — the in-page wallet signs directly; an external Phantom/Ledger wallet approves the same purchase built unsigned — and, once the purchase confirms, automatically re-sends the held draft, bounty and reply linkage included. Whether the purchase opens the frombox or tops it up is decided by a fresh chain read at click time, exactly like frombox stamp’s create-on-first-purchase. That same read sets the purchase’s price ceiling at the per-stamp postage the card quoted you, so a recipient repricing between the quote and the click makes the buy refuse rather than overcharge — and your draft is still held. A purchase still pending past the poll budget does not auto-retry (it would only bounce off the stamps check) — the card keeps the draft and says to send again shortly. The Balances pane remains the standing place to buy stamps outside a compose, and its purchases ride both signing flavors too, exactly like this card’s own Prepay & send: the in-page wallet signs directly, an external Phantom/Ledger wallet approves the same purchase built unsigned.

The receipt line carries the on-chain message id and transaction signature. There is no Sent folder in this mode — the on-chain message account is the record.

The pin lifecycle caveat (operators, read this)

A body pinned by a trustless client sits outside any mail server’s pin lifecycle. When mail is deleted or settled, a sithbitd operator’s pipeline releases the pin its own delivery made — it has no idea your daemon holds a client-made pin for the same message, and it will never unpin it. The client’s pin is the client’s lifecycle, exactly like the per-recipient pin providers’ standing rule that settlement releases the operator’s pin, never yours: a client-pinned body stays on the daemon it was pinned to until someone removes it there.

So an operator offering a pin service to trustless webmail users is signing up to store senders’ outbound bodies indefinitely, on a surface browsers can write to. Treat it accordingly: set the daemon’s auth_token (the pin URL settings take a bearer token) or put network isolation in front, mind the max_pin_bytes cap, and own the retention story — sweeping stale client pins is your policy, because no protocol sweep will do it.

The live proof

webclients/shared/test/e2e-noapi.test.js is this chapter runnable: the seeded dev validator plus one sithbit-ipfsd, no account-api and no mail server, driving the real wasm bundle through enumeration, the postage affordance, a client-pinned send, and the recipient’s trustless read-back. The env-gated runbook is in the file header.

The Chrome extension

An installable Chrome MV3 extension for using a SithBit account from the browser: wallet login, the onboarding wizard, aliases, balances, do-not-disturb schedules, delegated encryption-key management, and an in-popup mail reader — the same shared panes the Thunderbird, Outlook, and webmail clients carry, because all four hosts run the same shared core (webclients/shared/). Everything that must be signed is signed inside the extension by a WebAssembly module compiled from this workspace’s own crates; the server only relays already-signed transactions and never holds your key.

It reads mail two ways, exactly as webmail does. When an account-api is reachable it shows the full three-pane reader — folder rail, message list, message view, compose, and search — over the API’s /v1/mail surface. With the mail server down (or no account API configured at all), it falls back to a trustless on-chain inbox: your mailbox’s messages listed straight from Solana and read by unsealing their IPFS-stored bodies in wasm, no server involved. You can still also point any IMAP/ POP/SMTP mail client at the same account. Either way this same surface also runs in Chrome’s side panel, a persistent panel that stays open as you browse (the toolbar-icon click still opens the transient popup; an Open in side panel button promotes it). It is not a Gmail integration — it is a self-contained SithBit mail client, packaged as a browser extension.

What you need from your operator

Nothing, to start: the extension installs on your own machine. The panes that read the chain — aliases, balances, encryption keys — do need your operator’s account-api to have its chain surface configured, and report themselves unavailable when it does not; login and the settings panes keep working either way. The trustless on-chain inbox needs no operator at all, only a Solana RPC endpoint and an IPFS gateway you set under Connection settings — which is why it is the reader you get with the account API url left blank.

Operators: what to configure is Serving the browser clients.

Installing from the store

Once the extension is published, install it from the Chrome Web Store: open _todo_store_listing_url_ (or search the store for _todo_store_listing_name_) and click Add to Chrome. Store installs update automatically.

Note: the extension is not yet published to the Chrome Web Store. The _todo_store_listing_name_ and _todo_store_listing_url_ placeholders resolve when the listing goes live; until then, install via Building and installing below.

For pre-release distribution the Web Store offers two non-public visibilities — Unlisted (installable by direct link, never surfaced in search) and Private (restricted to a trusted-tester group or a Google Workspace domain) — plus draft sharing with trusted testers, so a pre-GA listing can exist without public exposure. The load-unpacked path below remains the zero-store development route.

Building and installing

Until the store listing is live this is how you install the extension — building it yourself, from this workspace:

cd webclients/chrome
./build.sh          # wasm-pack build + stages shared/ + zips the package

build.sh writes two things: a staging/ directory (the unpacked extension) and sithbit-chrome.zip (the same tree, packaged). Install it either way:

• Load unpacked (development). Open chrome://extensions, enable Developer mode, choose Load unpacked, and point it at webclients/chrome/staging.
• Packaged. Distribute or side-load sithbit-chrome.zip.

An extension package cannot reference files outside its own root, so the shared core and the wasm module are copied into staging/ at build time — always load staging/, never the source tree. The manifest requests the storage and sidePanel permissions and host permissions for http://127.0.0.1 / http://localhost by default, with https://* as an optional grant for pointing it at a remote API.

What it does

Opening the popup routes to one of a few views from the session it probes (see the onboarding wizard):

• Wallet manager — import more than one Solana keypair file (a JSON array of 64 numbers) into the same Chrome profile, each sealed under its own passphrase (PBKDF2 + AES-GCM), and unlock, switch between, lock, or forget them. Decrypted keys live only in memory and are gone when the browser exits, so each session re-prompts for the passphrases you want unlocked. One unlocked wallet is active at a time; every pane acts on it, and switching between already-unlocked wallets needs no passphrase.
• Onboarding wizard — a brand-new profile (no wallet stored) or an unlocked wallet with no mailbox drops straight into the shared five-step wizard: create or import a wallet, claim an optional handle, set your default postage, and mint your mailbox on-chain — the mailbox and its alias ride one signed transaction built in wasm.
• Dashboard panes — once unlocked and mailbox-registered, under the popup’s Mail / Account / Marketplace switch (the popup opens on Mail) and, in the Account view, the shared five-tab strip — Wallet, Mailbox, Names, Services, Sign-in, each with a half-second hover note — so the narrow popup fits without scrolling: Balances (wallet SOL, on-chain message count, per-sender stamp lookup, plus an outbound Quote that pins a purchase to the price it shows and a Reclaim unspent button for idle postage in a frombox of your own — see the webmail write-up of the same shared pane), Aliases (every alias pointing at your wallet; registration and transfer stay in the CLI), Domains (list a domain you hold for sale on the open marketplace, or buy a listed one by name and current authority; reassigning a domain’s authority is an operator action, not offered here), Reply bounties (settle reply bounties on-chain — claim one on a message you received and replied to, or refund one you placed that went unclaimed past its deadline), Pinning leases (escrow a refundable deposit asking operators to keep a message’s pinned body past the default retention — create a lease by the message’s CID and id, check a CID for your wallet’s lease, or close it anytime to reclaim the deposit; see pinning leases), Encryption key (publish, rotate, or close a delegated X25519 key; export the secret when it is shown — it appears once), Mailbox (claim your on-chain mailbox and set its registration config — an optional handle, the sending domain, the default postage unknown senders pay per stamp, and an on-chain-only (no IPFS) option; once registered it shows the message count and points per-sender price changes to Balances), Settings (the derived mail password for the active wallet and its IANA timezone), and Do not disturb (weekly or date-range retry windows). Close mailbox sits alongside them and is the one pane that does not act at once: closing runs a two-step, 7-day timelock, so the request only starts a clock — the mailbox stays open and keeps receiving mail, nothing is refunded, and a cancel is offered the whole time — and the rents come back only when you return after the wait and finish the close. Both reach your wallet for a mailbox you created yourself; a sponsored mailbox returns its mailbox rent to the sponsor instead, and the pane says so. The delay prices identity-cycling in time, since an instant refund made discarding a burned sending identity free.
• Mail — the shared three-pane reader (folder rail, message list, message view, compose, and search) over the account API’s /v1/mail surface. This is the primary in-popup reader, shown whenever an account API is reachable; it is the same reader webmail and the Outlook add-in mount.
• On-chain inbox — your mailbox’s messages listed newest-first straight from Solana, no mail server: open a row to read it in the Trustless viewer below. A KEPT pane in both modes, and — with the three-pane reader above — the whole of the in-popup mail experience when the mail server is down.
• Trustless viewer — reads a single on-chain message with nothing but a Solana RPC endpoint, any IPFS gateway, and your unlocked wallet, with the SithBit mail server completely down: pick a message from the On-chain inbox (or enter a mailbox message id) and the extension resolves the message account for its sealed-body CID, fetches the sealed bytes from the gateway, and unseals them in wasm. A wallet-only read only works if the body was sealed to your wallet — a recipient who published a delegated key needs that key’s secret instead. Its header also carries a Reply on-chain action — see Trustless reply and compose below. Once a body has rendered, a Lease this message button beside Reply prefills the Pinning leases pane (Account view, Services tab) with the open message’s CID and id — prefill only: you still review the deposit and submit, and entering a CID by hand works as before.
• Open in side panel — promotes the whole popup into Chrome’s persistent side panel, which stays open while you browse instead of closing on blur like the toolbar popup. It is the same app either way.
• Connection settings — where the popup points: the account API, the Solana RPC, the IPFS gateway, and — for trustless sending — the IPFS pin service. This popup never connects to the mail servers itself. They sit in a collapsed disclosure at the foot of every view, including first-run onboarding and the unlock gate — deliberately, and not merely for convenience: reaching them must never depend on being signed in, because signing in depends on the account API these settings configure. If the configured API is unreachable, the popup says so and continues, so you can correct the URL — or blank it to run trustlessly — from where you already are.

Trustless reply and compose

Reading is no longer the trustless surface’s whole story: the Trustless viewer’s header carries a Reply on-chain button, and the popup mounts the same floating on-chain compose card as trustless webmail — a Compose on-chain button opens it blank; Reply seeds it with the decrypted sender and the parent message’s account address. The card is always available (it rides the on-chain path, not the account API) and follows the webmail card’s lifecycle exactly: resolve the recipient and their published key on-chain, seal in the extension’s wasm module, pin the sealed bytes to your configured IPFS pin service, then sign and submit the SendMail transaction. The same seam ships in the Thunderbird extension and the Outlook add-in.

A reply sent this way is an on-chain send, not an SMTP compose: it never touches an outgoing mail server, and the operator’s SMTP/IMAP/spooler pipeline plays no part in delivery — the reply lands as an on-chain message account even while those servers are down. Chain reads, sealing, and pinning go straight to your configured endpoints; the transaction is signed in the extension’s wasm module like every other on-chain action here, and as always nothing the popup talks to can alter what you sign (see Security notes).

The card carries webmail’s three affordances, documented in full there rather than restated here:

• The reply chip — the draft threads to the parent message with the same privacy-preserving linkage --reply-to makes (only its blake3 hash reaches the chain); Clear drops the link and keeps the draft. See Replying, and attaching a bounty.
• Attach a reply bounty — an amount in SOL (blank = plain send) and a claim window in days escrow SOL on the message exactly like --bounty/--bounty-window.
• Inline prepay — no frombox toward the recipient yet? The card holds the draft, quotes the postage (live per-stamp protocol fee included), and Prepay & send buys the stamps then re-sends the held draft once the purchase confirms — the same prepayment rule and behavior as webmail’s card. The Balances pane remains the standing place to buy stamps outside a compose.

Sending needs one endpoint reading does not: Connection settings gains an IPFS pin service URL (ipfsPinUrl, default http://127.0.0.1:8182 — an unauthenticated loopback sithbit-ipfsd) plus its optional bearer token (ipfsPinToken, default empty), where outbound sealed bodies are pinned. As with a remote API origin, saving a non-loopback pin URL prompts for that origin’s host permission on the same Save click — the extension ships with loopback-only host permissions. Operators offering that pin surface should read the pin lifecycle caveat: a client-made pin sits outside any mail server’s pin lifecycle.

Configuration

There is no hosted config: the endpoints live in chrome-store (backed by chrome.storage.local) under the Connection settings pane, each with a loopback dev default so a fresh install runs against a local stack with nothing to set —

• apiUrl — the account API (default http://127.0.0.1:8180).
• rpcUrl — the Solana JSON-RPC endpoint for trustless viewing (default a local surfpool at http://127.0.0.1:8899).
• gatewayUrl — the IPFS gateway serving GET /ipfs/{cid} (default http://127.0.0.1:8183 — e.g. a sithbit-gateway).
• ipfsPinUrl — the IPFS pin service that receives the sealed body on a trustless send (default http://127.0.0.1:8182 — an unauthenticated loopback sithbit-ipfsd).
• ipfsPinToken — the optional bearer token for that pin service (default empty — the loopback default needs no auth).

Security notes

• The wallet secret at rest is exactly as strong as your passphrase.
• The session token authorizes account changes (password, timezone, DND) for up to 24 hours; on-chain actions additionally require the unlocked wallet, which never survives a browser exit.
• The API relay cannot alter what you sign: transactions are built from the workspace’s own instruction encoders compiled to wasm, and a parity test pins them byte-for-byte to the CLI’s.

The Outlook add-in

An Office.js taskpane add-in for self-service on a SithBit account: wallet login, mail password, timezone, do-not-disturb schedules, aliases, balances, and delegated encryption-key management — the same panes as the Thunderbird extension, because both hosts run the same shared core (webclients/shared/). Everything that must be signed is signed inside the pane by a WebAssembly module compiled from this workspace’s own crates; the server only relays already-signed transactions and never holds your key.

Runs in new Outlook on Windows and Outlook on the web via the unified JSON manifest. On classic Windows desktop Outlook the add-in installs via its XML manifest instead (build.sh renders it to package/manifest.xml), and Lockbox sealing is not available at send time there: the classic send runtime gives the hook no module loading and no network access, so the send hook states that sealing is unavailable and lets your message send exactly as you typed it. Not Outlook for Mac — the unified JSON manifest doesn’t run there; the same legacy XML manifest route is the recorded fallback.

What you need from your operator

An Office add-in is an https-hosted web page, so the pane itself is served by your operator’s account-api — you will be given that origin, and the manifest you sideload below points at it. As with Thunderbird, the aliases, balances, and encryption-key panes need that API’s chain surface configured; login and the settings panes work without it.

Operators: what to serve and how to mount it is Serving the browser clients.

Installing from the store

Once the add-in is published, install it from Microsoft Marketplace (formerly Microsoft AppSource): in Outlook open Apps → Get Add-ins and search for _todo_store_listing_name_, or open _todo_store_listing_url_ in a browser and choose Get it now. Store installs update automatically.

Note: the add-in is not yet published to Microsoft Marketplace. The _todo_store_listing_name_ and _todo_store_listing_url_ placeholders resolve when the listing goes live; until then, install via Building and sideloading below.

Microsoft Marketplace listings are public-only and Microsoft-validated — there is no unlisted tier. The supported private paths are sideloading (the atk flow below) and Microsoft 365 admin center → Integrated Apps → Upload custom app, which deploys the add-in privately to a whole tenant — the de-facto org-wide pre-release deployment.

Building and sideloading

Until the marketplace listing is live this is how you install the add-in — building the package yourself, from this workspace:

cd webclients/outlook
./build.sh    # wasm-pack build + stages shared/ into staging/ + packages sithbit-outlook.zip

Sideload sithbit-outlook.zip with the Agents Toolkit CLI (atk auth login m365, then atk install --file-path sithbit-outlook.zip) or via Teams → Apps → Upload a custom app. The Outlook-web “Add-Ins” upload dialog accepts only XML manifests — use one of the two paths above. On classic Windows desktop Outlook, sideload the rendered package/manifest.xml instead (aka.ms/olksideload → My add-ins → Add a custom add-in → Add from file) — that XML manifest is what carries the add-in there. The full dev runbook, including the localhost-https trust step, lives in webclients/outlook/README.md.

First run and onboarding

The first time you open the pane in a browser profile with no wallet stored yet, it opens on the shared five-step onboarding wizard instead of the wallet manager. It creates or imports a wallet (the create branch shows your secret key once, with the save it — it is the only copy gate), claims an optional handle, sets your default postage, and mints your mailbox on-chain — mailbox plus, if claimed, its alias in one transaction, signed in the pane’s wasm module and relayed through /v1/chain. Until it finishes, the pane shows only the wizard.

The pane routes to one of four views from the session it probes on open:

• Onboarding wizard — no wallet stored yet, or an unlocked wallet with no mailbox (a returning user finishing setup).
• Unlock — a stored wallet that is locked this run; the shared wallet-list pane below owns the passphrase prompt.
• Dashboard — unlocked and mailbox-registered: the normal panes.
• (a brief loading view while it probes.)

The add-in needs no endpoint configuration for onboarding: because the bundle is served same-origin from account-api, it infers the API base URL from the page’s own origin, and the onboarding create relays through that same API. Only the optional trustless fallback and its on-chain compose read endpoints of their own (RPC, IPFS gateway, and pin service, from localStorage).

Using it

Select any message and open Apps → SithBit Account (the pane is pinnable, so it stays open as you move around). The pane opens on a wallet manager, not a single-account gate: paste a Solana keypair file and choose a passphrase to import it — the key is encrypted with that passphrase before it is stored in the browser’s storage — and repeat for as many SithBit addresses as you want available in this browser profile. Each is unlocked with its own passphrase (needed again each time the taskpane opens), several can stay unlocked at once, and switching which one is active needs no passphrase. The settings, DND, aliases, balances, mail view, and delegated-key panes all act on the active wallet, each on-chain action signed client-side in wasm and relayed through /v1/chain. As with Thunderbird, each address still needs its own native Outlook mail account — Office.js add-ins run inside an already-configured mailbox and have no API to provision one.

Every flow above is exercised headlessly by the env-gated live suite webclients/outlook/test/e2e-outlook.test.js — the bundle served from a real account-api, login and settings through the real storage adapters, and the key lifecycle confirmed on-chain.

Panes

The taskpane mounts the same shared dashboard the other clients do, so the pane set — and its five-tab strip (Wallet / Mailbox / Names / Services / Sign-in, with a half-second hover note on each tab) — is identical to Thunderbird’s. The taskpane’s own Mail / Settings / Marketplace buttons pick the view; the panes are the Settings view.

• Balances — wallet SOL, the on-chain mailbox message count, and a per-sender stamp lookup (stamps are held per sender, so there is no single total). Outbound, Quote shows the live per-stamp price toward a recipient and pins the purchase to it; Reclaim unspent takes idle postage back out of a frombox of your own — see the webmail write-up, which describes the same shared pane.
• Aliases — the aliases pointing at the active wallet. Registering and transferring them stays in the CLI.
• Domains — list a domain you hold for sale on the open marketplace, or buy a listed one by name and current authority. Reassigning a domain’s authority is an operator action, not offered here.
• Reply bounties — settle reply bounties on-chain: claim one on a message you received and replied to (bountied message id, original sender, your reply’s id), or refund one you placed that went unclaimed past its deadline.
• Pinning leases — escrow a refundable deposit asking operators to keep a message’s pinned body past the default retention (pinning leases): create one by the message’s CID and id (deposit prefills to the protocol minimum; a one-time fee applies), check a CID for your wallet’s lease, or close it anytime to reclaim the deposit — even after the message has settled. The trustless fallback reader’s Lease this message button (beside Reply, shown once a body has rendered) prefills this pane’s create fields with the open message’s CID and id, switches the taskpane to the settings view (a plain view switch — the taskpane keeps no history) and opens the panes’ Services tab; you still review the deposit and submit, and manual CID entry works as before.
• Encryption key — publish, rotate, or close a delegated X25519 key, signed in wasm and relayed through /v1/chain. Export the secret while it is on screen — it is shown once, and mail sealed to an old key still needs that key.
• Settings — the derived mail password for the active wallet (see The mail password below) and its IANA timezone.
• Do not disturb — weekly or date-range windows in which senders are asked to retry later, evaluated in your timezone.
• Mailbox — claim your on-chain mailbox and set its registration config: an optional handle (claimed as an alias in the same transaction), the sending domain (blank uses sithbit.com), the default postage unknown senders pay per stamp, and an on-chain-only (no IPFS) option. Once registered the pane shows the message count and points per-sender price changes to the Balances pane.
• Close mailbox — request, cancel, or finish closing the mailbox. This one is not instant: the request starts a fixed 7-day wait and refunds nothing, the mailbox stays open and keeps receiving mail meanwhile, and the pane offers Cancel for the whole period. Only after the clock runs out does finalizing become available, closing the mailbox and returning its rent and the transient request record’s — both to your wallet for a mailbox you created yourself, while a sponsored mailbox sends the mailbox rent back to the sponsor that funded it and leaves you the request record’s. The pane says which happened. The wait exists because an instant refund made discarding a burned sending identity free; it costs an honest owner time on a rare action, not money. The Encryption key close above is unaffected and stays instant.

Zero-config setup (autodiscover)

If the operator runs the domain-sithbit service, Outlook’s native Add Account flow can fill in the IMAP/ POP/SMTP connection settings for you — no add-in, no hand-typed servers. Type your address as <wallet-base58>@<domain>; Outlook POSTs it to the domain’s autodiscover endpoint and auto-fills the servers, ports, and TLS modes from the operator’s advertised coordinates.

Two limits, by design:

• It does not create the account. Autodiscover fills in connection settings only; native account auto-provisioning is deliberately not offered. Your mailbox must already exist on-chain (sithbit mailbox create) before you connect.
• It does not set your password. The login name is auto-filled as your wallet address (the base58 public key — the @domain is not leaked), but you still supply a mail password. Get it from the operator’s self-serve enrollment page (/addin/enroll.html on the account API) or offline from the CLI — see The mail password just below.

Where the operator hasn’t enabled autodiscover, enter the same settings by hand; the username and password rules are identical.

The mail password

Like the Thunderbird extension, your IMAP/POP/SMTP client authenticates as your wallet with no separate stored password. The “mail password” is a wallet signature over a fixed challenge that the servers verify against your wallet address; nothing is stored server-side, so a password on the account is now optional (see the account API).

Get the credential for the active wallet from the Settings pane’s Copy mail password button, or offline from the CLI:

sithbit mailbox credentials --keypair ~/.config/solana/id.json

The same pane’s Rotate the wallet mail password… button retires it when you need to: a two-step control that bumps your account’s auth epoch, so every copy of the old password — this add-in’s included, until you copy the new one — stops authenticating at once, and the CLI derives the replacement with sithbit mailbox credentials --epoch <N>. It rotates the wallet-derived password alone; a stored mail password, your session, and a client-certificate login are unaffected. See Rotating the wallet mail password.

Rotation is step-up gated: the server refuses it with 428 Precondition Required until the request carries a wallet signature made seconds ago, so a live session alone cannot change your mail credentials. The pane answers that for you — it fetches the challenge and has your wallet sign it, which is the approval prompt a Phantom or Ledger wallet raises — and what surfaces in the add-in is only the case where no signature could be produced (locked or disconnected wallet, declined prompt, stale challenge): “This change needs a fresh wallet signature. Make sure your wallet is unlocked (or reconnected) and try again.” Do exactly that — unlock or reconnect, arm the control again, approve the prompt. Waiting achieves nothing, because every attempt spends its own challenge and needs its own signature; and a refused rotation leaves the epoch and the password this add-in already holds untouched. Offline, the same signer is sithbit mailbox sign-text, signing the challenge string with --keypair.

Enter it in your mail client as username = your wallet address (base58 public key), password = the derived base58 signature, mechanism = SASL PLAIN over TLS (the signature is bearer-equivalent, so always use TLS). This is the tested path for reading mail (POP3/IMAP retrieval); wallet-authenticated submission authenticates identically, and its envelope sender is fixed to exactly your own wallet address at a domain the submission server serves — and, when that server is connected to the chain, one your wallet also owns on-chain (the domain’s recorded authority), not merely any domain the server happens to serve. Set the Outlook account’s email address to <wallet-base58>@<the operator's domain>, the same string the add-in POSTs to autodiscover. Another wallet’s address, your address at a domain that server does not serve (or, on a chain-connected server, that your wallet does not own on-chain), and a case-variant of your own base58 (base58 is case-sensitive, so the match is exact) are each refused 553 5.7.1; the Thunderbird page and the configuration reference carry the full rule and the chain-less-dev-stack gotcha. Regenerating the credential is free and offline.

Client-certificate login (SASL EXTERNAL)

The passwordless alternative to the mail password above, exactly as on Thunderbird: instead of pasting a signature, you hand your mail client a TLS client certificate minted from your wallet, and the server authenticates you over the TLS handshake — no password entered, nothing stored server-side. It requires client_cert_auth on the listener (see the configuration reference).

1. Mint the certificate — offline, no RPC:

   sithbit mailbox create-cert --keypair ~/.config/solana/id.json --out sithbit
   

   This writes sithbit.p12 — the combined, password-less PKCS#12 bundle meant for your certificate store’s import dialog — alongside sithbit.crt and its PKCS#8 key sithbit.key as a PEM pair for other apps (omit --out to print just the PEM blocks to stdout). The certmgr / Keychain import in step 2 hasn’t been walked end-to-end here yet; Thunderbird’s own certificate store is known to refuse this bundle — see the known issue. The certificate is a self-signed Ed25519 leaf whose public key is your wallet address — no CA, no expiry to manage. The .p12 and .key embed your wallet secret; guard them like the wallet itself.

2. Install it. The Office.js taskpane above manages only the account settings, not the mailbox’s IMAP/POP/SMTP transport, so a client certificate is configured in the host mail app, not the add-in. In classic Outlook that is File → Options → Trust Center → Email Security → import your certificate — pick sithbit.p12 and leave the password prompt blank (the bundle is password-less) — then attach it on the account’s outgoing/incoming server security settings; on new/web Outlook the certificate is selected by the OS/browser certificate store when the server requests one. Set each of the account’s SMTP, IMAP, and POP entries to SSL/TLS and select this certificate as the client certificate.

3. Leave the password blank — with EXTERNAL the certificate is the whole credential; keep your wallet address as the username.

The add-in mints the same files without the CLI: the taskpane’s settings view carries a Certificate sign-in section on the panes’ Sign-in tab, whose Download client certificate button derives everything in the wasm module and saves three files named after your wallet address: the combined <pubkey>.p12 first, then the <pubkey>.crt / <pubkey>.key PEM pair for other apps — byte-for-byte what sithbit mailbox create-cert writes. Importing stays manual as in step 2 — an Office add-in cannot touch the OS certificate store — so bring the .p12 into certmgr on Windows or Keychain Access on macOS (or your mail app’s own certificate settings) — the same import caveats as step 1 apply. The .p12 and .key files embed your wallet secret; guard them like the wallet itself. The button needs a wallet unlocked in the add-in’s wasm module: while every wallet is locked it is disabled, and an external signer (a Phantom or Ledger wallet) reads as locked too — it holds no local seed to derive from, so external-wallet users stay on the CLI path above.

Regenerate and reinstall it freely; it carries no secret beyond your wallet key, which never leaves your machine — the derivation is fully deterministic per wallet, so re-downloading on any device yields the identical certificate.

Trustless (server-down) viewing

The taskpane wires two read paths. The primary one is the server mail view over account-api’s /v1/mail surface (the same three-pane reader the webmail app shows). Behind it sits a trustless fallback that reads a message straight from a Solana RPC endpoint and an IPFS gateway with the mail server down: it resolves the message’s on-chain account for its sealed-body CID, fetches the sealed bytes from the gateway, unseals them in wasm with your unlocked wallet, and renders the MIME — HTML in a fully sandboxed frame that blocks scripts and remote loads. The fallback is a no-op until the wallet is unlocked.

Its two endpoints come from localStorage and default to the dev stack: the Solana RPC (config.rpcUrl, default the local surfpool at http://127.0.0.1:8899) and the IPFS gateway (config.gatewayUrl, default http://127.0.0.1:8183 — e.g. a sithbit-gateway). Paste a bare URL into either key to point the fallback at a remote endpoint.

The same two caveats as the Thunderbird extension apply:

• A wallet-only read only works if the body was sealed to your wallet; a recipient who published a delegated encryption key needs that delegated secret instead.
• Under the default [spooler.settle] auto-settle worker a settled message is unpinned past its window (keep_pin = false), so trustlessly reading an old, settled message depends on the operator having kept the pin (keep_pin = true).

Trustless reply and compose

Viewing is no longer the fallback’s whole surface: the trustless reader’s header carries a Reply on-chain button, and the mail view mounts the same floating on-chain compose card as trustless webmail — a Compose on-chain button opens it blank; Reply seeds it with the decrypted sender and the parent message’s account address. The card is always available (the taskpane has no trustless mode to switch into) and follows the webmail card’s lifecycle exactly: resolve the recipient and their published key on-chain, seal in the pane’s wasm module, pin the sealed bytes to your configured IPFS pin service, then sign and submit the SendMail transaction. The same seam ships in the Thunderbird extension.

A reply sent this way is an on-chain send, not a host SMTP compose: it never touches the Outlook account’s own outgoing server, and the operator’s SMTP/IMAP/spooler pipeline plays no part in delivery — the reply lands as an on-chain message account even while those servers are down. Chain reads, sealing, and pinning go straight to your configured endpoints; the signed transaction is relayed through account-api’s /v1/chain like every other on-chain action in the pane, and as always the relay cannot alter what you sign.

The card carries webmail’s three affordances, documented in full there rather than restated here:

• The reply chip — the draft threads to the parent message with the same privacy-preserving linkage --reply-to makes (only its blake3 hash reaches the chain); Clear drops the link and keeps the draft. See Replying, and attaching a bounty.
• Attach a reply bounty — an amount in SOL (blank = plain send) and a claim window in days escrow SOL on the message exactly like --bounty/--bounty-window.
• Inline prepay — no frombox toward the recipient yet? The card holds the draft, quotes the postage (live per-stamp protocol fee included), and Prepay & send buys the stamps then re-sends the held draft once the purchase confirms — the same prepayment rule and behavior as webmail’s card. Settings → Balances remains the standing place to buy stamps outside a compose.

Sending needs one endpoint viewing does not: the connection-settings pane gains an IPFS pin service URL (config.ipfsPinUrl, default http://127.0.0.1:8182 — a sithbit-ipfsd) plus its optional bearer token (config.ipfsPinToken, default empty), where outbound sealed bodies are pinned. Operators offering that pin surface should read the pin lifecycle caveat: a client-made pin sits outside any mail server’s pin lifecycle.

The Thunderbird extension

A MailExtension for self-service on a SithBit account: wallet login, mail password, timezone, do-not-disturb schedules, aliases, balances, and delegated encryption-key management. Everything that must be signed is signed inside the extension by a WebAssembly module compiled from this workspace’s own crates — the server only relays already-signed transactions and never holds your key.

Requires Thunderbird 140 or later.

What you need from your operator

Only an account-api to point the extension at — there is nothing for an operator to host, since a MailExtension installs from a file on your own machine. For the aliases, balances, and encryption-key panes that API needs its chain surface configured, and reports those panes as unavailable when it does not; login and the settings panes keep working either way.

Operators: what to configure is Serving the browser clients.

Installing from the store

Once the extension is published, the one-click route is addons.thunderbird.net (ATN): search for _todo_store_listing_name_ in the Add-ons Manager (gear menu → Add-ons and Themes) and install it directly from the search results, or open _todo_store_listing_url_ in a browser and install from the listing page. Store installs update automatically.

Note: the extension is not yet published to addons.thunderbird.net. The _todo_store_listing_name_ and _todo_store_listing_url_ placeholders resolve when the store listing goes live; until then, install via Building and installing below.

Thunderbird MailExtensions need no signing, so self-distributing the .xpi — the build path below — is a fully supported permanent channel, not a workaround. ATN listings are public-only (no unlisted or private tier), which makes the store listing an optional later step rather than a pre-release necessity.

Building and installing

With no store listing yet — and none needed, per the note above — this is the install route: build the .xpi yourself, from this workspace.

cd webclients/thunderbird
./build.sh          # wasm-pack build + stages shared/ + zips the xpi

Install sithbit-thunderbird.xpi via Thunderbird’s Add-ons Manager (gear menu → Install Add-on From File). Thunderbird accepts self-built, unsigned xpi files permanently — no store listing is needed. For development, point Load Temporary Add-on (Tools → Developer Tools → Debug Add-ons) at thunderbird/staging/manifest.json.

The extension ships with host permissions for http://localhost / http://127.0.0.1 only. Pointing it at a remote API (extension options) prompts for that origin’s permission when you save.

First run and onboarding

Opening the SithBit dashboard for the first time — with no wallet stored in this Thunderbird profile yet — drops you straight into the shared five-step onboarding wizard rather than the wallet manager. It creates or imports a wallet (the create branch reveals your secret key once, with the save it — it is the only copy gate), claims an optional handle, sets your default postage, and mints your mailbox on-chain — the mailbox and, if you claimed a handle, its alias ride one signed transaction, built and signed in the extension’s wasm module. Until it finishes, the dashboard shows only the wizard.

The dashboard routes to one of four views from the session it probes on open:

• Onboarding wizard — no wallet stored yet, or an unlocked wallet with no mailbox (a returning user finishing setup).
• Unlock — a stored wallet that is locked this run; the shared wallet-list pane below owns the passphrase prompt.
• Dashboard — unlocked and mailbox-registered: the normal panes.
• (a brief loading view while it probes.)

The onboarding relay and the trustless endpoints all come from the extension’s options page, not from any hosted config: the account-API origin (which also prompts for its host permission when you save a remote one), the Solana RPC (config.rpcUrl), the IPFS gateway (config.gatewayUrl), and — for the on-chain compose — the IPFS pin service (config.ipfsPinUrl plus its bearer token), each defaulting to the local dev stack. See Trustless (server-down) viewing for the read-path endpoint defaults.

Wallets and their passphrases

The SithBit button in the spaces toolbar opens a wallet manager, not a single-account gate — you can import more than one Solana keypair file (a JSON array of 64 numbers) into the same Thunderbird profile, each under its own passphrase, and unlock several of them at once. Every imported wallet is encrypted with its passphrase (PBKDF2 + AES-GCM) before it is stored in the Thunderbird profile; decrypted keys live only in memory and are gone when Thunderbird exits, so each restart asks for the passphrase again for whichever wallets you want unlocked this session.

Unlocking a wallet is a login challenge: the API issues a nonce, the extension signs it with that wallet, and a day-long session token comes back. No password ever exists for login — the wallet is the account. One unlocked wallet at a time is active; the settings, balances, aliases, keys, and trustless-viewer panes all act on whichever wallet is active, and switching between already-unlocked wallets needs no passphrase. This lets one profile manage several SithBit addresses (e.g. a personal one and a work/domain one), but each address still needs its own separate account added through Thunderbird’s native Add Mail Account wizard — Thunderbird’s stable extension API has no way to create that account programmatically (see The mail password below for what to enter there).

Panes

Since v0.86.0 the panes sit under a five-tab strip so the dashboard fits without scrolling: Wallet (Balances, Encryption key), Mailbox (Mailbox, Do not disturb, Close mailbox), Names (Aliases, Domains), Services (Reply bounties, Pinning leases) and Sign-in (Settings — the mail password — plus the certificate and connection sections described below). Hovering a tab for half a second shows a one-line note of what it holds. Above the strip, a Mail / Account / Marketplace switch picks the view; the panes are the Account view. The dashboard opens on Account — Thunderbird itself reads your server mail — and the Mail view holds the on-chain viewer and composer.

• Balances — wallet SOL, on-chain mailbox message count, and a per-sender stamp lookup (stamp balances are held per sender, so there is no single “total stamps” number). Outbound, Quote shows the live per-stamp price toward a recipient and pins the purchase to it; Reclaim unspent takes idle postage back out of a frombox of your own — see the webmail write-up, which describes the same shared pane.
• Aliases — every alias pointing at your wallet. Registration and transfer stay in the CLI.
• Domains — list a domain you already hold for sale on the open marketplace, or buy one that’s listed by name and current authority. Reassigning a domain’s authority is an operator action and isn’t offered here. Needs the unlocked wallet.
• Reply bounties — settle reply bounties on-chain: claim one on a message you received and replied to (giving the bountied message’s id, the original sender, and your reply’s id), or refund a bounty you placed that went unclaimed past its deadline.
• Pinning leases — escrow a refundable deposit asking operators to keep a message’s pinned body past the default retention (pinning leases). Create a lease by the message’s CID and id — the recipient defaults to your own mailbox, the deposit prefills to the protocol minimum, and a one-time creation fee applies — then check whether your wallet holds a lease on a CID, or close it anytime to reclaim the deposit. Closing works even after the message itself has settled: the lease is addressed by the CID, not the message. The trustless reader further down this dashboard carries a Lease this message button beside Reply (shown once a body has rendered) that prefills this pane’s create fields with the open message’s CID and id — prefill only, so the deposit is still yours to review and submit, and typing a CID by hand works as before.
• Encryption key — publish, rotate, or close a delegated X25519 key. The transaction is built and signed in the extension’s wasm module and relayed through the API. Export the secret when it is shown — it appears exactly once, in the same JSON format sithbit mail get --delegated-key-path reads; mail sealed to an old key still needs that old key’s secret, so keep every export.
• Settings — mail-client credentials for the active wallet (see The mail password below) and its IANA timezone. The pane’s Copy mail password button derives the wallet-signature credential for you, so you never have to run the CLI.
• Do not disturb — weekly or date-range windows during which senders are asked to retry later, evaluated in your timezone.
• Mailbox — where you claim your on-chain mailbox and set its registration config: an optional handle (claimed as an alias in the same transaction), the sending domain (blank uses sithbit.com), the default postage — the per-stamp price unknown senders pay to reach you — and whether to store bodies on-chain only (opting out of IPFS). Once the mailbox is registered the pane shows the received-message count and sends you to the Balances pane to adjust per-sender prices.
• Close mailbox — request, cancel, or finish closing your mailbox. Closing is not instant: the request opens a fixed 7-day wait during which the mailbox stays open, keeps receiving mail, and refunds nothing. The pane shows the remaining time and offers Cancel throughout — cancelling leaves the mailbox exactly as it was — and only once the clock has run does the finalize button appear, closing the mailbox and returning its rent and the transient request record’s. Both come back to your wallet for a mailbox you created yourself; for a sponsored mailbox the mailbox rent returns to the sponsor who funded it and you keep the request record’s, which the pane states when it happens. The wait is deliberate: an instant refund made discarding a burned sending identity free, so the cost of leaving is time on a rare action rather than money. It does not apply to the Encryption key close above, which stays instant on purpose.

Zero-config setup (autoconfig)

If the operator runs the domain-sithbit service, Thunderbird can fill in all the IMAP/ POP/SMTP connection settings for you — no plugin, no hand-typed hostnames. In the native Account Setup wizard (File → New → Existing Mail Account), enter your address as <wallet-base58>@<domain> and Thunderbird fetches the server settings from the domain’s Mozilla autoconfig document and auto-fills them.

Two things the wizard does not do, by design:

• It does not create the account. Autoconfig fills in connection settings only; native account auto-provisioning is deliberately not offered. Your mailbox must already exist on-chain (sithbit mailbox create) before you connect.
• It does not set your password. The username is auto-filled as your wallet address (the base58 public key — the @domain is dropped), but you still supply a mail password. Get it either from the self-serve enrollment page the operator hosts (/addin/enroll.html on the account API) or offline from the CLI — see The mail password just below. Then finish the wizard.

If the operator hasn’t enabled autoconfig, enter the same settings by hand — the username and password rules are identical, and the mail-server coordinates are whatever the operator advertises (standard IMAPS 993 / POP3S 995 / submission 587 by default).

The mail password

Your IMAP/POP/SMTP client authenticates as your wallet with no separate stored password: the “mail password” is a signature your wallet produces over a fixed challenge, which the servers verify against your wallet address. Nothing is stored server-side — the signature is self-proving — so you never “set” a password on the account (see the account API, where a stored password is now optional).

Two ways to get the credential:

• In the extension — the Settings pane’s Copy mail password button derives it in the wasm module and copies it to your clipboard.

• On the command line — run:

  sithbit mailbox credentials --keypair ~/.config/solana/id.json
  

  which prints the pair offline (no RPC, no on-chain write).

Because the signature is deterministic it never expires either, so the credential comes with a way to retire it: the same Settings pane’s Rotate the wallet mail password… button, a deliberate two-step that adds one to your account’s auth epoch and with it changes the bytes a valid password signs over. Every copy of the old password stops working at once — including the one in this extension, until you copy the new value — and the CLI takes the epoch as an argument (sithbit mailbox credentials --epoch <N>). It rotates the wallet-derived password and nothing else: a stored mail password, your signed-in session, and a client-certificate login all survive it untouched. The full walk-through, with the warning the control shows before it commits, is on the webmail page — the pane is the same one.

A rotation can also be refused, and that is the design rather than a fault: bumping the epoch is one of the account API’s step-up gated calls, so the server turns it down with 428 Precondition Required until the request carries a wallet signature made seconds ago — a live session on its own may not change your mail credentials. Usually you never meet the 428: the pane answers it for you, fetching the challenge and asking your wallet to sign it, which is exactly the approval prompt a Phantom or Ledger wallet raises at that moment. What reaches you is the case where no signature could be produced — a locked or disconnected wallet, a declined prompt, a challenge that went stale — and the pane says so in one sentence: “This change needs a fresh wallet signature. Make sure your wallet is unlocked (or reconnected) and try again.” Do that literally: unlock or reconnect the wallet, arm Rotate the wallet mail password… again, and approve the prompt when it appears. Waiting is not the remedy — each attempt spends its own challenge, so a fresh try needs a fresh signature, never the previous one — though it is worth not hammering the button either, since these mutations share a per-wallet budget that counts refused attempts too. A refused rotation changes nothing: the epoch stays where it was and the password already in this extension keeps working. From a shell the same proof is produced by sithbit mailbox sign-text, signing the challenge string with --keypair.

Enter it in your mail client as:

• Username — your wallet address (the base58 public key), exactly as the CLI prints it.
• Password — the derived base58 signature.
• Mechanism — SASL PLAIN over TLS (STARTTLS or implicit TLS). The signature is bearer-equivalent for the connection, so always use TLS.

This is the tested path for reading mail — POP3 and IMAP retrieval authenticate with the wallet signature end to end. Wallet-authenticated submission (sending) authenticates the same way, and the envelope sender you may present is fixed: exactly your own wallet address, at a domain the submission server is authoritative for — and, when that server is connected to the chain, one your wallet also owns on-chain (the domain’s recorded authority), not merely any domain the server serves. Set the account’s identity to <your-wallet-base58>@<the operator's domain> — the same address you typed as the username, with the operator’s mail domain — and sending works. Anything else is refused 553 5.7.1: another wallet’s address, your address at a domain that server does not serve (or, on a chain-connected server, that your wallet does not own on-chain), or a case-variant of your own base58 (base58 is case-sensitive, so Alice and alice are different keys and the match is exact). Copy the address from the CLI rather than retyping it. Regenerating the credential is free and offline — the wallet key never leaves your machine.

If your operator runs a chain-less dev stack and sends are refused 553 5.7.1 even though the address looks right, the server’s local_domains is the likely culprit — see Wallet submission envelopes.

Client-certificate login (SASL EXTERNAL)

The passwordless alternative to the mail password above: instead of a signature you paste as a password, you hand your mail client a TLS client certificate minted from your wallet, and the server logs you in over the TLS handshake itself — no credential typed, nothing stored on either side. The server must have client_cert_auth turned on for the listener (see the configuration reference); where it does, this and the mail password both work, so pick whichever your client handles best — though from Thunderbird itself this path is currently blocked by an import failure; see the known issue in step 2 below.

1. Mint the certificate — offline, no RPC:

   sithbit mailbox create-cert --keypair ~/.config/solana/id.json --out sithbit
   

   This writes sithbit.p12 — the combined, password-less PKCS#12 bundle, for mail clients whose certificate store takes one (Thunderbird itself currently cannot; see the known issue in step 2) — alongside sithbit.crt (the certificate) and sithbit.key (its PKCS#8 private key) as a PEM pair for other apps. Omit --out to print just the two PEM blocks to stdout instead. The certificate is a self-signed Ed25519 leaf whose public key is your wallet address, so it needs no CA and never expires into a renewal chore — regenerate it any time from the same keypair. The .p12 and .key files embed your wallet secret; guard them like the wallet itself.

2. Install it in Thunderbird — currently blocked by the known issue below. The intended path is importing sithbit.p12 under Settings → Privacy & Security → Manage Certificates → Your Certificates → Import — the bundle is password-less, so the password prompt is left blank — and then, on each of the account’s SMTP (outgoing), IMAP, and POP server entries, setting the connection security to SSL/TLS, the authentication method to Encrypted certificate, and selecting this certificate.

   Known issue: Thunderbird 140 ESR refuses this import, so SASL EXTERNAL from Thunderbird is effectively unusable until NSS (Thunderbird’s certificate store) accepts the key — sign in with the mail password above instead. Specifically: Your Certificates → Import rejects sithbit.p12 with “Failed to decode the file” (blank password given, as instructed), and re-encoding the same certificate and key into NSS’s preferred PKCS#12 shape (a sha256 MAC with a PBES2-shrouded key bag, still an empty password) gets past decoding but fails with “The PKCS #12 operation failed for unknown reasons” — consistent with NSS refusing to import an Ed25519 private key into its soft token, not merely disliking the bundle’s encoding. The .p12 and the sithbit.crt / sithbit.key PEM pair remain valid credentials for other mail clients — see Outlook for the Windows certificate-store path, for example.

3. Leave the password blank. With EXTERNAL there is no password to enter — the certificate is the whole credential. Use your wallet address as the username exactly as before.

No CLI at hand? The extension mints the identical files: the dashboard’s Account view carries a Certificate sign-in section on the panes’ Sign-in tab, whose Download client certificate button derives everything in the wasm module — no server involved — and saves three files named after your wallet address: the combined <pubkey>.p12 first (the PKCS#12 bundle for other clients’ certificate stores — Thunderbird itself currently cannot import it; see the known issue in step 2), then the <pubkey>.crt / <pubkey>.key PEM pair for other apps — byte-for-byte what sithbit mailbox create-cert writes. Importing stays manual exactly as in step 2 — a WebExtension has no way into Thunderbird’s certificate store, so the download is the whole affordance. The .p12 and .key files embed your wallet secret; guard them like the wallet itself. The button needs the active wallet unlocked in the extension’s wasm module: while every wallet is locked it is disabled, and an external signer (a Phantom or Ledger wallet) reads as locked too — it holds no local seed to derive from, so external-wallet users stay on the CLI path above.

Because the certificate carries no secret beyond your wallet key (which never leaves your machine), you can regenerate and reinstall it freely — the derivation is fully deterministic per wallet, so re-downloading on any device yields the identical certificate, and a fresh download never invalidates one already imported.

Trustless (server-down) viewing

The dashboard also carries a Read mail trustlessly pane — a read path that needs nothing but a Solana RPC endpoint, any IPFS gateway, and your unlocked wallet. It works with the SithBit mail server (account-api) completely down: enter a mailbox message id and the extension resolves that message’s on-chain account for its sealed-body CID, fetches the sealed bytes from the gateway, unseals them in the wasm module with your wallet, and renders the MIME. HTML bodies render in a fully sandboxed frame that blocks scripts and remote loads, exactly like every other reader here.

Two endpoints drive it, both set in the extension options and defaulting to the dev stack: the Solana RPC (config.rpcUrl, default the local surfpool at http://127.0.0.1:8899) and the IPFS gateway (config.gatewayUrl, default http://127.0.0.1:8183 — e.g. a sithbit-gateway). The pane relies on the messagesRead permission, already declared in the manifest.

Two caveats:

• A wallet-only read only works if the body was sealed to your wallet. A recipient who published a delegated encryption key had their mail sealed to that key instead, so the trustless read needs the delegated secret, not the wallet — the same secret sithbit mail get --delegated-key-path reads.
• The sealed IPFS copy is only fetchable while it stays pinned. Under the default [spooler.settle] auto-settle worker, a message settled past its window is unpinned (keep_pin = false), so a trustless read of an old, settled message depends on the operator having set keep_pin = true.

Trustless reply and compose

Reading is no longer the pane’s whole surface: the trustless reader’s header carries a Reply on-chain button, and the dashboard mounts the same floating on-chain compose card as trustless webmail — a Compose on-chain button opens it blank; Reply seeds it with the decrypted sender and the parent message’s account address. The card is always available (the dashboard has no trustless mode to switch into) and follows the webmail card’s lifecycle exactly: resolve the recipient and their published key on-chain, seal in the extension’s wasm module, pin the sealed bytes to your configured IPFS pin service, then sign and submit the SendMail transaction.

A reply sent this way is an on-chain send, not a Thunderbird compose: it never opens a compose window or touches the account’s outgoing SMTP server, and the operator’s SMTP/IMAP/spooler pipeline plays no part in delivery — the reply lands as an on-chain message account even while those servers are down. Chain reads, sealing, and pinning go straight to your configured endpoints; the signed transaction is relayed through the account API like every other on-chain action here, and as always the relay cannot alter what you sign (see Security notes).

The card carries webmail’s three affordances, documented in full there rather than restated here:

• The reply chip — the draft threads to the parent message with the same privacy-preserving linkage --reply-to makes (only its blake3 hash reaches the chain); Clear drops the link and keeps the draft. See Replying, and attaching a bounty.
• Attach a reply bounty — an amount in SOL (blank = plain send) and a claim window in days escrow SOL on the message exactly like --bounty/--bounty-window.
• Inline prepay — no frombox toward the recipient yet? The card holds the draft, quotes the postage (live per-stamp protocol fee included), and Prepay & send buys the stamps then re-sends the held draft once the purchase confirms — the same prepayment rule and behavior as webmail’s card. The Balances pane remains the standing place to buy stamps outside a compose.

Sending needs one endpoint reading does not: the options page gains an IPFS pin service URL (config.ipfsPinUrl, default http://127.0.0.1:8182 — a sithbit-ipfsd) plus its optional bearer token (config.ipfsPinToken, default empty), where outbound sealed bodies are pinned. As with a remote API origin, saving a non-loopback pin URL prompts for that origin’s host permission on the same Save click — the extension ships with loopback-only host permissions. Operators offering that pin surface should read the pin lifecycle caveat: a client-made pin sits outside any mail server’s pin lifecycle.

Reading sealed mail in the message pane

Messages sealed with Lockbox open in Thunderbird’s own message pane — the same place you read everything else. Open the message and the extension replaces the armored block with the decrypted text under a notice line saying what happened.

This needs the SithBit tab open, with a wallet unlocked. The message pane holds no wallet of its own: it hands the sealed block to the SithBit tab, which opens it and hands back the plaintext, so your key material never leaves the one place that already had it. With the tab closed or the wallet locked, the message shows the armored block and a line telling you to unlock — the same degradation as any other locked read, never a broken message.

Three further behaviours worth knowing:

• Only the text is rendered. A sealed message’s rich HTML is not displayed here. The web clients render it inside a sandboxed view; the Thunderbird message pane has no equivalent sandbox, so sender-authored HTML is deliberately never parsed in it.
• A message sealed to someone else says so rather than appearing to fail.
• Sealed attachments are listed under a Sealed attachments heading with a save button and the file size, which is known without downloading anything. Nothing is fetched until you click: an attachment carried inside the envelope decodes locally, and an offloaded one is fetched from your own configured IPFS gateway and decrypted on your machine. The save itself goes through the extension’s background rather than the message pane directly — the message pane’s own document cannot trigger a download — so it works even if you close the SithBit tab right after the attachment finishes fetching.

Nothing here changes the stored message — only what is displayed.

Security notes

• The wallet secret at rest is exactly as strong as your passphrase.
• The session token authorizes account changes (password, timezone, DND) for up to 24 hours; on-chain actions additionally require the unlocked wallet, which never survives a restart.
• The API relay cannot alter what you sign: transactions are built from the workspace’s own instruction encoders compiled to wasm, and a parity test pins them byte-for-byte to the CLI’s.

Lockbox: end-to-end encrypted mail

Lockbox mail makes a message readable only by its recipient — the mail server, the relay, and anyone who later reads the stored copy all see ciphertext. It reuses SithBit’s sealed-box encryption (the same crypto_box_seal that protects on-chain mail bodies) but applies it client-side, over ordinary email: the SithBit plugin seals the body before it leaves your machine and unseals it after it arrives, so lockbox mail rides your existing email account with no SithBit mail server in the path.

It is also fully automatic. Once you and a correspondent both have the plugin, there is no button to press and nothing to remember — every message between you is sealed and reopened transparently, the same way TLS quietly protects a web page. This is the single best reason to run the Thunderbird extension or the Outlook add-in instead of a plain IMAP/POP/SMTP account in your everyday mail client: the plugin is the only way to get true end-to-end encryption, and it costs you nothing to keep it turned on.

Why it matters: who can read your mail without it

Conventional providers do more with your mail than store it: most marketing mail carries a tracking pixel that reports when and where you opened it, and the largest provider has been fined by a national regulator for advertising inside the inbox without consent. Lockbox is the opposite posture: the message is sealed on your device, your operator never sees plaintext, and there is nothing in the stored copy to read, mine, or serve.

Every SithBit mailbox lives on a domain whose authority runs the mail server behind it — for a custom domain, that’s often your employer or whoever administers acme.com, not you. Without lockbox, that operator can read your mail in the clear:

• Your IMAP / POP client fetches each message body from the operator’s own storage, and that copy is kept as plaintext — it has to be, so the server can hand it back to you on request. The separate, sealed copy that gets pinned to IPFS is computed from that plaintext at delivery time; it protects the public copy on IPFS, not the one sitting on your operator’s disk.
• For mail relayed in from ordinary SMTP, the same operator also sees the envelope and headers in the clear — see the domain authority is fully trusted for relayed mail.

None of this is a bug — it’s the same trust model every traditional mail server already has (an IT admin can read mail on a company Exchange server, Gmail’s operator can technically read Gmail), and SithBit documents it honestly rather than pretending otherwise; see what’s public and private for the full picture. But it means that on-chain sealing alone protects you from the public internet, not from whoever runs your own mail domain.

Lockbox closes exactly that gap. Because sealing happens on your device before the message ever reaches a server — yours or anyone else’s — your own domain’s operator never holds a plaintext copy to begin with. There is nothing on their disk to subpoena, leak, or simply read.

How it works

Sending. When you send a message, the plugin:

1. Resolves each recipient to a wallet — a raw wallet address, or a alias — using only a public Solana RPC endpoint.

2. Looks up the recipient’s published encryption key (or falls back to sealing straight to their wallet address).

3. Packs the message into a small JSON envelope — the text body plus, when the sending client supplies them, rich HTML and any attachments, so everything seals and travels as one unit — then seals that envelope to the key and replaces the message body with an ASCII-armored block:

   -----BEGIN SITHBIT SEALED MESSAGE-----
   Version: 1
   To: alice
   
   …base64 sealed body…
   -----END SITHBIT SEALED MESSAGE-----
   

   The envelope is capped at 12 MiB, measured before sealing; a larger message is refused with a clear error rather than silently truncated. The headroom exists because the payload inflates twice on the wire — attachment bytes ride as base64 inside the envelope, and the sealed result is base64-armored again, roughly ×1.78 combined — so 12 MiB of raw content still clears the SMTP server’s default 25 MiB message-size limit. Messages sealed by earlier plugin versions carried the bare body with no envelope; they remain readable — opening simply falls back to treating the unsealed bytes as the text body.

   Large attachments offload instead of hitting that cap when the sending client has an IPFS pin service configured. Before the cap is measured, each attachment over 1.5 MiB (an eighth of the ceiling, derived from it rather than configured) is individually encrypted, pinned to IPFS, and replaced inside the envelope by a small reference — the content id, the decryption key, and the plaintext size. The key rides inside the sealed envelope and the reference carries no URL: a content id is permanent where a gateway hostname is not, so the recipient fetches from their own configured gateway and old mail never expires with the sender’s domain. Without a pin service nothing changes: attachments seal inline exactly as before, and an over-cap message is refused. Configuring the pin service is the on/off switch — there is no second setting to disagree with it.

   Concretely, “configured” means a pin service URL has been saved in the client’s connection settings, not merely that the field shows a value: the settings pane pre-fills it with the loopback development default, so saving connection settings at all arms the offload, while a client whose settings have never been saved keeps sealing inline. That distinction is deliberate — the pin URL always reads as something, so arming on the value alone would point every install at a port that usually has nothing behind it, and turn a large-attachment send that seals fine today into a failure.

All three steps run automatically on every send — there is no compose-time toggle to find or forget. A recipient without the plugin sees this block plus a short notice telling them how to read it — never a broken message.

Receiving. The recipient’s plugin automatically detects the armored block, unseals it with their wallet, and shows the plaintext — again, with no action from the reader beyond opening the message as usual. Ordinary (non-lockbox) mail is passed through untouched.

The web clients’ shared mail reader — the webmail app, the Chrome extension popup, and the Outlook task pane — opens sealed messages the same way. With your wallet unlocked, a sealed message shows its decrypted text (and rich HTML, through the same sandboxed view as ordinary mail) with a notice line naming what happened; locked, it shows the armored block with a hint to unlock, and a message sealed to a different recipient says so instead of failing. The envelope’s attachments are listed under Sealed attachments with a per-file download: an attachment that traveled inside the envelope decodes on your device, and an offloaded one (see the sending step above) is fetched from your own configured IPFS gateway and decrypted locally — the gateway sees only ciphertext and a content id, never the key, and a fetch whose bytes do not match the size the sealed message declares is refused rather than saved.

The Thunderbird extension opens sealed mail in Thunderbird’s own message pane, so there is no separate reading surface to switch to. Two differences follow from where that pane runs, and both are deliberate. First, the reading needs the SithBit tab open with your wallet unlocked: the message pane itself never holds your wallet, and instead hands the sealed block to that tab to open — so key material stays in one place. With the tab closed or locked, the message shows the armored block and a line telling you to unlock. Second, an opened message shows its text only: unlike the web clients, which render a sealed message’s rich HTML inside the same sandboxed view they use for ordinary mail, the Thunderbird message pane has no such sandbox, so sender-authored HTML is not rendered there at all. Sealed attachments are listed with a per-file save, and behave exactly as described above.

The recoverable reading key

Standard S/MIME and PGP have a painful weakness: lose the private key and your archived mail is gone, and using more than one device means hand-copying key files. SithBit derives your reading key from your wallet instead.

Your wallet signs one fixed, domain-separated message; that signature is run through a KDF to produce your X25519 reading key. Because the signature is deterministic, any device holding your wallet reproduces the exact same reading key — including a signing-only hardware wallet — with nothing to back up. Publish its public half once:

sithbit mailbox set-key --derive

Senders then seal to that published key. The trade-off is forward secrecy: the derived key never changes, so if it’s ever compromised, every message ever sealed to it — past and future — is readable. A random delegated key you rotate periodically (sithbit mailbox key) limits a compromise to whatever was sealed under that one key; older mail sealed under a previous, now-discarded key stays safe. If you prefer that protection over never needing a backup, keep generating a random delegated key instead.

Trade-off. Anyone who can trick your wallet into signing this exact message can reconstruct your reading key, so approve the signing prompt only in the SithBit plugin. See the threat model.

Autocrypt-style key discovery

Sealing to a recipient means first knowing their key. The plugin can always learn it from the chain (that lookup is the second step of Sending above), but a chain round-trip on every send is avoidable when the two sides have already exchanged mail. Borrowing the idea behind OpenPGP’s Autocrypt, the plugins advertise the sender’s key in an ordinary mail header and quietly remember it on the receiving end — so a reply to someone who has written to you seals without touching the chain at all.

The header. Outgoing lockbox mail carries a SithBit-specific header:

X-SithBit-Key: v=1; wallet=<base58 wallet>; key=<base58 X25519 key>

It names the sender’s wallet and their published X25519 reading key. The header is emitted opportunistically: the plugin adds it only when the sender resolves to a published key, and its absence never blocks or fails a send.

Both ends participate. The Thunderbird extension sets the header as the message is composed; the Outlook add-in sets it as the message is sent. On the receiving side, both plugins read the header off displayed mail and cache the wallet → key pair. A later send to that same wallet is served straight from the cache — no fresh RPC lookup — while the plugin still knows the sender is SithBit-capable.

The chain stays the source of truth. The header and its cache are a convenience and a “this sender speaks SithBit” signal, not an authority. The published key lives on-chain (set with sithbit mailbox set-key), and any send can fall back to the chain lookup — so a reply seals correctly even if no header was ever seen.

Not OpenPGP Autocrypt. This borrows Autocrypt’s shape — advertise your key in a header, remember peers’ keys from received mail — but it is a separate, SithBit-only mechanism. The advertised key is an X25519 reading key, not a PGP key, and the header does not interoperate with real Autocrypt or any OpenPGP client.

Limitations. Only the wallet named in the header is remembered, so the cache short-circuits future sends addressed to that bare wallet or to wallet@host — an alias-addressed reply such as bob@acme.com still resolves through the chain, because the header advertises the wallet, not the alias. Thunderbird caches when a message is displayed; Outlook has no event for “message read”, so its read-caching rides the task pane loading on an opened message. In every case a cache miss simply falls back to the normal chain lookup.

What v1 does — and does not — do

• Both ends need the plugin. Lockbox is end-to-end encryption between SithBit users, not a way to send encrypted mail to someone running plain Apple Mail. (S/MIME interop for plugin-less recipients is a possible later layer.)
• Recipients must be SithBit-native. Lockbox seals to a raw wallet address or a global alias. Alias resolution is domain-blind — the suffix is parsed off and ignored, so alice, alice@acme.com, and alice@anything.example all seal to whoever holds the global alice. This is load-bearing, not incidental: sealing follows resolution, so if any third party could redefine which wallet an address names, it would thereby choose which key your browser seals to. No domain authority can. A recipient that can’t be resolved is reported as unsupported and the message is sent as ordinary plaintext.
• All-or-nothing per message. If any recipient can’t be sealed to, nothing is sealed — the message goes as plaintext rather than leaking who could and could not be reached. A message to several SithBit recipients carries one sealed block per recipient.
• The plugins seal the body, the rich HTML, and the attachments. Both the Thunderbird and Outlook plugins read the composed message out of the host mail client and hand the whole thing to the envelope, so formatting and attachments seal and travel as one unit. Attachment bytes ride inside the sealed envelope, which is why the originals are detached from the outgoing message once the seal succeeds — a recipient without the plugin sees the armored block and no attachments, rather than the files in the clear beside it.
• Two things a message can contain that stop it being sealed. Both fail closed: the message is sent exactly as you typed it, unencrypted, and the plugin tells you why. It is never sent partly sealed.
  • Inline (embedded) images. A pasted or dragged-in image lives in the message body as a cid: reference rather than as an attachment, and neither host’s plugin API can enumerate those parts — so the plugin cannot seal them, and rewriting the body around them would either destroy the image or leave it readable beside a sealed body. Attach the images as files instead and the message seals normally.
  • Cloud attachments and attached messages. A OneDrive-style cloud attachment is a link, not bytes, and a forwarded .eml item is handed to the plugin in a form that carries no bytes either. Download and re-attach either one as an ordinary file to seal it.

Relationship to on-chain mail

Lockbox mail and on-chain SithBit mail solve the same privacy problem from two directions. On-chain mail seals the body server-side at delivery time and stores that ciphertext on IPFS, but — as covered above — the operator’s own mailbox copy stays plaintext so IMAP/POP can serve it back to you. Lockbox mail seals client-side instead, so the operator never sees plaintext in the first place — at the cost of requiring the plugin on both ends. See what’s public and private for the full picture.

The name marketplace

The open market for aliases and domains, in the browser: a single browse pane that lists every name currently offered for sale, lets you buy one with a click, list your own for a fixed price, and look back over completed sales. It is the graphical twin of the CLI’s alias sell/alias buy and domain sell/domain buy commands — the same fixed-price, first-come-first-served listings, driven from a page instead of a terminal. Prices are in SOL; a completed sale settles on-chain with the seller keeping 90% and the postoffice the remaining 10% (the standard marketplace split).

The marketplace ships two ways, both from the same shared core (webclients/shared/marketplace-panes.js):

• a standalone page (webclients/marketplace/) that does nothing but the marketplace, and
• the identical pane mounted inside the webmail app, the Outlook add-in, and the Thunderbird extension, alongside their other settings panes.

Two wallets meet here

Every other browser pane signs in the page with the in-wasm keypair (see the webmail app). The marketplace is deliberately different, because you may want to buy a name with a hardware wallet or a Phantom account that never touches this app:

• Browsing and sale history are plain reads. They ride the authenticated /v1/chain/listings and /v1/chain/sales account-api routes with your normal session JWT. The listing index is global — the JWT only authenticates the request; whose wallet it belongs to is irrelevant to what you see.
• Buying and listing sign with an external wallet. When you click Buy or List for sale, the pane connects your browser wallet — Phantom or a Ledger through it — builds the unsigned wire transaction from a wasm *_unsigned builder, and hands it to that wallet to sign and broadcast. The in-wasm keypair never signs a purchase, and your external wallet’s key never enters the page.

If no browser wallet is injected, the buy/list controls report the wallet as unavailable; browsing still works.

The tabs

The pane opens on For sale — the names you can buy right now — and offers four filters:

• For sale (default) — live listings: every offer with no expiry, or whose expiry is still ahead. These are purchasable.
• Expired — listings past their binding window. Nothing sweeps expired listings on-chain (see the binding window), so they linger in the index; this tab is where they land, and they are no longer buyable.
• Sold — completed sales, newest first. This tab lazy-loads sale history from /v1/chain/sales the first time you open it.
• Participants — the opt-in campaign pool: wallets that published a discovery beacon advertising the topics they’ll accept paid mail on. Like Sold, it lazy-loads on first view.

The Participants tab

The first three tabs trade names; the Participants tab is a window onto the campaign pool — the people who have opted in to be reached, not the names for sale. A tag-filter box narrows the pool to wallets carrying every tag you enter (a logical AND); Apply re-pulls the list from the global /v1/chain/participants account-api route. Tags go by the same names the sithbit campaign --tag flag takes — interest.technology, region.apac, and so on, case-insensitive — and the filter also accepts raw bit positions, mixed freely in one comma-separated list (interest.technology,10). A name the vocabulary doesn’t know is reported as an error right in the pane, before anything is fetched. Each row shows a participant’s wallet address, its self-attested tags by name (a tag newer than the page’s vocabulary shows as its bit number rather than disappearing), and whether it advertises an off-chain detail profile.

Browsing the pool is a plain read; reaching the people in it is a separate, paid step — you send them bountied mail, most easily with the sithbit campaign tree. See Campaigns for the whole flow and what it costs.

Managing your own beacon

Below the pool list, a My beacon heading carries a single Manage my beacon button — disabled until a browser wallet is available, because authoring your beacon, like buying and listing, signs with your external wallet, never the in-wasm keypair. Clicking it connects the wallet, reads your own beacon from chain, and shows one of three states:

• Not opted in — a “not in the pool yet” prompt, six checkbox groups of tag pickers by name (interest / skill / age / region / language / role — the same 71-tag vocabulary the sithbit campaign --tag flag takes), an optional detail CID field, and a Publish beacon button. Publishing requires at least one tag picked.
• Opted in — your published tags by name, above the same form pre-seeded from your chain state, with Update beacon, Disable, and Close beacon buttons.
• Disabled — a clear notice that your beacon is disabled and advertises no tags, with Re-enable alongside Update and Close.

The detail CID field is paste-only: it takes a literal CID, mirroring the CLI’s --detail-cid — the page never encrypts or pins a profile for you (that is the CLI’s --profile-file path). And like the CLI, an update is a wholesale replacement: the picked tags and the pasted CID replace whatever the beacon carried, so an empty CID field clears a published one.

Disable is a convention of this pane, not a chain state. Disabling publishes an update carrying no tags: the beacon account and its rent stay on-chain, but because a pool search must match at least one tag, a tag-less beacon drops out of every tag search. The pane remembers the tags you disabled locally in your browser, per wallet, so Re-enable restores exactly the set you had — the chain never stores that remembered set, so a different browser or a cleared profile has nothing to restore and says so; pick your tags again and Update instead. Close is the full opt-out: it closes the beacon account and refunds its rent to your wallet.

Success, pending-signature, and error feedback share the pane’s existing status lines, exactly as a buy or a listing does.

Each For sale row shows the name, whether it is an alias or a domain, and the asking price in SOL, with a Buy button. A successful buy refreshes the index and shows the transaction signature.

Listing your own name

The List for sale form takes the kind (alias or domain), the name, and an asking price in SOL. It connects your external wallet — which must be the name’s current holder/authority — signs the listing transaction, and refreshes the index so your new offer appears under For sale. Listings default to the program’s 30-day binding window; the CLI’s alias sell / domain sell let you set a different --expires-in.

A marketplace listing names nobody: whoever pays first wins. To hand a name to one specific recipient for a fee, use the escrowed alias transfer or domain transfer offer instead; for an ascending-bid sale, see Auction an alias.

The standalone page

Besides the panes built into every client, the marketplace has a standalone page of its own, served by your operator at a URL they choose.

The standalone shell asks you to import a Solana keypair on first run: that keypair unlocks the browse JWT only. Buying and listing still use your separate Phantom/Ledger wallet, which connects on demand from the pane. (The in-client panes reuse whichever wallet already logged that client in, so they skip this step.)

Operators: building and mounting that page is Serving the browser clients.

Honest notes

• Purchases are public. The buyer’s wallet, the asking price, and the winning transaction all live on-chain — an observer can see who bought which name and for how much. This is inherent to a public ledger; see What’s public and private.
• Sale history comes from an indexer, not the chain directly. The Sold tab is only as complete and current as the operator’s alias/marketplace indexer; an operator who disables it leaves the tab empty.
• [chain] is required. All three routes the pane uses answer 503 without account-api’s [chain] section configured, just like the other chain-backed panes.

Economics

In one breath: strangers pay postage to reach you and you keep roughly 90% of it; the operator whose domain carried the message takes 10% by protocol default; funding a friend’s postage yourself is fee-free, so mail among people you know is free beyond ordinary transaction fees; and every amount below moves in native SOL — there is no token.

Where the SOL goes: every lamport transfer in the protocol, traced from the on-chain programs (the mail_program, alias_program, and domain_program processors), and what each participant class pays and collects. Amounts marked ≈ are rent-exemption minimums — a refundable, one-time deposit every Solana account needs to exist, sized to the account’s byte length rather than to any price or value it represents (see Closing accounts for what rent is and how to reclaim it) — and vary with account size at current rent parameters. This is a completely separate quantity from postage: postage is a price the recipient chooses; rent is a storage deposit nobody chooses and everybody gets back.

The stamp lifecycle

A stamp is prepaid postage for one email from one sender (“from” address) to one recipient wallet. Its value cycles through three accounts, then settles across four destinations:

1. Buying (AddStamps / CreateFrombox): anyone may fund the frombox for a (from, recipient) pair. Each stamp costs the frombox’s required_postage plus a two-signature fee surcharge (STAMP_FEE_SURCHARGE_LAMPORTS = 10 000 = 2 × the 5 000-lamport base fee); the surcharge prefunds both settlement signature refunds (SendMail and DeleteMail). The whole amount transfers into the frombox account. A new frombox inherits required_postage from the recipient mailbox’s default_postage; only the recipient may change it afterwards (UpdateFrombox requires the recipient’s signature). Price changes do not revalue stamps already bought — value amortizes over the remaining stamp count. Third-party purchases additionally pay the per-stamp protocol fee — the greater of a flat per-stamp amount and a small percentage of the escrowed postage, split between the recipient’s domain authority and the postoffice (see “The per-stamp protocol fee” below); purchases paid by the recipient wallet itself are fee-free.
2. Sending (SendMail): the signer must be the sender named in the email (or the active domain authority for the recipient’s domain — the MX operator’s wallet, for relayed mail). The signer pays the transaction fee and fronts the message account’s rent-exemption (≈0.003–0.006 SOL depending on address/cid sizes — a deposit sized to the account’s byte length, not to the postage price; see the note above) as a new deposit, separate from anything paid at the Buying step. One proportional share of the frombox’s value — (balance − frombox rent) / stamps — moves onto the message account alongside that rent, and one stamp burns. A frombox whose share rounds to zero still sends (the stamp count is the gate; the value is what settles later).
3. Settling (DeleteMail): only the sender or the recipient may delete. The message balance is split, in order: the sender recovers the message rent + one signature fee, the delete signer recovers this transaction’s signature fee (both prefunded by the surcharge), the recipient’s domain authority collects the operator share (operator_share_bps — default OPERATOR_SHARE_BPS = 10% of the remaining postage, delegate-tunable since v0.36.0), and the recipient collects the rest.¹ Postage only settles on delete; until then it sits parked on message accounts.

Try it yourself: a worked example

The script below re-derives the three steps above as plain arithmetic — paste it into a browser console or run it with node (no dependencies, no network access, nothing on-chain). Change postageLamports, messageRentLamports, or thirdPartyBuyer at the top to try a different scenario.

Money enters this example at two different points, not one: the buyer’s purchase at Buying, and the sender’s rent deposit at Sending (the same wallet, if the buyer is also the sender — but still two separate transactions). That’s why the settlement totals add up to more than buyerPays alone: the conservation check sums both inputs (buyerPays + messageRentLamports) against everything paid out, and only that combined total should balance.

Note: the default postageLamports below is priced at roughly what a single US first-class postage stamp costs (about $0.82 as of this writing), converted to lamports at the SOL/USD rate on the date this page was last updated ($81.16/SOL, 2026-07-06) — a deliberate nod to the stamp analogy, not a protocol default. Change it to see how the split scales.

// SithBit stamp economics calculator -- a hypothetical worked example.
// Pure JavaScript, no dependencies: paste into a browser console, or run
// with `node stamp-calculator.js`. All amounts are in lamports
// (1 SOL = 1,000,000,000 lamports).

// Protocol constants (from mail_model::constants). The two bps rates are
// the DEFAULTS -- the delegate can retune both (SetSettlementBps), each
// bounded by its on-chain cap.
const SIGNATURE_FEE_LAMPORTS = 5_000;
const STAMP_FEE_SURCHARGE_LAMPORTS = 10_000;   // 2 x SIGNATURE_FEE_LAMPORTS
const POSTOFFICE_STAMP_FEE_LAMPORTS = 100_000; // flat arm; waived if the buyer is the recipient
const DEFAULT_STAMP_FEE_BPS = 100;             // bps arm: 1% of the escrowed postage
const OPERATOR_SHARE_BPS = 1_000;              // 10% of postage, to the domain authority
const POSTAGE_ROUNDING_LAMPORTS = 1_000;       // recipient payout rounds down to this

// --- Inputs: change these to try a different scenario ---
const postageLamports = 10_000_000;    // ~0.01 SOL -- priced at ~$0.82, a US first-class stamp
const messageRentLamports = 4_000_000; // ~0.004 SOL -- rent-exemption sized to account bytes, independent of postage
const thirdPartyBuyer = true;          // false = the recipient self-funds (fee waived)
const solUsdPrice = 81.16;             // SOL/USD rate used for the $ comments below (2026-07-06)

function sol(lamports) {
  return (lamports / 1_000_000_000).toFixed(9) + " SOL";
}

function usd(lamports) {
  return "$" + ((lamports / 1_000_000_000) * solUsdPrice).toFixed(2);
}

// 1. Buying: AddStamps / CreateFrombox
// The protocol fee is a hybrid: the greater of the flat per-stamp fee and
// the bps share of the escrowed postage (the surcharge is a refundable
// prefund, not stamp value). At this example's 0.01 SOL postage the two
// arms meet exactly; raise postageLamports to watch the bps arm take over.
const stampValue = postageLamports + STAMP_FEE_SURCHARGE_LAMPORTS;
const hybridFee = Math.max(
  POSTOFFICE_STAMP_FEE_LAMPORTS,
  Math.floor((postageLamports * DEFAULT_STAMP_FEE_BPS) / 10_000),
);
const protocolFee = thirdPartyBuyer ? hybridFee : 0;
const buyerPays = stampValue + protocolFee;
// The purchase carries the operator tail (as current clients build it),
// so the fee splits: operator_share_bps to the recipient's domain
// authority, the remainder to the postoffice. The buyer's total is the
// same either way.
const feeOperatorShare = Math.floor((protocolFee * OPERATOR_SHARE_BPS) / 10_000);
const feePostofficeCut = protocolFee - feeOperatorShare;

console.log("== Buying: AddStamps / CreateFrombox ==");
console.log(`Buyer pays:          ${buyerPays} lamports (${sol(buyerPays)})`);
console.log(`  // ≈ ${usd(buyerPays)}`);
console.log(`  -> frombox value:  ${stampValue} lamports (${sol(stampValue)})`);
console.log(`  -> protocol fee:   ${protocolFee} lamports (${sol(protocolFee)})${thirdPartyBuyer ? "" : " (waived)"}`);
if (thirdPartyBuyer) {
  console.log(`       ${feeOperatorShare} to the domain authority (operator share) + ${feePostofficeCut} to the postoffice`);
}

// 2. Sending: SendMail
const messageBalance = messageRentLamports + stampValue;
console.log("\n== Sending: SendMail ==");
console.log(`Sender fronts message rent: ${messageRentLamports} lamports (${sol(messageRentLamports)})`);
console.log(`  // a new deposit -- separate from what the buyer paid above`);
console.log(`One stamp's value moves onto the message account: ${stampValue} lamports (${sol(stampValue)})`);
console.log(`Message account now holds: ${messageBalance} lamports (${sol(messageBalance)})`);

// 3. Settling: DeleteMail
const senderShare = messageRentLamports + SIGNATURE_FEE_LAMPORTS;
const deleteSignerShare = SIGNATURE_FEE_LAMPORTS;
const remainingPostage = messageBalance - senderShare - deleteSignerShare; // == postageLamports
const operatorShare = Math.floor((remainingPostage * OPERATOR_SHARE_BPS) / 10_000);
const recipientRaw = remainingPostage - operatorShare;
const recipientShare = Math.floor(recipientRaw / POSTAGE_ROUNDING_LAMPORTS) * POSTAGE_ROUNDING_LAMPORTS;
const postofficeResidue = recipientRaw - recipientShare;

console.log("\n== Settling: DeleteMail ==");
console.log(`Sender recovers:        ${senderShare} lamports (${sol(senderShare)})  [rent + 1 signature fee]`);
console.log(`  // ≈ ${usd(senderShare)}`);
console.log(`Delete signer recovers: ${deleteSignerShare} lamports (${sol(deleteSignerShare)})  [1 signature fee]`);
console.log(`  // ≈ ${usd(deleteSignerShare)}`);
console.log(`Domain authority earns: ${operatorShare} lamports (${sol(operatorShare)})  [10% operator share]`);
console.log(`  // ≈ ${usd(operatorShare)}`);
console.log(`Recipient collects:     ${recipientShare} lamports (${sol(recipientShare)})  [the rest, rounded down]`);
console.log(`  // ≈ ${usd(recipientShare)}`);

// 4. Conservation check
const totalIn = buyerPays + messageRentLamports;
const totalOut = senderShare + deleteSignerShare + operatorShare + recipientShare + protocolFee + postofficeResidue;
console.log("\n== Conservation check ==");
console.log("  // totalIn = buyerPays + messageRentLamports: money entered at TWO steps, not one");
console.log(`Total in:  ${totalIn} lamports`);
console.log(`Total out: ${totalOut} lamports`);
console.log(totalIn === totalOut ? "Every lamport is accounted for." : "Mismatch -- check the math!");

Example output for the defaults above (a stranger buying one first-class-stamp-priced stamp, with the recipient later deleting the message to collect payment):

== Buying: AddStamps / CreateFrombox ==
Buyer pays:          10110000 lamports (0.010110000 SOL)
  // ≈ $0.82
  -> frombox value:  10010000 lamports (0.010010000 SOL)
  -> protocol fee:   100000 lamports (0.000100000 SOL)
       10000 to the domain authority (operator share) + 90000 to the postoffice

== Sending: SendMail ==
Sender fronts message rent: 4000000 lamports (0.004000000 SOL)
  // a new deposit -- separate from what the buyer paid above
One stamp's value moves onto the message account: 10010000 lamports (0.010010000 SOL)
Message account now holds: 14010000 lamports (0.014010000 SOL)

== Settling: DeleteMail ==
Sender recovers:        4005000 lamports (0.004005000 SOL)  [rent + 1 signature fee]
  // ≈ $0.33
Delete signer recovers: 5000 lamports (0.000005000 SOL)  [1 signature fee]
  // ≈ $0.00
Domain authority earns: 1000000 lamports (0.001000000 SOL)  [10% operator share]
  // ≈ $0.08
Recipient collects:     9000000 lamports (0.009000000 SOL)  [the rest, rounded down]
  // ≈ $0.73

== Conservation check ==
  // totalIn = buyerPays + messageRentLamports: money entered at TWO steps, not one
Total in:  14110000 lamports
Total out: 14110000 lamports
Every lamport is accounted for.

Per-participant flows

Recipient (mailbox owner)

The recipient is the protocol’s revenue side: strangers pay required_postage per message, and pricing is the recipient’s spam control (the CLI defaults new mailboxes to 1 SOL per stamp — unknown senders are priced out until the recipient lowers the price for them, though a stranger with a real on-chain spending record pays a scaled share of that default — see reputation-scaled first-contact pricing). When the recipient funds a correspondent’s frombox themselves, the value round-trips back minus transaction fees — allow-listing costs only fees. Accumulates SOL in proportion to mail from senders who paid their own postage — roughly 90% of each stranger’s postage, everything after the 10% operator share and the sub-1 000-lamport rounding — and net of their one-time rents otherwise.

Sender (wallet-holding)

Pays postage (the recipient’s price) plus the fee surcharge per stamp, and fronts the message rent per send. On delete, rent and one signature fee come back. Net cost per mail ≈ required_postage — the intended price of communication. Spends SOL by design.

MX operator (runs sithbitd + the gRPC gateway)

For relayed mail, the operator’s domain-authority wallet is the on-chain “sender”: it fronts the message rent and transaction fee per inbound delivery, and recovers rent plus the surcharge-funded signature fee at DeleteMail. On-chain revenue: the operator share — every settled message for a mailbox on the operator’s active domain pays the authority the operator share of the postage (operator_share_bps, default OPERATOR_SHARE_BPS = 10%), and every third-party stamp purchase that presents the operator accounts (what current clients build) pays the authority the same share of the per-stamp protocol fee (v0.37.0). At scale this turns relaying into a revenue stream rather than a pure cost. Off-chain costs remain ( IPFS pinning, servers, RPC); the share offsets them on-chain.

The per-stamp protocol fee

The postoffice’s primary revenue: a hybrid fee per purchased stamp — the greater of a flat amount and a bps share of the escrowed postage (v0.36.0) — collected at purchase time. A purchase that presents the recipient’s mailbox/domain/authority accounts (the operator tail, which current clients build automatically) splits the fee: operator_share_bps (default 10%) to the recipient’s domain authority, the remainder to the postoffice PDA. A legacy account list keeps the whole fee with the postoffice.

• Amount: the greater of the two arms — max(stamp_fee_lamports × stamps, postage × stamp_fee_bps / 10 000). The flat arm is stamp_fee_lamports from the postoffice account (default POSTOFFICE_STAMP_FEE_LAMPORTS = 100 000 = 0.0001 SOL) per stamp; the bps arm is stamp_fee_bps (default DEFAULT_STAMP_FEE_BPS = 100 = 1%) of the postage being escrowed, so the fee scales with premium-priced stamps instead of rounding to noise beside them. At the defaults the arms cross at 0.01 SOL of postage per stamp: cheap friend-tier stamps pay the flat fee, a default-priced 1-SOL stranger stamp pays 0.01 SOL. The refundable signature surcharge is not stamp value and is never in the bps base.
• Operator split (v0.37.0): when the purchase’s account list carries the operator tail — the recipient’s mailbox, its named domain, and the domain authority — the authority receives operator_share_bps of the fee and the postoffice the rest. The buyer’s total is identical either way; only the fee’s destination splits. The lapse and filler rules mirror the settlement share: no domain named, a closed or inactive domain, or a closed mailbox lapse the share back to the postoffice, while present-but-wrong accounts are refused (a purchaser cannot reroute the share to itself). Legacy five/six-account purchases keep today’s whole-fee-to-postoffice behavior — the tail is optional, so old clients never break.
• Waiver: the fee is skipped iff the purchase’s fee payer is the recipient wallet (fee_payer == to_account) — the whole hybrid, both arms. The payer is a required signer, so the check is unforgeable. This keeps the adoption path free: a mailbox owner who prices a correspondent’s frombox low and prefunds its stamps pays no protocol fee, and the recipient’s settlement payouts are untouched — mailbox owners perceive zero cost. Gift purchases by anyone else pay the fee.
• Governance: the delegate tunes the flat arm with SetStampFee (sithbit postmaster fee stamp <LAMPORTS>), hard-capped on-chain at MAX_POSTOFFICE_STAMP_FEE_LAMPORTS (1 000 000), and the bps arm with SetSettlementBps (sithbit postmaster fee settlement <OPERATOR_SHARE_BPS> <STAMP_FEE_BPS>), capped at MAX_STAMP_FEE_BPS (1 000 = 10%) — so a compromised delegate key cannot price-gouge purchasers. A zero bps rate stores the “unset” sentinel and resolves to the protocol default (the rate cannot be tuned to literal zero; the flat arm can). There is no on-chain read instruction — account state is world-readable; anyone can query the current schedule with the ungated sithbit postoffice fee stamp (both arms) or sithbit postoffice fee settlement (both bps rates).
• Layout migration: postoffice accounts created before the fee field (32-byte layout) still work everywhere — readers parse them with a versioned load that applies the default fee, and the writers (the fee setters and the ownership instructions) grow the account in place (resize + rent top-up from the signing delegate) on their next run.

Domain authorities

CreateDomain takes an explicit payer — either the delegate or the domain authority may fund the domain account’s rent plus the DOMAIN_AUTHORIZATION_FEE_LAMPORTS (0.01 SOL default, delegate-tunable via SetDomainFee up to MAX_DOMAIN_AUTHORIZATION_FEE_LAMPORTS) paid to the postoffice. Either way the delegate must sign: domain ownership is proven off-chain (the authority’s pubkey in the domain’s DNS TXT record, checked by the delegate’s trusted agent), so on-chain authorization is always the delegate’s — authority-pays is a co-signed two-signature transaction, never authority-alone. The domain records its rent_payer, and CloseDomain (delegate-signed) refunds the rent to whoever paid. When the delegate sponsors a domain itself, the fee is a wash — it lands in the postoffice the postmaster can sweep. Deactivation remains a separate, reversible toggle. In exchange, the authority earns the operator share (default 10%) on every settled message for its domain.

The permissionless proof-carrying path (AuthorizeDomainByProof, the CLI’s sithbit domain authorize) charges its payer the same fee, once the on-chain DNSSEC verification succeeds — fee parity keeps the two authorization routes economically interchangeable; a failed proof charges nothing.

Alias holders

An alias costs its own account rent plus a claim fee paid to the mail program’s postoffice — squatting a name now has a price. The claim fee is length-tiered (v0.35.0): names of 5 or more characters pay the flat ALIAS_FEE_LAMPORTS (0.01 SOL default), while 1–4 character names are scarce assets (36 one-character, ~1.3k two-character combinations) and pay a scarcity premium from the ALIAS_TIER_FEES_LAMPORTS schedule — by default 10 SOL (1 char), 1 SOL (2), 0.1 SOL (3), and 0.05 SOL (4). The CLI and the web register form both quote the fee before you sign; premium pricing is never charged silently. Handing an alias to a new holder for free likewise pays the ALIAS_TRANSFER_FEE_LAMPORTS (0.001 SOL default) — charged when the recipient accepts a zero-fee transfer offer (v0.7.0: every transfer is an offer the recipient must accept), and waived when the offer’s holder is the standing delegate; a priced sale pays the 90/10 split below instead. The flat fees are delegate-tunable via SetAliasFee (one instruction sets the claim and transfer fees together) and the premium schedule via SetAliasTierFees, every value bounded by its own on-chain cap (MAX_ALIAS_FEE_LAMPORTS / MAX_ALIAS_TRANSFER_FEE_LAMPORTS / MAX_ALIAS_TIER_FEES_LAMPORTS, the tier caps at 10× their defaults). Delegate reservations waive the claim fee at every length, so the postmaster can reserve premium short names for rent alone and resell them on the marketplace at seller-set prices. Names remain globally unique, first-come, and never expire. CloseAlias lets the holder (the wallet the alias points at) reclaim the rent; the fee is not refunded.

Escrowed alias transfers

Selling an alias (alias transfer init --fee) stages an offer that the named recipient later accepts by paying the fee. Since v0.7.0 this escrowed offer is the ONLY transfer path — a zero fee stages a free hand-off that still needs the recipient’s accept. The money flow for a priced offer:

• Nothing monetary ever sits in escrow. The escrow account holds only the offer’s terms (recipient, fee, expiry) plus its own rent-exemption; the fee itself never parks anywhere. It moves at accept, in the same atomic instruction that repoints the alias — so a cancelled or expired offer has no refund leg, because no money was ever taken.
• At accept, the fee splits 90/10 (at the default rate): the paying wallet (the recipient, or a sponsor co-signing via --payer-keypair) transfers the seller’s share to the alias’s current holder and the operator share to the mail program’s postoffice. The cut is operator_share_bps (default OPERATOR_SHARE_BPS = 1 000 bps = 10%), the same delegate-tunable rate the DeleteMail settlement uses for the domain operator’s share — retuned with SetSettlementBps up to MAX_OPERATOR_SHARE_BPS (2 000 = 20%), one rate for every settlement split; the postoffice’s leg is floored and the rounding dust goes to the seller.
• Escrow rent round-trips to the seller. The holder fronts the escrow account’s rent-exemption when staging the offer and gets it back when the escrow closes — on accept and on cancel (including the expiry-reclaim cancel). Replacing a standing offer reuses the funded account: no additional rent.
• No flat transfer fee rides a PRICED offer. The 90/10 split is the paid path’s entire economics. A zero-fee accept (a free hand-off) instead pays the flat ALIAS_TRANSFER_FEE_LAMPORTS lever above to the postoffice — waived when the offer’s holder is the standing delegate, keeping operator reservation hand-offs fee-free end to end.

Open marketplace listings

Listing an alias or a domain for sale (alias sell / domain sell) inherits the escrowed-transfer money flow above wholesale, with one difference: there is no named recipient — any buyer may pay the fixed price and take the asset. The seller is the alias’s current holder, or the domain’s current authority (the one authority-signed domain instruction; every other domain mutation is delegate-gated). The money flow:

• Nothing monetary ever sits in the listing. The listing account holds only the sale’s terms (seller, price, staged-at, expiry) plus its own rent-exemption; the price never parks anywhere. It moves at buy, in the same atomic instruction that swaps ownership — so a cancelled or expired listing has no refund leg, because no money was ever taken.
• At buy, the price splits 90/10 (at the default rate): the paying wallet (the buyer, or a sponsor co-signing via --payer-keypair, which also fronts the two-signature transaction fee) transfers the seller’s share to the seller and the operator share to the mail program’s postoffice. The cut is operator_share_bps (default OPERATOR_SHARE_BPS = 1 000 bps = 10%), the same delegate-tunable rate the DeleteMail settlement, the escrowed alias transfer, and the reply-bounty claim use — retuned with SetSettlementBps up to MAX_OPERATOR_SHARE_BPS (2 000 = 20%), one rate for every settlement split; the postoffice’s leg is floored and the rounding dust goes to the seller.
• The fee is seller-side. The buyer pays exactly the listed price, no more; the share comes out of the seller’s proceeds. A seller who wants to net a target amount prices it in — the marketplace’s positioning matches the rest of the protocol, where the postoffice’s revenue rides the party monetizing an asset, never the party adopting one.
• Listing rent round-trips to the seller. The seller fronts the listing account’s rent-exemption when staging and gets it back when the listing closes — on buy and on cancel (including the expiry-reclaim cancel). Replacing a standing listing reuses the funded account: no additional rent.
• No flat fee on this path either. Like the escrowed accept, a buy pays no ALIAS_TRANSFER_FEE_LAMPORTS-style flat fee — the 90/10 split is the marketplace’s entire economics, for aliases and domains alike (a marketplace domain sale also pays no DOMAIN_AUTHORIZATION_FEE_LAMPORTS; that fee prices authorizing a new domain, not re-selling an authorized one).
• A listed name is locked to its listing. While a listing is open the asset can’t be moved out from under it: close and the transfer paths (alias transfer init, the delegate’s domain transfer) refuse until the seller cancels, and a domain mid-deactivation-timelock can be neither listed nor bought. The buy itself also re-checks the seller, so a stale listing surviving a change of ownership can never sell the new owner’s name at the old owner’s price. See the guard notes on the alias and domain listing pages.
• A domain sale conveys protocol authority only — the mail-injection signing right and the operator share; never the DNS name, MX hosting, or DKIM keys, which stay with whoever holds them off-chain. Buyers should read What buying a domain does — and does not — buy before paying.

Reputation-scaled first-contact pricing

The mailbox default postage is a blunt instrument on purpose: 1 SOL per stamp — a wall the recipient lowers per sender — prices out spam, phishing, and any other free-to-send abuse from senders the recipient has never met. But “never met” describes two very different wallets — a fraudster’s freshly-minted burner and a legitimate organization that has been paying postage across the network for months. Since v0.39.0 the protocol tells them apart: the default price a stranger pays at first contact scales with the sender wallet’s on-chain track record, while spam economics are untouched (a burner wallet has no record and pays full price).

The record is the sender-reputation account — a small mail-program PDA, one per sender wallet, holding the wallet’s cumulative distinct-recipient postage spend. Every third-party CreateFrombox (each one a first purchase toward a new recipient) that carries the reputation tail records the postage it escrows — postage only, never the refundable surcharge or the protocol fee — onto the payer’s record. Current clients (the CLI, the wasm builders, and the web prepay) carry the tail by default; the account is lazily created on its first use, rent funded by the payer.

That cumulative spend steps the rate a stranger’s first contact is priced at, in basis points of the recipient’s default_postage:

Three boundaries keep the mechanic honest:

• Only the default is scaled — a recipient-set price is never touched. The discount applies exactly where the frombox would have inherited the mailbox’s default postage: a stranger’s first purchase. A price the recipient chose — cheaper for a friend, punitive for a nuisance — applies verbatim, whatever the sender’s reputation, and repricing stays exclusively the recipient’s lever. Recipients keep full sovereignty and full revenue: the discounted postage still settles to them, and a recipient who wants full price from everyone simply sets their prices rather than relying on the default.
• The discount has a floor. However much reputation a wallet accumulates, first contact never prices below reputation_floor_bps of the recipient’s default — DEFAULT_REPUTATION_FLOOR_BPS = 1,000 bps (10%) by default, delegate-tunable with SetReputationFloor (sithbit postmaster fee reputation-floor <BPS>) up to the 10,000-bps cap (100%, which disables the discount entirely; over-cap refuses with custom error 102 ReputationFloorAboveCap, and zero resets to the protocol default). And a nonzero asking price never rounds to zero — first contact is never free.
• A verified-sender attestation is the fast path. A purchase whose account tail carries the payer’s attestation for the from address’s domain prices first contact at the floor immediately — no spend history required. Proven DNS control plus the attestation fee substitutes for months of postage: the two friction mechanics compose instead of stacking.

Owner purchases — the recipient prefunding a sender’s frombox — are unaffected: they ride the legacy account list, pay the raw default, and record no spend (a recipient prepaying their own inbound mail is not sender reputation). Anyone can read a wallet’s standing with the ungated sithbit postoffice reputation <WALLET>, which prints the recorded cumulative spend and the effective first-contact rate in bps, floor included; server operators get the same two figures over gRPC via the gateway’s GetSenderReputation RPC.

This is the positioning principle again, applied to the sender side: reputable and attested senders earn cheaper first contact — friction should price out spam, not commerce — while every discounted lamport still flows to the recipient, whose own prices the protocol never overrides.

Pinning leases

The auto-settle sweeper releases a delivered copy’s IPFS pin about 30 days after delivery — a generous default that most mail never needs to outlive. For the mail that does, a pinning lease (sithbit mail lease) pays for extended retention: a small on-chain account, one per (CID, holder wallet), whose existence asks operators to keep that CID pinned. Operators consult it before releasing a pin, and the check fails safe — an operator that cannot prove a CID unleased keeps the pin.

The shape is deliberately deposit-heavy, fee-light:

• The deposit is reclaimable capital, not spend. A lease escrows at least PIN_LEASE_MIN_DEPOSIT_LAMPORTS (0.01 SOL) on its own account and returns it in full — with the rent — the moment the holder closes the lease. Retention costs opportunity, not money.
• The only spend is a one-time creation fee (default 0.001 SOL, tunable up to 10×), split at the standard operator share with the recipient’s registered domain authority — the operator actually storing the bytes — the remainder to the postoffice. No recurring or renewal fee exists, deliberately: a lease held for a year costs exactly what a lease held for a week costs.
• Anyone may hold one. Retention is usually a recipient desire, but senders and third parties can lease a CID too; per-(CID, holder) keying means independent leases never contend.

Against the positioning principle: the default retention stays generous and free (nobody needs a lease to read their mail — the local copy survives settlement regardless), the lease is a strictly opt-in power-user extension, and its fee is sender/holder-side revenue that partly lands on the operator storing the data. The read path stays toll-free.

Where SOL parks or strands

• Message accounts hold rent + stamp value until settlement. Both sides have an incentive to settle (sender: rent; recipient: postage), but nothing on-chain forces it, and the only client-driven trigger is an IMAP/POP expunge — so a recipient who archives mail forever, never deleting it from their client, leaves every message’s postage parked on its PDA indefinitely: their own postage revenue unrealized, the sender’s rent locked, and the operator’s 10% share uncollected. The auto-settle worker ([spooler.settle], on by default) closes that gap without waiting on the recipient’s mail client: it fires DeleteMail after_days (default 30) past confirmed delivery, which realizes the recipient’s postage and the operator share and returns the sender’s rent — while keeping the recipient’s local copy. Settlement reclaims the on-chain value; it does not delete the mail the recipient reads. What it does remove is the on-chain message account, and by default the sealed IPFS body too (keep_pin = false unpins it), so a past-window settled message is only trustlessly fetchable from the decentralized copy if keep_pin was set to leave the pin in place.
• Every other account class now has a close path: CloseFrombox (the recipient reclaims rent plus any residual stamp value — stamps never used; a sender who prepaid against their own wallet address can instead withdraw that residual themselves with ReclaimFromboxStamps, leaving the account alive on its rent), the two-step mailbox close and CloseKey (owner reclaims rent — the mailbox’s only at FinalizeCloseMailbox, 7 days after the request; the key account’s on the spot), CloseAlias (holder reclaims rent), CloseDomain (rent back to the recorded payer), and WithdrawPostoffice (the postmaster — a revealed key-ceremony key, see The Postmaster — sweeps accumulated revenue). A closed mailbox’s undelivered message accounts stay open and settle individually via DeleteMail; recreating the mailbox restarts message ids at zero, so new sends fail until those old message accounts are deleted — an availability nuisance, never a loss of funds.

Refunds: postage as a refundable deposit

DeleteMail settles a message to the recipient; RefundMail settles the same message back to the sender. It is the mirror image of the split in Where SOL parks or strands: where settlement collects a stranger’s postage to the recipient and the domain operator, a refund returns that postage to the sender in full — and, as in DeleteMail, the message account then drains and is reaped.

The rent and signature legs are unchanged from DeleteMail: the sender recovers the message rent plus one signature fee, and the refund signer recovers this transaction’s signature fee — both still prefunded by the STAMP_FEE_SURCHARGE_LAMPORTS bought at the Buying step. What changes is where the postage goes:

• the operator share is waived — a refund is not a revenue event, so OPERATOR_SHARE_BPS is not applied and the domain authority collects nothing;
• the recipient collects nothing — the postage they would have earned on a DeleteMail is not theirs on a refund;
• the whole remaining postage returns to the sender, on top of the rent and signature fee they already recover.

A refund is recipient-signed: only the mailbox owner can give a stranger’s postage back, so a refund can never be used to claw postage away from a recipient who means to keep it. Trigger it with the CLI — sithbit mail refund <message_id> — or the RefundMail method on the gRPC chain gateway.

Why refunds matter: a deposit, not a price

Without refunds, postage is a one-way price: a legitimate stranger who pays the recipient’s spam-pricing floor (the CLI’s default 1 SOL, which the recipient lowers per sender — see Sender) has no way to get it back, so the very defense that prices out spammers also prices out good-faith strangers. RefundMail reframes stranger postage as a refundable deposit rather than a sunk cost. The spam defense is untouched — a spammer’s postage still settles to the recipient on DeleteMail, and spammers never see a refund — while a recipient who recognizes a good-faith first contact can choose to make that sender whole. Because the deposit is only ever returned by the recipient’s own signature, pricing stays the recipient’s spam control exactly as it was; refunds add a release valve, not a loophole.

Reply bounties

Where postage pays the recipient for attention, a reply bounty pays them for an answer — the flagship of the protocol’s sender-pays positioning: the recipient doesn’t just avoid cost by being on SithBit, they earn by replying. Campaigns batch exactly this flow across an opted-in audience. The money flow:

• The escrow is the message account itself. mail send --bounty folds the bounty into the message account’s opening balance (rent + postage + bounty, all fronted by the sender at send time); no separate escrow account exists, so there is no extra rent leg and nothing else to close.
• At claim, the bounty splits 90/10: the recipient — having put a reply on-chain that carries the bounty’s reply linkage — collects 90%, and the 10% operator share follows the same domain-resolution rules as the DeleteMail settlement above: the claimant’s domain authority collects it when their mailbox names an active domain, and it falls to the mail program’s postoffice when the chain legitimately doesn’t resolve — no mailbox, no domain named, domain closed or inactive (where DeleteMail’s unresolved share folds into the recipient’s postage, a claim’s goes to the postoffice). As in DeleteMail, a named, active domain must be presented with the correct authority account or the claim is rejected, so a claimant can’t redirect the operator’s cut with filler accounts. The cut is operator_share_bps (default OPERATOR_SHARE_BPS = 1 000 bps = 10%), the same delegate-tunable rate the DeleteMail settlement and the escrowed alias transfer use; the operator’s leg is floored and the rounding dust goes to the claimant. At the default rate a 5 000 007-lamport bounty splits as 500 000 to the claimant’s domain authority — or to the postoffice, for a domainless claimant — and 4 500 007 to the claimant.
• An expired bounty refunds in full. Claims are legal through the exact expiry instant; strictly after it, mail refund-bounty returns the whole bounty to the sender. Like RefundMail above, a bounty refund is not a revenue event — no operator or postoffice share is taken.
• Deletion returns a riding bounty to the sender. If a bountied message is settled by DeleteMail — including the auto-settle worker’s — the unclaimed bounty joins the sender-refund leg. It never converts into recipient postage: the only path that pays the recipient is a claim.
• Nothing is claimable without the on-chain reply linkage. The claim evidence is a reply, in the sender’s mailbox, whose reply_to_hash names the bountied message account (a blake3 hash — no addresses on chain); claiming zeroes the bounty so no reply can claim twice.

Campaigns

A campaign introduces no new money mechanics — it is a batch of the flows already traced above, fired from one funded wallet at a set of opted-in recipients. Economically it is N bountied SendMails, and every lamport is sender-side: the campaign wallet fronts the entire per-recipient cost, which is exactly the quote itemization:

One line is campaign-wide, not per-recipient: a sender whose very first first-contact prepay happens in this campaign also fronts the one-time rent of their sender-reputation account (the prepay lazily creates the PDA), charged once no matter how many first contacts the batch holds.

The quote behind this table reads each recipient’s live chain state rather than assuming the 1 SOL protocol default: a recipient whose frombox already holds prepaid stamps costs only the send-side terms (no postage, no fee, no surcharge), a stampless frombox tops up at its stored — possibly lowered — price, and only true strangers price at the reputation-scaled first-contact rate. Unprepaid recipients carry two signature fees, one on the prepay transaction and one on the send transaction; prepaid recipients carry only the send’s.

The recipient never pays — they only collect. A participant profits twice per campaign message: the postage lands as recipient income when the message settles, and the reply bounty pays 90% at the default rate (the operator share goes to their domain authority, or the postoffice when no active domain resolves) if they answer before the window closes. Unanswered bounties are refunded to the campaign wallet in full — a refund, not a revenue event.

Opting in costs a participant nothing but a refundable deposit: the beacon account’s rent, returned when they close it. This keeps campaigns squarely on the right side of the sender-pays positioning — the burden sits entirely on the advertiser, and the recipient’s whole interaction is upside.

Modeling the postoffice’s revenue base

The settlement rates above exist because the postoffice’s naive revenue model — “a flat fee on every stamp” — mostly rounds to zero once you segment who actually buys stamps. The honest model, at the defaults and the pinned $81.16/SOL rate used throughout this page:

Stamp purchases segment into three populations, and two of them pay nothing or almost nothing:

1. Owner-prefunded fromboxes (the “friends mail you free” path): the recipient buys stamps for their correspondents, the waiver applies, revenue is zero by design. This waiver is load-bearing for the protocol’s feels-free positioning and is not a lever — every fee design must survive it.
2. Known-sender third-party prepay (a sender funding their own frombox after the recipient priced it down): postage here is friend-tier — thousands to tens of thousands of lamports — so the flat arm dominates and each stamp yields the 100 000-lamport flat fee (~$0.008). Real, but linear in mail volume and small.
3. Default-priced strangers (1 SOL postage): mostly priced out — that is the postage floor’s job — so volume is low by construction. (Since v0.39.0, reputation-scaled first-contact pricing steps this segment’s postage down for senders with a spending track record; the bps fee arm rides whatever postage is actually escrowed, so a discounted conversion pays proportionally less fee but converts more often.) Before v0.36.0 each rare conversion still paid only the 100 000 flat fee: the protocol earned ~$0.008 on a $81 postage escrow. The bps arm fixes exactly this segment: at the default 100 bps a converted 1-SOL stamp now pays 0.01 SOL ($0.81) — 100× the flat fee — while segments 1 and 2 are untouched (waived, or below the 0.01-SOL crossover).

(Since v0.37.0, purchases carrying the operator tail split each charged fee operator_share_bps to the recipient’s domain authority — so the postoffice’s take in segments 2 and 3 is ~90% of the figures above at the default rate, with the other 10% funding the operator the same way settlements do.)

The non-stamp streams scale with marketplace activity, not mail volume, and all ride the one operator_share_bps rate: alias/domain marketplace sales and auction settlements (the share lands on the postoffice directly), reply-bounty claims (domain authority, postoffice only for domainless claimants), and the DeleteMail operator share (domain authority — the postoffice keeps only the sub-1 000-lamport rounding residue). A 1-SOL alias sale yields the postoffice 0.1 SOL at the default rate; premium-name claim fees (the length tiers above) are one-time but far larger per event.

Sensitivity, honestly stated: the dominant unknown is the waiver share — the fraction of stamps bought on the waived path — which no protocol lever changes and which the positioning wants high. Bps revenue scales with postage prices the protocol does not set (recipients do) and with conversion rates on a floor designed to deter conversion. The model’s conclusion is therefore structural, not a projection: stamp-fee revenue is real but bounded, the settlement rates are the scalable levers because they piggyback every value flow without new per-feature fees, and both are capped (10% / 20%) so the “minimal rake, no token” positioning survives a hostile delegate key.

Which unit each surface speaks

On-chain there is exactly one money unit: the lamport, one-billionth of a SOL. Every price, fee, deposit, and balance the three programs store is an integer count of them, and so is every figure on this page. What differs is how each client spells that integer, and the split between them is a rule:

• The CLI takes lamports. alias sell --price, alias sell --auction --reserve, alias bid --amount, mail send --bounty, mailbox create --default-postage, the delegate’s postmaster fee … setters — every money argument the sithbit binary reads is an integer number of lamports. The CLI is a scripting surface, and an exact integer in the chain’s own unit composes: it survives shell substitution and generated command lines with no float rounding, no locale decimal separator, and no ambiguity about which unit a bare number is in — and it is the same unit an RPC response or a program error quotes back. Reports may annotate a figure with a SOL and best-effort USD tail for readability (sithbit earnings, frombox get, mailbox get --usd); nothing the CLI accepts is denominated in SOL.
• The human-facing clients show SOL. Webmail, the marketplace, and the Outlook / Thunderbird / Chrome panes quote stamp prices, wallet balances, reply bounties, and asking prices in SOL, because SOL is the unit a person holds in a wallet and compares against a price. They convert at their own edge — someone types an asking price of 0.05 SOL, the pane sends 50 000 000 lamports.

No surface mixes the two: everything on a sithbit command line is lamports, everything in a webmail or marketplace field is SOL. The auction flags follow the rule rather than carve an exception out of it — --reserve and --amount are lamports because their siblings --price and --fee are, and a marketplace that read a reserve in SOL and a fixed price in lamports would be a foot-gun for anyone scripting both.

Constants worth knowing

Protocol economics are consensus constants in mail_model::constants. Four are fixed and never change without a program upgrade:

The other nine are defaults, not fixed constants — the delegate can retune each one, and each is bounded on-chain by its own MAX_* cap so a compromised delegate key cannot price the protocol out of reach:

Tune them with sithbit postmaster fee stamp / fee domain / fee alias / fee alias-tiers / fee settlement / fee attestation / fee reputation-floor / fee pin-lease (a delegate-only op), and read the current values back with the public, read-only sithbit postoffice fee stamp / fee domain / fee alias / fee settlement / fee pin-lease (the alias getter prints the flat fees and the effective per-length premium schedule together; the settlement getter prints both bps rates; the effective floor prints with any wallet’s sithbit postoffice reputation). A postoffice account that predates a fee field reads back its protocol default.

On-chain CreateMailbox applies the 1-SOL DEFAULT_POSTAGE_LAMPORTS spam-pricing floor (the wall the owner then lowers per sender) when the instruction omits a price — a raw-instruction caller must opt into a cheaper (or free) mailbox explicitly; the safety margin is no longer client-side only.

Rent hygiene (implemented)

The follow-ups the original analysis recommended are now protocol behavior (see the “Economics” record in HANDOFF.md):

• Domain economics — CreateDomain takes an explicit payer (delegate or authority; the delegate always signs), charges DOMAIN_AUTHORIZATION_FEE_LAMPORTS to the postoffice, and records the rent_payer so CloseDomain can refund the rent to whoever funded it.
• Close instructions — CloseFrombox (recipient reclaims residue + rent) and its sender-side counterpart ReclaimFromboxStamps (a wallet-address sender withdraws its own unspent postage; the account survives on its rent), RequestCloseMailbox/FinalizeCloseMailbox and CloseKey (owner reclaims rent; see the close timelock below), CloseAlias (holder reclaims rent), and WithdrawPostoffice (the postmaster — via a key-ceremony proof — sweeps the postoffice balance above its rent-exempt minimum — without which the accumulated protocol fee revenue would be unspendable).
• Alias fee — an ALIAS_FEE_LAMPORTS charge on alias creation (and an ALIAS_TRANSFER_FEE_LAMPORTS charge on transfer), CPI-transferred to the mail program’s postoffice, pricing out squatting. Both are delegate-tunable (SetAliasFee, capped on-chain) and waived when the payer is the delegate (the round-trip waiver kept its shape through the delegation cutover) — see bulk alias reservation.

The mailbox close timelock

Rent hygiene has an abuse edge. Rent that comes back instantly makes an identity disposable: a sender whose wallet had burned its reputation could CloseMailbox, take the full refund, and stand up a fresh identity for the price of a signature. Cheap identity-cycling is the one thing a postage-priced system cannot afford, because postage only bites a sender who has something to lose by being recognized.

So closing a mailbox is now timelocked: a request starts a 7-day clock and refunds nothing (the mailbox stays open and keeps receiving mail), a finalize past the clock closes it and returns both the mailbox’s rent and the transient pending record’s, and a cancel aborts the request meanwhile. The one-step CloseMailbox is refused on-chain with error 94, InstantCloseDisabled.

The lever here is deliberately a delay, not a fee, and that follows straight from the positioning principle this whole page is written against — the system must feel free to use and be profitable for recipients, with the cost burden on senders. A mailbox owner is a recipient. Charging them to leave would be a recipient-side cost, which is presumptively the wrong shape. Time is the only currency available that bills the spammer (capital stuck for a week per burned identity, plus a week in which operators can watch a mailbox announce its own close) while costing an honest owner nothing but patience on an action they take approximately never. The rent comes back in full either way.

CloseKey is deliberately exempt and stays instant — it revokes a compromised delegated encryption key, where a waiting period would protect the attacker rather than the owner. See the threat model.

Money is only half the picture: for what each participant must trust — the MX operator’s sender authentication, the postoffice admin keys, public message metadata, and frombox custody (including that CloseFrombox returns third-party-funded stamps to the recipient, not the buyer — a sender can only withdraw postage they prepaid against their own wallet address) — see Trust assumptions and threat model.

1. The recipient’s payout is rounded down to the nearest POSTAGE_ROUNDING_LAMPORTS (1 000 lamports); the sub-quantum remainder — at most 999 lamports per message — accrues to the postoffice. This is below the smallest price increment anyone quotes and isn’t something senders, recipients, or operators need to think about. ↩

CLI Quickstart

This documentation is primarily geared towards developers rather than end-users. (Operators looking to run the mail services themselves should start at Running a mail server.) To follow the examples, you’ll need the sithbit CLI built from the sithbit-solana repository: clone the repo and build it with cargo build -p mail-client -r, which produces the sithbit binary at target/release/sithbit.

The fast path: sithbit setup

If you just want to get going, run the guided setup wizard and follow the prompts:

sithbit setup

It walks you through the two things you need — a Solana RPC endpoint and a signing wallet, offering to generate a fresh wallet if you don’t already have one — checks that the wallet holds enough SOL to claim a mailbox (funding it automatically from the faucet on devnet-style clusters, or walking you through a transfer on mainnet), and can optionally claim your on-chain mailbox in the same pass, then prints the next steps to start receiving mail. The wizard is re-runnable and non-destructive: it shows your current settings, changes only what you explicitly ask it to, and never overwrites an existing keypair, so running it again on a configured machine is safe. Pressing Enter at any prompt keeps the current value (with one exception: on a machine with no wallet yet, Enter at the endpoint prompt accepts a suggested default — mainnet for release builds, devnet for development builds); the mailbox step — the one that spends SOL — defaults to skip, so a scripted or piped run never sends a transaction. See First-run setup for a full walkthrough.

The rest of this page does the same two steps by hand — useful when you want to understand exactly what setup writes, or to script the pieces individually.

Configuring a Solana RPC endpoint

Talking to the chain also needs a Solana RPC endpoint — the URL of a server that answers reads and forwards transactions for one of Solana’s networks (see Solana clusters and RPC endpoints for what the public clusters are and which one SithBit runs on). Configure one with sithbit config set --url <cluster> (e.g. https://api.devnet.solana.com), or point a JSON_RPC_URL environment variable at one directly.¹

Creating a wallet

You’ll need a cryptographic keypair / wallet; its public key becomes your first email address. sithbit can generate one directly:

sithbit wallet create
# Wallet keypair written to '/home/you/.config/solana/id.json'
# Address: 85FZrun1Eb5bdkbFCDjaFSTLnBfnx6sUFHa5BiYH2Q03

By default this writes to the path sithbit config get reports as your keypair path.² Pass --outfile <path> to write elsewhere; sithbit wallet create refuses to overwrite an existing keypair file unless you also pass --force.

Even though there is no domain portion of the address, i.e., 85FZrun1Eb5bdkbFCDjaFSTLnBfnx6sUFHa5BiYH2Q03@sithbit.com, your standalone public key address is already a legitimate email address in the system, although you will need to create a mailbox for it and at least one frombox before emails can be routed to your address. A frombox is keyed by a pair: your wallet address as the recipient, and a sender’s “from” address — but only the recipient side needs to be an on-chain wallet. The sender’s “from” address is just a plain, off-chain RFC822-compliant address string (e.g. jane_doe@sithbit.com, or any other domain) — it never has to resolve to a Solana keypair.

Neither step above needs the Solana CLI/SDK installed at all — sithbit config and sithbit wallet create are a complete substitute for it in this workflow.

1. If you already have the Solana CLI installed, solana config set --url <cluster> writes the same config file. ↩

2. If you already have the Solana CLI/SDK installed, solana-keygen new followed by solana-keygen pubkey gets you the same keypair file and address. ↩

First-run setup: sithbit setup

sithbit setup

A guided, re-runnable first-run wizard. It configures the two things every other command depends on — a Solana RPC endpoint and a signing keypair — using plain stdin prompts, makes sure the wallet can afford a mailbox, can optionally claim your on-chain mailbox in the same pass, and then points you at the next steps. It takes no flags: everything is driven by the dialogue.

It is deliberately non-destructive. It reads your current config values up front and shows them, writes a change only when you type an explicit new value (pressing Enter keeps the current one), and confirms before generating a wallet — so re-running it on an already-configured machine, or against a funded keypair, never clobbers anything. The one exception to “Enter changes nothing” is a brand-new machine: when no wallet exists yet the wizard suggests a default endpoint, and pressing Enter accepts and writes that suggestion. The one step that spends SOL and sends a transaction — the mailbox create — defaults to no, so a piped or closed stdin never fires it by accident.

The wizard runs five steps:

1. RPC endpoint. Shows the currently configured endpoint. Enter a new URL to switch clusters (this writes the same config sithbit config set --url edits), or press Enter to keep the current one. On a machine with no wallet yet, the wizard instead suggests a build-appropriate default — mainnet for release builds, devnet for development builds — and Enter accepts and persists the suggestion. (The two endpoint constants live at the top of mail_client/src/commands/setup.rs, so an operator shipping a hosted RPC endpoint swaps them in one place.)
2. Signing keypair. Shows the current keypair path and lets you change it. If no readable keypair exists at the chosen path, it offers to generate a fresh wallet there (the same artifact sithbit wallet create writes). It asks first, so a re-run never overwrites an existing wallet; decline and it prints the manual sithbit wallet create command instead.
3. Wallet funding. Checks that the settled wallet — freshly generated or pre-existing — holds enough SOL to pay for a mailbox create (the account rents, the flat alias fee, and a small fee buffer; about 0.0124 SOL). A wallet that already covers it, or that already owns a mailbox, skips the step with a note. Otherwise, on clusters with a faucet (devnet, testnet, a local validator) the wizard requests an airdrop of one SOL, retrying a few times because the public devnet faucet is flaky; on mainnet — or if the faucet stays dry — it prints your wallet address and the required amount, re-checks the balance each time you press Enter, and lets you type skip to move on unfunded. (The devnet web faucet at faucet.solana.com is the manual fallback when the RPC faucet errors.)
4. Mailbox. Offers to claim your on-chain mailbox right now, defaulting to skip (only an explicit y/yes proceeds). Accept and it prompts for the mail domain (default sithbit.com) and the default stamp price in lamports (default one SOL), then drives the same on-chain create as sithbit mailbox create — which also mints the wallet’s self-alias in the same transaction. It is re-run-safe: a create against a mailbox that already exists errors on-chain, and the wizard surfaces that message and carries on to completion rather than aborting. Decline and it prints the manual sithbit mailbox create command instead.
5. Next steps. Static guidance — create your on-chain mailbox (if you skipped step 4), set a default stamp price, and review your settings with sithbit config get.

Example

A first run on a machine with no wallet yet, switching to devnet, letting the wizard generate a keypair, fund it from the faucet, and claim a mailbox inline:

$ sithbit setup
SithBit setup — configure your RPC endpoint and wallet.
Config file: /home/you/.config/solana/cli/config.yml

Step 1/5  RPC endpoint
  Current: https://api.mainnet-beta.solana.com
  New URL (Enter keeps current): https://api.devnet.solana.com
  Set RPC endpoint to https://api.devnet.solana.com.

Step 2/5  Signing keypair
  Current: /home/you/.config/solana/id.json
  No keypair file found at /home/you/.config/solana/id.json.
  Generate a new wallet there now? [Y/n]: y
  Generated a new wallet at /home/you/.config/solana/id.json.

Step 3/5  Wallet funding
  Requesting 1000000000 lamports (1 SOL) from the cluster faucet…
  Airdropped 1000000000 lamports (1 SOL).

Step 4/5  Mailbox
  A mailbox is your on-chain inbox — claim one to start receiving mail.
  Create your mailbox on-chain now? [y/N]: y
  Domain [sithbit.com]:
  Default stamp price in lamports [1000000000]:
  Created your mailbox for domain sithbit.com.

Step 5/5  Next steps
  You're configured. To start receiving mail:
    1. sithbit mailbox create   # claim your on-chain mailbox
    2. sithbit mailbox update   # set your default stamp price
    3. sithbit config get       # review your settings anytime

Done.

On mainnet the funding step has no faucet to lean on, so a wallet short of the mailbox cost is shown its own address and the amount to send, and the wizard re-checks the balance each time you press Enter:

Step 3/5  Wallet funding
  Creating a mailbox costs about 12415720 lamports (0.01241572 SOL).
  Send at least that much to your wallet address:
    85FZrun1Eb5bdkbFCDjaFSTLnBfnx6sUFHa5BiYH2Q03
  Press Enter to re-check the balance, or type 'skip':

If a keypair already exists at the chosen path the wizard reports Found an existing keypair at … and skips generation entirely; a wallet that already holds enough SOL passes the funding step with a one-line note, and one that already owns a mailbox skips both the funding wait and the create prompt. Declining the mailbox step (the default) prints Claim one later with: sithbit mailbox create and moves on, and re-running the wizard against a wallet that already owns a mailbox prints You already have a mailbox — skipping. and still finishes. The prompts also default cleanly on end-of-input, so a piped or closed stdin takes every default — including skipping the funding wait and the mailbox create — rather than hanging.

Prefer a browser? The four web clients walk a brand-new user through the same five steps without a terminal — see Getting started. And once you’re set up, the read-only sithbit earnings snapshot shows what your wallet holds and has taken in.

Looking up a mailbox

See Mailboxes for what a mailbox is and the settings it holds. This page covers the sithbit mailbox get command.

sithbit mailbox get [owner_address]

mailbox get is a read-only query: it derives the mailbox PDA for the given address, reads the account, and prints its settings. It signs nothing, spends nothing, and needs no CLI feature flag — anyone can inspect any mailbox.

Arguments

• [owner_address] (optional) — the address whose mailbox to look up. Defaults to the address of your own configured keypair, so sithbit mailbox get with no arguments looks up your own mailbox.

What it prints

mailbox get prints the mailbox’s mail count, default postage, domain, and no-IPFS opt-out flag — see Mailbox settings for what each one means.

Related commands

• Create a mailbox — create the mailbox for an address that doesn’t have one yet.
• Update a mailbox — change an existing mailbox’s settings.
• Mailbox keys — publish a delegated encryption key for signing-only wallets.

See Closing accounts for how to close a mailbox you no longer need.

Create a mailbox

See Mailboxes for what a mailbox is, the settings it holds, and why creating one also claims a self-alias and carries an IPFS opt-out trade-off. This page covers the sithbit mailbox create command.

sithbit mailbox create \
  [--keypair <path>] \
  [--default-postage <lamports>] \
  [--domain <domain>] \
  [--no-ipfs] \
  [--for <address>] \
  [--skip-preflight]

Before running it you need a Solana wallet — see CLI Quickstart — and, if you’re naming a domain, that domain must already be registered and active on-chain; creation refuses an unregistered or deactivated name. A wallet has exactly one mailbox, and a mailbox names exactly one domain (switch it later with mailbox update --domain).

No encryption setup is required: mail servers seal mail straight to your wallet address, and your wallet keypair file decrypts it. Only wallets that cannot expose a decryption key (hardware and browser wallets, which can only sign) need to publish a delegated encryption key.

Arguments

• --keypair <path> (optional) — the mailbox owner’s keypair. Defaults to the keypair in your Solana CLI config when omitted.
• --default-postage <lamports> (optional) — the starting default postage for the mailbox, in lamports. Defaults to 1 SOL worth of lamports; set it high to price out spam, then lower it per-sender by adjusting a frombox’s stamp price.
• --domain <domain> (optional) — the domain that can send mail to this mailbox, by name (e.g. sithbit.com) or by its account address. Defaults to sithbit.com when omitted.
• --no-ipfs (optional) — a bare flag; present opts the mailbox out of public IPFS body storage from the start, absent leaves it off (the default). See Opting out of IPFS storage.
• --for <address> (optional) — create the mailbox for a different owner (a base58 wallet address): a sponsored create, see below. Requires --domain, and the fee payer must be that domain’s on-chain authority.
• --skip-preflight (optional) — submits the transaction without a local simulation pass first.

Sponsored creation (--for)

A domain’s on-chain authority can provision mailboxes for other wallets under its domain — see Sponsored mailboxes for the concept and its guards. With --for, the fee payer funds the mailbox but the named address owns it:

• The payer must be the on-chain authority of the --domain domain; anyone else is refused (UnauthorizedDomainSponsor, error 96). Omitting --domain is refused client-side, and a raw instruction without a domain fails on-chain (SponsoredMailboxRequiresDomain, error 95).
• Any --default-postage you pass is overridden to the 1-SOL spam floor on-chain.
• The self-alias is not bundled — the owner claims their own alias.
• The payer is recorded as the mailbox’s funder: closing the mailbox refunds its rent to the payer, not the owner.

Examples

Create a mailbox with an explicit postage and domain:

sithbit mailbox create \
  --default-postage 100000 \
  --domain sithbit.com \
  --keypair <path to wallet keypair>

Create a mailbox that opts out of public IPFS storage from the start:

sithbit mailbox create \
  --domain sithbit.com \
  --no-ipfs \
  --keypair <path to wallet keypair>

As a domain’s authority, sponsor a mailbox for one of your users (the postage you’d pass is forced to the 1-SOL floor either way):

sithbit mailbox create \
  --for <user wallet address> \
  --domain example.com \
  --keypair <path to the domain authority's keypair>

Related commands

• Looking up a mailbox — inspect a mailbox’s settings, including whether it opted out of IPFS.
• Update a mailbox — change postage, domain, or the no-IPFS flag on a mailbox that already exists.
• Mailbox keys — publish a delegated encryption key for signing-only wallets.

Update a mailbox

See Mailboxes for what a mailbox is and the settings it holds. This page covers the sithbit mailbox update command.

sithbit mailbox update \
  [--keypair <keypair>] \
  [--default-postage <lamports>] \
  [--domain <name or address>] \
  [--no-ipfs <true|false>] \
  [--skip-preflight]

All of --default-postage, --domain, and --no-ipfs are optional — only the ones you supply are changed. For example, raising the default postage to price out a recent wave of spam:

sithbit mailbox update --default-postage 2000000000

…or moving to a different domain:

sithbit mailbox update --domain sithbit.net

The new domain must already be registered on-chain and active — updating a mailbox to reference an unregistered or deactivated domain is refused.

…or toggling the IPFS opt-out: --no-ipfs true opts out (your operator keeps bodies in its own store, off public IPFS), and --no-ipfs false clears it so new mail is pinned to IPFS again. Omitting the flag leaves the current setting untouched. The change applies to mail delivered after it lands — bodies already pinned stay where they are.

sithbit mailbox update --no-ipfs true

Arguments

• --keypair <path> (optional) — the mailbox owner’s keypair. Defaults to the keypair in your Solana CLI config when omitted.
• --default-postage <lamports> (optional) — the new default postage for the mailbox, in lamports. Omitted leaves the stored value unchanged.
• --domain <name or address> (optional) — the domain that can send mail to this mailbox, by name (e.g. sithbit.net) or by its account address. Omitted leaves the stored domain unchanged.
• --no-ipfs <true|false> (optional) — true opts the mailbox out of public IPFS body storage, false clears the opt-out. Omitted leaves the stored flag unchanged. See Opting out of IPFS storage.
• --skip-preflight (optional) — submits the transaction without a local simulation pass first.

Examples

Raise the default postage to price out a recent wave of spam:

sithbit mailbox update --default-postage 2000000000

Move to a different domain:

sithbit mailbox update --domain sithbit.net

Opt a mailbox out of public IPFS storage, then opt back in later:

sithbit mailbox update --no-ipfs true
sithbit mailbox update --no-ipfs false

Related commands

• Looking up a mailbox — inspect a mailbox’s current settings before or after an update.
• Create a mailbox — create the mailbox in the first place.
• Mailbox keys — publish a delegated encryption key for signing-only wallets.

When a mailbox is no longer needed, see Closing accounts for mailbox close and mailbox key close.

Mailbox keys

See Mailboxes for why mail is sealed to your wallet address by default and when a delegated encryption key is needed. This page covers the sithbit mailbox key commands that publish, rotate, read, and clear that optional on-chain key.

CLI build note: key create and key set are gated behind the CLI’s rand feature, which is on by default — a stock cargo build -p mail-client has them, and only a --no-default-features build that leaves rand out drops the pair. key get and key close are ungated. See sithbit mailbox reading-secret for the full note on what else that feature carries.

mailbox key create

Generates a delegated X25519 keypair client-side and writes it to a file — this does not touch the chain:

sithbit mailbox key create <output path>

mailbox key set

Publishes (or replaces) the delegated key on your mailbox:

sithbit mailbox key set <keypair path> \
  [--keypair <path>] \
  [--skip-preflight]

Arguments

• <keypair path> (required) — the delegated X25519 keypair file to publish, as generated by mailbox key create.
• --keypair <path> (optional) — the mailbox owner’s keypair, used to sign the transaction. Defaults to the keypair in your Solana CLI config when omitted.
• --skip-preflight (optional) — submits the transaction without a local simulation pass first.

Re-running mailbox key set with a fresh keypair file rotates the key: senders start sealing to the new public key immediately, and mail already sealed to the old key still opens with the old key file.

mailbox key get

Reads the published key back, if one exists:

sithbit mailbox key get [owner_address]

• [owner_address] (optional) — the address whose mailbox to look up. Defaults to your own configured keypair’s address.

Prints the delegated X25519 public key as base58 when one is published, or reports that the mailbox has no delegated key (i.e. mail is sealed to the wallet address).

mailbox key close

Removes the delegated key account and reclaims its rent, returning the mailbox to wallet-sealed mail:

sithbit mailbox key close \
  [--keypair <path>] \
  [--skip-preflight]

Examples

Generate a delegated key, publish it, then confirm it’s live:

sithbit mailbox key create my_delegated_key.json
sithbit mailbox key set my_delegated_key.json --keypair <path to wallet keypair>
sithbit mailbox key get

Rotate to a fresh key:

sithbit mailbox key create my_new_key.json
sithbit mailbox key set my_new_key.json --keypair <path to wallet keypair>

Stop using a delegated key and fall back to wallet-sealed mail:

sithbit mailbox key close --keypair <path to wallet keypair>

Related commands

• Looking up a mailbox — inspect a mailbox’s other settings.
• Create a mailbox — create the mailbox that a delegated key attaches to.
• Update a mailbox — change postage, domain, or the no-IPFS flag.

See Appendix: How sealed-box encryption works for the full protocol, and Closing accounts for mailbox key close alongside other account-closing commands.

Mailbox credentials

See Addresses for how your wallet address is your mail identity. This page covers the two commands that derive a mail app’s login material from your wallet keypair, offline: sithbit mailbox credentials (who you are) and sithbit mailbox reading-secret (what opens your mail) — and their third neighbour, sithbit mailbox sign-text, the raw signer that answers a challenge the account service just handed you.

None of the three is needed in the webmail app or the Thunderbird/ Outlook extensions: they derive both login values in the page, sign you in with them, and have your wallet sign any challenge the account service asks for without your typing anything. These commands are for configuring a stock mail app by hand — and, for sign-text, for driving the account API from a shell or a script.

sithbit mailbox credentials

sithbit mailbox credentials \
  [--keypair <path>] \
  [--epoch <N>]

credentials prints the username/password pair a stock mail app uses to authenticate to the SithBit SMTP/IMAP/POP servers as your wallet — with no separate stored password. The username is your wallet address (the base58 public key); the password is a base58 wallet signature over a challenge that embeds that same public key and your account’s current auth epoch. The servers verify the signature against the username, and nothing is stored server-side — the signature is self-proving.

Read that binding precisely: the password is tied to your wallet and that epoch, so nobody can present it as a different wallet, and it stops working the moment you rotate the epoch. It is not otherwise single-use. Anyone who captures it can replay it as you, on any of the three protocols, until you rotate — which is what makes rotation the revocation lever rather than a housekeeping step, and TLS non-optional. See the threat model for what else follows from that.

The command is fully offline: it contacts no RPC endpoint, reads nothing on-chain, and writes no files. Both values are derived purely from the local wallet keypair, and because the signature is deterministic, re-running the command for the same keypair and epoch prints the identical pair every time — paste it into a mail app once and you are done.

Arguments

• --keypair <path> (optional, -k) — the wallet keypair file the credentials are derived from. Defaults to the keypair in your Solana CLI config when omitted.
• --epoch <N> (optional, default 0) — the auth epoch to sign for. 0 is an account that has never rotated; after a rotation, pass the epoch the account now reports. Offline means offline: the command cannot look this up for you, so a wrong value here is the one way to get a well-formed password the servers refuse.

The auth epoch, and rotation

A wallet signature never expires on its own — whoever copied your mail password holds it for good. The auth epoch is the handle that takes it back: a counter the account keeps, mixed into the challenge the wallet signs, so adding one to it changes the bytes every valid password must sign over and retires every copy of the old one at once, on every listener.

Rotating is done from the account, not from here — the webmail app’s Settings pane (the same control the Thunderbird/Outlook extensions and the operator’s enrollment page carry), or POST /v1/account/auth-epoch directly. Both report the new epoch; GET /v1/account reports the current one at any time. This command’s job is the other half: deriving the password that matches whatever epoch the account is on now.

That is what the output leads with, so a mismatch is visible before it becomes a mystery:

Auth epoch:         0
Mail auth username: <your wallet address>
Mail password:      <base58 signature>

These credentials are valid ONLY at auth epoch 0.
If your account shows a different auth epoch (webmail, or GET /v1/account),
re-run with --epoch <N> — otherwise this password will be rejected.

Three limits are worth knowing before you rotate, because a rotation is narrower than it sounds:

• It retires the wallet-derived password only. A stored mail password, if the account has one, keeps working exactly as before, so rotation is not a way to shut that path. Closing it is a separate, equally deliberate gesture — Remove the stored mail password on the webmail Settings pane, or DELETE /v1/account/password — and it leaves the auth epoch, and so this command’s output, untouched.
• It does not end web or add-in sessions. A session token is untouched and stays valid to its expiry; only mail apps have to be re-provisioned with the new password.
• It does not revoke a client-certificate login. SASL EXTERNAL proves identity from the certificate in the TLS handshake rather than from a signature over the epoch, so a bump leaves it working; only the operator turning client_cert_auth off for the listener closes it.

The one compatibility note: a password derived before epochs existed still authenticates an account that has never rotated, which is why --epoch defaults to 0 and nothing broke on the day epochs landed. The first rotation ends that grace for that account permanently — from then on only a password derived at the account’s exact current epoch is accepted.

Using the credentials

Enter the printed pair in your mail client as its ordinary username and password — SASL PLAIN over TLS for IMAP/submission, or the plain POP3 PASS login. The password is bearer-equivalent for the connection, so always use TLS. The client walk-throughs show exactly where each value goes, and how the browser/mail-app extensions derive the same pair without the CLI: Thunderbird and Outlook.

Because the username here is your wallet address, the server looks nothing up: the signature proves the account directly. A client configured with an alias and a stored mail password instead — the password path the account service manages — does need that name resolved to a wallet, and aliases move: a transfer, a sale, or the settlement of an auction re-points one at a new holder, and nobody needs permission to make that happen. The guarantee is that the resolution happens once per login: the account your password authenticates is the account the session opens, so a name that changes hands in the instant between the two cannot hand your session to anyone else’s mail, or theirs to you. See a re-pointed alias cannot redirect a mail login for the full statement.

Examples

Print the credentials for the Solana CLI config’s default wallet:

sithbit mailbox credentials

Derive them for a specific keypair file:

sithbit mailbox credentials --keypair ~/.config/solana/id.json

Re-derive them after a rotation — for an account whose settings pane now reads auth epoch 3:

sithbit mailbox credentials --epoch 3

sithbit mailbox reading-secret

sithbit mailbox reading-secret \
  [--keypair <path>]

reading-secret prints the base58 reading key secret that opens mail sealed to this wallet address: the X25519 twin of your wallet keypair, which is what senders — and your operator’s at-rest sealing — wrap to whenever the mailbox publishes no delegated key. It is derived from the local keypair alone, so the command is fully offline, deterministic, and prints the same string every time. The address it belongs to goes to standard error and the secret alone to standard output, so the command pipes cleanly.

This one really is a secret. The credentials password above only authenticates — it proves you hold the wallet and is useless for anything else. The reading secret decrypts: whoever holds it reads every message ever sealed to that wallet, the delivered ones as much as the future ones, and no rotation takes that back for mail already sealed. Print it into a mail app’s password field and nothing else; never into a chat, a ticket, or a shell history you keep.

CLI build note: reading-secret is one of the commands gated behind the CLI’s rand feature — but rand is on by default, so a stock cargo build -p mail-client already has it and there is nothing to enable. Only a slimmed --no-default-features build that does not add rand back drops the command, together with the feature’s other surfaces: delegated-key generation and the local body decryption flags. Its two neighbours on this page, credentials and sign-text, are ungated and ship in every build.

Arguments

• --keypair <path> (optional, -k) — the wallet keypair file the secret is derived from. Defaults to the keypair in your Solana CLI config when omitted.

Using the reading secret

A mail app that logs in with the wallet-signature password alone still sees your account, its folders and its message list — but on a deployment that seals mail at rest, the bodies it cannot open show up locked. To read them, append the reading secret to that password after a single .:

<password from `mailbox credentials`>.<secret from `mailbox reading-secret`>

. never appears in base58, so the two halves are unambiguous. Use the joined value for the incoming server only (IMAP or POP, over TLS). The submission (SMTP) server refuses a password carrying a reading secret: sending mail never needs your decryption key, so a misconfigured client fails loudly there instead of shipping the secret to a service that has no use for it. The secret is held for the session, used to unwrap that session’s messages, and dropped when the session ends; nothing stores it.

If your mailbox publishes a delegated key, that key — not this one — is what mail is sealed to; read it with the key file from Mailbox keys instead.

Examples

Print the reading secret for the Solana CLI config’s default wallet:

sithbit mailbox reading-secret

Derive it for a specific keypair file, keeping the address note out of the piped value:

sithbit mailbox reading-secret --keypair ~/.config/solana/id.json

sithbit mailbox sign-text

sithbit mailbox sign-text <TEXT> \
  [--keypair <path>]

sign-text prints the base58 ed25519 signature of your wallet keypair over the exact UTF-8 bytes of <TEXT> — the proof the account service’s challenges ask for. Fetch a challenge from POST /v1/auth/step-up, sign the nonce it hands back, and send the signature in the gated write’s x-sithbit-step-up header. Like its two neighbours above, the command is fully offline: no RPC endpoint, no chain read, no HTTP call, nothing written — so it runs on an air-gapped machine holding the wallet.

It is a raw signer: nothing is prepended, appended, hashed or trimmed. Domain separation is the challenge’s job — the account service’s nonces carry their own SithBit login nonce: or SithBit step-up nonce: prefix and are verified against exactly the string that was issued, which is why a signature collected at login can never be presented as a step-up proof, or the reverse. The rule that follows is short: sign only text a server just handed you, pasted verbatim. One stray trailing space is a different message, and the signature over it will not verify.

The browser clients never need this. Webmail and the Thunderbird/ Outlook/ Chrome extensions sign the same challenge in the page with the wasm wallet — the identical signer, byte for byte — so the settings pane’s buttons already run the whole dance, invisibly with an in-app wallet and as an approval prompt on a Phantom or Ledger one. sign-text is for the surfaces that have no button: a shell, a script, a provisioning job.

Arguments

• <TEXT> (required, positional) — the string to sign, verbatim. Quote it: a challenge nonce contains spaces and a colon.
• --keypair <path> (optional, -k) — the wallet keypair file that signs. Defaults to the keypair in your Solana CLI config when omitted.

Output, and capturing it

The signature alone goes to standard output; the wallet it signed as goes to standard error, where it is visible interactively without polluting the captured value:

Signed as <your wallet address>:
<base58 signature>

So a shell capture holds exactly the header value, with nothing to trim:

PROOF=$(sithbit mailbox sign-text "$NONCE" --keypair ./wallet.json)

One signature, one request

A challenge lives 300 seconds and is spent by the first request that carries it, whatever that request answers — a success, a wrong signature and an expired one all consume it. So sign the nonce you were just handed, send it once, and after any failure fetch a fresh challenge and sign that one; re-sending the same proof answers 428 for good. Two gated writes are two challenges, not one. See One proof, one mutation for the full contract.

Examples

Sign a step-up nonce with the Solana CLI config’s default wallet:

sithbit mailbox sign-text "SithBit step-up nonce: 0f9c2b1a-4d3e-4c5f-8a7b-6d5e4f3c2b1a"

Sign it with a specific keypair file:

sithbit mailbox sign-text "SithBit step-up nonce: 0f9c2b1a-4d3e-4c5f-8a7b-6d5e4f3c2b1a" --keypair ~/.config/solana/id.json

The per-recipient pin provider walkthrough is the worked example, end to end: challenge, signature, gated write.

Related commands

• Create a client certificate — the password-less alternative: a TLS client certificate that logs the same wallet in over SASL EXTERNAL, for servers with client-certificate auth enabled.
• Create a mailbox — the credentials log you in to a server account; the mailbox is what receives your on-chain mail.
• Looking up a mailbox — inspect a mailbox’s settings.
• Mailbox keys — publish a delegated encryption key, which replaces the wallet twin above as what mail is sealed to.

Create a client certificate

See Addresses for how your wallet address is your mail identity. This page covers the sithbit mailbox create-cert command.

sithbit mailbox create-cert \
  [--keypair <path>] \
  [--out <prefix>]

create-cert mints the TLS client certificate a stock mail app (Thunderbird, Outlook, …) presents to log in over SASL EXTERNAL: a self-signed Ed25519 leaf whose public key is your wallet’s signing key, so the SMTP/IMAP/POP servers read the wallet address straight off the certificate during the TLS handshake — no password typed, nothing stored on either side. The server must have client_cert_auth turned on for the listener (see the configuration reference); your wallet address stays the username. (Thunderbird itself currently cannot import the bundle — see the known issue in its walk-through; the files stay valid for other clients.)

The command is fully offline: it contacts no RPC endpoint and writes nothing on-chain. Everything is derived purely from the local wallet keypair, so you can regenerate the same files any time, anywhere — and because the certificate is self-signed, there is no certificate authority and no renewal to manage.

Arguments

• --keypair <path> (optional, -k) — the wallet keypair file the certificate is derived from. Defaults to the keypair in your Solana CLI config when omitted.
• --out <prefix> (optional, -o) — output path prefix; the three files below are written as <prefix>.crt / <prefix>.key / <prefix>.p12 (an extension already on the prefix is replaced, not appended). When omitted, the certificate and key PEM blocks are printed to stdout instead, and no .p12 is written.

What it writes

With --out <prefix>, three files:

• <prefix>.crt — the certificate, as PEM.
• <prefix>.key — the private key, as PKCS#8 PEM.
• <prefix>.p12 — both combined in a password-less PKCS#12 bundle, the one file meant for a mail app’s certificate-import dialog (Thunderbird currently refuses it — see the known issue).

The .p12 carries no MAC and no password, so its bytes are deterministic per wallet: re-running the command for the same keypair reproduces the identical file. The .key and .p12 files embed your wallet secret — guard them like the wallet itself.

Installing the certificate

Importing the files into a mail app — including leaving the .p12 import’s password prompt blank — is covered step by step in the client walk-throughs: Thunderbird and Outlook. Both pages also show how their extension mints the identical files without the CLI.

Examples

Print the certificate and key PEM to stdout:

sithbit mailbox create-cert

Write ./mywallet.crt, ./mywallet.key, and ./mywallet.p12:

sithbit mailbox create-cert --out ./mywallet

Related commands

• Mailbox keys — the other optional key: a delegated X25519 encryption key for signing-only wallets. Unrelated to login — the client certificate authenticates you to mail servers, the delegated key changes what senders seal mail to.
• Create a mailbox — the certificate logs you in to a server account; the mailbox is what receives your on-chain mail.
• Looking up a mailbox — inspect a mailbox’s settings.

Close a mailbox

See Mailboxes for what a mailbox is and the rent it holds. This page covers the sithbit mailbox close command’s three modes: request, --finalize, and --cancel.

Closing a mailbox is not instant. It runs through a two-step, 7-day close timelock: a request starts the clock and leaves the mailbox open and receiving mail, a finalize actually closes it once the clock has elapsed, and a cancel aborts the request meanwhile. The mailbox’s rent comes back only at finalize — the request refunds nothing.

sithbit mailbox close \
  [--finalize] \
  [--cancel] \
  [--keypair <path>] \
  [--skip-preflight]

Arguments

• --finalize (optional) — closes the mailbox once the timelock has elapsed since the request, refunding the transient pending-close account’s rent to the owner and the mailbox’s rent to its recorded funder — the owner itself on a normal mailbox, or the sponsoring domain authority on a sponsored mailbox (the CLI reads the funder from the mailbox automatically, as does the webmail Mailbox pane). Run before the timelock has elapsed, it is rejected on-chain. Mutually exclusive with --cancel.
• --cancel (optional) — aborts an in-flight close request, refunding the transient account’s rent and leaving the mailbox exactly as it was. Mutually exclusive with --finalize.
• --keypair <path> (optional) — the mailbox owner’s keypair. Defaults to the keypair in your Solana CLI config when omitted.
• --skip-preflight (optional) — submits the transaction without a local simulation pass first.

With neither --finalize nor --cancel given, the command opens a new timelock: it stamps the request with the current chain time and creates a small transient PDA that tracks it. The mailbox stays open — mail keeps arriving, and settlement keeps working — until the request is finalized; the presence of that account is what marks the mailbox as closing.

The timelock duration

The wait between a close request and the earliest it can be finalized is a fixed 7 days. There is no flag to shorten it. It is a separate setting from the domain deactivation timelock, even though the two currently hold the same value.

Why a mailbox close waits at all: an instant rent refund made discarding a burned sending identity free, so a spammer could cycle mailboxes at no cost. The delay parks that capital for a week per identity and gives operators a window to notice. It costs an honest owner time on a rare action, not money — the rent still comes back in full. See Economics.

The one-step close is disabled

The original single-instruction CloseMailbox (discriminant 16) is refused on-chain with error 94, InstantCloseDisabled. The discriminant still decodes, so indexers replaying history resolve old transactions, but no current client can emit it and the CLI has no spelling for it. Use the request/finalize pair instead.

mailbox key close is unaffected

Closing the delegated encryption key account stays instant and still refunds its rent on the spot. That is deliberate, not an oversight: mailbox key close is the revocation path for a compromised delegated key, and a seven-day window there would leave MX servers sealing new mail to a key the owner already knows is compromised — the timelock would protect the attacker.

Examples

Request a close, starting the 7-day clock:

sithbit mailbox close --keypair <path to wallet keypair>

Change your mind and keep the mailbox:

sithbit mailbox close --cancel --keypair <path to wallet keypair>

Finalize once at least 7 days have passed, reclaiming both rents:

sithbit mailbox close --finalize --keypair <path to wallet keypair>

Errors

• MailboxCloseAlreadyPending (error 91) — a close is already in flight for this mailbox. Cancel it before requesting another.
• NoPendingMailboxClose (error 92) — --finalize or --cancel was run with nothing pending.
• MailboxCloseTimelockNotElapsed (error 93) — --finalize was run before the 7 days elapsed.
• InstantCloseDisabled (error 94) — the retired one-step CloseMailbox instruction was submitted.
• --finalize and --cancel cannot be combined.

Related commands

• Create a mailbox — create the mailbox in the first place.
• Update a mailbox — change postage, domain, or the no-IPFS flag instead of closing.
• Mailbox keys — including mailbox key close, which stays instant.

Note: a closed mailbox’s still-open message accounts persist and settle individually via mail delete, and recreating the mailbox restarts its message-id counter at zero. See Closing accounts for the full picture across every account class.

Looking up a frombox

See Fromboxes for what a frombox is and how pricing works. This page covers the sithbit frombox get command.

sithbit frombox get <from> [to_address]

frombox get is a read-only query: it derives the frombox PDA for the (from, to) pair, reads the account, and prints its stamp price and balance. It signs nothing, spends nothing, and needs no CLI feature flag — anyone can inspect any frombox.

Arguments

• <from> (required) — the sender’s “from” address, exactly as it keys the frombox: a wallet address, an alias@domain / wallet@domain email address, or a path to a .json keypair file (its public key is used). The value is taken literally as the frombox’s from-key, so a bare local part and its fully-qualified email address are different fromboxes — match whatever was used at create time.
• [to_address] (optional) — the recipient whose mailbox charges the postage. Accepts a wallet address, an alias/email address, or a .json keypair path, and (unlike <from>) is resolved to a wallet pubkey, so an alias is looked up on-chain. Defaults to your own configured wallet — the recipient’s own point of view.

What it prints

For an existing frombox the report is two lines: the derived frombox account address, its per-stamp postage price in lamports, the number of stamps currently available, and the account’s total lamport balance (rent plus the residual prepaid stamp value — what closing the frombox would refund to the recipient, or what frombox reclaim would return to a wallet-address sender, less the rent).

If no frombox exists for the pair, the command reports that the account does not exist and exits successfully — that is the normal state for an unknown sender, who simply pays the recipient’s mailbox default postage instead.

Examples

Check the frombox a recipient (you) has set up for jane_doe@sithbit.com:

sithbit frombox get jane_doe@sithbit.com

Inspect the frombox from jane_doe@sithbit.com to a specific recipient alias, rather than your own wallet:

sithbit frombox get jane_doe@sithbit.com bob@sithbit.com

Related commands

• Create a frombox — created on the sender’s first stamp purchase.
• Add stamps — top up the prepaid balance.
• Update postage — set the per-stamp price (owner only).
• Reclaim unspent stamps — the sender takes back postage it prepaid and never spent.

See Closing accounts for how to close a frombox and reclaim its rent and remaining stamp value.

Update a frombox

See Fromboxes for why postage pricing matters. This page covers the sithbit frombox update command.

sithbit frombox update <from> [required_postage] \
  [--keypair <keypair>] \
  [--skip-preflight]

Updating a frombox sets its per-stamp price — the required_postage, in lamports, that one email from <from> to you costs. Since every send burns exactly one stamp, this single number is the price of a message from that sender.

Unlike buying stamps, which anyone may run, only the recipient can update the price. The command signs with the recipient (“to”) keypair, and the program checks that signer against the mailbox owner. That same signer requirement is what lets you price a sender before their frombox even exists — see Setting a price before the frombox exists.

Arguments and flags

• <from> — the sender’s “from” address (alias, wallet address, or keypair path). Hashed client-side; only the hash reaches the chain.
• [required_postage] — the new per-stamp price in lamports. Optional; defaults to 1 SOL (1000000000 lamports) when omitted.
• --keypair <keypair> (short -k) — the recipient’s keypair; defaults to the CLI’s configured key. This key must be the mailbox owner.
• --skip-preflight (short -s) — skip the RPC pre-flight simulation.

There is no --stamps flag here — updating only changes the price, never the stamp balance. Prices are per-stamp and take effect on the next stamp purchase; stamps already bought keep the value they were funded at.

Examples

Lower a trusted sender’s price to 0.1 SOL (100000000 lamports):

sithbit frombox update jane_doe@sithbit.com 100000000

Update frombox address 7XkQ…Qp9 for <From:jane_doe@sithbit.com To:9aBc…prj> ...
Required postage set to 100000000 lamports
see https://explorer.solana.com/tx/…?cluster=devnet

Reset a sender back to the 1 SOL default by omitting the amount:

sithbit frombox update jane_doe@sithbit.com

You can also raise the price above the mailbox’s own default — there is no CLI-side maximum.

Setting a price before the frombox exists

You do not have to wait for a frombox to exist before pricing it. When you run frombox update against a (sender, you) pair that has no frombox yet, the CLI opens one in the same transaction: it checks the chain for the frombox PDA and, finding it absent, submits [CreateFrombox { stamps: 0 }, UpdateFrombox { … }] — a genuine two-instruction transaction that creates the empty frombox and then writes your price onto it. When the frombox already exists it behaves as before: a lone UpdateFrombox.

The frombox starts at your price with zero stamps, so the sender still can’t reach you until it holds at least one, funded by either side via Add stamps. See the anti-spam lever for why this stampless create is allowed only for the recipient.

On-chain effect

The UpdateFrombox instruction re-derives the frombox PDA from the recipient address and the from-hash, verifies the frombox and the recipient’s mailbox both exist and are program-owned, requires the recipient to sign, and overwrites the frombox’s required_postage field. No lamports move — this is purely a price change; funding the frombox is Add stamps’ job.

When the frombox does not exist yet, the CLI prepends a CreateFrombox { stamps: 0 } (the owner exception above), so the same transaction allocates the account and funds only its rent-exemption reserve — no postage, since it carries zero stamps — before the UpdateFrombox sets the price.

Add stamps

See Fromboxes for what stamps are and why prepayment is required. This page covers the sithbit frombox stamp command.

sithbit frombox stamp <from> [to_address] \
  [--keypair <keypair>] \
  [--stamps <count>] \
  [--max-price <lamports> | --no-max-price] \
  [--skip-preflight]

Adding stamps prepays postage into a frombox — creating the frombox on the spot if it does not exist yet (see Creating the frombox on first purchase). This command buys <count> stamps at the frombox’s current per-stamp price and adds them to the balance.

Anyone can add stamps — a sender buying their own postage to reach a recipient, or the recipient prefunding a sender so their mail stays free. The signer is the payer.

Arguments and flags

• <from> — the sender’s “from” address (alias, wallet address, or keypair path). Hashed client-side; only the hash reaches the chain.
• [to_address] — the recipient whose frombox is being funded. Defaults to your own address.
• --keypair <keypair> (short -k) — the payer’s keypair; defaults to the CLI’s configured key.
• --stamps <count> (short -p) — how many stamps to buy. Defaults to 1.
• --max-price <lamports> — the highest per-stamp price this purchase will accept. Defaults to the price quoted from the chain, so you never pay more than you were shown; pass a higher figure to pre-authorize a rise you are willing to absorb. See The price can move under you.
• --no-max-price — buy at whatever the price turns out to be, with no guard. Mutually exclusive with --max-price.
• --skip-preflight (short -s) — skip the RPC pre-flight simulation.

The frombox does not need to exist first: if it is absent this command creates it (see Creating the frombox on first purchase). Adding stamps never changes the price; run update for that.

Example

Top up a sender’s frombox by 10 stamps:

sithbit frombox stamp jane_doe@sithbit.com --stamps 10

Purchasing 10 stamps for frombox 7XkQ…Qp9 <From:jane_doe@sithbit.com To:9aBc…prj>
Protocol fee: waived (owner purchase)
Purchased 10 stamps
see https://explorer.solana.com/tx/…?cluster=devnet

When the recipient pays for their own mailbox’s frombox the per-stamp protocol fee is waived, as shown. A third party funding a frombox to someone else instead sees the fee it will pay, e.g. Protocol fee: 1000000 lamports (100000 per stamp).

Creating the frombox on first purchase

When the target frombox does not exist yet, frombox stamp opens it in the same transaction instead of failing. The CLI checks the chain for the frombox PDA; if it is absent it submits a single CreateFrombox carrying your requested stamp count rather than an AddStamps against a missing account. That one instruction allocates the account and credits the stamps at once — the fee and postage are identical to buying the same stamps on an existing frombox, so a first purchase and a top-up cost the same (no separate create step, and no double charge).

The trustless webmail compose rides this same create-or-top-up decision for its inline Prepay & send: when a send finds no frombox, the card quotes the purchase (postage + surcharge + the live protocol fee) and re-sends the held draft once the stamps confirm. The webmail Balances pane rides the identical decision for its own stamp purchases, and now supports both signing flavors as well — the in-page wallet signs directly, an external Phantom/Ledger wallet approves the same purchase built unsigned.

A newly created frombox’s per-stamp price is set to the recipient mailbox’s current default postage — scaled by the payer’s on-chain sender reputation when the create is a third party’s (see Reputation-scaled first contact below). Buying stamps never sets a custom price; to give a trusted sender a cheaper rate the recipient runs sithbit frombox update afterwards, or sets the price up front before any stamps are bought — see Setting a price before the frombox exists.

Reputation-scaled first contact

A third party’s first purchase toward a recipient — the create-if-absent path above, buying at the mailbox’s default postage — is priced by reputation-scaled first-contact pricing: the default steps down with the payer wallet’s cumulative distinct-recipient postage spend, never below the tuned floor (10% of the default by default), and never below one lamport for a nonzero price. The same purchase also records its escrowed postage onto the payer’s sender-reputation account, so every first contact a sender pays for makes the next one cheaper. Only the default is scaled: a price the recipient set with frombox update applies verbatim, and an owner purchase (the recipient prefunding a sender) pays the raw default and records nothing.

The CLI builds this automatically. A third-party create carries the reputation tail by default — a 9-account CreateFrombox form: the legacy six accounts, the operator pair (the recipient’s mailbox PDA fills both slots when no operator split resolves), and the payer’s sender-reputation PDA, lazily created rent-exempt on first use. When the payer holds a verified-sender attestation for the from address’s domain, the CLI detects it on-chain and appends it as a tenth account, which prices the first contact at the floor immediately — attested organizations skip the spend ladder. (A wallet-literal or domainless from address has no domain to attest, so the lookup is skipped.) Owner purchases and top-ups of an existing frombox stay on their legacy account lists: reputation is earned and priced at first contact, never on a top-up.

The tail never carries a guessed account: a present-but-invalid attestation fails the transaction (error 19 for another wallet’s attestation, error 17 for a bad derivation) rather than silently repricing, so only a confirmed on-chain record is ever included.

Looking up a wallet’s reputation

sithbit postoffice reputation <WALLET>

Read-only, ships in every build. It prints the wallet’s recorded cumulative postage spend and the effective first-contact rate that spend earns, in basis points of a recipient’s default postage — computed through the same on-chain rule the program applies, tuned floor included. A wallet with no reputation account reads as zero spend at the full 10,000 bps (the common negative answer, not an error):

sithbit postoffice reputation mAiLiLdgjgGdWoCZkpW3cj7JLAC56qb4NErFyQFWNJg

MX operators can query the same figures over gRPC — the gateway’s GetSenderReputation RPC answers with identical semantics.

Tuning the floor

The delegate tunes the discount’s floor with:

sithbit postmaster fee reputation-floor <BPS> \
  [--keypair <delegate keypair>] \
  [--skip-preflight]

The value is basis points of a mailbox’s default postage, hard-capped on-chain at 10,000 bps (100% — a floor that high disables the discount entirely); an over-cap value refuses with custom error 102 (ReputationFloorAboveCap). Zero resets to the protocol default of 1,000 bps (10%): like the other tunable rates, a zero stores the “unset” sentinel, and a postoffice account that predates the field reads back the default (the setter grows the legacy account in place). See the tunable-constants table.

The prepayment rule

A third party’s first purchase toward someone else’s frombox must buy at least one stamp: running frombox stamp --stamps 0 as anyone other than the recipient fails, since the on-chain CreateFrombox guard refuses a zero-stamp create from a non-owner payer. The only way to open a stampless frombox is for the recipient (the mailbox owner) to do it while setting the price — see Setting a price before the frombox exists.

The price can move under you

The recipient owns the per-stamp price and can change it at any moment — including between the instant this command quotes you a price and the instant your transaction is confirmed. A purchase carrying no ceiling simply pays whatever price it finds on arrival.

So the command sets one for you. By default it pins the ceiling to the price it just quoted, and prints the figure alongside the fee preview:

Protocol fee: 30000 lamports (greater of 10000 flat per stamp and 250 bps of postage)
Slippage guard: max 1000000 lamports per stamp (quote-pinned)

If the price has risen past that ceiling by the time the transaction lands, the program refuses the purchase with custom error 107 (PriceExceedsMax) and your postage stays in your wallet. Nothing is partially spent — buy again at the new price if you still want the stamps.

Two ways to change that posture:

• --max-price <lamports> sets the ceiling yourself. Use it to pre-authorize a rise (“I’ll pay up to 2 SOL a stamp, whatever it says today”) so a modest increase does not bounce your purchase.
• --no-max-price removes the guard entirely, restoring the older pay-whatever behavior.

The ceiling is checked against the per-stamp price, not the total, and it applies to both purchase paths — a top-up compares it against the frombox’s stored required_postage, while a first purchase compares it against the effective first-contact price after reputation scaling. Because reputation scaling only ever prices at or below the mailbox’s default postage, the quoted default is a safe ceiling for a first purchase.

The GUI clients take the same posture, so the CLI is no longer the only guarded buyer: the webmail Balances pane, the compose card’s inline prepay and the self-service funding page all pin every purchase to the price they quoted. They expose no equivalent of --max-price or --no-max-price: raising or removing the ceiling stays a power-user choice, and the panes re-read the quote at buy time rather than trusting whatever is on screen.

On-chain effect

The AddStamps instruction transfers postage from the payer into the frombox account and increments its stamp count. For each stamp bought the payer deposits:

• the per-stamp price (required_postage); plus
• a settlement surcharge (10000 lamports) that reimburses the sender’s later SendMail and DeleteMail signatures.

On top of that it collects the flat per-stamp protocol fee to the postoffice, waived when the payer is the recipient wallet — see Economics.

On a first purchase the command runs CreateFrombox instead: it does everything AddStamps does (crediting the stamps and charging the same per-stamp fee) and additionally allocates the account and funds its rent-exemption reserve, storing the mailbox’s default_postage — scaled by the payer’s sender reputation on a third-party create — as the new frombox’s required_postage, and recording the escrowed postage onto the payer’s sender-reputation account.

Stamps are prepaid postage, not a fee charged per send. When a message is delivered, the frombox’s stored balance is split evenly across its remaining stamps: one stamp’s share is moved into the message account to fund the delivery, and the stamp count drops by one. That escrowed postage is settled when the message is deleted (a share to the recipient’s MX operator, the remainder as the recipient’s postage income) — so the price you set is really the value backing each stamp, refundable as a deposit rather than spent as a toll. See the stamp lifecycle for the full settlement path.

If you prepaid more postage than you ended up needing, you can take the unspent remainder back — see Reclaiming unspent stamps. When a frombox is no longer needed at all, see Closing accounts, where the recipient closes it and reclaims its rent and remaining stamp value.

Reclaiming unspent stamps

See Fromboxes for what stamps are and why prepayment is required. This page covers the sithbit frombox reclaim command.

sithbit frombox reclaim <to_address> \
  [--keypair <keypair>] \
  [--skip-preflight]

reclaim takes back the postage you prepaid into someone else’s frombox and never spent. It is the sender’s counterpart to frombox close, which is the recipient’s sweep of the same account: close hands the whole balance to the recipient, reclaim returns only the unspent postage to the sender.

The frombox itself survives. Only the balance above the account’s rent-exemption reserve moves, so the account stays open at the price the recipient set — reclaiming is not a way to reset your standing with them, just a way to get idle postage out of escrow.

This is also reachable from a GUI: the webmail Balances pane offers a Reclaim unspent button once a quote shows a frombox of yours holding stamps. The pane applies the wallet-address rule below by hiding the button rather than surfacing a failure — it appears only when you are sending as your own wallet.

Only works for a wallet-address sender

A frombox is keyed on the blake3 hash of the sender’s “from” address, and this command works by reproducing that derivation from your signature: the program hashes your wallet’s address bytes and checks that the result names the frombox you passed. Reproducing the derivation is therefore the whole authorization — no separate ownership field exists, and no stranger can reach your frombox.

The flip side is that it only works when the “from” is a wallet address. A frombox keyed on an email string (alice@example.com) hashes text that no wallet key can reproduce, so those stay recipient-managed: the recipient’s frombox close remains the only way their balance comes back out. If you expect to reclaim, buy postage against your wallet address.

Arguments

• <to_address> — the recipient whose frombox holds your postage. Accepts a wallet address or an alias, which is resolved to its wallet.
• --keypair <keypair> (short -k) — the sender’s keypair. This is the wallet the frombox is keyed on and the wallet the postage is returned to; defaults to the CLI’s configured key.
• --skip-preflight (short -s) — skip the RPC pre-flight simulation.

Examples

Reclaim your unspent postage from the frombox a recipient holds for you:

sithbit frombox reclaim 7cVfgArCheMR6Cs29HXTFrpMg2XwYFhrCtdz3EgKPfHM

Reclaim as a specific wallet, naming the recipient by alias:

sithbit frombox reclaim jane_doe --keypair ~/.config/solana/id.json

Confirm the result — the stamp count reads zero and the balance is down to the account’s rent:

sithbit frombox get <your-wallet-address> jane_doe

On-chain effect

The ReclaimFromboxStamps instruction zeroes the frombox’s stamp count and moves everything above the rent-exemption reserve back to the signer. It carries no instruction data at all — the accounts and your signature say everything the program needs.

Reclaiming is not the only way that balance can come back out. The recipient’s frombox close still sweeps whatever residual a sender leaves behind, so this is the sender’s proactive recovery path rather than an exclusive claim on the escrow — see frombox custody in the threat model for why custody is arranged that way.

Related commands

• Add stamps — the purchase this reverses, including the slippage guard that keeps a purchase from overpaying in the first place.
• Looking up a frombox — check the stamp count and balance before and after.
• Closing accounts — the recipient’s side: closing the frombox and reclaiming its rent along with any residual.

Create an alias

See Aliases for what an alias is and the automatic self-alias spoof guard that mailbox create already gives you. This page covers the sithbit alias create command.

Creating an alias

sithbit alias create <alias> [--keypair <keypair>] [--skip-preflight]

For example:

sithbit alias create john_doe

This registers john_doe as an alias pointing at the address of the signing keypair (defaulting to your configured default keypair — see CLI Quickstart).

Registration fee

Registering a name pays a claim fee to the postoffice on top of the account rent, and the fee is length-tiered: names of 5 or more characters pay the flat fee (0.01 SOL default), while 1–4 character names carry a scarcity premium — by default 10 SOL (1 char), 1 SOL (2), 0.1 SOL (3), and 0.05 SOL (4). See Economics for the schedule, its caps, and how the postmaster tunes it.

Before submitting, the command prints what the run will pay — one line per premium short name plus a total, so a premium price is never charged silently:

Premium short name 'ab' (2 chars): 1000000000 lamports
Total registration fees: 1010000000 lamports

When the signing wallet is the postmaster delegate the preview prints Registration fee: waived (delegate reservation) instead — reservations are fee-free at every length (see Reserve aliases in bulk).

Note: sithbit mailbox create already registers your wallet’s own address as a self-alias automatically — a namespace reservation, so nobody else can hold a name that reads as your wallet. Resolution is literal-first, so that claim is not what routes your mail (see Aliases). Use alias create for additional friendly names beyond that automatic one.

To register many names at once (e.g. the postoffice delegate reserving names for resale), see Reserve aliases in bulk.

Allowed characters

Alias names are validated at registration — both client-side and by the on-chain program, so the rules hold even for hand-rolled transactions:

• Lowercase ASCII letters, digits, and the separators ., _, - (uppercase input is accepted and lowercased before storage and PDA derivation).
• Must start and end with a letter or digit.
• No consecutive dots.
• At most 64 bytes.

Non-ASCII names are refused outright: this shuts out homoglyph (e.g. Cyrillic а), zero-width, and Unicode-normalization look-alike spoofing.

Reserve aliases in bulk

See Aliases for what an alias is and the automatic self-alias namespace reservation that mailbox create already gives you. This page covers the sithbit alias create command’s bulk form.

sithbit alias create [<alias>...] [--keypair <keypair>] [--skip-preflight]

Creates many aliases in one invocation, packing as many CreateAlias instructions into each transaction as fit Solana’s transaction-size budget (about a dozen typical names per transaction; longer lists are split into successive transactions automatically):

sithbit alias create ceo sales support billing --keypair my_wallet.json

When no aliases are given as arguments, the list is read from stdin — whitespace-separated, so one name per line works — which suits piping in a prepared file:

sithbit alias create --keypair my_wallet.json < aliases.txt

Every created alias points at the signing wallet address, exactly as alias create would — same validation, same lowercasing, same per-alias fee (see Economics) — and duplicates in the list are collapsed before submission. The delegate waiver covers the length-tiered premium fees too: reserving a 1–4 character name costs the operator only rent, which is precisely how premium short names are meant to reach the market — reserved fee-free, then sold on the marketplace or handed off at a chosen price.

Bulk-created names carry no special state: like any alias, they can later be handed to another wallet with alias transfer init — a zero-fee offer the buyer accepts, fee-waived because the delegate is the holder — or closed at any time to reclaim their rent.

Get an alias

See Aliases for what an alias is and how it resolves to a wallet address. This page covers the sithbit alias get command.

sithbit alias get <alias>

Resolves an alias to the wallet address it currently points at:

sithbit alias get john_doe

Note: lookups are case-insensitive by construction — the alias is lowercased before it’s hashed into the account’s address, the same as at creation, so John_Doe and john_doe resolve identically.

Resolution is domain-blind: any @domain suffix is parsed off and ignored, so john_doe, john_doe@sithbit.com, and john_doe@anything.example all resolve to the one global john_doe. No domain authority can claim a local part it does not hold — see Aliases.

See Closing accounts for how to close an alias and reclaim its rent.

Discovering a recipient’s encryption key: the cert keyserver

Before anyone can seal mail to a SithBit address they need the recipient’s published X25519 key. The account API exposes a public lookup for exactly that, with the recipient identity in the ?email= query parameter:

GET /v1/chain/cert?email=alice@acme.com

It is public and unauthenticated — deliberately, in the spirit of PGP keyservers (HKP) and Web Key Directory (WKD). Everything it returns is already readable on-chain by anyone, so gating it behind a login would add friction without adding privacy. Give it any recipient identity — a wallet address or an alias, with or without a domain suffix — and it resolves that identity to a wallet (composing the same domain-blind resolution as alias get above), then returns that wallet’s published encryption key.

Two response cases matter:

• Empty key, 200 OK. The recipient exists but has published no delegated key. This is not an error — a sender seals straight to the wallet address itself (see Mailbox Keys and sealed-box encryption).
• Unknown recipient, 404. No wallet resolves for that identity at all — there is nobody to seal to.

Because it is a convenient public surface over on-chain data, it carries a threat-model note; see the discovery keyserver is a public enumeration surface.

Transfer an alias

See Aliases for what an alias is and why a transfer is always a two-party consent ceremony rather than a unilateral push. This page covers the sithbit alias transfer command tree.

sithbit alias transfer init <alias> <recipient> \
  [--fee <lamports>] [--expires-in <seconds>] \
  [--keypair <keypair>] \
  [--skip-preflight]

Offers to move an existing alias to a new wallet address. Every transfer is a two-party ceremony: the alias’s current holder signs to stage the offer, and the alias changes hands only when the named recipient signs to accept it. Both consents are structural — an alias can never be taken from its owner without their key, and it can never be planted on a wallet that didn’t ask for it.

--fee is the price, in lamports, the recipient pays the holder on acceptance. It defaults to 0 — a free hand-off:

sithbit alias transfer init john_doe maiLtdkxym8CCmo9TwDuXywqd9DXaK3tB6toKFVeBFR

The alias keeps resolving to the current holder until the recipient runs alias transfer accept. A free hand-off pays the flat alias-transfer fee to the postoffice at accept — waived when the offer’s holder is the standing delegate, so operator reservation hand-offs stay fee-free — while a priced offer pays the 90/10 split instead (see Economics).

See Closing accounts for how to close an alias instead of transferring it.

The consent guarantee. Before v0.7.0 the TransferAlias instruction repointed an alias at any address with only the holder’s signature — a name could be attached to a wallet unilaterally. That instruction now refuses with custom error 85 (UnilateralTransferDisabled); its discriminant remains decodable so pre-cutover history replays cleanly. See the change history.

Selling an alias: escrowed transfer for a fee

With a positive --fee, the same command stages the offer as a sale: the alias changes hands only when the named recipient accepts the offer and pays the fee. Until then the alias keeps resolving to the current holder, exactly as before.

sithbit alias transfer init john_doe <RECIPIENT_PUBKEY> --fee 50000000

The offer names one specific recipient — only that wallet can accept it — and each alias can carry at most one outstanding offer (the offer lives in a dedicated escrow account derived from the alias name, so a second simultaneous offer is structurally impossible). The holder fronts the escrow account’s rent when staging the offer and gets it back when the offer resolves, whichever way it resolves.

The binding window

For its first 5 minutes an offer is binding on the holder: it can be neither cancelled nor replaced. This protects a recipient who sees the offer and pays promptly from having it retracted out from under them mid-purchase.

Replacing an offer

To change the fee, the recipient, or the expiry, just issue a new alias transfer init for the same alias — a new offer replaces the standing one in place (no cancel-first needed, and no extra rent). The replacement re-arms the 5-minute binding window.

Expiry

An offer expires 30 days after it is staged, unless you pass a different lifetime in seconds:

sithbit alias transfer init john_doe <RECIPIENT_PUBKEY> --fee 50000000 --expires-in 86400

Enforcement is lazy — nothing sweeps expired offers. An accept at or before the expiry instant succeeds; an accept after it is refused. The escrow account of an expired offer sits until the holder cancels it (see below) or stages a replacement.

Accepting an offer

sithbit alias transfer accept <alias> \
  [--payer-keypair <keypair>] \
  [--keypair <keypair>] \
  [--skip-preflight]

The offer’s named recipient signs — the signature is the consent, so an alias can never be planted on a wallet that didn’t ask for it. In one atomic instruction the fee leg settles, the alias repoints at the recipient, and the escrow closes with its rent refunded to the previous holder. The fee leg depends on the offer’s price:

• Priced offer — the fee leaves the paying wallet and splits between the current holder and the postoffice (90/10 — see Economics for the exact money flow). No flat fee rides on top.
• Free hand-off (fee 0) — the paying wallet pays the flat alias-transfer fee (default 0.001 SOL, postmaster-tunable) to the postoffice, waived when the offer’s holder is the standing delegate. The CLI prints the fee (or the waiver) before signing.

sithbit alias transfer accept john_doe --keypair recipient.json

By default the recipient’s own wallet pays. A sponsor may pay instead with --payer-keypair — the sponsor funds the fee and the transaction fee and co-signs alongside the recipient. (Simply funding the recipient’s wallet beforehand works too.)

Cancelling an offer

sithbit alias transfer cancel <alias> [--keypair <keypair>] [--skip-preflight]

The holder cancels an outstanding offer (once its binding window has elapsed), closing the escrow and reclaiming its rent:

sithbit alias transfer cancel john_doe

This is also how you reclaim the escrow rent of an expired offer — an expired offer can no longer be accepted, but its account stays open until the holder cancels it.

While an offer is pending

• The alias resolves to the current holder until the moment the offer is accepted; mail keeps working unchanged.
• sithbit alias close refuses while a transfer offer is outstanding — cancel the offer first, then close (otherwise the escrow’s rent would be stranded).

List an alias for sale

See Aliases for what an alias is and how a listing differs from an escrowed transfer. This page covers the sithbit alias sell/buy command tree.

sithbit alias sell <alias> --price <lamports> \
  [--expires-in <seconds>] \
  [--keypair <keypair>] \
  [--skip-preflight]

Puts an alias up for sale on the open marketplace: a fixed-price listing that any buyer may take, first come, first served. Where an escrowed transfer offer names one specific recipient who alone can accept, a listing names nobody — whoever signs alias buy and pays the price becomes the alias’s holder.

For an ascending-bid sale instead of a fixed price — bidders escrow lamports on-chain and the high bidder wins at a deadline — see Auction an alias. A listing is one mode or the other, chosen when it is staged.

sithbit alias sell john_doe --price 50000000
Listed alias 'john_doe' for sale at 50000000 lamports
https://explorer.solana.com/tx/…

The alias’s current holder signs. The price is in lamports and must be positive — for a free hand-off, stage a zero-fee alias transfer init offer. The listing lives in a dedicated account derived from the alias name’s blake3 hash, so each alias can carry at most one listing at a time (a second simultaneous listing is structurally impossible). The holder fronts that account’s rent when staging the listing and gets it back when the listing resolves — bought, cancelled, or reclaimed after expiry.

Until the moment a buyer pays, the alias keeps resolving to the current holder, exactly as before; mail keeps working unchanged.

The binding window

For its first 5 minutes a listing is binding on the holder: it can be neither cancelled nor replaced. This protects a buyer who sees the listing and pays promptly from having it retracted out from under them mid-purchase. Buying itself is never window-gated — a listing is buyable the moment it is staged.

Replacing a listing

To change the price or the expiry, just issue a new alias sell for the same alias — once the binding window has elapsed, the new listing replaces the standing one in place (no cancel-first needed, and no extra rent). The replacement re-arms the 5-minute binding window.

Expiry

A listing lapses 30 days after it is staged, unless you pass a different lifetime in seconds:

sithbit alias sell john_doe --price 50000000 --expires-in 86400

Enforcement is lazy — nothing sweeps expired listings. A buy at or before the expiry instant succeeds; a buy after it is refused. The listing account of an expired listing sits until the holder cancels it or stages a replacement.

Buying a listed alias

sithbit alias buy <alias> \
  [--payer-keypair <keypair>] \
  [--keypair <keypair>] \
  [--skip-preflight]

Any wallet may buy — the buyer signs, and paying the price doubles as consent, so an alias can never be planted on a wallet that didn’t ask for it. In one atomic instruction the price leaves the paying wallet, splits between the current holder and the postoffice (90/10 — see Economics for the exact money flow), the alias repoints at the buyer, and the listing closes with its rent refunded to the previous holder.

sithbit alias buy john_doe --keypair buyer.json
Bought alias 'john_doe' for maiLtdkxym8CCmo9TwDuXywqd9DXaK3tB6toKFVeBFR
https://explorer.solana.com/tx/…

By default the buyer’s own wallet pays the price. A sponsor may pay instead with --payer-keypair — the sponsor funds the price and the transaction fee (two signatures) and co-signs alongside the buyer. (Simply funding the buyer’s wallet beforehand works too.)

A bought alias shows up in the gRPC gateway’s alias index as an ordinary transfer event — the index records the change of holder, not how it was paid for.

Cancelling a listing

sithbit alias sell <alias> --cancel [--keypair <keypair>] [--skip-preflight]

The holder cancels an open listing (once its binding window has elapsed), closing the listing account and reclaiming its rent:

sithbit alias sell john_doe --cancel
Cancelled the listing on alias 'john_doe' and reclaimed its rent
https://explorer.solana.com/tx/…

This is also how you reclaim the rent of an expired listing — an expired listing can no longer be bought, but its account stays open until the holder cancels it.

One disposal path at a time

An alias cannot carry both a private transfer offer and an open listing — the two would race to sell the same name. The refusal works in both directions: alias sell is refused while a transfer offer is outstanding, and alias transfer init (any fee, including a zero-fee hand-off) is refused while a listing is open. Resolve one path (cancel, accept, or buy) before starting the other.

The guard matters because repointing the alias under a live listing would leave a stale holder recorded as the listing’s seller, able to collect the sale price the moment a buyer paid. Cancel the listing first, then transfer. The refusal is deliberate rather than an auto-cancel: a silent retraction could land inside the listing’s binding window, doing exactly what the window exists to prevent. (Buying re-checks the seller for the same reason: a stale listing that predates a change of holder can never sell the new holder’s alias at the old holder’s price.)

Relatedly, sithbit alias close refuses while a listing is open — cancel the listing first, then close (otherwise the listing account’s rent would be stranded). See Appendix: Closing accounts.

Aliases have no deactivation concept, so there is no alias twin of the domain marketplace’s deactivation interplay — an open alias listing only ever resolves by buy, cancel, or expiry.

Errors

Related

• Auction an alias — the ascending-bid alternative to a fixed price.
• Transfer an alias — the escrowed hand-off or sale to one named recipient (free when the fee is 0).
• Economics — the exact money flow: who pays, who collects, and when.
• List a domain for sale — the same marketplace for domains.
• Closing accounts — reclaiming rent, and why a listed alias can’t close.

Auction an alias

See Aliases for what an alias is and how an auction differs from a fixed-price listing. This page covers the sithbit alias sell --auction/bid/settle-auction command tree.

sithbit alias sell <alias> --auction --reserve <lamports> \
  [--ends-in <seconds> | --ends-at <unix-timestamp>] \
  [--antisnipe <seconds>] \
  [--keypair <keypair>] \
  [--skip-preflight]

An auction is the second way to sell an alias on the open marketplace, alongside the fixed-price alias sell --price listing. Where a fixed-price listing sets one number any buyer may take first come, first served, an auction opens an ascending-bid contest: bidders escrow lamports on-chain, each bid must top the last by a minimum increment, and after the clock runs out anyone settles the auction and the alias repoints at the high bidder.

The two modes are mutually exclusive — a listing is either fixed-price or an auction, chosen when it is staged. --auction requires --reserve (the floor the first bid must meet) and rejects --price; a plain --price listing rejects the auction flags.

sithbit alias sell john_doe --auction --reserve 50000000
Opened an auction on alias 'john_doe' (reserve 50000000 lamports, ends in 7d)
https://explorer.solana.com/tx/…

The alias’s current holder signs to open the auction. As with a fixed-price listing, the auction lives in a dedicated account derived from the alias name’s blake3 hash, so each alias carries at most one listing of either kind at a time. The holder fronts that account’s rent when opening the auction and gets it back at settlement (or on cancel — see Strict commitment for when a cancel is still allowed).

Until settlement the alias keeps resolving to the current holder, exactly as before; mail keeps working unchanged while bids come in.

Timing: when it ends, and anti-snipe

The end time is set at open and clamped on-chain:

• --ends-in <seconds> — a duration from now, clamped to [now + 1 hour, now + 7 days] (the minimum and maximum auction duration). A value below the floor is raised to one hour; above the ceiling it is capped at seven days.
• --ends-at <unix-timestamp> — an absolute end instant, clamped to the same one-hour-to-seven-day band around now.

The default duration

Omitting both defaults the auction to run 7 days from the moment it is opened. The default and the ceiling above are separate on-chain settings that hold the same length today: an auction naming no end instant gets the default, not the maximum.

Anti-snipe extension

To blunt last-second sniping, a bid that lands inside the final anti-snipe window pushes the end time out, giving other bidders a chance to respond. The window is set with --antisnipe <seconds>, clamped to [0, 24 hours] and defaulting to 24 hours; passing 0 disables the extension entirely (a hard deadline).

Concretely: a bid arriving after expires_at - window moves expires_at out to min(now + window, created_at + 7 days). Two properties fall out of that formula:

• Each qualifying late bid re-arms roughly a full window of remaining time, so an auction only ever ends once a full anti-snipe window passes with no further bids.
• The extension can never carry the auction past seven days from when it was opened — the created_at + 7d cap is a hard backstop, so no amount of sniping keeps an auction alive indefinitely.

Bidding

sithbit alias bid <alias> --amount <lamports> \
  [--payer-keypair <keypair>] \
  [--keypair <keypair>] \
  [--skip-preflight]

Any wallet may bid. The amount is in lamports and is escrowed on-chain in the auction account the moment the bid lands — the bidder is not merely promising to pay, the funds are held by the program until the bid is either outbid (refunded) or settled (won).

sithbit alias bid john_doe --amount 50000000 --keypair bidder.json
Bid 50000000 lamports on alias 'john_doe'
https://explorer.solana.com/tx/…

The minimum next bid

• The first bid must be at least the reserve (--reserve at open).

• Every later bid must clear the standing high bid by a minimum increment:

  minimum next bid = high_bid + max(5% of high_bid, 1_000_000 lamports)
  

The max(...) means a flat 1,000,000-lamport floor dominates while the high bid is small, and the 5% term takes over once the high bid exceeds 20,000,000 lamports (5% of 20,000,000 is exactly the flat floor). The increment exists so a bidder can’t inch past the leader one lamport at a time, and — together with the reserve and the escrow-rent cost below — it is the auction’s friction against spam bidding.

By default the bidder’s own wallet escrows the amount; a sponsor may fund it with --payer-keypair, co-signing alongside the bidder (or simply fund the bidder’s wallet beforehand).

Settlement

sithbit alias settle-auction <alias> \
  [--keypair <keypair>] \
  [--skip-preflight]

Once the end time has passed, anyone may crank settlement — the seller, the winner, or an unrelated third party. Settlement is fully deterministic: the alias repoints at the recorded high bidder, and the escrowed high bid splits 90% to the seller (the prior holder) and 10% to the postoffice (OPERATOR_SHARE_BPS = 1000 basis points), the same split as every other marketplace path — see Economics for the exact money flow.

sithbit alias settle-auction john_doe
Settled the auction on alias 'john_doe'; new holder maiLtdkxym8CCmo9TwDuXywqd9DXaK3tB6toKFVeBFR
https://explorer.solana.com/tx/…

An auction that reaches its end with no bids settles as a no-op: the alias stays with the holder and the listing closes with its rent returned, just like a cancelled fixed-price listing.

A settled auction shows up in the gRPC gateway’s alias index as an ordinary transfer event — the index records the change of holder, not how it was won.

Strict commitment: no take-backs

An auction with a live high bid is binding on the seller. Unlike a fixed-price listing — which the holder may cancel or re-price at will once its binding window elapses — an auction that has taken even one bid can be neither cancelled nor replaced. The seller has, in effect, committed to sell to the highest bidder at the deadline. Bidders likewise cannot cancel a bid: a bid is a firm, escrowed commitment that is only ever undone by being outbid.

A bidless auction is still the seller’s to cancel (alias sell --cancel, closing the auction and reclaiming its rent) or to let expire and settle as a no-op. It is only the arrival of the first bid that locks the auction in.

alias buy is rejected on an auction listing — buying is the fixed-price path only. An auction changes hands solely through bid-then-settle-auction.

The escrow-rent flow (read this before you bid)

This is the one genuinely surprising piece of the auction’s money flow, so it is worth spelling out.

The auction’s bid escrow — the on-chain account that holds the current high bid — must itself be rent-exempt, so it holds rent + high_bid. That rent is funded once, by the first bidder, on top of their bid amount.

When a bid is outbid, only the bid amount is refunded to the outbid bidder — the account rent stays behind in the escrow, carried forward under the new high bid. The rent is not re-funded by each successive bidder; it is paid once and then travels with the escrow.

At settlement, that rent is reclaimed by the winner — the final high bidder — not by whoever originally funded it. So:

• An early bidder who is later outbid is net out the escrow rent (plus their transaction fee): they get their full bid amount back, but the rent they fronted stays in the escrow and is ultimately recovered by someone else.
• The eventual winner recovers that rent at settlement, regardless of whether they were the one who first funded it.
• The listing account’s own rent always returns to the seller, on every resolution path — this is separate from the bid escrow’s rent.

The practical upshot: being the first bidder in an auction you don’t go on to win costs you a small, non-refundable amount (the escrow rent). That is deliberate — it is a further disincentive against throwaway spam bids, on top of the reserve and the minimum increment.

Errors

Related

• List an alias for sale — the fixed-price alternative, and the marketplace rules the two modes share (the one-listing-per-alias lock, the transfer/close interplay).
• Transfer an alias — the escrowed hand-off or sale to one named recipient (free when the fee is 0).
• Economics — the 90/10 split and where each lamport goes.
• Compute-unit consumption — the measured cost of opening an auction, bidding, and settling.
• Trust assumptions and threat model — escrow custody, the anti-snipe mitigation, and crankable settlement.

Looking up a domain

See Domains for what a domain is and what the active/inactive status means. This page covers the sithbit domain get command.

sithbit domain get <domain>

domain get is a read-only query — it derives the domain’s on-chain account, reads it, and prints its status. It signs nothing, spends nothing, and, unlike the admin subcommands below, needs no special CLI feature: any mailbox owner can check whether a domain exists and is active before pointing their mailbox at it.

Arguments

• <domain> (required) — either the domain name itself (e.g. sithbit.com, case-insensitive; domain names are stored lowercased) or the domain account’s on-chain address. A value that parses as a base58 pubkey is read as an account address directly; anything else is treated as a domain name and hashed into its PDA.

What it prints

For a registered domain the command prints one line: the domain name, its derived account address, the domain authority that controls it (the address that can transfer it), and whether it is currently active or inactive — see Active and inactive domains for what that status means.

If the domain has never been registered — or its account address does not exist — the command reports that the domain does not exist on Solana and exits successfully.

Examples

Look up a domain by name:

sithbit domain get sithbit.com

Look up the same domain by its on-chain account address instead:

sithbit domain get 7Np41oeYqPefeNQEHSv1UDhYrehxin3NStELsSKCT4K2

Note: domain create, domain transfer, and domain deactivate require the CLI’s domain feature (enabled by default) and always require the delegate’s signature — domain administration is not something an ordinary mailbox owner can do unilaterally. domain get, by contrast, is unauthenticated and always available.

Create a domain

See Domains for what a domain is and the authority/delegate/payer role model behind domain creation. This page covers the sithbit domain create command.

sithbit domain create <domain> \
  [--authority-keypair <path>] \
  [--keypair <delegate keypair>] \
  [--payer-keypair <path>] \
  [--skip-preflight]

Arguments

• <domain> (required) — the domain name to register, e.g. sithbit.com (case-insensitive; domain names are stored lowercased).
• --authority-keypair <path> — the key that becomes this domain’s authority. Defaults to your configured default keypair when omitted.
• --keypair <delegate keypair> — the delegate’s signing keypair. Required on every invocation: a signer that isn’t the postoffice’s standing delegate is refused with error 66, NotDelegate.
• --payer-keypair <path> — funds the new domain account’s rent. Defaults to the delegate keypair when not given separately.
• --skip-preflight (optional) — submits the transaction without a local simulation pass first.

Examples

Register a domain with a dedicated authority key, signed by the delegate:

sithbit domain create sithbit.com --authority-keypair ./authority.json

One authority key may hold any number of domains: domain accounts are keyed by the domain name alone, so a mail-server deployment that serves several domains registers each of them with the same authority key (its gateway’s signing keypair) and lists them all in [smtp] local_domains. Nothing else changes — the send path checks each recipient’s own domain account, and per-domain DKIM signers keep outbound signatures aligned.

Domain creation charges a fixed protocol fee — see Economics for the exact amount.

Note: a domain operator doesn’t have to ask the delegate holder to run this command by hand. See DNS setup and the domain-sithbit service for a self-service flow: prove ownership of a domain via a DNS TXT record, and the service submits this authorization on your behalf. A delegate-free, proof-carrying path — domain authorize — also exists on chain: its DNSSEC verifier mints the domain straight from a proof, the CLI stages and submits the witness end-to-end, and both routes charge the same authorization fee.

Authorize a domain by proof

See Authorize a domain by proof for what proving domain ownership buys you and why DNS is the root of trust behind it. This page is the full technical reference: the on-chain DNSSEC verifier, the witness-staging protocol, the sithbit domain authorize command tree, and measured compute costs.

sithbit domain authorize <domain> \
  ( --witness-file <path> | --witness-hex <hex> ) \
  [--payer-keypair <path>] \
  [--skip-preflight]

This is the proof-carrying sibling of domain create. Where domain create authorizes a domain because the delegate signed for it (that delegate-initiated, delegate-signed path remains as-is), domain authorize authorizes a domain because the transaction carries a witness — the DNSSEC RRSIG chain proving the domain’s _solana.authority delegation — that the on-chain program verifies for itself. No delegate signature is required, and the submitter need not be anyone special: anyone may submit a proof and pay for it, because the proof, not the signer, is the authority. Both paths charge the same authorization fee.

The design rationale — why moving from a signed token to a verifiable proof takes the admin key out of the loop entirely — is the Proving behaviour to the chain design note.

Status: the on-chain verifier is live

The on-chain DNSSEC verifier is implemented and enforced. Given a staged witness buffer, AuthorizeDomainByProof walks the real chain-of-trust from the postoffice’s root KSK down to the leaf _solana.authority.<domain> TXT and mints the domain with the proven ed25519 authority — proven end-to-end in the domain_program test suite. It verifies all three DNSSEC signature algorithms a real ICANN-anchored chain uses: RSA-2048/SHA-256 (algorithm 8), ECDSA-P256/SHA-256 (algorithm 13), and Ed25519 (algorithm 15) — see How it works.

Because a real witness (~2.7–3.1 KiB) exceeds Solana’s ~1232-byte legacy/v0 transaction packet (transaction v1, SIMD-0385, raises the envelope to 4096 bytes, but the CLI still emits legacy transactions, so the chunking stays sized to 1232 until a v1 emit path lands), it is staged into a program-owned buffer PDA first via chunked WriteProofWitness instructions, and the buffer is closed and its rent refunded afterward with CloseProofWitness (both detailed below).

How it works

The witness is far too large to ride inside a single instruction, so authorization is a two-step flow against a program-owned buffer, with a third instruction to reclaim the buffer’s rent afterward:

1. Stage the witness. The full DNSSEC chain is written into a program-owned buffer PDA seeded on [PROOF_WITNESS_SEED, payer, blake3(domain)] (see How blake3 hashing works) — a fixed header plus the contiguous witness bytes, capped at 8 KiB — via a series of chunked WriteProofWitness instructions (discriminant 27). Each carries an offset and a chunk of up to MAX_PROOF_WITNESS_CHUNK (900) bytes; the first write allocates the buffer to its declared total_len, and later writes fill it in until written_len == total_len.
2. Authorize. A single AuthorizeDomainByProof transaction then reads the fully-staged buffer and runs the verifier. Because the chain walk is compute-heavy (306–312k CU measured for an all-RSA chain, well past the 200k default — see Measured compute cost), this transaction must prepend a ComputeBudget set-compute-unit-limit instruction.
3. Reclaim the rent. Once authorization has landed (or the attempt is abandoned), CloseProofWitness (discriminant 28) closes the buffer PDA and refunds its full rent to the payer. Only the original payer may close it — the buffer PDA is seeded on the payer, so a different signer derives a different address and cannot reach it — and a partially-written buffer refunds just the same. The CLI emits this automatically after a successful domain authorize; for a failed or abandoned attempt, run domain authorize --close-witness yourself.

The authorization fee

A verified proof pays the same delegate-tuned domain-authorization fee domain create charges — DOMAIN_AUTHORIZATION_FEE_LAMPORTS, 0.01 SOL by default, tunable via SetDomainFee (see Economics) — debited from the payer and credited to the postoffice once, at the authorize step, after the chain walk succeeds. The two authorization paths cost the same, so nobody routes around the fee by choosing one path over the other. A failed proof charges nothing beyond transaction fees — the domain is not created and no fee moves (the staged buffer’s rent stays reclaimable via domain authorize --close-witness).

The chain-of-trust walk

The verifier (program_common::dnssec::walk_chain_with) anchors at the postoffice’s root_ksk fingerprint: a DS-style SHA-256 digest of owner ‖ DNSKEY (RFC 4509) for some key in the root DNSKEY set, which must self-sign that set. From there it walks each delegation down the tree — for every link it canonicalizes the RRSIG (RFC 4034 §6), matches the DS digest root → TLD → registrable zone, and checks the signature’s validity window against the cluster clock — and finally verifies the leaf _solana.authority.<domain> TXT RRSIG. The ed25519 public key that TXT publishes (base58) becomes the new domain’s authority.

Three signature algorithms

A real ICANN-anchored chain mixes signature algorithms: the root and TLD zones sign with RSA-2048/SHA-256 (DNSSEC algorithm 8), while the registrable leaf zone is today typically ECDSA-P256/SHA-256 (algorithm 13 — used by Cloudflare, Route 53, and Google Cloud DNS); Ed25519 (algorithm 15) is valid but rare. The verifier handles all three, by two different routes:

• RSA (alg 8) is checked inline. Its RSASSA-PKCS1-v1_5 modular exponentiation runs in-program through the allocator-free sol_big_mod_exp syscall. An all-RSA chain needs nothing beyond the buffer.
• ECDSA-P256 (alg 13) and Ed25519 (alg 15) ride the native precompiles. Solana has no in-program P-256 or Ed25519 curve op, only the Secp256r1SigVerify and Ed25519SigVerify precompiles. So for each non-RSA RRSIG in the chain, the transaction includes one matching precompile instruction and passes the Instructions sysvar as an optional 6th account to AuthorizeDomainByProof. The program then introspects that sysvar to confirm a precompile in this transaction verified the exact (public key, message, signature) the DNSSEC link requires. (An all-RSA chain omits the sysvar account entirely.) The CLI derives and emits all of this automatically — see the walkthrough.

The one wrinkle between the two delegated algorithms: ECDSA-P256 signs a SHA-256 pre-hash of the canonical RRset, whereas Ed25519 signs the canonical octets raw and hashes them itself with SHA-512 — the verifier hands each precompile the message shape its algorithm expects.

Because the verifier calls sol_big_mod_exp, the target cluster must have the enable_big_mod_exp_syscall feature active. It is active on mainnet; a local surfpool validator needs --features-all.

Prerequisite: publish the root KSK

The proof chains back to a root key-signing-key (KSK) fingerprint stored on the PostOffice account — a mail-program account the domain program reads cross-program. The delegate publishes it once (and rotates it when ICANN rolls the root key):

sithbit postmaster ksk set <BASE58_32B> \
  [--keypair <delegate keypair>] \
  [--skip-preflight]

Read the fingerprint currently anchored on the PostOffice with the read-only sithbit postmaster ksk get (prints the base58 value, or unset).

The fingerprint is a 32-byte value in base58 (the same encoding wallet addresses use). Concretely it is the DS-style SHA-256 digest of owner ‖ DNSKEY (RFC 4509) for the ICANN root KSK — the same digest a DS record carries — which is what the verifier’s anchor step matches. The all-zero value — 11111111111111111111111111111111 — is the “unset” sentinel and clears it; while it is unset, domain authorize fails with RootKskUnset before it looks at the witness at all.

You do not compute that digest by hand. IANA publishes it as the SHA-256 KeyDigest in its root trust anchor (root-anchors.xml), and postmaster ksk iana turns that file into the base58 value — a pure offline conversion that neither signs nor touches the chain:

# from a downloaded anchor file (recommended — verify its signature first)
sithbit postmaster ksk iana --anchors-file root-anchors.xml

# or fetch it straight from data.iana.org (unverified — dev/preview only)
sithbit postmaster ksk iana

It prints each anchor’s key tag, digest, and base58 fingerprint, and — when exactly one is active (no validUntil) — the ready-to-run ksk set line. The trust decision stays with you: the CLI does not fetch the anchor inside ksk set itself, because the whole security model rests on the delegate deliberately vouching for the anchor (verified out-of-band), not on trusting whatever a network lookup returns. It is a rare, governance-paced step — you re-run it only when ICANN rolls the root key.

Rollovers: more than one active anchor

During a root-KSK rollover ICANN publishes two active anchors (neither carries a validUntil) for the overlap period — as it is doing now for the KSK-2024 introduction alongside KSK-2017. When it sees more than one active anchor, ksk iana does not guess: it prints a warning, recommends the newest by validFrom (with that anchor’s ready-to-run ksk set line), and exits non-zero so the choice stays deliberate. Note that “newest” is a convenience, not gospel — during the introduction phase the incoming key may be published before it is signing. Confirm which key tag is operational against ICANN’s rollover announcement, then pin exactly that one:

sithbit postmaster ksk iana --key-tag 20326

--key-tag selects that anchor’s ksk set line directly (and exits zero), so once you have decided, the command is scriptable again. Because the root DNSKEY RRset carries both keys throughout the overlap, a witness verifies against either active anchor while both are present; pinning the key that will remain avoids a re-ksk set when the old one is finally revoked.

Downloading and verifying the anchor

IANA signs root-anchors.xml with a detached S/MIME (CMS) signature (root-anchors.p7s) — not PGP. --fetch-anchors <DIR> downloads the anchor, that signature, and ICANN’s CA bundle, then prints the exact openssl command to verify them and the follow-up derive step. It deliberately does not derive a fingerprint itself — you verify first:

sithbit postmaster ksk iana --fetch-anchors ./anchors

then run the printed command:

openssl cms -verify -CAfile ./anchors/icannbundle.pem -inform DER \
  -in ./anchors/root-anchors.p7s -content ./anchors/root-anchors.xml -binary

The -binary flag is required: without it openssl canonicalizes the detached content as text (CRLF translation) and the digest fails to match. On older OpenSSL use openssl smime -verify -inform der ... instead. Verification successful means the XML is authentic; now derive from the file you just verified:

sithbit postmaster ksk iana --anchors-file ./anchors/root-anchors.xml

Getting ICANN’s CA independently

There is a bootstrap trap here: icannbundle.pem was fetched from data.iana.org over the same channel as the anchor it vouches for. On its own it only proves the three files are internally consistent — a network attacker who can serve you a forged root-anchors.xml can serve a matching forged .p7s and icannbundle.pem too. Verifying downloaded content against a downloaded signature using a downloaded CA proves nothing unless the CA reaches you through a channel independent of the data. ICANN’s DNSSEC CA is a private CA — it is not in your browser/system web-PKI trust store — so you cannot lean on the usual roots. Practical ways to obtain it out-of-band, in rough order of effort:

• Cross-check the digest itself, not the CA (simplest, and usually enough). The root KSK’s DS digest is a widely-replicated public constant. Confirm the hex postmaster ksk iana prints — E06D44B80B8F1D39A95C0B0D7C65D08458E880409BBC683457104237C7F8EC8D for the current KSK-2017 (tag 20326) — against several independent, authenticated sources: your distro’s DNSSEC root-anchor package (below), ICANN’s site over web-PKI TLS, and RFC 7958. If independent sources agree on the digest, the S/MIME dance is belt-and-suspenders.
• Use a copy shipped through your distro’s signed package channel. Packages like Debian/Ubuntu dns-root-data (/usr/share/dns/root.ds) and unbound (whose unbound-anchor ships a built-in copy of ICANN’s CA / the 2017 KSK to bootstrap root.key) reach you via APT/DNF’s GPG-signed repositories — a genuinely independent, cryptographically-verified channel. Point openssl -CAfile at unbound’s bundled cert, or just compare digests with unbound-anchor -v.
• Fetch the CA over multiple independent network paths and compare. Download icannbundle.pem from a different ISP, a cloud VM in another region, and/or over Tor, and compare the file’s SHA-256. A non-global adversary cannot MITM all paths at once, so matching hashes raise confidence.
• Check the CA certificate’s own fingerprint against ICANN’s out-of-band publications (its DNSSEC practice statement and announcements).

For a one-time devnet/preview setup the bare ksk iana fetch is fine; for a mainnet delegate, verify through at least one independent channel above before you ksk set.

Note: ksk set is a delegate-only governance action (error 66, NotDelegate, for any other signer), gated behind the CLI’s postmaster feature. See The Postmaster.

Supplying the witness

The witness is the opaque RRSIG-chain bytes — the staged DNSSEC proof the verifier walks. Provide it from exactly one of two sources (the CLI enforces the choice):

• --witness-file <path> — a file holding the raw witness bytes.
• --witness-hex <hex> — the witness as a hex string (an optional 0x prefix is accepted).

The CLI bounds the witness client-side at MAX_PROOF_WITNESS_LEN (8 KiB — the on-chain buffer’s cap) and refuses an empty one, both before it sends any transaction, so a mis-sized witness never costs a fee. A real chain runs ~2.7–3.1 KiB, comfortably inside that bound.

Building the witness with gather-witness

Not in the default build. gather-witness links a DNS resolver stack, so — like discover — it is gated behind the CLI’s opt-in gather feature and is absent from a stock sithbit binary. Build one that has it with cargo build -p mail-client --features gather (or --all-features) before the commands below will resolve.

You do not assemble those bytes by hand. domain gather-witness collects them from live DNS for you:

sithbit domain gather-witness <domain> \
  [--resolver <ip>] \
  [--out <path>]

It queries a recursive resolver with the DNSSEC DO bit set — so every answer carries its RRSIG — walks the delegation from the root to your zone (finding each cut by its DS record), and collects exactly the records the on-chain verifier needs: the root DNSKEY self-signature, each zone’s parent-signed DS and self-signed DNSKEY, and your leaf _solana.authority.<domain> TXT. It serializes them into the witness buffer and — before writing anything — re-walks the assembled chain locally with the very same program_common verifier the program runs (RSA inline; ECDSA-P256/Ed25519 via host curve checks), so a witness that would fail on-chain is caught for free, not paid for. On success it prints the root KSK fingerprint the chain anchors to (which must match the one set on-chain with ksk set) and the proven authority key.

# write the witness to a file, then authorize with it
sithbit domain gather-witness sithbit.com --out proof.bin
sithbit domain authorize sithbit.com --witness-file proof.bin

# or without --out, it prints the hex for --witness-hex
sithbit domain gather-witness sithbit.com

--resolver defaults to 1.1.1.1; override it if your network blocks it or the default does not return RRSIGs. (As noted above, gather-witness needs a CLI built with --features gather.)

Publishing the DNS records the proof needs

gather-witness (and the on-chain verifier) require your domain to be a DNSSEC-signed zone apex publishing a single authority TXT. Three one-time setup steps get you there:

1. Enable DNSSEC at your DNS host. Your host signs the zone and shows you a DS record (key tag, algorithm, digest type, digest). On Cloudflare: DNS → Settings → Enable DNSSEC; it signs with ECDSA-P256 (algorithm 13), which the verifier handles.
2. Install that DS at your registrar. The DS must live in the parent zone (e.g. .com), and only your registrar — the company you bought the domain from — can write there. Copy the DS from your DNS host into the registrar’s DNSSEC panel; the registrar relays it to the TLD registry, which completes the signed delegation. Special case: if you registered the domain through Cloudflare Registrar (Cloudflare is both registrar and DNS host), enabling DNSSEC submits the DS for you — nothing to copy. The two-step copy only applies when your domain is registered elsewhere and merely uses Cloudflare for DNS.
3. Publish the authority TXT. Add exactly one TXT record at _solana.authority.<domain> whose value is your wallet’s authority key, base58-encoded (the same convention the off-chain domain-sithbit flow reads). More than one TXT at that name is rejected — the verifier requires exactly one.

Once the DS is live at the parent and the TXT is published, gather-witness can collect a complete, verifiable chain.

The --payer-keypair funds the staging and authorize transactions, the new domain account’s rent, and the authorization fee; it defaults to the CLI’s configured keypair, and it is the only required signer — no delegate signature is involved.

End-to-end walkthrough

Two commands take a domain from a witness to authorized. First the delegate publishes the root KSK once (see Prerequisite: publish the root KSK); then anyone holding the witness runs domain authorize:

# once, by the delegate — anchors every proof to the ICANN root
sithbit postmaster ksk set <BASE58_32B>

# permissionless — anyone with the witness may submit and pay
sithbit domain authorize example.com --witness-file ./proof.bin

That second command runs the whole submission for you — you never stage the buffer, build a precompile instruction, attach a ComputeBudget instruction, or reclaim the buffer’s rent by hand:

1. It stages the witness automatically, splitting it into ≤900-byte chunks and writing each with a confirmed WriteProofWitness transaction, printing Staged witness chunk N/N as it goes (the buffer protocol is How it works).
2. It derives any precompile instructions the chain needs — for each non-RSA (ECDSA-P256 or Ed25519) RRSIG it re-walks the witness client-side (the same program_common chain walk the program runs, with a collecting verifier plugged into the same seam the on-chain precompile introspection uses) and builds one self-contained Secp256r1SigVerify / Ed25519SigVerify instruction over the exact (public key, canonical message, signature) tuple the on-chain walk will demand. An all-RSA chain needs none, and the transaction is unchanged from its historical form.
3. It then submits AuthorizeDomainByProof with a ComputeBudget set-compute-unit-limit instruction prepended automatically (400k, sized for the measured ~306–312k-CU all-RSA chain walk with headroom — see Measured compute cost), the derived precompile instructions alongside it, and — only when precompiles ride — the Instructions sysvar as the authorize instruction’s 6th account, and prints the submitted-proof transaction URL.
4. On a successful authorization it closes the spent witness buffer automatically with CloseProofWitness, refunding the buffer’s rent to the payer and printing Closed witness buffer; reclaimed N lamports. A failed authorize deliberately skips this step: the staged buffer stays put for a retry or inspection, reclaimable any time with domain authorize --close-witness.

This is proven end-to-end in the client integration suite for both a genuine all-RSA-2048 chain (authorize_by_proof_cli_with_staged_witness_succeeds) and an ECDSA-P256-leaf chain — the shape most Cloudflare, Route 53, and Google Cloud DNS zones have today — with the CLI-emitted precompiles (authorize_by_proof_cli_with_ecdsa_leaf_succeeds).

One honest wrinkle: the on-chain matcher compares each precompile’s signature bytes against the RRSIG’s raw bytes, and the secp256r1 precompile itself rejects high-S ECDSA signatures — so an alg-13 RRSIG whose signature is high-S cannot be proven on-chain at all. Real DNSSEC signers emit low-S in practice; the CLI normalizes to low-S on emission, which is the identity for those.

Reclaiming an abandoned witness buffer

sithbit domain authorize <domain> --close-witness \
  [--payer-keypair <path>] \
  [--skip-preflight]

A successful domain authorize reclaims the staged buffer’s rent automatically, but a failed or abandoned attempt leaves the buffer behind on purpose — the staged witness stays available for a retry or for inspection. When you are done with it, domain authorize --close-witness submits CloseProofWitness to close the buffer and refund its full rent, printing the reclaimed lamports.

The --payer-keypair must be the same keypair that staged the witness: the buffer PDA is seeded on the payer, so it is the only key that derives — and may close — that buffer, and it is where the rent refund lands. A partially-staged buffer (an attempt abandoned mid-write) closes and refunds just the same. If no buffer exists for the (payer, domain) pair, the command refuses client-side before sending any transaction.

Measured compute cost

The chain walk’s cost is measured through the deployed .so on a real cluster (surfpool), driven by the two positive end-to-end tests. Both shapes walk a three-zone chain (root → TLD → leaf):

• All-RSA chain (six RSA-2048 verifications, all inline via sol_big_mod_exp): the authorize instruction consumed 305,704–311,868 CU across runs — the small spread tracks witness content (domain-name lengths and key values vary per run).
• ECDSA-P256-leaf chain (four RSA-2048 verifications inline; the leaf’s two P-256 RRSIGs proven by Secp256r1SigVerify precompile instructions): 229,845–231,181 CU. The precompile instructions themselves metered zero transaction-budget CU on this runtime, so the transaction-wide total was the program’s consumption plus 150 CU for the ComputeBudget instruction itself.

The CLI’s 400,000-CU limit therefore keeps ~28% headroom over the worst measured shape. Each additional all-RSA zone in a deeper chain costs roughly +80k CU (two more RSA-2048 verifications at ~40k each), so a four-zone chain approaches the limit and a deeper one would need it raised. The other instructions are cheap and ride the 200k default: each WriteProofWitness chunk measured ~9–11k CU and CloseProofWitness ~7–8k.

Reclaim a domain by proof

See Domains for what a domain is and how it’s normally created, administered, and transferred. This page covers reclaiming a domain’s on-chain authority by DNSSEC proof — the sovereign-DNS counterpart to authorizing a new domain by proof — including its timelock mechanics, its threat model, and the sithbit domain reclaim command tree.

sithbit domain reclaim <domain> \
  ( --witness-file <path> | --witness-hex <hex> ) \
  [--payer-keypair <path>] \
  [--skip-preflight]

Reclaiming is the sovereign-DNS counterpart of domain authorize. Where authorize mints a new domain from a DNSSEC proof, reclaim targets a domain that already exists and seizes its on-chain authority for the wallet address a fresh proof establishes — even when that domain is held by someone else on chain. It is the same proof-carrying, permissionless machinery: anyone may submit a current DNSSEC proof and pay for it, because the proof, not the signer, is the authority. The one difference from authorize is the guard rail — a reclaim does not take effect immediately. It runs behind a 7-day timelock, so the current on-chain authority has a window to notice and respond.

DNS is the root of trust, forever

This is the deliberate design intent, stated plainly: the DNS owner of a domain can always reclaim its on-chain authority. On-chain possession of a domain is never permanently sovereign against the DNS root. Whoever controls the domain’s DNSSEC delegation today — and can therefore publish a current _solana.authority.<domain> TXT and sign it down a chain that anchors to the postoffice’s root KSK — can produce a proof that binds the domain to a wallet of their choosing, and reclaim it.

That is not a loophole; it is the point. SithBit domains are DNS domains. Ownership of the on-chain MailDomain account tracks ownership of the real domain name, and the real domain name is governed by DNS, not by the chain. If a domain changes hands at the registrar, or a stale/hostile party holds the on-chain authority, the rightful DNS owner is never locked out: a fresh proof reclaims the authority. The chain defers to the DNS root of trust as the final arbiter of who owns a name.

The two-step timelock

Because a reclaim can seize a live domain’s authority, it cannot be instantaneous — that would let a fresh proof yank a domain out from under its current holder with no warning. So a reclaim is a request → wait → finalize flow, mirroring deactivation’s shape:

1. Request. domain reclaim stages the DNSSEC witness and, on a verified proof, opens the timelock: it creates a small transient PDA seeded on the domain, stamped with the current chain time and the proven incoming authority (the ed25519 key the leaf TXT published). The MailDomain account itself is untouched — its authority does not change yet. The presence of that pending PDA is the “reclaim pending” flag.
2. Wait. A 7-day clock runs (RECLAIM_TIMELOCK_SECS). During it the domain keeps its current authority and mail keeps flowing.
3. Finalize. Once the clock elapses, domain reclaim --finalize installs the recorded authority onto the domain and closes the pending PDA. The chain was walked once, at request time, so finalize trusts the recorded key and is permissionless — any fee-payer may crank it. The rent refund, however, does not follow the cranker: the pending PDA records the wallet that funded the request, and finalize pays the refund back to that wallet. A stranger turning the crank performs a service; they cannot capture the requester’s deposit by doing so.

Before the timelock elapses, the reclaim can be cancelled by either the domain’s current authority (the standing holder rejecting an unwanted reclaim) or the proven key itself; the canceller receives the pending PDA’s rent refund. Cancelling is authority-gated rather than permissionless, which is why it is the one path where the refund follows the signer.

Request the reclaim

sithbit domain reclaim <domain> \
  ( --witness-file <path> | --witness-hex <hex> ) \
  [--payer-keypair <path>] \
  [--skip-preflight]

The witness, its two input sources, the client-side size bound, the automatic buffer staging + ComputeBudget bump + precompile emission for non-RSA chain links, and the automatic buffer close on success are exactly as domain authorize describes — a reclaim reuses that whole pipeline. It also requires the same prerequisite root KSK and charges the same authorization fee (0.01 SOL by default) once the proof verifies. The --payer-keypair funds the pending PDA’s rent plus that fee and is the only required signer.

sithbit domain reclaim example.com --witness-file ./proof.bin

Finalize after the timelock

sithbit domain reclaim --finalize <domain> \
  [--payer-keypair <path>] \
  [--skip-preflight]

Once at least 7 days have passed since the request, this swaps the domain’s authority to the proven key and closes the pending PDA (rent to the fee-payer). Run before the timelock has elapsed, it is rejected on-chain (ReclaimTimelockNotElapsed). It is permissionless — the fee-payer need not be anyone in particular.

sithbit domain reclaim --finalize example.com

Cancel a pending reclaim

sithbit domain reclaim --cancel <domain> \
  [--keypair <path>] \
  [--skip-preflight]

Aborts an in-flight reclaim before it finalizes, closing the pending PDA. The signer must be the current authority or the proven key; the domain stays with its current authority as if the request had never happened.

sithbit domain reclaim --cancel example.com

Seeing a pending reclaim

domain get surfaces any in-flight reclaim beneath the domain’s authority line — the request timestamp, the proven incoming authority, and whether the timelock has elapsed:

sithbit domain get example.com

Domain 'example.com' (…) has authority <current> and is active
Reclaim pending: requested at <ts> for authority <proven key>; timelock not yet elapsed (unlocks at <ts>)

A pending reclaim freezes the marketplace

While a reclaim is pending, the domain cannot be bought or listed. Both domain buy and domain sell are refused on-chain with DomainReclaimPending (error 71). This closes an obvious front-run: without it, a holder who saw an incoming reclaim could dump the domain on the open marketplace — selling it out from under the reclaimer — or a buyer could pay for a domain that is about to change owner. Once the pending is cancelled or finalized (or never existed), listing and buying are allowed again.

Threat model: the timelock is the defense window

The 7-day timelock is the whole security argument for reclaim. A reclaim proves DNS ownership as of proving time — it is a snapshot of the domain’s DNSSEC state when the witness was assembled. The timelock turns that snapshot into a notice-and-veto window: the current on-chain authority (or an operator watching for pending reclaims) sees the request, and can cancel it, migrate custody, or otherwise respond before the authority actually changes hands. Nothing is seized silently or instantly.

That window also bounds a subtler risk. A DNSSEC RRSIG is valid for its whole signature window, so a proof reflects DNS state at the moment it was signed, not the moment it is submitted — a proof captured while a party controlled the domain stays cryptographically valid until its RRSIGs expire, even if control has since moved on. The timelock caps the damage of such a stale-but-still-valid (replayed) proof: because finalizing takes 7 more days after the request lands, the true current owner always has time to notice a reclaim opened against an out-of-date proof and cancel it. The defense is not “proofs never go stale” — it is “a stale proof cannot complete a reclaim faster than the real owner can veto it.” Keep signature windows short and rotate the delegated authority key when custody changes to shrink the replay surface further.

For the broader admin-key and trust discussion, see the threat model.

Related

• Domains — what a domain is and its normal creation/administration lifecycle.
• Authorize a domain by proof — the sibling operation that mints a new domain from a DNSSEC proof, with no timelock.
• Looking up a domain — reading a domain’s current authority and any pending reclaim.
• List a domain for sale — the marketplace listings a pending reclaim freezes.
• Threat model — the broader admin-key and trust discussion this page’s threat-model section draws on.

Attest a verified sender

See Verified-sender attestation for what an attestation is and why a sending organization buys one. This page is the technical reference: the attest, lookup, and revoke commands, the postmaster fee setting, and the on-chain mechanics they ride.

sithbit domain attest-sender <MAIL_DOMAIN> [WALLET] \
  ( --witness-file <path> | --witness-hex <hex> ) \
  [--payer-keypair <path>] \
  [--skip-preflight]

This is the third member of the proof-carrying family, alongside domain authorize and domain reclaim. It submits the same DNSSEC witness — the RRSIG chain proving the domain’s _solana.authority delegation, which the on-chain program verifies for itself — but instead of authorizing the domain, a verified proof records that the domain vouches for a wallet as a legitimate sender. Like its siblings it is permissionless: anyone may submit a proof and pay for it, because the proof, not the signer, is the authority.

What a verified proof mints is the SenderAttestation account for the (domain, wallet) pair, stamped with the chain clock. Three shape differences from domain authorize are worth knowing:

• No domain account is involved. Attesting neither reads nor creates a MailDomain: a domain that has never been registered as a mail domain can attest senders just the same. The attestation is a freestanding record, and it confers no serving rights over the domain.
• The attested wallet rides the instruction payload. It defaults to the payer’s own address, but the proving claimant may attest any wallet — control of the domain’s DNS is the sole authorization, and the authority key the leaf TXT publishes is not required to match the attested wallet (the domain vouches for whoever it names).
• One record per (domain, wallet) pair, any number of pairs. A domain may attest as many wallets as it likes; each attestation is minted — and later revoked — independently.

The witness, its two input sources (--witness-file / --witness-hex), the client-side size bound, gathering the witness from live DNS, the automatic buffer staging + ComputeBudget bump + precompile emission for non-RSA chain links, and the automatic buffer close on success are exactly as domain authorize describes — an attest reuses that whole pipeline, including the prerequisite root KSK. The staged buffer is even the same (payer, domain) PDA, so either command can reclaim it.

# attest your own wallet (the payer's address is the default)
sithbit domain attest-sender acme.com --witness-file ./proof.bin

# attest a different sending wallet
sithbit domain attest-sender acme.com mAiLiLdgjgGdWoCZkpW3cj7JLAC56qb4NErFyQFWNJg \
  --witness-file ./proof.bin

The attestation fee

A verified proof pays a one-time flat fee to the postoffice — DEFAULT_SENDER_ATTESTATION_FEE_LAMPORTS, 0.01 SOL by default — debited from the payer once, at the attest step, after the chain walk succeeds. A failed proof charges nothing beyond transaction fees, and the staged buffer’s rent stays reclaimable. The CLI quotes the currently tuned fee in its success output, and anyone can read it ahead of time — no signature, ships in every build:

sithbit postoffice fee attestation

The delegate tunes the fee with:

sithbit postmaster fee attestation <LAMPORTS> \
  [--keypair <delegate keypair>] \
  [--skip-preflight]

The value is hard-capped on-chain at MAX_SENDER_ATTESTATION_FEE_LAMPORTS (0.1 SOL, 10× the default) — an over-cap value refuses with custom error 101 (SenderAttestationFeeAboveCap) — so even a compromised delegate key cannot price attestation out of reach. Zero resets to the protocol default: like the settlement rates, a zero stores the “unset” sentinel, so the fee cannot be tuned to literal zero. A postoffice account that predates the fee field reads back the default, and the setter grows the legacy account in place (to the 184-byte layout) on its first run. See the tunable-constants table.

Looking up an attestation

sithbit domain attestation <MAIL_DOMAIN> <WALLET>

Read-only, and — like domain get — it ships in every build. It prints the attested wallet, the attestation account, and the attested-at timestamp, or a not-found notice when the domain has not attested that wallet (a missing record is the common negative answer, not an error):

sithbit domain attestation acme.com mAiLiLdgjgGdWoCZkpW3cj7JLAC56qb4NErFyQFWNJg

Servers ask the same question over the mail-grpc gateway: the GetSenderAttestation call takes {domain, wallet} and answers {attested, attested_at}. A clean on-chain absence answers attested = false; a failed chain read is an UNAVAILABLE status, never a false — absent and unknown stay distinguishable. The read is finalized-commitment and uncached, so a fresh attestation (or revocation) is visible on the next call.

Revoking an attestation

sithbit domain revoke-attestation <MAIL_DOMAIN> \
  [--keypair <path>] \
  [--skip-preflight]

Closes the (domain, wallet) attestation for the signing wallet and refunds the record’s rent to it. Only the attested wallet itself can revoke: the attestation’s address is re-derived from the signer, so any other key — the domain’s included — derives a different address and never reaches the record (the same derivation binding CloseProofWitness uses for its payer). The command refuses client-side when no attestation exists for the signer under that domain.

sithbit domain revoke-attestation acme.com --keypair wallet.json

Reclaiming an abandoned witness buffer

sithbit domain attest-sender <MAIL_DOMAIN> --close-witness \
  [--payer-keypair <path>] \
  [--skip-preflight]

A successful attest reclaims the staged witness buffer’s rent automatically; a failed or abandoned attempt leaves the buffer behind for a retry or inspection, exactly as domain authorize does. When you are done with it, --close-witness closes the buffer and refunds its full rent to the same payer keypair that staged it — the buffer PDA is seeded on the payer, so it is the only key that can. Because the buffer is the shared (payer, domain) staging PDA, domain authorize --close-witness reclaims the identical buffer.

Measured compute cost

Measured through the deployed .so on a real cluster, like every row in the compute-unit table: the attest transaction consumed 322,474 CU (fenced at 345,000) — the DNSSEC chain walk dominates, which is why the CLI prepends the same ComputeBudget limit domain authorize sizes to the proof’s zone depth. RevokeSenderAttestation measured 11,224 CU (fenced 34,000) and SetSenderAttestationFee 6,546 CU (fenced 30,000), both comfortably on the 200k default budget.

Related

• Verified-sender attestation — what the record means, who buys it, and what it does not confer.
• Reputation-scaled first-contact pricing — the economic effect an attestation buys: a stranger’s first contact priced at the discount floor immediately, no spend history required.
• Authorize a domain by proof — the shared witness pipeline, root-KSK prerequisite, and gather-witness.
• Reclaim a domain by proof — the other proof-carrying sibling, for seizing an existing domain’s authority.
• Program & PDA reference — the instruction discriminants and the sender_attestation PDA seed.

Transfer a domain

See Domains for what a transfer conveys — mail-serving control of the domain, not the mailboxes that reference it — and why it’s a delegate-only operation. This page covers the sithbit domain transfer command.

sithbit domain transfer <domain> <new_authority> \
  [--keypair <delegate keypair>] \
  [--skip-preflight]

Arguments

• <domain> (required) — the domain to transfer.
• <new_authority> (required) — a bare address (or alias/keypair path the CLI can resolve to one) of the wallet that becomes the domain’s new authority. It does not sign: the new operator need not be online, and no signature from the outgoing authority is required either. It may be any wallet, including one that has never held a domain before.
• --keypair <delegate keypair> — the delegate’s signing keypair. Required on every invocation: a signer that isn’t the postoffice’s standing delegate is refused with error 66, NotDelegate. Also pays the transaction fee. Defaults to your configured default keypair when omitted.
• --skip-preflight (optional) — submits the transaction without a local simulation pass first.

This command requires the CLI’s domain feature, which is enabled by default.

What changes on-chain

Transfer rewrites a single field — authority — on the existing MailDomain PDA. Its is_active flag, rent_payer, and domain name are all left untouched, and no account is created or closed. Consequences:

• The domain keeps serving mail without interruption; only the key that may sign SendMail for it changes.
• Because rent_payer is unchanged, a later domain close still refunds the account rent to whoever originally funded it — transferring authority does not move the rent claim.
• A domain must already exist and be program-owned to be transferred; transferring a domain that was never created is rejected.

Refused while listed

A domain with an open marketplace listing (domain list) cannot be transferred. Repointing the authority under a live listing would leave a stale holder recorded as the listing’s seller — able to collect the sale proceeds the moment a buyer paid for a domain they no longer own. The instruction carries the domain’s listing account read-only and refuses while a listing stands, with The domain has an open listing; cancel it before closing, transferring, or deactivating on stderr. The authority must cancel the listing first; then the delegate transfers.

Deactivation is the asymmetric case: requesting a deactivation proceeds while a listing is open — the delegate’s safety brake on a rogue domain is never blocked by a sale — and it is the purchase that then refuses while the deactivation timelock is pending. See Deactivate a domain.

Example

sithbit domain transfer sithbit.net maiLtdkxym8CCmo9TwDuXywqd9DXaK3tB6toKFVeBFR

After it lands, SendMail for sithbit.net must be signed by maiLtdkxym8…VeBFR, and that key earns the operator settlement share (see Economics). Confirm the new value any time with domain get, which prints the domain’s current authority.

Errors

• NotDelegate (error 66) — the signing --keypair isn’t the postoffice’s recorded standing delegate. Transfer is a delegate-only operation, same as create and deactivate.
• Transferring a domain that was never created, or is not program-owned, is rejected.
• Transferring a domain with an open marketplace listing is refused; see Refused while listed above.

Note: don’t confuse this with handing over the postoffice itself — see Delegate and postmaster administration. domain transfer changes who administers one domain; installing a new postmaster or repointing the standing delegate changes who administers every domain in the deployment.

See also

• Create a domain
• Deactivate a domain
• List a domain for sale — the marketplace sale the open-listing guard protects, and what an authority swap conveys.
• The marketplace sells protocol authority; DNS remains separately owned — the threat model of repointing authority away from whoever controls the domain’s DNS.
• Closing accounts for retiring a domain outright with domain close.

List a domain for sale

See Domains for what a domain sale conveys — and doesn’t — and Trading names: aliases & domains for how a domain listing fits alongside the rest of the marketplace. This page covers the sithbit domain sell/buy command tree.

sithbit domain sell <domain> --price <lamports> \
  [--expires-in <seconds>] \
  [--keypair <authority keypair>] \
  [--skip-preflight]

Puts a domain up for sale on the open marketplace: a fixed-price listing that any buyer may take, first come, first served. Whoever signs domain buy and pays the price becomes the domain’s authority — the mail server’s signing key, and the wallet that collects the domain’s operator share of settlement.

sithbit domain sell sithbit.net --price 5000000000
Listed mail domain 'sithbit.net' for sale at 5000000000 lamports
https://explorer.solana.com/tx/…

Who signs

Unlike every other domain mutation — create, transfer, deactivate, close are all delegate operations — listing a domain is signed by the domain’s current authority (--keypair, defaulting to the CLI’s configured keypair): selling is the owner’s own decision, not an administrative one. The delegate is not involved at any step of a marketplace sale.

The price is in lamports and must be positive — a free hand-off uses domain transfer instead, a delegate operation. The listing lives in a dedicated account derived from the domain name’s blake3 hash, so each domain can carry at most one listing at a time. The authority fronts that account’s rent when staging the listing and gets it back when the listing resolves — bought, cancelled, or reclaimed after expiry.

Listing changes nothing about how the domain serves mail: the current authority keeps signing SendMail and collecting the operator share until the moment a buyer pays.

The binding window, replacing, and expiry

Listings share the alias marketplace’s semantics exactly:

• For its first 5 minutes a listing is binding on the authority — it can be neither cancelled nor replaced, so a buyer paying promptly can’t be front-run by a retraction. Buying is never window-gated.
• A new domain sell for the same domain replaces the standing listing in place (same account, no extra rent) once the window has elapsed — and re-arms the 5-minute window.
• A listing lapses 30 days after staging unless --expires-in <seconds> sets a different lifetime. A buy at or before the expiry instant succeeds; after it, only sell --cancel (reclaiming the rent) remains.

Deactivation interplay

A domain with an in-flight deactivation timelock cannot be listed — the domain’s state would change under the buyer between listing and purchase; cancel the deactivation first. The same guard sits on the purchase itself: domain buy is refused while a deactivation is pending. That matters because requesting a deactivation while listed is allowed — the delegate’s safety brake on a rogue domain is never blocked by a sale — so a timelock started after the listing was staged would otherwise hand a buyer a domain that flips inactive moments after they paid.

An already-inactive domain, though, is listable: like domain transfer, a sale swaps the authority regardless of the active flag, and the is_active field is plainly readable on-chain for any buyer doing their diligence (domain get prints it).

Buying a listed domain

sithbit domain buy <domain> \
  [--payer-keypair <keypair>] \
  [--keypair <keypair>] \
  [--skip-preflight]

Any wallet may buy — the buyer signs, and paying the price doubles as consent. In one atomic instruction the price leaves the paying wallet, splits between the current authority and the postoffice (90/10 — see Economics for the exact money flow), the domain’s authority field repoints at the buyer, and the listing closes with its rent refunded to the selling authority.

sithbit domain buy sithbit.net --keypair buyer.json
Bought mail domain 'sithbit.net'; its new authority is maiLtdkxym8CCmo9TwDuXywqd9DXaK3tB6toKFVeBFR
https://explorer.solana.com/tx/…

Exactly as with domain transfer, only the authority field changes: is_active, rent_payer, and the domain name are preserved, no mailbox is touched, and a later domain close still refunds the domain rent to whoever originally funded it. See what a purchase does and does not convey for what stays off-chain regardless.

By default the buyer’s own wallet pays the price. A sponsor may pay instead with --payer-keypair — the sponsor funds the price and the transaction fee (two signatures) and co-signs alongside the buyer.

Domain listings and completed domain sales appear alongside alias activity in the gRPC gateway’s marketplace surface — its listing scans and sale-history walk follow the domain program, which owns every listing account. Read the authoritative current authority any time with domain get.

Cancelling a listing

sithbit domain sell <domain> --cancel [--keypair <keypair>] [--skip-preflight]

The authority cancels an open listing (once its binding window has elapsed), closing the listing account and reclaiming its rent:

sithbit domain sell sithbit.net --cancel
Cancelled the listing on mail domain 'sithbit.net' and reclaimed its rent
https://explorer.solana.com/tx/…

This is also how the rent of an expired listing comes back.

While a listing is open, domain close and domain transfer are refused — cancel the listing first (closing would strand the listing account’s rent; transferring would leave a stale holder able to collect the sale proceeds).

Errors