Skip to main content Crate xmtp_configuration Copy item path Source attachments Checks for attachment storage configuration shared by the backend and client. ApplicationComponentDefinition One operator-defined group metadata field. A client registers it in a new
group when in_groups is set and in a new DM when in_dms is set. AttachmentsConfiguration Attachment storage offered by this deployment. AuthConfiguration What a client must present to be admitted. The client acts only on
enabled and required_scopes; the rest exists for operator tooling. ComponentPermissions The member policies of one component. None is a policy the definition
left out, which a valid definition never does. DockerUrls Local chain used for smart-contract-wallet verification. GrpcUrls Temporary test URL names. Remove with the Task 9 binding update. GrpcUrlsToxic Temporary fault-test URL name. Remove with the Task 9 binding update. HandlesConfiguration Handle settings the deployment applies when it admits a claim. They are
published for apps, for example to hint at a name a user types. The client
never applies them: it neither fails an operation nor hides a handle because
of them. LimitsConfiguration Request shapes the deployment accepts. A client chunks its work to these
values rather than to its compiled constants. MlsConfiguration Advisory group shapes. The backend publishes them and does not enforce them. RetentionConfiguration How long the deployment keeps each payload kind, in seconds. ServerConfiguration One immutable snapshot of what a deployment published. SigningKeyDescription Public identity of one accepted signing key. Never the key itself. StaticConfigProvider A provider a test constructs from any values, with no database and no
fetch. Passing one to the builder disables fetch, store, refresh, and the
identifier check. StoredConfigProvider The provider backed by the copy stored in the client database. ApplicationComponentError Why one application component definition cannot be used. Carries no
value from the definition, so the backend can report it for a document
whose contents came from the environment. AttachmentConfigurationError An attachment configuration field and the reason it cannot be used. Eip155ChainIdError Why a chain identifier is not a routable eip155 chain id. MetadataPolicy A group metadata permission policy, mirroring the wire MetadataPolicy. ServerConfigurationError Why a published configuration cannot be used. ACTIVE_DATABASE_POLL_INTERVAL Maximum delay between fresh database checks while work is active. ANVIL_URL_DEFAULT Local chain address when no worktree environment is loaded. APPLICATION_COMPONENT_IDS Component IDs an operator may define, 0xC000–0xFEFF. The group
metadata ID ranges derive from this, so both sides agree on one range. AUTH_LOCKOUT_COOLDOWN Time before one authentication probe is allowed after lockout. BACKEND_DEFAULT_GROUP_MESSAGE_SECONDS Default age for ordinary group messages, in seconds. BACKEND_DEFAULT_HANDLE_MIN_NAME_LENGTH Default minimum number of characters in a handle’s name part. The backend
applies it when no handles.min_name_length is configured, and a client
uses it when a snapshot does not carry the value. BACKEND_DEFAULT_KEEPALIVE_INTERVAL_MS Default interval between stream keepalive frames, in milliseconds. BACKEND_DEFAULT_KEY_PACKAGE_SECONDS Default age for key packages, in seconds. BACKEND_DEFAULT_MAX_ENVELOPE_BYTES Default maximum encoded envelope size, in bytes. BACKEND_DEFAULT_MAX_HTTP2_STREAMS Default maximum HTTP/2 streams per connection. BACKEND_DEFAULT_MAX_IDENTITY_ENTRIES Default maximum identity entries per inbox. BACKEND_DEFAULT_MAX_LOOKUP_IDENTIFIERS Default maximum identifiers in one inbox lookup. BACKEND_DEFAULT_MAX_NEWEST_FULL_TOPICS Default maximum number of full newest topics. BACKEND_DEFAULT_MAX_NEWEST_METADATA_TOPICS Default maximum number of metadata-only newest topics. BACKEND_DEFAULT_MAX_PING_BURST Default client ping token-bucket burst. BACKEND_DEFAULT_MAX_PING_FRAMES_PER_SECOND Default client ping rate, in frames per second. BACKEND_DEFAULT_MAX_PUBLISH_TOPICS Default maximum number of topics in one publish. BACKEND_DEFAULT_MAX_QUERY_LIMIT Default maximum query limit. BACKEND_DEFAULT_MAX_QUERY_TOPICS Default maximum number of query topics. BACKEND_DEFAULT_MAX_REQUEST_BYTES Default maximum encoded request size, in bytes. BACKEND_DEFAULT_MAX_RESPONSE_BYTES Default maximum encoded response size, in bytes. BACKEND_DEFAULT_MAX_SCW_SIGNATURES Default maximum smart-contract-wallet signatures per request. BACKEND_DEFAULT_MAX_STATIC_TOPICS Default maximum topics in a static subscription. BACKEND_DEFAULT_MAX_STREAM_TOPICS Default maximum registered topics per stream. BACKEND_DEFAULT_MAX_UPDATE_ADDS Default maximum topics added by one stream update. BACKEND_DEFAULT_MAX_UPDATE_BURST Default stream update token-bucket burst. BACKEND_DEFAULT_MAX_UPDATE_FRAMES_PER_SECOND Default stream update rate, in frames per second. BACKEND_DEFAULT_MAX_UPDATE_REMOVES Default maximum topics removed by one stream update. BACKEND_DEFAULT_MAX_UPLOAD_BYTES Default maximum ciphertext size for one attachment upload, in bytes. BACKEND_DEFAULT_QUERY_LIMIT Default per-topic query limit. BACKEND_DEFAULT_STATEMENT_TIMEOUT_MS Default database statement timeout. Client identity waits exceed this value. BACKEND_DEFAULT_WELCOME_SECONDS Default age for welcome messages, in seconds. BACKEND_INSTALLATION_ID_BYTES Welcome, key-package, and identity topic identifier length, in bytes. BACKEND_TEST_TOXIC_URL_DEFAULT Local backend proxy URL when no worktree environment is loaded. BACKEND_TEST_URL_DEFAULT Local backend URL when no worktree environment is loaded. BUSY_TIMEOUT max time the database will wait to acquire a lock for a table CHAIN_CALL_TIMEOUT_MS The longest one chain RPC call may take, its permit wait included. CONFIGURATION_REFRESH_ATTEMPTS Attempts in one refresh run. After the last failure the run ends and the
stored copy is left alone. CONFIGURATION_REFRESH_BACKOFF Waits between the attempts of one run. CONFIGURATION_REFRESH_INTERVAL How long after one refresh run ends before the next one starts, before
jitter. The first run starts this long after build. CONFIGURATION_REFRESH_JITTER Random spread added to each wait, so a fleet of clients does not refresh
at the same time. CONVERSATION_LIST_DEFAULT_LIMIT Conversations returned by one app conversation listing that names no limit. CREATE_PQ_KEY_PACKAGE_EXTENSION DEFAULT_CONSUMER_LEASE_DURATION Lease duration for the default app message consumer. DEFAULT_GROUP_DESCRIPTION DEFAULT_GROUP_IMAGE_URL_SQUARE DEFAULT_GROUP_NAME ENABLE_COMMIT_LOG GROUP_ID_BYTES Length of a keyed group id and of a commit-log id, in bytes: the topic
identifier of kinds 0 and 4. GROUP_KEY_ROTATION_INTERVAL_NS GROUP_MEMBERSHIP_EXTENSION_ID GROUP_PERMISSIONS_EXTENSION_ID HMAC_SALT IDENTITY_DEPENDENCY_CONCURRENCY Maximum concurrent identity proof requests in one resolver batch, and the
most association states one batch read derives at once. IDENTITY_REFERENCE_MAX_RETRY_INTERVAL Longest interval between primary reads for absent identity updates. IDENTITY_REFERENCE_RETRY_INTERVAL First interval between primary reads for absent identity updates. Each
later interval doubles up to IDENTITY_REFERENCE_MAX_RETRY_INTERVAL. IDENTITY_REFERENCE_WAIT Healthy primary-read time allowed for an absent pinned identity update.
This exceeds the backend’s default statement timeout. INSTALLATION_RETRY_MIN_PROTOCOL_VERSION First version whose receivers accept an inbox adding back its own leafless
installation. Senders retry only in groups whose floor is at least this. INSTALLATION_THRESHOLD_FOR_WELCOME_POINTER_SENDING KEYS_EXPIRATION_INTERVAL_NS KEY_PACKAGE_QUEUE_INTERVAL_NS KEY_PACKAGE_ROTATION_INTERVAL_NS Interval in NS used to compute next_key_package_rotation_ns.
This defines how often a new KeyPackage should be rotated ,
but does not determine the actual KeyPackage expiration. LEGACY_GROUP_ID_BYTES Length of a legacy group id, in bytes. Legacy ids come only from imported
archives, and no topic carries one. LOCALHOST LOCAL_PAGE_MAX_LIMIT Largest limit an app may name for one conversation list, message list or reaction page. MAX_APPLICATION_COMPONENT_NAME_BYTES Longest application component name, in UTF-8 bytes. MAX_ATTACHMENT_RETENTION_SECONDS Largest retention value an SDK integer can carry exactly. MAX_ATTACHMENT_UPLOAD_BYTES Largest attachment contentLength the content type can carry. MAX_CHAIN_CALLS_IN_FLIGHT The most chain calls one batch of smart contract wallet checks keeps in
flight, so a batch never starts every check before the first completes. MAX_CHAIN_CALLS_PER_PROVIDER The most calls one chain provider has in flight, across all requests. MAX_CONSECUTIVE_AUTH_FAILURES Maximum consecutive credential rejections and callback failures. MAX_DB_POOL_SIZE Max Size the Database Pool is allowed to grow to MAX_GROUP_SIZE MAX_GROUP_SYNC_RETRIES MAX_HANDLE_NAME_LEN The most characters a handle’s name part can hold. The handle grammar
applies it, and the backend refuses a handles.min_name_length above it. MAX_IDENTITY_UPDATE_ACTIONS Most actions one identity update may carry. Validators reject a larger
update when they decode it, before they verify any of its signatures, and
clients refuse to build one. It is also the most installations a client
accepts as a deployment’s installation ceiling, so one update can revoke
every installation that ceiling allows. MAX_INSTALLATIONS_PER_INBOX MAX_INTENT_PUBLISH_ATTEMPTS MAX_IN_MEMORY_DECRYPT_BYTES Longest ciphertext, tag included, accepted by in-memory decryption, in bytes.
Equals the default download bound when attachment storage is not offered and
BACKEND_DEFAULT_MAX_UPLOAD_BYTES MAX_PAST_EPOCHS MAX_PUBLISHED_VALUE Largest published numeric value, 2^53 - 1. MAX_PUBLISH_ENVELOPES Most envelopes one publish request may carry, duplicates included (API
section 7). Clients chunk to it, and the backend refuses more. MAX_PUBLISH_IDENTITY_ACTIONS Most identity actions one publish request may carry across all its
identity updates: every identity update at the action limit. MAX_PUBLISH_IDENTITY_UPDATES Most identity updates one publish request may carry, duplicates included
(API section 7). Admission replays one stored log for each, one at a time. MAX_SCW_SIGNATURES_PER_REQUEST The most ERC-6492 signatures one verify request carries: two for each
action of the largest identity update, so no update needs more. The
backend refuses a larger max_scw_signatures, and a client sizes its
requests by the smaller of this and the published value. MAX_SCW_SIGNATURE_BYTES The longest ERC-6492 signature a validator verifies: the verifier’s
ceiling. MAX_SERVER_IDENTIFIER_BYTES Longest operator identifier, in bytes. Shared with the backend so one rule
governs what it accepts and what a client will store. MAX_SUBSCRIPTION_HMAC_KEYS Most HMAC keys one subscription may carry: the previous, current, and next epoch. MAX_TRANSPORT_BYTES Maximum bytes in one gRPC message, in either direction. The client’s
transport refuses a larger message, and the backend refuses a request or
response budget above it. MESSAGE_LIST_DEFAULT_LIMIT Messages returned by one messages() call that names no limit. MESSAGE_REACTION_LIMIT Reaction messages in a message’s reaction summary, and in one reaction page
that names no limit. MIN_DB_POOL_SIZE Minimum amount of connections to keep open & idle to the database in the pool MIN_RECOVERY_REQUEST_VERSION MUTABLE_METADATA_EXTENSION_ID MLS Extension Types NOTIFICATION_BATCH_HMAC_KEYS Most HMAC keys one notification request may carry across its adds. NOTIFICATION_BATCH_MAX_BYTES Largest complete UpdateSubscriptions protobuf, excluding the gRPC header.
Two 32-byte credentials, full adds with 33-byte topics, maximum nonnegative
epoch bases, include_commits, and 42-byte keys; includes all field wrappers. NOTIFICATION_BATCH_TOPICS Maximum total adds and removes in one notification request. NOTIFICATION_REQUEST_TIMEOUT Bound the complete notification operation, including auth and transport retries. OPENMLS_KV_TARGET Target for xmtp_db::sql_key_store instrumentation. Enable via openmls_kv=trace. PROPOSALS_MIN_PROTOCOL_VERSION The protocol floor written when a group or DM is created. RATE_LIMITED_DOMAIN The google.rpc.ErrorInfo domain on a rate-limit rejection (RATE-040). RATE_LIMITED_REASON The google.rpc.ErrorInfo reason on a rate-limit rejection (RATE-040). RECEIVER_FALLBACK_INTERVAL Maximum delay before a receiver with no progress falls back to Query. SENDER_RATCHET_MAX_FORWARD_DISTANCE Largest gap from a sender’s ratchet head accepted in the current epoch.
OpenMLS persists this configuration per group; changing it needs a migration. SENDER_RATCHET_OUT_OF_ORDER_TOLERANCE Number of earlier sender generations retained for out-of-order messages. SEND_MESSAGE_UPDATE_INSTALLATIONS_INTERVAL_NS STREAM_BARRIER_TIMEOUT Maximum duration of one bounded catch-up operation. STREAM_BATCH_BYTES Maximum encoded bytes in one admission transaction or fetched page. STREAM_BATCH_ROWS Maximum rows in one admission transaction or fetched page. STREAM_BLOCKED_WELCOME_RESCAN_INTERVAL How often a long-lived client rechecks Welcomes it could not process, so
their retention deadline is reached without restarting the client. STREAM_GROUP_BYTES Maximum pending group bytes across all group topics. STREAM_GROUP_ROWS Maximum pending group rows across all group topics. STREAM_IDENTITY_BYTES Reserved pending identity bytes. STREAM_IDENTITY_ROWS Reserved pending identity rows, separate from group and Welcome capacity. STREAM_LOCAL_READ_BYTES Maximum decoded bytes returned by one local message read. STREAM_LOCAL_READ_ROWS Maximum rows returned by one local message read. STREAM_PERMANENT_RETRY_INITIAL First delay before retrying a receiver that failed with a permanent error.
A permanent classification describes this response, not every later one, so
the retry never stops. It only slows down. STREAM_PERMANENT_RETRY_MAX Longest delay between retries of a receiver that keeps failing permanently. STREAM_TOPIC_BYTES Maximum pending encoded bytes for one topic. STREAM_TOPIC_ROWS Maximum pending rows for one topic. STREAM_UPDATE_PACING_MARGIN Extra refill delay for client Update pacing to absorb variation in arrival time. STREAM_WELCOME_BYTES Reserved pending Welcome bytes. STREAM_WELCOME_ROWS Reserved pending Welcome rows, separate from group and identity capacity. SUPER_ADMIN_METADATA_PREFIX SYNC_BACKOFF_TOTAL_WAIT_MAX_SECS the total wait for all attempts SYNC_BACKOFF_WAIT_MS the base backoff time that is multiplied by 3 SYNC_JITTER_MS jitter time between attempts in ms SYNC_UPDATE_INSTALLATIONS_INTERVAL_NS WASM_VFS_DIRECTORY VFS Directory for OPFS WASM_VFS_NAME WELCOME_HPKE_LABEL WELCOME_POINTEE_ENCRYPTION_AEAD_TYPES_EXTENSION_ID WELCOME_POINTEE_KEY_BYTES Length of a welcome pointer’s ChaCha20-Poly1305 pointee key. WELCOME_POINTEE_NONCE_BYTES Length of each of a welcome pointer’s two ChaCha20-Poly1305 nonces. WELCOME_RETENTION_NS How long after the backend’s timestamp on a Welcome the client keeps it
waiting for a welcome pointee or for its group’s message topic to reach the
join anchor. WELCOME_WRAPPER_CURVE25519_KEY_BYTES Length of a key package’s Curve25519 Welcome wrapper key. WELCOME_WRAPPER_ENCRYPTION_EXTENSION_ID WELCOME_WRAPPER_XWING_KEY_BYTES Length of a key package’s X-Wing (ML-KEM-768 draft 6) Welcome wrapper key. WELL_KNOWN_COMPONENT_NAMES Every well-known group metadata component, as its ID and its META
section 2 name, in ID order. WORKER_RESTART_DELAY Duration to wait before restarting workers in case of an error. ConfigProvider One immutable configuration, read by every consumer in section 6.4. backend_test_toxic_url Local backend proxy URL for fault tests. See backend_test_url backend_test_url Local backend URL for client tests. check_base_url Check the published base URL without replacing its raw host, port, or path. check_max_upload_bytes Check the effective upload limit after a missing wire value takes its default. check_retention_seconds Check a configured or published retention value. is_caip2_chain_id A CAIP-2 identifier is namespace:reference, where the namespace is three
to eight lowercase characters and the reference is one to thirty-two. The
client only needs the shape; the verifier owns the routes. parse_eip155_chain_id The chain id of an eip155 CAIP-2 identifier, whose reference must be the
chain id in canonical decimal form: no sign, no leading zero. validate_application_components Check each definition alone, then the catalogue for repeated IDs and
names. The error carries the position of the first failing definition. validate_server_identifier Check the shape of an operator identifier. The backend refuses to start
with one that fails, and a client refuses to store one. version_is_below Compare two versions on major, minor, and patch only. A prerelease tag
never makes a client too old for a minimum it otherwise satisfies.