Skip to content

setup.md

Latest commit

 

History

History
155 lines (117 loc) · 5.72 KB

setup.md

File metadata and controls

155 lines (117 loc) · 5.72 KB
Raw

Installing the CLI

To run the recipes in this book you need a wallet that understands txmanifest. An example wallet is provided at https://github.com/stringhandler/txmanifest-wallet

This page installs that CLI and points it at a network. Creating a wallet then gets you keys and coins.

tx-manifest-wallet is an example implementation of a wallet. It is a reference tool that consumes manifests and walks through the full build-and-sign lifecycle so the recipes in this book are runnable. It is not the only way to consume a manifest — any wallet can implement the same lifecycle. If you are building your own wallet, see the Wallet implementation guide for the execution lifecycle a wallet follows when executing an action.

Get the CLI

The wallet binary is tx-manifest-wallet, and this book calls it txw throughout — the two are interchangeable. There are two ways to get it.

The codespace installs nothing on your machine and is the fastest way to run a recipe. A local install is what you want if you would rather work in your own editor, or you are on arm64.

The codespace (nothing to install)

txw-codespace is a dev container with the wallet already installed and nothing else. Click the badge in its README, or from the repo page choose Code ▸ Codespaces ▸ Create codespace on main. First creation takes a couple of minutes and ends with Ready. in the log.

Then:

txw --help

Three things about it are worth knowing before you start:

  • work/ is entirely gitignored. Put your manifests, wallets and state files there and nothing of yours can be committed by accident. Start every recipe with cd work.

  • txw is a wrapper script, not a shell alias, so it works from scripts and editor tasks as well as from the prompt.

  • The recipes that use bundled examples need one command first. The examples are not copied into the codespace, where they would drift from the format the installed wallet speaks. Fetch them on demand:

    ./scripts/fetch-examples.sh

    That puts a sparse clone in work/txmanifest-wallet/, keeping upstream's examples/ and schema/ layout so the manifests' relative $schema references still resolve.

It runs on x86_64 only, because that is what the wallet publishes Linux binaries for. On an arm64 machine, use a local build.

A local install

A prebuilt binary is the simplest. Grab one from the releases page — Linux x86_64, macOS Apple Silicon, and Windows x86_64 are published — unpack it, and put tx-manifest-wallet on your PATH:

curl -LO https://github.com/stringhandler/txmanifest-wallet/releases/download/v0.2.2/tx-manifest-wallet-v0.2.2-x86_64-unknown-linux-gnu.tar.gz
tar xzf tx-manifest-wallet-v0.2.2-x86_64-unknown-linux-gnu.tar.gz
sudo mv tx-manifest-wallet /usr/local/bin/
alias txw=tx-manifest-wallet
txw --help

Asset names are version-stamped, so check the releases page for the current one. The macOS and Windows builds are tx-manifest-wallet-<version>-aarch64-apple-darwin.tar.gz and tx-manifest-wallet-<version>-x86_64-pc-windows-msvc.zip.

Or via asdf, which is how the codespace does it, and lets you keep several versions side by side (Linux x86_64 and macOS Apple Silicon; asdf is shell-based, so not Windows):

asdf plugin add tx-manifest-wallet https://github.com/stringhandler/asdf-tx-manifest-wallet.git
asdf install tx-manifest-wallet latest
asdf set -u tx-manifest-wallet latest

Or from source, which is the arm64 answer and the one to use if you want to change the wallet itself. It is the txmanifest_wallet crate of a standard Cargo workspace:

git clone https://github.com/stringhandler/txmanifest-wallet
cd txmanifest-wallet
cargo build --release          # binary at ./target/release/tx-manifest-wallet
alias txw="$(pwd)/target/release/tx-manifest-wallet"
txw --help

A source clone also gives you examples/ directly, which is what the recipes' bundled-example paths refer to.

Check the version speaks this format

This book is written against manifest format 0.2.0, and a wallet checks that before it does anything else. Any 0.2.x release speaks it; a 0.1.x one will refuse every manifest here.

txw --version

In the codespace the version is pinned in .tool-versions and can be changed without a rebuild:

./scripts/set-wallet-version.sh latest

Throughout the book, commands are written as txw <subcommand>. Manifest paths like examples/p2pk/txmanifest.json are relative to your current directory — run them from a source clone, or from work/txmanifest-wallet/ in the codespace.

You do not need simc installed. The SimplicityHL compiler is linked into the wallet as a library, so txw compiles the .simf files a manifest points at in-process. Nothing shells out, and there is no separate toolchain to keep in step. The simc "=x.y.z"; directive inside a .simf still applies — it is enforced by that same linked compiler.

Configure the network and backend

The CLI keeps a small config file with two keys: the default network and the default Esplora URL. Set them once:

txw config default_network testnet
txw config default_esplora https://blockstream.info/liquidtestnet/api

Run config with no arguments to print the current values:

txw config

Most subcommands also accept --network and --esplora flags to override the defaults per-invocation.

With the CLI installed and pointed at testnet, the next step is a wallet: Creating a wallet.