let config = Config::new("thinclient.toml")?;
let client = ThinClient::new(config).await?;

// Listen for events
let mut event_rx = client.event_sink();
tokio::spawn(async move {
    while let Some(event) = event_rx.recv().await {
        // Process events
        println!("Event: {:?}", event);
    }
});

// ... do work ...

client.stop().await;

async def on_connection_status(event):
    print(f"Connected: {event.get('is_connected')}")

async def on_new_document(event):
    print("New PKI document received")

async def on_message_reply(event):
    print(f"Reply received")

config = Config("thinclient.toml")
config.on_connection_status = on_connection_status
config.on_new_pki_document = on_new_document
config.on_message_reply = on_message_reply

client = ThinClient(config)
loop = asyncio.get_running_loop()
await client.start(loop)

# ... do work ...

client.stop()

let doc = client.pki_document().await?;

// Get a random echo service
let desc = client.get_service("echo").await?;

// Use the destination for send_message
let (dest_node, dest_queue) = desc.to_destination();

doc = client.pki_document()
if doc is None:
    raise Exception("No PKI document available")

# Get a random echo service
desc = client.get_service("echo")

# Use the destination for send_message
dest_node, dest_queue = desc.to_destination()

package main

import (
    "encoding/hex"
    "fmt"
    "log"

    "github.com/katzenpost/hpqc/sign"
    "github.com/katzenpost/hpqc/sign/hybrid"

    "github.com/katzenpost/katzenpost/client/thin"
    "github.com/katzenpost/katzenpost/core/cert"
)

// AuthorityPublicKeysHex is the application's root of trust for the
// network's directory: the wire-format hybrid public keys of each
// authority, hex-encoded. They must be obtained out of band and
// never from the daemon. Replace these placeholders with your own.
var AuthorityPublicKeysHex = []string{
    "abab...", // auth1
    "cdcd...", // auth2
    "efef...", // auth3
}

// FetchAndVerifyPKI fetches the signed PKI document for the given
// epoch (pass 0 for "current") and verifies it against the
// authority public keys above using core/cert.VerifyThreshold.
func FetchAndVerifyPKI(client *thin.ThinClient, epoch uint64) ([]byte, error) {
    scheme := hybrid.FalconPadded512Ed25519
    verifiers := make([]sign.PublicKey, 0, len(AuthorityPublicKeysHex))
    for _, hexKey := range AuthorityPublicKeysHex {
        raw, err := hex.DecodeString(hexKey)
        if err != nil {
            return nil, fmt.Errorf("decoding authority key: %w", err)
        }
        pub, err := scheme.UnmarshalBinaryPublicKey(raw)
        if err != nil {
            return nil, fmt.Errorf("parsing authority key: %w", err)
        }
        verifiers = append(verifiers, pub)
    }

    payload, returnedEpoch, err := client.GetPKIDocumentRaw(epoch)
    if err != nil {
        return nil, fmt.Errorf("fetching signed PKI doc: %w", err)
    }

    threshold := len(verifiers)/2 + 1
    certified, good, _, err := cert.VerifyThreshold(verifiers, threshold, payload)
    if err != nil {
        return nil, fmt.Errorf(
            "threshold verification failed for epoch %d: %w",
            returnedEpoch, err,
        )
    }
    log.Printf("verified %d of %d authority signatures for epoch %d",
        len(good), len(verifiers), returnedEpoch)
    return certified, nil
}

let desc = client.get_service("echo").await?;
let (dest_node, dest_queue) = desc.to_destination();

let reply = client.blocking_send_message(
    b"hello mixnet",
    dest_node,
    dest_queue,
    std::time::Duration::from_secs(30),
).await?;
println!("Reply: {:?}", reply);

desc = client.get_service("echo")
dest_node, dest_queue = desc.to_destination()

reply = await client.blocking_send_message(
    b"hello mixnet", dest_node, dest_queue, timeout_seconds=30.0
)
print(f"Reply: {reply}")

let seed: [u8; 32] = rand::random();
let result = client.new_keypair(&seed).await?;

// Writer keeps: result.write_cap, result.first_index
// Share with reader out-of-band: result.read_cap, result.first_index

import os
seed = os.urandom(32)
result = await client.new_keypair(seed)

# Writer keeps: result.write_cap, result.first_index
# Share with reader out-of-band: result.read_cap, result.first_index

// Encrypt the message
let result = client.encrypt_write(
    b"hello", &write_cap, &current_index,
).await?;

// Send via ARQ (blocks until acknowledged)
client.start_resending_encrypted_message(
    None,                           // read_cap (None for writes)
    Some(&write_cap),
    None,                           // message_box_index
    None,                           // reply_index
    &result.envelope_descriptor,
    &result.message_ciphertext,
    &result.envelope_hash,
).await?;

// Advance the index for the next write
current_index = result.next_message_box_index;

# Encrypt the message
result = await client.encrypt_write(b"hello", write_cap, current_index)

# Send via ARQ (blocks until acknowledged)
await client.start_resending_encrypted_message(
    read_cap=None,
    write_cap=write_cap,
    next_message_index=None,
    reply_index=None,
    envelope_descriptor=result.envelope_descriptor,
    message_ciphertext=result.message_ciphertext,
    envelope_hash=result.envelope_hash,
)

# Advance the index for the next write
current_index = result.next_message_box_index

// Encrypt a read request
let read_result = client.encrypt_read(&read_cap, &current_index).await?;

// Send via ARQ (blocks until the message is retrieved)
let result = client.start_resending_encrypted_message(
    Some(&read_cap),
    None,                                    // write_cap (None for reads)
    None,                                    // message_box_index
    None,                                    // reply_index
    &read_result.envelope_descriptor,
    &read_result.message_ciphertext,
    &read_result.envelope_hash,
).await?;

let plaintext = result.plaintext;
// Advance the index for the next read
current_index = read_result.next_message_box_index;

# Encrypt a read request
read_result = await client.encrypt_read(read_cap, current_index)

# Send via ARQ (blocks until the message is retrieved)
plaintext = await client.start_resending_encrypted_message(
    read_cap=read_cap,
    write_cap=None,
    next_message_index=None,
    reply_index=None,
    envelope_descriptor=read_result.envelope_descriptor,
    message_ciphertext=read_result.message_ciphertext,
    envelope_hash=read_result.envelope_hash,
)

# Advance the index for the next read
current_index = read_result.next_message_box_index

let deadline = std::time::Instant::now()
    + std::time::Duration::from_secs(120);
let plaintext = loop {
    let read = client.encrypt_read(&read_cap, &current_index).await?;
    match client.start_resending_encrypted_message(
        Some(&read_cap), None, None, None,
        &read.envelope_descriptor,
        &read.message_ciphertext,
        &read.envelope_hash,
    ).await {
        Ok(result) => {
            current_index = read.next_message_box_index;
            break result.plaintext;
        }
        Err(e) if e.is_expected_outcome() => {
            if std::time::Instant::now() > deadline {
                return Err(e);
            }
            tokio::time::sleep(
                std::time::Duration::from_secs(3)).await;
        }
        Err(e) => return Err(e),
    }
};

import asyncio, time
from katzenpost_thinclient import is_expected_outcome

deadline = time.monotonic() + 120
while True:
    read = await client.encrypt_read(read_cap, current_index)
    try:
        plaintext = await client.start_resending_encrypted_message(
            read_cap=read_cap, write_cap=None,
            next_message_index=None, reply_index=None,
            envelope_descriptor=read.envelope_descriptor,
            message_ciphertext=read.message_ciphertext,
            envelope_hash=read.envelope_hash,
        )
        current_index = read.next_message_box_index
        break
    except Exception as exc:
        # "not written yet" is expected; anything else is a real error.
        if not is_expected_outcome(exc):
            raise
        if time.monotonic() > deadline:
            raise
        await asyncio.sleep(3)

// new_keypair already returns Vec<u8> for each artefact.
let kp = client.new_keypair(&seed).await?;
save_state(&kp.write_cap, &kp.read_cap, &kp.first_index);
let mut current_index = kp.first_index.clone();

// ... each time you advance, persist the new index bytes ...
save_index(&current_index);

// After a restart, the stored bytes are passed straight back into
// the API; no deserialisation step is required.
let (write_cap, read_cap, current_index) = load_state();

# new_keypair already returns bytes for each artefact.
kp = await client.new_keypair(seed)
save_state(kp.write_cap, kp.read_cap, kp.first_index)
current_index = kp.first_index

# ... each time you advance, persist the new index bytes ...
save_index(current_index)

# After a restart, the stored bytes are passed straight back into
# the API; no deserialisation step is required.
write_cap, read_cap, current_index = load_state()

// Alice's side. (Bob's is the mirror image.)
let alice = client.new_keypair(&alice_seed).await?;

// Exchange read caps out-of-band.
send_out_of_band(&alice.read_cap, &alice.first_index);
let (bob_read, mut bob_idx) = receive_out_of_band();
let mut alice_idx = alice.first_index.clone();

// Send on Alice's own stream.
let w = client.encrypt_write(b"hello Bob",
    &alice.write_cap, &alice_idx).await?;
client.start_resending_encrypted_message(
    None, Some(&alice.write_cap), None, None,
    &w.envelope_descriptor, &w.message_ciphertext,
    &w.envelope_hash).await?;
alice_idx = w.next_message_box_index; // persist this

// Receive on Bob's stream with the polling pattern, reading with
// bob_read and advancing bob_idx.

# Alice's side. (Bob's is the mirror image.)
alice = await client.new_keypair(alice_seed)

# Exchange read caps out-of-band.
send_out_of_band(alice.read_cap, alice.first_index)
bob_read, bob_idx = receive_out_of_band()
alice_idx = alice.first_index

# Send on Alice's own stream.
w = await client.encrypt_write(b"hello Bob",
    alice.write_cap, alice_idx)
await client.start_resending_encrypted_message(
    read_cap=None, write_cap=alice.write_cap,
    next_message_index=None, reply_index=None,
    envelope_descriptor=w.envelope_descriptor,
    message_ciphertext=w.message_ciphertext,
    envelope_hash=w.envelope_hash)
alice_idx = w.next_message_box_index  # persist this

# Receive on Bob's stream with the polling pattern, reading with
# bob_read and advancing bob_idx.

// Offline: pure local crypto, works regardless.
let w = client.encrypt_write(
    b"written while offline", &write_cap, &current_index).await?;
enqueue(&w); // persist for later

// Later, only transmit once connected.
if client.is_connected() {
    for e in drain_queue() {
        client.start_resending_encrypted_message(
            None, Some(&write_cap), None, None,
            &e.envelope_descriptor, &e.message_ciphertext,
            &e.envelope_hash).await?;
    }
}

# Offline: pure local crypto, works regardless.
w = await client.encrypt_write(
    b"written while offline", write_cap, current_index)
enqueue(w)  # persist for later

# Later, only transmit once connected.
if client.is_connected():
    for e in drain_queue():
        await client.start_resending_encrypted_message(
            read_cap=None, write_cap=write_cap,
            next_message_index=None, reply_index=None,
            envelope_descriptor=e.envelope_descriptor,
            message_ciphertext=e.message_ciphertext,
            envelope_hash=e.envelope_hash)

use katzenpost_thin_client::{Config, ThinClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::new("thinclient.toml")?;
    let client = ThinClient::new(config).await?;

    // Alice creates a stream.
    let seed: [u8; 32] = rand::random();
    let kp = client.new_keypair(&seed).await?;

    // Alice writes one message.
    let w = client.encrypt_write(
        b"hello from Alice", &kp.write_cap, &kp.first_index).await?;
    client.start_resending_encrypted_message(
        None, Some(&kp.write_cap), None, None,
        &w.envelope_descriptor, &w.message_ciphertext,
        &w.envelope_hash).await?;

    // Bob reads it back (read_cap would normally be shared out-of-band).
    let r = client.encrypt_read(&kp.read_cap, &kp.first_index).await?;
    let result = client.start_resending_encrypted_message(
        Some(&kp.read_cap), None, None, None,
        &r.envelope_descriptor, &r.message_ciphertext,
        &r.envelope_hash).await?;
    println!("Bob read: {:?}", result.plaintext);

    client.stop().await;
    Ok(())
}

import asyncio, os
from katzenpost_thinclient import ThinClient, Config

async def main():
    config = Config("thinclient.toml")
    client = ThinClient(config)
    await client.start(asyncio.get_running_loop())

    # Alice creates a stream.
    seed = os.urandom(32)
    kp = await client.new_keypair(seed)

    # Alice writes one message.
    w = await client.encrypt_write(
        b"hello from Alice", kp.write_cap, kp.first_index)
    await client.start_resending_encrypted_message(
        read_cap=None, write_cap=kp.write_cap,
        next_message_index=None, reply_index=None,
        envelope_descriptor=w.envelope_descriptor,
        message_ciphertext=w.message_ciphertext,
        envelope_hash=w.envelope_hash)

    # Bob reads it back (read_cap would normally be shared out-of-band).
    r = await client.encrypt_read(kp.read_cap, kp.first_index)
    plaintext = await client.start_resending_encrypted_message(
        read_cap=kp.read_cap, write_cap=None,
        next_message_index=None, reply_index=None,
        envelope_descriptor=r.envelope_descriptor,
        message_ciphertext=r.message_ciphertext,
        envelope_hash=r.envelope_hash)
    print("Bob read:", plaintext)

    client.stop()

