Class MarmotGroup<THistory, TMedia>

constructor

• new MarmotGroup<
      THistory extends BaseGroupHistory
      | undefined = undefined,
      TMedia extends BaseGroupMedia | undefined = undefined,
  >(
      state: ClientState,
      options: MarmotGroupOptions<THistory, TMedia>,
  ): MarmotGroup<THistory, TMedia>

  Type Parameters

  • THistory extends BaseGroupHistory | undefined = undefined

    The type of the history store to use for the group, must implement the BaseGroupHistory interface. (Default is no history store)

  • TMedia extends BaseGroupMedia | undefined = undefined

  Parameters

  • state: ClientState
  • options: MarmotGroupOptions<THistory, TMedia>

  Returns MarmotGroup<THistory, TMedia>

Readonlyciphersuite

Readonlyhistory

idStr

Readonlymedia

ReadonlymediaService

Readonlynetwork

Readonlyruntime

Readonlysession

Readonlysigner

Readonlystore

convergenceStatus

• get convergenceStatus(): ConvergenceStatus

  The group's derived convergence status (group-state.md §Convergence status, B5): Syncing / Resolving / Settled / Blocked. Recomputed on read against the clock, so it advances to Settled once the quiescence window elapses with no further convergence-relevant input.

  Returns ConvergenceStatus

dirty

• get dirty(): boolean

  Returns boolean

forkTree

• get forkTree(): GroupHistoryTree

  The live full-fork history tree: every group state observed (the canonical branch and every fork), keyed by MLS confirmation tag. Exposes synchronous structural queries (node, childrenOf, tips, path, ancestors, lowestCommonAncestor) and async snapshot access (stateAt, commitMessageOf). For a serializable rendering snapshot use forkTreeView.

  Returns GroupHistoryTree

groupData

• get groupData(): MarmotGroupView | null

  Returns MarmotGroupView | null

id

• get id(): Uint8Array<ArrayBufferLike>

  Returns Uint8Array<ArrayBufferLike>

info

• get info(): MarmotGroupInfo

  Complete group info/debug model for chat panels and diagnostics.

  Returns MarmotGroupInfo

lifecycle

• get lifecycle(): GroupLifecycleState

  The group's lifecycle state (group-state.md). A new local commit may only be prepared while Stable; the commit flow moves through PendingPublish (commit prepared, publish unconfirmed) and Merging (publish acked, staged commit applying) and back to Stable.

  Returns GroupLifecycleState

pendingWelcomes

• get pendingWelcomes(): readonly WelcomeDeliveryOutcome[]

  The failed subset of welcomeDeliveries — the invitees a founding create has not yet reached. Retry with retryWelcome.

  Carries the same R-04 warning as welcomeDeliveries: this is in-memory only, lost on restart, and ignorable by a caller that never reads it. The only recovery beyond retryWelcome is the spec's re-invite-with-a-fresh-KeyPackage path (refs/marmot/protocol-core/publish-lifecycle.md lines 66-78).

  Returns readonly WelcomeDeliveryOutcome[]

profileSupport

• get profileSupport(): GroupProfileSupport

  Account-identity-proof profile support is orthogonal to membership status (D-11): a stored group whose GroupContext does not classify as the current profile (legacy, mixed, or missing the 0x8009 requirement) stays listable and destroy()-able, but every outbound send and every inbound event is refused. Delegates to session.profileSupport, which recomputes from the engine on every access.

  Returns GroupProfileSupport

relays

• get relays(): string[] | undefined

  Returns string[] | undefined

state

• get state(): ClientState

  Read the current group state

  Returns ClientState

• set state(newState: ClientState): void

  Overrides the current group state

  Parameters

  • newState: ClientState

  Returns void

  Warning

  It is not recommended to use this

status

• get status(): MarmotGroupStatus

  Public absorbing status; Unrecoverable deliberately remains active/repairable.

  Returns MarmotGroupStatus

unappliedProposals

• get unappliedProposals(): UnappliedProposals

  Returns UnappliedProposals

welcomeDeliveries

• get welcomeDeliveries(): readonly WelcomeDeliveryOutcome[]

  The FOUND-04 per-invitee Welcome delivery report: one entry per recipient a founding create attempted to deliver to, in delivery order.

  This is in-memory only and is lost on restart or crash (D-04). It is discoverable state, not a returned value or a thrown error — a caller that never reads it silently loses an invitee who is already a member at epoch 1. The only recovery is the spec's re-invite path: the founding creator MAY re-invite the unreachable member with a fresh KeyPackage against the now-canonical group (refs/marmot/protocol-core/publish-lifecycle.md lines 66-78). This is an accepted consequence of D-04 + D-10 + D-12, not an oversight (R-04).

  Returns readonly WelcomeDeliveryOutcome[]

decryptMedia

• decryptMedia(
      encrypted: Uint8Array,
      attachment: MediaAttachment,
  ): Promise<StoredMedia>

  Decrypts an encrypted-media-v1 attachment downloaded from a blob store.

  On the first call for a given file the plaintext bytes are derived via key-derivation + ChaCha20-Poly1305 decryption (after verifying the ciphertext and plaintext hashes) and stored in {@link media}. Subsequent calls for the same attachment.ciphertextSha256 are served directly from the cache, skipping key-derivation entirely.

  Parameters

  • encrypted: Uint8Array
  • attachment: MediaAttachment

  Returns Promise<StoredMedia>

deliverFoundingWelcomes

• deliverFoundingWelcomes(
      options: {
          author: string;
          recipients: WelcomeRecipient[];
          welcome: Welcome;
      },
  ): Promise<readonly WelcomeDeliveryOutcome[]>

  Fans out a founding Welcome to every invitee, one NostrWelcomeDelivery.deliverMany call reached directly through runtime.welcomeDelivery (D-05/D-07) — this bypasses GroupRuntime's publish path entirely, since a founding Add has no GroupPublishWork to drive. Retains the Welcome and author so a failed recipient can be retried later via retryWelcome.

  Never throws and never saves: partial or total Welcome failure is a normal outcome (D-12), reported through pendingWelcomes rather than raised. GroupFactory.create refuses a founding create without valid group relays (CR-01), so on the factory path this group always carries relays; the group-relay list is forwarded both as each Welcome rumor's required relays tag and as deliver's inbox-lookup fallback, and a recipient whose own inbox lookup resolves empty still fails independently of the others.

  Parameters

  • options: { author: string; recipients: WelcomeRecipient[]; welcome: Welcome }

  Returns Promise<readonly WelcomeDeliveryOutcome[]>

destroy

• destroy(): Promise<void>

  Destroys the group and purges the group history

  Returns Promise<void>

disband

• disband(): Promise<DisbandResult>

  Persists irreversible intent, publishes one candidate, and retains it until selection.

  Returns Promise<DisbandResult>

dispose

• dispose(): void

  Releases in-memory resources without touching persisted state (B5): cancels the settle-check timer and fails any queued outbound. Call on unload so a timer/promise does not outlive the cached instance.

  Returns void

enableDisbanding

• enableDisbanding(): Promise<EnableDisbandingResult>

  Atomically enables lifecycle-v1 for a legacy group and publishes it once.

  Returns Promise<EnableDisbandingResult>

encryptMedia

• encryptMedia(
      blob: Blob,
      metadata: EncryptMediaMetadata,
  ): Promise<{ attachment: MediaAttachment; encrypted: Uint8Array }>

  Encrypts a media file for sharing in a group message (encrypted-media-v1).

  Derives the per-file key from the current MLS epoch, encrypts with ChaCha20-Poly1305, and returns the ciphertext alongside a populated MediaAttachment (hashes, nonce, media type, filename) with no locators yet.

  Caller responsibilities:

  1. Upload encrypted to a blob store (ciphertextSha256 is the content id).
  2. Push a locator ({ kind, value }) onto attachment.locators.
  3. Serialize with encodeMediaImetaTag and include the tag on the rumor.

  Parameters

  • blob: Blob
  • metadata: EncryptMediaMetadata

  Returns Promise<{ attachment: MediaAttachment; encrypted: Uint8Array }>

evaluateKeyPackage

• evaluateKeyPackage(keyPackageEvent: NostrEvent): KeyPackageEligibility

  Evaluates whether a candidate's KeyPackage event (kind 30443) can be added to this group — cipher-suite match, required_capabilities, agent-text-stream-QUIC required_member_roles, and already-a-member. Use this before GroupsManager.invite to surface why a KeyPackage can't be added; an eligible: true result is safe to invite. Never throws.

  Parameters

  • keyPackageEvent: NostrEvent

  Returns KeyPackageEligibility

forkTreeView

• forkTreeView(): ForkTreeView

  A plain, serializable snapshot of the fork-history tree for debugging UIs — every node with its epoch, parent/children, tip flag, and whether it lies on the canonical path to the live tip (the branch convergence settled on, i.e. the node matching state). Computed on demand.

  Returns ForkTreeView

ingest

• ingest(
      events: NostrEvent[],
      options?: { maxRetries?: number },
  ): AsyncGenerator<DispositionedIngestResult>

  ingests an array of group messages and applies commits to the group state.

  Processing happens in two stages:

  1. Process all non-commit messages (proposals, application messages)
     • If a message fails to process, it's added to unreadable for retry
  2. Process commits according to refs/marmot/protocol-core/group-messaging.md (sorted by epoch, timestamp, event id)
     • Commits advance the epoch and update the group state

  After both stages, recursively retry unreadable messages until no more can be read. Events that can never be processed are yielded as UnreadableIngestResult.

  Parameters

  • events: NostrEvent[]

    Array of Nostr events containing encrypted MLS messages

  • Optionaloptions: { maxRetries?: number }

  Returns AsyncGenerator<DispositionedIngestResult>

  Yields

  DispositionedIngestResult - The processing result plus its inbound-processing Disposition.

off

• off<T extends keyof MarmotGroupEvents<THistory, TMedia>>(
      event: T,
      fn?: (
          ...args: ArgumentMap<MarmotGroupEvents<THistory, TMedia>>[Extract<
              T,
              keyof MarmotGroupEvents<THistory, TMedia>,
          >],
      ) => void,
      context?: unknown,
      once?: boolean,
  ): this

  Type Parameters

  • T extends keyof MarmotGroupEvents<THistory, TMedia>

  Parameters

  • event: T
  • Optionalfn: (
        ...args: ArgumentMap<MarmotGroupEvents<THistory, TMedia>>[Extract<
            T,
            keyof MarmotGroupEvents<THistory, TMedia>,
        >],
    ) => void
  • Optionalcontext: unknown
  • Optionalonce: boolean

  Returns this

on

• on<T extends keyof MarmotGroupEvents<THistory, TMedia>>(
      event: T,
      fn: (
          ...args: ArgumentMap<MarmotGroupEvents<THistory, TMedia>>[Extract<
              T,
              keyof MarmotGroupEvents<THistory, TMedia>,
          >],
      ) => void,
      context?: unknown,
  ): this

  Add a listener for a given event.

  Type Parameters

  • T extends keyof MarmotGroupEvents<THistory, TMedia>

  Parameters

  • event: T
  • fn: (
        ...args: ArgumentMap<MarmotGroupEvents<THistory, TMedia>>[Extract<
            T,
            keyof MarmotGroupEvents<THistory, TMedia>,
        >],
    ) => void
  • Optionalcontext: unknown

  Returns this

once

