Marmot
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
  • Start here

    • Documentation
  • Integration guides

    • Native apps · MarmotKit
    • Rust application runtime
    • C and native hosts
    • Bots and agents
    • Terminal and scripts
    • TypeScript quickstart
    • TypeScript storage
    • TypeScript networking
  • Reference

    • MarmotKit distribution
    • MarmotKit API
    • C API
    • Architecture
    • Upgrade guide

C and native hosts

MDK 0.17.0View source on GitHub

This guide follows the latest stable release. Use the documentation at your installed version’s tag when working with an older release.

marmot-c

C ABI over the Marmot app runtime (marmot-uniffi), for C/C++ and any raw-FFI consumer (Zig, Nim, Go, Odin, Lua, PHP, …). Runtime concepts, screen contracts and API selection are shared with Swift/Kotlin and live in the binding integration guide; this README covers what is specific to C: building and linking, binary compatibility, memory ownership, blocking calls, and C-only differences per feature.

Contents

  • What you get
  • Binary compatibility
  • Rules of the road
  • Using the ABI
  • Integration documentation
  • Lifecycle and teardown
  • Onboarding relay repair
  • Relay liveness
  • NIP-46 accounts
  • Feature notes: runtime construction, experimental device-group test builds, discarding a failed send, local sends, attachment handoff leases, attachment storage, custom reaction artwork, sticker pack sharing, emoji set installs, file-backed media upload, account attachment history, public event verification, host performance stages, Markdown rendering, identity references and pseudonyms, KeyPackage inventory, invitation lookup outcomes, selected chat-list presentation, chat screens and avatars, advanced timeline search, history may be incomplete notices, blocked leaves, group reporting, turning on account devices, undelivered Welcomes, backup recovery, host-driven agent publishing, audit v5 recording and delivery, audit source metadata and legacy files
  • Smoke test and example
  • Regenerating the header

Relay liveness

Connection states and privacy follow the shared relay contract.

marmot_account_relay_liveness returns an owned MarmotRelayLivenessList; marmot_reconnect_relay returns an owned MarmotRelayLiveness. Release them with marmot_relay_liveness_list_free and marmot_relay_liveness_free, respectively. The list owns every URL and optional error string. has_last_attempt_unix distinguishes an absent attempt timestamp from zero; a NULL last_error means no error is recorded.

marmot_subscribe_relay_liveness creates a MarmotRelayLivenessSubscription. Its snapshot and blocking next return owned lists; callback lists are borrowed only until the callback returns. Updates carry the latest complete snapshot and may coalesce. snapshot takes the initial snapshot once; later calls return an empty list. The relay callback additionally receives a MarmotStatus: OK accompanies a list, CLOSED accompanies terminal NULL, and a mapped error status accompanies terminal NULL on failure. Blocking next returns the same error status directly. cancel wakes pending reads without freeing the handle; release it with marmot_relay_liveness_subscription_free before freeing its client. Callback cancellation and context lifetime follow the generic subscription rules below.

What you get

  • libmarmot_c.so / libmarmot_c.a (cdylib + staticlib).
  • include/marmot.h, generated by cbindgen and checked in.
  • A pkg-config file (marmot-c.pc) in the staged output/ bundle.

Build the bundle locally:

./crates/marmot-c/c-bindings.sh   # stages output/ (libs, header, pkg-config)

Tagged releases (marmotc-v*) publish a Linux x86_64 zip (marmot-c-linux-x86_64-<version>.zip) with the same contents plus this README.

Binary compatibility

Build clients against the header shipped with the exact native library they load. Output records have concrete C layouts; this API has no tail-extension or cross-release layout-compatibility guarantee, and a shared major/minor number does not imply layout compatibility. Do not swap in a new library under an application compiled against older record layouts. Any additive record field, union tag or function requires regenerating marmot.h, recompiling consumers and shipping the matching library.

See the changelog for record-layout changes and upgrade requirements for each release.

MARMOT_STATUS_EVENT_TOO_LARGE (119) reports the shared size-refusal error. The last-error string contains only the coarse artifact and size class; C has no structured size-error payload. For a Welcome, status119 explains the observed attempt, not terminal delivery or proof of no earlier receipt. Keep native retry work and confirmed state, including when a crash or expired bookkeeping hides earlier exposure.

Rules of the road

  • Every fallible function returns MarmotStatus (MARMOT_STATUS_OK is 0); detail text for the calling thread's most recent failure comes from marmot_last_error_message() (free with marmot_string_free).
  • Structs returned by pointer are freed ONLY with their matching marmot_*_free, which deep-frees every field. Never free fields individually, never free twice; NULL is always a no-op.
  • Input structs and strings are borrowed: the library never frees or retains caller memory.
  • Values you supply are fixed-width integers, never C enums or _Bool: booleans are uint8_t (nonzero is true) and enums are uint32_t discriminants — use the generated MARMOT_* constants. Out-of-range values are rejected with MARMOT_STATUS_INVALID_ARGUMENT.
  • Required out-pointers are checked and zeroed before the call does any work, so an invalid required output pointer cannot cause the operation to run. Other failures/timeouts can follow durable intent or external side effects; inspect authoritative state before retrying a mutation.
  • Calls block unless documented otherwise. Blocking functions may be called from a subscription callback.
  • Subscriptions offer blocking *_next (0 timeout = wait forever; MARMOT_STATUS_TIMEOUT / MARMOT_STATUS_CLOSED otherwise) or callback registration. Callback item pointers are borrowed and valid only for the duration of the call; user_data must outlive every possible callback invocation (clear/free do not wait for a running callback).
  • Free every subscription handle before the client that created it, and never free an object while another call uses it.

Using the ABI

#include <stdio.h>

#include <marmot.h>

static void report(const char *what) {
    char *msg = marmot_last_error_message();
    fprintf(stderr, "marmot: %s: %s\n", what, msg ? msg : "(no detail)");
    marmot_string_free(msg);
}

