Sigil Mail is the on-chain substrate for decentralised mail. The chain stores mail identity records, versioned receive policies, public key directory, delivery commitments, sender economics, and mail-scoped permissions. The chain does not store message plaintext; encrypted messages live in Weave, framed by zer0-secret-stream, which runs the Noise IK handshake and ChaCha20-Poly1305 framing that carries Mail’s E2E payload.

​
What lives where

On-chainOff-chain (Weave)
Mailbox capability recordsEncrypted message bodies
Versioned receive policiesIndexes (per-recipient)
Public key directoryDrafts
Delivery commitmentsAttachments
Sender economics stateSearch tokens
Abuse reports—
Delegations—
Mail-scoped nonces—

​
Live protocol surface

ModulePurpose
node/sigil-core/src/mail.rsCanonical records, transaction data, policy rules, deterministic IDs, privacy-shape validators.
node/sigil-node/src/mail_durable.rsAkashaKV persistence under mail/ and sns/ prefixes.
node/sigil-node/src/executor_mail.rsExecutor for mailbox, policy, key, delivery, abuse, delegation, and SNS transactions. Real Ed25519 sender-key verification is live.
node/sigil-node/src/rpc_mail.rsRead surface for mailbox resolution, policy/key lookup, delivery scans, delegations, abuse reports, name resolution.
node/sigil-sdk/src/mail.rsTransaction builders and preflight helpers.
weave/libs/weave-sdk/src/mailbox.rsPrivate encrypted mailbox envelope, ChaCha20-Poly1305 via loom-encrypt, content-key wrap with sealed boxes.

​
Mailbox model

A mailbox is identified by a deterministic id derived from (owner_did, mailbox_label). Each mailbox has:
  • A capability record binding the mailbox to its owner DID, username, and wallet controller.
  • A versioned receive policy.
  • An active encryption key and signing key in the public key directory.
  • A history of delivery commitments.
  • A sender-economics ledger (fees, refundable stakes).

​
Receive policies

A receive policy declares who can deliver to the mailbox. Policy kinds, all composable:
KindAllowsRequires
OpenAnyoneSender fee or refundable stake.
RequireVerifiedSenderAnyone with an active signing keyCryptographic sender signature over the delivery transcript.
AllowlistListed DIDs onlyOff-chain payload may be encrypted to any allowlisted key.
MandateGatedHolders of a specified mandateMandate id; the chain verifies authority.
ContactListDIDs the owner has previously sent toBi-directional history check.
RateLimitUp to N messages per epochPer-sender counter.
Policies are versioned; updates require a SetMailPolicy transaction. The active version applies to new deliveries.

​
Delivery commitment

A delivery commitment binds the sender, recipient, encryption key version, Weave object commitment, timestamp, and policy version: 
pub struct DeliveryCommitment {
    pub sender_did: Did,
    pub recipient_mailbox_id: [u8; 32],
    pub key_version: u32,
    pub envelope_commitment: [u8; 32], // BLAKE3 of the sealed Weave object
    pub policy_version: u32,
    pub delivered_at_height: u64,
}
Deliveries are deduplicated by (sender, recipient, envelope_commitment). Locked or deactivated mailboxes, expired keys, and revoked keys all reject.

​
Key directory

The key directory holds the active encryption and signing keys for each DID. Operations:
TransactionPurpose
RegisterMailKeyRegister an initial key set.
RotateMailKeyRotate keys (a previous key remains valid for a grace period).
RevokeMailKeyImmediately revoke a key (e.g. on compromise).
Key rotation is voluntary; recommended cadence is annual.

​
Sender economics

Anti-spam relies on either a one-time fee or a refundable stake:
  • Fee mode: sender pays a per-message fee to the mailbox owner. The mailbox may refund part of it as reputation grows.
  • Stake mode: sender locks a refundable stake; abuse reports against the sender may slash the stake.
The mailbox owner posts the policy parameters; senders see them before delivery via sigil_getMailPolicy.

​
Abuse reports

Recipients can submit ReportAbuse against a delivery. Abuse reports accrue against the sender DID. A configurable threshold triggers automatic stake slashing (under stake mode) or capability downgrade.

​
Delegations

Mail-scoped delegations allow mailbox operators, delivery services, devices, and recovery controllers to act on behalf of the mailbox owner without full key access. Delegations carry explicit scope (delivery, key rotation, policy update) and expiry.

​
RPC

MethodReturns
sigil_getMailboxMailbox capability record.
sigil_getMailPolicyVersioned receive policy.
sigil_getMailKeyActive key for a DID.
sigil_listMailDeliveriesByRecipientDelivery commitments for a mailbox.
sigil_listMailDeliveriesBySenderDelivery commitments by a sender.
sigil_getMailDelegationDelegation record.
sigil_resolveMailResolve a name to a mailbox via SNS.

​
What is not yet live

The substrate is live at the runtime/API layer; consumer-facing pieces remain follow-on work:
  • Consumer UI, dBrowser integration, Forge agent integration, SMTP/Gmail bridges, JMAP adapters.
  • Full contact / reputation / proof / rate-limit policy enforcement beyond the launch deny / allow / fee / stake gates.
The launch-readiness gate pre-genesis-feature-readiness reports mail: or sns: blockers if the substrate is incomplete; the feature is not marketed as live when those blockers report.

​
Implementation

  • Types: node/sigil-core/src/mail.rs.
  • Executor: node/sigil-node/src/executor_mail.rs.
  • Durable state: node/sigil-node/src/mail_durable.rs.
  • SDK: node/sigil-sdk/src/mail.rs.

​
See also