Writing a wrapper

A wrapper turns “run a process, read stdout” into function calls. The contract makes this simple if the wrapper follows a few rules. Complete, tested wrappers are in wrappers/: Python, TypeScript, Rust, Shell.

The algorithm

1. argv = [binary, "--output", "json", ...command path, ...options]   # array, no shell
   + "--yes" for writes, only with the user's consent
2. spawn with stdin closed, a timeout (≈45 s), environment with MOSTRO_PUBKEY/RELAYS
3. if spawn failed                     → TransportError(may_have_acted = false)
   if timeout                          → TransportError(may_have_acted = is_write)
4. stdout.strip() empty                → TransportError(may_have_acted = is_write and exit == 1)
   not one JSON object                 → TransportError(may_have_acted = is_write)
5. envelope.schema_version != "1"      → IncompatibleError
6. return envelope (+ exit code)       → caller branches on status, then error.code

Rules

1. Build argv as a list. Never join a command string for a shell; values such as payment methods and invoices are user data.
2. One --output json, placed first. Never let user data land where an option is expected. For a value that could start with -, use the attached form --payment-method=<value>: the CLI never reads an output selection inside a value.
3. Close stdin. The CLI does not read it in JSON mode; a closed stdin makes sure a future version can never block on a prompt.
4. Parse stdout, ignore stderr (log it, do not parse it).
5. Branch on status, then error.code. Never on message. Keep a default branch for codes you do not know (within v1 new commands can add codes).
6. Keep decimal strings as strings or parse them as big integers.
7. Never retry uncertain or a write transport failure automatically. See Recovering.
8. Serialise writes per data directory.
9. Discover once: call schema at start-up; check every command you need is present with "json" in output_modes.
10. Validate optionally: the per-command output schemas are strict; validating in tests (or in debug builds) catches drift between your wrapper and a new binary.

Surfacing results to a UI

Testing a wrapper without a node

Many outcomes can be produced offline:

For the rest, feed your parser the files in examples/ (all 120 are real-shaped envelopes; examples/index.json gives the exit code to pair with each).