Private messaging

Softchat private messages have two distinct layers:

1. a rumor carries the author, event kind, timestamp, exact tags, content, and deterministic ID without a signature; and
2. a NIP-59 seal and gift wrap authenticate and privately route that rumor to one recipient.

Never expose a rumor recovered from the network until unwrapGiftWrap authenticates the outer route, outer signature, ciphertext, seal signature, seal shape, rumor ID, and author binding.

Create a one-to-one message

Operation contractprivate.create-message

Create a minimal private kind-14 message rumor.

Inputs and exact bounds

• exactly one non-self recipient
• non-empty content with resulting canonical rumor at most 512 KiB
• explicit timestamp from 0 through 9,007,199,254,740,991

Output

A typed unsigned rumor.

Trust and authentication

Locally created rumor is authored but is not relay-publishable until wrapped.

Stable errors

nip17_message_creation_failed · handling and retry rules

Ownership, lifecycle, and execution rules

Ownership

Rust owns protocol semantics, Android account SQLite/use-case state, and optional native relay I/O; the host owns account lifecycle, HTTP/media/background effects, files, and UI.

Retry

Retry only host transport or explicitly retryable session work; validation and authentication failures are permanent for the same input.

Lifecycle

Language ownership is automatic; explicitly cancel or erase only at the operation-specific authority boundary.

Concurrency

Serialize mutable session capabilities; immutable values follow the language type system.

Cancellation

The host owns async cancellation; use cancel, shutdown, close, or erase only where exposed.

Exact public symbols

Rust

LocalIdentity::create_nip17_text_message

Android

SoftchatIdentity.createNip17TextMessage

Swift

SoftchatIdentity.createNip17TextMessage

TypeScript

SoftchatIdentity.createNip17TextMessage

The minimum NIP-17 helper creates kind 14 with exactly one canonical p tag. Group messages, replies, attachments, and extension tags use the richer chat event API.

The lower-level createRumor operation is available when the application has already assembled another accepted event draft:

Rust

Measured performancedescriptive host audit

Median

1.07 µs

p95

1.07 µs

Equivalent rate

938,000 calls/s

15-byte input · optimized Rust 1.97.0 on hosted Ubuntu 24.04 x86_64; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

Android

No accepted measurement

This operation was not present in the accepted benchmark corpus for this surface. No duration or calls-per-second estimate is inferred from another platform.

Audit scope and methodology.

Swift

Measured performancemacOS host audit, not iOS

Median

4.90 µs

p95

4.95 µs

Equivalent rate

204,000 calls/s

15-byte input · optimized SoftchatKit facade on hosted macOS 15 arm64, Swift 6.1.2; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

TypeScript

Measured performanceNode/Wasm audit, not browser

Median

48.0 µs

p95

82.3 µs

Equivalent rate

20,900 calls/s

15-byte input · authored package on hosted Ubuntu 24.04 x86_64, Node.js 22.23.1; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

Rust

let message = alice.create_nip17_text_message(
    &bob.public_key(),
    1_700_000_000,
    "hello Bob",
)?;

Android

val message = alice.createNip17TextMessage(
    recipient = bob.publicKey,
    createdAt = 1_700_000_000,
    content = "hello Bob",
)

The returned rumor is not ready for relay publication; wrap a distinct recipient copy and sender history copy first.

Swift

let message = try alice.createNip17TextMessage(
    for: bob.publicKey,
    createdAt: 1_700_000_000,
    content: "hello Bob"
)

TypeScript

const message = alice.createNip17TextMessage(
  bob.publicKey,
  1_700_000_000,
  "hello Bob",
);

Rust

Measured performancedescriptive host audit

Median

6.31 µs

p95

6.32 µs

Equivalent rate

159,000 calls/s

15-byte input · optimized Rust 1.97.0 on hosted Ubuntu 24.04 x86_64; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

Android

No accepted measurement

This operation was not present in the accepted benchmark corpus for this surface. No duration or calls-per-second estimate is inferred from another platform.

Audit scope and methodology.

Swift

Measured performancemacOS host audit, not iOS

Median

15.5 µs

p95

15.7 µs

Equivalent rate

64,600 calls/s

15-byte input · optimized SoftchatKit facade on hosted macOS 15 arm64, Swift 6.1.2; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

TypeScript

Measured performanceNode/Wasm audit, not browser

Median

113 µs

p95

119 µs

Equivalent rate

8,810 calls/s

15-byte input · authored package on hosted Ubuntu 24.04 x86_64, Node.js 22.23.1; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

Wrap recipient and sender copies

Operation contractprivate.wrap

Create an independent NIP-59 copy for one recipient.

Inputs and exact bounds

• exactly one recipient
• now from 0 through 9,007,199,254,740,991
• input rumor and each generated envelope at most 512 KiB

Output

A verified signed durable or ephemeral outer event.

Trust and authentication

Fresh seal and wrapper keys/timestamps are generated for every call.

Stable errors

nip59_envelope_creation_failed · handling and retry rules

Ownership, lifecycle, and execution rules

Ownership

Rust owns protocol semantics, Android account SQLite/use-case state, and optional native relay I/O; the host owns account lifecycle, HTTP/media/background effects, files, and UI.

Retry

Retry only host transport or explicitly retryable session work; validation and authentication failures are permanent for the same input.

Lifecycle

Language ownership is automatic; explicitly cancel or erase only at the operation-specific authority boundary.

Concurrency

Serialize mutable session capabilities; immutable values follow the language type system.

Cancellation

The host owns async cancellation; use cancel, shutdown, close, or erase only where exposed.

Exact public symbols

Rust

LocalIdentity::gift_wrap

Android

SoftchatIdentity.giftWrap

Swift

SoftchatIdentity.giftWrap

TypeScript

SoftchatIdentity.giftWrap

Call giftWrap separately for every recipient and for the author’s own recoverable history. Each call creates a fresh wrapper key, exactly one outer p tag, empty seal tags, and independently randomized seal/wrapper timestamps within the previous two days.

Rust

let recipient_copy = alice.gift_wrap(
    &bob.public_key(),
    message.rumor(),
    Nip59EnvelopeKind::Durable,
    now,
)?;
let sender_copy = alice.gift_wrap(
    &alice.public_key(),
    message.rumor(),
    Nip59EnvelopeKind::Durable,
    now,
)?;

Android

val recipientCopy = alice.giftWrap(
    bob.publicKey, message.rumor, Nip59EnvelopeKind.DURABLE, now
)
val senderCopy = alice.giftWrap(
    alice.publicKey, message.rumor, Nip59EnvelopeKind.DURABLE, now
)

Persist both publish intents before handing frames to a WebSocket. Durable kind 1059 is retryable and persistable; ephemeral kind 21059 is not durable history.

Swift

let recipientCopy = try alice.giftWrap(
    message.rumor, for: bob.publicKey, kind: .durable, now: now
)
let senderCopy = try alice.giftWrap(
    message.rumor, for: alice.publicKey, kind: .durable, now: now
)

TypeScript

const recipientCopy = alice.giftWrap(
  bob.publicKey, message.rumor, "durable", now,
);
const senderCopy = alice.giftWrap(
  alice.publicKey, message.rumor, "durable", now,
);

Rust

Measured performancedescriptive host audit

Median

237 µs

p95

238 µs

Equivalent rate

4,220 calls/s

15-byte input · optimized Rust 1.97.0 on hosted Ubuntu 24.04 x86_64; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

Android

Measured performanceone-device migration audit

Median

528 µs

p95

568 µs

Equivalent rate

1,890 calls/s

Allocations

499 / call

Old median

1.37 ms

Median vs old

-61.58%

Old p95

1.85 ms

p95 vs old

-69.23%

15-byte input · non-debuggable AndroidX Benchmark on Pixel 9 Pro Fold, API 37 userdebug, arm64; 3 independent runs (30 legacy-pair or 50 public-account measurements each)

Descriptive single-thread benchmark, 2026-08-04, revision bb3cfc8ddc51. Full audit and methodology.

Swift

Measured performancemacOS host audit, not iOS

Median

292 µs

p95

296 µs

Equivalent rate

3,420 calls/s

15-byte input · optimized SoftchatKit facade on hosted macOS 15 arm64, Swift 6.1.2; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

TypeScript

Measured performanceNode/Wasm audit, not browser

Median

3.20 ms

p95

3.50 ms

Equivalent rate

312 calls/s

15-byte input · authored package on hosted Ubuntu 24.04 x86_64, Node.js 22.23.1; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

Receive and classify

Operation contractprivate.unwrap

Authenticate all NIP-59 layers and classify the rumor.

Inputs and exact bounds

• one signed kind-1059 or kind-21059 event
• encoded event at most 512 KiB

Output

An authenticated rumor and envelope metadata.

Trust and authentication

No rumor content is trusted before complete outer, seal, route, and rumor authentication.

Stable errors

invalid_nip59_envelope, invalid_nip17_message · handling and retry rules

Ownership, lifecycle, and execution rules

Ownership

Rust owns protocol semantics, Android account SQLite/use-case state, and optional native relay I/O; the host owns account lifecycle, HTTP/media/background effects, files, and UI.

Retry

Retry only host transport or explicitly retryable session work; validation and authentication failures are permanent for the same input.

Lifecycle

Language ownership is automatic; explicitly cancel or erase only at the operation-specific authority boundary.

Concurrency

Serialize mutable session capabilities; immutable values follow the language type system.

Cancellation

The host owns async cancellation; use cancel, shutdown, close, or erase only where exposed.

Exact public symbols

Rust

LocalIdentity::unwrap_gift_wrapNip17TextMessage::from_rumor

Android

SoftchatIdentity.unwrapGiftWrapNip17TextMessage.fromRumor

Swift

SoftchatIdentity.unwrapGiftWrapNip17TextMessage.init(rumor:)

TypeScript

SoftchatIdentity.unwrapGiftWrapNip17TextMessage.fromRumor

Rust

let envelope = bob.unwrap_gift_wrap(&recipient_copy)?;
let received = Nip17TextMessage::from_rumor(envelope.into_rumor())?;
assert_eq!(received.content(), "hello Bob");

Android

val envelope = bob.unwrapGiftWrap(recipientCopy)
val received = Nip17TextMessage.fromRumor(envelope.rumor)
check(received.content == "hello Bob")

For production ingestion, pass the signed outer event to account.incoming.ingest(listOf(recipientCopy), receivedAt). Rust unwraps, authenticates, classifies, and commits exact truth plus projections in one SQLite transaction. Confirm relay ingestion only after that call succeeds.

Swift

let envelope = try bob.unwrapGiftWrap(recipientCopy)
let received = try Nip17TextMessage(rumor: envelope.rumor)
precondition(received.content == "hello Bob")

TypeScript

const envelope = bob.unwrapGiftWrap(recipientCopy);
const received = Nip17TextMessage.fromRumor(envelope.rumor);
console.assert(received.content === "hello Bob");

Rust

Measured performancedescriptive host audit

Median

112 µs

p95

113 µs

Equivalent rate

8,900 calls/s

15-byte input · optimized Rust 1.97.0 on hosted Ubuntu 24.04 x86_64; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

Android

Measured performanceone-device migration audit

Median

366 µs

p95

385 µs

Equivalent rate

2,730 calls/s

Allocations

358 / call

Old median

1.14 ms

Median vs old

-67.74%

Old p95

1.86 ms

p95 vs old

-79.31%

15-byte input · non-debuggable AndroidX Benchmark on Pixel 9 Pro Fold, API 37 userdebug, arm64; 3 independent runs (30 legacy-pair or 50 public-account measurements each)

Descriptive single-thread benchmark, 2026-08-04, revision bb3cfc8ddc51. Full audit and methodology.

Swift

Measured performancemacOS host audit, not iOS

Median

173 µs

p95

174 µs

Equivalent rate

5,770 calls/s

15-byte input · optimized SoftchatKit facade on hosted macOS 15 arm64, Swift 6.1.2; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

TypeScript

Measured performanceNode/Wasm audit, not browser

Median

2.18 ms

p95

2.25 ms

Equivalent rate

458 calls/s

15-byte input · authored package on hosted Ubuntu 24.04 x86_64, Node.js 22.23.1; 3 paired processes

Descriptive single-thread benchmark, 2026-07-26, revision 5e7c0c65e6e8. Full audit and methodology.

Durable and ephemeral envelopes

Wrapper	Event kind	Use	Persistence
Durable	1059	messages, account copies, durable changes	persist and retry under host policy
Ephemeral	21059	typing and other transient signals	do not persist as history

A wrong recipient, altered wrapper, altered seal, or mismatched rumor produces the same stable invalid-envelope failure. Do not reveal which layer failed.