MarmotKit API
This guide follows the latest stable release. Use the documentation at your installed version’s tag when working with an older release.
This reference inventories the UniFFI exports and is maintained alongside source changes. Start with the integration guide for API selection, lifecycle, localization and ownership. For the 0.14.0 changes, read 0.13.0 → 0.14.0.
The native-host test recipe exercises generated Swift against a local MockRelay
with an injected thread-safe SecretStore, bounded delivery assertions, and same-root reopening.
It also gives the corresponding Android configuration and callback signatures.
This inventories runtime/object methods, free functions and host callback methods. AttachmentHistoryCursor,
AccountAttachmentCursor, ChatStorageCursor, RetainedAttachmentsCursor and ChatListDraftVersionFfi are opaque
objects with no exported methods. Generated disposal/concurrency helpers are platform scaffolding, not additional
MDK commands. C has a separate complete symbol index, including
its lifetime helpers and compatibility-only entry points.
Reading the reference
- Signatures below use exact Rust export spelling and types; Swift/Kotlin normally expose
lowerCamelCase names (
attachment_local_assets→attachmentLocalAssets). Constructors and native integer/optional/list/error syntax follow generated code from your cohort. async fnbecomes Swift async / Kotlin suspend. A synchronousfncan perform storage I/O; run blocking operations off the UI thread.Resultbecomes the generated error path;Optionis successful absence/stream closure as specified by the individual contract.- Current means supported for its stated purpose, not that every app needs it. Lower-level means an intentional custom-client/primitive surface. Compatibility means a newer path is recommended for that listed use case; it is not a formal deprecation annotation, removal promise or requirement to rewrite custom clients. Host callback means implement it in the host, not call it as a runtime command.
- Source links lead to signatures, full doc comments and implementations. DTO field/variant definitions live in conversions, errors, Markdown types and the generated binding from the same release. Per-feature contracts in the README override no source behavior; report discrepancies.
- Object methods use their owning type explicitly. Distinguish each
next/snapshotcontract: a transfer subscription delivers its initial value fromnext, while a screen window has a separate initial snapshot. Do not infer cancellation support from another handle.
Maintaining the reference
Run just binding-docs-update to refresh exact signatures and source anchors without
rewriting the surrounding guidance. New exports receive blocking scaffolds for an author
to complete and organize; removed/duplicate entries need explicit editorial cleanup.
just binding-docs-gate checks that metadata and runs the companion regression tests.
Descriptions and API-selection recommendations still require source-aware human review;
they are not verified by the mechanical gate. Counts are reported by the tool rather than
hard-coded in these pages.
Swift cancellation adapters
The published MarmotKit.swift includes these Swift-only methods from
CancellableSubscriptions.swift.
Each has the same result and native errors as its object's next(), but forwards Swift task cancellation
to the native future and throws CancellationError. Cancellation does not close the subscription.
These are not new Rust exports or Kotlin methods. See
subscription ownership for concurrent receive and cancellation races.
| Subscription | Swift signature |
|---|---|
PresentedChatListSubscription |
func nextCancellable() async throws -> PresentedChatListUpdateFfi? |
ChatListWindowSubscription |
func nextCancellable() async throws -> ChatListWindowSnapshotFfi? |
AccountAttentionSubscription |
func nextCancellable() async throws -> AccountAttentionSnapshotFfi? |
ConversationWindowSubscription |
func nextCancellable() async throws -> ConversationWindowSnapshotFfi? |
BlockListSubscription |
func nextCancellable() async throws -> BlockListSnapshotFfi? |
Methods by source module
Each expandable section lists every export in that module. Search this page for the exact Rust or owning-type method name. Signatures are kept intact to make input/output, optionality, synchronous versus asynchronous behavior and drift review explicit.
<details> <summary>commands/account.rs</summary>
Marmot::list_accounts
Current.
pub fn list_accounts(&self) -> Result<Vec<AccountSummaryFfi>, MarmotKitError>
All accounts known to the runtime, in stable order. running is false for accounts that haven't been brought up by the current process yet.
Marmot::account_unread_summary
Lower-level. One-shot unread query; prepared account badges use subscribe_account_attention.
pub fn account_unread_summary( &self, ) -> Result<Vec<conversions::AccountUnreadFfi>, MarmotKitError>
Per-account unread aggregate for the account-switcher and application badge (mdk#461, mdk#1460). Each entry is read from that account's materialized chat-list projection, so this does not require switching into, or loading a full session/timeline for, any account — non-active (not-running) local-signing accounts are reported too. This legacy getter omits accounts whose projection read fails. attention_only_conversations counts each active pending invitation once and accepted manual-only reminders, without overlapping message totals. Archived chats and departed or departing groups contribute nothing.
Marmot::remove_account
Current.
pub async fn remove_account(&self, account_ref: String) -> Result<(), MarmotKitError>
Remove a local-signing account from this device.
Marmot::sign_out_and_wipe
Current.
pub async fn sign_out_and_wipe( &self, account_ref: String, ) -> Result<conversions::WipeOutcomeFfi, MarmotKitError>
Destructive sign-out: leave every active MLS group (best-effort), delete this device's relay-published KeyPackage slot, then wipe all local state for this account (MLS state DB, cached media/secrets, SQL account row, and the secret-store nsec). After this returns the account ref is no longer valid for any further FFI call. The returned WipeOutcomeFfi reports each stage independently so the app can show progress and a partial-failure sheet (mdk#478).
With linked devices, it first asks the account's other devices to take it out, which can take about 30 seconds: show progress meanwhile. It leaves them the chats they can take it out of, counted in groups_left_to_siblings, and leaves the rest itself. When it could not ask them in time it tries to leave every chat itself, reporting any it cannot in group_leave_failures, and sets siblings_not_reached: tell the user its other devices may still list it until the user removes it from one of them. A chat this device is no longer in is neither left nor reported. In a chat its account administers with another account, and no other of its devices is in, it steps the account down first and counts the chat as left only once it sees its removal, waiting up to about 30 seconds more for all such chats (mdk#2818). The call keeps running when it is cancelled (mdk#2628).
Marmot::sign_out
Current.
pub async fn sign_out( &self, account_ref: String, delete_key_packages: bool, ) -> Result<conversions::SignOutOutcomeFfi, MarmotKitError>
Non-destructive sign-out: deactivate the account on this device and, when delete_key_packages is true (the default behavior in the UI), publish one kind:5 deletion for this device's KeyPackage slot so nobody can add this device to a new group while it is signed out. The account's other devices keep their KeyPackages.
Marmot::create_identity
Current.
pub async fn create_identity( &self, default_relays: Vec<String>, bootstrap_relays: Vec<String>, inbox_relays: Vec<String>, ) -> Result<AccountSummaryFfi, MarmotKitError>
Compatibility entry point for creating a brand-new Nostr identity. This retains the historical terminal-success contract: relay lists and the initial KeyPackage are published when it returns. New callers may use create_identity_with_profile for the earlier local-ready boundary and an explicit readiness state. Public indexers receive best-effort copies of both relay lists and kind-0 metadata; KeyPackages remain on the advertised write relays. inbox_relays (default empty) sets the kind-10050 inbox list separately; empty declares default_relays in both lists.
Marmot::create_identity_with_profile
Current.
pub async fn create_identity_with_profile( &self, default_relays: Vec<String>, bootstrap_relays: Vec<String>, inbox_relays: Vec<String>, ) -> Result<IdentityCreationResultFfi, MarmotKitError>
Create a generated identity and return at durable local readiness with the exact locally persisted default profile. readiness remains the authority for whether relay publication has completed; LocalReady must not be presented as invite-receivable. Account setup sends best-effort copies of both relay lists and the default kind-0 profile to public indexers. inbox_relays (default empty) sets the kind-10050 inbox list separately; empty declares default_relays in both lists.
Marmot::create_identity_with_initial_profile
Current.
pub async fn create_identity_with_initial_profile( &self, profile: UserProfileMetadataFfi, default_relays: Vec<String>, bootstrap_relays: Vec<String>, inbox_relays: Vec<String>, ) -> Result<IdentityCreationResultFfi, MarmotKitError>
Create a generated identity whose first public kind-0 is the caller's profile, returning at durable local readiness like create_identity_with_profile. Use it whenever onboarding collects a name: creating with the generated default and then calling publish_user_profile exposes the default to relays first, and contacts can keep seeing it. The returned profile is the stamped copy that setup publishes and caches; readiness remains the authority for relay publication. A setup resumed past its first local step ignores profile and returns the profile its bootstrap publishes; change it afterwards with publish_user_profile. inbox_relays (default empty) sets the kind-10050 inbox list separately; empty declares default_relays in both lists.
Marmot::account_setup_readiness
Current.
pub fn account_setup_readiness( &self, account_ref: String, ) -> Result<AccountSetupReadinessFfi, MarmotKitError>
Read setup readiness without performing network I/O.
Marmot::login
Compatibility. Prefer begin_onboarding for an interactive imported-account workflow.
pub async fn login( &self, identity: String, default_relays: Vec<String>, bootstrap_relays: Vec<String>, inbox_relays: Vec<String>, ) -> Result<AccountSummaryFfi, MarmotKitError>
Log in with an existing identity. identity can be an nsec (private key) for a local-signing account, or an npub to track a public identity without local signing. inbox_relays (default empty) sets the kind-10050 inbox list separately; empty declares default_relays in both lists.
Marmot::reset_incomplete_account_setup
Current.
pub async fn reset_incomplete_account_setup( &self, nsec: String, acknowledge_possible_key_package_orphan: bool, ) -> Result<(), MarmotKitError>
Remove only the legacy ambiguous partial-account shape so a subsequent login with the same nsec can recreate it. The acknowledgement is required because old local state cannot prove that no KeyPackage was exposed before its stable slot was lost.
Marmot::login_recovering_incomplete_setup
Current.
pub async fn login_recovering_incomplete_setup( &self, nsec: String, default_relays: Vec<String>, bootstrap_relays: Vec<String>, acknowledge_possible_key_package_orphan: bool, inbox_relays: Vec<String>, ) -> Result<AccountSummaryFfi, MarmotKitError>
Consent-gated one-call recovery for installations stranded before MDK had durable account-setup journals. This validates the same nsec, removes only the recognized ambiguous partial shape, preserves an existing account-id Keychain credential, and immediately retries login. inbox_relays (default empty) sets the kind-10050 inbox list separately; empty declares default_relays in both lists.
Marmot::login_external_signer
Compatibility. Prefer begin_external_signer_onboarding for an interactive imported-account workflow. C: not exposed; external-signer callback vtable is not implemented.
pub async fn login_external_signer( &self, public_key: String, signer: std::sync::Arc<dyn ExternalAccountSignerFfi>, default_relays: Vec<String>, bootstrap_relays: Vec<String>, inbox_relays: Vec<String>, ) -> Result<AccountSummaryFfi, MarmotKitError>
Log in with an external account signer such as Amber/NIP-55. inbox_relays (default empty) sets the kind-10050 inbox list separately; empty declares default_relays in both lists.
Marmot::register_external_signer
Current. C: not exposed; external-signer callback vtable is not implemented.
pub async fn register_external_signer( &self, account_ref: String, signer: std::sync::Arc<dyn ExternalAccountSignerFfi>, ) -> Result<(), MarmotKitError>
Re-register an external signer for an already-known external account.
Marmot::sign_in_account
Current.
pub async fn sign_in_account( &self, account_ref: String, ) -> Result<AccountSummaryFfi, MarmotKitError>
Re-activate a non-destructively signed-out local account. This clears the durable signed-out marker and starts the account worker again; relay list/key-package repair can still be driven by the existing publish commands after sign-in.
Marmot::publish_relay_lists
Current.
pub async fn publish_relay_lists( &self, account_ref: String, default_relays: Vec<String>, bootstrap_relays: Vec<String>, inbox_relays: Vec<String>, ) -> Result<(), MarmotKitError>
Publish (or re-publish) the NIP-65 and inbox relay lists for account_ref. Each call writes fresh replaceable events to the account relays and schedules best-effort public indexer copies when eligible; call when the lists need publication rather than on every launch. Indexers are not advertised as account relays. inbox_relays (default empty) sets the kind-10050 inbox list separately; empty declares default_relays in both lists.
Marmot::account_nip65_relays
Current.
pub fn account_nip65_relays(&self, account_ref: String) -> Result<Vec<String>, MarmotKitError>
Read the account NIP-65 relay list.
Marmot::account_inbox_relays
Current.
pub fn account_inbox_relays(&self, account_ref: String) -> Result<Vec<String>, MarmotKitError>
Read the account inbox relay list.
Marmot::account_key_packages
Compatibility. Prefer local_account_key_packages then refresh_account_key_packages for settings UI.
pub async fn account_key_packages( &self, account_ref: String, bootstrap_relays: Vec<String>, ) -> Result<Vec<conversions::AccountKeyPackageFfi>, MarmotKitError>
List the local and relay-discovered Marmot KeyPackage publications for account_ref. Relay-backed rows are the current winner per addressable slot in the validated fetch window.
Marmot::local_account_key_packages
Current.
pub fn local_account_key_packages( &self, account_ref: String, ) -> Result<Vec<conversions::AccountKeyPackageInventoryEntryFfi>, MarmotKitError>
Local-storage KeyPackage inventory with typed durable provenance. Does not wait for network startup or issue a directory query. Synchronous SQLCipher I/O on the calling thread; keep it off a UI or main thread.
Marmot::refresh_account_key_packages
Current.
pub async fn refresh_account_key_packages( &self, account_ref: String, bootstrap_relays: Vec<String>, ) -> Result<Vec<conversions::AccountKeyPackageInventoryEntryFfi>, MarmotKitError>
Fetch validated relay observations, then merge a fresh local snapshot. Empty bootstrap_relays remains network-enabled. On failure, keep the previously rendered local result.
Marmot::account_key_package_relay_events
Current.
pub async fn account_key_package_relay_events( &self, account_ref: String, bootstrap_relays: Vec<String>, ) -> Result<Vec<conversions::AccountKeyPackageRelayEventFfi>, MarmotKitError>
Observed relay history for account_ref: current and superseded kind-30443 events from one validated fetch window. Clients can pass a superseded event id and its source relays to the existing deletion API.
Marmot::publish_new_key_package
Current.
pub async fn publish_new_key_package( &self, account_ref: String, ) -> Result<u64, MarmotKitError>
Publish a new fresh KeyPackage for account_ref.
Marmot::rotate_key_package
Current.
pub async fn rotate_key_package(&self, account_ref: String) -> Result<u64, MarmotKitError>
Rotate the account's KeyPackage: mint and publish a fresh one, superseding the current slot. This is the sanctioned repair for an epoch-stalled group. publish_new_key_package is the same operation under its legacy name.
Marmot::republish_key_package
Current.
pub async fn republish_key_package(&self, account_ref: String) -> Result<u64, MarmotKitError>
Re-publish the latest cached KeyPackage when possible, otherwise publish a fresh one.
Marmot::delete_account_key_package
Current.
pub async fn delete_account_key_package( &self, account_ref: String, event_id_hex: String, relays: Vec<String>, ) -> Result<u64, MarmotKitError>
Publish a NIP-09 deletion for a KeyPackage event.
Marmot::set_account_nip65_relays
Current.
pub async fn set_account_nip65_relays( &self, account_ref: String, relays: Vec<String>, bootstrap_relays: Vec<String>, ) -> Result<conversions::AccountRelayListsFfi, MarmotKitError>
Publish the account read/write relay selection to its operational relays and copy it to public indexers.
Marmot::set_account_inbox_relays
Current.
pub async fn set_account_inbox_relays( &self, account_ref: String, relays: Vec<String>, bootstrap_relays: Vec<String>, ) -> Result<conversions::AccountRelayListsFfi, MarmotKitError>
Publish the account inbox relay selection to its operational relays and copy it to public indexers.
Marmot::account_follows
Current.
pub fn account_follows(&self, account_ref: String) -> Result<Vec<String>, MarmotKitError>
Return the complete locally cached kind-3 follow list for account_ref as canonical lowercase public-key hex strings.
Marmot::is_following
Current.
pub fn is_following( &self, account_ref: String, user_ref: String, ) -> Result<bool, MarmotKitError>
Return whether account_ref currently follows user_ref, using the same local cache as Self::account_follows. user_ref accepts npub, hex, nostr:npub…, and Marmot profile links.
Marmot::follow_user
Current.
pub async fn follow_user( &self, account_ref: String, user_ref: String, ) -> Result<Vec<String>, MarmotKitError>
Follow user_ref while preserving every other entry in the account's current kind-3 contact list. Returns the complete updated list. Appends one p tag and republishes petnames, relay hints, other tags and the content unchanged. Returns FollowListUnavailable when no current list is found, and FollowListTooLarge, publishing nothing, when the list has 2,048 follows or more (the most MDK reads from one list).
Marmot::unfollow_user
Current.
pub async fn unfollow_user( &self, account_ref: String, user_ref: String, ) -> Result<Vec<String>, MarmotKitError>
Unfollow user_ref while preserving every other entry in the account's current kind-3 contact list. Returns the complete updated list. Removes only user_ref's p tags; errors as follow_user.
Marmot::reveal_nsec
Current.
pub fn reveal_nsec(&self, account_ref: String) -> Result<String, MarmotKitError>
Export the active account's raw private key in canonical nsec1... bech32 form for an in-app key-backup display (mdk#543).
Marmot::export_encrypted_secret_key
Current.
pub fn export_encrypted_secret_key( &self, account_ref: String, passphrase: String, ) -> Result<String, MarmotKitError>
Export the active account's private key as a password-encrypted NIP-49 ncryptsec1... bech32 backup string (mdk#544).
Marmot::publish_user_profile
Current.
pub async fn publish_user_profile( &self, account_ref: String, profile: UserProfileMetadataFfi, default_relays: Vec<String>, bootstrap_relays: Vec<String>, ) -> Result<UserProfileMetadataFfi, MarmotKitError>
Publish Nostr kind:0 metadata with explicit caller-supplied relay overrides. Most app clients should use publish_user_profile_using_account_relays so relay selection remains owned by MDK. This override remains for diagnostics, tests, and specialized clients. Public indexers receive a best-effort copy of the same event.
Marmot::publish_user_profile_using_account_relays
Current.
pub async fn publish_user_profile_using_account_relays( &self, account_ref: String, profile: UserProfileMetadataFfi, ) -> Result<UserProfileMetadataFfi, MarmotKitError>
Publish Nostr kind:0 metadata using one coherent snapshot of the selected account's MDK-owned relay configuration. Public indexers receive a best-effort copy of the same event.
Marmot::upload_profile_image
Current.
pub async fn upload_profile_image( &self, account_ref: String, data: Vec<u8>, media_type: String, blossom_server: Option<String>, ) -> Result<String, MarmotKitError>
Upload a public raster profile image to Blossom with the account's signer. The returned HTTPS URL can be published as kind:0 picture.
Marmot::download_profile_image
Compatibility. Prefer avatar asset request/read for visible screen metadata.
pub async fn download_profile_image( &self, url: String, max_bytes: u64, ) -> Result<Vec<u8>, MarmotKitError>
Fetch one untrusted kind:0 profile picture URL with MDK dial-safe HTTPS policy, address pinning, and bounded streaming.
</details>
<details> <summary>commands/agent_stream.rs</summary>
Marmot::start_agent_text_stream
Current.
pub async fn start_agent_text_stream( &self, account_ref: String, group_id_hex: String, stream_id_hex: Option<String>, quic_candidates: Vec<String>, ) -> Result<AgentStreamStartFfi, MarmotKitError>
Anchor a live agent text stream start in the encrypted group history. Host apps pass the broker candidate(s) they will publish to, such as quic://quic-broker.ipf.dev:4450; omit stream_id_hex to let Rust generate a 32-byte stream id.
Marmot::watch_agent_text_stream
Current.
pub async fn watch_agent_text_stream( &self, account_ref: String, group_id_hex: String, stream_id_hex: Option<String>, server_cert_der: Option<Vec<u8>>, insecure_local: bool, ) -> Result<Arc<AgentStreamSubscription>, MarmotKitError>
Watch a live agent text stream over the brokered QUIC channel. Pass stream_id_hex = None to follow the latest stream in the group (the common case when reacting to an AgentStreamStarted event). The returned subscription yields incremental Chunks then a terminal Finished / Failed. server_cert_der pins a self-signed broker cert (else the bundled public-CA roots, not the OS trust store); insecure_local is loopback-only for testing.
</details>
<details> <summary>commands/attachment_access.rs</summary>
Marmot::attachment_local_assets
Current.
pub async fn attachment_local_assets( &self, account_ref: String, group_id_hex: String, targets: Vec<AttachmentLocalTargetFfi>, ) -> Result<Vec<AttachmentLocalAssetFfi>, MarmotKitError>
Local-only metadata for up to 64 original source slots in one group. Results preserve input order/duplicates. No bytes are loaded, jobs queued, downloads started or engine state hydrated. Requires no runtime start.
Marmot::read_attachment_asset
Current.
pub async fn read_attachment_asset( &self, account_ref: String, reference: String, offset: u64, limit: u32, ) -> Result<AttachmentLocalBytesFfi, MarmotKitError>
Read 1..=1048576 bytes at an offset from an opaque local asset reference. Unavailable is distinct from available/empty EOF. Every call rechecks source visibility, expiry and account/store identity. No network fallback. Hosts own decoding and must discard assembled bytes if a chunk is unavailable.
Marmot::open_attachment_handoff
Current.
pub async fn open_attachment_handoff( &self, account_ref: String, group_id_hex: String, target: AttachmentLocalTargetFfi, control: Arc<MediaFileTransferControlFfi>, ) -> Result<Option<AttachmentHandoffFfi>, MarmotKitError>
Write a plaintext copy of one retained attachment for an OS surface that needs a real file (the Android package installer, the share sheet, "open with", Quick Look) and lend it under a lease. Use it only for those surfaces; in-app display and playback keep using read_attachment_asset. None means the attachment is not held locally, exactly as attachment_local_assets reports it; no download is started. The copy is <account>/handoff/<lease>/<file_name>, created owner-only, where file_name is the attachment's own name made safe (basename only, no separators, control characters or edge dots, at most 128 bytes) with an extension from the media type when it had none. It stays until release_attachment_handoff, account removal, or the account worker's next start in a new process; shutdown_and_close refuses new handoffs but keeps existing copies, and removing the attachment does not revoke a lease. Each call makes a separate copy. control reports copied bytes and cancels the copy, which then leaves nothing. Cancel only through control, never by cancelling the awaiting coroutine or task: a call cancelled just as it completes can drop the lease before the host sees it, leaving the copy until the account worker's next start in a new process deletes it. A copy the disk cannot hold beyond the attachment policy's disk_reserve fails with StorageFull. Works for bodies in the media store and in the legacy database layout. See the handoff contract.
Marmot::release_attachment_handoff
Current.
pub async fn release_attachment_handoff(&self, lease: String) -> Result<(), MarmotKitError>
Delete a handoff copy once the OS surface is done with it (the installer or share activity returned, the controller was dismissed). Idempotent: an unknown or already released lease succeeds; a malformed one is rejected with InvalidMediaReference, which no retry fixes. A copy that cannot be deleted returns Io and stays leased, so retry the release. Do not use the path afterwards.
</details>
<details> <summary>commands/attachment_controls.rs</summary>
AttachmentTransferSubscription::next
Current.
pub async fn next(&self) -> Result<Option<AttachmentTransferSnapshotFfi>, MarmotKitError>
Initial snapshot, then replacements: a transfer state change at once, progress-only changes at most four per second. None means closed. Errors terminate this observation; close/drop never cancels acquisition.
AttachmentTransferSubscription::cancel
Current.
pub fn cancel(&self)
Stop observation and wake receivers; does not cancel acquisition.
Marmot::attachment_download_policy
Current.
pub async fn attachment_download_policy( &self, account_ref: String, ) -> Result<AttachmentDownloadPolicyFfi, MarmotKitError>
Read the durable per-account automatic acquisition, quota, disk-reserve and transfer-cap policy.
Marmot::set_attachment_download_policy
Current.
pub async fn set_attachment_download_policy( &self, account_ref: String, policy: AttachmentDownloadPolicyFfi, ) -> Result<(), MarmotKitError>
Validate and persist acquisition policy; disabling automatic work preserves explicit work and retained files.
Marmot::request_explicit_attachment
pub async fn request_explicit_attachment( &self, account_ref: String, group_id_hex: String, target: AttachmentLocalTargetFfi, ) -> Result<Option<String>, MarmotKitError>
Join a current source or promote automatic demand to explicit priority without resetting retry budgets or scheduled backoff. Use this for ordinary interactive demand; reserve control_attachment(Retry) and download_attachment_again for deliberate recovery. A returned opaque reference does not promise readiness: inspect transfer state and prefer local assets first. Active attempts retain their original size limit and deadline; promotion changes subsequent admission, not the existing transport budget. Cancelled, removed, exhausted and failed sources are not rearmed.
Marmot::control_attachment
Current.
pub async fn control_attachment( &self, account_ref: String, reference: String, control: AttachmentControlFfi, ) -> Result<bool, MarmotKitError>
Cancel durably, retry explicitly, or remove local bytes. Returns false for obsolete references or ineligible operations; cancellation preserves ready bytes.
Marmot::download_attachment_again
Current.
pub async fn download_attachment_again( &self, account_ref: String, group_id_hex: String, target: AttachmentLocalTargetFfi, ) -> Result<Option<String>, MarmotKitError>
Queue explicit acquisition for a current original source slot, clearing removal/cancellation; no reference means unavailable or obsolete.
Marmot::attachment_transfer_snapshot
Current.
pub async fn attachment_transfer_snapshot( &self, account_ref: String, group_id_hex: String, targets: Vec<AttachmentLocalTargetFfi>, ) -> Result<AttachmentTransferSnapshotFfi, MarmotKitError>
Read bounded transfer state for up to 64 source slots in one group without requesting a transfer.
Marmot::subscribe_attachment_transfers
Current.
pub async fn subscribe_attachment_transfers( &self, account_ref: String, group_id_hex: String, targets: Vec<AttachmentLocalTargetFfi>, ) -> Result<Arc<AttachmentTransferSubscription>, MarmotKitError>
Observe initial transfer state and complete replacements for bounded source slots: a row that appears, disappears or changes transfer state arrives as soon as the engine reports it, while progress-only replacements stay coalesced to at most four per second. Observation does not request a transfer.
</details>
<details> <summary>commands/attachment_history.rs</summary>
Marmot::reaction_attachment
Current.
pub async fn reaction_attachment( &self, account_ref: String, group_id_hex: String, reaction_message_id_hex: String, ) -> Result<Option<AttachmentEntryFfi>, MarmotKitError>
Bounded local lookup for one active custom-emoji reaction, keyed by its reactionMessageIdHex within the account and chat. Returns the validated image attachment matching that reaction's shortcode, with its original message/source IDs and attachment index, or None when unavailable or unmatched. Starts no download. Use the target with ordinary automatic or explicit attachment acquisition and opaque local reads; re-resolve when the earliest active reaction ID changes. Never fetch an emoji tag URL directly. See reaction artwork.
The reaction ID must contain exactly 64 hexadecimal characters; malformed IDs return InvalidMediaReference. The lookup considers original imeta indices 0–99 only, source tag JSON and each candidate slot up to 16 KiB, and reaction content up to 64 UTF-8 bytes including colons. Oversized metadata, artwork outside those indices, or no eligible match returns None. The first well-formed definition of the exact content shortcode wins; later duplicates cannot replace an unmatched first definition.
Marmot::attachment_history_page
Current.
pub async fn attachment_history_page( &self, account_ref: String, group_id_hex: String, limit: u32, cursor: Option<Arc<AttachmentHistoryCursor>>, ) -> Result<AttachmentPageReadFfi, MarmotKitError>
Read 1..=100 attachment slots in canonical newest-first order. Rejected slots consume the limit. Filter categories within returned pages; an empty filtered page is not exhaustion while has_more is true. No downloads are started. Keep cursors/versions in memory only and restart after runtime reconstruction.
Marmot::attachment_history_version
Current.
pub async fn attachment_history_version( &self, account_ref: String, group_id_hex: String, ) -> Result<Arc<AttachmentHistoryVersion>, MarmotKitError>
Cheap local refresh signal, including for a fully loaded or empty library. Compare against the baseline version captured when the current collection began: replacing that baseline with a newer page can hide a destructive change to earlier rows.
</details>
<details> <summary>commands/attachment_storage.rs</summary>
Marmot::attachment_storage_usage
Current.
pub async fn attachment_storage_usage( &self, account_ref: String, ) -> Result<AttachmentStorageUsageFfi, MarmotKitError>
Account-wide attachment storage for a Manage storage screen: media_bytes (media-store files, a file shared by several attachments counted once), legacy_bytes (bodies still in the account database; they move to the media store in the background), attachment_count, the database's database_bytes and database_free_bytes, and migration with migration_bytes: where moving legacy bodies into the media store stands (Running with the bytes left, Paused with the free space it still needs, NotNeeded, Complete, or Compacting while the database returns its free pages to the filesystem, with the other figures from just before), and cache_bytes: the avatar and group-image cache, which clear_avatar_cache empties and which is fetched again on demand. Reads no bodies and starts no worker. See Manage storage.
Marmot::attachment_storage_by_chat
Current.
pub async fn attachment_storage_by_chat( &self, account_ref: String, limit: u32, cursor: Option<Arc<ChatStorageCursor>>, ) -> Result<ChatStoragePageFfi, MarmotKitError>
Chats by retained attachment bytes, largest first, limit 1..=256 per page; pass the page's next_cursor to continue, and stop when it is absent (the last page may be empty). A stored file counts once per chat however many of its attachments share it; content shared with other chats counts in each, so per-chat totals can add up to more than media_bytes. Cursors are opaque handles: never persist them, and start over after a removal.
Marmot::largest_retained_attachments
Current.
pub async fn largest_retained_attachments( &self, account_ref: String, group_id_hex: Option<String>, limit: u32, cursor: Option<Arc<RetainedAttachmentsCursor>>, ) -> Result<RetainedAttachmentsPageFfi, MarmotKitError>
Retained attachments, largest first, limit 1..=256 per page, optionally within one chat (group_id_hex); continue with next_cursor as for attachment_storage_by_chat. Each entry's target works with attachment_local_assets (for an opaque reference to pass to control_attachment Remove) and open_attachment_handoff; media_type and file_name come from the published descriptor and are empty when it does not parse.
Marmot::remove_chat_attachments
Current.
pub async fn remove_chat_attachments( &self, account_ref: String, group_id_hex: String, ) -> Result<u64, MarmotKitError>
Removes every retained attachment in one chat and returns how many it removed. Each removal is exactly control_attachment Remove: the attachment shows as removed and download-again stays allowed. Media-store files the removal releases are deleted before this returns, so their space frees at once; legacy database bodies free database pages, which return to the filesystem only when the database is compacted. Refresh usage and listings afterwards.
Marmot::remove_attachments_older_than
Current.
pub async fn remove_attachments_older_than( &self, account_ref: String, received_before: u64, group_id_hex: Option<String>, ) -> Result<u64, MarmotKitError>
Removes retained attachments of messages received before received_before (Unix seconds, the message's received time), across the account or within one chat (group_id_hex), with the same semantics and immediate reclaim as remove_chat_attachments. Returns how many it removed.
Marmot::attachment_keep_media
Current.
pub async fn attachment_keep_media( &self, account_ref: String, ) -> Result<AttachmentKeepMediaFfi, MarmotKitError>
Reads the account's "Keep media" setting for a settings screen: Forever (the default) unless the user chose OneYear, SixMonths or ThirtyDays. The setting is per account on this device and is not synced to the account's other devices. Local read; needs no started runtime.
Marmot::set_attachment_keep_media
Current.
pub async fn set_attachment_keep_media( &self, account_ref: String, keep: AttachmentKeepMediaFfi, ) -> Result<u64, MarmotKitError>
Stores the account's "Keep media" setting, then removes every retained attachment already past the new window before returning, and returns how many it removed so the host can confirm what was freed. Age is the message's received time, or the user's last explicit download of that attachment when later. Removed attachments read CleanedBySetting in transfer snapshots, distinct from Removed (removed by you); download_attachment_again works for both. Media-store space is freed before this returns. While the runtime runs, the account worker applies the window at start and hourly as attachments age, and automatic downloads of attachments past it are skipped, or dropped if already queued but unfinished (they count toward the returned number and read CleanedBySetting too). Forever removes nothing. Ask the user to confirm before shortening the window: Blossom servers may no longer hold old media, so a removed attachment may not download again.
</details>
<details> <summary>commands/audit.rs</summary>
Marmot::audit_log_settings
Current.
pub fn audit_log_settings(&self) -> Result<AuditLogSettingsFfi, MarmotKitError>
Local forensic audit-log recording settings. Recording is opt-in and only applies to account sessions opened after the setting is enabled.
Marmot::set_audit_log_settings
Current.
pub async fn set_audit_log_settings( &self, settings: AuditLogSettingsFfi, ) -> Result<AuditLogSettingsFfi, MarmotKitError>
Persist local forensic audit-log recording settings and return the stored value.
Marmot::audit_log_retention
Current.
pub fn audit_log_retention(&self) -> Result<AuditLogRetentionFfi, MarmotKitError>
Read the persisted local audit retention policy: maximum file age in days and per-account size budget in bytes. Defaults to 30 days and 256 MiB.
Marmot::set_audit_log_retention
Current.
pub fn set_audit_log_retention( &self, retention: AuditLogRetentionFfi, ) -> Result<AuditLogRetentionFfi, MarmotKitError>
Persist the local audit retention policy and return the stored value, with max_age_days clamped to 1-30 and max_bytes_per_account to at least 16 MiB. Files past the age are deleted whether or not v5 delivery accepted them; deleting undelivered data records an ExpiredUndelivered gap. Above the budget, only the oldest sealed segments that v5 delivery accepted, or that no v5 delivery will send, are deleted. A running app sweeps under the new policy shortly after; explicit delete and clear calls are unaffected.
Marmot::set_audit_log_source
Current.
pub fn set_audit_log_source( &self, source: AuditLogSourceFfi, ) -> Result<AuditLogSourceFfi, MarmotKitError>
Set the in-memory source metadata (system hardware model, platform, app version) that each audit recorder opened afterwards writes into its source_context row, and return the trimmed stored value; a blank field becomes absent. Call it on every launch before opening accounts: recorders already open keep the source they started with. The hardware model must come from system model information, never a device name, hostname or serial number.
Marmot::audit_log_files
Current.
pub fn audit_log_files(&self) -> Result<Vec<AuditLogFileFfi>, MarmotKitError>
Local JSONL audit log files, including historical v4 files until retention expires them.
Marmot::delete_audit_log_file
Current.
pub async fn delete_audit_log_file( &self, path: String, ) -> Result<AuditLogDeleteResultFfi, MarmotKitError>
Delete one local JSONL audit log file (e.g. behind a "clear audit log" button).
</details>
<details> <summary>commands/avatar.rs</summary>
Marmot::request_avatar_assets
Current.
pub async fn request_avatar_assets( &self, account_ref: String, targets: Vec<String>, ) -> Result<Vec<AvatarAssetFfi>, MarmotKitError>
Pass up to 16 opaque targets from visible screen metadata. Does not await HTTP.
Marmot::read_avatar_assets
Current.
pub async fn read_avatar_assets( &self, account_ref: String, references: Vec<String>, max_bytes: u64, ) -> Result<Vec<AvatarBytesFfi>, MarmotKitError>
Local-only read, up to 16 references and a 1-byte..16-MiB aggregate byte budget. Results preserve input order; deferred entries can be retried in a later batch.
Marmot::clear_avatar_cache
Current.
pub async fn clear_avatar_cache(&self, account_ref: String) -> Result<(), MarmotKitError>
Clear durable avatar bytes and demand; later visible requests can acquire again.
</details>
<details> <summary>commands/chat_list.rs</summary>
Marmot::chat_list
Lower-level. Raw full list; prepared bounded screens use open_chat_list_window.
pub fn chat_list( &self, account_ref: String, include_archived: bool, ) -> Result<Vec<ChatListRowFfi>, MarmotKitError>
Durable chat-list rows for fast app launch. Rows include the group title/avatar, last kind-9 preview, unread count, and read anchors.
Marmot::chat_list_row
Lower-level. Raw keyed row; selected presentation uses presented_chat_list_row.
pub fn chat_list_row( &self, account_ref: String, group_id_hex: String, ) -> Result<Option<ChatListRowFfi>, MarmotKitError>
Read one hydrated chat-list row for a known group.
Marmot::existing_direct_conversation
Current.
pub async fn existing_direct_conversation( &self, account_ref: String, peer_account_id: String, ) -> Result<Option<ExistingDirectConversationFfi>, MarmotKitError>
Look up the reusable existing direct conversation with peer_account_id.
Marmot::initialize_chat_read_state
Current.
pub fn initialize_chat_read_state( &self, account_ref: String, group_id_hex: String, ) -> Result<Option<ChatListRowFfi>, MarmotKitError>
Establish the unread baseline the first time a user opens a group. Existing kind-9 history remains read; later remote kind-9 messages count until marked visible via mark_timeline_message_read.
Marmot::mark_timeline_message_read
Current.
pub fn mark_timeline_message_read( &self, account_ref: String, group_id_hex: String, message_id_hex: String, ) -> Result<Option<ChatListRowFfi>, MarmotKitError>
Mark a kind-9 timeline message visible/read. Own kind-9 messages can advance the marker too, which clears any earlier unread messages.
Marmot::set_chat_manually_unread
Current.
pub fn set_chat_manually_unread( &self, account_ref: String, group_id_hex: String, manually_unread: bool, ) -> Result<Option<ChatListRowFfi>, MarmotKitError>
Set or clear a manual unread reminder without moving the durable timeline read marker backwards.
Marmot::set_chat_pinned
Current.
pub fn set_chat_pinned( &self, account_ref: String, group_id_hex: String, pinned: bool, ) -> Result<ChatPinStateFfi, MarmotKitError>
Pin or unpin one local chat. Newly pinned chats enter at the top of the manually ordered pinned section.
Marmot::set_pinned_chat_order
Current.
pub fn set_pinned_chat_order( &self, account_ref: String, ordered_group_ids: Vec<String>, ) -> Result<ChatPinStateFfi, MarmotKitError>
Atomically replace the order of the current pinned set. The input must contain every currently pinned group exactly once.
Marmot::chat_notification_settings
Current.
pub fn chat_notification_settings( &self, account_ref: String, group_id_hex: String, ) -> Result<ChatNotificationSettingsFfi, MarmotKitError>
Read the current MDK timed/indefinite mute state for one chat.
Marmot::set_chat_muted
Current.
pub fn set_chat_muted( &self, account_ref: String, group_id_hex: String, muted_until_ms: Option<i64>, ) -> Result<ChatNotificationSettingsFfi, MarmotKitError>
Mute one chat until an absolute Unix epoch millisecond timestamp, or indefinitely when muted_until_ms is None.
Ordinary notification updates stay suppressed, while direct mentions of the receiving account reach subscriptions with NotificationUpdateFfi.is_mention = true; blocked senders remain suppressed. Hosts apply their own notification permission and channel settings.
Marmot::clear_chat_muted
Current.
pub fn clear_chat_muted( &self, account_ref: String, group_id_hex: String, ) -> Result<ChatNotificationSettingsFfi, MarmotKitError>
Clear either a finite or indefinite MDK chat mute.
</details>
<details> <summary>commands/chat_window.rs</summary>
Marmot::open_chat_list_window
Current.
pub async fn open_chat_list_window( &self, account_ref: String, view: ChatListViewFfi, initial_rows: Option<u32>, ) -> Result<Arc<ChatListWindowSubscription>, MarmotKitError>
Bind to one account/view. None defaults to 50; explicit sizes must be 1–100.
Marmot::chat_list_ids
Current.
pub async fn chat_list_ids( &self, account_ref: String, view: ChatListViewFfi, ) -> Result<Vec<String>, MarmotKitError>
Select all: every chat ID in the view, in display order, including chats beyond the open window. The count is the list length. Use it for "select all" and bulk-action counts instead of the window's rows, which are bounded. While base rows are still being prepared it fails with ChatPresentationNotReady rather than returning a partial list; keep the action disabled and retry. The list is a snapshot: keep it as host checkbox state and call revalidate_chat_list_ids before acting.
Marmot::revalidate_chat_list_ids
Current.
pub async fn revalidate_chat_list_ids( &self, account_ref: String, view: ChatListViewFfi, group_ids: Vec<String>, ) -> Result<Vec<String>, MarmotKitError>
The subset of a host selection still in the view, in the caller's order with duplicates dropped. It only removes: chats that joined the view after the selection was read are never added. IDs are normalized to lowercase hex, and a malformed ID fails the call with InvalidHex. Call it right before a bulk action, then run the existing per-chat commands (archive, local delete, leave), which still check their own preconditions; this read does not lock the selection.
Marmot::open_chat_list_query_window
Current.
pub async fn open_chat_list_query_window( &self, account_ref: String, query: ChatListViewQueryFfi, initial_rows: Option<u32>, ) -> Result<Arc<ChatListWindowSubscription>, MarmotKitError>
open_chat_list_window narrowed by a filter: the same subscription, window policy and commands over the chats a ChatListViewQueryFfi matches. The query is a base view plus filter, a flat node list where node 0 is the root and every other node is the child of exactly one node listed before it; an empty list means no filter. All, Any and Not combine Condition leaves (scope, unread, manual unread, mention, pinned, pending leave, disbanding, has draft, pending or failed send, direct or group kind, muted), GroupIds, Text and MessageText; an empty All matches every chat in the view and an empty Any none. A chat whose kind is still Unknown matches neither kind leaf. Muted is evaluated at each read, and a window testing it updates when a mute expires, even for a chat it does not show. Text matches the title, group name, description or a direct chat's peer profile name as a literal substring after trimming and lowercasing both, like user directory search; localized fallback titles are not searchable and blank text matches nothing. While any chat in the view still has presentation pending, a query with Text fails with ChatPresentationNotReady (an open window publishes it and retries) instead of returning part of the set. MessageText matches chats with a visible message containing the text by the same rule: a chat message or poll question the timeline shows, in its latest edit, not deleted, expired or from a blocked account, and not invalidated unless it is an own send shown as failed. Timeline search uses the same rule. It scans message history, so a window refuses it: this call fails with InvalidChatListQuery (MessageTextInWindow) before any read, and only chat_list_query_ids and revalidate_chat_list_query_ids accept it. Folder include/exclude lists are ordinary nodes, for example All[Not(GroupIds(excluded)), Any[GroupIds(included), rule]]. A malformed node list or a query over 8 levels, 64 nodes, 500 group IDs or 1024 bytes of text fails with InvalidChatListQuery before any read; a malformed group ID fails with InvalidHex. Use the same query value for the window, chat_list_query_ids and revalidate_chat_list_query_ids so list, count and selection agree; a query with MessageText has no window.
Marmot::chat_list_query_ids
Current.
pub async fn chat_list_query_ids( &self, account_ref: String, query: ChatListViewQueryFfi, ) -> Result<Vec<String>, MarmotKitError>
Select all for a filtered query: every chat ID the query matches, in display order, beyond the open window, from the same compiled condition the window pages through. Same readiness and snapshot rules as chat_list_ids, and the same query validation as open_chat_list_query_window, except that it accepts MessageText, whose cost grows with message history. A query with MessageText also fails with ChatPresentationNotReady while retained deletions and edits are still being backfilled into the timeline.
Marmot::revalidate_chat_list_query_ids
Current.
pub async fn revalidate_chat_list_query_ids( &self, account_ref: String, query: ChatListViewQueryFfi, group_ids: Vec<String>, ) -> Result<Vec<String>, MarmotKitError>
revalidate_chat_list_ids for a filtered query: the subset of a host selection that still matches, in the caller's order with duplicates dropped, never adding chats. Call it with the query the selection was read under, right before a bulk action.
Marmot::subscribe_account_attention
Current.
pub async fn subscribe_account_attention( &self, ) -> Result<Arc<AccountAttentionSubscription>, MarmotKitError>
Signed-in local/external accounts, independent of any list or active worker.
</details>
<details> <summary>commands/compromise_warning.rs</summary>
Marmot::compromise_warning
Current.
pub async fn compromise_warning( &self, account_ref: String, ) -> Result<Vec<CompromiseWarningItemFfi>, MarmotKitError>
List the account's open compromise warning on this device: each item the user has not seen here, the earliest gathered first. An empty list means no warning is open. An item means someone holding the account's signing key, or a session with its remote signer, published where the account's devices did not: a sign-in answered This wasn't me (RejectedSignIn), or a KeyPackage this device found in its own slot that it did not make (ForeignOwnSlotKeyPackage, with its key_package_ref_hex; only the device that found it warns of it). Later releases add reasons; show one the app does not know as a generic one. The warning gathers this device's rejections and those in its device group's roster, so a rejection made on another device warns here too; rejections already in the first roster this device trusts count as seen. A rejected sign-in leaves the warning once its slot is linked as a device. The app writes the wording, and never says the account's devices stopped them. Read from local state with no network I/O. Always empty without explicit dev capability and runtime intent. Refresh on MarmotEventFfi::CompromiseWarningChanged, which also fires once each time the account's worker opens, so it may fire with no visible change. Runs on the account worker.
Marmot::dismiss_compromise_warning
Current.
pub async fn dismiss_compromise_warning( &self, account_ref: String, ) -> Result<(), MarmotKitError>
Dismiss the compromise warning on this device: everything it gathers now is marked seen here, and it stays closed until a new rejection arrives. Other devices' warnings are unchanged, and a rejection that branch selection drops and brings back stays seen. A refusal is MarmotKitError::Runtime whose details read device group refused: roster_unsupported, while device groups are off. Raises CompromiseWarningChanged when something was marked seen. Runs on the account worker.
</details>
<details> <summary>commands/conversation_window.rs</summary>
Marmot::open_conversation_window
Current.
pub async fn open_conversation_window( &self, account_ref: String, group_id_hex: String, mode: ConversationOpenModeFfi, message_id_hex: Option<String>, initial_rows: Option<u32>, timeout_ms: u32, ) -> Result<Arc<ConversationWindowSubscription>, MarmotKitError>
Open first unread/latest or an explicit message. No implicit mark-read. Zero timeout uses 30 seconds; timeout/cancellation abandons the opening. Mode Message requires a message id; other modes reject one. None rows uses 50.
Marmot::send_message_draft
Current.
pub async fn send_message_draft( &self, account_ref: String, revision: Arc<MessageDraftRevisionFfi>, attachments: Vec<MediaAttachmentReferenceFfi>, ) -> Result<SendSummaryFfi, MarmotKitError>
Submit exactly the selected draft revision. Prepared media must match its descriptors. Clears only on durable acceptance; do not clear again in the host after delivery.
Marmot::selected_message_draft
Current.
pub fn selected_message_draft( &self, account_ref: String, group_id_hex: String, ) -> Result<SelectedMessageDraftFfi, MarmotKitError>
Descriptor-only selected draft with an opaque store/group-scoped revision.
Marmot::clear_message_draft_if_revision
Current.
pub fn clear_message_draft_if_revision( &self, account_ref: String, revision: Arc<MessageDraftRevisionFfi>, ) -> Result<SelectedMessageDraftFfi, MarmotKitError>
Clear only the exact revision the caller observed; handle conflict instead of erasing a newer draft.
Marmot::save_message_draft_if_revision
Current.
pub fn save_message_draft_if_revision( &self, account_ref: String, revision: Arc<MessageDraftRevisionFfi>, content: String, reply_to_message_id_hex: Option<String>, media_attachments: Vec<MessageDraftAttachmentFfi>, ) -> Result<SelectedMessageDraftFfi, MarmotKitError>
Save composer state conditional on the observed revision; use the returned result/revision for subsequent edits.
Marmot::message_draft_attachment_if_revision
Current.
pub fn message_draft_attachment_if_revision( &self, account_ref: String, revision: Arc<MessageDraftRevisionFfi>, attachment_id: String, ) -> Result<Option<Vec<u8>>, MarmotKitError>
Read only the requested local attachment, rejecting a changed selected draft.
</details>
<details> <summary>commands/device_link.rs</summary>
Marmot::cancel_device_link
Current.
pub async fn cancel_device_link( &self, account_ref: String, ) -> Result<DeviceLinkSnapshotFfi, MarmotKitError>
On the new device, request cancellation of the link. This does not guarantee notification of the other device: cancellation while waiting in Joining can end locally without sending a cancellation message. Before an authenticated Welcome is admitted, successful cancellation ends new_device as Ended { reason: Cancelled }. Cancelling while still waiting in Joining first withdraws this device's Welcome expectation; if withdrawal fails, the call returns an error and the current worker retries while that in-memory link remains active. After restart, a failed cancellation is not durably retried; its stored Welcome wait can remain active until its deadline. While that wait remains, a new ordinary link can reach confirmation and then end as LinkFailed. Cancellation does not undo an already-admitted Welcome: an ordinary link can resolve as Linked; for a move, inspect moves for the durable outcome. Refused as MarmotKitError::Runtime with details device group refused: pairing_unsupported unless the explicit experimental build/runtime gates are enabled, or device group refused: no_link_in_progress when no link is in progress.
Marmot::confirm_device_link_match
Current.
pub async fn confirm_device_link_match( &self, account_ref: String, ) -> Result<DeviceLinkSnapshotFfi, MarmotKitError>
On the new device, record that the user says both screens show the same emoji. new_device moves to WaitingForOtherDevice until the other device's user chooses Link device, then Joining while that device adds this one, then Linked once its Welcome arrives. This device joins only through a Welcome into the device group the other device's verified confirmation named, sent by the leaf that confirmation named, and only while the link waits for it. A mismatch is the user's to report: cancel instead. Refused with no_link_in_progress when there is no link to confirm, and ends the link with a reason when the exchange fails a check or time ran out.
Marmot::decline_device_link
Current.
pub async fn decline_device_link( &self, account_ref: String, prompt_id: String, ) -> Result<DeviceLinkSnapshotFfi, MarmotKitError>
On a device already signed in, Not now for the prompt prompt_id: the prompt goes and the new device's link ends with CancelledElsewhere. Refused with unknown_prompt for a stale prompt.
Marmot::device_link_snapshot
Current.
pub async fn device_link_snapshot( &self, account_ref: String, ) -> Result<DeviceLinkSnapshotFfi, MarmotKitError>
Current linking and durable move progress: new_device while this device asked to be linked, prompts for the sign-ins it can link, newest last, and moves as described in move guidance. Each prompt's state says what to show: Preparing while the sign-in's KeyPackage is checked, Comparing with the code, CompetingRequests, RateLimited until retry_at, CannotLink with what its client lacks, TooManyDevices, Linking, Linked, AddedElsewhere ("<device_label> was added by <added_by_label>") or Ended with a reason. Re-read on MarmotEventFfi::DeviceLinkChanged, which also fires each time the account's worker opens or reconnects; unconfirmed comparisons end because their secrets are memory-only, while admitted native/move work keeps its durable owner. Refused when the explicit experimental build/runtime gates are disabled (pairing_unsupported). Runs on the account worker and sends what linking owes.
Marmot::dismiss_device_group_move_sibling
pub async fn dismiss_device_group_move_sibling( &self, account_ref: String, move_id: String, slot_id_hex: String, ) -> Result<DeviceLinkSnapshotFfi, MarmotKitError>
End one local old-sibling recognition hint from device_link_snapshot().moves. Pass its opaque move_id and the
hint's slot_id_hex; this neither links, removes nor trusts the sibling. The returned snapshot reflects the hint.
Refused when device linking is disabled or the move/sibling is unknown. Refresh on DeviceLinkChanged; see
move guidance.
Marmot::link_device
Current.
pub async fn link_device( &self, account_ref: String, prompt_id: String, label: String, add_to_all_chats: bool, bring_history: bool, ) -> Result<DeviceLinkSnapshotFfi, MarmotKitError>
On a device already signed in, Link device for the prompt prompt_id, offered while its state is Comparing. label is the name the user gave the new device: not blank, at most 64 bytes (label_invalid). Offer add_to_all_chats and bring_history as toggles, both on by default. The prompt moves to Linking until the new device's confirmation verifies; then this device creates the account's device group on a first link, or adds the new device to the one it trusts, in one commit that also writes its roster entry. That commit is the approval. Its Welcome goes out only once relays confirm the commit, and the prompt remains Linking until the new device's first selected own change is present; a Welcome not taken by relays remains under its existing bounded delivery owner. A commit whose publish is retried keeps the prompt Linking. A device group that is still settling makes this device retry while the new device waits for its Welcome. A commit that rolls back, or a link not confirmed before the new device stops waiting, ends the prompt with LinkFailed. Refused with unknown_prompt for a stale prompt, including one from before the client reopened, link_unavailable while more than one sign-in competes or the code is not shown, device_already_linked, sign_in_rejected when its sign-in was rejected after the prompt appeared (the prompt then ends Rejected), or too_many_devices at 20 devices (remove one first).
Marmot::reset_device_group_for_repair
Current.
pub async fn reset_device_group_for_repair( &self, account_ref: String, ) -> Result<DeviceLinkSnapshotFfi, MarmotKitError>
After explicit user confirmation, discard only this device's quiet trusted hidden device-group copy before fresh code pairing. Keeps ordinary chat data, drafts/settings, account credentials and stable slot; abandons old link-bound preparations, while shared values and security decisions retain their ordinary synchronization rules. This sends no removal, authenticates no device and repairs no chat membership. Active pairing/Move or unsettled native work returns device_group_busy without a deadline; no trusted copy returns no_device_group. An unlinked device cannot bypass removal. Cancellation after reset restores nothing, while a fresh already-confirmed link keeps its ordinary durable Welcome wait. Duplicate membership, rejection and capacity can still refuse the new link. Requires the explicit experimental capability/constructor; see the shared reset contract.
Marmot::start_device_link
Current.
pub async fn start_device_link( &self, account_ref: String, ) -> Result<DeviceLinkSnapshotFfi, MarmotKitError>
Ask a device of this account already signed in to link this one, returning its current comparison state. If this device already trusts a different device group, the same flow moves only this device; keep showing the old trust until snapshot.moves reports Made, as described in move guidance. The request names this device's published KeyPackage, never one this device already joined a group by, so publish one first, and again after such a join (key_package_not_published). new_device starts at WaitingForAnswer: ask the user to open the app on a device already signed in. Once one answers it moves to Comparing with the seven emoji both screens show, each with an English description for screen readers; offer "They match" (confirm_device_link_match) and cancel (cancel_device_link). Refresh on MarmotEventFfi::DeviceLinkChanged. Refused with MarmotKitError::Runtime (details device group refused: <reason>) while a link is in progress (pairing_in_progress) or the explicit experimental build/runtime gates are disabled (pairing_unsupported). Runs on the account worker and sends one gift-wrapped request to the account's relays.
</details>
<details> <summary>commands/directory.rs</summary>
Marmot::display_name
Current.
pub fn display_name(&self, account_id_hex: String) -> Option<String>
Best-effort cached display name for an account id. Returns the Nostr kind:0 display_name/name when the runtime has projected one, or the local account label if the id refers to one of our own accounts. None when nothing is known yet — call refresh_profile to fetch.
Marmot::npub
Current.
pub fn npub(&self, account_id_hex: String) -> Option<String>
Convert a hex account id (Nostr public key) into its npub… bech32 form for display. None if the hex isn't a valid public key.
Marmot::account_id_hex
Current.
pub fn account_id_hex(&self, reference: String) -> Option<String>
Normalize a public-key reference (hex, npub, nostr:npub, nprofile, nostr:nprofile, or a marmot://profile/ link) to canonical hex. None if it isn't a valid public identity reference. nprofile relay hints are discarded. Duplicate type-0 TLV entries keep the first key. After wrapper normalization, the nprofile fallback rejects encoded tokens longer than 1023 UTF-8 bytes; a valid 1023-byte token still decodes when wrapped. Used to resolve a scanned or deep-linked mention back to the account id the rest of the API expects.
Marmot::default_profile_pseudonym
Current.
pub fn default_profile_pseudonym(&self, account_id_hex: String) -> String
Deterministic cosmetic display name for a canonical hex account id.
Marmot::random_profile_pseudonym
Current.
pub fn random_profile_pseudonym(&self) -> String
Random cosmetic display name from the shared wordlists.
Marmot::parse_markdown
Current.
pub fn parse_markdown(&self, text: String) -> MarkdownDocumentFfi
Parse plaintext message content into the same Markdown AST returned on message and timeline records. Useful for draft previews and host-side fallback rendering.
Local-time timestamps are MarkdownInlineFfi::Timestamp { unix_seconds: i64, style: MarkdownTimestampStyleFfi }, preserving signed seconds and a typed style rather
than formatted text. The nine styles are ShortTime, LongTime, ShortDate,
LongDate, ShortDateTime (the parser's default), LongDateTime, CompactDateTime,
CompactDateTimeSeconds and Relative. Invalid syntax remains literal text.
Hosts format using the device locale/timezone at render time, refresh after
locale/timezone/clock changes and resume, and refresh visible Relative nodes as
time passes. See Markdown rendering for the style
mapping and optional absolute-time tooltip/accessibility guidance.
Marmot::user_profile
Current.
pub fn user_profile( &self, account_id_hex: String, ) -> Result<Option<UserProfileMetadataFfi>, MarmotKitError>
Full cached Nostr kind:0 profile for an account id (name, display name, about, picture, nip05, lud16), if the runtime has one projected. The local account's own profile is cached immediately after publish_user_profile from the submitted value, without reparsing it. Other accounts' profiles populate via refresh_profile / refresh_directory and are sanitized on ingest: about keeps normalized LF line breaks, and every other known string stays single-line. Tab and other controls (NUL, ESC, BEL, DEL, C1) are removed. A cached bio flattened by an older build stays until a newer event replaces it; an equal timestamp does not. Returns None when nothing is cached yet.
Marmot::cached_identity_projections
Current.
pub fn cached_identity_projections( &self, account_id_hexes: Vec<String>, ) -> Result<Vec<CachedIdentityProjectionFfi>, MarmotKitError>
Bounded local cached-identity page for many account IDs.
Marmot::user_profile_website
Current.
pub fn user_profile_website( &self, account_id_hex: String, ) -> Result<Option<String>, MarmotKitError>
Cached Nostr kind:0 website metadata for an account id, when it is a string. The generic profile record intentionally exposes the fields the host can publish; this read-only accessor preserves arbitrary kind:0 metadata while still making the standard website field available to profile presentation surfaces.
Marmot::refresh_profile
Current.
pub async fn refresh_profile( &self, account_id_hex: String, relays: Vec<String>, ) -> Result<(), MarmotKitError>
Fetch and cache an account's own Nostr kind:0 profile from relays. After this resolves, user_profile / display_name return the freshly-fetched metadata (name, picture, etc.) for that account.
Marmot::user_relay_lists
Current.
pub fn user_relay_lists( &self, account_id_hex: String, ) -> Result<conversions::AccountRelayListsFfi, MarmotKitError>
Cached NIP-65 and inbox relay lists for any account id — no network. An account with nothing cached yet returns an empty status with both kinds in missing rather than erroring; call refresh_user_relay_lists to fetch.
Marmot::refresh_user_relay_lists
Current.
pub async fn refresh_user_relay_lists( &self, account_id_hex: String, relays: Vec<String>, ) -> Result<conversions::AccountRelayListsFfi, MarmotKitError>
Fetch an account's published NIP-65 and inbox relay lists from relays, updating the cache. An account with nothing published reports both kinds in missing rather than erroring.
Marmot::search_cached_users
Current.
pub fn search_cached_users( &self, account_id_hex: String, query: String, limit: u32, ) -> Result<Vec<conversions::UserDirectorySearchResultFfi>, MarmotKitError>
Search public identities cached through any connected account, without network or group-membership work. Follow flags refer only to the selected searcher. Call off the UI thread; zero limit returns no rows.
Marmot::search_users
Current.
pub async fn search_users( &self, account_id_hex: String, query: String, radius_start: u8, radius_end: u8, ) -> Result<Arc<UserSearchSubscription>, MarmotKitError>
Stream cached public identities across accounts, then independent provider and graph results. The radius window bounds known social distances; cached/provider identities without a known distance remain discoverable. Those identities can recur when paging radii: deduplicate by account id across pages as well as within each subscription.
</details>
<details> <summary>commands/draft.rs</summary>
Marmot::message_drafts
Current.
pub fn message_drafts( &self, account_ref: String, ) -> Result<Vec<MessageDraftSummaryFfi>, MarmotKitError>
Metadata-only saved composer drafts for an account, newest-updated first. Attachment plaintext is intentionally omitted from this list; call messageDraft when restoring one selected composer. Hosts must delete empty or sent drafts; deleting a group also removes its draft.
Marmot::message_draft
Compatibility. Prefer selected_message_draft for the revisioned composer.
pub fn message_draft( &self, account_ref: String, group_id_hex: String, ) -> Result<Option<MessageDraftFfi>, MarmotKitError>
The saved composer draft for an account and MLS group, if one exists.
Marmot::save_message_draft
Compatibility. Prefer save_message_draft_if_revision for concurrent composer safety.
pub fn save_message_draft( &self, account_ref: String, group_id_hex: String, content: String, reply_to_message_id_hex: Option<String>, media_attachments: Vec<MessageDraftAttachmentFfi>, ) -> Result<MessageDraftFfi, MarmotKitError>
Upsert a composer draft into the account's encrypted SQLCipher store.
Marmot::delete_message_draft
Compatibility. Prefer clear_message_draft_if_revision for concurrent composer safety.
pub fn delete_message_draft( &self, account_ref: String, group_id_hex: String, ) -> Result<(), MarmotKitError>
Delete a saved composer draft. This is a no-op when no draft exists.
</details>
<details> <summary>commands/group.rs</summary>
Marmot::prewarm_group_member_key_packages
Current.
pub async fn prewarm_group_member_key_packages( &self, account_ref: String, member_refs: Vec<String>, ) -> Result<MemberKeyPackagePrewarmSummaryFfi, MarmotKitError>
Resolve the current composition roster before Create is tapped. The result is aggregate-only; no package is reserved or consumed, and the later create call revalidates cached packages before MLS mutation.
Marmot::start_direct_conversation
Current. Recommended for an explicit direct-chat start.
pub async fn start_direct_conversation( &self, account_ref: String, peer_account_id: String, ) -> Result<String, MarmotKitError>
Accepts a hex or npub peer identity. The account worker serializes lookup and creation, reusing the deterministic local direct-conversation selection or creating an unnamed group with both accounts as founding admins. Reuse preserves existing roles without an admin-policy commit.
The returned string encodes the canonical opaque MLS group id as hex. Success confirms local creation or reuse, not Welcome delivery. Retained Welcome delivery continues independently. Cancellation detaches the wait without cancelling admitted work. Retry after response loss or delayed projection recovers and reuses the canonical engine group. If a matching canonical group is eligible for reuse but cannot hydrate, retry returns an error rather than creating another group. Removed and disbanded copies do not block a fresh start. Same-account concurrent starts return one local group. Simultaneous starts by different accounts can produce two groups, each with both accounts as admins.
No immutable cross-client DM provenance exists, so legacy and generic groups keep their authoritative roles. An unnamed two-member roster does not authorize automatic repair. Generic creator-only clients remain interoperable but produce asymmetric groups until they adopt this operation. A non-admin recipient cannot self-promote.
Marmot::create_group
Current.
pub async fn create_group( &self, account_ref: String, name: String, member_refs: Vec<String>, description: Option<String>, ) -> Result<GroupCreationResultFfi, MarmotKitError>
Create an MLS group with name and the available members (npub or hex account id). Returns an optional group_id_hex and ordered per-account outcomes. A nonempty request with no available members returns no group id and creates no group; empty member input still creates a creator-only group. A present id confirms local canonicalization, not Welcome delivery. WelcomeDeliveryPending is a delivery-failure signal, not an acknowledgement. Subscribe before creation and/or query pending_welcome_deliveries afterward before presenting invitation success.
Marmot::create_group_with_options
Current.
pub async fn create_group_with_options( &self, account_ref: String, name: String, member_refs: Vec<String>, options: CreateGroupOptionsFfi, ) -> Result<GroupCreationResultFfi, MarmotKitError>
Create a group with founding options, returning the same optional group id and ordered member outcomes as create_group. A nonzero retention value is written into the founding MLS state and Welcome; it does not emit a follow-up retention commit or publication.
Marmot::create_group_detailed
Current.
pub async fn create_group_detailed( &self, account_ref: String, name: String, member_refs: Vec<String>, description: Option<String>, ) -> Result<DetailedGroupCreationResultFfi, MarmotKitError>
Return ordered member outcomes and an optional created group containing the exact durable chat-list row available at the response boundary. created is absent when a nonempty request has no available members.
Marmot::create_group_with_options_detailed
Current.
pub async fn create_group_with_options_detailed( &self, account_ref: String, name: String, member_refs: Vec<String>, options: CreateGroupOptionsFfi, ) -> Result<DetailedGroupCreationResultFfi, MarmotKitError>
Create a group with founding options, returning ordered member outcomes and an optional created group with the durable chat-list row. No group is created when a nonempty request has no available members.
Marmot::create_group_with_initial_image
Current.
pub async fn create_group_with_initial_image( &self, account_ref: String, name: String, member_refs: Vec<String>, description: Option<String>, initial_image: Option<InitialGroupImageFfi>, ) -> Result<GroupCreationResultFfi, MarmotKitError>
Create a group with an optional initial avatar, returning the same optional group id and ordered member outcomes as create_group. MDK prefers an encrypted Blossom image and uses source_url only when the selected founding members do not all support that component but do support URL avatars.
Marmot::stage_prepared_group_image
Current.
pub async fn stage_prepared_group_image( &self, account_ref: String, plaintext: Vec<u8>, media_type: String, ) -> Result<PreparedGroupImageUploadFfi, MarmotKitError>
Validate and durably encrypt a founding image without performing any network transfer. The opaque id survives process restart; keys, ciphertext, and the content hash stay inside MDK's SQLCipher database.
Marmot::upload_prepared_group_image
Current.
pub async fn upload_prepared_group_image( &self, account_ref: String, upload_id: String, ) -> Result<PreparedGroupImageUploadFfi, MarmotKitError>
Upload a staged founding image. A transfer failure is returned as an error after its failed status is durably recorded, and can be retried with the same id; an already uploaded id performs no duplicate HTTP transfer.
Marmot::prepared_group_image_status
Current.
pub async fn prepared_group_image_status( &self, account_ref: String, upload_id: String, ) -> Result<PreparedGroupImageUploadFfi, MarmotKitError>
Read one prepared group-image operation status.
Marmot::prepared_group_images
Current.
pub async fn prepared_group_images( &self, account_ref: String, ) -> Result<Vec<PreparedGroupImageUploadFfi>, MarmotKitError>
List prepared group-image operations.
Marmot::create_group_with_prepared_initial_image
Current.
pub async fn create_group_with_prepared_initial_image( &self, account_ref: String, name: String, member_refs: Vec<String>, description: Option<String>, upload_id: String, ) -> Result<GroupCreationResultFfi, MarmotKitError>
Create with an already-uploaded upload_id; the image component is present in epoch-zero metadata and no Blossom request occurs on this call. Returns an optional group id and ordered member outcomes. Reusing a consumed id returns its original canonical group and stored selection report, not newly resolved input. A legacy, corrupt, or unsupported report returns CreatedGroupMemberReportUnavailable with the canonical group id rather than inventing outcomes or creating a duplicate.
Marmot::create_group_with_initial_image_detailed
Current.
pub async fn create_group_with_initial_image_detailed( &self, account_ref: String, name: String, member_refs: Vec<String>, description: Option<String>, initial_image: Option<InitialGroupImageFfi>, ) -> Result<DetailedGroupCreationResultFfi, MarmotKitError>
Create a group with an initial image, returning ordered member outcomes and an optional created group with the durable chat-list row. No group is created when a nonempty request has no available members.
Marmot::normalize_member_ref
Current.
pub fn normalize_member_ref(&self, member_ref: String) -> Result<MemberRefFfi, MarmotKitError>
Normalize a member reference for group-management UI. Accepts hex, npub, nostr:npub..., nprofile, nostr:nprofile..., and marmot://profile/... references. nprofile relay hints are discarded and never used for routing or membership authorization. Duplicate type-0 TLV entries keep the first key. After wrapper normalization, the nprofile fallback rejects encoded tokens longer than 1023 UTF-8 bytes; a valid 1023-byte token still decodes when wrapped.
Marmot::group_members
Current.
pub async fn group_members( &self, account_ref: String, group_id_hex: String, ) -> Result<Vec<AppGroupMemberRecordFfi>, MarmotKitError>
Membership roster for group_id_hex: one row per member account, with how many of its devices are in the group (device_count). An account with several devices is one member.
Marmot::group_member_ids_page
Current.
pub async fn group_member_ids_page( &self, account_ref: String, group_ids_hex: Vec<String>, ) -> Result<Vec<AppGroupMemberIdsFfi>, MarmotKitError>
Identifier-only rosters for a bounded page of groups. Each member account appears once, however many devices it has in the group.
Marmot::group_details
Current.
pub async fn group_details( &self, account_ref: String, group_id_hex: String, ) -> Result<GroupDetailsFfi, MarmotKitError>
Group plus enriched member rows for detail screens, one per member account with its device_count. Admin counts and last-admin checks therefore count accounts.
Marmot::group_conversation_snapshot
Current.
pub async fn group_conversation_snapshot( &self, account_ref: String, group_id_hex: String, ) -> Result<GroupConversationSnapshotFfi, MarmotKitError>
Group details and management state captured for conversation loading in one worker command. The authoritative group record, roster, and MLS state share one session/snapshot frontier; management state is derived from those exact returned details without another await.
Marmot::group_roster
Current.
pub async fn group_roster( &self, account_ref: String, group_id_hex: String, ) -> Result<GroupRosterFfi, MarmotKitError>
Lightweight membership roster projection for membership screens: one entry per member account with its device_count, and member_count counts accounts.
Marmot::group_management_state
Current.
pub async fn group_management_state( &self, account_ref: String, group_id_hex: String, ) -> Result<GroupManagementStateFfi, MarmotKitError>
Current caller permissions plus per-member action availability.
Marmot::enable_group_disbanding
Current.
pub async fn enable_group_disbanding( &self, account_ref: String, group_id_hex: String, ) -> Result<GroupMutationResultFfi, MarmotKitError>
Install lifecycle-v1 and require it in one admin Commit.
Marmot::account_devices_activation
Current.
pub async fn account_devices_activation( &self, account_ref: String, group_id_hex: String, ) -> Result<AccountDevicesActivationFfi, MarmotKitError>
Whether the account can turn on account-devices in the group now, so its own devices can later add and remove each other there without an admin. Ask before offering enable_account_devices, and show the reason when it is not Eligible. The answer is about the whole group and never names the members or devices that hold it back; a non-admin only learns NotAdmin. It is advisory: enable_account_devices checks again.
Marmot::enable_account_devices
Current.
pub async fn enable_account_devices( &self, account_ref: String, group_id_hex: String, ) -> Result<GroupMutationResultFfi, MarmotKitError>
Turn on account-devices (marmot.group.account-devices.v1) in one admin Commit. Call it only when the user asks: MDK never turns it on by itself, and a group can never turn it off. Refused before anything is published with AccountDevicesActivationRefused, carrying the same aggregate reason, unless account_devices_activation would answer Eligible.
Marmot::disband_group
Current.
pub async fn disband_group( &self, account_ref: String, group_id_hex: String, ) -> Result<DisbandRequestFfi, MarmotKitError>
Durably accept an irreversible disband request. Completion is observed through normal group state updates after bounded convergence.
Marmot::acknowledge_disband_failure
Current.
pub async fn acknowledge_disband_failure( &self, account_ref: String, group_id_hex: String, ) -> Result<bool, MarmotKitError>
Acknowledge the recorded group-disband failure.
Marmot::invite_members
Current.
pub async fn invite_members( &self, account_ref: String, group_id_hex: String, member_refs: Vec<String>, ) -> Result<InviteMembersResultFfi, MarmotKitError>
Invite the available accounts in member_refs into one Commit, returning ordered per-account outcomes. summary is absent for nonempty all-unavailable input; no Commit is created. Selection is not Welcome delivery. Empty input, native membership-edit refusals, authorization, and global runtime failures remain errors.
Marmot::invite_members_with_initial_admins
Current.
pub async fn invite_members_with_initial_admins( &self, account_ref: String, group_id_hex: String, member_refs: Vec<String>, initial_admin_refs: Vec<String>, ) -> Result<InviteMembersResultFfi, MarmotKitError>
Invite available accounts in member_refs and grant admin to selected accounts named in initial_admin_refs in the same Commit. Every initial admin must be a requested invitee; unavailable invitees receive no role. Returns the same optional summary and ordered member outcomes as invite_members.
Marmot::remove_members
Current.
pub async fn remove_members( &self, account_ref: String, group_id_hex: String, member_refs: Vec<String>, ) -> Result<SendSummaryFfi, MarmotKitError>
Request removal of selected members; use the detailed variant for operation outcomes.
Marmot::leave_group
Current.
pub async fn leave_group( &self, account_ref: String, group_id_hex: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Queue leaving a group; retained local history is separate from membership. An admin gets AdminCannotSelfRemove until self_demote_admin (requires_self_demote_before_leave); only the experimental device-groups constructor demotes a nonlast admin itself.
Marmot::cancel_leave
Current.
pub async fn cancel_leave( &self, account_ref: String, group_id_hex: String, ) -> Result<(), MarmotKitError>
Cancel this account's blocked leave, on this device only. A leave is blocked when the selected branch makes the account the group's last active admin, so no Commit can finish it; the chat keeps reading as leaving (leave_request_pending) with leave_blocked set, and hosts offer Cancel while GroupManagementStateFfi::can_cancel_leave holds. Cancel makes the chat joined again and the account can send. While the group is still settling, or in any other state, it returns LeaveNotBlocked; read the state again before offering Cancel. With experimental device groups on, it leaves the shared Decline alone, so each linked device cancels its own leave.
Marmot::forget_group_local
Current.
pub async fn forget_group_local( &self, account_ref: String, group_id_hex: String, ) -> Result<bool, MarmotKitError>
Reset a group on this account-device, without sending an MLS leave or disband. Erases local history and protocol state, cancels group work, and rejects old welcomes. A valid Welcome whose authenticated inner creation time is strictly newer than the reset's Unix-second cutoff can join the same group with fresh state. Equal-second invitations are rejected; receipt time and outer wrapper time do not establish freshness. Hosts should close the group's UI subscriptions and clear their media caches. Returns true when resetting, false when already awaiting a fresh Welcome.
Marmot::delete_group_local
Current.
pub async fn delete_group_local( &self, account_ref: String, group_id_hex: String, ) -> Result<bool, MarmotKitError>
Delete this group's local app data without performing an MLS leave. The caller should cancel any active UI subscriptions for the group before invoking the wipe. The runtime removes the active transport route, then transactionally drops the chat-list/account projection, plaintext app events, timeline rows, agent-stream projection rows, push-token rows, and cached encrypted-media epoch secrets. MLS/OpenMLS group state is left intact; a future fresh group delivery can recreate a local chat row. Returns true if any local rows or a live route were removed.
Marmot::group_app_component
pub async fn group_app_component( &self, account_ref: String, group_id_hex: String, component_id: u16, ) -> Result<Option<GroupAppComponentFfi>, MarmotKitError>
Current.
Read one application-owned group component from local committed MLS state. None is absence; a record with empty data is present empty state. component_id must be at or above APP_OWNED_APP_COMPONENT_ID_START (0xf000), otherwise InvalidAppComponent is returned; use the typed profile, image, retention and policy APIs for protocol settings. The protocol registry allocates upward from 0x8001, so an id picked merely because it is unassigned today can be taken by a later registry entry — applications allocate inside the application range instead, and version their own payloads. Reads are serialized through the account worker and may wait behind an in-flight mutation, so refresh after group events (including EpochChanged and convergence) and after local updates.
Marmot::update_app_component
pub async fn update_app_component( &self, account_ref: String, group_id_hex: String, component_id: u16, data: Vec<u8>, ) -> Result<SendSummaryFfi, MarmotKitError>
Current.
Replace one optional application-owned component through an admin-authorized MLS commit. Ids below APP_OWNED_APP_COMPONENT_ID_START (0xf000), components the group requires, and data longer than APP_COMPONENT_DATA_MAX_LEN (4096 bytes) are rejected with InvalidAppComponent. Before staging, the engine rejects updates whose resulting application-owned state exceeds 32 entries or 8192 encoded bytes (including entry ids and TLS payload length prefixes). Replacements count once; empty values still occupy a slot. The value is re-encoded into the GroupContext of every later commit and into every Welcome, so this is a settings channel rather than a blob store. Empty data stores an empty payload; it does not remove the component. The value survives message expiry and reaches newly invited members in their Welcome without sharing earlier application-message history, and unsupported clients preserve the bytes without interpreting them. Publication and convergence semantics match other group mutations: handle publication uncertainty and GroupChangeSuperseded rather than assuming a local change wins every later concurrent commit. The runtime does not retry an application's desired value.
Marmot::update_message_retention
Current.
pub async fn update_message_retention( &self, account_ref: String, group_id_hex: String, disappearing_message_secs: u64, ) -> Result<SendSummaryFfi, MarmotKitError>
Set the per-group disappearing-message retention, wrapping the engine's update_message_retention. disappearing_message_secs of 0 disables expiry; any positive value is the retention window in seconds. Thin passthrough over the already-public engine API (mdk#571).
Marmot::acknowledge_group_catching_up
Current.
pub async fn acknowledge_group_catching_up( &self, account_ref: String, group_id_hex: String, ) -> Result<bool, MarmotKitError>
Call only after a group change failed with GroupCatchingUp and the user chose to continue anyway. The group may have moved past this device, so the change can split the group for everyone (mdk#2258). Records the acknowledgement for the group at the device's current epoch, then retry the original change. It admits exactly one change attempt and is consumed even if that attempt fails, so a different change asks again. It is not persisted, so a restarted app asks again too. Returns false, recording nothing, when the group is not catching up. It is a separate call rather than a flag on every group-change method, and it is distinct from dismiss_history_notice, which accepts missing history, not fork risk. Runs on the account worker; no network I/O.
Marmot::acknowledge_group_commit_undelivered
Current.
pub async fn acknowledge_group_commit_undelivered( &self, account_ref: String, group_id_hex: String, ) -> Result<bool, MarmotKitError>
Call only after a group change failed with GroupCommitUndelivered and the user chose to continue anyway. A change of yours confirmed on its first relay acknowledgement but some group relays have not accepted it, or a group relay refused it for good, so members who read only those relays may not have it, or the new change built on it (mdk#2255, mdk#2333). Dismisses every relay refusal in the group for good: group_commit_delivery stops listing them and they no longer gate, across restarts too. It also records the acknowledgement for the changes owed or refused now; retry the original change. That admits exactly one change attempt and is consumed even if that attempt fails, so a different change asks again, and it is not persisted. A change that starts gating afterwards, such as a new refusal, asks again. Returns false, recording nothing, when no relay is owed or has refused a change of yours. Distinct from acknowledge_group_catching_up; a change can need both. Hosts can also call it from a "dismiss" action on the refusal warning. Runs on the account worker; no network I/O.
Marmot::group_commit_delivery
Current.
pub async fn group_commit_delivery( &self, account_ref: String, group_id_hex: String, ) -> Result<Option<GroupCommitDeliveryFfi>, MarmotKitError>
Returns the group's oldest change of yours that a group relay refused, until the user acknowledges it, or else the oldest change some group relays have not accepted yet; None once no relay is owed a change of yours and every relay refusal has been acknowledged (mdk#2255, mdk#2333). owed_relay_urls lists the relays MDK is still retrying with the exact event. refused_relays lists the relays that refused the change for good, each with its cause: TooLarge (the relay's size answer, its known limit, or the 64 KiB commit floor at a relay of unknown limit; size_class when known) or Rejected (any other final answer). MDK will not deliver it there, and members who read only those relays may not have it; a refusal never says the relay lacks the change. Say, for example, "relay X refused a change of yours: too large". since is when the first relay accepted the change, in Unix seconds. A newer change can be owed to other relays as well. Both are reported immediately, so use it to show the warning proactively. A refusal makes group changes fail with GroupCommitUndelivered at once, until acknowledged. With only owed relays, Some alone does not mean the next change fails: group changes fail only once since is two minutes old, because a healthy relay cut off at the first acknowledgement is retried after 30 seconds. What a host can offer: proceed (acknowledge_group_commit_undelivered), or ask an admin to change the group's relays. No event announces delivery completing, so poll while the indicator is visible. Local read on the account worker; no network I/O.
Marmot::pending_welcome_deliveries
Current.
pub async fn pending_welcome_deliveries( &self, account_ref: String, ) -> Result<Vec<crate::conversions::PendingWelcomeDeliveryFfi>, MarmotKitError>
Return the account's retained Welcome repair handles in oldest-first order after a locally canonical create or confirmed Add. This is a local account-worker read, not a new invitation or network retry. size_class explains an observed all-target refusal; earlier legacy exposure can be unknown after a crash or expired bookkeeping. Neither a present class nor None proves delivery or non-delivery; None means Unknown, including legacy rows or a later coarse legacy retry. A specific cause can disappear while the same debt remains. recorded_at is the local repair-index timestamp in Unix seconds, not proof that the recipient joined. The pending event stays once per process/Welcome; re-read this query for later causes. Use the matching regenerated bindings/native library. See Welcome delivery and compatibility.
Marmot::group_recovery_status
Current.
pub async fn group_recovery_status( &self, account_ref: String, group_id_hex: String, ) -> Result<crate::conversions::GroupRecoveryStatusFfi, MarmotKitError>
Re-read on GroupStateUpdated; display uncertainty separately from whether the user accepted the original invitation. history_may_be_incomplete and history_notice_ids report recovery parked on this group's own history; account-wide occurrences are listed only by history_notices, and each id can be passed to dismiss_history_notice.
Marmot::confirm_group_rejoin
Current.
pub async fn confirm_group_rejoin( &self, account_ref: String, welcome_id_hex: String, local_state_token: String, ) -> Result<crate::conversions::GroupRecoveryStatusFfi, MarmotKitError>
Call only after explicit user consent to replace the active copy. Show the offer's authenticated inviter and pass its exact id and state token.
Marmot::decline_group_rejoin
Current.
pub async fn decline_group_rejoin( &self, account_ref: String, welcome_id_hex: String, ) -> Result<(), MarmotKitError>
Decline a proposed recovery rejoin.
Marmot::accept_group_invite
Current.
pub async fn accept_group_invite( &self, account_ref: String, group_id_hex: String, ) -> Result<AppGroupRecordFfi, MarmotKitError>
Accept a pending group invitation.
Marmot::decline_group_invite
Current.
pub async fn decline_group_invite( &self, account_ref: String, group_id_hex: String, ) -> Result<GroupInviteDeclineResultFfi, MarmotKitError>
Decline a pending group invitation. An invitee the invite made an admin gets AdminCannotSelfRemove until self_demote_admin (requires_self_demote_before_leave), unless the experimental device-groups constructor is used.
Marmot::update_group_profile
Current.
pub async fn update_group_profile( &self, account_ref: String, group_id_hex: String, name: Option<String>, description: Option<String>, ) -> Result<SendSummaryFfi, MarmotKitError>
Update the group name and description.
Marmot::update_group_image
Current.
pub async fn update_group_image( &self, account_ref: String, group_id_hex: String, plaintext: Vec<u8>, media_type: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Encrypt and upload a group avatar to Blossom, then commit the marmot.group.blossom.image.v1 component. plaintext must contain the decoded image bytes; use clear_group_image to remove an existing encrypted Blossom avatar.
Marmot::clear_group_image
Current.
pub async fn clear_group_image( &self, account_ref: String, group_id_hex: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Clear the group's encrypted Blossom avatar by committing the absent marmot.group.blossom.image.v1 component state.
Marmot::download_group_blossom_image
Compatibility. Prefer avatar asset request/read for visible screen metadata.
pub async fn download_group_blossom_image( &self, account_ref: String, group_id_hex: String, ) -> Result<Vec<u8>, MarmotKitError>
Fetch and decrypt the group's encrypted Blossom avatar (marmot.group.blossom.image.v1) into raw image bytes (PNG/JPEG/…). Errors when the group has no Blossom image set. Presence and the content hash (for caching) are on AppGroupRecordFfi::image_hash_hex; when the group also carries a URL avatar, the URL takes precedence for rendering.
Marmot::update_group_avatar_url
Current.
pub async fn update_group_avatar_url( &self, account_ref: String, group_id_hex: String, url: Option<String>, dim: Option<String>, thumbhash: Option<String>, ) -> Result<SendSummaryFfi, MarmotKitError>
Set (or clear, with url = None) the group's URL-based avatar (marmot.group.avatar-url.v1). The URL is validated (https-only, no localhost/private hosts) and normalized before it is committed.
Marmot::replace_encrypted_media_blob_endpoints
Current.
pub async fn replace_encrypted_media_blob_endpoints( &self, account_ref: String, group_id_hex: String, endpoints: Vec<AppBlobEndpointFfi>, ) -> Result<SendSummaryFfi, MarmotKitError>
Replace the group's encrypted-media default blob endpoints as a full marmot.group.encrypted-media.v1 component update. Requires the caller to be an admin.
Marmot::promote_admin
Current.
pub async fn promote_admin( &self, account_ref: String, group_id_hex: String, member_ref: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Grant admin rights to member_ref (npub or hex). Requires the caller to be an admin; publishes a group state update.
Marmot::demote_admin
Current.
pub async fn demote_admin( &self, account_ref: String, group_id_hex: String, member_ref: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Revoke member_ref's admin rights.
Marmot::self_demote_admin
Current.
pub async fn self_demote_admin( &self, account_ref: String, group_id_hex: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Step down as an admin of group_id_hex (demote the active account).
Marmot::invite_members_detailed
Current.
pub async fn invite_members_detailed( &self, account_ref: String, group_id_hex: String, member_refs: Vec<String>, ) -> Result<GroupInviteResultFfi, MarmotKitError>
Return the optional invitation summary and ordered member outcomes together with refreshed group details and management state. The snapshots remain available when the invitation is a no-op.
Marmot::invite_members_detailed_with_initial_admins
Current.
pub async fn invite_members_detailed_with_initial_admins( &self, account_ref: String, group_id_hex: String, member_refs: Vec<String>, initial_admin_refs: Vec<String>, ) -> Result<GroupInviteResultFfi, MarmotKitError>
Return the same invitation result as invite_members_with_initial_admins, plus refreshed group details and management state, including when the invitation is a no-op.
Marmot::remove_members_detailed
Current.
pub async fn remove_members_detailed( &self, account_ref: String, group_id_hex: String, member_refs: Vec<String>, ) -> Result<GroupMutationResultFfi, MarmotKitError>
Remove selected members and return detailed operation outcome.
Marmot::promote_admin_detailed
Current.
pub async fn promote_admin_detailed( &self, account_ref: String, group_id_hex: String, member_ref: String, ) -> Result<GroupMutationResultFfi, MarmotKitError>
Promote selected members and return detailed operation outcome.
Marmot::demote_admin_detailed
Current.
pub async fn demote_admin_detailed( &self, account_ref: String, group_id_hex: String, member_ref: String, ) -> Result<GroupMutationResultFfi, MarmotKitError>
Demote selected administrators and return detailed operation outcome.
Marmot::self_demote_admin_detailed
Current.
pub async fn self_demote_admin_detailed( &self, account_ref: String, group_id_hex: String, ) -> Result<GroupMutationResultFfi, MarmotKitError>
Demote the current account and return detailed operation outcome.
Marmot::group_mls_state
Current.
pub async fn group_mls_state( &self, account_ref: String, group_id_hex: String, ) -> Result<AppGroupMlsStateFfi, MarmotKitError>
Current MLS state (epoch, member count, required components) for the conversation developer/debug view.
Marmot::quarantined_groups
Current.
pub async fn quarantined_groups( &self, account_ref: String, ) -> Result<Vec<AppQuarantinedGroupFfi>, MarmotKitError>
Stored groups that failed session-open hydration and were skipped so the rest of the account could open (mdk#151 / #417). These groups are not in the live roster and otherwise vanish from the account with no explanation; surface them in a per-group recovery flow (mdk#426) distinct from healthy and archived groups, using reason to pick the per-reason guidance, and offer Self::retry_hydrate_quarantined_group.
Marmot::retry_hydrate_quarantined_group
Current.
pub async fn retry_hydrate_quarantined_group( &self, account_ref: String, group_id_hex: String, ) -> Result<bool, MarmotKitError>
Re-attempt hydration of a single quarantined group (mdk#426).
Marmot::set_group_archived
Current.
pub async fn set_group_archived( &self, account_ref: String, group_id_hex: String, archived: bool, ) -> Result<AppGroupRecordFfi, MarmotKitError>
Flag a group archived (or restore it). Local-only projection state — it does not change membership or publish anything. The chats list filters archived groups unless include_archived is set.
Marmot::group_maintenance_status
Current.
pub async fn group_maintenance_status( &self, account_ref: String, group_id_hex: String, ) -> Result<GroupMaintenanceStatusFfi, MarmotKitError>
Inspect maintenance status for a group.
Marmot::key_package_maintenance_status
Current.
pub async fn key_package_maintenance_status( &self, account_ref: String, ) -> Result<Option<KeyPackageMaintenanceStatusFfi>, MarmotKitError>
Inspect account KeyPackage maintenance status.
Marmot::schedule_group_self_update
Current.
pub async fn schedule_group_self_update( &self, account_ref: String, group_id_hex: String, ) -> Result<String, MarmotKitError>
Schedule a group self-update.
Marmot::periodic_maintenance_policy
Current.
pub async fn periodic_maintenance_policy( &self, account_ref: String, ) -> Result<PeriodicMaintenancePolicyFfi, MarmotKitError>
Read periodic maintenance policy.
Marmot::set_periodic_maintenance_policy
Current.
pub async fn set_periodic_maintenance_policy( &self, account_ref: String, policy: PeriodicMaintenancePolicyFfi, ) -> Result<(), MarmotKitError>
Set periodic maintenance policy.
Marmot::pause_maintenance
Current.
pub async fn pause_maintenance(&self, account_ref: String) -> Result<(), MarmotKitError>
Pause maintenance for an account.
Marmot::resume_maintenance
Current.
pub async fn resume_maintenance(&self, account_ref: String) -> Result<(), MarmotKitError>
Resume maintenance for an account.
Marmot::run_due_maintenance
Current.
pub async fn run_due_maintenance( &self, account_ref: String, ) -> Result<MaintenanceRunSummaryFfi, MarmotKitError>
Run due maintenance for an account.
</details>
<details> <summary>commands/history_notice.rs</summary>
Marmot::history_notices
Current.
pub async fn history_notices( &self, account_ref: String, ) -> Result<Vec<HistoryNoticeFfi>, MarmotKitError>
List the account's "history may be incomplete" notices, oldest first. Each is one parked recovery occurrence: automatic recovery stopped retrying because it could not prove some history complete. cause picks the host's wording; group_id_hex names the affected group for a group-scoped occurrence (an epoch gap) and is None when the account's history as a whole may be incomplete (delivery or notification loss, incremental or explicit history). The list is local and durable, needs no network, and is cheap to re-read: refresh it on MarmotEventFfi::HistoryNoticesChanged. A group's own occurrences also appear in group_recovery_status as history_may_be_incomplete and history_notice_ids. Treat notice_id as opaque; it changes when new evidence re-arms recovery, so never store it as an identity of a group or account.
Marmot::account_recovery_status
Current.
pub async fn account_recovery_status( &self, account_ref: String, ) -> Result<AccountRecoveryStatusFfi, MarmotKitError>
Read the account's recovery in one call: catching_up_group_ids_hex lists the groups whose history is still being fetched (lowercase hex, sorted), inbox_catching_up says whether the inbox's is, and notices holds every notice exactly as history_notices lists them. Show the first two as "catching up" and the notices as "history may be incomplete". It reads local state on the account worker, needs no network, and is cheap to re-read: refresh it on MarmotEventFfi::RecoveryStatusChanged. The recovery runner supplies the catching-up fields.
Marmot::dismiss_history_notice
Current.
pub async fn dismiss_history_notice( &self, account_ref: String, notice_id: String, ) -> Result<bool, MarmotKitError>
Dismiss one notice after the user accepts that this history may be incomplete. The dismissal is durable and is recorded as its own outcome, never as recovered history. It retires exactly that occurrence; for delivery or notification loss the transport cursor may advance again once no loss recovery remains pending. Returns false, changing nothing, for a stale id (new evidence re-armed recovery, or it was already dismissed); re-read the list and show the current notices. A malformed id is InvalidHex. New loss, a higher missing epoch, a later startup comparison or a new explicit repair can raise a new notice with a new id. Runs on the account worker in order with other mutations; it performs no network I/O.
</details>
<details> <summary>commands/linked_device.rs</summary>
Marmot::linked_devices
Current.
pub async fn linked_devices( &self, account_ref: String, ) -> Result<Vec<LinkedDeviceFfi>, MarmotKitError>
List this account's own devices for a Devices screen, from the roster of the device group this device trusts: this device first (is_this_device), then by linked_at. Every entry is this account's own device, never another account's, and it is read from local group state with no network I/O, so it is cheap to re-read. slot_id_hex is the device's KeyPackage slot and the handle later device actions take; label, client and platform are empty until set, and linked_by_slot_id_hex is None for the device that founded the group. last_active_at is when a heartbeat last showed a sibling running, in Unix seconds: each device sends one in the device group at most hourly while it runs, and each is dated when it was created or, if earlier, when this device read it. It is None for this device and for a sibling none of whose heartbeats has counted. inactive is this device's own judgement for showing the user, 30 days after the later of that and when this device first found the sibling in the roster; it is never set for this device, and status Inactive is the roster's separate mark. The list is empty until this device trusts a device group (a single-device account has none), once that group is terminal, and always without explicit dev capability and runtime intent. The device group's own events never reach hosts: refresh on MarmotEventFfi::LinkedDevicesChanged, which may fire with no visible change. A roster that cannot be read fails with MarmotKitError::Runtime (details device group refused: roster_unavailable). Runs on the account worker.
Marmot::chat_history_imports
Current.
pub async fn chat_history_imports( &self, account_ref: String, ) -> Result<Vec<ChatHistoryImportFfi>, MarmotKitError>
List the held chats whose history from another of this account's devices is arriving or has arrived, for progress beside each chat after a link ("Book club: history imported"). Receiving means a delivery arrived and waits to be imported, as while its bundle is fetched from the chat's media server; retrying turns on once an attempt to get its bundle failed, and it is tried again later. Imported names the device the latest import came from (device_slot_id_hex, and device_label, its name now) and when, in Unix seconds. A chat with a delivery still waiting reads Receiving even after an earlier import. Only facts are listed: a chat with no history to bring sends nothing, so no chat ever waits for one, and a delivery that expired after a week leaves nothing behind. A delivery for a chat this device does not hold yet is left out until it joins, since a host cannot name that chat. Empty while device groups are off. Refresh on MarmotEventFfi::ChatHistoryImportsChanged, which fires whenever this answer changes: a delivery arriving, importing, first failing or going, imported rows pruned or deleted with their chat, a source device renamed or removed, or a chat joined after its delivery arrived. It also fires once each time the account's worker opens or reconnects. An empty device_label means "another device". The same source names each imported row in TimelineMessageRecordFfi.imported_from: draw "Imported from <device>" where rows change from imported to live. Runs on the account worker, with no network I/O.
Marmot::key_package_refresh_overdue
Current.
pub async fn key_package_refresh_overdue( &self, account_ref: String, ) -> Result<bool, MarmotKitError>
Whether this device's device group has held its KeyPackage refresh back for a week, so the app warns the user. While this device trusts a device group, each KeyPackage it publishes is first announced in its own roster entry; if the device group can't take that Commit, the old KeyPackage stays in the slot, and at 30 days inviters stop treating the device as fresh. True once the KeyPackage this device would publish is still unannounced and its slot's newest publication is a week old, or there is none. A routine refresh never shows, and neither does one that is announced but failing at the relays. Always false until this device trusts a device group, and without explicit dev capability and runtime intent. Re-read on MarmotEventFfi::KeyPackageRefreshOverdueChanged, which carries no device or group identities and may fire with no visible change. Reads local state with no network I/O; runs on the account worker.
Marmot::rename_linked_device
Current.
pub async fn rename_linked_device( &self, account_ref: String, slot_id_hex: String, label: String, ) -> Result<(), MarmotKitError>
Rename one of this account's devices, this one included, by its slot_id_hex from linked_devices: one roster commit in the device group that sets only that device's label. The label is at most 64 bytes of UTF-8, and an empty label clears it. It is refused with MarmotKitError::Runtime (details device group refused: <reason>) and nothing sent without explicit dev capability and runtime intent (roster_unsupported), for a label that is too long (label_too_long), without a device group (no_device_group), for a slot the roster doesn't list (unknown_device), and while the device group has an earlier change of this device's in flight (device_group_busy, retry later). A rename whose commit loses a fork is made again on a later maintenance pass, unless another user edit of that device won; that one stands. Show the label linked_devices returns after LinkedDevicesChanged. Runs on the account worker.
Marmot::update_linked_device_settings
Current.
pub async fn update_linked_device_settings( &self, account_ref: String, slot_id_hex: String, add_to_all_chats: Option<bool>, bring_history: Option<bool>, keep_while_inactive: Option<bool>, ) -> Result<(), MarmotKitError>
Patch the supplied settings of any linked device, this one included; None preserves the value from the current account-worker roster. Earlier lost label/settings edits recover first; a patch that still matches afterwards sends no new edit. Retry device_group_busy while one remains unsettled. Other refusals are roster_unsupported, no_device_group, unknown_device and roster_unavailable. A competing user edit wins as a whole; re-read linked_devices on LinkedDevicesChanged. Add-to-all permits the available linked-device Add flow and off never leaves joined chats. History affects future sibling Adds and remaining transfers owed, without retroactive backfill; keep is stored for inactivity removal and does not cancel explicit removal or sign-out. See the shared contract.
Marmot::remove_linked_device
Current.
pub async fn remove_linked_device( &self, account_ref: String, slot_id_hex: String, ) -> Result<(), MarmotKitError>
Remove another of this account's devices, by its slot_id_hex from linked_devices: from the device group and from every chat, and delete its KeyPackage slot so inviters stop adding it. The decision is recorded at once and carried out as the device group allows, so a busy device group only delays it; linked_devices lists the device with removal_pending until the device group takes the removal, then no longer lists it. Chats that can't take a same-account removal keep the device; removed_device_leftover_chats counts them. It is refused with MarmotKitError::Runtime (details device group refused: <reason>) and nothing recorded without explicit dev capability and runtime intent (roster_unsupported), without a device group (no_device_group), for a slot the roster doesn't list (unknown_device), for this device (this_device: sign out instead), and for a device whose link may still fail (device_link_pending). Refresh on LinkedDevicesChanged. Runs on the account worker.
Marmot::removed_device_leftover_chats
Current.
pub async fn removed_device_leftover_chats( &self, account_ref: String, ) -> Result<u32, MarmotKitError>
How many chats this device is in still hold a device this account no longer has, because the chat does not take a same-account removal. That device is one this account removed, or one its device group stopped listing, as after a failed link. A chat admin can remove it; show the count beside the device list so the user knows to ask. Zero until this device trusts a device group, and always zero without explicit dev capability and runtime intent. It is not evented: read it when showing the device list. Runs on the account worker.
Marmot::chats_closed_to_linked_devices
Current.
pub async fn chats_closed_to_linked_devices( &self, account_ref: String, ) -> Result<u32, MarmotKitError>
How many chats this device is in can't take any device of this account: they don't require marmot.group.account-devices.v1, name no relays a sibling Welcome can carry, or already hold this account's limit of 20 leaves. Once a link this device approved is made, MDK adds the new device to this device's other chats by itself when its "add to all my chats" setting is on, for a week after the link; these chats are passed over, and so, uncounted, is a chat that can take this account's devices but whose requirements the new device's KeyPackages don't meet, so zero does not mean the new device reaches every chat. A chat admin can turn the component on; removing a device frees its leaves. Show the count beside the device list, as "N chats can't add your other devices". Zero until this device trusts a device group, and always zero without explicit dev capability and runtime intent. It is not evented: read it when showing the device list. Runs on the account worker.
</details>
<details> <summary>commands/media.rs</summary>
parse_media_imeta_tag
Current free function. Generated Swift/Kotlin name: parseMediaImetaTag.
pub fn parse_media_imeta_tag( tag: MessageTagFfi, source_epoch: u64, ) -> Result<MediaAttachmentReferenceFfi, MarmotKitError>
Parse one authenticated encrypted-media imeta tag using MDK's frozen V1 or current V2 validation rules.
Marmot::build_media_imeta_tag
Current.
pub async fn build_media_imeta_tag( &self, account_ref: String, group_id_hex: String, reference: MediaAttachmentReferenceFfi, ) -> Result<MessageTagFfi, MarmotKitError>
Build one outbound encrypted-media imeta tag without publishing it.
Marmot::send_media_attachments
Current.
pub async fn send_media_attachments( &self, account_ref: String, group_id_hex: String, attachments: Vec<MediaAttachmentReferenceFfi>, caption: Option<String>, ) -> Result<SendSummaryFfi, MarmotKitError>
Send already-uploaded encrypted media attachments as a kind-9 chat carrying ordered NIP-92 imeta tags. Preserve each upload's local source_epoch_identity; missing provenance or a changed upload branch requires a fresh upload.
Marmot::send_tagged_media
Current.
pub async fn send_tagged_media( &self, account_ref: String, group_id_hex: String, attachments: Vec<MediaAttachmentReferenceFfi>, caption: Option<String>, tags: Vec<Vec<String>>, ) -> Result<SendSummaryFfi, MarmotKitError>
send_media_attachments plus application tags on the same kind-9. For NIP-30 custom emoji, upload the image with upload_media(send = false), then send its reference with an ["emoji", shortcode, reference.locators[0].value] tag; receivers match the tag URL to the imeta locator and render that attachment inline. Preserve the returned reference's source_epoch_identity: sending requires the upload's exact branch, not only its epoch number. Missing provenance requires a fresh upload. Same tag limits as send_tagged_text. upload_media with MediaUploadRequestFfi.message_tags and send = true is the one-call equivalent.
Marmot::send_media_reference
Current.
pub async fn send_media_reference( &self, account_ref: String, group_id_hex: String, reference: MediaAttachmentReferenceFfi, caption: Option<String>, ) -> Result<SendSummaryFfi, MarmotKitError>
Backward-compatible single-attachment send helper. Prefer send_media_attachments for new callers so one chat can carry ordered mixed media attachments.
Marmot::upload_media
Current.
pub async fn upload_media( &self, account_ref: String, group_id_hex: String, request: MediaUploadRequestFfi, ) -> Result<MediaUploadResultFfi, MarmotKitError>
Encrypt plaintext attachments, upload the ciphertext blobs, and optionally send the resulting media references into the group. Upload references include local source_epoch_identity; preserve it unchanged when saving or sending them. Each body is first kept in the account's encrypted media store, so the sender reads its own attachments locally once the message is confirmed; a body the disk cannot hold beyond the attachment policy's disk_reserve fails with StorageFull before anything is uploaded.
Marmot::upload_media_files
Current. C: marmot_upload_media_files.
pub async fn upload_media_files( &self, account_ref: String, group_id_hex: String, request: MediaFileUploadRequestFfi, control: Arc<MediaFileTransferControlFfi>, ) -> Result<MediaUploadResultFfi, MarmotKitError>
File-backed upload_media for large attachments. Each source_path (a regular file, not a symlink; expected_size must match when set, and the file must not change while it is read) is copied into the account's encrypted media store with 64 KiB buffers before the first PUT, so plaintext never crosses the FFI as a byte array. A source the disk cannot hold beyond the attachment policy's disk_reserve fails with StorageFull before anything is uploaded. The ciphertext is never written to disk: one pass over the stored copy computes its digest, and each PUT streams it again. Ordered server fallback re-sends identical ciphertext from offset 0; a server whose descriptor omits or mismatches sha256/size fails over. The batch ciphertext ceiling is max_file_media_ciphertext_bytes(), including each 16-byte AEAD tag. The stored copy becomes the sender's local attachment once the message is confirmed; no retention budget applies. Explicit large acquisitions stream ciphertext into private files and authenticate it before bounded local publication; resumable ciphertext checkpoints never grant readable plaintext. Legacy array APIs retain their smaller bounds. control reports monotonic processed_bytes and cancels preparation, transfer and fallback. There is no dedicated cancellation error variant: after an error, control.is_cancelled() distinguishes requested cancellation (InvalidMediaReference, detail media transfer cancelled). A failed or cancelled upload deletes its stored copies; after a crash, the account worker's media sweep removes copies no upload owns, and an upload that is never sent expires after seven days. processed_bytes covers the copy, the digest pass and the transfer.
File-backed uploads have no fixed worker-response timeout; per-endpoint network deadlines still apply. Cancellation observed before message admission starts prevents publication. Admission is not interruptible once started, including while durable acceptance is pending.
Marmot::download_media
Compatibility. Prefer retained local access plus transfer controls for received chat media. Explicit one-shot fetch remains supported.
pub async fn download_media( &self, account_ref: String, group_id_hex: String, reference: MediaAttachmentReferenceFfi, ) -> Result<MediaDownloadResultFfi, MarmotKitError>
Fetch an encrypted media blob and decrypt it using the group's encrypted media component secret.
Marmot::list_media
Compatibility. Prefer attachment_history_page/version for new media-library screens.
pub fn list_media( &self, account_ref: String, group_id_hex: String, limit: Option<u32>, ) -> Result<Vec<MediaRecordFfi>, MarmotKitError>
Typed media references projected from group message history. Host apps can pass a returned reference back to download_media.
</details>
<details> <summary>commands/message.rs</summary>
Marmot::send_text
Current.
pub async fn send_text( &self, account_ref: String, group_id_hex: String, text: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Send a plain UTF-8 text message. Structured payloads (reactions, replies, deletes, media) go through dedicated methods.
Marmot::send_tagged_text
Current.
pub async fn send_tagged_text( &self, account_ref: String, group_id_hex: String, text: String, tags: Vec<Vec<String>>, ) -> Result<SendSummaryFfi, MarmotKitError>
Send send_text content plus application tags on the same kind-9, e.g. NIP-30 ["emoji", shortcode, url]. At most 64 tags and 16 KiB of tag values; imeta rows are rejected, and e/q rows need a non-empty target. Name custom emoji images through send_tagged_media instead: an emoji URL alone is not a decryptable Marmot media reference.
Marmot::send_tagged_sticker
Current.
pub async fn send_tagged_sticker( &self, account_ref: String, group_id_hex: String, sticker_ref: StickerRefFfi, message_tags: Vec<Vec<String>>, ) -> Result<SendSummaryFfi, MarmotKitError>
Send an authorized exact sticker reference with reply e, NIP-22 E/K/P, or effect tags on the same kind-9 message. Rejects imeta and extra sticker rows. Context is bounded to 64 tags and 16 KiB of tag values. Native sticker authorization and normal send admission still apply; this does not upload media. send_sticker keeps its existing signature and sends without context.
Marmot::send_sticker
Current.
pub async fn send_sticker( &self, account_ref: String, group_id_hex: String, sticker_ref: StickerRefFfi, ) -> Result<SendSummaryFfi, MarmotKitError>
Sends a kind-9 message carrying one exact sticker reference. The account must already have that reference in its projection, so a host cannot send an arbitrary URL.
Marmot::retry_group_convergence
Current.
pub async fn retry_group_convergence( &self, account_ref: String, group_id_hex: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Re-attempt publishing a group's pending (committed-but-undelivered) commit(s) without minting a new event.
Marmot::react_to_message
Current.
pub async fn react_to_message( &self, account_ref: String, group_id_hex: String, target_message_id: String, emoji: String, ) -> Result<SendSummaryFfi, MarmotKitError>
React to target_message_id with emoji (an "add" reaction).
Marmot::react_with_media
Current.
pub async fn react_with_media( &self, account_ref: String, group_id_hex: String, target_message_id: String, emoji: String, tags: Vec<Vec<String>>, attachments: Vec<MediaAttachmentReferenceFfi>, ) -> Result<SendSummaryFfi, MarmotKitError>
React with a custom emoji image. emoji is the reaction content (e.g. :shortcode:), attachments are already-uploaded references emitted as imeta on the kind-7, and tags name them (NIP-30 ["emoji", shortcode, url]). The reaction retains its media epoch secret like a chat, so the image stays decryptable after the group advances. Preserve the returned reference's source_epoch_identity; missing provenance or a changed upload branch requires a fresh upload. Same tag limits as send_tagged_text; repeating an existing reaction with the same content is a no-op.
Marmot::unreact_from_message
Current.
pub async fn unreact_from_message( &self, account_ref: String, group_id_hex: String, target_message_id: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Remove all of this account's active reactions from target_message_id.
Marmot::reply_to_message
Current.
pub async fn reply_to_message( &self, account_ref: String, group_id_hex: String, target_message_id: String, text: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Send text as a reply that quotes target_message_id.
Marmot::delete_message
Current.
pub async fn delete_message( &self, account_ref: String, group_id_hex: String, target_message_id: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Mark target_message_id deleted for the whole group. This is a tombstone — the original stays in everyone's store; clients render a "message deleted" placeholder.
Marmot::discard_failed_send
Current.
pub async fn discard_failed_send( &self, account_ref: String, group_id_hex: String, message_id_hex: String, ) -> Result<DiscardFailedSendResultFfi, MarmotKitError>
Remove a failed own send from this device without publishing anything. Offer it, instead of delete_message, on a row whose invalidation_status is local_publish_failed: a delete would tell the group about a message nobody received. Discarded securely deletes the row, its edits and its media references, and timeline subscribers receive the row's removal with reason Cleared; purge media_ciphertext_sha256 from any decrypted-media cache. erasure_pending means secure WAL truncation is still owed; the next secure delete in the group retries it. StillSending means the group has a send the engine may still publish, which could be this one, so nothing changed: keep the row and offer the action again later. NotFailedSend means the row was delivered, is still pending, was confirmed by a peer's reaction, or is already gone.
Marmot::secure_delete_expired
Current.
pub async fn secure_delete_expired( &self, account_ref: String, group_id_hex: String, ) -> Result<SecureDeleteExpiredResultFfi, MarmotKitError>
Securely scrub and prune expired disappearing-message plaintext for a group according to its active retention component. The media hash list identifies pruned encrypted-media blobs so host apps can purge their own decrypted-media disk caches keyed by ciphertext hash.
Marmot::sweep_expired_retention
Current.
pub async fn sweep_expired_retention( &self, account_ref: String, now_ms: u64, ) -> Result<RetentionSweepReportFfi, MarmotKitError>
Run the engine-owned disappearing-message sweep for one account using the supplied Unix wall-clock time in milliseconds. Each group reports pruning, a fail-closed deferral, or a privacy-safe failure category.
Marmot::edit_message
Current.
pub async fn edit_message( &self, account_ref: String, group_id_hex: String, target_message_id: String, content: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Edit target_message_id by publishing a kind-1009 event that references it and carries the replacement plaintext in content. Recipients honour the edit only when its authenticated author matches the target's author; MDK ignores mismatched edits. It returns InvalidEditTarget, publishing nothing, unless the target is an available chat message this account sent. Competing edits resolve by created_at, then the larger event id.
Marmot::send_custom_event
Current.
pub async fn send_custom_event( &self, account_ref: String, group_id_hex: String, kind: u64, tags: Vec<Vec<String>>, content: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Send an app-defined event with an arbitrary non-reserved kind. tags and content pass through verbatim; kinds MDK owns (chat, reaction, edit, delete, agent, group system, push token, device group: 457, 458, 459, 460, 461, 473, 475, 476) are rejected so an app cannot forge protocol events. Custom events appear in the timeline as standalone rows and can be fetched via Marmot::messages with a kinds filter.
Marmot::create_tagged_poll
Current.
pub async fn create_tagged_poll( &self, account_ref: String, group_id_hex: String, question: String, options: Vec<String>, poll_type: PollTypeFfi, ends_at: Option<u64>, message_tags: Vec<Vec<String>>, ) -> Result<SendSummaryFfi, MarmotKitError>
Create the same encrypted NIP-88 poll as create_poll, adding reply e, NIP-22 E/K/P, or effect context on the same event. Rejects imeta, option, polltype, endsAt, and response context rows. Generated poll tags plus context must total at most 32; context also follows the tagged-text bounds of 64 tags and 16 KiB of values. Poll replies project the same reply target and preview as chat messages. See Polls for question, option, deadline and vote semantics. The original create_poll remains available without context.
Marmot::create_poll
Current. Typed API for an encrypted NIP-88 group poll; do not build kinds 1068/1018 through send_custom_event.
pub async fn create_poll( &self, account_ref: String, group_id_hex: String, question: String, options: Vec<String>, poll_type: PollTypeFfi, ends_at: Option<u64>, ) -> Result<SendSummaryFfi, MarmotKitError>
Pass two through ten option labels and an optional Unix-seconds deadline no more than 30 days after creation. MDK validates bounded display text, assigns stable option ids in display order, and exposes results through the timeline poll projection. Creation follows MDK's canonical conversation classification: named two-member conversations are groups, while unnamed two-member conversations are direct. Polls are neither anonymous nor election-grade. See Polls.
Marmot::cast_poll_vote
Current. Use for a complete replacement selection on an existing encrypted group poll.
pub async fn cast_poll_vote( &self, account_ref: String, group_id_hex: String, poll_event_id: String, option_ids: Vec<String>, ) -> Result<SendSummaryFfi, MarmotKitError>
The poll must already be a valid local timeline row in this group and remain open. Pass one option id for single choice
or one through ten unique ids for multiple choice; use the ids from TimelineMessageRecordFfi.poll, not option labels.
This is a replacement, not a delta or unvote. MDK revalidates the poll against the response event's actual timestamp at
send time, and an accepted open poll remains votable after conversation reclassification. See Polls.
Marmot::message_reactions
pub fn message_reactions( &self, account_ref: String, group_id_hex: String, message_id_hex: String, ) -> Result<Vec<crate::conversions::TimelineUserReactionFfi>, MarmotKitError>
Read every effective user/emoji pair for an exact account/group/message. Use for reaction details, because conversation references contain only a bounded preview. Returns one local snapshot, ordered by timestamp/sender/emoji, with duplicate events collapsed to the latest pair. Blocked reactors and hidden, deleted, invalidated or retention-pruned targets are excluded. Run off the UI thread, refresh on installed conversation revisions, and discard results when the owning screen closes. No network work, localization or durable client cache is involved; records are caller-owned. See conversation details.
Marmot::poll_votes
Current. Use for a "View votes" sheet that lists who chose each option.
pub fn poll_votes( &self, account_ref: String, group_id_hex: String, poll_event_id: String, after_voted_at: Option<u64>, after_voter_account_id_hex: Option<String>, limit: u32, ) -> Result<crate::conversions::PollVotePageFfi, MarmotKitError>
Returns one page of each voter's effective selection, resolved by the same rules as TimelineMessageRecordFfi.poll:
all pages together hold participants entries whose selections sum to each option's votes. Polls are not anonymous;
every member can already read each response and its sender. Blocked voters stay listed because the shared tally still
counts them; mark them with the account's block list. A missing, deleted, hidden, or non-poll row returns an empty
page. Votes are ordered by (voted_at, voter_account_id_hex). Omit both cursor fields for the first page, then pass the
last vote's voted_at and voter_account_id_hex while has_more_after is true. limit is 1..=100 because retained
votes from former members are not bounded by the current group size. Re-read from the start when the poll row is
reprojected, and run this synchronous query off the UI thread. See Polls.
Marmot::messages
Lower-level. Raw stored messages; complete conversation screens use open_conversation_window.
pub fn messages( &self, account_ref: String, group_id_hex: Option<String>, limit: Option<u32>, kinds: Option<Vec<u64>>, ) -> Result<Vec<AppMessageRecordFfi>, MarmotKitError>
Initial history fetch for a group (or, when group_id_hex is None, the account-wide tail). Used to populate the conversation view before the subscription stream takes over.
</details>
<details> <summary>commands/moderation.rs</summary>
Marmot::report_message
Current.
pub async fn report_message( &self, account_ref: String, group_id_hex: String, message_id: String, reason: ReportReasonFfi, explanation: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Publish a report with a typed reason and explanation for a target message.
Marmot::dismiss_reports
Current.
pub async fn dismiss_reports( &self, account_ref: String, group_id_hex: String, report_ids: Vec<String>, explanation: String, ) -> Result<SendSummaryFfi, MarmotKitError>
Publish an admin dismissal label for selected reports.
Marmot::content_reports
Current.
pub fn content_reports( &self, account_ref: String, group_id_hex: String, message_id: Option<String>, after: Option<String>, limit: u32, ) -> Result<ContentReportPageFfi, MarmotKitError>
Read a bounded page of reports with per-report dismissal state.
Marmot::reported_message
Current.
pub fn reported_message( &self, account_ref: String, group_id_hex: String, message_id: String, ) -> Result<Option<TimelineMessageRecordFfi>, MarmotKitError>
Read the report target through deletion-masked timeline presentation.
Marmot::report_dismissals
Current.
pub fn report_dismissals( &self, account_ref: String, group_id_hex: String, report_id: String, after: Option<String>, limit: u32, ) -> Result<ReportDismissalPageFfi, MarmotKitError>
Read a bounded page of dismissal labels.
Marmot::submit_moderation_report
Current.
pub async fn submit_moderation_report( &self, account_ref: String, reported_pubkey: String, reason: ReportReasonFfi, explanation: String, origin: ModerationReportOriginFfi, ) -> Result<ModerationReportOutcomeFfi, MarmotKitError>
Privately report a user to the deployment's moderation team: a NIP-56 kind-1984 report about reported_pubkey (hex or npub), sealed by the account key and gift-wrapped per NIP-59 to the configured reports key, published only to the configured relays. It carries the reported key, the NIP-56 type mapped from reason, an origin label and the trimmed explanation (at most 1,000 characters; empty is omitted), and never message content, message ids, group ids or relay metadata. Additive to report_message, which stays the in-group path and is unchanged; "Block and Report" still calls block_user separately. Published, AcceptedPending and CompletionUnknown follow send summaries: the two retained states are queued, retried on catch-up and must not be resubmitted. A repeat of the same reported key, reason and origin within 10 minutes returns the existing outcome. Typed errors: ModerationReportingNotConfigured, InvalidReportedPublicKey, CannotReportSelf, ModerationReportRateLimited (20 per account per hour). Sign-out and wipe delete the account's queued reports. See moderation reports.
Marmot::moderation_reporting_available
Current.
pub fn moderation_reporting_available(&self) -> bool
True when a valid moderation-report destination is installed (from MarmotOptions.moderation_report_config or configure_moderation_reporting). Gate the report-to-operator affordance on it.
Marmot::configure_moderation_reporting
Current.
pub fn configure_moderation_reporting( &self, config: Option<ModerationReportConfigFfi>, ) -> Result<(), MarmotKitError>
Install (Some) or clear (None) the moderation-report destination at runtime and learn why one was rejected. The recipient is 64-character hex or npub; every relay must pass the relay safety policy. One bad entry rejects the whole destination with InvalidModerationReportConfig and leaves reporting unconfigured; nothing is partially applied. Prefer MarmotOptions.moderation_report_config set per build flavor so production and staging never mix.
</details>
<details> <summary>commands/notification.rs</summary>
Marmot::notification_settings
Current.
pub fn notification_settings( &self, account_ref: String, ) -> Result<NotificationSettingsFfi, MarmotKitError>
Read account notification settings.
Marmot::set_local_notifications_enabled
Current.
pub fn set_local_notifications_enabled( &self, account_ref: String, enabled: bool, ) -> Result<NotificationSettingsFfi, MarmotKitError>
Set local notification generation preference.
Marmot::set_native_push_enabled
Current.
pub async fn set_native_push_enabled( &self, account_ref: String, enabled: bool, ) -> Result<NotificationSettingsFfi, MarmotKitError>
Set native push preference.
Marmot::catch_up_accounts
Current.
pub async fn catch_up_accounts(&self) -> Result<(), MarmotKitError>
Run bounded account catch-up work.
Marmot::notify_connectivity_restored
Current.
pub async fn notify_connectivity_restored(&self) -> Result<(), MarmotKitError>
Interrupt retry backoff for durable outbound work after the host has observed usable connectivity. This is a scheduling signal only; it does not recreate application events or weaken exact-replay guarantees.
Marmot::collect_notifications_after_wake
Current.
pub async fn collect_notifications_after_wake( &self, max_wait_ms: u32, source: NotificationWakeSourceFfi, ) -> Result<BackgroundNotificationCollectionFfi, MarmotKitError>
Collect notifications after bounded wake/catch-up processing.
</details>
<details> <summary>commands/onboarding.rs</summary>
OnboardingSubscription::snapshot
Current.
pub fn snapshot(&self) -> OnboardingSnapshotFfi
Read the initial/current snapshot for this handle; follow its feature contract for one-shot versus repeatable reads.
Each finding preserves typed context, check purpose/outcome, declared capability,
allowed finding actions, and optional original observation revision. Keep rows
with the same endpoint separate. See the evidence limits;
InspectionCompleted directory-query success is not event-publication evidence.
OnboardingSubscription::next
Current.
pub async fn next(&self) -> Option<OnboardingSnapshotFfi>
Wait for the next value; None means the observation ended. Bind one receive loop to this handle.
Marmot::onboarding_recovery_required
Current.
pub fn onboarding_recovery_required( &self, account_ref: String, ) -> Result<bool, MarmotKitError>
Whether an unreadable or exhausted checkpoint needs explicit recovery.
Marmot::recover_onboarding
Current.
pub async fn recover_onboarding( &self, account_ref: String, acknowledge_latest_only_evidence: bool, ) -> Result<String, MarmotKitError>
Preserve opaque evidence, sign out, and retire the old attempt. Hosts invalidate old UI callbacks first, acknowledge latest-only retention, then explicitly begin again and use the snapshot's recovery_epoch.
Marmot::propose_onboarding_relay_repair
Current.
pub async fn propose_onboarding_relay_repair( &self, account_ref: String, step: OnboardingStepFfi, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Preview an exact, minimal general or inbox relay-list repair. The returned proposal.relay_repair carries the source event ID, ordered before/after tags, unchanged content, typed occurrence diff, and repair mode. This method only persists a revision-bound proposal; it never signs or publishes. Show the diff and use approve_onboarding_repair (or its epoch-aware variant) only when ApproveRepair is offered. ManualReview deliberately has no approval action; prefill an editor from before_tags or offer a separately labeled full reset. Preserve the account, attempt, recovery epoch, source event, and snapshot revision until approval.
Marmot::approve_onboarding_repair_in_epoch
Current.
pub async fn approve_onboarding_repair_in_epoch( &self, account_ref: String, revision: u64, recovery_epoch: String, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Approve with the epoch and revision from the same displayed snapshot.
Marmot::acknowledge_onboarding_single_device_in_epoch
Current.
pub async fn acknowledge_onboarding_single_device_in_epoch( &self, account_ref: String, revision: u64, recovery_epoch: String, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Acknowledge with the epoch and revision from the displayed device notice.
Marmot::cancel_onboarding
Current.
pub async fn cancel_onboarding(&self, account_ref: String) -> Result<(), MarmotKitError>
Cancel the current interactive onboarding attempt at any step, including approved or ready checkpoints. The identity stays signed out. Already journaled evidence is retained in the latest cancellation checkpoint; later cancellations replace it even if publication remains uncertain. A later explicit begin_*_onboarding starts a new attempt. Hosts should invalidate the UI attempt, ignore the old subscription, and await this call before beginning again. Open Chats stays host-owned.
Marmot::acknowledge_onboarding_single_device
Current.
pub async fn acknowledge_onboarding_single_device( &self, account_ref: String, revision: u64, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Record Continue anyway for the displayed notice, then resume setup.
Marmot::begin_onboarding
Current.
pub async fn begin_onboarding( &self, nsec: String, options: OnboardingOptionsFfi, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Persist the identity and return before any network preflight or publication.
Marmot::begin_external_signer_onboarding
Current. C: not exposed; external-signer callback vtable is not implemented.
pub async fn begin_external_signer_onboarding( &self, public_key: String, signer: Arc<dyn ExternalAccountSignerFfi>, options: OnboardingOptionsFfi, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Begin interactive identity-only onboarding with a host signer; signer remains host-owned and must be registered after reconstruction.
Marmot::onboarding_snapshot
Current.
pub fn onboarding_snapshot( &self, account_ref: String, ) -> Result<Option<OnboardingSnapshotFfi>, MarmotKitError>
Read the persisted onboarding state.
Marmot::subscribe_onboarding
Current.
pub fn subscribe_onboarding( &self, account_ref: String, ) -> Result<Arc<OnboardingSubscription>, MarmotKitError>
Observe onboarding snapshots for one account.
Marmot::set_onboarding_discovery_relays
Current.
pub async fn set_onboarding_discovery_relays( &self, account_ref: String, discovery_relays: Vec<String>, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Change discovery sources for the workflow without publishing them as account relay lists.
Marmot::run_onboarding
Current.
pub async fn run_onboarding( &self, account_ref: String, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Run/resume the durable onboarding workflow until ready or user input is required.
Marmot::retry_onboarding_step
Current.
pub async fn retry_onboarding_step( &self, account_ref: String, step: OnboardingStepFfi, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Retry a step whose current snapshot offers Retry.
Marmot::continue_onboarding_without
Current.
pub async fn continue_onboarding_without( &self, account_ref: String, step: OnboardingStepFfi, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Explicitly skip an optional step where the current snapshot permits it.
Marmot::propose_onboarding_recommended_relays
Current.
pub async fn propose_onboarding_recommended_relays( &self, account_ref: String, step: OnboardingStepFfi, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Append missing recommended relays while preserving all original relay tags and NIP-65 roles, including declarations this runtime cannot use. Dial policy filters connection attempts without deleting published entries. A policy-allowed outbox or inbox route is required; proposal alone is not publication.
Marmot::propose_onboarding_relays
Current.
pub async fn propose_onboarding_relays( &self, account_ref: String, step: OnboardingStepFfi, read_relays: Vec<String>, write_relays: Vec<String>, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Prepare explicit relay changes for approval.
Marmot::propose_onboarding_profile
Current.
pub async fn propose_onboarding_profile( &self, account_ref: String, profile: UserProfileMetadataFfi, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Prepare profile changes for approval.
Marmot::propose_onboarding_follows
Current.
pub async fn propose_onboarding_follows( &self, account_ref: String, follows: Vec<String>, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Prepare follow-list changes for approval.
Marmot::approve_onboarding_repair
Current.
pub async fn approve_onboarding_repair( &self, account_ref: String, revision: u64, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Approve the displayed revision for a non-recovered attempt; recovered attempts require the epoch-aware method.
Marmot::cancel_onboarding_repair
Current.
pub async fn cancel_onboarding_repair( &self, account_ref: String, ) -> Result<OnboardingSnapshotFfi, MarmotKitError>
Dismiss an unapproved repair proposal; this cannot undo already-approved publication intent.
</details>
<details> <summary>commands/presentation.rs</summary>
Marmot::presented_chat_list
Lower-level. Selected full list; default paged screens use open_chat_list_window.
pub async fn presented_chat_list( &self, account_ref: String, include_archived: bool, ) -> Result<PresentedChatListSnapshotFfi, MarmotKitError>
Local whole rows, including selected title/avatar. First use may await local preparation.
Marmot::presented_chat_list_row
Current.
pub async fn presented_chat_list_row( &self, account_ref: String, group_id_hex: String, ) -> Result<Option<PresentedChatRowFfi>, MarmotKitError>
One complete row for creation/rebind; missing local groups return None.
Marmot::open_presented_chat_list
Lower-level. Live selected full list; default paged screens use open_chat_list_window.
pub async fn open_presented_chat_list( &self, account_ref: String, include_archived: bool, ) -> Result<Arc<PresentedChatListSubscription>, MarmotKitError>
Returns an attached handle containing the initial snapshot. Take its snapshot once, then consume whole replacement updates; dispose the old handle on account switch.
</details>
<details> <summary>commands/product_analytics.rs</summary>
Marmot::usage_diagnostics_settings
Current.
pub fn usage_diagnostics_settings( &self, ) -> Result<UsageDiagnosticsSettingsFfi, MarmotKitError>
Read durable diagnostics-consent settings.
Marmot::set_usage_diagnostics_consent
Current.
pub fn set_usage_diagnostics_consent( &self, enabled: bool, ) -> Result<UsageDiagnosticsSettingsFfi, MarmotKitError>
Persist the user diagnostics-consent choice.
Marmot::usage_diagnostics_status
Current.
pub fn usage_diagnostics_status(&self) -> Result<UsageDiagnosticsStatusFfi, MarmotKitError>
Read diagnostics configuration/delivery status.
Marmot::set_product_analytics_runtime_config
Current.
pub fn set_product_analytics_runtime_config( &self, config: ProductAnalyticsRuntimeConfigFfi, ) -> Result<(), MarmotKitError>
Configure the consent-gated product-event pipeline.
Marmot::record_product_event
Current.
pub fn record_product_event( &self, event: ProductEventFfi, ) -> Result<ProductRecordResultFfi, MarmotKitError>
Record an event accepted by the configured closed product-event schema and consent policy.
Marmot::set_product_analytics_activity
Current.
pub async fn set_product_analytics_activity( &self, activity: ProductAnalyticsActivityFfi, ) -> Result<(), MarmotKitError>
Update host activity state for product analytics.
Marmot::flush_product_analytics
Current.
pub async fn flush_product_analytics(&self) -> Result<(), MarmotKitError>
Flush pending eligible product analytics work.
</details>
<details> <summary>commands/push.rs</summary>
Marmot::push_registration
Current.
pub fn push_registration( &self, account_ref: String, ) -> Result<Option<PushRegistrationFfi>, MarmotKitError>
Read an account native-push registration.
Marmot::upsert_push_registration
Current.
pub async fn upsert_push_registration( &self, account_ref: String, platform: PushPlatformFfi, raw_token: String, server_pubkey_hex: String, relay_hint: Option<String>, ) -> Result<PushRegistrationSyncResultFfi, MarmotKitError>
Register/update native push configuration with account ownership proof.
Marmot::clear_push_registration
Current.
pub async fn clear_push_registration( &self, account_ref: String, ) -> Result<PushRegistrationShareOutcomeFfi, MarmotKitError>
Clear the account native-push registration.
Marmot::group_push_debug_info
Current.
pub async fn group_push_debug_info( &self, account_ref: String, group_id_hex: String, ) -> Result<GroupPushDebugInfoFfi, MarmotKitError>
Inspect group push-routing debug information; do not log sensitive identifiers indiscriminately.
</details>
<details> <summary>commands/relay.rs</summary>
Marmot::retired_relay_hosts
Current.
pub fn retired_relay_hosts(&self) -> Vec<String>
Hostnames the relay plane will never dial or adopt.
Marmot::classify_relay_endpoints
Current.
pub fn classify_relay_endpoints( &self, endpoints: Vec<String>, ) -> Vec<RelayEndpointClassificationFfi>
Classify relay URLs using the same policy enforced at the dial boundary.
Marmot::account_relay_lists
Current.
pub fn account_relay_lists( &self, account_ref: String, ) -> Result<conversions::AccountRelayListsFfi, MarmotKitError>
Per-account relay lists: the NIP-65 and inbox lists the account has published, plus the configured default/bootstrap sets.
Marmot::relay_health
Current.
pub async fn relay_health(&self) -> conversions::RelayHealthFfi
Live relay-plane connection health (connected / connecting / disconnected counts, etc.) for the relay diagnostics view.
Marmot::relay_telemetry_settings
Current.
pub fn relay_telemetry_settings(&self) -> Result<RelayTelemetrySettingsFfi, MarmotKitError>
Device-wide relay telemetry export settings. Export is opt-in and stays inert until export_enabled is true and runtime/default config supplies a valid OTLP endpoint, bearer token, and resource attributes.
Marmot::telemetry_install_id
Current.
pub fn telemetry_install_id(&self) -> Result<String, MarmotKitError>
Consent-bound random OTLP identifier, stable until revocation. Requires a current combined grant; never use this value in product events.
Marmot::set_relay_telemetry_runtime_config
Current.
pub async fn set_relay_telemetry_runtime_config( &self, config: RelayTelemetryRuntimeConfigFfi, ) -> Result<(), MarmotKitError>
Supply non-persisted OTLP runtime metadata: optional metrics URL override, bearer token from the host app's build-time secret, and resource attributes from the platform shell.
Marmot::set_relay_telemetry_settings
Current.
pub async fn set_relay_telemetry_settings( &self, settings: RelayTelemetrySettingsFfi, ) -> Result<RelayTelemetrySettingsFfi, MarmotKitError>
Deprecated consent control. Use set_usage_diagnostics_consent instead. Enable requires a combined grant; disable revokes both exporters. This compatibility setter still updates the telemetry interval.
</details>
<details> <summary>commands/sign_in.rs</summary>
Marmot::answer_sign_in
Current.
pub async fn answer_sign_in( &self, account_ref: String, slot_id_hex: String, response: SignInResponseFfi, ) -> Result<(), MarmotKitError>
Answer the unrecognized sign-in in slot_id_hex. NotNow keeps it listed without a prompt. Reject records that it was not the user: it leaves this device's list, and its slot goes into the device group's roster as rejected, in one commit once that group is quiet. Another device that still shows it as a new sign-in's waiting prompt lists it as RejectedElsewhere until Dismiss; one there that was put off with NotNow, or found before that device, leaves its list. With no device group yet, the rejection stays on this device and goes into the roster of the group it later creates or joins. Dismiss only ends a prompt another device already answered. A refusal is MarmotKitError::Runtime whose details read device group refused: <reason>, the reason being sign_in_unknown (not listed), sign_in_answered, sign_in_answered_elsewhere (only Dismiss applies), sign_in_unanswered (Dismiss before any device answered), or roster_unsupported; re-read the list after one. An answer raises UnrecognizedSignInsChanged. Runs on the account worker.
Marmot::check_sign_ins
Current.
pub async fn check_sign_ins( &self, account_ref: String, ) -> Result<Vec<UnrecognizedSignInFfi>, MarmotKitError>
Check the account's KeyPackage slots for new sign-ins now, for a pull-to-refresh or a Check now action, and return the list after the check. The check reads every slot from each of the account's KeyPackage relays, and restarts the six-hour schedule. Only a complete read marks a sign-in as signed out. A read that reached no relay fails with MarmotKitError::Runtime (device group refused: key_packages_unreachable), and the list is unchanged. Runs on the account worker and waits on the network.
Marmot::start_fresh
Current.
pub async fn start_fresh(&self, account_ref: String) -> Result<(), MarmotKitError>
Start this device without the devices its first sign-in check found, for "No, start fresh" when the user no longer has them: every sign-in from before this device is answered NotNow, now and when one is listed later, so none prompts. It rejects nothing and raises no compromise warning, so one of those devices can still link this one. A refusal is MarmotKitError::Runtime whose details read device group refused: <reason>, the reason being sign_ins_unchecked (before the first check), device_group_exists (this device trusts a device group), or roster_unsupported. Raises UnrecognizedSignInsChanged when a listed sign-in changed. Runs on the account worker.
Marmot::started_fresh
Current.
pub async fn started_fresh(&self, account_ref: String) -> Result<bool, MarmotKitError>
Whether this device started fresh and still trusts no device group, so the app can say that only chats it is invited to from now on are here. It turns false once the device trusts a device group; re-read after start_fresh and on LinkedDevicesChanged. Read from local state with no network I/O. Always false without explicit dev capability and runtime intent. Runs on the account worker.
Marmot::unrecognized_sign_ins
Current.
pub async fn unrecognized_sign_ins( &self, account_ref: String, ) -> Result<Vec<UnrecognizedSignInFfi>, MarmotKitError>
List the sign-ins of this account that this device does not recognize, the earliest to appear first. Each is a fresh, valid KeyPackage of this account in a slot that neither this device nor the roster of its device group knows: someone holding the account's key signed in there. An entry with before_this_device was found by this device's first check, so it was signed in before this device: ask whether the user still has it, with last_seen_at. Any other is new: ask whether it was them, with client and appeared_at. A LinkedElsewhere or RejectedElsewhere entry was answered on another device while its prompt waited here; offer Dismiss. A sign-in whose slot empties stays listed with signed_in false. Linking one is device pairing's, started from its slot_id_hex. Read from local state with no network I/O; the account checks its slots at open, every six hours, and soon after one of its KeyPackages arrives live. Always empty without explicit dev capability and runtime intent. Refresh on MarmotEventFfi::UnrecognizedSignInsChanged, which may fire with no visible change. Runs on the account worker.
</details>
<details> <summary>commands/sticker.rs</summary>
Marmot::sticker_packs
Current.
pub fn sticker_packs( &self, account_ref: String, installed_only: bool, search: Option<String>, limit: Option<u32>, ) -> Result<Vec<StickerPackFfi>, MarmotKitError>
Reads the encrypted sticker projection off the UI thread. installed_only selects the installed list; search matches public title and description only.
Marmot::sticker_pack
Current.
pub fn sticker_pack( &self, account_ref: String, input: String, ) -> Result<Option<StickerPackFfi>, MarmotKitError>
Reads one cached pack without network I/O. Returns none when the coordinate is absent; use fetch_sticker_pack for an explicit network fetch.
Marmot::sticker_pack_share_link
Current.
pub fn sticker_pack_share_link( &self, account_ref: String, coordinate: String, ) -> Result<String, MarmotKitError>
Builds https://sonarprivacy.xyz/stickers?a=... from a valid pack coordinate without network I/O. Call off the UI thread because it reads local storage. Includes up to eight normalized, unique relay candidates retained by pack fetches, or current account relays when none remain usable. Both sources pass the current relay safety policy. New fetch candidates displace older hints. Hints are candidates, not confirmed event locations; oversized hints are omitted to keep links within the parser's 2048-character limit. An uncached coordinate can be shared. Invalid coordinates return InvalidSticker.
Marmot::sync_sticker_packs
Current.
pub async fn sync_sticker_packs( &self, account_ref: String, ) -> Result<StickerSyncResultFfi, MarmotKitError>
Refreshes at most MAX_DISCOVERY_PACKS recent public packs and separately refreshes cached installed packs. Pending install changes are published only after a complete installed-list read. Uninstalled discovery above that bound is pruned; installed packs, pending operations, and message-referenced assets stay.
Marmot::fetch_sticker_pack
Current.
pub async fn fetch_sticker_pack( &self, account_ref: String, input: String, ) -> Result<StickerPackFfi, MarmotKitError>
Fetches one pack by coordinate or trusted Sonar link, querying the link's relay hints and the account relays; the newest version wins NIP-01 ordering, so a hint cannot hide a newer pack. The requested coordinate is protected from discovery eviction. Call this when the user opens a shared pack, not from a background crawl.
Marmot::install_sticker_pack
Current.
pub async fn install_sticker_pack( &self, account_ref: String, input: String, ) -> Result<StickerPackFfi, MarmotKitError>
After a complete installed-list read, signs the proposed list before saving local install intent. A signing refusal does not queue this install. Without a complete read, intent stays pending for a later sync_sticker_packs. This is the user action after previewing a pack; it does not upload sticker bytes.
Marmot::uninstall_sticker_pack
Current.
pub async fn uninstall_sticker_pack( &self, account_ref: String, input: String, ) -> Result<(), MarmotKitError>
After a complete installed-list read, signs the proposed list before saving local uninstall intent. A signing refusal does not queue this uninstall. Without a complete read, intent stays pending for a later sync_sticker_packs. Previously received messages can still resolve their exact historical asset.
Marmot::import_signal_sticker_pack
Current.
pub async fn import_signal_sticker_pack( &self, account_ref: String, signal_link: String, blossom_server: Option<String>, ) -> Result<StickerImportResultFfi, MarmotKitError>
Validates a canonical HTTPS Signal pack link, then refuses before any network call. The pinned importer dials Signal's CDN without address pinning, so this command does not download, upload, or publish until that fetch can be injected. The Signal key stays in memory only and is not persisted.
Marmot::fetch_sticker_asset
Current.
pub async fn fetch_sticker_asset( &self, account_ref: String, sticker_ref: StickerRefFfi, ) -> Result<StickerAssetFfi, MarmotKitError>
Downloads one exact sticker after the account has its (coordinate, shortcode, hash) mapping. Hosts pass the typed reference from a timeline row; MDK never asks the host to parse tags. A missing mapping returns StickerNotFound rather than fetching an unvalidated URL.
</details>
<details> <summary>commands/subscription.rs</summary>
Marmot::subscribe_events
Current.
pub fn subscribe_events(&self) -> Arc<EventsSubscription>
Top-level event firehose. One subscription, every account, every event type. Useful for global diagnostics; specific UIs prefer the per-account chats/messages/group-state subscriptions below.
Marmot::subscribe_notifications
Current.
pub async fn subscribe_notifications( &self, ) -> Result<Arc<NotificationsSubscription>, MarmotKitError>
Observe prepared runtime notification events.
Marmot::subscribe_chats
Lower-level. Raw chat/group subscription; prepared screens use open_chat_list_window.
pub async fn subscribe_chats( &self, account_ref: String, include_archived: bool, ) -> Result<Arc<ChatsSubscription>, MarmotKitError>
Per-account chats list. Emits whenever a group's projection changes.
Marmot::subscribe_chat_list
Lower-level. Raw list subscription; prepared screens use open_chat_list_window.
pub async fn subscribe_chat_list( &self, account_ref: String, include_archived: bool, ) -> Result<Arc<ChatListSubscription>, MarmotKitError>
Per-account durable chat-list projection. Async for the same tokio-runtime reason as Marmot::subscribe_chats.
Marmot::subscribe_messages
Lower-level. Raw message subscription; complete screens use open_conversation_window.
pub async fn subscribe_messages( &self, account_ref: String, group_id_hex: Option<String>, limit: Option<u32>, kinds: Option<Vec<u64>>, ) -> Result<Arc<MessagesSubscription>, MarmotKitError>
Messages for a specific group (when group_id_hex is Some) or every message across the account (when None). limit caps the initial snapshot to the latest N rows; live updates continue after the snapshot. kinds restricts to the listed inner app-event kinds (e.g. an app-defined custom kind); None or an empty list streams all kinds. Async for the same tokio-runtime reason as Marmot::subscribe_chats.
Marmot::subscribe_timeline_messages
Lower-level. Custom timeline subscription; complete screens use open_conversation_window.
pub async fn subscribe_timeline_messages( &self, account_ref: String, group_id_hex: Option<String>, limit: Option<u32>, ) -> Result<Arc<TimelineMessagesSubscription>, MarmotKitError>
Live materialized timeline updates for a group or account-wide tail. The snapshot
and each next() result replace the retained window in ascending display order.
Use the handle's paginate_backwards and paginate_forwards methods rather than
merging cursor pages. The lower-level
timeline_messages contract describes selection order
and cursor boundaries; complete chat screens use the
conversation window.
Marmot::subscribe_group_state
Current.
pub async fn subscribe_group_state( &self, account_ref: String, group_id_hex: String, ) -> Result<Arc<GroupStateSubscription>, MarmotKitError>
Member/profile/roster changes for one group. Async for the same tokio-runtime reason as Marmot::subscribe_chats.
</details>
<details> <summary>commands/telemetry.rs</summary>
Marmot::record_host_timing
Current.
pub fn record_host_timing( &self, name: String, duration_ms: u64, outcome: HostPerformanceOutcomeFfi, ) -> Result<ProductRecordResultFfi, MarmotKitError>
Record an app-defined timing in the consent-gated product event pipeline. Register name with elapsed: DurationBucket and outcome: Enum choices success/failure in the product analytics config. Milliseconds are bucketed before recording; this does not add an OTLP performance metric.
Marmot::record_host_performance
Current.
pub fn record_host_performance( &self, operation: HostPerformanceOperationFfi, duration_ms: u64, outcome: HostPerformanceOutcomeFfi, )
Record one approved host-app milestone.
Marmot::app_performance_snapshot
Current.
pub fn app_performance_snapshot(&self) -> AppPerformanceSnapshotFfi
Read the process-wide app-performance snapshot for debug/diagnostics surfaces and on-demand support dumps.
</details>
<details> <summary>commands/timeline.rs</summary>
Marmot::message_edit_history
Current.
pub fn message_edit_history( &self, account_ref: String, group_id_hex: String, target_message_id_hex: String, before_edited_at: Option<u64>, before_message_id_hex: Option<String>, limit: u32, ) -> Result<crate::conversions::TimelineEditHistoryPageFfi, MarmotKitError>
Accepted edit versions, oldest first within a latest-first page (1..=100). Supply both cursor fields from the first version to load older versions. Run this synchronous details query off the UI thread; screens already carry effective content.
Marmot::timeline_messages
Lower-level. Supported custom timeline page. Complete chat screens start from
open_conversation_window and use the
conversation window paging and lifetime contract.
pub fn timeline_messages( &self, account_ref: String, query: TimelineMessageQueryFfi, ) -> Result<TimelinePageFfi, MarmotKitError>
Materialized conversation timeline for a group or account-wide tail. This read is
synchronous and local; run it off the UI thread. Custom live timelines can use
subscribe_timeline_messages and its
paginate_backwards and
paginate_forwards methods.
Those methods return a bounded replacement window, not a page to merge.
TimelinePageFfi.messages is always in ascending display order, including initial
and Before pages. Selection direction does not change returned order:
- No cursor selects the last
limitmatching rows (default 50, capped at 200). beforeselects the nearest preceding rows, excluding the boundary row.afterselects the nearest following rows, excluding the boundary row.
TimelineMessageQueryFfi carries the cursor directly, without a separate cursor
DTO. Older-page queries copy the first row's timeline_at and message_id_hex
into before and before_message_id. Newer-page queries copy the last row into
after and after_message_id. Both fields in a pair are required; half cursors
and requests with both directions fail. Keep the group scope and filters unchanged.
Group queries use canonical display order unless search_wall_clock is true.
An epoch-establishing system row precedes the authenticated application rows in
that epoch, which precede the next epoch boundary. For example, an epoch-7 message
at time 200 precedes an epoch-8 message at time 150. Storage resolves the cursor's
canonical key by message id. Keep the returned order and cursor fields rather than
sorting by timestamp or inventing a timestamp-only cursor. If the cursor row is no
longer retained, the query fails; restart without a cursor.
Account-wide and wall-clock queries order by (timeline_at, message_id_hex).
Equal timestamps still require the message-id tie-breaker. Account-wide queries
with search_wall_clock = true add group_id_hex as the final tie-breaker;
paging also requires the boundary row's group in cursor_group_id.
Flags describe locally stored matching rows, not remote history completeness. The cursor-facing flag records navigation context, even when the page is empty:
| Query | has_more_before |
has_more_after |
|---|---|---|
| No cursor | More older matching rows than fit in the tail | false |
| Before | More older matching rows than fit before the cursor | true (cursor-side context) |
| After | true (cursor-side context) |
More newer matching rows than fit after the cursor |
This Rust example uses the actual binding DTO. kit, account, and group are
an open Marmot, an account reference, and an MLS group id in hex. The enclosing
function returns Result<(), MarmotKitError>. Run it off the UI thread:
let query = TimelineMessageQueryFfi {
group_id_hex: Some(group),
limit: Some(50),
..Default::default()
};
let initial = kit.timeline_messages(account.clone(), query.clone())?;
if !initial.has_more_before {
return Ok(());
}
let Some(first) = initial.messages.first() else { return Ok(()); };
let older = kit.timeline_messages(account.clone(), TimelineMessageQueryFfi {
before: Some(first.timeline_at),
before_message_id: Some(first.message_id_hex.clone()),
..query.clone()
})?;
let Some(last) = older.messages.last() else { return Ok(()); };
let newer = kit.timeline_messages(account, TimelineMessageQueryFfi {
after: Some(last.timeline_at),
after_message_id: Some(last.message_id_hex.clone()),
..query
})?;
initial, older, and newer each remain in ascending display order. newer
starts after older's last row; it can revisit the initial page but does not
repeat its cursor row. Each request starts from the cursor-free query, so the
After request does not accidentally retain a Before pair. Equal timestamps and
different canonical epochs use the same boundary-row selection.
</details>
<details> <summary>commands/user_blocks.rs</summary>
BlockListSubscription::snapshot
Current.
pub fn snapshot(&self) -> Option<BlockListSnapshotFfi>
Read the initial/current snapshot for this handle; follow its feature contract for one-shot versus repeatable reads.
BlockListSubscription::next
Current.
pub async fn next(&self) -> Option<BlockListSnapshotFfi>
Wait for the next value; None means the observation ended. Bind one receive loop to this handle.
Marmot::block_user
Current.
pub async fn block_user( &self, account_ref: String, user_account_id_hex: String, ) -> Result<(), MarmotKitError>
Block a user for the account.
Marmot::unblock_user
Current.
pub async fn unblock_user( &self, account_ref: String, user_account_id_hex: String, ) -> Result<(), MarmotKitError>
Remove a user block.
Marmot::get_blocked_users
Current.
pub fn get_blocked_users( &self, account_ref: String, ) -> Result<Vec<BlockedUserFfi>, MarmotKitError>
Read the current blocked-user collection.
Marmot::is_user_blocked
Current.
pub fn is_user_blocked( &self, account_ref: String, user_account_id_hex: String, ) -> Result<bool, MarmotKitError>
Check one user block.
Marmot::subscribe_blocked_users
Current.
pub fn subscribe_blocked_users( &self, account_ref: String, ) -> Result<Arc<BlockListSubscription>, MarmotKitError>
Observe block-list snapshots.
</details>
<details> <summary>conversions/conversation_window.rs</summary>
MessageDraftRevisionFfi::includes_chat_list_version
pub fn includes_chat_list_version(&self, version: Arc<ChatListDraftVersionFfi>) -> bool
Compare a chat-list row’s opaque draft_version with this captured composer revision. True means the same account store/group and a version no newer than this revision; false includes foreign store/group metadata and newer identical edits. This is presentation correlation, not mutation authorization. Keep both values device-local and use revision-checked cleanup. See pending-send draft presentation.
</details>
<details> <summary>conversions/attachment_history.rs</summary>
AttachmentHistoryVersion::change_since
Current.
pub fn change_since( &self, previous: Arc<AttachmentHistoryVersion>, ) -> AttachmentHistoryChangeFfi
Compare current with an older version, including after the last page. RestartRequired means discard all loaded rows before restarting at the head.
</details>
<details> <summary>conversions/emoji_set.rs</summary>
EmojiSetInstallControlFfi::new
Current constructor. C: marmot_emoji_set_install_control_new.
pub fn new() -> Arc<Self>
Create one control per install_emoji_set call and pass it in; it is never reused across installs. A control that is already cancelled makes the install fail with EmojiSetInstallCancelled before any download.
EmojiSetInstallControlFfi::cancel
Current. C: marmot_emoji_set_install_control_cancel.
pub fn cancel(&self)
Request cancellation from any thread. The install starts no new download, drops those in flight, stores nothing and fails promptly with EmojiSetInstallCancelled; a cancelled reinstall leaves the previous snapshot readable. Install is all-or-nothing: the final atomic write is not interruptible, so a cancellation that arrives once it has started is too late and the install succeeds. Needed because cancelling the host's task does not reach the Rust future under UniFFI 0.29.
EmojiSetInstallControlFfi::is_cancelled
Current. C: marmot_emoji_set_install_control_is_cancelled.
pub fn is_cancelled(&self) -> bool
Whether cancellation was requested, by cancel() or by the runtime: shutdown and shutdown_and_close cancel every running install the same way, so a backgrounded app never keeps downloading or writes after close.
EmojiSetInstallControlFfi::progress
Current. C: marmot_emoji_set_install_control_progress.
pub fn progress(&self) -> EmojiSetInstallProgressFfi
Poll for a determinate progress bar: completed_emoji of total_emoji entries finished (stored, skipped or given up on), and transferred_bytes received from image hosts. total_emoji is the stored version's valid emoji count and stays 0 until the install has read it; completed_emoji reaches it when an install succeeds. Bytes are counted as each download finishes, not while it streams.
</details>
<details> <summary>conversions/media.rs</summary>
MediaFileTransferControlFfi::new
Current constructor. C: marmot_media_file_transfer_control_new.
pub fn new() -> std::sync::Arc<Self>
Create one control per file-backed operation; it is never reused across operations.
MediaFileTransferControlFfi::cancel
Current. C: marmot_media_file_transfer_control_cancel.
pub fn cancel(&self)
Request cancellation. Preparation, body transfer and server fallback stop at the next chunk; nothing is published when cancellation is observed before message admission starts. Admission is not interruptible once started, even before durable acceptance returns; cancellation cannot retract an admitted message.
MediaFileTransferControlFfi::is_cancelled
Current. C: marmot_media_file_transfer_control_is_cancelled.
pub fn is_cancelled(&self) -> bool
Whether cancel was called. It is not an outcome: await the operation's result.
MediaFileTransferControlFfi::processed_bytes
Current. C: marmot_media_file_transfer_control_processed_bytes.
pub fn processed_bytes(&self) -> u64
Monotonic local work counter across the copy into the encrypted media store, the digest pass and the transfer of the current attachment. Not a percentage or a delivery signal.
max_file_media_ciphertext_bytes
Current free function. Generated Swift/Kotlin name: maxFileMediaCiphertextBytes. C: marmot_max_file_media_ciphertext_bytes.
pub fn max_file_media_ciphertext_bytes() -> u64
Per-batch ciphertext ceiling for file-backed uploads (an implementation resource bound, not protocol).
</details>
<details> <summary>external_signer.rs</summary>
ExternalAccountSignerFfi::public_key
Host callback. C: not exposed; external-signer callback vtable is not implemented.
fn public_key(&self) -> Result<String, MarmotKitError>
Return the signer account public key as hex or npub.
ExternalAccountSignerFfi::sign_event
Host callback. C: not exposed; external-signer callback vtable is not implemented.
fn sign_event(&self, unsigned_event_json: String) -> Result<String, MarmotKitError>
Sign a serialized unsigned Nostr event and return the signed event JSON.
ExternalAccountSignerFfi::nip04_encrypt
Host callback. C: not exposed; external-signer callback vtable is not implemented.
fn nip04_encrypt(&self, public_key: String, content: String) -> Result<String, MarmotKitError>
NIP-04 encrypt/decrypt support for legacy Nostr surfaces.
ExternalAccountSignerFfi::nip04_decrypt
Host callback. C: not exposed; external-signer callback vtable is not implemented.
fn nip04_decrypt( &self, public_key: String, encrypted_content: String, ) -> Result<String, MarmotKitError>
Host callback for legacy NIP-04 decryption; return an unsupported error if not implemented.
ExternalAccountSignerFfi::nip44_encrypt
Host callback. C: not exposed; external-signer callback vtable is not implemented.
fn nip44_encrypt(&self, public_key: String, content: String) -> Result<String, MarmotKitError>
NIP-44 encrypt/decrypt support for gift-wrap and encrypted app data.
ExternalAccountSignerFfi::nip44_decrypt
Host callback. C: not exposed; external-signer callback vtable is not implemented.
fn nip44_decrypt(&self, public_key: String, payload: String) -> Result<String, MarmotKitError>
Host callback for NIP-44 payload decryption.
</details>
<details> <summary>lib.rs</summary>
Marmot::new_with_configuration
Current.
pub fn new_with_configuration( root_path: String, relay_urls: Vec<String>, options: MarmotOptions, ) -> Result<Arc<Self>, MarmotKitError>
Open with any combination of runtime options, including the required deployment. The other constructors are wrappers around this entry point and take the deployment as their last argument.
Marmot::new_with_experimental_device_groups
pub fn new_with_experimental_device_groups( root_path: String, relay_urls: Vec<String>, options: MarmotOptions, ) -> Result<Arc<Self>, MarmotKitError>
Open a controlled development build with device-group capability and explicit runtime intent. The library must enable dev-device-groups; otherwise it returns Runtime with experimental_device_groups_unavailable before opening the root or acquiring host secret storage. It takes the same MarmotOptions and required deployment as new_with_configuration, preserving their ordinary meanings and ownership. Ordinary constructors remain disabled even in a capable library. Use this constructor for every foreground/background opener of the experimental root, a notification service extension included: an ordinary constructor does not open an account that holds or is joining a device group and reports Runtime with experimental_device_groups_required; see the shared host test-build guidance. Production timing is unchanged. This is not release activation or proof of mobile artifact/device validation.
Marmot::new_with_options
Compatibility. Prefer new_with_configuration when combining settings.
pub fn new_with_options( root_path: String, relay_urls: Vec<String>, relay_policy: RelayPolicyFfi, secret_store: Option<Arc<dyn SecretStore>>, deployment: MarmotDeploymentFfi, ) -> Result<Arc<Self>, MarmotKitError>
Open with an explicit relay policy and optional host-owned key storage. Existing constructors retain their public-only relay policy.
Marmot::new
Current.
pub fn new( root_path: String, relay_urls: Vec<String>, deployment: MarmotDeploymentFfi, ) -> Result<Arc<Self>, MarmotKitError>
Open the Marmot app at root_path, configured with the given default relay URLs and deployment. Account secrets (Nostr private keys) are stored in the platform keyring (Keychain on Apple platforms, Android's native keyring on Android) under the deployment's keychain_service — not in a plaintext file. Fallible because initializing the platform secret store can fail or another process may own the same root (MarmotKitError::RuntimeBusy). Root ownership is nonblocking and remains held until the final Marmot/runtime handle is dropped, even after Marmot::shutdown. Call Marmot::start before subscribing to events.
Marmot::new_with_secret_store
Compatibility. Prefer new_with_configuration when combining settings.
pub fn new_with_secret_store( root_path: String, relay_urls: Vec<String>, secret_store: Arc<dyn SecretStore>, deployment: MarmotDeploymentFfi, ) -> Result<Arc<Self>, MarmotKitError>
Open the Marmot app with host-supplied account-secret storage instead of the platform keychain. Identical to Marmot::new except that every read, write, and removal of an account signing key goes through secret_store.
Marmot::new_with_cursor_persistence
Compatibility. Prefer new_with_configuration when combining settings.
pub fn new_with_cursor_persistence( root_path: String, relay_urls: Vec<String>, cursor_persistence: CursorPersistenceFfi, deployment: MarmotDeploymentFfi, ) -> Result<Arc<Self>, MarmotKitError>
Construct with explicit advancing/frozen relay cursor behavior; new_with_configuration composes this with other options.
Marmot::new_with_client_name
Compatibility. Prefer new_with_configuration when combining settings.
pub fn new_with_client_name( root_path: String, relay_urls: Vec<String>, client_name: Option<String>, cursor_persistence: CursorPersistenceFfi, secret_store: Option<Arc<dyn SecretStore>>, deployment: MarmotDeploymentFfi, ) -> Result<Arc<Self>, MarmotKitError>
Open with an optional public client label for new KeyPackage publications. Existing constructors remain untagged. Whitespace-only labels, and labels longer than 64 bytes once trimmed, are omitted rather than truncated. Hosts must supply this on every foreground/background runtime construction.
Marmot::start
Current.
pub async fn start(&self) -> Result<(), MarmotKitError>
Bring the runtime to local readiness.
Marmot::shutdown
Current.
pub async fn shutdown(&self)
Tear the runtime down. Drops all subscriptions; long-lived EventsSubscription / ChatsSubscription / etc. instances on the host side will see their next() return None shortly after.
Marmot::shutdown_and_close
Current.
pub async fn shutdown_and_close(&self) -> Result<(), MarmotKitError>
Terminally stop work, close storage and release root ownership; reconstruct before further reads/work.
Marmot::storage_is_closed
Current.
pub fn storage_is_closed(&self) -> bool
True once Marmot::shutdown_and_close has closed the store. A host can check this to confirm it is safe to be suspended, or to notice it is holding a spent handle and needs a fresh one.
Marmot::is_stopping
Current.
pub fn is_stopping(&self) -> bool
True once shutdown has started. Host apps can use this to avoid launching more subscriptions or account work while they are moving to the background.
</details>
<details> <summary>publisher.rs</summary>
Marmot::open_agent_publisher
Current.
pub async fn open_agent_publisher( &self, account_ref: String, group_id_hex: String, options: PublisherOptionsFfi, ) -> Result<Arc<AgentTextPublisher>, MarmotKitError>
Publish a new stream start and return a handle for appending records. No exporter secret or framing state crosses the foreign boundary.
AgentTextPublisher::info
Current.
pub fn info(&self) -> PublisherInfoFfi
Read the anchored stream information.
AgentTextPublisher::append
Current.
pub async fn append( &self, kind: PublisherRecordFfi, text: String, ) -> Result<PublisherAckFfi, MarmotKitError>
Append transcript/preview content; transport failure does not discard accepted transcript content.
AgentTextPublisher::finish
Current.
pub async fn finish(&self) -> Result<SendSummaryFfi, MarmotKitError>
Seal and durably send the transcript; inspect send disposition. Retry on the same handle after failure; successful repeats return the original receipt.
AgentTextPublisher::cancel
Current.
pub async fn cancel(&self)
Stop the preview; an already-running finish wins. State is not restored after process restart.
</details>
<details> <summary>secret_store.rs</summary>
SecretStore::has_secret_for_label
Host callback.
fn has_secret_for_label(&self, label: String) -> Result<bool, MarmotKitError>
Whether a credential is stored under label.
SecretStore::has_secret_for_account_id
Host callback.
fn has_secret_for_account_id(&self, account_id_hex: String) -> Result<bool, MarmotKitError>
Whether a credential is stored under account_id_hex. Stores that key one credential per label report false.
SecretStore::write_secret
Host callback.
fn write_secret( &self, label: String, account_id_hex: String, secret_key_hex: String, ) -> Result<(), MarmotKitError>
Persist secret_key_hex for this account, replacing any existing credential.
SecretStore::load_secret
Host callback.
fn load_secret(&self, label: String, account_id_hex: String) -> Result<String, MarmotKitError>
Return the stored secret-key hex, or MarmotKitError::SecretNotFound when this account has no credential.
SecretStore::remove_secret
Host callback.
fn remove_secret(&self, label: String, account_id_hex: String) -> Result<(), MarmotKitError>
Remove this account's credential. Removing a missing credential succeeds.
</details>
<details> <summary>subscriptions/chat_window.rs</summary>
ChatListWindowSubscription::snapshot
Current.
pub fn snapshot(&self) -> Option<ChatListWindowSnapshotFfi>
Take the initial complete replacement once, before driving next().
ChatListWindowSubscription::next
Current.
pub async fn next(&self) -> Result<Option<ChatListWindowSnapshotFfi>, MarmotKitError>
One receiver per handle. Cancellation does not consume an update.
ChatListWindowSubscription::page
Current.
pub async fn page( &self, sequence: u64, direction: ChatListPageDirectionFfi, count: u32, ) -> Result<ChatListWindowSnapshotFfi, MarmotKitError>
1–100 rows, at most 200 retained. Uses the installed snapshot's sequence. This can run while next() waits; accepted commands survive caller cancellation.
ChatListWindowSubscription::set_visible_anchor
Current.
pub async fn set_visible_anchor( &self, sequence: u64, group_id_hex: String, ) -> Result<ChatListWindowSnapshotFfi, MarmotKitError>
Stable row identity, not pixel offset. A missing/outside anchor is rejected.
ChatListWindowSubscription::return_to_top
Current.
pub async fn return_to_top( &self, sequence: u64, ) -> Result<ChatListWindowSnapshotFfi, MarmotKitError>
Navigate the prepared chat list back to its current head with sequence validation.
AccountAttentionSubscription::snapshot
Current.
pub fn snapshot(&self) -> Option<AccountAttentionSnapshotFfi>
Take the initial account set once. Unavailable entries never contain invented totals.
AccountAttentionSubscription::next
Current.
pub async fn next(&self) -> Result<Option<AccountAttentionSnapshotFfi>, MarmotKitError>
Wait for the next value; None means the observation ended. Bind one receive loop to this handle.
</details>
<details> <summary>subscriptions/conversation_window.rs</summary>
ConversationWindowSubscription::snapshot
Current.
pub fn snapshot(&self) -> Option<ConversationWindowSnapshotFfi>
Take once before next(). Complete replacements include every visible identity.
ConversationWindowSubscription::next
Current.
pub async fn next(&self) -> Result<Option<ConversationWindowSnapshotFfi>, MarmotKitError>
One receiver; cancellation leaves pending replacements available. Worker replacement is terminal: reopen the conversation after Closed/None with a fresh generation.
ConversationWindowSubscription::cancel
Current.
pub async fn cancel(&self)
Wake receivers/commands and release the retained runtime window. Idempotent. Drop the native object too when finished. Previously returned snapshots stay valid.
ConversationWindowSubscription::page
Current.
pub async fn page( &self, revision: ConversationWindowRevisionFfi, direction: ConversationPageDirectionFfi, count: u32, timeout_ms: u32, ) -> Result<ConversationWindowSnapshotFfi, MarmotKitError>
1–200 rows, at most 200 retained; report a new visible anchor to page beyond saturated context. Zero timeout uses 30 seconds. After timeout/cancellation an accepted command may still complete through next(); refresh before retrying.
ConversationWindowSubscription::set_visible_anchor
Current.
pub async fn set_visible_anchor( &self, revision: ConversationWindowRevisionFfi, message_id_hex: String, timeout_ms: u32, ) -> Result<ConversationWindowSnapshotFfi, MarmotKitError>
Report a row in the installed replacement, not a pixel offset. No read acknowledgement.
ConversationWindowSubscription::return_to_latest
Current.
pub async fn return_to_latest( &self, revision: ConversationWindowRevisionFfi, timeout_ms: u32, ) -> Result<ConversationWindowSnapshotFfi, MarmotKitError>
Resume following new arrivals. Retains the current row budget (up to 200).
ConversationWindowSubscription::jump_to_message
Current.
pub async fn jump_to_message( &self, revision: ConversationWindowRevisionFfi, message_id_hex: String, timeout_ms: u32, ) -> Result<ConversationWindowSnapshotFfi, MarmotKitError>
Missing targets fail explicitly. Commands may run while next() waits.
</details>
<details> <summary>subscriptions.rs</summary>
ChatsSubscription::snapshot
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub fn snapshot(&self) -> Vec<AppGroupRecordFfi>
Read the initial/current snapshot for this handle; follow its feature contract for one-shot versus repeatable reads.
ChatsSubscription::next
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub async fn next(&self) -> Option<AppGroupRecordFfi>
Wait for the next value; None means the observation ended. Bind one receive loop to this handle.
ChatListSubscription::snapshot
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub fn snapshot(&self) -> Vec<ChatListRowFfi>
Read the initial/current snapshot for this handle; follow its feature contract for one-shot versus repeatable reads.
ChatListSubscription::next
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub async fn next(&self) -> Option<ChatListRowFfi>
Legacy row-only update stream.
ChatListSubscription::next_update
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub async fn next_update(&self) -> Option<ChatListSubscriptionUpdateFfi>
Typed update stream, including atomic full-list replacement snapshots.
MessagesSubscription::snapshot
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub fn snapshot(&self) -> Vec<AppMessageRecordFfi>
Read the initial/current snapshot for this handle; follow its feature contract for one-shot versus repeatable reads.
MessagesSubscription::next
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub async fn next(&self) -> Option<MessageUpdateFfi>
Wait for the next value; None means the observation ended. Bind one receive loop to this handle.
TimelineMessagesSubscription::snapshot
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub fn snapshot(&self) -> Option<TimelinePageFfi>
Read the initial/current snapshot for this handle; follow its feature contract for one-shot versus repeatable reads.
TimelineMessagesSubscription::next
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub async fn next(&self) -> Option<TimelinePageFfi>
Await the next live update and return the resulting authoritative window. Windowing (ordering, dedup, head-anchoring while scrolled back, and the cap) is owned by the runtime, so this returns exactly the bounded window pagination operates on — render it directly. Use next_update(Self::next_update) instead to receive the raw delta.
TimelineMessagesSubscription::next_update
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub async fn next_update(&self) -> Option<TimelineSubscriptionUpdateFfi>
Consume raw timeline deltas or a replacement page. Use either next or next_update, not both; the host maintains delta ordering and bounds.
TimelineMessagesSubscription::paginate_backwards
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub async fn paginate_backwards(&self, count: u32) -> Result<TimelinePageFfi, MarmotKitError>
Extend the materialized window toward older history by up to count messages and return the new window. The returned page is already sorted, deduplicated, capped, and carries correct has_more_before / has_more_after flags — render it directly; no client-side merging or windowing is required. The store read runs off the caller thread and uses a different lock than next(), so a host driving next() on a background task can paginate without blocking (and this never blocks the UI thread, unlike the synchronous Marmot::timeline_messages).
TimelineMessagesSubscription::paginate_forwards
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub async fn paginate_forwards(&self, count: u32) -> Result<TimelinePageFfi, MarmotKitError>
Extend the materialized window toward the live head by up to count messages and return the new window. Reaching the head re-anchors the window (has_more_after becomes false). Same windowing/threading guarantees as paginate_backwards(Self::paginate_backwards).
GroupStateSubscription::snapshot
Current.
pub fn snapshot(&self) -> Option<AppGroupRecordFfi>
Read the initial/current snapshot for this handle; follow its feature contract for one-shot versus repeatable reads.
GroupStateSubscription::next
Current.
pub async fn next(&self) -> Option<AppGroupRecordFfi>
Wait for the next value; None means the observation ended. Bind one receive loop to this handle.
EventsSubscription::next
Current.
pub async fn next(&self) -> Option<MarmotEventFfi>
Wait for the next value; None means the observation ended. Bind one receive loop to this handle.
NotificationsSubscription::next
Current.
pub async fn next(&self) -> Option<NotificationUpdateFfi>
Wait for the next value; None means the observation ended. Bind one receive loop to this handle.
UserSearchSubscription::next_update
Current.
pub async fn next_update(&self) -> Option<UserSearchUpdateFfi>
Await the next step of the search, or None once it is over.
AgentStreamSubscription::stream_id_hex
Current.
pub fn stream_id_hex(&self) -> String
The resolved stream id this watch is following (hex).
AgentStreamSubscription::next
Current.
pub async fn next(&self) -> Option<AgentStreamUpdateFfi>
Wait for the next value; None means the observation ended. Bind one receive loop to this handle.
PresentedChatListSubscription::snapshot
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub fn snapshot(&self) -> Option<crate::conversions::PresentedChatListUpdateFfi>
Take the initial snapshot once, with generation and sequence zero.
PresentedChatListSubscription::next
Lower-level. For the corresponding lower-level subscription; use prepared screen windows for default chat UI.
pub async fn next( &self, ) -> Result<Option<crate::conversions::PresentedChatListUpdateFfi>, MarmotKitError>
Wait for the next value; None means the observation ended. Bind one receive loop to this handle.
</details>
<details> <summary>Host-managed automatic attachment acquisition</summary>
Marmot::begin_attachment_permission_update
pub async fn begin_attachment_permission_update( &self, account_ref: String, ) -> Result<String, MarmotKitError>
Revoke automatic permission for this account before asynchronous network/preference evaluation. Returns a single-use runtime/account generation. Requires HostManaged construction; do not persist the token or mint a new one from a stale callback. See the host-managed contract.
Marmot::request_automatic_attachment
pub async fn request_automatic_attachment( &self, account_ref: String, group_id_hex: String, target: AttachmentLocalTargetFfi, ) -> Result<AutomaticAttachmentRequestFfi, MarmotKitError>
Submit idempotent automatic demand for an authoritative original source slot. Returns current status plus whether work was newly queued; preserves suppression, history, deadlines and retry budgets. Use from foreground and restored workers; never substitute explicit download-again or legacy downloadMedia after a local miss. See Android migration.
Marmot::set_attachment_automatic_permission
pub async fn set_attachment_automatic_permission( &self, account_ref: String, generation: String, permission: AttachmentAutomaticPermissionFfi, ) -> Result<bool, MarmotKitError>
Apply media-category permission using the generation captured before evaluating host policy. False means stale, foreign or already consumed; it is not permission to retry with a fresh token. Approval is runtime-only and cannot override the durable automatic policy. See the permission lifecycle.
</details>
<details> <summary>Durable local sends and caller correlation</summary>
Marmot::local_send_status
pub fn local_send_status( &self, account_ref: String, group_id_hex: String, client_token: String, ) -> Result<Option<LocalSendStatusFfi>, MarmotKitError>
Read a retained submission's local state without relay I/O. None means no retained
association. Completed describes the worker attempt; inspect its summary disposition
and follow timeline updates for later delivery. See local sends.
Marmot::edit_local_message_with_client_token
pub async fn edit_local_message_with_client_token( &self, account_ref: String, group_id_hex: String, original_client_token: String, content: String, edit_client_token: String, ) -> Result<LocalSendAcceptanceFfi, MarmotKitError>
Durably admit a revision of an original text or reply submitted with a client
token, even while the original awaits relay publication. Use a new edit token
for each submitted revision. The return value is local acceptance, not
delivery; follow the edit token with local_send_status and preserve rejected
text for retry. The original token must belong to the same account and group.
See pending edits.
Marmot::reply_to_message_with_client_token
pub async fn reply_to_message_with_client_token( &self, account_ref: String, group_id_hex: String, target_message_id: String, text: String, client_token: String, ) -> Result<LocalSendAcceptanceFfi, MarmotKitError>
Durably admit a reply and bind its optimistic bubble to an opaque local token. Returns local acceptance before relay publication. Repeating the original request and token returns the same identity; changed requests are rejected. See local sends.
Marmot::send_message_draft_with_client_token
pub async fn send_message_draft_with_client_token( &self, account_ref: String, revision: Arc<MessageDraftRevisionFfi>, attachments: Vec<MediaAttachmentReferenceFfi>, client_token: String, ) -> Result<LocalSendAcceptanceFfi, MarmotKitError>
Atomically consume exactly the supplied draft revision and retain its token-bound message. Prepared attachments must match selected descriptors. Returns local acceptance, not delivery; never clear a newer composer on completion. See local sends.
Marmot::send_prepared_media_with_client_token
pub async fn send_prepared_media_with_client_token( &self, account_ref: String, group_id_hex: String, attachments: Vec<MediaAttachmentReferenceFfi>, caption: Option<String>, client_token: String, consuming_draft: Option<Arc<MessageDraftRevisionFfi>>, ) -> Result<LocalSendAcceptanceFfi, MarmotKitError>
Admit an uploaded ordinary-media snapshot with its stable client token and optional captured draft revision. Conditional consumption is transactional, bound to ordered plaintext SHA-256 hashes, and preserves newer drafts. The method has no reply target. See the captured-media contract for token replay, interruption recovery and matching bindings.
Marmot::send_text_with_client_token
pub async fn send_text_with_client_token( &self, account_ref: String, group_id_hex: String, text: String, client_token: String, ) -> Result<LocalSendAcceptanceFfi, MarmotKitError>
Admit text durably outside the account publication queue. Use one token per logical submission and reconcile by the exact token on timeline rows. Acceptance survives caller cancellation and restart; delivery uses ordinary subscriptions. See local sends.
Marmot::upload_media_with_client_token
pub async fn upload_media_with_client_token( &self, account_ref: String, group_id_hex: String, request: MediaUploadRequestFfi, client_token: String, ) -> Result<MediaUploadSubmissionFfi, MarmotKitError>
Upload encrypted attachments and optionally admit the resulting token-bound message. The result includes uploaded references and optional local acceptance. Uploads themselves are not idempotent or restart-resumable; query token status after unknown outcomes. See local sends for cancellation and epoch-bound media handling.
Marmot::upload_media_files_with_client_token
C: marmot_upload_media_files_with_client_token.
pub async fn upload_media_files_with_client_token( &self, account_ref: String, group_id_hex: String, request: MediaFileUploadRequestFfi, control: Arc<MediaFileTransferControlFfi>, client_token: String, ) -> Result<MediaUploadSubmissionFfi, MarmotKitError>
File-backed upload_media_with_client_token: every attachment is stored locally and uploaded before durable token admission; a source the disk cannot hold fails with StorageFull before anything is uploaded. Cancellation observed before admission starts returns an error and admits nothing. Once admission starts it is not interruptible, even before durable acceptance returns; follow local_send_status and timeline delivery, including uncertain-delivery handling. Admission rejects references from a source epoch that is no longer current with MediaReferenceStaleEpoch (upload again), and refuses while the group's epoch is unsettled with MediaReferenceEpochUnsettled (sync and send again). There is no fixed worker-response timeout; per-endpoint network deadlines still apply.
</details>
<details> <summary>Stateless public-event verification</summary>
verify_public_nostr_event_json
pub fn verify_public_nostr_event_json(event_json: String) -> bool
Verify both the canonical ID and BIP-340 signature of a public Nostr event.
This stateless helper needs no Marmot object or account and returns false
for malformed JSON or failed verification. It does not establish an allowed
author, kind, tag, relay provenance, or MLS group-membership policy; the host
must enforce those separately and bound any untrusted JSON before passing it.
</details>
<details> <summary>Audit v5 tracker and configuration</summary>
Marmot::audit_delivery_status_v5
pub fn audit_delivery_status_v5( &self, ) -> Result<Vec<AuditDeliveryStatusV5Ffi>, MarmotKitError>
Read each account's persisted v5 OTLP delivery status without dialing or touching the delivery cursor. Use it to show "audit delivery stalled since X: reason": last_success_at_ms against last_failure, whose kind separates local failures (StateOverLimit, TooManyOpenFiles, LocalIo, LocalBlocked) from receiver verdicts and whose http_status is set when the receiver answered. paused is true after ReceiverBlocked (for example 401) for the configured destination; changing the destination, endpoint or token, or calling post_audit_log_tracker_update_v5, retries it. ReceiverRejected counts rows the receiver refused in rejected_batches while delivery continues. backlog is the last measured undelivered bytes, segments, gaps and oldest undelivered record time, as of observed_at_ms. Accounts that never ran a v5 pass report no failure and no backlog.
Marmot::post_audit_log_tracker_update_v5
pub async fn post_audit_log_tracker_update_v5( &self, ) -> Result<AuditLogTrackerUpdateResultV5Ffi, MarmotKitError>
Run an immediate v5 OTLP delivery pass. Safe to call unconditionally: enabled reports the audit recording switch, and v5 is absent when no dedicated sender is configured; when present, accepted batches, pending accounts, blocked accounts, and idle accounts report the delivery state. A manual pass also retries accounts whose automatic delivery is paused. Automatic activity triggers use the same v5 sender and retry policy.
Marmot::set_audit_otlp_config_v5
pub fn set_audit_otlp_config_v5( &self, mut config: AuditOtlpConfigV5Ffi, ) -> Result<AuditOtlpConfigV5Ffi, MarmotKitError>
Install or remove an in-memory v5 OTLP audit destination. With enabled: true, provide a stable destination identity, an HTTPS /v1/logs endpoint, and a bearer token; local loopback testing additionally requires allow_loopback_dev: true. The returned configuration always omits the token. With enabled: false, the runtime clears the sender. This does not enable recording or persist credentials. A configuration change fences in-flight acknowledgments.
</details>
<details> <summary>Account attachment history</summary>
AccountAttachmentVersion::change_since
pub fn change_since( &self, previous: Arc<AccountAttachmentVersion>, ) -> AttachmentHistoryChangeFfi
Compare a freshly read account version with the original loaded-page baseline. RestartRequired discards loaded rows; Additions offers a head refresh while old-page cursors remain valid. The opaque value is not a row count; retain it in memory only.
Marmot::account_attachment_history_page
pub async fn account_attachment_history_page( &self, account_ref: String, query: AccountAttachmentQueryFfi, limit: u32, cursor: Option<Arc<AccountAttachmentCursor>>, ) -> Result<AccountAttachmentPageReadFfi, MarmotKitError>
Read at most 100 indexed attachment candidates across one local account with group, sender and inclusive date constraints. Empty filtered pages can have a continuation. Keep handles in memory, replace pages on RestartRequired, and use the typed metadata with the existing on-demand open/download APIs. See Account attachment history for bounds and ownership.
Marmot::account_attachment_history_version
pub async fn account_attachment_history_version( &self, account_ref: String, ) -> Result<Arc<AccountAttachmentVersion>, MarmotKitError>
Read the constant-work local account attachment change token, including after exhaustion. No network, acquisition or decryption starts. Keep the original loaded-page baseline and compare it using change_since; replace rows on RestartRequired and offer refresh on Additions.
</details>
<details> <summary>Native startup diagnostics</summary>
Marmot::set_startup_diagnostics_enabled
pub fn set_startup_diagnostics_enabled(&self, enabled: bool) -> Result<(), MarmotKitError>
Explicitly enable or revoke bounded native progress for a diagnostic investigation. Capture is off by default and shared by clones of this app handle. It does not change database content, diagnostic-sharing/upload consent, network behavior or cryptographic settings. Re-enabling an already-enabled capture preserves its history; disabling clears it and fences in-flight observations from later captures. Enable before the first account policy read when diagnosing account opening.
Marmot::startup_diagnostics_snapshot
pub fn startup_diagnostics_snapshot(&self) -> Result<NativeStartupSnapshotFfi, MarmotKitError>
Synchronously clone fixed native phases, monotonic durations and migration progress from independent memory. This does not query account storage or the keystore, and remains usable before start or while an account-opening future is blocked. At most 16 active scopes and 96 events are retained; drop counters expose truncation. Tokens are anonymous process-local scope numbers. No identifiers, paths, call arguments/results, keys or error messages are returned. Bound serialized host exports separately and collect only in an explicitly enabled diagnostic flow.
</details>
<details> <summary>Public event previews</summary>
Marmot::cached_public_event_previews
pub fn cached_public_event_previews( &self, account_ref: String, references: Vec<String>, ) -> Result<Vec<PublicEventPreviewFfi>, MarmotKitError>
Network-free read of cached public Nostr events referenced from message content, for first-frame rendering of event cards. Pass up to 16 note, nevent, naddr or hex event-ID references, with or without nostr:; each gets one row in input order, duplicates included, echoing the reference. Present rows carry the signature-verified event JSON. Deleted means the author published a NIP-09 deletion; Missing is not durable, so call resolve_public_event_preview; Unsupported rows never resolve. More than 16 references fails with InvalidPublicEventReferences; split the batch. The cache is per account and survives restarts. A cold call may open the account's encrypted cache, so warm it off the UI thread. Read author names and avatars from cached_identity_projections.
Marmot::resolve_public_event_preview
pub async fn resolve_public_event_preview( &self, account_ref: String, reference: String, ) -> Result<PublicEventPreviewFfi, MarmotKitError>
Fetch one referenced event from at most two safe relay hints plus the configured directory relays when it is missing or stale, store it if it verifies and matches, and return the resulting local state. An event-ID preview never refetches once every relay answered the fetch that cached it; otherwise, and for naddr previews, it refetches after 30 minutes. naddr keeps the newest version. Author-signed NIP-09 deletions apply in either tag form: an e tag removes that event (an naddr falls back to the previous version), an a tag removes every version up to its timestamp. Calls within 30 seconds of a finished fetch for the same reference return local state without network I/O, as does any call while the row is fresh, so call it for every reference a screen shows. A failed or empty fetch keeps prior content and stores no miss.
</details>
<details> <summary>deployment.rs</summary>
marmot_deployment_neutral
pub fn marmot_deployment_neutral() -> MarmotDeploymentFfi
Current free function. Generated Swift/Kotlin name: marmotDeploymentNeutral. C: marmot_deployment_neutral.
A deployment with no services: recovery requires every relay on a route, onboarding searches only the host's discovery relays, there is no Open Ranking tier, moderation reporting refuses a destination, and the keychain service is org.marmot-protocol.mdk. With no media servers new groups stay text-only, and with no group-image server group images are refused. Start here and fill in the services your deployment operates.
marmot_deployment_white_noise
pub fn marmot_deployment_white_noise() -> MarmotDeploymentFfi
Current free function. Generated Swift/Kotlin name: marmotDeploymentWhiteNoise. C: marmot_deployment_white_noise.
White Noise's deployment: its recovery relays, discovery indexers, media and image servers, Vertex Open Ranking, moderation label namespace and keychain service com.marmot.whitenoise. White Noise apps pass it to every constructor. Keep keychain_service unchanged for an existing install, or its account secrets are stranded.
</details>
<details> <summary>Backup recovery and observation</summary>
BackupRestoreSubscription::next
pub async fn next(&self) -> Option<crate::conversions::BackupRestoreStatusFfi>
Wait for the next aggregate progress or availability revision; None means the worker closed. This receive is cancellation-safe. Closing the observer does not cancel restore; use the named operation command.
BackupRestoreSubscription::snapshot
pub fn snapshot(&self) -> Option<crate::conversions::BackupRestoreStatusFfi>
Take the initial status exactly once; later calls return None. Use next for changes or backupRestoreStatus for a fresh read. This observer owns neither recovery words nor the operation.
Marmot::backup_history_availability
pub async fn backup_history_availability( &self, account_ref: String, group_id_hex: String, ) -> Result<Vec<BackupHistoryAvailabilityFfi>, MarmotKitError>
Read private words-again hints for a currently joined chat, using its variable-length MLS group id. A hint does not prove downloadable content or create membership. Re-read after a restore-watch revision or real join.
Marmot::backup_restore_status
pub async fn backup_restore_status( &self, account_ref: String, ) -> Result<BackupRestoreStatusFfi, MarmotKitError>
Read aggregate status without changing the operation. Complete means eligible work settled, not global completeness or proof that a pointer existed. Counts retain committed prefixes after cancellation.
Marmot::backup_settings
pub async fn backup_settings( &self, account_ref: String, ) -> Result<BackupSettingsFfi, MarmotKitError>
Read the selected account backup settings, including whether this device writes. Use this authoritative read after setup or a concurrent setting change; submitting a change is not proof it remains selected.
Marmot::begin_backup_restore
pub async fn begin_backup_restore( &self, account_ref: String, words: String, ) -> Result<BackupRestoreStatusFfi, MarmotKitError>
Start one ephemeral manual history-only restore per account from old recovery words. Only current own-leaf member chats can receive history; current keys and archived preferences stay unchanged. Keep the returned opaque operation token for cancellation. Clear host-owned word copies promptly; generated strings are not secure buffers.
Marmot::begin_recovery_words
pub async fn begin_recovery_words( &self, account_ref: String, ) -> Result<RecoveryWordsFfi, MarmotKitError>
Generate twelve new words for backup setup and two 1-based confirmation positions. Show once and confirm answers in that order. Never persist or log the words; this is separate from restoring with existing words.
Marmot::cancel_backup_restore
pub async fn cancel_backup_restore( &self, account_ref: String, operation: String, ) -> Result<bool, MarmotKitError>
Cancel only the named account-scoped operation. A stale valid token returns false; a malformed token is rejected. Committed history remains. Retry requires words again; dropping a watch does not call this command.
Marmot::cancel_recovery_words
pub async fn cancel_recovery_words(&self, account_ref: String) -> Result<(), MarmotKitError>
Forget a pending recovery-word confirmation without changing existing account backups. Clear host-managed display/input copies separately.
Marmot::confirm_recovery_words
pub async fn confirm_recovery_words( &self, account_ref: String, answers: Vec<String>, ) -> Result<(), MarmotKitError>
Confirm the two requested words in position order. Busy or error results keep the core setup for another try. MDK guards its owned queued answers; caller/generated copies still need host handling. Read backup settings again to render the selected outcome.
Marmot::run_due_backup_pass
pub async fn run_due_backup_pass( &self, account_ref: String, ) -> Result<BackgroundBackupOutcomeFfi, MarmotKitError>
Await one current or newly admitted due pass through serialized settlement and credit release. NotStarted means this call joined/admitted none; FinishedAttempt includes failed attempts and does not prove pointer publication. This neither forces work nor waits for future due work or global idleness. Cancelling the host await detaches only the waiter; worker stop/replacement returns TransportClosed. The host bounds its OS task lifetime; disabled device groups return NotStarted without starting a worker.
Marmot::set_runtime_backup_background_conditions
pub async fn set_runtime_backup_background_conditions( &self, wifi: bool, charging: bool, ) -> Result<(), MarmotKitError>
Report the runtime-wide current Wi-Fi and charging facts before workers exist and on changes; both are required for background admission. The latest report survives account-worker replacement and intervals with no workers, while a new runtime starts closed. This requires no account and starts no worker; eligible reports wake existing due dispatchers. An admitted pass settles after false. Manual restore remains independent.
Marmot::set_backup_background_conditions
pub async fn set_backup_background_conditions( &self, account_ref: String, wifi: bool, charging: bool, ) -> Result<(), MarmotKitError>
Compatibility wrapper for the runtime-wide platform report. It validates the existing active, signable, fully onboarded account before changing the shared facts and never starts that account worker. Prefer the account-free runtime setter; no parameter or return layout changed. Admitted passes settle after false; manual restore is independent.
Marmot::turn_off_backups
pub async fn turn_off_backups(&self, account_ref: String) -> Result<(), MarmotKitError>
Disable future account backups through the selected account setting. Existing archives remain; this is not archive deletion or cancellation of an already admitted pass.
Marmot::watch_backup_restore
pub async fn watch_backup_restore( &self, account_ref: String, ) -> Result<Arc<BackupRestoreSubscription>, MarmotKitError>
Observe one initial snapshot and later progress/availability revisions. Closing the watch stops observation only. Keep its account context and cancel explicitly with the operation token when desired.
</details>
<details> <summary>commands/emoji_set.rs</summary>
Marmot::emoji_set
pub async fn emoji_set( &self, account_ref: String, coordinate: String, ) -> Result<Option<EmojiSetFfi>, MarmotKitError>
Reads one stored set by coordinate (30030:<pubkey>:<d>) or naddr without network I/O, on the blocking pool. Returns none when it is not stored; use fetch_emoji_set for an explicit network fetch.
Marmot::emoji_sets
pub async fn emoji_sets( &self, account_ref: String, installed_only: bool, search: Option<String>, limit: Option<u32>, ) -> Result<Vec<EmojiSetFfi>, MarmotKitError>
Reads the encrypted emoji set projection on the blocking pool, off the caller's thread. installed_only returns installed snapshots in install order; otherwise the newest discovered sets first. search matches title, description, author (hex or npub) and shortcodes. No network I/O.
Marmot::fetch_emoji_set
pub async fn fetch_emoji_set( &self, account_ref: String, input: String, ) -> Result<EmojiSetFfi, MarmotKitError>
Fetches one set from a pasted coordinate or naddr, trying up to 8 of the naddr's relay hints and then the account relays, and stores it. Text only. Refused with InvalidEmojiSet for malformed input or a set with no valid emoji, EmojiSetNotFound when no relay has it.
Marmot::fetch_emoji_set_asset
pub async fn fetch_emoji_set_asset( &self, account_ref: String, coordinate: String, expected_event_id_hex: String, shortcode: String, ) -> Result<EmojiSetAssetFfi, MarmotKitError>
Downloads and validates one emoji of a stored set for a preview, with the same limits as install. Nothing is stored. Kept as its own call so the host can disclose it: it reveals the user's IP address to the image host the set's author chose, so call it only after the user opens the set. expected_event_id_hex is the event_id_hex of the version shown: when a sync or fetch has stored another version since, the call fails with EmojiSetChanged before any download.
Marmot::fetch_emoji_set_cover
pub async fn fetch_emoji_set_cover( &self, account_ref: String, coordinate: String, expected_event_id_hex: String, ) -> Result<EmojiSetCoverFfi, MarmotKitError>
Downloads and validates a stored set's cover image (image_url, its image tag) under the emoji image limits, through the same hardened public fetch as fetch_emoji_set_asset. Nothing is stored. It reveals the user's IP address to the host the set's author chose, so call it only after the user opens the set, never from a list; MDK loads it so the host never fetches set images itself. expected_event_id_hex is the version shown: another stored version fails with EmojiSetChanged before any download. A set without a cover fails with EmojiSetNotFound.
Marmot::install_emoji_set
pub async fn install_emoji_set( &self, account_ref: String, coordinate: String, expected_event_id_hex: String, control: Arc<EmojiSetInstallControlFfi>, ) -> Result<EmojiSetInstallResultFfi, MarmotKitError>
Snapshots the stored set version (its event id), downloads each emoji once over hardened HTTPS (public hosts only, redirects re-checked), validates it (4 MiB, 4096 px per side, 200 frames, PNG/APNG, GIF, WebP or JPEG decided by the bytes; a response typed as a non-image such as text/html is refused, any image/* type is accepted) and stores the bytes and SHA-256 under the account. expected_event_id_hex binds the install to the version the user was shown, including a reinstall for update_available: another stored version fails with EmojiSetChanged (carrying current_event_id_hex) before any download, and nothing stored fails with EmojiSetNotFound; install never fetches the set itself. control (EmojiSetInstallControlFfi) reports progress and cancels; a cancelled install, or one stopped by runtime shutdown or close, fails with EmojiSetInstallCancelled and stores nothing, leaving any previous snapshot as it was. Invalid, duplicate, failed and over-cap entries are reported in skipped, not fatal. A later change to the set's URLs or images never reaches the stored bytes until the user reinstalls. Caps: 50 installed sets, 500 emoji and 32 MiB per set, 128 MiB in all (EmojiSetLimit). Reveals the user's IP address to every image host in the set: call only after the user taps Install.
Marmot::installed_custom_emoji
pub async fn installed_custom_emoji( &self, account_ref: String, ) -> Result<Vec<InstalledCustomEmojiFfi>, MarmotKitError>
Every installed emoji, flattened in set install order then set order, for a picker: set coordinate and title, author, shortcode, MIME, dimensions, frames, SHA-256 and size. No URL. Shortcode collisions between installed sets are flagged with shortcode_collision, not resolved; host built-ins such as marmot and wn win in the host. No network I/O; the read runs on the blocking pool.
Marmot::read_installed_custom_emoji
pub async fn read_installed_custom_emoji( &self, account_ref: String, coordinate: String, shortcode: String, ) -> Result<InstalledCustomEmojiAssetFfi, MarmotKitError>
Reads an installed emoji's stored bytes (up to 4 MiB), checked against the SHA-256 recorded at install; a mismatch is an error, never other bytes. No network I/O; the read and hash run on the blocking pool. To use an emoji in a chat, upload these bytes as an encrypted attachment (send_tagged_media); never put the set's image URL or address in a message.
Marmot::sync_emoji_sets
pub async fn sync_emoji_sets( &self, account_ref: String, search: Option<String>, ) -> Result<EmojiSetSyncResultFfi, MarmotKitError>
Fetches up to 60 of the newest kind-30030 sets from the account's relays (the sticker discovery relays), keeping only the newest version of each address and at most 16 versions per fetch. Sets with no valid emoji are hidden. A search that is an npub or hex public key narrows the fetch to that author. Text only: never fetches an image.
Marmot::uninstall_emoji_set
pub async fn uninstall_emoji_set( &self, account_ref: String, coordinate: String, ) -> Result<bool, MarmotKitError>
Removes an installed snapshot and its stored bytes. Returns whether the set was installed. The discovered set stays in the projection. No network I/O.
Marmot::user_emoji_list
pub async fn user_emoji_list( &self, account_ref: String, ) -> Result<UserEmojiListFfi, MarmotKitError>
Reads the account's own kind-10030 emoji list and the kind-30030 sets its a tags point to (at most 64), for suggestions. Its loose emoji tags come back as own_emoji, installable as the pseudo-set 10030:<pubkey>:. Text only. MDK never publishes or edits kind 10030; it is a public list shared with other clients.
</details>
Relay liveness
Marmot::account_relay_liveness
pub async fn account_relay_liveness( &self, account_ref: String, ) -> Result<Vec<conversions::RelayLivenessFfi>, MarmotKitError>
Read every configured relay's canonical URL and current account-pool state without dialing.
Unobserved sessions are Unknown; closed configured sessions retain Offline. Optional attempt times and
bounded connection-error categories are session-local. See the state and privacy contract;
aggregate relay_health is unchanged.
Marmot::reconnect_relay
pub async fn reconnect_relay( &self, account_ref: String, url: String, ) -> Result<conversions::RelayLivenessFfi, MarmotKitError>
Reconnect one configured relay through its running account worker after the normal dial-safety check, preserving existing
socket roles and ownership. New manual connections follow configured membership, independently of UI observers.
After dispatch, wait up to five seconds for the next observed attempt state, which may be Connecting rather than a successful
connection. Use the liveness subscription for the eventual outcome; this does not establish message delivery.
Marmot::subscribe_relay_liveness
pub async fn subscribe_relay_liveness( &self, account_ref: String, ) -> Result<std::sync::Arc<crate::RelayLivenessSubscription>, MarmotKitError>
Open an account-scoped observer before reading its initial snapshot. Take snapshot() once, then apply each
next() list as a complete replacement. Updates follow socket, account-pool, and configured-list changes without
polling and may coalesce intermediate states. Close the observer when leaving the settings screen.
RelayLivenessSubscription::cancel
pub fn cancel(&self)
Stop this observer and wake pending receives with None. Future receives also return None.
The call does not disconnect the account's relays; release the foreign handle separately.
RelayLivenessSubscription::next
pub async fn next(&self) -> Result<Option<Vec<RelayLivenessFfi>>, MarmotKitError>
Wait for a complete replacement list. Slow consumers may skip intermediate states; cancellation does not consume
an update. None ends the stream after close or runtime shutdown. A read failure propagates as MarmotKitError
and ends this observer. Snapshot production runs on MDK's runtime, not the calling host thread.
RelayLivenessSubscription::snapshot
pub fn snapshot(&self) -> Vec<RelayLivenessFfi>
Take the initial list once; subsequent calls return an empty list. An empty first list is valid for an account without configured relay entries. This method does not consume a later update or initiate a connection.
<details> <summary>nip46.rs</summary>
Marmot::nip46_new
pub fn nip46_new(&self, config_json: String) -> Result<Arc<Nip46SessionFfi>, MarmotKitError>
Create an offline MDK-owned session from a bunker URI, pairing config, or secret export. Review and approve permissions before URI access or connection. Imports do not silently approve grants. No host signer callback is retained; the handle belongs to its creating Marmot object.
Marmot::nip46_login
pub async fn nip46_login( &self, session: Arc<Nip46SessionFfi>, default_relays: Vec<String>, bootstrap_relays: Vec<String>, inbox_relays: Vec<String>, ) -> Result<AccountSummaryFfi, MarmotKitError>
Create or reopen the external account using the verified shared signer and persist its communication credentials through MDK's configured secret store. Requires a successful explicit connect and an already-verified Ready session; other states are rejected without connecting, discovering relays, or creating an account. Messaging relay-list discovery and default publication follow external-signer login. Empty inbox relays reuse defaults. A session from another Marmot object returns ExternalSignerMismatch before network work.
Once Native adoption is admitted, caller cancellation only stops waiting; runtime-owned work continues. Pairing is a separate bounded, caller-cancellable connect call and makes no account changes while unbound. Explicit session cancel, disconnect, or logout interrupts adoption; shutdown interrupts and settles owned work before returning.
Adoption retains its admission generation through binding and network waits. A later explicit reconnect cannot resume adoption retired by disconnect.
Rollback does not reset newer-generation transport state or cancel its pending requests.
Before commit, a failed Native handoff restores the previous local callback and grant record without deleting pre-existing credentials. Completed accounts rebind without reopening setup and restore prior activation on failure. Already-published KeyPackages are not retracted. New and incomplete accounts retain pairing for possibly exposed publication retries. Post-commit journal cleanup errors do not revoke a network-ready account. Account sign-out cleanup remains explicit; legacy host login behavior is unchanged.
Marmot::nip46_register
pub async fn nip46_register( &self, account_ref: String, session: Arc<Nip46SessionFfi>, ) -> Result<(), MarmotKitError>
Attach a verified imported session to an existing account, persist credentials, and activate the worker. A different attached session must be removed before replacement. A foreign-owner handle returns ExternalSignerMismatch. Ordinary cold startup restores MDK-owned sessions without this import path.
Admitted adoption outlives caller cancellation and is interrupted and settled by shutdown, as with nip46_login. If no prior callback exists, a verified pairing remains attached for recovery when worker startup fails.
Marmot::nip46_resume
pub async fn nip46_resume( &self, account_ref: String, ) -> Result<Arc<Nip46SessionFfi>, MarmotKitError>
Obtain the account's shared session from MDK-owned credentials, without a host descriptor or signer callback. Persisted approval is retained unchanged; changed required grants need explicit review. Startup restores local credentials before workers; a missing account-identity proof can require bounded remote signing.
Marmot::nip46_remove
pub async fn nip46_remove(&self, account_ref: String) -> Result<(), MarmotKitError>
Detach the account's shared session and remove its persisted communication credentials. This does not replace account sign-out or data wiping.
Nip46SessionFfi::permissions
pub fn permissions(&self) -> Nip46PermissionsFfi
Read the currently required version and grants without recording review, approving access, or doing network work.
Nip46SessionFfi::review_permissions
pub fn review_permissions(&self) -> Nip46PermissionsFfi
Record the exact required snapshot for user review. Review does not approve; display its version and grants before calling approval.
Nip46SessionFfi::approve_permissions
pub async fn approve_permissions( &self, version: u32, grants: Vec<String>, ) -> Result<(), Nip46ErrorFfi>
Approve only the previously reviewed version and exact grant set after user consent. Missing review or changed grants return PermissionApprovalRequired. An imported descriptor, including one exported with approval metadata, does not grant access by itself. Bound account credential persistence runs on a blocking worker and finishes even if the foreign caller cancels its wait.
Nip46SessionFfi::connect
pub async fn connect(&self) -> Result<String, Nip46ErrorFfi>
Pair or reconnect, verify the pinned account public key, and adopt policy-checked signer relay changes. Returns user hex; messaging relays are unchanged. Requires permission approval. The independently driven native transport does not block the host or Tokio async workers. Cancelling a pending foreign call cancels its scoped request.
Nip46SessionFfi::pairing_offer
pub async fn pairing_offer(&self) -> Result<String, Nip46ErrorFfi>
Install the client-pairing listener and await relay subscription acknowledgements before returning the credential-bearing URI. Display that URI only after this call succeeds, then await connect while the pairing UI remains visible. Requires explicit permission approval and an unpaired client-initiated session. Cancellation retires the offer; obtain and display a fresh one before retrying.
Nip46SessionFfi::uri
pub fn uri(&self) -> Result<String, Nip46ErrorFfi>
Return the credential-bearing pairing URI locally after permission approval. This accessor does not install a listener; use pairing_offer before displaying a client-initiated QR code. Never log or persist either URI as ordinary settings.
Nip46SessionFfi::export
pub fn export(&self) -> Result<String, Nip46ErrorFfi>
Export secret communication credentials and pinned identities as compatibility JSON for an optional encrypted-vault backup. MDK-owned resume does not require this export. Logged-out credentials cannot be exported.
Nip46SessionFfi::status
pub fn status(&self) -> Nip46StatusFfi
Read local typed state, optional privacy-safe error, auth URL, request ID, and generation. No keys, pairing URI, or signer request payload is included. Approval is an intermediate challenge, not successful RPC completion.
Nip46SessionFfi::state_json
pub fn state_json(&self) -> Result<String, Nip46ErrorFfi>
Read the compatibility JSON status used by C. Existing state/detail/auth-url fields are retained with request, generation, and typed-error metadata. No network work.
Nip46SessionFfi::ping
pub async fn ping(&self) -> Result<(), Nip46ErrorFfi>
Check the remote signer through the independently driven shared transport. Failures retain the typed session reason. Cancelling a pending foreign call cancels its scoped request without terminally cancelling the session.
Nip46SessionFfi::disconnect
pub fn disconnect(&self)
Interrupt transport work and advance its generation while permitting explicit reconnection. Does not remove persisted credentials.
Nip46SessionFfi::cancel_request
pub fn cancel_request(&self, request_id: String) -> Result<(), Nip46ErrorFfi>
Cancel one matching pending request without cancelling the session. Stale IDs return RequestNotFound; other sessions are unaffected.
Nip46SessionFfi::complete_auth
pub fn complete_auth(&self, request_id: String) -> Result<(), Nip46ErrorFfi>
Acknowledge a matching auth challenge after reviewing its URL. The pending RPC still needs its final remote response. Stale IDs return RequestNotFound.
Nip46SessionFfi::cancel
pub fn cancel(&self)
Permanently cancel this session and interrupt pending work, including synchronous identity-proof callbacks. Does not remove persisted credentials or revoke an optional saved export.
Nip46SessionFfi::logout
pub async fn logout(&self) -> Result<(), Nip46ErrorFfi>
Attempt bounded remote courtesy logout and erase the session's communication credentials even when no acknowledgement arrives or the foreign caller cancels its wait. Successful local erasure detaches the revoked signer so a fresh pairing can be registered in the same process. A vault deletion error stops signing but retains cleanup ownership; retry logout or account-level removal after the vault recovers. This does not sign out the MDK account; account sign-out already leaves attached handles logged out.
</details>