int main(void) {
    MarmotClient *client = NULL;
    MarmotDeployment *deployment = NULL;
    const char *relays[] = {"wss://relay.example.org"};
    if (marmot_deployment_white_noise(&deployment) != MARMOT_STATUS_OK) {
        report("deployment_white_noise");
        return 1;
    }
    MarmotStatus status = marmot_client_new("/path/to/home", relays, 1, deployment, &client);
    marmot_deployment_free(deployment); /* the client keeps its own copy */
    if (status != MARMOT_STATUS_OK) {
        report("client_new");
        return 1;
    }
    if (marmot_client_start(client) != MARMOT_STATUS_OK) {
        report("client_start");
        marmot_client_free(client);
        return 1;
    }
    /* ... */
    if (marmot_client_shutdown_and_close(client) != MARMOT_STATUS_OK) {
        report("client_shutdown_and_close");
        marmot_client_free(client);
        return 1;
    }
    marmot_client_free(client);
    return 0;
}

Integration documentation

  • Shared binding integration guide: runtime lifecycle, screen contracts, API selection, localization and upgrade policy.
  • Complete C symbol reference: every function declaration, including ownership helpers and C-only compatibility shims.
  • Shared method reference: runtime purposes and recommended alternatives to older screen paths.
  • Integration index: a per-release upgrade guide for every release from 0.10.2, including C record, enum, error and schema changes.

Read the exact version's header and docs. The marmot_nip46_* adapter supports remote signer login and registration. Arbitrary host signer callbacks and external-signer onboarding remain UniFFI-only. The host secret-store vtable is a separate interface. The catalog includes C-only compatibility shims; prefer the composable runtime options constructor for new integrations.

Lifecycle and teardown

Before OS suspension/root handoff, use marmot_client_shutdown_and_close and observe its status; marmot_client_shutdown alone does not close shared database handles. Release subscriptions before clients, and never free an object while another call uses it. marmot_client_free waits for runtime worker cleanup on an ordinary host thread, preventing pending database destructors from racing process exit (since 0.10.3). Run final free off the UI thread. Calls from a Tokio runtime context retain nonblocking cleanup to avoid deadlock and are not a process-teardown barrier.

Onboarding relay repair

MarmotOnboardingFinding includes typed context, check purpose and outcome, declared capability, an owned actions/actions_len array, and optional has_observed_revision/observed_revision. Free all nested findings and actions through marmot_onboarding_snapshot_free; do not free the arrays separately. See the shared diagnostic evidence limits before interpreting query success as relay capability or publication evidence.

The historical SingleDevice onboarding step is a sign-in chat/history notice, not a blanket claim that multi-device use is unsupported. Its notice, actions, acknowledgment calls and publication gate are unchanged; MultiDeviceUnsupported is retained for compatibility and omitted from current findings. Adopt the shared notice copy and evidence limits in host localization with a published binding artifact. Continue is still an explicit acknowledgment, not permission to link devices or dismiss sign-in prompts.

For a general or inbox onboarding relay failure, call marmot_propose_onboarding_relay_repair and inspect the optional proposal->relay_repair in the returned snapshot. Its ordered before/after tags and occurrence changes preserve duplicate entries, direction markers, unrelated fields, and content. ManualReview has no approval action; do not publish it or treat it as a full reset. Free the snapshot with marmot_onboarding_snapshot_free after presenting the exact diff. Approval remains a separate revision- and recovery-epoch-bound call.

Explicit marmot_propose_onboarding_relays selections also return the typed preview. See the shared manual-edit preservation and checkpoint compatibility contract. The C signatures and snapshot ownership rules are unchanged.

C relay-repair previews encode original_content, proposed_content, every fields element in tags and changes, and each non-NULL endpoint as a JSON string literal. Decode exactly once with a parser that preserves embedded zero bytes and decoded UTF-8 lengths before displaying or prefilling an editor. For example, "a\u0000b" represents three bytes: 61 00 62; "" is an empty string, distinct from a NULL optional endpoint. Do not use strlen on decoded content or discard control bytes. The encoded C strings contain no embedded NULs; their snapshot ownership and deep-free rules are unchanged. Swift/Kotlin records retain ordinary strings and do not use this C-only encoding.

Runtime construction

marmot_client_new_with_configuration takes a MarmotClientOptions struct combining relay policy, cursor persistence, client label, secret store, attachment acquisition mode and device platform; NULL options or zero initialization selects the same defaults as the Swift/Kotlin MarmotOptions (see the shared contract). Use the matching header and library for that struct's layout. marmot_client_new_with_client_name is the older label-only constructor.

Every marmot_client_new* constructor takes a required MarmotDeployment just before out_client: the deployment's recovery relays, discovery indexers, media and image servers, Open Ranking, moderation label namespace, keychain service and relay event limits. Create one with marmot_deployment_white_noise or marmot_deployment_neutral, adjust it with the marmot_deployment_set_* functions, construct, then free it with marmot_deployment_free; the client keeps its own copy. For an available constructor, a NULL deployment returns MARMOT_STATUS_NULL_POINTER before anything opens. The unavailable experimental constructor checks its capability immediately after required output preflight, before reading the remaining arguments. White Noise hosts pass marmot_deployment_white_noise(). The shared contract covers what neutral means, the keychain caveat and how marmot_deployment_set_relay_event_limits limits apply.

For private integration fixtures, marmot_client_new_with_options accepts an explicit loopback relay policy and an optional host secret-store vtable. Existing constructors keep their public-only policy. Loopback broker access requires a separate publisher trust opt-in; neither permits private or link-local endpoints. Local insecure trust is intended only for tests.

Experimental device-group test builds

