Welcome

Email you own. Spam you don’t pay for.

A decentralized mail protocol on Solana — postage paid by the sender and earned by you, pricing spam out at the source; addresses tied to your wallet instead of a rented domain; and mail encrypted end-to-end and stored off-chain on IPFS. Standard SMTP, IMAP, and POP3 underneath, so the inbox you already use just works.

Read the Prelude → Skip to the Introduction

Curious how a blockchain 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.

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 blockchain email.

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.

Worse, 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 in exchange for a losing battle. And that provider usually also owns the domain your address lives on — your identity on the internet is rented, not owned, and it stops existing the moment they decide it should.

The mail program fixes the actual incentive: it charges the sender, not the recipient, and lets you set the price. 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.

Blockchain Email

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 stranger has to pay to reach you (new mailboxes default to 1 SOL/message), and you can raise, lower, or waive that price per sender at any time. Spam has to actually be profitable after your price, not just after a filter’s guess.
• You get paid for your own attention. Postage from strangers accrues directly to your wallet — you’re compensated for the inbox space you’re already defending, instead of paying a provider or letting them monetize your data instead.
• Known senders cost you nothing extra. Each correspondent gets their own prepaid postage balance for mail to you (a “frombox” — see Fromboxes). Allow-listing someone just means funding theirs yourself, and that 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.
• Your address is yours. It’s tied to your wallet, not 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.

See Economics for the full lamport-by-lamport ledger of who pays and who collects at every step.

Priced in SOL — No New Token to Trust

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.

That means no mint anyone controls, no allocation for insiders to dump, and nothing to “rug.” Sending and receiving mail never requires acquiring, wrapping, or swapping into some other asset first — 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, a blockchain-based mail system needs to clear millions of transactions per second — throughput only the Solana blockchain provides today.

Decentralized Email

Pricing solves the incentive; storage solves the trust problem. This system uses the Interplanetary File System (IPFS) to store mail bodies, encrypted by the sender, so no central authority ever holds your messages in the clear — see IPFS storage: benefits to users for what that means for you, and where to go for the IPFS project itself. Taken together, it’s possible to send email between two addresses using only the blockchain for transactions and IPFS for storage — bypassing the internet’s traditional SMTP relay infrastructure entirely.

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 stream that can offset it.
• The barrier to entry is a small, flat, one-time fee, not a gatekeeper’s approval — 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.
• You’re never locked into someone else’s infrastructure. Because routing and pricing live on-chain rather than inside one company’s servers, you can self-host a domain you already own instead of renting identities out to users the way traditional email providers do.

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 spam economy that finally works without throwing away Thunderbird, Outlook, Apple Mail, or the mobile client already on your phone.

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.

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

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

In the Solana blockchain, an “address” is the public key portion of a 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 duel 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: [email protected]

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. [email protected]), 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 (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 [email protected] also applies to [email protected]. 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 [email protected], you might create the alias myalias, and use [email protected] as your public email address.

Unlike public key addresses, aliases are case-insensitive. So [email protected], [email protected], and [email protected] 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 eliptical 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 publically 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 7489 (Domain-based Message Authentication, Reporting, and Conformance); 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. The default price should be set very high to prevent SPAM from being sent to the mailbox.
• 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 spoof guard, not a convenience — address resolution checks the alias registry before treating a string as a raw wallet address, so an unclaimed address string could otherwise be registered as someone else’s alias, silently intercepting mail meant for your wallet. See Aliases for the full explanation 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 anti-spam lever. A freshly created frombox inherits the recipient’s mailbox’s high default price, 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.

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.³

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.⁴

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. 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 security measure, not just a convenience: address resolution checks the alias registry before falling back to treating the string as a raw wallet address, so if your address string were left unclaimed, a malicious user could register it as their alias and quietly receive mail addressed to your wallet. Claiming the self-alias at mailbox creation closes that spoof. Most users therefore 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.¹

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. ↩

Domain-scoped aliases

An alias normally lives in one global namespace: whoever registers alice first owns it everywhere, and alice@anything resolves to that one wallet. A domain-scoped alias is a second, separate namespace layered on top of it — it maps local-part @ verified-domain to a wallet, and only that domain’s authority may create entries in it. This lets an organization that controls acme.com on-chain assign [email protected], [email protected], … to its people’s wallets, in a namespace nobody else can write to.

The two namespaces never collide: [email protected], [email protected], and the global alice are three different on-chain accounts — the domain-scoped account is hashed on both the domain and the local part under a seed distinct from the global alias seed, so registering one never touches or shadows the other.

Who can register a domain-scoped address

Only the wallet recorded as the domain’s authority may write into that domain’s namespace. There is no anti-squatting fee the way there is for a global alias — the namespace is scoped to a domain the authority already owns, so squatting isn’t possible in the first place, and the authority pays only the new mapping account’s rent.

Trust note. The domain authority chooses which wallet each user@domain maps to, and can repoint or remove it at any time. This is not a new trust relationship — that same authority already operates the domain’s mail relay and is fully trusted for relayed mail. A domain-scoped address is only ever as trustworthy as the domain that issues it.

Resolution precedence: domain-scoped wins, global is the fallback

Because both namespaces can define an address like [email protected] at once — a domain-scoped mapping and a same-named global alias are unrelated accounts — something has to decide which one wins. The rule is simple and applied consistently everywhere an address is resolved: the domain-scoped mapping is checked first, and only when no domain-scoped entry exists does resolution fall back to the global alias namespace (the historical, domain-blind behavior).

That single precedence rule does triple duty:

• Native resolution — a client turning [email protected] into a wallet address checks the domain-scoped namespace first, then falls back to the global alias alice.
• Inbound mail delivery — a SithBit MX server receiving mail addressed to [email protected] over SMTP applies the identical precedence to decide which wallet’s mailbox receives it, so a domain that has never registered any domain-scoped addresses keeps delivering through the plain global-alias path, unchanged.
• Encryption-key discovery — looking up the public key to seal mail to an address composes the same domain-then-global lookup before returning a key.

The practical effect: existing global aliases keep resolving exactly as before even after a domain starts registering its own scoped names, and a domain only ever affects addresses under its own suffix — it can never shadow or hijack a global alias belonging to someone else’s domain (or none at all).

A domain’s authority creates, repoints, and removes these mappings from the terminal — see Register a domain-scoped alias, which also covers the mechanics of inbound delivery and key discovery.

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.

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 (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. 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.

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.

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 — 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 — 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 — 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 — 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.

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.
• 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 — which means both have a resale market. 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. ↩

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 reach exactly that set.
• 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 counts the matched set and itemizes the per-recipient cost — message rent, postage, bounty, and fees — so you see the total before a single lamport moves.
• 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.
• 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, before committing funds.
4. Send. The advertiser sends one bountied message to each 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 is email built on a public blockchain, and that shapes its privacy model in a way ordinary email does not. The short version: SithBit puts the envelope on the chain — public and permanent — and keeps the letter sealed. 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: the sender wallet, a blake3 hash of the from address (never the string), a timestamp, and the body’s storage locator. 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.

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.

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.
• 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:

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.

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. ↩

GUI clients

Not everyone lives at a terminal. Alongside the sithbit CLI, SithBit ships four graphical clients — the Thunderbird extension, the Outlook add-in, the webmail app, and the Chrome 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:

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

The three extension pages each open with an Installing from the store section (Thunderbird, Chrome, Outlook) 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. Everything else these clients do is the account-management and onboarding surface, not a replacement for your mail app.

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

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.

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 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 [email protected] 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, a global alias, or a domain-scoped user@verified-domain address. A verified domain’s authority can map user@its-domain to a wallet, and that mapping takes precedence over the global namespace — so [email protected] reaches the wallet acme.com’s authority designated, while a bare alice (or an alice@… with no domain-scoped mapping) still resolves through the global namespace. See Domain-scoped aliases. 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 only — for now. The sealed payload is a structured envelope that can carry rich HTML and attachments alongside the text body as a single sealed unit. The current Thunderbird and Outlook plugins, however, still hand it only the plaintext body — reading the composed HTML and attachments out of the host mail client is a planned addition, and HTML/attachment support in the plugins arrives with 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 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 the operator must run

The extension talks only to account-api. For the aliases, balances, and encryption-key panes, the API needs its [chain] section configured (a mail-grpc gateway plus a Solana RPC endpoint — see the configuration reference); without it those panes report the surface as unavailable while login and the settings panes keep working.

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

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

• 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).
• 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 -x 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 both its rent and the transient request record’s to your wallet. 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 -k ~/.config/solana/id.json
  

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

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.

1. Mint the certificate — offline, no RPC:

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

   This writes sithbit.p12 — the combined, password-less PKCS#12 bundle, the one file Thunderbird imports — 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. Import sithbit.p12 in one step under Settings → Privacy & Security → Manage Certificates → Your Certificates → Import — the bundle is password-less, so leave the password prompt blank. Then, on each of the account’s SMTP (outgoing), IMAP, and POP server entries, set the connection security to SSL/TLS, the authentication method to Encrypted certificate, and select this certificate.

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 signed-in view carries a Certificate sign-in section directly below the panes, 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 one Thunderbird imports in one step, exactly as 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 -x 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.

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.

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, Outlook on the web, and classic Windows Outlook (Microsoft 365, version 2307+). Not Outlook for Mac — the unified JSON manifest doesn’t run there; a legacy XML manifest is the recorded fallback if Mac coverage becomes a need.

What the operator must run

Office add-ins are https-hosted web pages, so the operator serves the built bundle from account-api’s [static] section — the same origin as the API, which is why the add-in needs no CORS setup. Office requires https: terminate TLS with a reverse proxy, or use account-api’s [tls] section (see the configuration reference, including the dev-certificate recipe). As with Thunderbird, the aliases/balances/keys panes need [chain] configured; login and the settings panes work without it.

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

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

Point account-api at the bundle:

[static]
root = "webclients/outlook/staging"   # served under /addin

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. 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 is identical to Thunderbird’s:

• 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).
• 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 and switches the taskpane to the settings view (a plain view switch — the taskpane keeps no history); 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 both its rent and the transient request record’s. 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 -k ~/.config/solana/id.json

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 -k ~/.config/solana/id.json --out sithbit
   

   This writes sithbit.p12 — the combined, password-less PKCS#12 bundle your certificate store imports in one step — 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 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 below the settings panes, 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) in one step. 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 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.

