provance 0.1.0__py3-none-any.whl

provance/__init__.py

@@ -0,0 +1,103 @@
+"""PROVANCE for Python: tamper-evident audit ledgers.
+
+Write audit events into a hash chained, signed ledger, and verify ledgers written by any PROVANCE implementation
+(.NET, Java, Python). See docs/SPEC.md for the format.
+
+    from provance import AuditedPayload, ProvanceLedger, SqlLedgerStore
+
+    ledger = ProvanceLedger(ledger_id="orders-api-prod", secret_key=os.environ["PROVANCE_SECRET_KEY"],
+                            store=SqlLedgerStore.from_url("postgresql://app@db/audit"))
+    ledger.add_entry("ORDER_REFUNDED", AuditedPayload(actor_id="user-42", description="Refund issued"))
+    result = ledger.verify()
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .checkpoints import FileCheckpointSink, LedgerCheckpointSink, read_latest_checkpoint
+from .errors import (
+    LedgerConcurrencyError,
+    LedgerError,
+    LedgerOverloadedError,
+    LedgerStoreError,
+    LedgerUnavailableError,
+    PayloadError,
+)
+from .format import (
+    FORMAT_VERSION,
+    canonical_checkpoint,
+    canonical_envelope,
+    compute_checkpoint_digest,
+    compute_entry_hash,
+    derive_genesis_hash,
+    format_timestamp,
+    parse_timestamp,
+    sha256_hex,
+)
+from .ledger import ProvanceLedger
+from .models import AuditedPayload, LedgerCheckpoint, LedgerEntry
+from .options import ProvanceOptions, QueueFullBehavior
+from .payload import canonical_payload
+from .signing import HmacLedgerSigner, HmacVerifier, LedgerSigner, SignatureCheck, SignatureVerifier
+from .stores import (
+    InMemoryLedgerStore,
+    JsonLinesReader,
+    LedgerStore,
+    ListSource,
+    SqlLedgerReader,
+    SqlLedgerStore,
+    connect,
+    connection_factory,
+    write_json_lines,
+)
+from .verifier import LedgerTamperedError, LedgerVerifier, VerificationFailure, VerificationResult
+
+try:
+    __version__ = version("provance")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.0.0"
+
+__all__ = [
+    "FORMAT_VERSION",
+    "AuditedPayload",
+    "FileCheckpointSink",
+    "HmacLedgerSigner",
+    "HmacVerifier",
+    "InMemoryLedgerStore",
+    "JsonLinesReader",
+    "LedgerCheckpoint",
+    "LedgerCheckpointSink",
+    "LedgerConcurrencyError",
+    "LedgerEntry",
+    "LedgerError",
+    "LedgerOverloadedError",
+    "LedgerSigner",
+    "LedgerStore",
+    "LedgerStoreError",
+    "LedgerTamperedError",
+    "LedgerUnavailableError",
+    "LedgerVerifier",
+    "ListSource",
+    "PayloadError",
+    "ProvanceLedger",
+    "ProvanceOptions",
+    "QueueFullBehavior",
+    "SignatureCheck",
+    "SignatureVerifier",
+    "SqlLedgerReader",
+    "SqlLedgerStore",
+    "VerificationFailure",
+    "VerificationResult",
+    "canonical_checkpoint",
+    "canonical_envelope",
+    "canonical_payload",
+    "compute_checkpoint_digest",
+    "compute_entry_hash",
+    "connect",
+    "connection_factory",
+    "derive_genesis_hash",
+    "format_timestamp",
+    "parse_timestamp",
+    "read_latest_checkpoint",
+    "sha256_hex",
+    "write_json_lines",
+]

provance/_writer.py

@@ -0,0 +1,249 @@
+"""Background writer of one process. Same algorithm as the .NET and Java writers.
+
+Linearity across processes comes from the store: it rejects a sequence or id that already exists. On any failure
+the writer reloads the head from the store, acknowledges the entries that were in fact persisted (looked up by
+their fixed id) and reseals the others on top of the real head. Several application instances can therefore
+write to the same ledger.
+"""
+
+from __future__ import annotations
+
+import logging
+import queue
+import random
+import threading
+import time
+import uuid
+from concurrent.futures import Future
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Callable
+
+from .errors import LedgerConcurrencyError, LedgerOverloadedError, LedgerUnavailableError
+from .format import FORMAT_VERSION, MAX_SEQUENCE, compute_entry_hash, normalize_timestamp
+from .models import LedgerEntry
+from .options import ProvanceOptions, QueueFullBehavior
+from .signing import LedgerSigner
+from .stores import LedgerStore
+
+log = logging.getLogger("provance.writer")
+
+_POLL_SECONDS = 0.1
+
+
+@dataclass
+class PendingEntry:
+    """An entry prepared by a producer (payload canonicalized and hashed) waiting for the writer.
+
+    The id is fixed here so that the writer can recognize the entry in the store after an ambiguous failure.
+    """
+
+    event_type: str
+    payload_json: str
+    payload_hash: str
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    future: Future = field(default_factory=Future)
+
+    def succeed(self, entry: LedgerEntry) -> None:
+        if not self.future.done():
+            self.future.set_result(entry)
+
+    def fail(self, error: BaseException) -> None:
+        if not self.future.done():
+            self.future.set_exception(error)
+
+
+class _Aborted(Exception):
+    pass
+
+
+class LedgerWriter:
+    def __init__(self, store: LedgerStore, signer: LedgerSigner, options: ProvanceOptions,
+                 clock: Callable[[], datetime]):
+        self._queue: queue.Queue[PendingEntry] = queue.Queue(maxsize=options.queue_capacity)
+        self._store = store
+        self._signer = signer
+        self._options = options
+        self._clock = clock
+        self._genesis = options.effective_genesis_hash()
+        self._accepting = True
+        self._aborted = False
+        self._head: tuple[int, str] | None = None  # writer thread only
+        self.thread = threading.Thread(target=self._run, name=f"provance-writer-{options.ledger_id}", daemon=True)
+
+    def start(self) -> None:
+        self.thread.start()
+
+    def enqueue(self, entry: PendingEntry) -> None:
+        if not self._accepting:
+            raise _stopped()
+        if self._options.queue_full_behavior is QueueFullBehavior.FAIL_FAST:
+            try:
+                self._queue.put_nowait(entry)
+            except queue.Full:
+                raise (LedgerOverloadedError("PROVANCE queue is full.") if self._accepting else _stopped()) from None
+            return
+        while True:
+            try:
+                self._queue.put(entry, timeout=_POLL_SECONDS)
+                return
+            except queue.Full:
+                if not self._accepting:
+                    raise _stopped() from None
+
+    def stop_accepting(self) -> None:
+        self._accepting = False
+
+    def abort(self) -> None:
+        self._accepting = False
+        self._aborted = True
+
+    def fail_queued(self) -> None:
+        while True:
+            try:
+                self._queue.get_nowait().fail(LedgerUnavailableError("PROVANCE writer stopped before the entry was written."))
+            except queue.Empty:
+                return
+
+    def _run(self) -> None:
+        log.info("PROVANCE writer started for ledger %s.", self._options.ledger_id)
+        try:
+            while not self._aborted:
+                try:
+                    first = self._queue.get(timeout=_POLL_SECONDS)
+                except queue.Empty:
+                    if not self._accepting and self._queue.empty():
+                        break
+                    continue
+                batch = [first]
+                while len(batch) < self._options.max_batch_size:
+                    try:
+                        batch.append(self._queue.get_nowait())
+                    except queue.Empty:
+                        break
+                try:
+                    self._process(batch)
+                except _Aborted:
+                    for item in batch:
+                        item.fail(LedgerUnavailableError("PROVANCE writer stopped before the entry was written."))
+                    break
+                except Exception as e:  # never let the writer die
+                    log.exception("Unexpected error in the PROVANCE writer. The batch is failed and the writer continues.")
+                    self._head = None
+                    for item in batch:
+                        item.fail(LedgerUnavailableError(f"Unexpected PROVANCE writer error: {e}"))
+        finally:
+            self._accepting = False
+            self.fail_queued()
+            log.info("PROVANCE writer stopped for ledger %s.", self._options.ledger_id)
+
+    def _process(self, batch: list[PendingEntry]) -> None:
+        pending = list(batch)
+        transient_failures = conflicts = 0
+
+        while pending:
+            if self._aborted:
+                raise _Aborted()
+            sealed: list[LedgerEntry] | None = None
+            try:
+                head = self._head if self._head is not None else self._load_head()
+                sealed = self._seal(pending, head)
+                self._store.append(sealed)
+                for item, entry in zip(pending, sealed):
+                    item.succeed(entry)
+                self._head = (sealed[-1].sequence, sealed[-1].hash)
+                return
+            except LedgerConcurrencyError as e:
+                failure: Exception = e
+                is_conflict = True
+            except Exception as e:
+                failure = e
+                is_conflict = False
+
+            if self._aborted:
+                raise _Aborted()
+
+            # Whatever happened, our view of the head is no longer trustworthy.
+            self._head = None
+
+            if sealed is not None:
+                self._acknowledge_persisted(pending)
+                if not pending:
+                    return
+
+            if is_conflict:
+                conflicts += 1
+                if conflicts > self._options.max_conflict_retries:
+                    log.error("PROVANCE writer gave up after %d sequence conflicts.", conflicts)
+                    error = LedgerUnavailableError(f"Gave up after {conflicts} sequence conflicts with other writers.")
+                    error.__cause__ = failure
+                    for item in pending:
+                        item.fail(error)
+                    return
+                log.debug("Sequence conflict (another writer appended first). Resealing %d entries.", len(pending))
+                continue
+
+            transient_failures += 1
+            if transient_failures >= self._options.max_append_attempts:
+                log.error("PROVANCE append failed %d times; failing %d entries: %s", transient_failures, len(pending), failure)
+                error = LedgerUnavailableError(f"The ledger store failed {transient_failures} times: {failure}")
+                error.__cause__ = failure
+                for item in pending:
+                    item.fail(error)
+                return
+
+            delay = self._backoff(transient_failures)
+            log.warning("PROVANCE append failed (attempt %d/%d), retrying in %.0f ms: %s",
+                        transient_failures, self._options.max_append_attempts, delay * 1000, failure)
+            time.sleep(delay)
+
+    def _acknowledge_persisted(self, pending: list[PendingEntry]) -> None:
+        acknowledged = 0
+        try:
+            for item in pending:
+                stored = self._store.get_by_id(item.id)
+                if stored is None:
+                    break
+                item.succeed(stored)
+                acknowledged += 1
+        except Exception as e:
+            # If an entry was persisted after all, the next append reuses its id, the store reports a conflict and
+            # this method runs again.
+            log.warning("Could not check which entries were persisted after a failed append: %s", e)
+        if acknowledged:
+            log.info("%d entries were persisted despite the reported failure.", acknowledged)
+            del pending[:acknowledged]
+
+    def _load_head(self) -> tuple[int, str]:
+        head = self._store.get_head()
+        if head is None:
+            return 0, self._genesis
+        if head.ledger_id != self._options.ledger_id:
+            raise RuntimeError(f"The store contains ledger '{head.ledger_id}' but this application is configured for "
+                               f"'{self._options.ledger_id}'. Use one table per ledger.")
+        return head.sequence, head.hash
+
+    def _seal(self, pending: list[PendingEntry], head: tuple[int, str]) -> list[LedgerEntry]:
+        sequence, previous = head
+        timestamp = normalize_timestamp(self._clock())
+        key_id = self._signer.key_id
+        sealed = []
+        for item in pending:
+            sequence += 1
+            if sequence > MAX_SEQUENCE:
+                raise RuntimeError("The ledger reached the maximum sequence number.")
+            draft = LedgerEntry(FORMAT_VERSION, self._options.ledger_id, sequence, item.id, timestamp, item.event_type,
+                                item.payload_json, item.payload_hash, previous, key_id, "", "")
+            digest = compute_entry_hash(draft)
+            entry = draft.with_changes(hash=digest, signature=self._signer.sign(bytes.fromhex(digest)).hex())
+            sealed.append(entry)
+            previous = digest
+        return sealed
+
+    def _backoff(self, failures: int) -> float:
+        base = self._options.retry_base_delay.total_seconds() * 2 ** (failures - 1)
+        return min(base + base * 0.2 * random.random(), 2.0)
+
+
+def _stopped() -> LedgerUnavailableError:
+    return LedgerUnavailableError("PROVANCE ledger is closed; the entry was not queued.")

provance/checkpoints.py

@@ -0,0 +1,101 @@
+"""Checkpoint sinks and automatic publication.
+
+A checkpoint is only as trustworthy as the place it is stored: use storage the application cannot overwrite
+(object storage with a retention lock, WORM storage, a timestamping service, a system owned by another team).
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from datetime import timedelta
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable, Protocol, Sequence
+
+from .models import LedgerCheckpoint
+
+if TYPE_CHECKING:
+    from .ledger import ProvanceLedger
+
+log = logging.getLogger("provance.checkpoints")
+
+
+class LedgerCheckpointSink(Protocol):
+    """Destination of automatic checkpoints. Must not overwrite an existing checkpoint."""
+
+    def publish(self, checkpoint: LedgerCheckpoint) -> None: ...
+
+
+class FileCheckpointSink:
+    """Writes each checkpoint to ``{directory}/{ledger_id}/{sequence:016}.json`` and never overwrites a file.
+
+    Same layout as the .NET and Java file sinks. Useful when the directory is mounted from immutable storage.
+    """
+
+    def __init__(self, directory: str | Path):
+        self.directory = Path(directory)
+
+    def publish(self, checkpoint: LedgerCheckpoint) -> None:
+        folder = _folder(self.directory, checkpoint.ledger_id)
+        folder.mkdir(parents=True, exist_ok=True)
+        path = folder / f"{checkpoint.sequence:016d}.json"
+        try:
+            with open(path, "x", encoding="utf-8", newline="\n") as f:  # "x": fails if the file exists
+                f.write(checkpoint.to_json())
+        except FileExistsError:
+            pass  # same head already published, possibly by another instance
+
+
+def read_latest_checkpoint(directory: str | Path, ledger_id: str) -> LedgerCheckpoint | None:
+    """Reads the checkpoint with the highest sequence written by a file sink, or ``None``."""
+    folder = _folder(Path(directory), ledger_id)
+    files = [f for f in folder.glob("*.json") if f.stem.isdigit()] if folder.is_dir() else []
+    if not files:
+        return None
+    return LedgerCheckpoint.from_json(max(files, key=lambda f: int(f.stem)).read_text(encoding="utf-8"))
+
+
+def _folder(directory: Path, ledger_id: str) -> Path:
+    if not ledger_id or ledger_id in (".", "..") or "/" in ledger_id or "\\" in ledger_id:
+        raise ValueError(f"Ledger id '{ledger_id}' cannot be used as a folder name.")
+    return directory / ledger_id
+
+
+class CheckpointPublisher:
+    """Publishes a checkpoint of the head to every sink at the interval, when the head has moved."""
+
+    def __init__(self, create: Callable[[], LedgerCheckpoint | None], sinks: Sequence[LedgerCheckpointSink],
+                 interval: timedelta, name: str):
+        self._create = create
+        self._sinks = list(sinks)
+        self._interval = interval.total_seconds()
+        self._stop = threading.Event()
+        self._last_sequence = 0
+        self._lock = threading.Lock()
+        self._thread = threading.Thread(target=self._run, name=f"provance-checkpoints-{name}", daemon=True)
+
+    def start(self) -> None:
+        if self._sinks:
+            self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread.is_alive():
+            self._thread.join(timeout=5)
+
+    def publish_once(self) -> None:
+        with self._lock:
+            try:
+                checkpoint = self._create()
+                if checkpoint is None or checkpoint.sequence == self._last_sequence:
+                    return
+                for sink in self._sinks:
+                    sink.publish(checkpoint)
+                self._last_sequence = checkpoint.sequence
+                log.info("PROVANCE checkpoint published at sequence %d.", checkpoint.sequence)
+            except Exception:
+                log.exception("PROVANCE checkpoint publication failed; it will be retried at the next interval.")
+
+    def _run(self) -> None:
+        while not self._stop.wait(self._interval):
+            self.publish_once()

