Crate softchat

Expand description

Portable Softchat protocol values and cryptographic operations.

The native API uses validated values and retained capabilities. Callers construct protocol data explicitly: signing does not read a hidden clock or normalize exact Nostr tag arrays.

§Protocol workflow

use softchat::{
    LocalIdentity, NostrEventDraft, NostrEventKind, NostrTag,
    SignedNostrEvent,
};

let alice = LocalIdentity::from_secret_hex(
    "5c0c523f52a5b6fad39ed2403092df8cebc36318b39383bca6c00808626fab3a",
)?;
let bob = LocalIdentity::from_secret_hex(
    "4b22aa260e4acb7021e32f38a6cdf4b673c6a277755bfce287e370c924dc936d",
)?;

let encrypted = alice.encrypt_utf8(&bob.public_key(), "hello")?;
assert_eq!(bob.decrypt_utf8(&encrypted)?, "hello");

let recipient = NostrTag::new(vec![
    "p".to_owned(),
    bob.public_key().to_hex(),
    String::new(),
    String::new(),
])?;
let draft = NostrEventDraft::new(
    1_700_000_000,
    NostrEventKind::SHORT_TEXT_NOTE,
    vec![recipient],
    "A signed protocol event",
)?;
let authored = alice.sign_event(draft)?;
let received = SignedNostrEvent::from_json(&authored.to_json()?)?;
assert_eq!(received, authored);

The keys above are fixtures. Never use them outside tests or examples. Network transport, attachment files, and application lifecycle remain platform-owned. With sqlite-storage, Rust also owns the Android account schema, transactions, authenticated truth, delivery recovery, and bounded use-case queries; Android supplies only an app-private path and lifecycle.

Structs§

AccountDatabase: One account-scoped SQLite owner.
AccountDatabaseInfo: Static database information returned after opening one account.
AccountDiagnostics: Redacted bounded account health information for support and recovery UI.
AccountDraft: One portable draft stored with its conversation.
AccountEngine: Stateless semantic account planner.
AccountEventNode: One use-case node derived from authenticated protocol truth.
AccountMediaItem: One attachment projected into an account media gallery.
AccountMediaLease: Exclusive bounded lease for one platform-owned media transfer.
AccountMediaOperation: One durable logical media operation.
AccountMediaOperationPage: One stable page of non-terminal media operations for a platform executor.
AccountMessage: One bounded message view derived without replacing protocol truth.
AccountMessageView: Complete effective message consumed by product UI.
AccountMutationResult: Generic result for a transaction that changed account state.
AccountOperationResult: Result of an idempotent outgoing operation transaction.
AccountProfile: Effective authenticated or explicitly local profile.
AccountProjection: One authenticated projection with exact protocol truth attached.
AccountReadState: Effective cross-device read state for one conversation.
AccountSettings: Versioned platform-neutral account settings.
AccountSettingsMutation: Result of a committed settings patch.
AccountTransportAction: One correlated, bounded platform action.
AccountTransportBatch: Complete result of one correlated state-machine transition.
AccountTransportResult: Correlated result returned by the Android system executor.
AccountTypingIndicator: One authenticated non-durable typing indicator retained until expiry.
AppDataSyncView: Authenticated and self-decrypted Softchat kind-30079 data.
ApplicationDataView: Generic direct NIP-78 application data.
AttachmentDecryptionStream: Incremental authenticated decryption for a private staged destination.
AttachmentEncryptionStream: Incremental encryption compatible with released clients’ combined nonce12 || ciphertext || tag16 attachment format.
AttachmentMetadata: Parsed canonical Softchat imeta metadata.
AttachmentStreamFinal: Final authentication and hash values for one staged attachment transform.
BatchAcknowledgement: One terminal relay result for a submitted event.
BatchProgress: Deterministic per-event batch progress in original submission order.
BuildFingerprint: Stable build metadata safe to include in logs and crash reports.
ChatMessageDraft: Canonical complete kind-14 message writer input.
ChatMessageView: Flat complete kind-14 message view.
ChatRelationInput: Flat relation input for generated native bindings.
ClaimedDelivery: One committed delivery lease and the exact bytes Android may send.
Contact: One canonical contact-backup entry.
ConversationCursor: Stable conversation-list paging cursor.
ConversationPage: One bounded page of complete conversations.
ConversationRecord: Complete conversation state consumed by product UI.
ConversationSummary: Bounded conversation list item derived from authenticated projections.
ConversationView: One complete conversation-list use case returned in a single native call.
CustomEmojiReference: Versioned platform-neutral account settings.
DeletionView: Typed NIP-09 deletion view.
DeliveryClaim: One bounded exclusive delivery lease.
DeliveryDecision: Stable host-facing delivery decision.
DeliveryIntentSnapshot: Store snapshot used by the pure delivery reducer.
DeliveryPayload: Exact payload attached to one claimed relay-delivery intent.
DeliveryReducer: Stateless durable-delivery reducer.
DeliveryStateMutation: State mutation returned for an atomic platform transaction.
DiagnosticsSnapshot: Monotonic process-local counters containing no protocol values.
DnsRelayRecord: One authenticated DNS URI record supplied by the Android system adapter.
DraftSpan: One bounded half-open UTF-16 range in a portable draft.
EditView: Typed Softchat kind-1010 edit view.
FollowListView: Typed private kind-3 contact backup.
GenericRepostView: Validated receive-only NIP-18 generic repost.
HttpAuthorizationPlan: Immutable NIP-98 authorization result for platform HTTP adapters.
IngestionBatch: One bounded atomic ingestion request to a platform-owned store.
IngestionReceipt: Platform result for one complete incoming transaction.
IngestionResult: Result returned by an authoritative Room, GRDB, IndexedDB, or host adapter.
LinkPreviewRecord: One cached HTTP link-preview result.
LocalContactRecord: One Android-local address-book entry.
LocalIdentity: A locally held secret-key capability.
ManagedAccountTransport: SDK-owned WSS/Noise executor for one crate::SoftchatAccount.
ManagedTransportSnapshot: Complete observable state of one SDK-owned account transport.
MediaCompletionResult: Result of acknowledging one completed attachment lease.
MediaPreparationInput: One platform source selected for an attachment-dependent message.
MessageContentInput: Complete user-authored message input.
MessageCursor: Stable newest-first message paging cursor.
MessageLocalExtras: Sparse account-local non-protocol data attached to one message.
MessagePage: One bounded page of messages.
MessageProjection: Pure text/deletion projection over one original and its event history.
MessageReactionInput: User-selected reaction input.
MessageReactionView: One effective reaction attached to a message.
NegentropyClient: Serialized, bounded Negentropy initiator.
NegentropyItem: One event timestamp/ID pair in a local reconciliation set.
NegentropyStep: Result of one stateful client reconciliation step.
Nip17TextMessage: A validated one-to-one kind-14 text-message rumor.
Nip19Identifier: A bounded, parsed NIP-19 value.
Nip19Tlv: One unknown NIP-19 TLV retained for forward-compatible re-encoding.
Nip44EncryptedMessage: A typed native-Rust NIP-44 v2 message.
Nip44Payload: One bounded, encoded NIP-44 v2 payload.
Nip59EnvelopeRoute: Verified outer-envelope routing metadata that does not expose plaintext.
NoiseClientHandshake: Single-use client handshake capability.
NoiseTransport: Established, serialized Noise transport capability.
NostrEventDraft: An explicit, validated NIP-01 event body waiting for a signature.
NostrEventId: A validated canonical lowercase hexadecimal Nostr event ID.
NostrEventKind: A NIP-01 event kind in the inclusive 0...65535 range.
NostrEventSignature: A validated canonical lowercase BIP-340 Schnorr signature.
NostrPublicKey: A validated lowercase hexadecimal Nostr public key.
NostrRumor: One unsigned NIP-59 rumor with a verified canonical event ID.
NostrTag: One exact, non-empty NIP-01 tag array.
OperationSnapshot: Aggregate operation state derived entirely from durable intent rows.
OutboundRelayFrame: One ordered text frame removed from the session’s bounded outbound queue.
PendingAssetReplacement: One durable public asset replacement and its platform upload dependency.
PendingMediaMessage: Durable message intent with its ordered logical attachment operations.
PreparedEventCopy: One independently randomized NIP-59 recipient copy.
PreparedIncomingBatch: One bounded atomic ingestion request for a platform-native database.
PreparedIncomingEvent: One fully authenticated event and its optional inner rumor.
PreparedOutgoingOperation: One outgoing operation that must be persisted before any socket write.
PreparedRelayIntent: One durable event-copy/relay delivery intent.
ProductOperationResult: High-level command result with the complete effective message when relevant.
ProjectionMutation: One normalized immutable projection mutation.
ReactionDraft: Canonical private-reaction writer input.
ReactionView: Typed NIP-25 reaction view.
RelayCatalogEntry: Complete platform-persisted relay catalog row.
RelayCatalogMutation: Persisted relay catalog mutation.
RelayCatalogPlan: Deterministic full-state catalog replacement.
RelayCatalogReducer: Stateless relay catalog reducer.
RelayDeliveryResult: Stable redacted relay result.
RelayEndpointPlan: Validated system-transport plan for one configured relay URL.
RelayFailoverMutation: Result of atomically selecting a failover relay and rebinding unfinished work.
RelayFilter: A strict NIP-01 filter that retains generic #<tag> constraints.
RelayRetryPlan: Bounded retry plan; the host chooses jitter inside the declared range.
RelaySession: One deterministic transport-independent relay session.
RelaySessionAction: One transport/platform action emitted by RelaySession.
RelaySessionSnapshot: Serializable non-secret session state for diagnostics only.
SignedNostrEvent: One structurally and cryptographically validated NIP-01 event.
SoftchatAccount: Android-facing owner of one identity and one Rust-managed account database.
StickerRecord: One cached custom emoji or sticker descriptor.
StoredEventJson: Exact stored event payload selected by an authenticated ID.
StoredIngestion: Result of one atomic authenticated ingestion.
StoredRelayCatalogPlan: Persisted authenticated relay-discovery reconciliation.
SubjectDraft: Canonical group-subject writer input.
SubjectView: Typed group-subject view.
SyncAction: One transport/database action with fields selected by SyncActionKind.
SyncEngine: Serialized synchronization state machine.
SyncEngineSnapshot: Redacted serializable synchronization state.
TypingView: Typed ephemeral typing view.
UnwrappedNip59Envelope: A rumor exposed only after every NIP-59 layer has authenticated.
UserMetadataView: Typed private user metadata with retained unknown JSON.

Enums§

AccountMediaOperationState: Logical media-operation state.
AccountMediaProtection: Confidentiality policy for one platform-executed media transfer.
AccountTransportActionKind: One system effect Android executes for the active account transport.
AccountTransportResultKind: Typed outcome of exactly one transport action.
AppDataContext: Accepted Softchat kind-30079 contexts.
AssetReplacementTarget: Public asset changed after one durable upload dependency completes.
BatchEventState: Terminal state for one event in a batch projection.
ChatRelation: One validated message relation.
ChatRelationKind: Relation semantics exposed by a kind-14 message view.
ClientRelayFrame: A validated client-to-relay frame.
DeliveryIntentState: Durable delivery-intent state.
DeliveryState: Durable delivery state for one authored event.
DraftSpanKind: Portable semantic span kind for one draft.
ManagedTransportFailure: Stable redacted reason for the most recent managed-transport failure.
Nip19IdentifierKind: Supported NIP-19 identifier family.
Nip59EnvelopeKind: The relay-storage behavior requested for one NIP-59 wrapper.
OperationState: User-visible aggregate operation state.
PendingAssetReplacementState: Logical state of one upload-dependent public asset replacement.
PendingMediaMessageState: Logical state of one attachment-dependent outgoing message.
ProjectionKind: Semantic projection family selected after authentication.
PushPlatform: Supported released push-registration wire profiles.
RelayCatalogSource: Consumer-visible source of one relay.
RelayConnectionState: Transport-independent relay connection state.
RelayDeliveryResultKind: Relay result class accepted by the delivery reducer.
RelayFailureKind: Transport failure class consumed by the Rust retry policy.
RelayResponseFrame: A validated relay-to-client frame.
RelayRetryAction: Retry/failover action selected by Rust.
RelaySessionActionKind: Action kind emitted by the pure session.
SoftchatError: Stable, redacted failures exposed by Softchat.
SyncActionKind: Action emitted by the host-driven synchronization coordinator.
SyncPhase: Durable synchronization phase.

Constants§

ACCOUNT_READ_STATE_SCHEMA_VERSION: Current portable read-state schema.
ACCOUNT_SETTINGS_SCHEMA_VERSION: Current portable settings schema.
DEFAULT_FALLBACK_RELAY_TTL_SECONDS: Default refresh lifetime assigned to the compiled fallback.
MAX_ACCOUNT_INGESTION_BYTES: Maximum canonical event bytes prepared in one incoming transaction.
MAX_ACCOUNT_INGESTION_EVENTS: Maximum events prepared in one incoming transaction.
MAX_ACCOUNT_READ_STATE_BYTES: Maximum UTF-8 bytes in one complete read-state snapshot.
MAX_ACCOUNT_READ_STATE_ENTRIES: Maximum conversations retained in one cross-device read-state snapshot.
MAX_ACCOUNT_SETTINGS_BYTES: Maximum UTF-8 bytes in retained settings JSON.
MAX_APP_DATA_JSON_BYTES: Maximum decrypted application-data JSON accepted by the shared layer.
MAX_ATTACHMENT_COMPATIBILITY_BYTES: Maximum input for the whole-buffer released-client compatibility helper.
MAX_ATTACHMENT_FALLBACKS: Maximum number of fallback URLs in one canonical attachment.
MAX_ATTACHMENT_METADATA_FIELDS: Maximum number of fields after the leading imeta tag name.
MAX_ATTACHMENT_STREAM_BYTES: Maximum plaintext bytes processed by one staged streaming operation.
MAX_ATTACHMENT_STREAM_CHUNK_BYTES: Maximum bytes accepted by one cross-language streaming call.
MAX_CHAT_ATTACHMENTS: Maximum inline attachments on one canonical chat message.
MAX_CHAT_EMOJI_TAGS: Maximum custom emoji definitions on one event.
MAX_CHAT_EXTENSION_TAGS: Maximum typed extension tags accepted from a writer.
MAX_CHAT_PARTICIPANTS: Maximum participant count in one Softchat rumor.
MAX_CIPHERTEXT_BYTES: Compatibility name for the current encoded-payload reader limit.
MAX_CONTACTS: Maximum contacts in one private backup.
MAX_DELIVERY_CLAIM_BYTES: Maximum canonical payload bytes returned in one platform lease.
MAX_DELIVERY_CLAIM_INTENTS: Maximum delivery rows returned in one platform lease.
MAX_DNS_RELAY_RECORDS: Maximum authenticated DNS URI records accepted in one refresh.
MAX_HTTP_AUTHORIZATION_PAYLOAD_BYTES: Maximum request-body bytes hashed by the whole-buffer NIP-98 helper.
MAX_HTTP_AUTHORIZATION_URL_BYTES: Maximum normalized URL bytes accepted by one NIP-98 plan.
MAX_INFLIGHT_INGESTION: Maximum received events awaiting authoritative platform persistence.
MAX_NEGENTROPY_FRAME_BYTES: Largest Negentropy frame allowed inside the 512-KiB relay profile.
MAX_NEGENTROPY_ITEMS: Maximum items accepted by one portable reconciliation capability.
MAX_NIP19_IDENTIFIER_CHARS: Maximum accepted encoded identifier length.
MAX_NIP19_RELAYS: Maximum relay hints retained in one shareable identifier.
MAX_NIP44_BINARY_WRITER_PLAINTEXT_BYTES: Maximum arbitrary-byte plaintext emitted through the native Rust API.
MAX_NIP44_ENCODED_PAYLOAD_BYTES: Cheap encoded-payload bound applied before base64 decoding.
MAX_NIP44_READER_PLAINTEXT_BYTES: Maximum plaintext size accepted by the Softchat NIP-44 v2 reader.
MAX_NIP44_WRITER_PLAINTEXT_BYTES: Maximum plaintext size emitted by the Softchat NIP-44 v2 writer.
MAX_NIP59_TIMESTAMP_TWEAK_SECONDS: Maximum number of seconds subtracted independently from private timestamps.
MAX_NOISE_FRAME_CIPHERTEXT: Largest encrypted WebSocket frame.
MAX_NOISE_FRAME_PLAINTEXT: Largest plaintext that fits in one unchunked encrypted frame.
MAX_NOISE_MESSAGE_SIZE: Largest logical message accepted by the deployed chunking profile.
MAX_NOSTR_EVENT_JSON_BYTES: Maximum standalone NIP-01 event JSON accepted by the portable boundary.
MAX_OPERATION_DELIVERY_INTENTS: Maximum event/relay intents retained by one outgoing operation.
MAX_OPERATION_EVENT_COPIES: Maximum event copies retained by one outgoing operation.
MAX_OPERATION_RELAYS: Maximum relay destinations attached to one outgoing operation.
MAX_OUTBOUND_RELAY_FRAMES: Maximum queued outbound frames in one session.
MAX_PENDING_PUBLISHES: Maximum authored events retained for durable delivery intent.
MAX_PLAINTEXT_BYTES: Compatibility name for the native arbitrary-byte writer limit.
MAX_PORTABLE_TIMESTAMP_SECONDS: Largest Unix timestamp represented exactly by JavaScript number.
MAX_PRODUCT_ATTACHMENT_TAG_BYTES: Maximum compact JSON bytes reserved for one outgoing imeta tag.
MAX_PRODUCT_DRAFT_ATTACHMENTS: Maximum logical attachment preparation references in one draft.
MAX_PRODUCT_DRAFT_SPANS: Maximum portable rich-text spans in one draft.
MAX_PRODUCT_MEDIA_OPERATION_LOOKUPS: Maximum exact media operations resolved by one ordered lookup.
MAX_PRODUCT_MESSAGE_BYTES: Maximum UTF-8 bytes in a portable message draft.
MAX_PRODUCT_MESSAGE_LOOKUPS: Maximum exact messages resolved by one ordered product lookup.
MAX_PRODUCT_PROFILE_LOOKUPS: Maximum exact profiles resolved by one ordered product lookup.
MAX_PRODUCT_QUERY_PAGE: Maximum requested rows for one product query. Media gallery pages finish the last message’s attachment group and may return at most limit + MAX_CHAT_ATTACHMENTS - 1 items.
MAX_PRODUCT_SEARCH_BYTES: Maximum UTF-8 bytes in one search query.
MAX_PRODUCT_TRANSCRIPT_BYTES: Maximum UTF-8 bytes in one local transcript.
MAX_PRODUCT_WAVEFORM_SAMPLES: Maximum normalized waveform samples stored for one message.
MAX_RELAY_BATCH_EVENTS: Maximum number of events in the deployed EVENTS extension.
MAX_RELAY_CATALOG_ENTRIES: Maximum effective relay records retained for one account.
MAX_RELAY_FILTERS: Maximum number of filters in one query.
MAX_RELAY_FILTER_VALUES: Maximum values in one filter field or generic-tag constraint.
MAX_RELAY_FRAME_BYTES: Maximum accepted logical relay frame size.
MAX_RELAY_MESSAGE_CHARS: Maximum bounded diagnostic/challenge string accepted from a relay.
MAX_RELAY_RETRY_DELAY_MS: Maximum reconnect delay before host-selected jitter.
MAX_RELAY_RETRY_JITTER_MS: Host-selected retry jitter range is always zero through this value.
MAX_RELAY_SUBSCRIPTIONS: Maximum simultaneous subscription identifiers.
MAX_RELAY_TTL_SECONDS: Maximum DNS URI TTL accepted by the portable policy.
MAX_SUBSCRIPTION_ID_CHARS: NIP-01 maximum subscription identifier length in Unicode scalar values.
MIN_NEGENTROPY_FRAME_BYTES: Smallest accepted non-zero Negentropy frame limit.
NIP42_AUTH_WINDOW_SECONDS: Accepted NIP-42 authentication timestamp skew in seconds.
NIP44_V2_ALGORITHM: Algorithm identifier carried by encrypted-message binding values.
NOISE_PROTOCOL_NAME: Exact deployed Noise protocol name.
SYNC_BASE_PAGE_LIMIT: Default relay/local snapshot page size.
SYNC_EVENT_REQUEST_CHUNK: Maximum IDs in one ordinary NIP-01 fetch or resend request.
SYNC_MAX_PAGE_LIMIT: Maximum page expansion used to capture a complete timestamp cohort.

Functions§

build_fingerprint: Return stable build metadata.
classify_application_data: Validate a direct generic NIP-78 event.
classify_chat_message: Validate a binding-owned rumor as a complete kind-14 message.
classify_deletion: Validate a binding-owned rumor as a deletion request.
classify_delivery_acknowledgement: Classify one standard OK without trusting its human-readable message as identity.
classify_edit: Validate a binding-owned rumor as a kind-1010 edit.
classify_follow_list: Validate a binding-owned private contact-backup rumor.
classify_generic_repost: Validate a signed receive-only NIP-18 generic repost.
classify_reaction: Validate a binding-owned rumor as a reaction.
classify_subject: Validate a binding-owned rumor as a subject update.
classify_typing: Validate a binding-owned rumor as a typing event.
classify_user_metadata: Validate a binding-owned private user-metadata rumor.
conversation_id: Compute the released-Android conversation ID from complete participants.
create_nip98_authorization: Create an immutable, signed NIP-98 HTTP authorization plan.
create_nip98_authorization_for_payload_hash: Create a NIP-98 plan from a SHA-256 produced while streaming a request body.
decrypt_attachment_bytes: Authenticate and decrypt a bounded released-client attachment value.
diagnostics_snapshot: Read monotonic process-local counters using relaxed atomics.
encode_events_frame: Encode the deployed flat, non-empty EVENTS extension.
encrypt_attachment_bytes: Encrypt a bounded released-client-compatible attachment value.
latest_application_data: Select the deterministic latest addressable application-data event.
latest_user_metadata: Select the deterministic latest private metadata rumor.
parse_attachment_metadata: Parse one complete imeta tag at generated binding boundaries.
parse_client_relay_frame: Parse one bounded client-to-relay JSON frame.
parse_relay_endpoint: Validate one configured relay and split protocol from system transport data.
parse_relay_response_frame: Parse one bounded relay-to-client JSON frame.
plan_nip42_authentication: Create a signed NIP-42 authentication event for one challenge and relay.
plan_relay_retry: Select the exact retry/failover behavior for one failed attempt.
project_chat_message: Apply authorized edit and deletion history without owning persistence.
route_nip59_envelope: Verify a bounded gift-wrap event and extract its account-routing hint.
track_batch_acknowledgements: Project unordered and repeated OK results onto one submitted batch.
validate_ingestion_result: Verify that a platform transaction classified every requested event exactly once.
validate_nip42_authentication: Validate a NIP-42 authentication event against its exact connection context.
version: Return the Softchat semantic version compiled into this library.

Crate softchat

Crate softchat Copy item path

§Protocol workflow

Structs§

Enums§

Constants§

Functions§

Crate softchat