• once<T extends keyof MarmotGroupEvents<THistory, TMedia>>(
      event: T,
      fn: (
          ...args: ArgumentMap<MarmotGroupEvents<THistory, TMedia>>[Extract<
              T,
              keyof MarmotGroupEvents<THistory, TMedia>,
          >],
      ) => void,
      context?: unknown,
  ): this

  Add a one-time listener for a given event.

  Type Parameters

  • T extends keyof MarmotGroupEvents<THistory, TMedia>

  Parameters

  • event: T
  • fn: (
        ...args: ArgumentMap<MarmotGroupEvents<THistory, TMedia>>[Extract<
            T,
            keyof MarmotGroupEvents<THistory, TMedia>,
        >],
    ) => void
  • Optionalcontext: unknown

  Returns this

pendingEvents

• pendingEvents(): NostrEvent[]

  Group transport events received but not yet decrypted/processed into the fork-history tree — the engine's ingestion pool (oldest-first). Normally transient (a message awaiting its commit, a fork message awaiting its branch); they are retried as the tree grows. An entry that lingers is a received event the client could never read — a gap a full-history debugger surfaces, since the unlocking state never arrived.

  Returns NostrEvent[]

propose

• propose<Args extends unknown[], T extends Proposal | Proposal[]>(
      action: ProposalBuilder<Args, T>,
      ...args: Args,
  ): Promise<Record<string, PublishResponse>>

  Creates and publishes a proposal as a private MLS message.

  Type Parameters

  • Args extends unknown[]
  • T extends Proposal | Proposal[]

  Parameters

  • action: ProposalBuilder<Args, T>
  • ...args: Args

  Returns Promise<Record<string, PublishResponse>>

  Promise resolving to the publish response from the relays

• propose<Args extends unknown[], T extends Proposal | Proposal[]>(
      action: ProposalAction<T>,
  ): Promise<Record<string, PublishResponse>>

  Creates and publishes a proposal as a private MLS message.

  Type Parameters

  • Args extends unknown[]
  • T extends Proposal | Proposal[]

  Parameters

  • action: ProposalAction<T>

  Returns Promise<Record<string, PublishResponse>>

  Promise resolving to the publish response from the relays

realizeDisbandIfNeeded

• realizeDisbandIfNeeded(): Promise<void>

  Realizes durable terminal notification exactly once across restarts.

  Returns Promise<void>

realizeRemovalIfNeeded

• realizeRemovalIfNeeded(): Promise<void>

  Realizes a persisted removal after the owning registry has attached its forwarding listeners. This is idempotent across concurrent loads and process restarts when a removal marker store is configured.

  Returns Promise<void>

reconverge

• reconverge(): Promise<void>

  Re-scores the persisted fork history against the current tip and switches to the canonical branch if a competing fork now wins (convergence.md), persisting a resulting switch. Candidates come from the forkTree, so a client that diverged onto a losing fork converges from disk without waiting for the network to re-deliver the winning branch. Called automatically on load; safe to call explicitly to force a re-evaluation.

  CR-06: the pass's results are routed through the SAME marker-clearing branch ingest uses, so a load-time rewind that supersedes the commit which removed us clears the persisted removed-inactive marker. Previously every result here was discarded, so the documented "called automatically on load" path could never clear it and a client restored to membership kept a stale marker that silently suppressed its next genuine removal.

  Returns Promise<void>

removeAllListeners

• removeAllListeners(event?: keyof MarmotGroupEvents<THistory, TMedia>): this

  Remove all listeners, or those of the specified event.

  Parameters

  • Optionalevent: keyof MarmotGroupEvents<THistory, TMedia>

  Returns this

removeListener

• removeListener<T extends keyof MarmotGroupEvents<THistory, TMedia>>(
      event: T,
      fn?: (
          ...args: ArgumentMap<MarmotGroupEvents<THistory, TMedia>>[Extract<
              T,
              keyof MarmotGroupEvents<THistory, TMedia>,
          >],
      ) => void,
      context?: unknown,
      once?: boolean,
  ): this

  Remove the listeners of a given event.

  Type Parameters

  • T extends keyof MarmotGroupEvents<THistory, TMedia>

  Parameters

  • event: T
  • Optionalfn: (
        ...args: ArgumentMap<MarmotGroupEvents<THistory, TMedia>>[Extract<
            T,
            keyof MarmotGroupEvents<THistory, TMedia>,
        >],
    ) => void
  • Optionalcontext: unknown
  • Optionalonce: boolean

  Returns this

