Skip to content

Groups ​

This page covers the group lifecycle with client.groups and MarmotGroup: creating, loading, inviting, removing, leaving, disbanding and changing metadata. Sending and receiving messages is on Messages.

Create a group ​

client.groups.create(name, options) builds a new group with you as its only member and an admin. Nothing is published until you invite someone or send a message.

typescript
const group = await client.groups.create("Engineering", {
  description: "Secure team chat",
  relays: ["wss://relay.example.com"], // where group traffic (kind 445) is published
  adminPubkeys: [alicePubkey], // extra admins; you are always one
});

console.log(group.idStr); // hex MLS group id, use it with client.groups.*

Without relays the group has no Nostr routing and cannot publish, so pass them unless you are only experimenting locally. To enable encrypted attachments at creation, see Media.

Create a group with founding members ​

Pass the invitees' key package events as invitees. They become members right away and each gets a Welcome. relays is required in this case.

typescript
const group = await client.groups.create("Engineering", {
  relays: ["wss://relay.example.com"],
  invitees: [aliceKeyPackageEvent, bobKeyPackageEvent],
});

// create() does not throw when a Welcome fails to send: check and retry
for (const outcome of group.pendingWelcomes) {
  await group.retryWelcome(outcome.recipient.pubkey);
}

Welcome results are kept in memory only

group.pendingWelcomes and retryWelcome() only work while this group instance stays loaded. After a restart, a member whose Welcome never arrived can't be reached this way; remove them and invite a fresh key package instead.

Load, unload and destroy groups ​

Groups are loaded from storage on demand and cached in memory.

typescript
const group = await client.groups.get(groupId); // Uint8Array or hex string
const all = await client.groups.loadAll();

await client.groups.unload(groupId); // free memory, keep storage
await client.groups.destroy(groupId); // delete local state and history

client.groups.watch() yields the stored group list now and after every create, join, load or destroy. Pass { includeStateChanges: true } to also re-yield when a loaded group's state changes, without reading storage. See UI Frameworks for using these in React, Svelte and others.

typescript
for await (const groups of client.groups.watch({ signal })) {
  renderGroupList(groups);
}

Read group state ​

typescript
import { getGroupMemberPubkeys } from "@internet-privacy/marmot-ts";

group.groupData?.name; // also description, adminPubkeys, relays, avatarUrl
group.info.members.pubkeys; // member pubkeys
getGroupMemberPubkeys(group.state); // same, from raw MLS state
group.info.mls.epoch; // current epoch
group.status; // "active" | "removed" | "disbanded"

groupData is null once a group is disbanded. A "removed" group keeps its local state so you can show it; call client.groups.destroy() when you no longer need it. For a cheap, cached value to render, use group.snapshot and the changed event (see UI Frameworks).

Invite members ​

Fetch the person's key packages from their NIP-65 write relays (see Key Packages), keep one this group can accept, and invite it. Membership changes require an admin.

typescript
const candidates = await client.network.request(writeRelays, [
  { kinds: [30443], authors: [memberPubkey] },
]);

const keyPackageEvent = candidates
  .sort((a, b) => b.created_at - a.created_at)
  .find((event) => group.evaluateKeyPackage(event).eligible);

if (keyPackageEvent) await client.groups.invite(group.id, keyPackageEvent);

evaluateKeyPackage checks the cipher suite, required capabilities, lifetime and existing membership; when eligible is false, reasons says why. invite() verifies the event, publishes the commit and, once a relay accepts it, gift-wraps a Welcome to the invitee's inbox relays.

Invite several key packages at once ​

To add several people, or every device of one person, put all the Adds in one commit with createInviteIntent. Sending it through client.groups.send also returns each invitee's Welcome result.

typescript
import { createInviteIntent } from "@internet-privacy/marmot-ts";

const actorPubkey = await client.signer.getPublicKey();
const intents = eligibleEvents.map((keyPackageEvent) =>
  createInviteIntent({ keyPackageEvent, actorPubkey }),
);

const [result] = await client.groups.send(group.id, {
  kind: "commit",
  actorPubkey,
  extraProposals: intents.flatMap((intent) => intent.extraProposals ?? []),
  welcomeRecipients: intents.flatMap(
    (intent) => intent.welcomeRecipients ?? [],
  ),
});

if (result.welcomeDelivery.kind === "attempted") {
  for (const outcome of result.welcomeDelivery.outcomes)
    if (outcome.kind === "failed")
      console.warn(outcome.recipient.pubkey, outcome.error);
}

Remove members ​

Proposals.proposeRemoveUser(pubkey) removes every device the user has in the group. Commit it as an admin:

