Pages on BXM.net

About

Mon, 01 Jan 0001 00:00:00 +0000

BXM is two small tools that share one idea: same input, same bytes, same result. They live in one repository and on one site because they solve the same kind of problem from two ends.

BXM Canon is a binary encoding with exactly one valid form for every value. When two programs encode the same data, they get the same bytes, so a hash or a signature taken on one machine holds on every other. More about Canon.

BXM Canon

Mon, 01 Jan 0001 00:00:00 +0000

BXM Canon is a binary encoding with exactly one valid encoding for every value. Same data in, same bytes out, on any machine. The decoder refuses everything else, so “are these two the same?” becomes “are these bytes equal?”.

The Problem It Solves

Sign a JSON object on one machine and check the signature on another, and it can fail even though nothing changed. One side wrote the keys in another order. Or 1.0 came out as 1. Or a string used an escape the other side didn’t. Same data, different bytes, broken hash.

BXM Memo

Mon, 01 Jan 0001 00:00:00 +0000

BXM Memo skips a command when its inputs haven’t changed. Put bxm-memo run in front of a slow step, say what it reads and writes, and the next time the inputs match it restores the outputs instead of running the step. When the inputs don’t match, it says which one changed.

bxm-memo run -i 'proto/**/*.proto' -i gen.sh -o gen/ -- ./gen.sh

The Problem It Solves

Build and CI pipelines redo work whose inputs didn’t change: code generation, asset processing, test fixtures, site builds, data preparation. Each step is a few seconds or minutes, and it adds up on every push and every laptop.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

Bug reports, feature requests and pull requests are welcome on GitHub. That’s the fastest way to get something fixed, and other people can see the answer.

For anything else, write to info@bxm.net.

The project would especially like to hear from:

People writing another Canon implementation, in any language, who find a corner of the spec that could be read two ways.
Teams trying Memo in CI, about what they wrapped, how much time it saved and what got in the way.
Anyone who signs or hashes structured data and has been bitten by two systems writing the same thing differently.

Download BXM

Mon, 01 Jan 0001 00:00:00 +0000

Each archive holds both tools, bxm-canon and bxm-memo, plus the Canon library and C header, the format spec with its test vectors, and the license files. The links always point to the latest release.

System	Download
Linux, x86-64	bxm-linux-amd64.tar.gz
Linux, ARM64	bxm-linux-arm64.tar.gz
macOS, Apple silicon	bxm-darwin-arm64.tar.gz
macOS, Intel	bxm-darwin-amd64.tar.gz
Windows, x86-64	bxm-windows-amd64.zip

To check a download, compare it with SHA256SUMS.

Canon for JavaScript

The bxm-canon package for Node 18+ and browsers is attached to every release:

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Five minutes with each tool. First download the archive for your system and put bxm-canon and bxm-memo on your PATH.

BXM Canon

Write the same data two ways and hash both:

echo '{"name":"bxm","tags":["a","b"],"n":3}' > a.json
echo '{ "n": 3, "tags": ["a", "b"], "name": "bxm" }' > b.json

bxm-canon hash --text a.json
bxm-canon hash --text b.json

The two hashes are the same, because both files hold the same value and Canon has one encoding for it.

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Every command and flag of both tools, and the Canon format in brief. The full format is in spec/CANON.md.

bxm-canon

bxm-canon encode [FILE] [-o OUT]     Canon text (JSON) in, canonical bytes out
bxm-canon decode [FILE] [--pretty]   canonical bytes in, Canon text out
bxm-canon fmt [FILE] [--pretty]      text in, the one normal text form out
bxm-canon check FILE...              exit 0 only if every file is canonical bytes
bxm-canon hash [FILE] [--text]       SHA-256 of the canonical bytes
bxm-canon diff A B [--text]          paths that differ between two values
bxm-canon version

FILE defaults to standard input, and - also means standard input. --text tells hash and diff that the inputs are Canon text rather than canonical bytes. -o writes to a file instead of standard output.

Use Cases

Mon, 01 Jan 0001 00:00:00 +0000

Where BXM earns its place, with a worked case study for each. Every case study is a script in the repository under examples/case-studies. Its recorded output is in test/results/case-studies, and you can run it again yourself.

BXM Canon

Signatures and hashes across languages. One service signs data and another checks it, each in its own language. With Canon both sides sign the same bytes, so the check only fails when the data changed. One order built in Python, JavaScript and by hand gave three JSON hashes and one Canon hash. Python’s signature over its JSON failed in JavaScript, and the one over the Canon bytes passed.