Follow the shared build and constructor guidance. marmot_client_new_with_experimental_device_groups takes the same arguments and unchanged MarmotClientOptions layout as marmot_client_new_with_configuration. Required output validation and clearing happen first. An incapable library returns MARMOT_STATUS_RUNTIME with experimental_device_groups_unavailable before opening the root or taking secret-store callback ownership; ownership transfers only on successful construction. A push extension or background worker on an experimental root needs this constructor too: under marmot_client_new_with_configuration, an account that holds or is joining a device group does not open, and its calls return MARMOT_STATUS_RUNTIME with experimental_device_groups_required.

Build the C library/header with ./crates/marmot-c/c-bindings.sh --dev-device-groups. It stages crates/marmot-c/output-dev-device-groups/ using a dev-device-groups/ child of the selected Cargo target directory. Ordinary output cleaning preserves this sibling directory.

Attachment handoff leases

marmot_open_attachment_handoff writes a private plaintext copy of a retained attachment for an OS surface that needs a real file and returns its path under a lease (NULL with MARMOT_STATUS_OK when the attachment is not held locally). A copy the disk cannot hold beyond the reserve returns MARMOT_STATUS_STORAGE_FULL. Call marmot_release_attachment_handoff when the surface is done: it returns MARMOT_STATUS_OK for an unknown or already released lease, MARMOT_STATUS_INVALID_MEDIA_REFERENCE for a malformed one, and MARMOT_STATUS_IO when the copy could not be deleted (the lease is kept; retry). Freeing the record with marmot_attachment_handoff_free does not release the lease. Both calls block, and the open holds the calling thread for the whole copy: run them off the UI thread. See the shared contract.

Attachment storage

marmot_attachment_storage_usage, marmot_attachment_storage_by_chat and marmot_largest_retained_attachments read a Manage storage screen's usage and largest-first pages; marmot_remove_chat_attachments and marmot_remove_attachments_older_than remove in bulk, each removal being an ordinary Remove. marmot_attachment_keep_media and marmot_set_attachment_keep_media read and set the account's "Keep media" window as MarmotAttachmentKeepMedia discriminants; attachments it removes read CleanedBySetting. Page cursors are borrowed from their page: keep the page alive while passing its next_cursor, then free the page. Calls block. See the shared contract.

Custom reaction artwork

marmot_reaction_attachment performs a bounded local lookup using the exact reaction event ID. It blocks off the UI thread and writes a standalone owned MarmotAttachmentEntry, or NULL with MARMOT_STATUS_OK when unavailable. Free the standalone result with marmot_attachment_entry_free; never use that free for an entry borrowed from a page. Use its original source target with ordinary attachment acquisition and local reads. See the shared reaction contract.

Sticker pack sharing

marmot_sticker_pack_share_link(account_ref, coordinate) follows the shared sticker sharing contract. It runs synchronously without network I/O and returns an owned string through its output pointer. Free that string with marmot_string_free.

Emoji set installs

marmot_install_emoji_set blocks for the whole install and borrows a host-owned MarmotEmojiSetInstallControl. Create it with marmot_emoji_set_install_control_new, pass it to one install, and free it with marmot_emoji_set_install_control_free only after the install has returned and every other call on the handle has finished. From another thread, marmot_emoji_set_install_control_cancel makes the install return MARMOT_STATUS_EMOJI_SET_INSTALL_CANCELLED (too late once the final write has started), marmot_emoji_set_install_control_is_cancelled writes a uint8_t, and marmot_emoji_set_install_control_progress fills a caller-provided MarmotEmojiSetInstallProgress with plain values that need no free. A NULL control returns MARMOT_STATUS_NULL_POINTER. Pass the expected_event_id_hex the user was shown; a different stored version returns MARMOT_STATUS_EMOJI_SET_CHANGED.

File-backed media upload

marmot_upload_media_files and its token-aware twin take borrowed MarmotMediaFileUploadRequest inputs with private regular-file paths instead of plaintext arrays. See the shared contract. MarmotMediaAttachmentReference.source_epoch_identity is a nullable local upload identity. Preserve the returned string when saving and sending a reference; NULL references remain readable but require a fresh upload before sending. See the shared upload provenance contract. The field changes the reference layout, including records embedding it. Calls block; run them off the UI thread. Strings and request arrays must remain valid until return. Create one MarmotMediaFileTransferControl per call, query or cancel it from another thread, and free it only after all calls on the handle have returned. Results use the existing upload/submission deep-free functions. No host path is included in published attachment metadata. A source the disk cannot hold returns MARMOT_STATUS_STORAGE_FULL before any upload. File-backed calls 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.

Account attachment history

marmot_account_attachment_history_page blocks off the UI thread and borrows its query arrays and cursor. Deep-free the result with marmot_account_attachment_page_read_free; its cursor and version are borrowed fields and must not be freed separately. Clone a version baseline with marmot_account_attachment_version_clone when it must outlive a page. Query flags use uint8_t, and arrays are capped at 100 before decoding. See the shared contract.

Discarding a failed send

marmot_discard_failed_send(client, account_ref, group_id_hex, message_id_hex, &out) follows the shared contract and publishes nothing. Inputs are borrowed; free *out with marmot_discard_failed_send_result_free, which also frees its media_ciphertext_sha256 array.

Local sends

The local-send contract (0.10.4) adds token-aware send/reply/draft/upload calls. C calls block until local acceptance (or upload then acceptance), rather than relay completion. Free their results with marmot_local_send_acceptance_free, marmot_media_upload_submission_free, or marmot_local_send_status_free. The nullable timeline client_token is owned by its row and released by the row's existing deep-free. Since 0.11.0, marmot_edit_local_message_with_client_token provides durable revisions of pending text or replies. Each revision needs a new edit token; the C call returns local acceptance and uses the same status and free functions.

Public event verification

marmot_verify_public_nostr_event_json is a stateless public-event check: it requires no client, returns a uint8_t result through a required out-pointer, and returns MARMOT_STATUS_OK with zero for malformed or invalid cryptographic input. Null/invalid UTF-8 pointers are argument errors. Callers still enforce their author, kind, tag, and JSON-size policy. See the shared contract.

