Rust, Python and Lean libraries that let an application send messages
and use Pigeonhole storage over a Katzenpost
mixnet, by talking to the local client daemon kpclientd.
This is for application developers. A thin client does no cryptography
and no networking of its own: it speaks a CBOR-framed protocol over a
local socket, and kpclientd does the rest, so you need a running
daemon. Go programs should use the reference thin client in
katzenpost/client/thin
instead. docs/overview.md explains thin clients and
Pigeonhole in more detail.
With kpclientd running and its thin client config in thinclient.toml
(Docker test network):
pip install katzenpost_thinclientimport asyncio
from katzenpost_thinclient import ThinClient, Config
async def main():
client = ThinClient(Config("thinclient.toml"))
await client.start(asyncio.get_running_loop())
print("PKI epoch", client.pki_document()["Epoch"])
client.stop()
asyncio.run(main())For Rust (cargo add katzenpost_thin_client) and Lean, see the
per-language READMEs below. The
how-to guide and
API reference
cover Pigeonhole streams and messaging.
src/: Rust cratekatzenpost_thin_client; README_rust.md.katzenpost_thinclient/: Python package; README_python.md.ThinClient/: Lean Lake packagethinclient; README_lean.md.tests/: Python and Rust tests, mostly integration tests against a daemon.scripts/gen-vectors/: writestestdata/vectors.jsonfrom the daemon's Go types.packaging/,debian/: Debian packages.
docs/layout.md lists every file.
Pre-1.0. The Python and Rust clients share one version (pyproject.toml,
Cargo.toml); the Lean client has its own (lakefile.toml).
All three speak to the kpclientd built from the Katzenpost commit pinned
as katzenpost_ref in the Makefile, which the integration
CI runs against. The test vectors in testdata/vectors.json are encoded by
the Go thin client's own types, at the Katzenpost version pinned in
scripts/gen-vectors/go.mod; the Rust, Python and Lean tests check against them, and
make test-lean checks that Lean-encoded requests decode in Go.
Build from source
lists the versions pinned across the stack.
make test runs the Python and Rust tests (Python needs uv; daemon
tests are skipped without one), make test-lean the Lean tests, and
make check-live builds kpclientd and runs a few tests against the
live namenlos mixnet (needs Go). Pull requests are welcome; maintainers
see RELEASING.md.
AGPL-3.0-only; see LICENSE.