What the operator must run

The app is served same-origin from account-api’s [static] section, so the API base URL is simply the page’s own origin and no CORS setup exists at all. Reading mail rides the /v1/mail surface, which needs only the shared [store]. Compose (POST /v1/mail/send) routes recipients the way sithbitd’s submission port does, so its reach follows the API’s config:

• No extra config — bare base58 wallet addresses deliver locally; anything else answers 503 ( alias resolution needs the chain).
• [chain] — aliases and user@your-domain addresses resolve through the gateway, with the frombox postage precheck applied before the message is accepted.
• [mail] (local_domains, [mail.dkim]) — mirrors sithbitd’s submission settings: which domains are yours (everything else is relayed) and the DKIM keys relayed mail is signed with.

As with the other clients, the aliases/balances/keys settings panes also need [chain]; login, mail reading, and the account settings work without it.

Building and serving

cd webclients/webmail
./build.sh    # wasm-pack build + stages shared/ into staging/

staging/ is the deployable bundle. Point account-api at it:

[static]
route = "/mail"
root = "webclients/webmail/staging"

then open http://127.0.0.1:8180/mail/index.html (or your deployment’s origin).

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 and #/settings 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 lists your folders with unseen counts; 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 #/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 both rents return only when you come back after the wait and finish the close. 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, 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.

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. 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 the operator must run

For the aliases, balances, and encryption-key panes, the account-api needs its [chain] section configured (a mail-grpc gateway plus a Solana RPC endpoint — see the configuration reference); without it those panes report the surface as unavailable while login and the settings panes keep working.

The three-pane mail reader rides the account API’s /v1/mail surface, so it appears whenever an account API is configured. The trustless on-chain inbox talks to no server at all — it needs only a Solana RPC endpoint and an IPFS gateway (both under Connection settings), so it keeps working with the mail server down, and it is the only reader shown when the account API url is left blank.

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

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: Balances (wallet SOL, on-chain message count, per-sender stamp lookup), 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 both rents come back only when you return after the wait and finish the close. 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 above 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 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.

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. Each row shows a participant’s wallet address, its self-attested tags, 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.

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.

Building and serving the standalone page

cd webclients/marketplace
./build.sh    # wasm-pack build + stages shared/ into staging/

staging/ is the deployable bundle, served same-origin from account-api exactly like the webmail app — no CORS, the API base URL is the page’s own origin:

[static]
route = "/marketplace"
root = "webclients/marketplace/staging"

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.)

CSP note. The standalone page bridges the wire transaction to the format the external wallet signs with the vendored codec-only @solana/kit bundle (shared/lib/kit-codec.esm.js) — served from the same origin as the page, so account-api’s script-src needs no extra origins.

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.

Getting started

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

Web onboarding: the browser wizard

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

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

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

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

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

   

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

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

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

   

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

   

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

   

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

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

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

A standalone get-started page

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

Self-service pages for refused senders

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

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

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

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

Economics

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; 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 prices out spam from senders the recipient has never met. But “never met” describes two very different wallets — a spammer’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 — 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:

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.

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 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 exit) 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., [email protected], 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. [email protected], 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.

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 sithbit mailbox credentials command.

sithbit mailbox credentials \
  [-k, --keypair <path>]

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 fixed challenge that embeds that same public key, so a captured password cannot be replayed as another wallet. The servers verify the signature against the username, and nothing is stored server-side — the signature is self-proving.

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 prints the identical pair every time — paste it into a mail app once and you are done.

Arguments

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

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.

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 -k ~/.config/solana/id.json

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.

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 \
  [-k, --keypair <path>] \
  [-o, --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 offer EXTERNAL on the listener (the client_cert_auth setting — see the configuration reference); your wallet address stays the username.

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

• -k, --keypair <path> (optional) — the wallet keypair file the certificate is derived from. Defaults to the keypair in your Solana CLI config when omitted.
• -o, --out <prefix> (optional) — 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 a mail app imports in a single step.

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). 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 [email protected]:

sithbit frombox get [email protected]

Inspect the frombox from [email protected] to a specific recipient alias, rather than your own wallet:

sithbit frombox get [email protected] [email protected]

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 [email protected] 100000000

Update frombox address 7XkQ…Qp9 for <From:[email protected] 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 [email protected]

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 [email protected] --stamps 10

