Reference

Contract reference

Every external function across MailRegistry and MailBox, with parameters, access control and behaviour.

Two contracts, both Solidity 0.8.24 targeting the cancun EVM. MailBox holds an immutable reference to MailRegistry and calls a single method on it.

MailRegistry: reading

Function	Returns	Notes
`nameHash(string)`	`bytes32`	Pure. The canonical key for every name mapping.
`isRegistered(address)`	`bool`	The only method `MailBox` calls.
`pubkeyOf(address)`	`bytes32`	Current published X25519 key.
`resolve(string)`	`address`	Name to wallet. Zero if unclaimed.
`lookup(string)`	wallet, pubkey, keyVersion, epoch	One call for everything a sender needs.
`feeFor(string)`	`uint256`	Priced on visible length, hyphens excluded.
`unavailableReason(string, address)`	reason	Why a name cannot be taken, for useful client errors.
`isValidName(string)`	`bool`	Charset, length and hyphen placement.
`isValidPubkey(bytes32)`	`bool`	Rejects zero, top-bit-set, and six small-order points.
`skeleton(string)`	`string`	Confusable folding. Advisory only, never enforced.

MailRegistry: writing

register

function register(string calldata name, bytes32 x25519Pubkey, uint256 maxFee)
  external payable

Mints a name to msg.sender and publishes its encryption key. Reverts if the wallet already holds a name, the name is taken, reserved, invalid, or inside another owner's release grace. Overpayment above the required fee is refunded; maxFee caps exposure to a price change.

rotateKey

function rotateKey(bytes32 newPubkey) external

Publishes a new key and increments keyVersion. The previous key stays in keyHistory, so older mail remains readable.

Transfers

initiateTransfer(address to)

Starts a handover. Expires after TRANSFER_WINDOW.

cancelTransfer()

Revokes a pending transfer immediately.

acceptTransfer(string name, bytes32 pubkey)

The receiving wallet completes it with its own key. Reserved names are refused here too.

releaseName()

Gives up the name. Opens a RELEASE_GRACE window in which only the previous owner may re-register it.

Owner-only

reserveNames(string[], bool)

Up to MAX_RESERVE_BATCH (256). Never dispossesses an existing holder; emits ReservedWhileRegistered instead.

setPrices(uint256, uint256)

Sets price3 and price4.

transferOwnership(address)

Two-step. Expires after OWNERSHIP_WINDOW.

cancelOwnershipTransfer()

Revokes a pending ownership handover.

acceptOwnership()

Called by the incoming owner.

withdraw(address payable)

Withdraws collected premium-name fees.

What the owner cannot do

There is no function that reassigns a registered name, reads mail, or changes a published key on someone's behalf. Owner powers are limited to reservations, pricing, and withdrawing fees.

MailBox: reading

Function	Returns	Notes
`requiredStamp(recipient, sender)`	`uint256`	What this sender must escrow right now.
`canSend(recipient, sender, envelopeBytes)`	ok, reason, required	Pre-flight check, so the client can explain a failure before spending gas.
`isAllowed(recipient, sender)`	`bool`	Allowlist membership, respecting its expiry.
`stamps(mailId)`	`Stamp`	Escrow row for one message.
`credits(address)`	`uint256`	Value owed after a failed push payment.
`mailCount()`	`uint256`	Total messages emitted; the source of `mailId`.

MailBox: sending

function send(
  address to,
  bytes calldata envelope,
  uint256 inReplyTo,
  uint256 maxStamp
) external payable

Recipient wallet. Must be registered.

envelope

The sealed blob. At most MAX_ENVELOPE_BYTES.

inReplyTo

A prior mailId, or zero. If it names a live stamp this recipient paid to reach the sender, the required stamp drops to zero.

maxStamp

The caller's ceiling, so a price change cannot front-run them.

The Mail event is emitted before settlement, so delivery is never contingent on a payout succeeding.

MailBox: settlement

refundStamp(mailId)

Recipient returns the escrow. Refused after expiry.

claimStamp(mailId)

Recipient takes it. Refused while they block the sender.

settleExpired(mailId)

Permissionless after 30 days. Pushes to the recipient so nothing is stranded.

reclaimStamp(mailId)

Sender recovers it, but only if blocked or the recipient left the registry.

refundStampBatch / claimStampBatch / reclaimStampBatch

Up to MAX_BATCH. Skip inapplicable rows rather than reverting; emit BatchSettled.

withdrawCredits() / withdrawCreditsTo(address)

Pull value credited after a failed push.

MailBox: inbox controls

setStampPrice(uint256)

Zero means an open inbox. Bounded by minStamp and MAX_STAMP.

setAllowed(address, uint64 until)

Time-bounded free access for one sender.

setBlocked(address, bool)

Blocked senders cannot send at any price.

setAllowedBatch / setBlockedBatch

Batch forms of the above.

Constants

Contract	Constant	Value
MailRegistry	`TRANSFER_WINDOW`	7 days
MailRegistry	`RELEASE_GRACE`	7 days
MailRegistry	`OWNERSHIP_WINDOW`	7 days
MailRegistry	`MAX_RESERVE_BATCH`	256
MailBox	`STAMP_EXPIRY`	30 days
MailBox	`MAX_ENVELOPE_BYTES`	32 KB
MailBox	`FREE_ENVELOPE_BYTES`	4 KB
MailBox	`MAX_STAMP`	100 ether
MailBox	`MAX_BATCH`	64
MailBox	`PAYOUT_GAS`	60,000