Marmot Protocol
Marmot is a protocol for end-to-end encrypted group messaging on Nostr. It pairs Nostr’s identity and relay network with MLS, which manages group keys and gives groups forward secrecy plus post-compromise security.
How it works
Nostr supplies identity and relay-based event distribution, and Marmot layers MLS on top for group membership changes and message encryption. NIP-17 focuses on one-to-one messaging, while Marmot is built for groups whose membership and keys change over time.
What MLS adds
MLS gives Marmot properties that Nostr’s direct-message schemes do not provide on their own. Group state evolves through authenticated membership changes with defined removal semantics, and later key updates let a group recover after a compromise.
Nostr handles identity and transport in an open network. MLS handles authenticated group key agreement. Marmot specifies how the two fit together.
Implementation status
The protocol remains experimental, but it now has multiple implementations and active application use. MDK is the main Rust reference stack and marmot-ts brings the model to TypeScript. Applications such as White Noise, Amethyst, Pika, and Vector have been using Marmot-compatible components.
Recent work has focused on hardening and interop. Audit-driven fixes landed in early 2026, and MIP-03 introduced deterministic commit resolution so clients can converge when concurrent group state changes race across relays.
MDK 0.9.9 preserves manual chat-pin order and adds terminal group disbanding. That release also exposes richer reply and ambient group context to agent integrations.
MDK 0.11.0 adds qualified account-history recovery with durable notices for unproven gaps. It also introduces a database-backed delivery queue and carries encrypted group polls along with an Android native-library update. Applications need the matching generated bindings and native libraries, and account databases cannot be downgraded after the schema migration.
In April 2026, Amethyst brought its embedded MDK into line with the MIP-01 and MIP-05 wire formats. PR #2462 added VarInt encoding of TLS-style length prefixes and round-trip validation against MDK test vectors. PR #2435 added MIP-00 KeyPackage Relay List support, and PR #2436 closed remaining admin-gate and media-handling gaps flagged by cross-client testing against White Noise. PR #2466 corrected MLS commit framing so encrypted welcome bytes match mdk-core output, and PR #2471 fixed an outer-layer decryption bug that caused state divergence between co-admins. Follow-up PR #2493 adds validation of MLS commit cryptography, and PR #2488 ships amy, a CLI interface for Marmot and MLS group operations driven from Amethyst’s implementation.
MDK landed PR #261 to compute a group’s RequiredCapabilities as the LCD of invitee capabilities (unblocking mixed-version invites between Amethyst and White Noise), PR #262 to parse invitee key packages before persisting the creator’s signer, PR #264 to converge the SelfUpdate wire format across implementations, and PR #265 to expose a group_required_proposals accessor.
whitenoise-rs is in the middle of a multi-phase refactor from global singletons to per-account AccountSession views: PR #743 established the AccountSession and AccountManager scaffolding, and follow-on phases have migrated relay handles, drafts and settings, message ops, group read and write, membership, push notifications, key-package reads, group creation, and, as of PR #770, session-scoped event dispatch. marmot-ts PR #68 migrates the TypeScript client to addressable kind 30443 key packages.
White Noise Android’s September 30 release brings encrypted group polls into its Android interface and shows notices when history recovery remains incomplete. Account-specific disappearing-message defaults apply to new conversations. Later MDK source work adds tagged custom-emoji sends and media reactions, separately from the tagged runtime release.
Draft linked-device and account-sync work
The Marmot repository has merged a series of draft specification sections for using one account from several devices, and that draft text alone does not show application support. MDK has since merged a default-off development device-groups capability that lets daemon-backed wn commands run device-group pairing through the existing pairing flow, provided matching persistent development binaries are used. Ordinary releases keep it off, and the change claims neither mobile or binding activation nor physical-device testing.
MDK source also includes experimental linked-device Welcome resend and history-only backup restore for current memberships. A newly merged MDK repair now matches the Marmot heartbeat rule. Repair falls due once the current target’s heartbeat shows activity at least 10 minutes after the latest accepted publication, and then the exact retained Welcome is resent without a new Add, KeyPackage or history. The resend stays default-off, and an unknown publication time blocks it. Heartbeat cadence or the target’s clock lag can delay it by an hour or more, and a bounded keyset scan may spend one maintenance turn wrapping before repair is checked again, so completion has no overall upper bound. It is not an ordinary app feature.
The device roster draft adds a roster component and a per-account device group. The device group lists the roster component, under the experimental identifier 0x800e, in its RequiredCapabilities. The separate experimental identifier 0x800f names the device-tag component. A new device pairs with an existing one by comparing seven emoji and then joins the device group. Private KeyPackages let a linked device add its siblings to existing chats, and each added sibling receives a sibling Welcome. Small-state sync shares compact account state between the devices.
Message history uses separate drafts. History keys and history deliveries define encrypted history for an account’s devices. Inline delivery remains available for history bundles, and the history bundle draft permits Blossom as an optional alternative transport. Backup writing seals backups to a recovery key. Encryption protects bundle and backup contents, but any Blossom server that carries them can still observe uploads and fetches.
Removing a device and cleanup after a device leaves the roster define how the remaining devices retire it and its keys. Removal cannot recall messages or history the device already received.
PR #480 narrows compromise handling to the warning raised by a device’s own-slot check. It removes the rejected-KeyPackage and anomaly event kind from earlier drafts and leaves compromise of the account signing key out of scope. The change also breaks the experimental roster encoding, so device groups built on earlier drafts must be recreated and cannot be upgraded in place.
Primary sources:
MDK 0.9.9 - Chat-pin ordering and terminal group disbanding, with agent context additions
Amethyst PR #2462 - MIP-01/MIP-05 wire format alignment
Amethyst PR #2435 - MIP-00 KeyPackage Relay List
Amethyst PR #2488 - Amy CLI
Marmot PR #452 - Device roster component and device group (draft)
Marmot PR #454 - Device pairing (draft)
Marmot PR #456 - Linking a device into the device group (draft)
Marmot PR #459 - Slot announcements with the own-slot check; private KeyPackages (draft)
Marmot PR #466 - Small-state sync between an account’s devices (draft)
Marmot PR #467 - History keys and history deliveries (draft)
Marmot PR #480 - Compromise handling narrowed to the own-slot warning (draft)
Marmot PR #483 - History bundles with optional Blossom delivery (draft)
Marmot PR #487 - Writing backups (draft)
Marmot invitation-generation and Welcome repair specification
Mentioned in:
- Newsletter #49
- Newsletter #48: Marmot projects at bitcoin++ Seoul
- Newsletter #47: MDK heartbeat-based Welcome repair
- Newsletter #46: Marmot adopts multiple devices per account
- Newsletter 45
- Newsletter #44
- Newsletter #1: News
- Newsletter #1: Releases
- Newsletter #4
- Newsletter #7
- Newsletter #12
- Newsletter #19: Amethyst MIP compliance
- Newsletter #19: MDK interop work
- Newsletter #19: whitenoise-rs session refactor
- Newsletter #23: White Noise
- Newsletter #27: ZapBook builds 4 through 27 add Marmot key publication
- Newsletter #31: Vector v0.4.0 moves Group Chats from Marmot to Concord, and Amethyst ships its own Concord client days later
- Newsletter #31: Bitcoin-Safe reaches Flathub, spotlighting its Nostr Sync & Chat plugin
- Newsletter #33: Tagged releases
- Newsletter #37: Heterodyne specifies portable personas and encrypted social communication
- Newsletter #38: MDK v0.9.15
- Newsletter #40: Marmot Protocol and MDK 0.10.0
- Newsletter #41: MDK 0.10.4 durable local sends
- Newsletter #42: MDK 0.11.0 recovery
- Newsletter #42: White Noise Android
- Newsletter #42: MDK source work
- Newsletter #42: Moyu workspace client
See also: