Program & PDA reference

This is a reference page — for behavior and pricing, see the topic pages and Economics. It’s here for readers who want to see exactly what’s on-chain.

Program IDs

The domain program carries the whole domain registry — domain lifecycle, DNSSEC-proof authorization/reclaim, and the domain marketplace — split out of the mail program (which originally hosted those instructions; see the retired discriminants below). The postoffice singleton stays a mail-program account: the alias and domain programs read it cross-program for the fees, the root KSK fingerprint, and the delegate gate.

PDA seeds

Mailbox and alias accounts don’t use a named seed constant — they derive directly from the owner’s wallet address (mailbox) or the alias name’s blake3 hash (alias); the participant beacon combines PARTICIPANT_BEACON_SEED with the owner’s wallet address, so each wallet carries at most one beacon and it can never collide with the bare-seeded mailbox. The sender-reputation account — the record behind reputation-scaled first-contact pricing — likewise combines SENDER_REPUTATION_SEED with the sender’s wallet address: one cumulative-spend record per wallet, owned by the mail program. The mailbox close timelock’s transient pending account combines PENDING_MAILBOX_CLOSE_SEED with that same wallet address, and the prefix is doubly load-bearing there: the Mailbox PDA is bare-seeded on the address, and PendingMailboxClose, PendingDeactivation and PendingReclaim all serialize to the same eight bytes — so a size-filtered account scan cannot tell the three apart and only the derivation can. The alias-transfer escrow and alias-listing accounts combine ALIAS_ESCROW_SEED / ALIAS_LISTING_SEED with that same blake3 alias hash; the domain-listing account combines DOMAIN_LISTING_SEED with the domain name’s blake3 hash, and the deactivation timelock’s transient pending-deactivation account likewise combines PENDING_DEACTIVATION_SEED with the domain hash. Seeding a listing on the asset itself means each alias or domain can carry at most one listing at a time, structurally. The verified-sender attestation combines SENDER_ATTESTATION_SEED with the domain’s blake3 hash and the attested wallet address — two variable seeds, so a domain carries one attestation per wallet, any number of wallets. Every domain-side account — MailDomain itself, the listing, the two timelock accounts, the proof-witness buffer, and the sender attestation — derives under and is owned by the domain program.

MailInstruction variants

Each variant is the on-chain instruction a sithbit command ultimately submits:

Retired mail-side domain discriminants

The sixteen domain-registry instructions originally lived in the mail program and moved wholesale to the domain program. Their variants stay in the MailInstruction enum — the borsh discriminant is wire ABI, so removing or reordering them would renumber every later instruction — but the mail program no longer carries their processors. Sending one of these discriminants to the mail program is rejected with error 84 (InstructionMoved, “This instruction has moved to the domain program”):

SetDomainFee (17) and SetRootKsk (25) are not in the retired set: despite their domain-flavored names they mutate the postoffice — a mail-program account — and stay mail-side.

DomainInstruction variants

The domain program’s enum, borsh discriminants 0–18. The CLI surface did not change with the split — the same sithbit domain commands now submit these to the domain program, with account-meta lists byte-identical to the retired mail-side twins (discriminants 17–18, the verified-sender attestation pair, postdate the split and never had mail-side twins):

Domain instructions authenticate against the mail program’s postoffice read cross-program: the delegate gate, the authorization fee, and the root KSK all come from that account, and fees still settle into it — the split moved the registry, not the treasury.

Postoffice admin gates

Since the delegation cutover the postoffice stores no postmaster pubkey — only the standing delegate wallet and a 32-byte ownership commitment root (see The Postmaster). The admin instructions — across all three programs — split accordingly:

• Delegate-gated (operational): every domain-program instruction including CreateDomain (the deactivation two-step, CloseDomain, TransferDomainAuthority, …), the mail-side fee setters (SetStampFee, SetDomainFee, SetAliasFee, SetAliasTierFees, SetSettlementBps, SetSenderAttestationFee, SetReputationFloor, SetPinLeaseFee — every postmaster fee command), SetRootKsk, the alias program’s fee-waived bulk reservation. A non-delegate signer is refused with code 66 (NotDelegate). The three AdminCloseAccount reclaim twins are delegate-gated too, with their own refusal code (AdminCloseUnauthorized) — and, on top of the authority check, a value guard: a target holding lamports above its rent-exempt minimum is refused with code 106 (AdminCloseEscrowPresent), so the tool reaps only rent-empty leftover state and can never seize escrowed postage, a bounty, or a live bid.
• Ownership-gated (chain-key proof): InstallCommitment, WithdrawPostoffice, and RotateDelegate. The signer is a revealed ceremony chain key presenting a Merkle membership path against the current commitment root, and the instruction installs the successor generation’s root (rotate-on-use). A proof that does not verify is refused with code 67 (InvalidCommitmentProof).

One naming footnote for error readers: the account-slot error PostmasterAccountInfo (code 9) now labels the delegate/chain-signer account slot — the variant name is kept for ABI stability (the enum’s numeric position is the on-chain error code, so variants are never renamed in place).

AliasInstruction variants

Marketplace listing accounts

An open marketplace listing is staged in a program-owned account — AliasListing (alias program) or DomainListing (domain program) — created by ListAlias/ListDomain and closed when the listing completes. Both share one fixed 56-byte borsh layout, so a listing’s rent is a constant and replacing a listing in place never changes it:

Six pre-existing instructions grew a read-only listing account at the tail of their account lists to guard against conflicting state: CloseAlias and CloseDomain refuse while a listing is open (reaping the asset would strand the listing’s rent), OfferTransferAlias refuses while a listing is open (an alias can’t carry both a private transfer offer and an open listing — and since v0.7.0 the offer is the only alias transfer path), TransferDomainAuthority refuses while a listing is open (repointing a name under a live listing would leave a stale holder recorded as the seller, able to collect the sale proceeds — the holder must cancel first; the alias-side TransferAlias carried the same guard until it was disabled outright in v0.7.0), and RequestDeactivateDomain refuses while a listing is open (a deactivation timelock finalizing under a live listing would flip the domain’s state under the buyer — the authority must cancel, or the sale complete, first). In each case the listing slot must be an uninitialized PDA for the instruction to proceed. BuyDomain carries the mirror-image guard: a read-only pending-deactivation slot at the tail of its account list, which must be uninitialized — a purchase is refused while a deactivation timelock is in flight. BuyDomain also re-checks, against the mail-domain account it already carries, that the domain is still active at the moment of purchase: an inactive domain stays listable (the flag is stable and plainly readable on-chain), but the sale settles only once the domain is reactivated — so a deactivation finalized under a live listing (reachable only in pre-guard history) can never sell a dead name. BuyAlias needs no extra slot for its guard: it re-checks the listing’s recorded holder against the alias account it already carries.

Marketplace account lists

The full account lists of the guard-reshaped mutation instructions, in slot order (the CLI’s builders pin these byte-for-byte):

A self-funded buy passes the buyer again in the price-payer slot; the runtime merges the duplicate metas into one writable signer.

Marketplace error codes

SithBitError variants convert to ProgramError::Custom(code), with the variant’s numeric position as the on-chain code (the enum is append-only for exactly this reason). The marketplace tail:

BuyDomain’s pending-deactivation refusal reuses code 29 (DeactivationAlreadyPending, “A deactivation is already pending for this domain”) — the same error RequestDeactivateDomain and ListDomain raise; the error enum is append-only, so guards reuse existing codes where one fits. On the same principle, RequestDeactivateDomain’s open-listing refusal reuses code 64 (DomainHasPendingListing), and BuyDomain’s inactive-domain refusal reuses code 25 (InactiveDomain, “Domain is not registered or is deactivated”).

All three programs share the single SithBitError enum, so a given code means the same thing whichever program raised it. The program split appended one variant:

Raised by the mail program for the sixteen retired domain discriminants.

The participant-beacon tail (item 43):

The mailbox close timelock tail — the mailbox-scoped twins of the domain-deactivation errors, appended as one block:

Code 94 gets its own variant rather than reusing a close error, mirroring item 30’s UnilateralTransferDisabled (85): a client hitting a disabled instruction needs to hear that, not be told to open a pending close it cannot then finalize instantly.

The sponsored-mailbox errors (payer ≠ owner creates and their funder-refund close) follow:

The verified-sender attestation appended one variant (its fee-cap twin of codes 98–100, which are noted inline on their setters’ instruction rows above):

Reputation-scaled first-contact pricing appended one more, the floor setter’s cap twin:

A purchase presenting a present-but-invalid attestation account in the reputation tail is refused rather than silently repriced — wrong owner raises the runtime’s IllegalOwner, an attestation for a different wallet raises code 19 (WrongAddressForInstruction), and a wrong derivation raises code 17 (InvalidDerivedAccount) — codes clients can match on.

Pinning leases added a missing-account code alongside the two fee codes noted inline above, and the money-path hardening added two more — one guarding the admin reclaim tool, one the purchaser’s slippage ceiling:

Code 106 is what makes AdminCloseAccount safe to expose: in all three programs it now refuses any target whose balance sits above its rent-exempt minimum, so the reclaim tool can only reap rent-empty leftover state — never a sender’s escrowed postage, a reply bounty, or a live auction bid. Code 107 is the purchaser’s side of the same principle: the recipient sets the price and may raise it at any moment, so a buyer who supplied a ceiling gets a revert instead of a silent overpayment.