Concepts
This page defines the terms used across the docs, shows how the library is layered, and lists the Nostr event kinds Marmot uses.
Key terms
- Group: a set of members sharing MLS encryption state. Each group has an MLS group id (
group.id) and a separate Nostr routing id used in thehtag of its events. - Member / leaf: one installation in a group. An account (Nostr pubkey) can have several leaves, one per device.
- Key package: a member's published public key material. You need someone's key package to add them to a group. Each install publishes into one addressable slot, its
clientId. - Proposal: a suggested change to the group, such as adding or removing a member or updating metadata.
- Commit: applies proposals and advances the group to a new epoch with fresh keys. Membership and metadata changes need an admin; any member can commit its own self-update or departure.
- Welcome: the MLS message that lets a new member join. It is delivered as a gift-wrapped invite.
- Rumor: an unsigned Nostr event. Application messages are rumors encrypted inside the group, so they never carry a signature that could leak outside it.
- Convergence: when members commit concurrently, every client deterministically picks the same winning branch. Sends are queued until the group settles.
- App component: a typed entry in the group's MLS app-data dictionary carrying Marmot metadata (profile, admins, relays, media policy).
Module layering
your app
│
▼
client MarmotClient, MarmotGroup, managers, Nostr I/O, storage
│
▼
engine transport-independent group state machine (ingest, convergence)
│
▼
core Marmot protocol: credentials, key packages, groups, messages; no I/O
│
▼
ts-mls RFC 9420 MLS (bundled fork)Most apps only need MarmotClient. Drop to lower layers when you need control the client does not give you; see Low-level APIs.
| Import | Use it for |
|---|---|
@internet-privacy/marmot-ts | Everything most apps need: client, core and utils, plus the main engine classes |
@internet-privacy/marmot-ts/client | MarmotClient, MarmotGroup, managers, network types, message helpers |
@internet-privacy/marmot-ts/core | Protocol building blocks with no I/O |
@internet-privacy/marmot-ts/engine | The full engine surface, for custom transports or persistence |
@internet-privacy/marmot-ts/mls | The bundled ts-mls fork (ciphersuites, crypto provider, MLS types) |
@internet-privacy/marmot-ts/extra | Optional helpers: in-memory and encrypted key/value stores, key/value history backend |
@internet-privacy/marmot-ts/audit | Audit event types and helpers for forensic logging |
@internet-privacy/marmot-ts/extra/audit/node, /extra/audit/browser | Ready-made audit log writers for Node.js and browsers |
@internet-privacy/marmot-ts/utils | Encoding, key/value, relay URL and Nostr helpers |
Event kinds
| Kind | What it is | Where it goes |
|---|---|---|
| 10002 | NIP-65 relay list; its write relays are where your key packages live | Your outbox and lookup relays |
| 10050 | Inbox relay list; where you receive invites | Your outbox and lookup relays |
| 30443 | Key package (addressable; d tag is your clientId) | Your NIP-65 write relays |
| 445 | Group event: commits, proposals and encrypted application messages | The group's relays |
| 444 | Welcome rumor (unsigned), sealed inside a gift wrap | Never published directly |
| 1059 | NIP-59 gift wrap carrying a Welcome | The invitee's kind 10050 inbox relays |
| 5 | NIP-09 deletion, published when you purge key packages | Your NIP-65 write relays |
| 450 | Account identity proof, a signed event embedded in each key package and leaf | Never published directly |
| 9 | Chat message rumor from createChatRumor (app convention, not part of the protocol) | Encrypted inside kind 445 |
Security guarantees
- End-to-end encryption: only current group members can read application messages.
- Forward secrecy: compromising today's keys does not reveal earlier messages.
- Post-compromise security: a commit (for example
selfUpdate()) heals the group after a key compromise. - Unlinkable group events: each kind 445 event is signed by a fresh ephemeral key and its content is wrapped in an extra ChaCha20-Poly1305 layer keyed from the group's MLS exporter secret, so relays cannot tie events to members.
- Private invites: Welcomes travel in NIP-59 gift wraps, hiding sender and group from relays.
- Identity binding: every key package and leaf carries a proof signed by the member's Nostr key, so a leaf cannot claim someone else's pubkey.
- Admin policy: commits that change membership or metadata are rejected unless an admin made them.
- Verified input: inbound events have their signatures checked before they reach the protocol layer.
Your Nostr signer and your stores remain part of your trust boundary: anyone who can read groupStateStore or keyPackageStore can read the group. See Storage.