The tx-manifest Cookbook

A recipe-driven guide to writing transaction manifests — machine-readable JSON descriptions of multi-UTXO protocols on Bitcoin and Liquid, backed by SimplicityHL covenants.

📖 Read it online: https://stringhandler.github.io/tx_manifest_book/

This is an mdBook. It is a cookbook in the style of the Rust Cookbook: a sequence of small, self-contained recipes, each solving one concrete problem and introducing one or two new concepts, building toward a full peer-to-peer lending protocol.

⚠️ Work in progress. The getting-started chapters, the first recipes, and the appendix are complete; several later recipes (05–10) and the lending walkthrough are still stubs being filled in.

Format version: 0.2.0. Every example is written against manifest format 0.2.0, and manifest_version is enforced at parse time — a 0.1.x file is a hard error in a current wallet, not a warning.

Checking the examples

Every ```json block in src/ is validated against schema/txmanifest.schema.json, copied verbatim from the reference wallet (see schema/README.md for the exact ref):

python3 scripts/check_manifests.py            # check the book
python3 scripts/check_manifests.py --self-test path/to/wallet/examples

The checker needs no third-party packages. --self-test validates the checker itself against the wallet's own example manifests, and against deliberately corrupted copies of them, so a validator that accepted everything would fail. CI runs the check on every push and blocks the deploy if it fails.

A block is anchored to what it is meant to be with an HTML comment above the fence — <!-- schema: Action -->, <!-- schema: manifest --> for a slice of a document, <!-- schema: map:ParamDef --> for a named map, or <!-- schema: none --> for JSON that is not part of a manifest (a state file, a params file). The book's ... and … elisions are understood.

The field reference is generated

src/appendix/manifest-reference.md is generated from the same schema — every type, field, default and description. Don't edit it by hand:

python3 scripts/gen_reference.py           # rewrite it from the schema
python3 scripts/gen_reference.py --check   # fail if it is stale (CI runs this)

So updating the book for a new format revision is: drop in the new schema, bump the ref in schema/README.md, re-run both scripts, and fix whatever check_manifests.py reports. Prose chapters link into the reference rather than restating it, which is what keeps that loop small.

The one exception is field-types.md, which is hand-maintained because the schema types a param's type as a plain string and so cannot enumerate the values. It tracks manifest_to_simf_type and prompt.rs in the wallet.

Building the book

You need mdBook:

cargo install mdbook

Then, from this directory:

mdbook serve --open   # live-reloading preview at http://localhost:3000
mdbook build          # render static HTML into ./book

Running the recipes

The recipes are executed with the tx-manifest-wallet CLI (this book calls it txw). Two ways to get it, both covered in Installing the CLI:

• txw-codespace — a dev container with the wallet already installed; nothing to set up locally.
• A local install — a prebuilt binary, the asdf plugin, or a source build.

Related projects

Project	What it is
txmanifest-wallet	The reference wallet/engine (tx-manifest-wallet) and example manifests.
tx_manifest_spec	A prose specification, tracked separately and currently ahead of format 0.2.0. The wallet's generated schema is what this book follows.
asdf-tx-manifest-wallet	asdf plugin that installs prebuilt wallet binaries.
txw-codespace	Dev container / GitHub Codespace with the wallet preinstalled.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.