Host performance stages

marmot_record_host_performance accepts 28 shared and nine Linux-specific host stages in addition to the existing readiness and visibility milestones. Read these 37 stages by their host_* operation name in MarmotAppPerformanceSnapshot.runtime_operations. Splash readiness, foreground readiness and outbound/inbound message visibility remain in host_splash_ready, host_foreground_local_ready, host_outbound_message_visible and host_inbound_message_visible, respectively. Free snapshots with marmot_app_performance_snapshot_free. Stage boundaries are defined in the runtime telemetry catalog. See the diagnostics contract.

Markdown rendering

MarmotMarkdownInline::Timestamp carries signed int64_t Unix seconds and a MarmotMarkdownTimestampStyle, with no allocated display string. The tag follows NostrUri, preserving existing inline tag values. Style values are ShortTime (t), LongTime (T), ShortDate (d), LongDate (D), ShortDateTime (f, the parser default), LongDateTime (F), CompactDateTime (s), CompactDateTimeSeconds (S), and Relative (R).

Format timestamps at render time using the device locale and time zone. Refresh labels after locale, time-zone or clock changes and when the app resumes; visible Relative nodes also need updates as time passes. An absolute-time tooltip or accessibility label is optional. Timestamp payloads require no separate free; marmot_markdown_document_free releases the containing tree. See the shared Markdown contract for host rendering guidance and Binary compatibility for adopting the new union tag.

MarmotMarkdownBlock includes a Details tag (bounded <details> / <summary> blocks) whose fields live behind MarmotMarkdownDetails. It was appended without changing existing discriminants or union stride; clients built against an older header cannot render it.

Identity references and pseudonyms

marmot_account_id_hex and marmot_normalize_member_ref accept nprofile and nostr:nprofile references (plus hex/npub/marmot://profile/ forms) and discard relay hints. Duplicate type-0 TLV entries keep the first key. After wrapper normalization, encoded tokens longer than 1023 UTF-8 bytes are rejected; a valid 1023-byte token still decodes when wrapped. The app helper's legacy NIP-21 parser may still accept a colon-suffixed nostr:<npub>: form, but C/UniFFI wrapper normalization rejects it.

marmot_default_profile_pseudonym hashes the supplied canonical hex account-id text; decode a scanned reference first. Passing uppercase hex or an undecoded npub silently produces a different name, not an error. marmot_random_profile_pseudonym is a cosmetic random roll from the same wordlists. Free those strings with marmot_string_free and normalized records with marmot_member_ref_free.

KeyPackage inventory

marmot_account_key_packages returns the current KeyPackage winner per addressable slot plus local-only rows. marmot_account_key_package_relay_events returns observed relay history from the same validated fetch window, including superseded events. Free that list with marmot_account_key_package_relay_event_list_free and the existing list with marmot_account_key_package_list_free.

marmot_local_account_key_packages is the local-first inventory. Call it immediately, then independently await marmot_refresh_account_key_packages and replace the displayed snapshot. The local read is synchronous SQLCipher I/O on the calling thread; do not invoke it on a UI or main thread. A retained package stays MARMOT_ACCOUNT_KEY_PACKAGE_LOCAL_STATE_RETAINED_PRIVATE_MATERIAL even when that exact event is observed; relay becomes true while local_state remains retained. On refresh failure, keep the local result. Free either list with marmot_account_key_package_inventory_entry_list_free. Each entry embeds the existing MarmotAccountKeyPackage record plus MarmotAccountKeyPackageLocalState.

Invitation lookup outcomes

MARMOT_STATUS_OK from creation or invitation does not mean every account was selected. Inspect member_outcomes (invite.member_outcomes for detailed invitations) using the shared lookup and result contract. Optional C operation fields (group_id_hex, created, or summary) are NULL when no operation occurred. Free the whole result even when its operation is absent.

marmot_start_direct_chat still requires its peer. It and explicit directory lookups can return MARMOT_STATUS_MISSING_KEY_PACKAGE when the lookup found nothing invitable; the detail ends in [obsolete_only] when the recipient must update their app. MARMOT_STATUS_DIRECTORY_LOOKUP_INCOMPLETE means the lookup ran out of time or relay coverage and nothing is known to be missing; offer retry. Authorization and other global failures still return error statuses, not partial recipient outcomes.

Undelivered Welcomes

Use marmot_pending_welcome_deliveries for the shared Welcome delivery contract. It returns an owned MarmotPendingWelcomeDeliveryList; release the whole result with marmot_pending_welcome_delivery_list_free. In records and the MARMOT_EVENT_WELCOME_DELIVERY_PENDING payload, read size_class only when has_size_class is true; false means Unknown. The event payload layout changes, so rebuild against the matching header and library. Each list owns its strings; do not free individual fields.

Selected chat-list presentation

marmot_presented_chat_list and marmot_presented_chat_list_row return complete existing row fields plus MDK-selected title/avatar descriptors. MarmotPresentedChatRow also embeds preview and actions (0.10.3; this changed its binary layout). The Draft preview owns its text; the parent row/snapshot free releases it. Message selection refers to the same row's last_message. See the shared chat-list row contract.

marmot_open_presented_chat_list returns an attached handle; take its *_snapshot once, then use *_next for whole-list replacements. The initial item has sequence zero. A repeated snapshot call returns CLOSED with NULL. This fallible subscription offers blocking next with timeout and typed storage/preparation errors. It has no callback pump: hosts drive next on their own worker and decide how to retry errors. Timeouts preserve the refresh obligation. Free each result with marmot_presented_chat_list_update_free and the handle with marmot_presented_chat_list_subscription_free. See the shared native contract for version ordering, localization, readiness, and account-switch behavior.

Chat screens and avatars

Live Chats/Unread/Archived/Left windows and independent account attention follow the native handoff contract for paging, sequence handling, cancellation, C ownership, and compatibility. Prepared conversation windows (history, header/capabilities, visible identities, read state and revisioned draft descriptors) follow the native conversation contract for opening, paging, cancellation, timeout, ownership and draft migration.

Avatar screen metadata is mirrored as MarmotAvatarAsset; resolved chat/conversation records carry an optional avatar metadata pointer. Use marmot_request_avatar_assets for up to 16 visible opaque targets, marmot_read_avatar_assets for bounded local bytes (at most 16 references / 16 MiB), and marmot_clear_avatar_cache for explicit local removal. Free returned lists with their matching marmot_avatar_asset_list_free / marmot_avatar_bytes_list_free functions.

Advanced timeline search

marmot_timeline_messages takes a borrowed MarmotTimelineMessageQuery. See the shared search contract for filters, ordering, and cursors. Initialize the entire struct with {0} before setting fields. The search fields have these C types and defaults:

Field C type Unset or default
sender const char * NULL
has_since, since uint8_t, uint64_t has_since = 0
has_until, until uint8_t, uint64_t has_until = 0
attachment_type uint32_t 0 (Any)
search_wall_clock uint8_t 0 (canonical group order)
cursor_group_id const char * NULL

These fields are appended after limit in the input layout. sender and cursor_group_id strings are borrowed for the call, like the other query strings. Nonzero flags are true, including has_since and has_until when their corresponding timestamp is zero. Invalid attachment_type values outside 0..=5 return MARMOT_STATUS_INVALID_ARGUMENT before querying the runtime. Free the returned page with marmot_timeline_page_free; the library does not free query inputs.

NIP-46 accounts

Keep one MarmotNip46Session per remote-signer account. Local-key accounts use their normal login path in the same client. C handles wrap the same MDK-owned session used by Swift and Kotlin, without retained host signer callbacks. See the shared session contract for identity, permission, status, and credential ownership.

NIP-46 sessions use the shared SOCKS5 routing policy. Invalid WN_SOCKS5_* configuration makes marmot_nip46_new fail with MARMOT_STATUS_INVALID_ARGUMENT, without connecting directly. The process policy is frozen at first use; clearing or correcting the environment afterward does not unblock it.

  1. Create an offline handle with marmot_nip46_new. Configuration accepts a bunker link in uri, or a relays array with an optional name for client pairing.
  2. Call marmot_nip46_review_grants; display its JSON version and grants. After user consent, pass the exact version and borrowed grant array to marmot_nip46_approve_grants. Imports, including unversioned descriptors, need explicit approval too. Review does not approve. For client-initiated pairing, await marmot_nip46_pairing_offer on a background worker before displaying its credential-bearing URI. It waits for relay subscription acknowledgements; marmot_nip46_uri alone does not install the listener.
  3. Run marmot_nip46_connect on a background worker while the pairing UI is visible. Bunker links can connect directly. It verifies get_public_key and adopts policy-checked switch_relays results for this signer transport only. Messaging relays are unchanged. An unsupported-method error leaves the previous signer relays in place; other errors fail connection.
  4. After marmot_nip46_connect succeeds, call marmot_nip46_login off the UI thread to create or reopen the external account. Login requires an already-verified Ready session; otherwise it rejects without connecting, discovering relays, or creating an account. It signs real MLS identity proofs and KeyPackages through the signer. Supply default messaging relays for lists the account has not published. Set inbox_relays separately, or pass NULL, 0 to use the defaults for both lists. Login publishes those defaults only for lists that discovery confirms absent. An incomplete directory read fails login with a retryable error instead of overwriting lists it could not see. Signed lists, including explicit-empty declarations, are kept.
  5. MDK persists verified signer credentials through the configured secret store. On restart, call marmot_client_start, then marmot_nip46_resume to obtain an account handle. Local startup restores credentials before activating workers; a missing account-identity proof can require bounded remote signing. No descriptor or host callback is needed. marmot_nip46_export remains an optional encrypted-vault backup. To import one, use new/review/approve/connect/register. Remove an existing owned session with marmot_nip46_remove before attaching a different one to the same account.

Poll marmot_nip46_state for compatibility JSON fields state, detail, and auth_url, plus typed last_error, request_id, and generation. Existing state strings remain; permission_approval, listening, disconnected, and reconnecting describe additional lifecycle states. marmot_nip46_status returns a typed MarmotNip46Status with the full MarmotNip46State/MarmotNip46Error vocabulary. Only read last_error when has_last_error is true; auth URL and request ID strings are nullable. Release the whole record with marmot_nip46_status_free, never its embedded strings separately. An approval URL is an intermediate response, not failure or completion. Show pending work until the final response; let the user review the URL before opening it. Pass its matching request ID to marmot_nip46_complete_auth; this acknowledges the challenge but does not complete the RPC. marmot_nip46_cancel_request cancels only the named pending request. Stale IDs return MARMOT_STATUS_INVALID_ARGUMENT. RPC requests have a 90-second budget; MDK account setup can time out sooner.

Login/register adoption follows the shared runtime-owned contract: once admitted, loss of the waiter does not cancel adoption. Pairing is a separate bounded, caller-cancellable connect call and makes no account changes while unbound. Cancel and discard abandoned pairing UI; call adoption explicitly only after verification succeeds. Account signout does not cancel unrelated unbound sessions. Use explicit session cancellation, disconnect, or logout to interrupt; client shutdown interrupts and settles owned adoption before returning. An explicit reconnect cannot resume adoption retired by an earlier disconnect. Rollback does not reset newer-generation transport state or cancel its pending requests. This does not permit freeing a handle during an active C call.

marmot_nip46_ping checks the remote signer; marmot_nip46_disconnect interrupts transport work but permits explicit reconnection. marmot_nip46_cancel permanently interrupts the shared session, including its account signer and other handles, without removing its persisted credentials or saved export. marmot_nip46_free releases only the C handle. Attached sessions remain owned by MDK, so freeing a login or resumed handle does not stop account signing or other handles. An unbound session stops when its final owner drops. Join every borrower before freeing a handle, and free all handles before their creating client. MDK account signout removes its owned signer credentials and leaves attached handles logged out; remove any optional host vault export too. marmot_nip46_logout is direct session revocation, not account signout. Its five-second courtesy request clears local client keys even without acknowledgement. If vault deletion fails, signing remains stopped and cleanup can be retried with logout or marmot_nip46_remove after the vault recovers. After account signout it reports an already logged-out session rather than sending another remote request. Do not free a handle while calls are in flight. Returned strings use marmot_string_free.

New-account publication retries retain pairing credentials across restart; a post-commit journal cleanup error does not revoke the ready account. Completed-account rebinds do not reopen setup, including when adoption fails. An unavailable signer can still stop the account's worker.

The loopback example exercises the C ABI with real NIP-44 websocket traffic, distinct user/bunker/client keys, mixed accounts, approvals and logout:

cargo run --release -p marmot-c --example nip46_smoke

Linked devices

See the shared linked-device guidance for invitation decisions, compatibility and retained-state limits.

marmot_linked_devices blocks on the account worker, reads local group state only, and writes an owned MarmotLinkedDeviceList; free it with marmot_linked_device_list_free. Each MarmotLinkedDevice has its slot_id_hex handle, is_this_device, label, client and platform (empty until set), linked_at, a linked_by_slot_id_hex that is NULL for the founder, a MarmotLinkedDeviceStatus and three setting flags. The list is empty in ordinary opens without explicit experimental device-group intent, and until this device trusts a device group. Re-read it on MARMOT_EVENT_LINKED_DEVICES_CHANGED. marmot_rename_linked_device blocks on the account worker and renames one device by its slot_id_hex with one roster commit; an empty label clears it.

marmot_update_linked_device_settings blocks on the account worker and patches any linked device's settings. Each has_<setting>/<setting> pair uses uint8_t: zero presence leaves the setting unchanged; nonzero presence supplies a value, with zero false and nonzero true. No structs or returned allocations are involved. Re-read the list on MARMOT_EVENT_LINKED_DEVICES_CHANGED; see the shared settings and recovery contract.

MarmotDeviceLinkSnapshot.moves owns its move views, sibling labels and overridden-slot strings; its existing marmot_device_link_snapshot_free releases them all. marmot_dismiss_device_group_move_sibling blocks on the account worker and returns another owned snapshot. Treat move_id as opaque. The status enum appends MARMOT_LINKED_DEVICE_STATUS_MOVED. See the shared move guidance. marmot_reset_device_group_for_repair is the explicit local reset action; free its returned snapshot with marmot_device_link_snapshot_free. Offer it when MarmotDeviceLinkSnapshot.device_group_stalled is set (rebuild against the matching header/library: the field is appended). Follow the shared reset and admission limits. The additive MarmotUnrecognizedSignIn.previously_linked_here is qualified local context; rebuild against the matching header/library. See shared sign-in guidance.

marmot_chat_history_imports blocks on the account worker and writes an owned MarmotChatHistoryImportList; free it with marmot_chat_history_import_list_free. Each entry's tagged state is Receiving or Imported. Imported MarmotTimelineMessageRecords name their source in the nullable imported_from. Re-read on MARMOT_EVENT_CHAT_HISTORY_IMPORTS_CHANGED.

When another of the account's devices removes this one, MARMOT_EVENT_DEVICE_UNLINKED fires once and the account stops on this device: MarmotAccountSummary.unlinked and signed_out stay set, and marmot_sign_in_account returns MARMOT_STATUS_ACCOUNT_UNLINKED. marmot_sign_out_and_wipe skips leaving its chats and deleting its slot. See the shared contract.

With a linked device that is not signing out too, marmot_sign_out_and_wipe first asks the account's other devices to take this one out, which can block for about 30 seconds, and leaves them the chats they can. MarmotWipeOutcome.groups_left_to_siblings counts those chats, and siblings_not_reached says it could not ask them in time, so it tried to leave every chat itself, reporting any it could not in group_leave_failures; tell the user. In a chat the account administers with another account, it steps the account down first and can block about 30 seconds more for its removal. See the shared contract.

marmot_key_package_refresh_overdue blocks on the account worker, reads local state only, and writes whether this device's device group has held its KeyPackage refresh back for a week. Re-read it on MARMOT_EVENT_KEY_PACKAGE_REFRESH_OVERDUE_CHANGED. See the shared contract.

Unrecognized sign-ins

marmot_unrecognized_sign_ins blocks on the account worker, reads local state only, and writes an owned MarmotUnrecognizedSignInList; free it with marmot_unrecognized_sign_in_list_free. marmot_check_sign_ins checks the account's slots now, over the network, and writes the list after the check. Each MarmotUnrecognizedSignIn has its slot_id_hex handle, client (empty when none), appeared_at, last_seen_at, before_this_device, signed_in, a MarmotUnrecognizedSignInState, and a linked_by_slot_id_hex set only for LinkedElsewhere. marmot_answer_sign_in takes a MarmotSignInResponse discriminant as uint32_t; an out-of-range value is MARMOT_STATUS_INVALID_ARGUMENT. The list is empty in ordinary opens without explicit experimental intent. Re-read it on MARMOT_EVENT_UNRECOGNIZED_SIGN_INS_CHANGED. See the shared contract.

marmot_start_fresh answers every sign-in from before this device Not now, now and when one is listed later, without rejecting any, and marmot_started_fresh writes whether the device did so and still has no device group; re-read it on MARMOT_EVENT_LINKED_DEVICES_CHANGED.

Compromise warning

marmot_compromise_warning blocks on the account worker, reads local state only, and writes the account's open compromise warning on this device as an owned MarmotCompromiseWarningItemList; free it with marmot_compromise_warning_item_list_free. An empty list means no warning is open. Each MarmotCompromiseWarningItem has its reason, the slot_id_hex the item names, a key_package_ref_hex set only for MARMOT_COMPROMISE_WARNING_REASON_FOREIGN_OWN_SLOT_KEY_PACKAGE, and occurred_at. reason is a MarmotCompromiseWarningReason discriminant carried as uint32_t: later releases add values, so show one the host does not know as a generic reason. marmot_dismiss_compromise_warning closes the warning on this device only. Re-read it on MARMOT_EVENT_COMPROMISE_WARNING_CHANGED. It is empty in ordinary opens without explicit experimental intent. See the shared contract.

Linking a new device

marmot_start_device_link, marmot_confirm_device_link_match and marmot_cancel_device_link (on the new device), marmot_link_device and marmot_decline_device_link (on a device already signed in) and marmot_device_link_snapshot each block on the account worker and write an owned MarmotDeviceLinkSnapshot; free it with marmot_device_link_snapshot_free. new_device is NULL unless this device asked to be linked. Both MarmotNewDeviceLinkState and each prompt's MarmotDeviceLinkPromptState are tagged unions: Comparing carries code/code_len emoji with screen-reader descriptions, CannotLink carries missing/missing_len, and AddedElsewhere carries both labels. marmot_link_device takes the label and two uint8_t setting flags. Every call requires the explicit experimental build and constructor described above. Re-read on MARMOT_EVENT_DEVICE_LINK_CHANGED. See the shared contract.

History may be incomplete notices

marmot_history_notices blocks on the account worker, reads local durable state only, and writes an owned MarmotHistoryNoticeList; free it with marmot_history_notice_list_free. Each MarmotHistoryNotice has an opaque notice_id, a MarmotHistoryNoticeCause, a group_id_hex that is NULL for an account-wide occurrence, and has_parked_at_ms/parked_at_ms. marmot_dismiss_history_notice writes true when it durably retired that occurrence and false for a stale id; a malformed id returns MARMOT_STATUS_INVALID_HEX. Re-read the list on MARMOT_EVENT_HISTORY_NOTICES_CHANGED; a group's own occurrences also set MarmotGroupRecoveryStatus.history_may_be_incomplete and fill its history_notice_ids array, released by marmot_group_recovery_status_free. See the shared contract for when notices appear, disappear and return. marmot_account_recovery_status writes an owned MarmotAccountRecoveryStatus: the groups still catching up (catching_up_group_ids_hex/catching_up_group_ids_hex_len), inbox_catching_up, and every notice (notices/notices_len); free it with marmot_account_recovery_status_free and re-read it on MARMOT_EVENT_RECOVERY_STATUS_CHANGED. The recovery runner supplies the catching-up fields. Current epoch-gap exhaustion emits MARMOT_HISTORY_NOTICE_CAUSE_EPOCH_GAP; a rejoin emits one MARMOT_HISTORY_NOTICE_CAUSE_BEFORE_REJOIN per new copy of the group. Other cause labels preserve compatibility: MARMOT_HISTORY_NOTICE_CAUSE_UNPROVEN_HISTORY is no longer emitted, so keep exhaustive switches. Group changes for a group whose unresolved epoch-gap recovery covers its current local epoch return MARMOT_STATUS_GROUP_CATCHING_UP. Retry after it syncs, or, once the user accepts that the change may split the group, call marmot_acknowledge_group_catching_up and retry. See the shared contract. Group changes can return MARMOT_STATUS_GROUP_COMMIT_UNDELIVERED when the group's last change has not reached every group relay; marmot_group_commit_delivery reports the owed relays immediately (free with marmot_group_commit_delivery_free), and marmot_acknowledge_group_commit_undelivered lets one change through. See the shared contract for when the status is returned.

Automatic Unrecoverable rejoin runs inside the account workers; C hosts keep their existing group-state subscriptions. See the shared automatic rejoin contract for authorization, history retention and availability requirements.

Blocked leaves

When leave_blocked is set on MarmotAppGroupRecord, MarmotChatListRow or MarmotGroupManagementState, the account is the chat's last active admin and the leave cannot finish. While can_cancel_leave is true, offer Cancel and call marmot_cancel_leave; it allocates nothing, applies to this device only, and returns MARMOT_STATUS_LEAVE_NOT_BLOCKED in any other state. See the shared leave contract.

Group reporting

The C ABI mirrors the shared reporting operations. Pages are capped at 100 and cursors are exclusive. Deep-free returned pages with marmot_content_report_page_free or marmot_report_dismissal_page_free; the reported message uses the ordinary timeline record and its free function.

Turning on account devices

The C ABI mirrors the shared flow. Call marmot_account_devices_activation and offer marmot_enable_account_devices only on MARMOT_ACCOUNT_DEVICES_ACTIVATION_ELIGIBLE. A refused activation returns MARMOT_STATUS_ACCOUNT_DEVICES_ACTIVATION_REFUSED; the last-error detail names the aggregate reason.

Host-driven agent publishing

marmot_agent_publisher_new anchors a stream and returns an opaque handle. Pass a QUIC candidate and broker trust options; cryptographic keys and transcript framing stay inside MDK. Append text, status, or progress using marmot_agent_publisher_append. Its receipt reports accepted record count and any preview transport failure; transport loss preserves the transcript.

marmot_agent_publisher_finish seals the transcript and sends the durable final message. Inspect the returned send disposition for delivery state. If sending fails, call finish again on the same handle; the sealed request is retained. After success, repeated finish returns the original receipt. Appends after sealing fail. These guarantees last for the handle's lifetime; publisher state is not restored after a process restart.

Cancel or free a handle to stop its preview. A finish already in progress wins over cancellation. Free every publisher before its client, and never free a handle concurrently with another call using it. Free info, append receipts, and send receipts with their matching generated free functions.

Audit v5 recording and delivery

v5 replaces v4 as the audit format. Recording remains opt-in through MarmotAuditLogSettings, and new recordings write only v5 JSONL files. Hosts that record audit logs must configure v5 delivery, or new evidence never leaves the device. Call marmot_set_audit_otlp_config_v5 with a dedicated OTLP /v1/logs destination and bearer token on every launch, because it is held in memory only. The returned config redacts the token; free it with marmot_audit_otlp_config_v5_free. Call marmot_post_audit_log_tracker_update_v5 for a manual pass and free its result with marmot_audit_log_tracker_update_result_v5_free. The result's v5 member reports accepted, pending, blocked, and idle counts, and is NULL when no destination is configured. The tracker's activity triggers use the same in-memory v5 config with their batching and retry policy. Set enabled to false to clear the destination. Loopback requires the explicit allow_loopback_dev flag, while public destinations require HTTPS.

marmot_audit_delivery_status_v5 returns a MarmotAuditDeliveryStatusV5List with one row per account; free it with marmot_audit_delivery_status_v5_list_free, which also frees each row's nullable last_failure and backlog. has_http_status tells whether the receiver answered. The fields and the pause/retry semantics match the shared description.

Local audit retention (maximum age and per-account size budget, shared with the Swift and Kotlin bindings in marmot-uniffi/README.md) is read with marmot_audit_log_retention and replaced with marmot_set_audit_log_retention, which takes a borrowed MarmotAuditLogRetention and returns the clamped stored value. Free both results with marmot_audit_log_retention_free.

Audit source metadata and legacy files

Call marmot_set_audit_log_source with a borrowed MarmotAuditLogSource at startup, before opening accounts, to supply the optional system hardware_model, platform and app_version that each new audit recorder writes into its source row. It is held in memory, so set it on every launch. It returns the trimmed stored copy; free that with marmot_audit_log_source_free. Never pass a device name, hostname or serial number as the model.

v5 OTLP delivery is the only remote audit path. Historical v4 files are never delivered; they stay listable and deletable until local retention expires them.

Backup recovery

See backup recovery and background conditions for the shared setup, current-membership restore, background eligibility and secret-handling contract. The C functions use the same names with the marmot_ prefix and snake case; Wi-Fi and charging inputs are uint8_t booleans. All operations block according to the usual ABI rules.

marmot_set_runtime_backup_background_conditions reports once for the runtime and starts no worker. The account-shaped function remains a validating compatibility wrapper. marmot_run_due_backup_pass blocks through one current/newly admitted due pass and writes MarmotBackgroundBackupOutcome by value; no allocation or free is needed. FinishedAttempt is settlement-attempt completion, not publication success. Use the call off the host UI thread; if the OS opportunity ends, stopping the worker/runtime from another thread ends the wait with MARMOT_STATUS_TRANSPORT_CLOSED. New exports need the matching generated header/library; existing parameter layouts are unchanged.

Free recovery-word output with marmot_recovery_words_free after clearing displayed and caller-owned copies. The free erases MDK's returned word buffers before releasing their C allocations. It does not erase host copies or earlier managed/FFI copies. Confirmation answers and restore phrases are borrowed inputs. Keep them valid for the call, then clear the host's buffers; MDK never retains the caller's pointer. Do not print words or entire recovery output records.

marmot_watch_backup_restore returns an observer handle. Its snapshot is available once; subsequent next calls use the standard timeout/closed statuses or callback interface. Freeing or clearing this observer never cancels the operation: call marmot_cancel_backup_restore with its exact account-scoped operation token. Snapshot and next outputs are owned and must be freed; callback output is borrowed for the callback's duration. Free status and availability-list outputs with their matching generated free functions.

MarmotTimelineMessageRecord.history_import_provenance is a nullable tagged union. Device and Backup payloads are embedded allocations released by the timeline record's deep-free; do not free them separately. Preserve the legacy sibling-only imported_from field when supporting older rendering paths. The additional timeline field changes its layout, including records that embed it.

Smoke test and example

examples/smoke.c is a worked example covering lifecycle, Markdown tagged-union walking, offline reads, the error taxonomy, and best-effort identity creation. ./crates/marmot-c/c-smoke.sh (or just c-smoke) builds and runs it against both linkage models (valgrind when available). Pass --debug first to reuse debug/test-profile dependencies for a faster local or PR smoke run; release and scheduled validation use the default release build.

On macOS both build scripts pin release strip=none, matching MarmotKit's Apple policy: Rust's debug-stripping path can emit a misaligned Mach-O string table that Xcode 27 rejects. Optimization remains enabled; Linux packaging is unchanged. Revisit the pin after a Rust toolchain upgrade incorporating rust-lang/rust#158410, and remove it only after the default optimized shared/static smoke passes without the override. The C CI workflows run on Linux; the Darwin branch has local smoke evidence only. Changing strip changes Cargo's release-profile fingerprint, so alternating these scripts with an unpinned cargo build --release can rebuild release dependencies.

On OpenBSD c-bindings.sh builds SQLCipher with OMIT_MEMLOCK and routes its malloc/calloc to malloc_conceal/calloc_conceal, so a host can run under pledge(2), which forbids mlock. Concealed pages stay out of core dumps and are wiped on free, but are not pinned in RAM: swap protection follows the host's swap encryption. Flags already in LIBSQLITE3_FLAGS are kept.

Regenerating the header

just c-header

The mirror surface is macro-generated, so header generation runs cbindgen with macro expansion (RUSTC_BOOTSTRAP=1 on the stable toolchain). CI diff-gates the checked-in header.

Prev
Rust application runtime
Next
Bots and agents
Protocol
Development Kit
Documentation
Apps
Awesome
Releases
Community
GitHub
Donate
Contact
©2025–2026 Internet Privacy Foundation. All rights reserved.
Marmot