typescript
import { Proposals } from "@internet-privacy/marmot-ts";

await client.groups.commit(group.id, {
  extraProposals: [Proposals.proposeRemoveUser(memberPubkey)],
});

If the removed user was an admin, they are dropped from the admin list in the same commit. A commit that would leave the group with no admin is refused.

Leave a group ​

leave() publishes a self-remove proposal, then deletes your local copy of the group. Another member commits your removal later.

typescript
await client.groups.leave(group.id);

If no relay accepts the proposal, leave() throws and keeps local state so you can try again.

Disband a group ​

An admin can end a group for everyone. disband() removes every other member and marks the group disbanded in one commit. It returns a result rather than throwing:

typescript
const result = await group.disband();
if (result.kind === "rejected" && result.reason === "notEnabled") {
  // Groups created by older clients must turn disbanding on first
  await group.enableDisbanding();
}

Groups created by this library have disbanding enabled already, so enableDisbanding() returns { kind: "alreadyEnabled" } for them. It fails with reason: "unsupportedMembers" if a member's client can't handle disbanding. Once the disband commit is selected, group.status becomes "disbanded" and the disbanded event fires on every member's client.

Update metadata ​

Proposals.proposeUpdateMetadata changes only the fields you pass. Commit it as an admin:

typescript
await client.groups.commit(group.id, {
  extraProposals: [
    Proposals.proposeUpdateMetadata({
      name: "Engineering (new)",
      relays: ["wss://relay.example.com", "wss://relay2.example.com"],
    }),
  ],
});

Supported fields are name, description, adminPubkeys, relays, avatarUrl, messageRetention (seconds; 0 keeps messages indefinitely), encryptedMedia and nostrGroupId. For group images, see Group Images.

Combine changes in one commit ​

client.groups.commit accepts any mix of proposal builders in extraProposals, so related changes land in one epoch:

typescript
await client.groups.commit(group.id, {
  extraProposals: [
    Proposals.proposeRemoveUser(memberPubkey),
    Proposals.proposeUpdateMetadata({ adminPubkeys: remainingAdmins }),
  ],
});
BuilderEffect
proposeInviteUser(keyPackageEvent)Add one key package (prefer createInviteIntent, which also checks the event and sends the Welcome)
proposeRemoveUser(pubkey)Remove all of a user's devices
proposeUpdateMetadata(fields)Change name, admins, relays and so on
proposeSetEncryptedMediaPolicy(policy)Turn encrypted media on, change it or turn it off (Media)
proposeLeaveGroup(ownPubkey)Self-remove; use client.groups.leave instead

To publish a proposal without committing it, use group.propose(action). An admin can later commit received proposals by passing keys of group.unappliedProposals as proposalRefs. Any member can rotate their own keys with group.selfUpdate().

Recover a failed publication ​

If the relays' answer to a commit is uncertain, the commit throws PublicationUncertainError and the group waits. Retry the same commit instead of building a new one:

typescript
import { PublicationUncertainError } from "@internet-privacy/marmot-ts";

try {
  await client.groups.commit(group.id, options);
} catch (error) {
  if (!(error instanceof PublicationUncertainError)) throw error;
  await group.retryPendingPublication();
}

Every new send also retries an outstanding publication first. To survive a restart while a commit is pending, provide a durable rewindStore (see Storage). For founding Welcomes that failed, use retryWelcome() as shown in Create a group with founding members.

Events ​

client.groups emits events for every group:

EventFires when
created / joined / importedA group was created, joined from a Welcome, or imported
loaded / unloadedA group was loaded from or dropped from memory
updatedThe set of loaded groups changed
changedThe loaded set or any loaded group's snapshot changed
destroyed / leftLocal state was deleted, or you left the group
removedSomeone else's commit removed you
disbandedThe group was disbanded
ingestResultA connected group produced an ingest result (Messages)
rejected / unreadableA connected group's event failed validation or could not be read

Each MarmotGroup emits events about itself:

EventFires when
changedgroup.snapshot changed
applicationMessageA message was decrypted (Messages)
ingestResultIngest produced a result
stateChangedThe MLS state advanced
stateSavedThe state was written to storage
removedYou were removed from the group
disbandedThe group was disbanded
historyChangedThe fork history grew (Fork History)
historyErrorSaving to history failed
disposedThe instance was unloaded and its watchers ended
destroyedLocal state was deleted
typescript
client.groups.on("removed", (groupId) => markInactive(groupId));
group.on("disbanded", (g, { actorPubkey }) => showDisbandedBy(actorPubkey));

See the API reference for every option and result type.