resumePendingDisband

• resumePendingDisband(): Promise<void>

  Resumes a durable terminal intent after hydration when preparation is eligible. Also the single seam #settleAndDrive uses to resume a pending request mid-session, so both resume paths share one predicate.

  Returns Promise<void>

retryWelcome

• retryWelcome(pubkey: string): Promise<WelcomeDeliveryOutcome>

  Re-delivers one invitee's founding Welcome. Throws naming pubkey when there is no matching delivery outcome, or when no founding Welcome is retained (for instance after a restart) — this fails loudly rather than silently no-opping, since a silent no-op is exactly R-04's failure mode. When the matching entry already succeeded, returns it unchanged without performing another delivery.

  Deliberately has no epoch guard: RESEARCH Priority Finding #1 establishes that a late epoch-1 Welcome is safe because the joiner's backfill (GroupsManager#connectGroup) has no since bound, provided the group has relays. GroupFactory.create no longer produces relay-less founding groups (CR-01), so on the factory path the relays precondition always holds.

  Parameters

  • pubkey: string

  Returns Promise<WelcomeDeliveryOutcome>

save

• save(force?: boolean): Promise<void>

  Persists any pending changes to the group state in the store.

  Parameters

  • force: boolean = false

    When true, writes the current state even if dirty is false. Useful for persisting the initial state of a freshly constructed group (e.g. after createGroup / joinGroupFromWelcome / import) without having to mutate dirty externally.

  Returns Promise<void>

selfUpdate

• selfUpdate(): Promise<Record<string, PublishResponse>>

  Performs a self-update commit (no proposals) to rotate this member's leaf key material.

  This is required by refs/marmot/protocol-core/joining.md for forward secrecy after joining from a Welcome.

  Unlike admin commits (see GroupsManager.commit), this operation is allowed for non-admin members.

  Returns Promise<Record<string, PublishResponse>>

sendProposal

• sendProposal(proposal: Proposal): Promise<Record<string, PublishResponse>>

  Sends a proposal to the group relays

  Parameters

  • proposal: Proposal

  Returns Promise<Record<string, PublishResponse>>

submitIntent

• submitIntent(intent: GroupSessionSendIntent): Promise<GroupPublishResult[]>

  Convergence-gated outbound entry point (B5). While convergence is Settled and the lifecycle allows outbound, the intent is built, encrypted, and published immediately. Otherwise it is queued and the returned promise stays pending until the quiescence window settles and the queue drains — so app payloads are held, and group-state commits are (re)generated only against the canonical post-settle state. leave() and the self_remove auto-committer bypass this gate by design (departures and convergence progress, not fresh local intents).

  Parameters

  • intent: GroupSessionSendIntent

  Returns Promise<GroupPublishResult[]>

StaticfromClientState

• fromClientState<
      THistory extends BaseGroupHistory
      | undefined = undefined,
      TMedia extends BaseGroupMedia | undefined = undefined,
  >(
      state: ClientState,
      options: Omit<MarmotGroupOptions<THistory, TMedia>, "ciphersuite"> & {
          cryptoProvider?: CryptoProvider;
      },
  ): Promise<MarmotGroup<THistory, TMedia>>

  Creates a new MarmotGroup instance from a ClientState object

  Type Parameters

  • THistory extends BaseGroupHistory | undefined = undefined
  • TMedia extends BaseGroupMedia | undefined = undefined

  Parameters

  • state: ClientState
  • options: Omit<MarmotGroupOptions<THistory, TMedia>, "ciphersuite"> & {
        cryptoProvider?: CryptoProvider;
    }

  Returns Promise<MarmotGroup<THistory, TMedia>>