provance/cli.py

@@ -0,0 +1,172 @@
+"""Command line: ``provance verify`` and ``provance export``.
+
+Exit codes: 0 the ledger is valid, 1 verification failed, 2 usage or connection error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from . import __version__
+from .models import LedgerCheckpoint
+from .signing import HmacVerifier
+from .stores import DEFAULT_TABLE, JsonLinesReader, SqlLedgerReader, connect, write_json_lines
+from .verifier import LedgerVerifier
+
+DEFAULT_KEY_ENV = "PROVANCE_SECRET_KEY"
+
+
+class UsageError(Exception):
+    pass
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return 2
+    try:
+        return args.handler(args)
+    except (UsageError, ValueError, FileNotFoundError, RuntimeError) as e:
+        print(f"provance: {e}", file=sys.stderr)
+        return 2
+    except Exception as e:  # driver errors (connection refused, unknown table, ...)
+        print(f"provance: {type(e).__name__}: {e}", file=sys.stderr)
+        return 2
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="provance", description="Verify and export PROVANCE tamper-evident ledgers.")
+    p.add_argument("--version", action="version", version=f"provance {__version__}")
+    sub = p.add_subparsers(dest="command")
+
+    v = sub.add_parser("verify", help="verify a ledger from a database or a JSON Lines export",
+                       description="Verify the hash chain, signatures and, with --checkpoint, truncation and rewrites.")
+    _add_source(v)
+    v.add_argument("--ledger-id", required=True, help="ledger id configured in the application")
+    v.add_argument("--genesis-hash", help="only if the application configured an explicit genesis hash")
+    v.add_argument("--key-id", default="k1", help="id of the current HMAC key (default: k1)")
+    v.add_argument("--key-env", default=DEFAULT_KEY_ENV, metavar="VAR",
+                   help=f"environment variable holding the HMAC secret (default: {DEFAULT_KEY_ENV})")
+    v.add_argument("--key-file", metavar="PATH", help="file holding the HMAC secret, instead of --key-env")
+    v.add_argument("--retired-key", action="append", default=[], metavar="ID=VAR",
+                   help="retired key: key id and the environment variable holding its secret (repeatable)")
+    v.add_argument("--checkpoint", metavar="PATH",
+                   help="trusted checkpoint: a checkpoint JSON file, or a checkpoint directory (latest one is used)")
+    v.add_argument("--from-checkpoint", action="store_true", help="verify only from the checkpoint onward")
+    v.add_argument("--json", action="store_true", help="print the result as JSON")
+    v.set_defaults(handler=_verify)
+
+    e = sub.add_parser("export", help="export a ledger table to JSON Lines (for an offline audit)")
+    _add_db(e, required=True)
+    e.add_argument("--from", dest="from_sequence", type=int, default=1, metavar="SEQ", help="first sequence (default: 1)")
+    e.add_argument("-o", "--output", metavar="PATH", help="output file (default: standard output)")
+    e.set_defaults(handler=_export)
+    return p
+
+
+def _add_db(p: argparse.ArgumentParser, required: bool) -> None:
+    p.add_argument("--db", required=required, metavar="URL",
+                   help="database URL: sqlite:///audit.db, postgresql://user@host/db, mysql://..., mssql://...")
+    p.add_argument("--table", default=DEFAULT_TABLE, help=f"ledger table (default: {DEFAULT_TABLE})")
+    p.add_argument("--schema", help="schema of the ledger table")
+
+
+def _add_source(p: argparse.ArgumentParser) -> None:
+    _add_db(p, required=False)
+    p.add_argument("--file", metavar="PATH", help="JSON Lines export produced by 'provance export'")
+
+
+def _open_source(args: argparse.Namespace):
+    file = getattr(args, "file", None)
+    if bool(args.db) == bool(file):
+        raise UsageError("give exactly one of --db or --file")
+    if file:
+        return JsonLinesReader(file), None
+    connection, dialect = connect(args.db)
+    return SqlLedgerReader(connection, dialect, table=args.table, schema=args.schema), connection
+
+
+def _secret_from_env(var: str, what: str) -> str:
+    value = os.environ.get(var)
+    if not value:
+        raise UsageError(f"environment variable {var} is not set ({what})")
+    return value
+
+
+def _keys(args: argparse.Namespace) -> dict[str, str]:
+    if args.key_file:
+        secret = Path(args.key_file).read_text(encoding="utf-8").rstrip("\r\n")
+    else:
+        secret = _secret_from_env(args.key_env, f"secret of key '{args.key_id}'")
+    keys = {args.key_id: secret}
+    for spec in args.retired_key:
+        key_id, sep, var = spec.partition("=")
+        if not sep or not key_id or not var:
+            raise UsageError(f"--retired-key expects ID=ENV_VAR, got '{spec}'")
+        keys[key_id] = _secret_from_env(var, f"secret of retired key '{key_id}'")
+    return keys
+
+
+def _load_checkpoint(path_text: str | None, ledger_id: str) -> LedgerCheckpoint | None:
+    if not path_text:
+        return None
+    path = Path(path_text)
+    if path.is_dir():
+        folder = path / ledger_id if (path / ledger_id).is_dir() else path
+        files = [f for f in folder.glob("*.json") if f.stem.isdigit()]
+        if not files:
+            raise UsageError(f"no checkpoint file (NNNN.json) in {folder}")
+        path = max(files, key=lambda f: int(f.stem))
+    return LedgerCheckpoint.from_json(path.read_text(encoding="utf-8"))
+
+
+def _verify(args: argparse.Namespace) -> int:
+    if args.from_checkpoint and not args.checkpoint:
+        raise UsageError("--from-checkpoint needs --checkpoint")
+    keys = _keys(args)
+    checkpoint = _load_checkpoint(args.checkpoint, args.ledger_id)
+    source, connection = _open_source(args)
+    try:
+        verifier = LedgerVerifier(source, HmacVerifier(keys), args.ledger_id, args.genesis_hash)
+        result = verifier.verify(checkpoint=checkpoint, start_from_checkpoint=args.from_checkpoint)
+    finally:
+        if connection is not None:
+            connection.close()
+
+    if args.json:
+        print(json.dumps(result.to_dict(), indent=2))
+    else:
+        status = "OK" if result.valid else f"FAILED ({result.failure.value})"
+        print(f"{status}: {result.message}")
+        if checkpoint is not None and result.valid:
+            print(f"Checkpoint at sequence {checkpoint.sequence} matched.")
+        if result.redacted_payloads:
+            print(f"{result.redacted_payloads} payload(s) redacted.")
+        if result.valid and result.last_hash:
+            print(f"Head: sequence {result.last_sequence}, hash {result.last_hash}")
+    return 0 if result.valid else 1
+
+
+def _export(args: argparse.Namespace) -> int:
+    source, connection = _open_source(args)
+    try:
+        if args.output:
+            with open(args.output, "w", encoding="utf-8", newline="\n") as out:
+                count = write_json_lines(source.read(args.from_sequence), out)
+            print(f"{count} entries written to {args.output}", file=sys.stderr)
+        else:
+            write_json_lines(source.read(args.from_sequence), sys.stdout)
+    finally:
+        connection.close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

provance/errors.py

@@ -0,0 +1,33 @@
+"""Exceptions raised by the ledger, the writer and the stores."""
+
+from __future__ import annotations
+
+
+class LedgerError(Exception):
+    """Base class of PROVANCE errors."""
+
+
+class LedgerConcurrencyError(LedgerError):
+    """Raised by a store when an entry with the same sequence or id already exists.
+
+    The writer handles it by reloading the head; applications rarely see it.
+    """
+
+
+class LedgerStoreError(LedgerError):
+    """A store operation failed (database unavailable, timeout, ...). The writer retries appends that fail this way."""
+
+
+class LedgerUnavailableError(LedgerError):
+    """The entry could not be written: the ledger is closed, or the store kept failing after all retries.
+
+    When the cause is a store failure, the entry may or may not have been persisted.
+    """
+
+
+class LedgerOverloadedError(LedgerUnavailableError):
+    """The queue is full and ``queue_full_behavior`` is ``FAIL_FAST``. Map it to HTTP 503 or 429."""
+
+
+class PayloadError(ValueError):
+    """The payload cannot be serialized to canonical JSON."""