Purchasing 10 stamps for frombox 7XkQ…Qp9 <From:[email protected] 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.

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.

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 ([email protected]) 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 -k ~/.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 spoof guard, since an unclaimed address string could otherwise be registered as someone else’s alias and intercept 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 spoof guard 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.

See Closing accounts for how to close an alias and reclaim its rent.

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 -k 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 -k 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.
• Omitting both defaults the auction to run 7 days.

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.

Domain-scoped aliases

See Domain-scoped aliases for the namespace model, the domain-then-global resolution precedence, and who is trusted to register into a domain’s namespace. This page covers the sithbit alias register-domain / update-domain / remove-domain commands, inbound delivery, and the public encryption-key keyserver.

Register, repoint, remove

All three are signed by the domain authority’s keypair (-k), and take a local-part@domain address:

# Map [email protected] to a wallet
sithbit alias register-domain [email protected] --wallet <WALLET_PUBKEY> -k authority.json

# Repoint it to a new wallet in place (keeps the account and its rent)
sithbit alias update-domain [email protected] --wallet <NEW_WALLET_PUBKEY> -k authority.json

# Remove it, refunding the rent to the authority
sithbit alias remove-domain [email protected] -k authority.json

The --wallet the address points at need not be the signer — the authority designates it. The local part is normalized to lowercase and must use the same a-z0-9._- character set as a global alias.

Resolving a domain-scoped address

sithbit alias get resolves a domain-scoped mapping first, then falls back to the global namespace when none exists — see Resolution precedence:

sithbit alias get [email protected]

• If acme.com registered alice, this returns that wallet.
• Otherwise it falls back to the global alias alice, so existing global aliases keep resolving unchanged.

The same precedence drives the lockbox plugins: mail addressed to [email protected] seals to the domain-scoped wallet when one is registered.

Receiving mail at a domain-scoped address

Registering [email protected] and resolving it from a native client is only half of an email address; the other half is that internet mail addressed to it actually arrives. A verified domain’s user@domain addresses now do — a SithBit MX accepts an inbound RCPT TO:<[email protected]> and delivers it to the wallet the authority mapped. This is the delivery counterpart of native resolution: the same mapping that a client reads to seal mail is now the one the server reads to receive it.

Resolution runs on the same precedence as alias get above, but starting from the SMTP envelope rather than a CLI argument:

1. The MX takes the recipient’s domain from the RCPT address and lowercases it, so it matches the on-chain PDA seed exactly (the domain-scoped account is hashed on the domain and the local part).
2. It asks the chain gateway to resolve the local part within that domain — the domain-scoped DomainAlias lookup.
3. If a mapping exists, delivery targets that wallet’s mailbox. If none does, resolution falls back to the global alias namespace, exactly as alias get does — so a bare alice global alias still receives, and an empty domain is the legacy global path. Nothing about pre-existing global-alias delivery changes.