asyncio.run(main())

// Create tombstone envelopes for 5 boxes
let result = client.tombstone_range(&write_cap, &start_index, 5).await;

// Send each tombstone
for envelope in &result.envelopes {
    client.start_resending_encrypted_message(
        None,
        Some(&write_cap),
        None,
        None,
        &envelope.envelope_descriptor,
        &envelope.message_ciphertext,
        &envelope.envelope_hash,
    ).await?;
}
// result.next is the index after the last tombstoned box

# Create tombstone envelopes for 5 boxes
result = await client.tombstone_range(write_cap, start_index, 5)

# Send each tombstone
for envelope in result.envelopes:
    await client.start_resending_encrypted_message(
        read_cap=None,
        write_cap=write_cap,
        next_message_index=None,
        reply_index=None,
        envelope_descriptor=envelope.envelope_descriptor,
        message_ciphertext=envelope.message_ciphertext,
        envelope_hash=envelope.envelope_hash,
    )
# result.next is the index after the last tombstoned box

// Create destination channel
let dest_seed: [u8; 32] = rand::random();
let dest = client.new_keypair(&dest_seed).await?;

// Create temporary channel
let temp_seed: [u8; 32] = rand::random();
let temp = client.new_keypair(&temp_seed).await?;

// Pack payload into copy stream elements
let envelopes_result = client.create_courier_envelopes_from_payload(
    &payload, &dest.write_cap, &dest.first_index,
    true,  // is_start
    true,  // is_last
).await?;

// Write each element to the temporary channel
let mut temp_index = temp.first_index.clone();
for chunk in &envelopes_result.envelopes {
    let write_result = client.encrypt_write(
        chunk, &temp.write_cap, &temp_index,
    ).await?;
    client.start_resending_encrypted_message(
        None, Some(&temp.write_cap), None, None,
        &write_result.envelope_descriptor,
        &write_result.message_ciphertext,
        &write_result.envelope_hash,
    ).await?;
    temp_index = write_result.next_message_box_index;
}

// Send the copy command (blocks until courier acknowledges)
client.start_resending_copy_command(&temp.write_cap, None, None).await?;

// Share dest.read_cap and dest.first_index with the reader

import os

# Create destination channel
dest_seed = os.urandom(32)
dest = await client.new_keypair(dest_seed)

# Create temporary channel
temp_seed = os.urandom(32)
temp = await client.new_keypair(temp_seed)

# Pack payload into copy stream elements
envelopes_result = await client.create_courier_envelopes_from_payload(
    payload, dest.write_cap, dest.first_index,
    is_start=True,
    is_last=True,
)

# Write each element to the temporary channel
temp_index = temp.first_index
for chunk in envelopes_result.envelopes:
    write_result = await client.encrypt_write(chunk, temp.write_cap, temp_index)
    await client.start_resending_encrypted_message(
        read_cap=None, write_cap=temp.write_cap,
        next_message_index=None, reply_index=None,
        envelope_descriptor=write_result.envelope_descriptor,
        message_ciphertext=write_result.message_ciphertext,
        envelope_hash=write_result.envelope_hash,
    )
    temp_index = write_result.next_message_box_index

# Send the copy command (blocks until courier acknowledges)
await client.start_resending_copy_command(temp.write_cap)

# Share dest.read_cap and dest.first_index with the reader

// Create destination channels
let dest1 = client.new_keypair(&seed1).await?;
let dest2 = client.new_keypair(&seed2).await?;

// Create temporary channel
let temp = client.new_keypair(&temp_seed).await?;

// Pack multiple payloads
let destinations = vec![
    (&payload1[..], &dest1.write_cap[..], &dest1.first_index[..]),
    (&payload2[..], &dest2.write_cap[..], &dest2.first_index[..]),
];

let result = client.create_courier_envelopes_from_multi_payload(
    destinations,
    true,  // is_start
    true,  // is_last
    None,  // buffer (None for first call)
).await?;

// Write envelopes to temporary channel
let mut temp_index = temp.first_index.clone();
for chunk in &result.envelopes {
    let write_result = client.encrypt_write(
        chunk, &temp.write_cap, &temp_index,
    ).await?;
    client.start_resending_encrypted_message(
        None, Some(&temp.write_cap), None, None,
        &write_result.envelope_descriptor,
        &write_result.message_ciphertext,
        &write_result.envelope_hash,
    ).await?;
    temp_index = write_result.next_message_box_index;
}

// Send copy command
client.start_resending_copy_command(&temp.write_cap, None, None).await?;