Skip to content

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 the h tag 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.

ImportUse it for
@internet-privacy/marmot-tsEverything most apps need: client, core and utils, plus the main engine classes
@internet-privacy/marmot-ts/clientMarmotClient, MarmotGroup, managers, network types, message helpers
@internet-privacy/marmot-ts/coreProtocol building blocks with no I/O
@internet-privacy/marmot-ts/engineThe full engine surface, for custom transports or persistence
@internet-privacy/marmot-ts/mlsThe bundled ts-mls fork (ciphersuites, crypto provider, MLS types)
@internet-privacy/marmot-ts/extraOptional helpers: in-memory and encrypted key/value stores, key/value history backend
@internet-privacy/marmot-ts/auditAudit event types and helpers for forensic logging
@internet-privacy/marmot-ts/extra/audit/node, /extra/audit/browserReady-made audit log writers for Node.js and browsers
@internet-privacy/marmot-ts/utilsEncoding, key/value, relay URL and Nostr helpers

Event kinds ​

KindWhat it isWhere it goes
10002NIP-65 relay list; its write relays are where your key packages liveYour outbox and lookup relays
10050Inbox relay list; where you receive invitesYour outbox and lookup relays
30443Key package (addressable; d tag is your clientId)Your NIP-65 write relays
445Group event: commits, proposals and encrypted application messagesThe group's relays
444Welcome rumor (unsigned), sealed inside a gift wrapNever published directly
1059NIP-59 gift wrap carrying a WelcomeThe invitee's kind 10050 inbox relays
5NIP-09 deletion, published when you purge key packagesYour NIP-65 write relays
450Account identity proof, a signed event embedded in each key package and leafNever published directly
9Chat 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.