Because the authority alone writes these mappings, it decides which wallet receives mail for each local-part it issues — the same trust already placed in it for relayed mail, now reaching inbound delivery as well as resolution.

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/[email protected]

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, a global alias, or a domain-scoped user@domain — and it resolves that identity to a wallet (composing the same domain-then-global precedence as resolving a domain-scoped address 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.

See Closing accounts for the general rent-refund model that remove-domain follows.

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 transaction packet, 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 -k 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

Related

• Domains — what a sale conveys, and what it doesn’t.
• Transfer a domain — the delegate-signed administrative hand-over, and what an authority swap does (and doesn’t) change.
• Economics — the exact money flow: who pays, who collects, and when.
• List an alias for sale — the same marketplace for aliases.
• Deactivate a domain — the timelock that blocks a listing.

Deactivate a domain

See Domains for why deactivation is timelocked and what a pending deactivation means. This page covers the sithbit domain deactivate command’s four modes: request, --finalize, --cancel, and --false (reactivate).

sithbit domain deactivate <domain> \
  [--finalize] \
  [--cancel] \
  [--false] \
  [--keypair <delegate keypair>] \
  [--skip-preflight]

Arguments

• <domain> (required) — the domain to act on.
• --finalize (optional) — flips the domain inactive once the timelock has elapsed since the request. Run before the timelock has elapsed, it is rejected on-chain. Mutually exclusive with --cancel.
• --cancel (optional) — aborts an in-flight deactivation request before it finalizes, leaving the domain active as if the request had never happened. Mutually exclusive with --finalize.
• --false (optional) — reactivates the domain. This is the one instant mode of the command; it is not subject to the timelock.
• --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. Defaults to your configured default keypair when omitted.
• --skip-preflight (optional) — submits the transaction without a local simulation pass first.

With none of --finalize, --cancel, or --false 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 domain remains active — mail keeps flowing — until the request is finalized; its presence is what marks the domain as having a pending deactivation.

The timelock duration

The wait between a deactivation request and the earliest it can be finalized is a fixed 7 days. There is no flag to shorten or extend it.

Examples

Request deactivation of a domain:

sithbit domain deactivate badactor_domain.com

Finalize a request once at least 7 days have passed:

sithbit domain deactivate --finalize badactor_domain.com

Cancel a pending request, refunding the transient PDA’s rent to the delegate and leaving the domain active:

sithbit domain deactivate --cancel badactor_domain.com

Reactivate a domain immediately, with no waiting period:

sithbit domain deactivate --false recovered_domain.com

Errors

• NotDelegate (error 66) — the signing --keypair isn’t the postoffice’s recorded standing delegate. All four modes are delegate-only.
• Finalizing before the 7-day timelock has elapsed is rejected on-chain.
• --finalize and --cancel cannot be combined.

Note: when a domain is retired for good rather than temporarily suspended, see Closing accounts for domain close instead.

Sending mail

For the concept behind sending mail — the split on-chain/off-chain model, what SendMail records, and how postage gates a send — see Sending mail. This page is the full command reference: syntax, flags, preconditions, and examples.

sithbit mail send <to> \
  [--from <address>] \
  (--cid <cid> | --path <file>) \
  [--keypair <keypair>] \
  [--skip-preflight] \
  [--bounty <lamports>] [--bounty-window <seconds>] [--reply-to <address>]

Arguments and options

• <to> — the recipient, as an alias, wallet address, or keypair path. Required. The recipient must already have a mailbox; the message account is a PDA seeded on that wallet and the next message id.
• --from <address> (short -f) — the From: address, which selects which frombox is charged. Defaults to the sending keypair’s own address.
• --cid <cid> (short -c) — the IPFS CID of a body that is already pinned somewhere. You supply the known CID directly.
• --path <file> (short -p) — a local file whose CID is computed from its bytes. Exactly one of --cid or --path is required, and they are mutually exclusive.
• --keypair <keypair> (short -k) — the sender’s signing keypair. Defaults to the Solana CLI’s configured wallet (~/.config/solana/cli/config.yml). This wallet pays the stamp and signs the transaction.
• --skip-preflight (short -s) — submit without the RPC pre-flight simulation. Off by default; see the appendix for when skipping helps and what it costs.
• --bounty <lamports> — escrows a reply bounty on the message; see Reply bounties for how claiming and refunding work. Omit for a plain send.
• --bounty-window <seconds> — how long the recipient has to reply and claim; only meaningful with --bounty. See Reply bounties.
• --reply-to <address> — links this send as a reply to an earlier message (the bountied message’s account address), making it eligible to claim that message’s bounty. See Reply bounties.

Important: --path only computes the local file’s IPFS content identifier (CID) from its bytes — it does not upload or pin the content anywhere. Before the recipient can actually fetch and decrypt the message, the file must be separately pinned to IPFS (for example, through the embedded node in your own sithbitd, or a shared sithbit-ipfsd). --cid is for content that’s already pinned somewhere — you supply its known CID directly instead of a local file.

Examples

Send a locally-prepared .eml file, computing its CID on the way:

sithbit mail send [email protected] \
  --from [email protected] \
  --path ./message.eml

Send a body you have already pinned, referencing it by CID:

sithbit mail send [email protected] \
  --cid bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

On success the command prints the assigned message id, the CID, and the From/To pair, followed by the transaction URL:

Sent message #7 bafybei… <From:[email protected] To:[email protected]>
https://explorer.solana.com/tx/…

Before you send

Two preconditions must hold or the transaction is rejected on-chain:

• The frombox must exist and hold at least one stamp. The <from> → <to> frombox is charged one stamp per send (see Add stamps for what a stamp is worth and how to top one up). A missing or empty frombox fails the send; new/unknown fromboxes also inherit a deliberately high default price to price out spam.
• The recipient must have a mailbox. The message account seeds on the recipient wallet, and its id is the mailbox’s current message count plus one — so the mailbox must exist for the id to be assigned.
• The recipient must not have opted out of IPFS. If the recipient’s mailbox has the no_ipfs opt-out set, mail send refuses before touching the CID: this command pins the body client-side with no operator store behind it, so it cannot honor the opt-out the way SMTP delivery does. Deliver through an ordinary mail client (SMTP) instead, and the recipient’s operator stores the copy privately.

What reaches the chain

Neither address string reaches the chain: the instruction carries only blake3 hash of the normalized --from address (the frombox seed), and the recipient is identified by the wallet the message account’s PDA seeds on. The readable From:/To: headers travel solely inside the sealed body — see the threat model for exactly what an observer can and cannot learn.

Related

• Getting mail — the receive side; fetch and decrypt what was sent here.
• Pinning mail — keep a body retrievable on infrastructure you control.
• Delete mail — settle a delivered message’s postage once it has been read.
• Reply bounties — attach an escrowed reward to a send and claim it on reply.

Getting mail

For the concept behind reading mail — how mail get reads the on-chain envelope and fetches the sealed body from IPFS — see Reading mail. This page is the full command reference: syntax, flags, the on-chain listing format, decrypting a fetched body, and examples.

sithbit mail get [to_address] \
  [--message-id <id>]... \
  [--range] \
  [--directory <path>] \
  [--keypair <path>] \
  [--delegated-key-path <path>] \
  [--gateway <url>]

Arguments and options

• [to_address] — the mailbox to read, as an alias, wallet address, or keypair path. Defaults to your own configured address.
• --message-id <id> (short -m), repeatable — fetch these specific message ids. Ids past the mailbox’s latest are silently dropped. With none given, only the latest message is fetched.
• --range (short -r) — treat the given ids (or all known ids, if none are given) as an inclusive span and fetch every message in it. With a single id and --range, the span runs from that id to the latest.
• --directory <path> (short -d) — write each fetched body to <cid>.eml under this directory instead of only listing it. The directory is created if it does not exist.
• --keypair <path> (short -k) — a Solana wallet keypair file used to decrypt sealed bodies (the default path: your own configured wallet).
• --delegated-key-path <path> (short -x) — a delegated X25519 secret key file, for mail sealed to a delegated key instead of your wallet directly.
• --gateway <url> (short -g) — the IPFS gateway body-fetches go through. Defaults to https://ipfs.sithbit.com/ipfs/; point it at your own node or a sithbit-gateway to avoid a third party.

Note: the decryption flags (--keypair, --delegated-key-path) require the CLI’s rand feature (enabled by default). Without any key flag, a fetched body is written as-retrieved — still sealed.

The on-chain listing

Every message the command finds is printed from its message account before any body is fetched:

-
Email #7: 9xQ…PDA
Date: 2026-07-08 14:02:11
From-hash: 3n7…
Sender: John…
cid: bafybei…

The chain stores only the blake3 hash of the from address (From-hash:), never the string; Sender: is the wallet that paid the postage. The readable From:/Subject: headers live inside the sealed body and appear only once it is fetched and decrypted. A message id that has been deleted prints DELETED (…) in place of its listing and is skipped, never fatal.

A message whose recipient opted out of IPFS carries a local-only marker (b3:…) rather than a fetchable CID. mail get recognizes the marker and skips the gateway fetch, reporting that the body is not on public IPFS and lives only in the operator’s store — read it through the operator’s IMAP/POP service instead.

A message carrying a reply bounty or reply linkage appends one line per set field; a plain send prints exactly the four lines above:

-
Email #8: 4vN…PDA
Date: 2026-07-09 09:15:40
From-hash: 3n7…
Sender: John…
cid: bafybei…
Reply-to-hash: Ckt…
Bounty: 5000000 lamports
Bounty-expires: 2026-07-16 09:15:40

Reply-to-hash: is the blake3 hash of the message account this one replies to, Bounty: the escrowed lamports, and Bounty-expires: the claim deadline — see Reply bounties for how they are attached and settled.

Examples

List the latest message in your own mailbox:

sithbit mail get

Fetch and decrypt messages 3 and 5 of another mailbox into a directory, using your wallet key:

sithbit mail get [email protected] \
  --message-id 3 --message-id 5 \
  --directory ./inbox \
  --keypair ~/.config/solana/id.json

Fetch everything from message 1 onward as a range, through your own gateway:

sithbit mail get \
  --message-id 1 --range \
  --gateway http://127.0.0.1:8080/ipfs/ \
  --directory ./inbox

Decrypting separately

If you already have a fetched .eml file (or one saved without a key flag) and want to decrypt it as a standalone step, use sithbit mail decrypt:

sithbit mail decrypt ./inbox/bafybei….eml \
  --keypair ~/.config/solana/id.json

It takes the same key flags (--keypair, --delegated-key-path), and with --directory writes the plaintext beside the input name; with none it prints the decrypted message to stdout.

Related

• Sending mail — the write side that creates these message accounts.
• Pinning mail — re-pin fetched bodies to storage you control so they stay retrievable.
• Mailbox keys — how sealed-to-wallet vs. delegated-key mail is addressed.

Pinning mail

For the concept behind pinning — why a message body’s availability depends on an operator, and how re-pinning to a provider you control fixes that — see Pinning to IPFS. This page is the full command reference: provider choices, message selection, keeping mail pinned continuously, the verify guarantee, and examples.

sithbit mail pin [to_address] \
  [--message-id <id>]... \
  [--range] \
  [--gateway <url>] \
  --provider (pinata | filebase | remote) \
  [provider credential flags] \
  [--watch <seconds>]

to_address defaults to your own address; give an alias, wallet address, or keypair path to pin someone else’s mailbox instead (you still need the provider credentials, since the pin lands on your provider).

Re-pinning puts a copy on infrastructure you run. To instead pay the recipient’s operator to keep their pin past the default retention window, see pinning leases — the two compose.

Choosing messages

Message selection mirrors sithbit mail get exactly:

• No --message-id — pins the latest message only.
• --message-id <id> (short -m), repeatable — pins those specific ids.
• --range (short -r) — treats the given ids (or all known ids, if none are given) as an inclusive range and pins every message in the span.

A message that has been deleted or is otherwise unavailable is reported and skipped, never fatal — the rest of the batch still pins. A message whose recipient opted out of IPFS carries a local-only marker (b3:…) instead of a fetchable CID: there is nothing on a gateway to fetch, hash-verify, or re-pin, so mail pin reports it and skips it rather than failing on a gateway 404.

Choosing a provider

--provider selects where the verified bytes are stored. Because the pin lands on infrastructure the recipient controls, the credentials are passed as flags rather than read from a config file.

remote (the default)

A self-hosted sithbit-ipfsd daemon spoken to over HTTP. This is the minimal path: with no flags at all, --provider remote targets a loopback daemon and needs no credentials, so mail pin works out of the box against a node you run yourself.

• --remote-endpoint <url> — daemon endpoint (default http://127.0.0.1:8182).
• --remote-token <token> — bearer token, only if the daemon requires one.

pinata

Pinata’s hosted pinning API, authenticated with a bearer JWT.

• --pinata-jwt <jwt> — Pinata bearer JWT (required).
• --pinata-gateway <url> — gateway base URL for provider-side fetches (default https://gateway.pinata.cloud).

filebase

Filebase’s S3-compatible IPFS pinning endpoint.

• --filebase-access-key <key> — S3 access key (required).
• --filebase-secret-key <key> — S3 secret key (required).
• --filebase-bucket <bucket> — target bucket (required).
• --filebase-endpoint <url> — S3 endpoint (default https://s3.filebase.com).

Keeping mail pinned: --watch

By default mail pin runs a single pass and exits. Pass --watch <seconds> to keep it running: after the first pass it re-enumerates the mailbox and re-pins it every N seconds, so newly-arrived messages stay pinned without a manual re-run. Each tick prints a one-line summary of how many bodies were pinned and how many errored; a transient failure (an RPC blip, say) is reported and the loop continues.

Examples

Pin your latest message to a loopback sithbit-ipfsd — the zero-config path:

sithbit mail pin

Pin messages 1 through 10 of your own mailbox to Pinata:

sithbit mail pin \
  --message-id 1 --message-id 10 --range \
  --provider pinata \
  --pinata-jwt "$PINATA_JWT"

Continuously mirror an entire mailbox to Filebase, re-checking every five minutes:

sithbit mail pin \
  --range \
  --provider filebase \
  --filebase-access-key "$FILEBASE_KEY" \
  --filebase-secret-key "$FILEBASE_SECRET" \
  --filebase-bucket my-sithbit-mail \
  --watch 300

The verify guarantee

Before anything is pinned, the fetched bytes are hashed and compared against the CID recorded on-chain for that message. Only bytes that hash to the expected CID are pinned; a mismatch is refused. A gateway that serves corrupted or substituted content therefore cannot get bad data into your provider — the worst it can do is fail to serve the body, in which case that message is skipped.

Pinning leases

sithbit mail pin keeps a message body available by re-pinning it to infrastructure you run. A pinning lease solves the same problem from the other side: it pays the recipient’s operator to keep their pin past the default retention window — the auto-settle sweeper normally releases a delivered copy’s pin about 30 days after delivery, and a live lease tells it not to.

A lease is a small on-chain account keyed on the message’s CID and your wallet. It escrows a reclaimable deposit (at least 0.01 SOL) and charges a one-time creation fee (default 0.001 SOL, split between the recipient’s mail operator and the postoffice). There is no expiry and no renewal: the pin stays protected exactly as long as the lease account exists, and closing it returns the deposit and the account rent in full. The fee is the only money spent.

sithbit mail lease create [to_address] [--message-id <id>] [--deposit <lamports>]
sithbit mail lease show   [to_address] [--message-id <id> | --cid <cid>] [--holder <address>]
sithbit mail lease close  [to_address] [--message-id <id> | --cid <cid>]

to_address defaults to your own address — leasing a message in your own mailbox — but any wallet may lease any message’s CID: a sender who wants their attachment to outlive the recipient’s retention window can lease it too. One lease exists per (CID, holder) pair, so your lease never collides with anyone else’s on the same message.

Creating a lease

sithbit mail lease create --message-id 3
sithbit mail lease create --message-id 3 --deposit 20000000

• --message-id (short -m) defaults to the latest message, matching mail pin.
• --deposit (short -d) defaults to the protocol minimum (PIN_LEASE_MIN_DEPOSIT_LAMPORTS, 0.01 SOL). The deposit rides on the lease account and comes back in full at close — the floor keeps a lease from being a near-free way to demand indefinite operator storage.
• The command quotes the current creation fee before sending (also readable anytime with sithbit postoffice fee pin-lease).

The lease must be created while the message account still exists on-chain — the program reads the CID off the message itself and verifies it cryptographically (the lease address derives from the CID’s hash, so a wrong CID simply cannot create the account). A message whose recipient opted out of IPFS carries a b3: local-only marker instead of a CID; there is no pinned body to retain, so leasing it is refused.

What the lease guarantees — and what it doesn’t

Operators running the stock sithbitd consult the chain before releasing a pin at settlement: a copy whose CID carries any live lease keeps its pin, and an operator that cannot prove the CID unleased (chain unreachable) keeps the pin too and retries later — the check fails safe. Settlement itself still happens: the recipient’s stamp value is still reclaimed on schedule; only the storage outlives it.

Two honest limits:

• A lease is an instruction to cooperating software, not a physical guarantee — an operator running modified software can drop any pin. For bodies you must keep regardless of the operator, mail pin to your own provider remains the trustless option (and composes with a lease).
• Closing a lease does not retroactively unpin a copy that already settled under it — the operator reclaims that storage through its own garbage collection, on its own schedule.

Inspecting and closing

sithbit mail lease show --cid QmTestCid
sithbit mail lease close --cid QmTestCid

show prints the holder, creation time, and escrowed deposit. close drains the account — deposit plus rent — back to the holder’s wallet; only the holder’s own signature can reach their lease (the account address derives from the holder, so there is nothing a stranger can even name). Both accept --message-id while the message record still exists; after the message settles and its on-chain record deallocates, pass --cid — the lease outlives the message on purpose.

The fee, for postmasters

The creation fee is a postoffice tunable with the standard shape: read it with sithbit postoffice fee pin-lease, tune it with sithbit postmaster fee pin-lease <LAMPORTS> (delegate-signed, capped at 10× the default; zero resets to the default rather than disabling the fee). Like every purchase-side fee it splits with the recipient’s registered domain authority at the tuned operator share — see the economics page.

Deleting mail

For the concept behind deleting mail — why deletion is the settlement trigger for a message’s prepaid postage — see Deleting mail. This page is the full command reference: syntax, flags, who may delete, the exact settlement order, examples, and delete vs. refund.

sithbit mail delete <message_id> \
  [to_address] \
  [--keypair <keypair>] \
  [--skip-preflight]

• <message_id> — the numeric id of the message to delete (the same id shown by sithbit mail get). Required.
• to_address — the recipient whose mailbox the message belongs to. Defaults to your own address; pass an alias, wallet address, or keypair path to name someone else’s mailbox (the message PDA is seeded on the recipient, so this selects which message #<id> is meant).
• --keypair <keypair> (short -k) — the signing keypair, defaulting to the CLI’s configured wallet.
• --skip-preflight (short -s) — skip the RPC pre-flight simulation and submit the transaction directly.

Who may delete

Either party to the message may delete it: the on-chain program requires the signer to be either the sender or the recipient of the message, and rejects anyone else. In normal operation it is the recipient (or the MX server acting on their behalf) who deletes, because deletion is what pays the postage into the recipient’s wallet.

Example

sithbit mail delete 3

deletes message #3 from your own mailbox and prints the resolved sender plus the settling transaction:

Found sender address 7Xh…q4M
Deleted message #3 for 9aF…2kD
https://explorer.solana.com/tx/5Jm…8sT

To delete a message in someone else’s mailbox (for instance an operator settling on a user’s behalf), name the recipient:

sithbit mail delete 3 [email protected] --keypair operator.json

What happens on-chain

The command builds a DeleteMail instruction carrying nine accounts: the signing payer, the message’s sender and recipient, the system program, the message account itself, and the recipient’s settlement accounts (their mailbox, its domain, that domain’s authority, and the postoffice). The program then drains the message account’s whole balance and closes it, in this order:

1. Sender refund. The sender recovers the message account’s rent plus the fee for their original SendMail signature (both were prefunded by the stamp surcharge the sender paid at purchase).
2. Deleter refund. The signer submitting this delete recovers this transaction’s signature fee — also prefunded — so settling costs the deleter nothing net.
3. Operator share. If the recipient’s mailbox names an active domain, that domain’s authority (the MX operator) collects 10% of the remaining postage. The share lapses to zero when the chain legitimately doesn’t resolve — no mailbox, no domain set, or the domain is closed or inactive — but a named, active domain must be presented with the correct authority account or the instruction is rejected, so a deleter can’t cheat the operator out of its cut with filler accounts.
4. Recipient postage. The recipient collects everything left, rounded down to the protocol’s settlement quantum (1000 lamports). This is the actual pay-for-attention the postage model exists to deliver.
5. Rounding residue. The sub-quantum remainder accrues to the postoffice (the postmaster’s operating revenue at scale).

Once the balance reaches zero the message account is reaped — the id is gone and a later get for it returns nothing. See Economics for the full postage/settlement model and the exact split.

Delete vs. refund. Deletion settles postage to the recipient. There is a sibling command, sithbit mail refund <message_id>, for the opposite outcome: the recipient (and only the recipient) refuses the mail and returns the postage to the sender instead of keeping it. Refund reuses the same nine-account shape and likewise reaps the message account and refunds the prepaid fees, but pays no postage to the recipient and no operator share. Use delete to accept and settle; use refund to reject.

Reply bounties

For the concept behind reply bounties — why they exist and how the escrow rides the message account — see Reply bounties. This page is the full command reference: attaching a bounty, linking a reply, claiming, and reclaiming an unanswered bounty.

sithbit mail send <to> … --bounty <lamports> [--bounty-window <seconds>]
sithbit mail send <to> … --reply-to <message account address>
sithbit mail claim-bounty <message_id> <reply_message_id> <SENDER_ADDRESS>
sithbit mail refund-bounty <message_id> <RECIPIENT_ADDRESS>

End users normally never type these: a mail client sending through a sithbitd daemon gets the reply linkage for free (see Replying to a bountied message). The commands are the low-level primitives, exactly as mail send is for delivery.

Attaching a bounty

Two extra flags on sithbit mail send:

• --bounty <lamports> — the amount to escrow on the message account. 0 (the default) is a plain send, byte-identical to a send without the flag.
• --bounty-window <seconds> — how long the recipient has to reply and claim, counted from now. Defaults to 7 days (604 800 seconds); only meaningful together with --bounty. The window must end in the future — a bounty that would be born expired is rejected on-chain.

sithbit mail send [email protected] \
  --path ./question.eml \
  --bounty 5000007

The sender fronts the bounty at send time, on top of the message rent: the message account is created holding rent + postage + bounty. Note the send’s output — Sent message #7 … — because that message id is what a later refund-bounty needs.

The trustless webmail compose authors the same two fields client-side — a SOL amount and a claim window in days behind its Attach a reply bounty control, with the same 7-day default — and its reader’s Reply on-chain action carries the --reply-to linkage automatically. Bounty authoring is a direct-signed surface: the CLI and the trustless compose write it; sends composed through a mail server stay bounty-less.

Replying to a bountied message

To make a reply claimable, the reply’s send must carry an on-chain link back to the bountied message:

sithbit mail send [email protected] \
  --path ./answer.eml \
  --reply-to <message account address>

• --reply-to takes the bountied message’s account address — the base58 address sithbit mail get prints next to each id (Email #7: <address>), not the numeric id.
• The linkage is privacy-preserving: what reaches the chain is only the blake3 hash of that account address — no sender or recipient address appears, consistent with what a plain send reveals.
• --reply-to works without a bounty too, if you want the threading link on-chain for its own sake.

Through a mail server, this is automatic. When the reply travels through a sithbitd daemon (the normal path for anyone using an ordinary mail client), the spooler resolves the reply’s In-Reply-To header to the original message’s chain coordinates and sets the linkage itself — just reply in your mail client and the claim evidence takes care of itself.

Claiming the bounty

Once the reply is on-chain, the recipient of the bountied message collects:

sithbit mail claim-bounty <message_id> <reply_message_id> <SENDER_ADDRESS> \
  [--keypair <keypair>] \
  [--skip-preflight]

• <message_id> — the bountied message’s id in your own mailbox.
• <reply_message_id> — your reply’s id in the original sender’s mailbox (a reply is itself a message, delivered to them).
• <SENDER_ADDRESS> — the original sender’s wallet address (or keypair path); their mailbox is where the reply lives.
• --keypair (short -k) — the claimant’s signing keypair; only the bountied message’s recipient may claim.

sithbit mail claim-bounty 7 12 7Xh…q4M
Claimed the bounty on message #7 with reply #12 from 7Xh…q4M
https://explorer.solana.com/tx/…

The claim pays out 90/10: for a 5 000 007-lamport bounty, 4 500 007 lamports go to you, and the 500 000 operator share goes to your domain’s authority (the operator running your mail host) — or to the postoffice, if your mailbox doesn’t name an active domain — see Economics for the exact split rules. A claim is legal through the exact expiry instant; at the deadline itself, the claim still wins.

Reclaiming an unanswered bounty

If the window closes with no claim, the sender takes the bounty back:

sithbit mail refund-bounty <message_id> <RECIPIENT_ADDRESS> \
  [--keypair <keypair>] \
  [--skip-preflight]

• <message_id> — the bountied message’s id in the recipient’s mailbox (the id mail send printed).
• <RECIPIENT_ADDRESS> — the recipient’s wallet address (or keypair path), which the message account is derived from.
• --keypair (short -k) — the sender’s signing keypair; only the original sender may reclaim.

sithbit mail refund-bounty 7 9aF…2kD
Refunded the expired bounty on message #7 to 9aF…2kD
https://explorer.solana.com/tx/…

The refund is strictly after expiry — one second past the deadline, not at it — and returns the bounty in full: unlike a claim, a refund pays no share to anyone. The message itself survives; only the bounty moves.

What deleting the message does

Deleting a message with a still-riding bounty returns the bounty to the sender, folded into the sender-refund leg of the normal settlement. No reply, no payout: an unclaimed bounty is the sender’s money and never converts into recipient postage. This holds for the auto-settle worker’s deletes too — a recipient who ignores a bountied message until the settle window sweeps it earns the postage but not the bounty.

What you can and can’t trust

• The escrow is the message account. The bounty sits on the same on-chain account as the message’s rent and postage from the moment of the send — there is no third party holding it and no separate account to audit.
• Only a real reply claims. The claim must present a message that (a) sits in the original sender’s mailbox, (b) was sent by the claimant, and (c) names the bountied message via the on-chain reply linkage. A routine unrelated message from the recipient satisfies (a) and (b) but not (c) — it cannot claim.
• One payout, ever. Claiming zeroes the bounty on the message account, so the same reply — or any other — cannot claim twice, and a claimed bounty cannot also be refunded (and vice versa).
• The deadline is exact. Claims win up to and including expires_at; refunds open strictly after it. The two windows cannot overlap.

Related

• Sending mail — the send primitive these flags extend.
• Getting mail — where to read a message’s id and account address.
• Deleting mail — settlement, and the delete path a riding bounty takes.
• Economics — the exact money flow: who pays, who collects, and when.

The sithbit campaign CLI (participant beacons & campaigns)

The sithbit campaign command tree is the chain-direct authoring surface for the participant-pool marketplace: a wallet publishes an on-chain participant beacon advertising the tags it is willing to be reached on, and a campaign wallet discovers those participants by tag, prices a bountied send to the matched set, and sends it.

Two roles use this tree:

• A participant runs create, update and close to opt in, edit and opt out. Opting in is setting a mailbox price: the advertised participation price is the wallet’s mailbox default_postage, so a beacon can only be published for a wallet that already has a mailbox.
• A campaign wallet runs search, quote and send to reach the pool. send is direct-signed only — the funded campaign wallet signs every delivery locally; there is no mail-server path for a campaign.

sithbit campaign create  [--tag <TAG>]… [--detail-cid <CID> | --profile-file <PATH>] [-k <KEY>]
sithbit campaign update  [--tag <TAG>]… [--detail-cid <CID> | --profile-file <PATH>] [-k <KEY>]
sithbit campaign close   [-k <KEY>]
sithbit campaign search  --tag <TAG>… [--limit <N>]
sithbit campaign quote   --tag <TAG>… --bounty <LAMPORTS> [--postage <LAMPORTS>] [--limit <N>]
sithbit campaign send    --tag <TAG>… --subject <TEXT> --bounty <LAMPORTS> \
                         [--body-file <PATH>] [--limit <N>] [-y] [-k <KEY>]

Tags

Every beacon carries a fixed-vocabulary tag bitmap. A --tag is one name from that vocabulary — an interest.*, skill.*, age.* or region.* name, e.g. interest.technology, skill.software, age.25_34, region.apac. Names are case-insensitive; an unknown name is rejected with the full valid list. --tag is repeatable, and search/quote/send treat multiple tags as a logical AND — a beacon must carry every requested tag to match. The vocabulary is derived from the mail_model TAG_* constants; see the participant-marketplace note for the bitmap layout.

sithbit campaign create

Publishes the signing wallet’s participant beacon, opting it in on the given tags. The wallet’s mailbox must already exist — the advertised price is its default_postage.

sithbit campaign create \
  --tag interest.technology \
  --tag skill.software \
  --tag region.apac

Flags:

• --tag <TAG> — a tag to advertise on (repeatable).
• --detail-cid <CID> — attach an existing IPFS CID as the beacon’s off-chain detail profile. Mutually exclusive with --profile-file.
• --profile-file <PATH> — seal a local profile file under a fresh key, pin it to IPFS, and attach the resulting CID. Needs the CLI’s rand feature. See --ipfs-endpoint / --ipfs-token below.
• --ipfs-endpoint <URL> — the sithbit-ipfsd endpoint a --profile-file is pinned to (default http://127.0.0.1:8182).
• --ipfs-token <TOKEN> — bearer token for that daemon, when it requires one.
• -k, --keypair <KEY_PATH> — the wallet publishing the beacon (defaults to the Solana CLI keypair).
• -s, --skip-preflight — skip the transaction pre-flight simulation.

sithbit campaign update

Rewrites the beacon wholesale: the given tags and detail CID replace its current contents in full — this is a replace, not a merge, so omitting --tag clears all tags and omitting a CID clears the attached profile.

sithbit campaign update --tag interest.finance --tag region.emea

Takes the same flags as create.

sithbit campaign close

Closes the signing wallet’s beacon — the opt-out. It drops out of every tag search and its rent is refunded to the wallet.

sithbit campaign close

Flags: -k, --keypair <KEY_PATH>, -s, --skip-preflight.

sithbit campaign search

Runs a trustless getProgramAccounts scan of the mail program for beacons carrying every requested tag, and lists each match’s sendable wallet, its tag names, and whether it advertises a detail profile. The wallet is recovered from the beacon’s on-chain owner field (a beacon PDA can’t be inverted to it), so the results are directly mailable.

sithbit campaign search --tag interest.technology --tag skill.software

2 matching participant beacon(s):
  mAiLiLdgjgGdWoCZkpW3cj7JLAC56qb4NErFyQFWNJg  [interest.technology, skill.software]  detail: yes
  CaMUbt4zNKeZb2AUaa4icv33CQEvBeJ8EsWKFsDvKWrT  [interest.technology, skill.software, region.apac]  detail: no

Flags:

• --tag <TAG> — a tag a beacon must carry to match (repeatable, required, logical AND).
• --limit <N> — cap the number of matches returned (default 100). The newest beacons are kept first.

sithbit campaign quote

Prices a campaign before committing funds. It counts the beacons matching the tag filter (the same trustless scan search runs) and multiplies by the per-recipient cost, itemized so you see where the money goes. The per-recipient figure mirrors the on-chain SendMail funding term for term: the message account rent, a new frombox’s rent, the prepaid postage, the escrowed bounty, one signature fee, and the per-stamp settlement surcharge.

sithbit campaign quote --tag interest.gaming --bounty 1000000

Campaign quote for 3 recipient(s):
  message rent              1670160 lamports
  frombox rent              1224960 lamports
  postage                1000000000 lamports
  bounty                    1000000 lamports
  signature fee                5000 lamports
  stamp surcharge             10000 lamports
  per recipient          1003915120 lamports
  total                  3011745360 lamports (3.01174536 SOL)

Flags:

• --tag <TAG> — recipient tag filter (repeatable, required, logical AND).
• --bounty <LAMPORTS> — the per-recipient bounty being offered.
• --postage <LAMPORTS> — the per-recipient postage the quote assumes; defaults to the protocol default a mailbox charges unknown senders. Lower it toward the price you expect recipients’ fromboxes to actually charge.
• --limit <N> — cap the quote at this many recipients (default: the full match set).

sithbit campaign send

Sends one bountied message to every recipient matching the tag filter. It selects recipients by the same trustless scan, prints the quote, gates on a confirmation (unless -y), then delivers the batch — one direct-signed SendMail per recipient, each escrowing the per-recipient reply bounty with the campaign message as the parent a recipient replies to. The loop continues past a per-recipient failure so one bad address can’t strand the rest of a paid campaign, and prints a sent/failed summary at the end.

sithbit campaign send \
  --tag interest.gaming \
  --subject 'Paid gaming survey' \
  --bounty 1000000 \
  --body-file ./invite.txt \
  --yes

Campaign quote for 3 recipient(s):
  …
  sent to mAiLiLdgjgGdWoCZkpW3cj7JLAC56qb4NErFyQFWNJg  https://explorer.solana.com/tx/…
  sent to CaMUbt4zNKeZb2AUaa4icv33CQEvBeJ8EsWKFsDvKWrT  https://explorer.solana.com/tx/…
  sent to maiLtdkxym8CCmo9TwDuXywqd9DXaK3tB6toKFVeBFR  https://explorer.solana.com/tx/…
Campaign complete: 3 sent, 0 failed.

Flags:

• --tag <TAG> — recipient tag filter (repeatable, required, logical AND).
• --subject <TEXT> — the message subject line.
• --body-file <PATH> — the message body; read from stdin when omitted.
• --bounty <LAMPORTS> — the per-recipient bounty escrowed for each recipient to claim. The claim window is the standard 7-day bounty default.
• --limit <N> — cap the send at this many recipients (default: the full match set).
• -y, --yes — skip the quote-then-confirm prompt and send immediately.
• -k, --keypair <KEY_PATH> — the sending (and funding) wallet.
• -s, --skip-preflight — skip the transaction pre-flight simulation.

Recipients collect a bounty by replying before the window closes; anything unclaimed can be refunded to the campaign wallet after it expires.

Revenue snapshot: sithbit earnings

sithbit earnings \
  [--owner <PUBKEY>] \
  [--from <ADDRESS>]...

A read-only holdings and revenue snapshot for one wallet — the bookend to sithbit setup: setup gets a brand-new user configured, earnings shows an existing recipient what their wallet holds and has taken in, and it only ever reads. It prints, in order:

• Wallet balance — the wallet’s native SOL balance.
• Mailbox asking price — this wallet’s default postage (the price a new sender pays), or a note that the wallet has no mailbox yet.
• Postoffice balance (delegate) — the singleton postoffice balance. This line appears only when the queried wallet is the postoffice’s standing delegate, and is omitted entirely for everyone else.
• Prepaid stamps — for each sender named with --from, the prepaid stamps that sender holds against this wallet plus the lamports held in that frombox, or none prepaid when no frombox exists for that pair.

Arguments

• --owner <PUBKEY> — the wallet to report on. Accepts a base58 pubkey or a keypair-file path; defaults to your configured signing keypair.
• --from <ADDRESS> — a sender address to report prepaid stamps for. Repeatable; each occurrence adds one Prepaid from … line.

--from is the only per-sender lookup — by design

earnings reads only the handful of accounts your wallet’s PDAs point at directly: its balance, its mailbox, the singleton postoffice, and the specific fromboxes you name. It deliberately does no chain-wide scan, so there is no wallet-wide enumeration of the senders who have prepaid you. To see a sender’s prepaid balance you must name that sender explicitly with --from — one flag per sender. Passing no --from prints a one-line hint instead of a per-sender list.

USD figures are best-effort

Every SOL figure is annotated with an approximate USD value (e.g. 1.5 SOL (~$210.00)) when a live SOL→USD rate is available. The rate fetch is fail-soft: any hiccup — no network, a slow or erroring price API — simply drops the dollar annotations and prints the bare SOL amounts. A pricing outage never blocks or fails the report.

The same best-effort SOL→USD annotation rides sithbit frombox get automatically — the asking price and held balance gain dollar tails whenever a rate is available. On sithbit mailbox get it is opt-in: pass --usd to annotate the asking price; without the flag it prints bare lamports exactly as before. The fetch is fail-soft the same way — a pricing outage just drops the dollar tails.

Example

A recipient checking their own snapshot and one known sender’s prepaid stamps, with a live rate available:

$ sithbit earnings --from [email protected]
Earnings summary for 85FZrun1Eb5bdkbFCDjaFSTLnBfnx6sUFHa5BiYH2Q0
  Wallet balance: 1.5 SOL (~$210.00)
  Mailbox asking price: 0.5 SOL (~$70.00) per email
  Prepaid from [email protected]: 7 stamps (1 SOL (~$140.00) held)

The same wallet queried without --from, and with no rate available (note the missing dollar tails and the per-sender hint):

$ sithbit earnings
Earnings summary for 85FZrun1Eb5bdkbFCDjaFSTLnBfnx6sUFHa5BiYH2Q0
  Wallet balance: 1.5 SOL
  Mailbox asking price: 0.5 SOL per email
  Prepaid stamps: pass --from <address> to show a named sender's balance

A sender you name who has never prepaid you reports none prepaid rather than erroring — asking about an unknown sender is expected:

$ sithbit earnings --from [email protected]
...
  Prepaid from [email protected]: none prepaid

For the wider picture of how postage and prepaid stamps price out spam, see Economics.

Closing accounts

Every SithBit account is a Solana account, and creating any Solana account requires a one-time SOL deposit — rent-exemption — that scales with how many bytes the account stores. It isn’t a fee: it’s a refundable deposit that sits in the account for as long as it exists, and it has nothing to do with any price or value the account might represent (a mailbox’s rent, for example, is the same regardless of how much postage it charges). Closing an account you no longer need reclaims that rent back to you. See Solana’s account model docs for the full mechanics of how the minimum balance is calculated.

One row in that table is not a close at all: frombox reclaim leaves the account standing. It exists because a frombox holds two different people’s money — the rent, deposited by whoever opened it, and the prepaid postage, deposited by the sender. frombox close hands the whole balance to the recipient; frombox reclaim lets the sender take back only the postage it prepaid and never spent, leaving the account alive on its rent so the recipient keeps the price it set. See Reclaiming unspent stamps.

Closing a mailbox is timelocked

Every command in the table above reclaims its rent in one transaction — except mailbox close, which is a two-step, 7-day flow:

1. sithbit mailbox close requests the close. It stamps a small transient PDA with the chain time and starts the clock. The mailbox stays open and keeps receiving mail, and no rent comes back yet — the request in fact costs the owner the transient account’s own rent until the flow resolves.
2. sithbit mailbox close --finalize, run once at least 7 days have passed, actually closes the mailbox and refunds both rents — the mailbox’s and the transient account’s — to the owner.
3. sithbit mailbox close --cancel, run any time before finalize, aborts the request: the transient account’s rent comes back and the mailbox is untouched.

The delay exists because an instant refund made discarding a burned identity free, which is a spammer’s economics, not an honest owner’s. The owner pays in time on a rare action, never in money — the rent is returned in full. The retired one-step CloseMailbox instruction is refused on-chain with error 94, InstantCloseDisabled. See Close a mailbox.

mailbox key close is not timelocked and stays in the table above as an instant close: it revokes a compromised delegated encryption key, and a week-long window there would keep MX servers sealing to the compromised key — protecting the attacker rather than the owner.

Note: closing drains an account’s lamports to zero, at which point Solana’s runtime deallocates it — so a closed account’s address can generally be recreated later with the matching create command. The one caveat: recreating a mailbox restarts its message-id counter at zero, so any of its old, still-open message accounts (which persist independently of the mailbox itself, settled separately by mail delete) can collide with new sends until they’re cleared out. This is an availability nuisance, not a loss of funds — closing a mailbox that still has undelivered mail is worth avoiding rather than treating as harmless.

Running a mail server

A SithBit deployment is at most six services, all built from this workspace: