Struct EncryptedLink 

pub struct EncryptedLink { /* private fields */ }

Handle to an established Encrypted Link with a counterparty.

Created by advance_handshake (via HandshakeProgress::Complete) after a successful Noise handshake. It wraps a transport-mode pubky_noise::PubkyNoiseEncryptor and should be closed with close_encrypted_link when no longer needed.

Session resumption

An established Encrypted Link can be snapshotted via snapshot or serialized via serialize, then restored with restore_encrypted_link or restore_encrypted_link_from_config.

Private Application Message stream

All private Paykit protocol messages on this link share one ordered stream. Use receive_private_application_messages for ordered intake. Callers or SDK layers that derive durable Event Message state should persist and route the returned messages before replacing a stored link snapshot whose read counter has advanced.

Automatic send retry

Send helpers retry transient homeserver write failures according to set_max_send_retries. Deterministic Noise state, counter, nonce, or encryption errors fail immediately.

Implementations

impl EncryptedLink

pub fn remote_static_public_key(&self) -> Option<&[u8]>

X25519 static key authenticated by the Noise transcript. The caller must bind this key to the expected identity, including after restore.

pub fn set_max_send_retries(&mut self, max: u32) -> &mut Self

Set the maximum number of automatic Private Application Message send_message retries before Paykit gives up and returns PaykitError::Transport.

Retryable homeserver write failures are retried. Deterministic Noise state, counter, nonce, or encryption errors fail immediately.

Default: DEFAULT_MAX_SEND_RETRIES (3).

pub fn snapshot(&self) -> Result<EncryptedLinkSnapshot>

Capture the current link state as a serializable snapshot.

The snapshot captures transport keys, counters, and counterparty identity. Take a new snapshot after receiving or sending messages when the caller wants the persisted read/write counters to catch up with local state.

Snapshot bytes include sensitive key material and must be stored as secrets. Do not log them or include them in telemetry.

pub fn serialize(&self) -> Result<Vec<u8>>

Serialize the current link state to bytes for persistence.

Convenience method equivalent to self.snapshot()?.serialize().

pub fn config(&self) -> &Arc<PubkyNoiseConfig>

Access the shared Noise configuration for this link.

Useful for passing to restore_encrypted_link_from_config when performing in-process session recovery without an app restart.

pub fn recipient(&self) -> &PublicKey

Access the counterparty public key for this Encrypted Link.

pub async fn send_private_application_message_json( &mut self, raw_json: &str, ) -> Result<()>

Send one raw JSON Private Application Message.

This is the low-level send counterpart to receive_private_application_messages. It validates the generic version, kind, and app_id envelope fields; it does not require a known Paykit kind or validate known Paykit message bodies. Use the typed serializers or SDK queue for protocol-managed Paykit messages.

Higher-level callers should persist the exact JSON before sending when retrying the same message matters.

Transient outbox write failures are retried up to the configured budget. If every attempt fails, the prepared packet is retained and blocks further sends, receives, and snapshots on this link until it is republished with retry_pending_send.

Do not restore an older snapshot to recover from a failed send: the failed write may still have reached the homeserver, and rolling back the sending nonce and slot would reuse the transport key and nonce for the next plaintext. Only the identical prepared packet may be republished; otherwise establish a fresh link.

pub async fn retry_pending_send(&mut self) -> Result<()>

Republish the prepared packet retained after a failed convenience send.

Until the identical packet is republished, sends, receives, and snapshots remain blocked. Never restore an older snapshot to retry with different plaintext: an ambiguous write may already have used that key and nonce. SDK callers using staged sends should instead publish their durably persisted ciphertext with publish_prepared_private_application_message.

pub fn prepare_private_application_message_json( &mut self, raw_json: &str, ) -> Result<PreparedPrivateApplicationMessageSend>

Prepare one raw JSON Private Application Message for durable handoff.

Persist the returned ciphertext and resulting snapshot atomically before calling acknowledge_persisted_private_send.

pub fn acknowledge_persisted_private_send( &mut self, prepared: PreparedPrivateApplicationMessageSend, ) -> Result<()>

Acknowledge that a prepared send and its resulting snapshot are durable.

pub async fn publish_prepared_private_application_message( &self, destination_path: &str, ciphertext: &[u8], ) -> Result<()>

Publish an exact prepared ciphertext, retrying without re-encryption.

This accepts values restored from durable SDK state after a crash. The destination must belong to this link’s local write stream.

pub async fn prepare_next_private_application_message( &mut self, ) -> Result<Option<PreparedPrivateApplicationMessageReceive>>

Fetch and prepare the next available inbound Private Application Message.

Persist the application result and returned snapshot atomically before calling acknowledge_persisted_private_receive.

pub fn acknowledge_persisted_private_receive( &mut self, prepared: PreparedPrivateApplicationMessageReceive, ) -> Result<()>

Acknowledge that a prepared receive and its application result are durable.

pub async fn receive_private_application_messages( &mut self, ) -> Result<Vec<PrivateApplicationMessage>>

Receive a bounded batch of available Private Application Messages in stream order.

The Noise read checkpoint advances past the returned messages. Callers that need crash-safe Event Message handling should persist returned messages before replacing a stored link snapshot. Call again to drain more than PRIVATE_APPLICATION_MESSAGE_RECEIVE_LIMIT available stream slots.