@meantjs/format 0.0.0-bootstrap → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog: @meantjs/format
+
+The five Candid Profile library packages (`@meantjs/profile`, `/format`, `/consent`, `/tools`, `/reconcile`) release together under one version and pin each other exactly; a version appears here even when this package did not change. Release steps: `docs/releasing.md` in the repository.
+
+## 0.1.0 — 2026-10-28
+
+First published version.
+
+Published under the `@meantjs` scope (D-051). Before any release, this package was `@candid-core/profile-format`.
+
+- Names (spec §5.3, D-045): `normalizeName`, `resolveName`, `nameOf` and `ownerOf`, the one rule every consumer
+  reads a name by, checked against the shared vectors in `spec/names-vectors.json`. `ownerOf` and `nameOf` compare
+  Candid values structurally, so two different accounts never share a name.
+- Exact parse and display for the six value tags of Candid Profile v0: `amount`, `timestamp`, `duration`, `account`,
+  `subaccount`, `bytes`. Excess precision is refused, never rounded; integers never pass through a JavaScript number.
+- `formatterFor(node, { refs, now })` for a position of a resolved form, with `describe()` for form hints and tool
+  descriptions; `FormatError` with stable codes.
+- No dependency, no Node built-in: runs in Node 22+ and in browsers.
+- Bytes from another realm (an iframe, a `node:vm` context) are accepted wherever a `Uint8Array` is; the check is
+  exported as `asUint8Array`.
+- TypeScript declarations.

package/README.md

@@ -1,5 +1,124 @@
-# @meantjs/format 0.0.0-bootstrap
+# @meantjs/format
 
-This version is a placeholder with no code. It exists because npm can attach a trusted publisher only to a
-package that is already on the registry. Every real version is published by the repository's release workflow.
-Install `@meantjs/format` without a tag to get the latest released version.
+Exact value conversion for the six value tags of Candid Profile v0 (`docs/profile-v0.md` §5.3): `amount`, `timestamp`, `duration`, `account`, `subaccount` and `bytes`. It turns the text a person or an agent writes (`"1.5 ICP"`, `"+PT24H"`, `"#7"`) into the value a call carries, and back into canonical text for display. The agent tools (`@meantjs/tools`) and the ICRC-21 consent generator (`@meantjs/consent`) both use it, so they cannot disagree about what a value means.
+
+```sh
+npm install @meantjs/format
+```
+
+- **Runs on:** Node 22 or later and browsers: no dependency, no I/O, no Node built-in.
+- **Module format:** ES modules only, with hand-written TypeScript declarations for every entry.
+- **Spec:** [Candid Profile v0](https://github.com/B3Pay/Meant/blob/main/profile/docs/profile-v0.md). **Licence:** Apache-2.0.
+- **Versions:** the five Candid Profile packages (`@meantjs/profile`, `/format`, `/consent`, `/tools`,
+  `/reconcile`) release together under one version and pin each other exactly; in 0.x a minor is breaking,
+  and so is any change to generated text ([releasing](https://github.com/B3Pay/Meant/blob/main/profile/docs/releasing.md)).
+
+- **No rounding, ever** (ground rule 8, D-006): input with excess precision is rejected, a conversion that would lose precision throws, integers never pass through a JavaScript number.
+- **No dependencies** at run time or for tests. Node >= 22.
+- **No I/O.** Dynamic tag arguments (`{ "from": "query:icrc1_decimals" }`) are resolved by the caller and passed in.
+- The choices it made where §5.3 was open were accepted as D-024 and are now in spec §5.3.
+
+```sh
+npm test -w packages/format          # or: npm test at the repo root
+npm run vectors -w packages/format   # re-fetch the ICRC-1 examples (needs network; see below)
+```
+
+## API
+
+The entry point for consumers:
+
+```js
+import { formatterFor } from "@meantjs/format";
+
+// node = a position of the resolved form (fixtures/*.resolved.json): { candid, tags, ... }
+const f = formatterFor(node, {
+  refs: { "query:icrc1_decimals": 8, "query:icrc1_symbol": "ICP" }, // dynamic args, keyed by their `from`
+  now: 1791547200000000000n,                                        // optional default clock, bigint ns
+});
+// f === null when the position has no value tag (render it as Candid text, spec §6)
+
+f.tag;                       // "amount" | "timestamp" | "duration" | "account" | "subaccount" | "bytes"
+f.args;                      // the tag's arguments with refs resolved, e.g. { decimals: 8, symbol: "ICP" }
+f.parse("1.5 ICP");          // -> "150000000"   (throws FormatError)
+f.display("150000000");      // -> "1.5 ICP"     (throws FormatError)
+f.safeParse(input, { now }); // -> { ok: true, value } | { ok: false, error: { code, message } }
+f.safeDisplay(value);        // same shape
+f.describe();                // -> { summary, examples, pattern? }: the text this position reads, in words
+```
+
+`describe()` gives a form hint or a tool input's description from the parser itself, so they cannot drift from it (#16). The summary is the grammar in words with the tag's resolved arguments filled in ("at most 8 digits after the point", the symbol), then "For example" and exactly the examples kept. Every kept example parses at this position: one a range or `max_len` refuses is left out (and the summary then quotes none), and a relative time is checked against the formatter's `now` when it was given one, else against a fixed instant, since describing reads no clock. `pattern` (amount and subaccount only, whose grammar is regular) is an ECMAScript regular expression for a JSON Schema `pattern`, valid under the `u` flag. It is a necessary condition only: everything `parse` accepts matches it, and a match can still be refused for its range. `describeInput(tag, args, candid, { accepts })` is the same without a formatter: it refuses the arguments and Candid types `formatterFor` refuses, with the same codes, and keeps the examples `accepts` returns true for (all, by default).
+
+`formatterFor` throws a `FormatError` (never returns a half-working formatter) when a ref is missing (`E_REF_UNRESOLVED`), a tag argument is invalid (`E_ARG`), the tag does not apply to the node's Candid type (`E_TAG_TYPE`) or the position carries two value tags (`E_TAG_CONFLICT`). `opt` is the node's `optional` flag: handle absence before calling the formatter.
+
+The same functions are exported directly: `parseAmount`, `displayAmount`, `parseTimestamp`, `displayTimestamp`, `parseDuration`, `displayDuration`, `convertUnit`, `alignNow`, `parseAccount`, `displayAccount`, `principalFromText`, `principalToText`, `parseSubaccount`, `displaySubaccount`, `parseBytes`, `displayBytes`, `VALUE_TAGS`, `describeInput`, `CODES`, `FormatError`.
+
+### Values
+
+| Tag | `parse` returns / `display` takes | Options |
+|---|---|---|
+| `amount` | base-unit integer as a decimal string (a bigint is accepted by `display`; a number is rejected) | `decimals`, `symbol`, `candid` (sign and range) |
+| `timestamp` | integer count of `unit` since the Unix epoch, decimal string | `unit` (`ns` `us` `ms` `s`), `candid`, `now` (bigint ns, relative input only) |
+| `duration` | integer count of `unit`, decimal string | `unit`, `candid` |
+| `account` | `{ owner: <principal text>, subaccount: Uint8Array(32) \| null }`, `null` = the default subaccount | |
+| `subaccount` | `Uint8Array(32)` | |
+| `bytes` | `Uint8Array` | `encoding` (`utf8` `hex` `base64`), `maxLen` (the tag's `max_len`, bytes) |
+
+Wherever a `Uint8Array` is taken, one made in another realm (an iframe, a `node:vm` context, a test environment's
+`TextEncoder`) is accepted too, read through its typed-array slot; other typed arrays, `DataView`s and look-alike
+objects are refused with `E_TYPE`, and so are a `Proxy` around a `Uint8Array` (it passed `instanceof` before) and
+a view of a detached buffer. A foreign view's memory is read through the intrinsic typed-array getters, so its own
+properties cannot make it show other bytes. The library imports no Node built-in (`test/browser-bundle.test.mjs`). The check is exported as `asUint8Array(value)`: the value as a `Uint8Array` of this realm viewing the same memory, or `null`. `@meantjs/consent` and `@meantjs/tools` use it, so the three packages agree on what bytes are.
+
+Other helpers: `convertUnit(value, from, to)` converts an integer between units and throws `E_INEXACT` when it would lose precision (W4: a ns timestamp with sub-second digits does not fit ICRC-21's `TimestampSeconds`; catch it and fall back to `Text`). `alignNow(nowNs, unit)` floors a clock reading to a unit. `parseTimestamp` already does this to `now` before adding a relative duration (spec §5.3, D-024), so `+PT24H` on a `unit: s` field is exact; `alignNow` is exported for callers that want the aligned value themselves.
+
+### Errors
+
+Every rejection is a `FormatError` with a stable `code` and a message that says how to fix the input. Codes: `E_TYPE` `E_SYNTAX` `E_RANGE` `E_TOO_LONG` `E_ARG` `E_TAG_TYPE` `E_TAG_CONFLICT` `E_REF_UNRESOLVED` `E_EXCESS_PRECISION` `E_NEGATIVE` `E_SYMBOL_MISMATCH` `E_INEXACT` `E_CALENDAR_UNIT` `E_NEEDS_NOW` `E_CHECKSUM` `E_CHECKSUM_MISSING` `E_NOT_CANONICAL` `E_PRINCIPAL` `E_HEX` `E_BASE64` `E_UTF8` `E_LENGTH` `E_MAX_LEN` (`CODES` lists them with their meaning).
+
+## Rules and where they are tested
+
+| Spec §5.3 rule | Behavior | Test (`test/rejections.test.mjs` unless noted) |
+|---|---|---|
+| amount: more than `d` fractional digits is rejected, never rounded | `E_EXCESS_PRECISION` (also for trailing zeros, proposal F1) | "amount: input with more than d fractional digits…"; property in `amount.test.mjs` |
+| amount: negative rejected unless signed | `E_NEGATIVE` | "amount: negative input…" |
+| amount: symbol must match, case-insensitive | `E_SYMBOL_MISMATCH` | "amount: a symbol that does not match…" |
+| timestamp: conversion to the unit is exact (an absolute time or a duration finer than the unit) | `E_INEXACT` | "timestamp: a conversion… is not exact"; properties in `time.test.mjs` |
+| timestamp: relative input is resolved against `now` floored to the unit | | "timestamp: a relative time is resolved against now floored…" |
+| timestamp: relative input follows the duration rules | `E_CALENDAR_UNIT`, `E_NEEDS_NOW` | "timestamp: relative input…" (two tests) |
+| duration: only W, D, H, M (after T), S | `E_SYNTAX` | "duration: only W, D, H, M…" |
+| duration: `P1Y`, `P1M` rejected | `E_CALENDAR_UNIT` | "duration: calendar years and months…" |
+| duration: `P1D` is exactly 86,400 s | | "duration: P1D is exactly 86,400 s" |
+| account: checksum verified on input | `E_CHECKSUM`, `E_CHECKSUM_MISSING` | "account: the checksum is verified on input"; the ICRC-1 vectors in `account.test.mjs` |
+| subaccount: `0 <= n < 2^64` | `E_RANGE` | "subaccount: a decimal n outside…" |
+| subaccount: hex is exactly 64 characters | `E_LENGTH` | "subaccount: a hex form with other than exactly 64…" |
+| subaccount: `parse(display(x)) = x` for every 32-byte value | | edge values in `rejections.test.mjs`; property over 20,000 random values in `subaccount.test.mjs` |
+| subaccount: display is `#n` iff the first 24 bytes are zero | | "subaccount: display is #n if and only if…" and the same property |
+| bytes: `max_len` counts bytes after encoding | `E_MAX_LEN` | "bytes: max_len counts bytes after encoding…" |
+| bytes: utf8 input starting with `0x` is hex | `E_HEX` for malformed hex | "bytes: utf8 input starting with 0x is hex…" |
+| §4 / D-006: integers are never JavaScript numbers | `E_TYPE` | "an integer is never a JavaScript number…" |
+
+## Why no principal library
+
+`principalFromText` and the ICRC-1 checksum need base32 and CRC-32. Options considered:
+
+- `@dfinity/principal` 3.4.3: tiny (one dependency, `@noble/hashes`), but **deprecated** on npm in favour of `@icp-sdk/core`, which would put a deprecation warning on every `npm ci`.
+- `@icp-sdk/core` 6.1.0: the supported package, but 2.2 MB unpacked with six direct dependencies (asn1js, two `@scure` BIP packages, `@dfinity/cbor`, `@noble/curves`, `@noble/hashes`) for a feature that is ~60 lines. It also pulls key-handling code into a package whose point is to be small enough to review.
+- **Chosen: implement it** in `src/principal.mjs` (base32 lowercase without padding, CRC-32 with the zlib polynomial, the canonical-dashes rule), with zero dependencies, and check it three ways:
+  1. the 7 official ICRC-1 parse examples and 3 `toText` examples, well-known canister ids (`aaaaa-aa`, `2vxsx-fae`, the ICP ledger, NNS governance and registry);
+  2. independent oracles in the tests: CRC-32 from `node:zlib`, and a base32 encoder built on big-integer division (a different algorithm from the bit shifter in `src`), compared on thousands of random principals and accounts; plus a property that **every single-character change** to a canonical account text is rejected;
+  3. a one-off differential run against `@dfinity/principal` 3.4.3 (installed temporarily, removed again): 60,000 random principals of 0 to 29 bytes, text and bytes in both directions, 0 mismatches. This is **not** in the suite, so it is not reproducible from the repo; the suite's oracles are.
+
+## ICRC-1 test vectors
+
+`test/vectors/icrc1-textual-encoding.json` holds the examples of the ICRC-1 textual encoding standard, extracted by `scripts/fetch-icrc1-vectors.mjs` from `standards/ICRC-1/TextualEncoding.md` of github.com/dfinity/ICRC-1 at commit `5d670e54d9a58fbf472bf0a25f33743d60cfd0e6` (head of `main` on 2026-10-09; Apache-2.0). The download itself, with its LICENSE, `SOURCE.json` (commit, URLs, sha256) lives alone in `upstream/icrc1/`.
+
+The download is **untrusted data**: the script only reads it as text and extracts fields with fixed regular expressions (and aborts if the shape changes), nothing from `upstream/` is ever imported or executed, and the tests read the committed JSON, never the network. A test checks that the recorded sha256 matches the committed bytes and that every vector appears in the document. To move to another commit: `node scripts/fetch-icrc1-vectors.mjs --commit <40-hex sha>`, review the diff of `upstream/` and the vectors, update `PINNED` in the script.
+
+## Design notes
+
+- **Integers are decimal strings or bigints** (D-006). Nanosecond timestamps (~1.8e18) and 18-decimal amounts exceed 2^53; a JavaScript number is rejected on input and on display.
+- **Calendar math is in BigInt nanoseconds** with the proleptic Gregorian calendar (days-from-civil), not `Date` (millisecond precision). Tests compare against `Date` for millisecond instants and zones.
+- **Display is canonical and total**: it throws on a value that does not fit the Candid type or the calendar instead of producing something misleading.
+- **Untrusted text**: lengths are bounded (1024 characters; 4 MiB for `bytes`), regular expressions are anchored and linear, symbols from a canister's `icrc1_symbol` are checked for control and invisible characters before use.
+- **Escaping is not done here.** `display` returns plain text; a memo can contain Markdown. The template renderer escapes values for its target format (spec §6).
+- **Property tests** use a seeded PRNG (`test/helpers/prng.mjs`, default seed 20261009, override with `FORMAT_TEST_SEED`); every failure message carries the seed.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@meantjs/format",
-  "version": "0.0.0-bootstrap",
-  "description": "Placeholder that registers the name for trusted publishing. Install a released version of @meantjs/format instead.",
+  "version": "0.1.0",
+  "description": "Exact value conversion for Candid Profile value tags (amount, timestamp, duration, account, subaccount, bytes): parse human input, display canonical text, never round.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -9,8 +9,43 @@
     "directory": "profile/packages/format"
   },
   "homepage": "https://github.com/B3Pay/Meant/tree/main/profile/packages/format#readme",
+  "bugs": {
+    "url": "https://github.com/B3Pay/Meant/issues"
+  },
+  "keywords": [
+    "candid",
+    "internet-computer",
+    "icp",
+    "icrc-1",
+    "amount",
+    "account",
+    "principal",
+    "no-rounding"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./src/index.mjs",
+  "types": "./src/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.mts",
+      "default": "./src/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
-    "README.md",
+    "src",
+    "CHANGELOG.md",
     "LICENSE"
-  ]
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "vectors": "node scripts/fetch-icrc1-vectors.mjs"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2"
+  }
 }

package/src/account.mjs

@@ -0,0 +1,78 @@
+// `account`, encoding `icrc1` (spec §5.3): the ICRC-1 textual encoding of
+// record { owner : principal; subaccount : opt blob }.
+//
+//   default subaccount (absent or 32 zero bytes):  <principal>
+//   any other subaccount:  <principal>-<checksum>.<subaccount hex without leading zeros>
+//     checksum = base32 (lowercase, no padding) of CRC-32(principal bytes ++ 32 subaccount bytes)
+//
+// Source: dfinity/ICRC-1 standards/ICRC-1/TextualEncoding.md. Value shape here:
+//   { owner: <principal text>, subaccount: Uint8Array(32) | null }   (null = the default subaccount)
+
+import { CODES, fail } from "./errors.mjs";
+import { MAX_INPUT_CHARS, bytesToHex, hexToBytes, requireString, toBytes } from "./util.mjs";
+import { accountChecksum, principalFromText, principalToText } from "./principal.mjs";
+
+const CHECKSUM_RE = /^[a-z2-7]{7}$/i;
+
+const isZero = (b) => b.every((x) => x === 0);
+
+/** Owner as principal bytes, from canonical text or bytes. */
+function ownerBytes(owner) {
+  if (typeof owner === "string") return principalFromText(owner);
+  const b = toBytes(owner, "owner");
+  principalToText(b); // length check
+  return b;
+}
+
+/**
+ * Parse an ICRC-1 account text. A bare principal is the default subaccount. The checksum is
+ * verified, and non-canonical texts (an explicit default subaccount, leading zeros in the
+ * subaccount, wrong dashes) are rejected.
+ *
+ * @param {string} input
+ * @returns {{ owner: string, subaccount: Uint8Array | null }}
+ */
+export function parseAccount(input) {
+  const text = requireString(input, "account").trim();
+  if (text.length > MAX_INPUT_CHARS) fail(CODES.TOO_LONG, "account is too long");
+  const dot = text.indexOf(".");
+  if (dot < 0) return { owner: principalToText(principalFromText(text)), subaccount: null };
+  if (text.indexOf(".", dot + 1) >= 0) fail(CODES.SYNTAX, `${JSON.stringify(text)} has more than one "."`);
+
+  const left = text.slice(0, dot);
+  const hex = text.slice(dot + 1);
+  const dash = left.lastIndexOf("-");
+  const checksum = dash < 0 ? "" : left.slice(dash + 1);
+  if (!CHECKSUM_RE.test(checksum)) {
+    fail(CODES.CHECKSUM_MISSING, `${JSON.stringify(text)} has a subaccount but no checksum: the form is <principal>-<checksum>.<subaccount>`);
+  }
+  if (hex === "") fail(CODES.NOT_CANONICAL, "the default subaccount is written as the bare principal, without a checksum or a dot");
+  if (!/^[0-9a-fA-F]+$/.test(hex)) fail(CODES.HEX, `the subaccount ${JSON.stringify(hex)} is not hexadecimal`);
+  if (hex.startsWith("0")) fail(CODES.NOT_CANONICAL, "the subaccount must not have leading zeros; they are removed in the canonical text");
+  if (hex.length > 64) fail(CODES.LENGTH, `the subaccount is at most 64 hex digits, got ${hex.length}`);
+
+  const owner = principalFromText(left.slice(0, dash));
+  const sub = hexToBytes(hex.padStart(64, "0"));
+  if (accountChecksum(owner, sub) !== checksum.toLowerCase()) {
+    fail(CODES.CHECKSUM, `the checksum ${checksum} does not match this principal and subaccount (a character was probably mistyped)`);
+  }
+  return { owner: principalToText(owner), subaccount: sub };
+}
+
+/**
+ * Display an account in the ICRC-1 textual encoding.
+ *
+ * @param {{ owner: string | Uint8Array, subaccount?: Uint8Array | number[] | null }} account
+ *   `subaccount` absent, null or 32 zero bytes means the default subaccount
+ * @returns {string}
+ */
+export function displayAccount(account) {
+  if (account === null || typeof account !== "object") fail(CODES.TYPE, "account must be { owner, subaccount }");
+  const owner = ownerBytes(account.owner);
+  const ownerText = principalToText(owner);
+  if (account.subaccount === undefined || account.subaccount === null) return ownerText;
+  const sub = toBytes(account.subaccount, "subaccount");
+  if (sub.length !== 32) fail(CODES.LENGTH, `a subaccount is 32 bytes, got ${sub.length}`);
+  if (isZero(sub)) return ownerText;
+  return `${ownerText}-${accountChecksum(owner, sub)}.${bytesToHex(sub).replace(/^0+/, "")}`;
+}

package/src/amount.mjs

@@ -0,0 +1,92 @@
+// `amount` (spec §5.3): exact decimal text <-> base-unit integers.
+//
+// Values are decimal strings (D-006). Nothing here uses a JavaScript number for an amount, and
+// nothing rounds: input with more fractional digits than `decimals` is rejected, even when the
+// extra digits are zeros (the literal reading of "more than d fractional digits MUST be rejected").
+
+import { CODES, fail } from "./errors.mjs";
+import { UNSAFE_DISPLAY_CHAR, checkRange, intType, requireString, toBigInt } from "./util.mjs";
+
+export const AMOUNT_TYPES = ["nat", "int", "nat8", "nat16", "nat32", "nat64", "int8", "int16", "int32", "int64"];
+
+// number, then (after whitespace) an optional symbol. "1.", ".5", "1,5", "1e3" and "+1" do not match.
+const AMOUNT_RE = /^(-?)([0-9]+)(?:\.([0-9]+))?(?:\s+(\S(?:.*\S)?))?$/s;
+
+/** ASCII-only case folding: "icp" matches "ICP", but a Kelvin sign never matches "k". */
+const asciiLower = (s) => s.replace(/[A-Z]/g, (c) => c.toLowerCase());
+
+/** @returns {string | undefined} a validated symbol */
+export function checkSymbol(symbol) {
+  if (symbol === undefined || symbol === null) return undefined;
+  if (typeof symbol !== "string") fail(CODES.ARG, `amount symbol must be a string, got ${typeof symbol}`);
+  const n = [...symbol].length;
+  if (n < 1 || n > 32) fail(CODES.ARG, `amount symbol must be 1 to 32 characters, got ${n}`);
+  if (symbol !== symbol.trim() || UNSAFE_DISPLAY_CHAR.test(symbol) || !symbol.isWellFormed()) {
+    fail(CODES.ARG, `amount symbol ${JSON.stringify(symbol)} has surrounding whitespace, control or invisible characters`);
+  }
+  return symbol;
+}
+
+export function checkDecimals(decimals) {
+  let d = decimals;
+  if (typeof d === "string" && /^(?:0|[1-9][0-9]{0,2})$/.test(d)) d = Number(d);
+  if (typeof d === "bigint" && d >= 0n && d <= 255n) d = Number(d);
+  if (!Number.isInteger(d) || d < 0 || d > 255) fail(CODES.ARG, `amount decimals must be an integer from 0 to 255, got ${String(decimals)}`);
+  return d;
+}
+
+/**
+ * Parse "1.5" or "1.5 ICP" into a base-unit decimal string.
+ *
+ * @param {string} input
+ * @param {{ decimals: number | bigint | string, symbol?: string, candid?: string }} opts
+ * @returns {string}
+ */
+export function parseAmount(input, { decimals, symbol, candid = "nat" }) {
+  const d = checkDecimals(decimals);
+  const expected = checkSymbol(symbol);
+  const type = intType(candid, AMOUNT_TYPES, "amount");
+  const text = requireString(input, "amount").trim();
+  const m = AMOUNT_RE.exec(text);
+  if (!m) {
+    fail(
+      CODES.SYNTAX,
+      `cannot read ${JSON.stringify(text)} as an amount: write digits with an optional decimal point, for example "1.5"${expected ? ` or "1.5 ${expected}"` : ""}; no thousands separators, exponents or signs other than "-"`,
+    );
+  }
+  const [, sign, whole, frac = "", given] = m;
+  if (sign && !type.signed) fail(CODES.NEGATIVE, `negative amounts are not allowed here (the Candid type ${candid} is unsigned)`);
+  if (given !== undefined) {
+    if (expected === undefined) fail(CODES.SYMBOL_MISMATCH, `this amount has no symbol; remove "${given}" and give the number only`);
+    if (asciiLower(given) !== asciiLower(expected)) fail(CODES.SYMBOL_MISMATCH, `the symbol "${given}" is not this token's symbol "${expected}"`);
+  }
+  if (frac.length > d) {
+    fail(
+      CODES.EXCESS_PRECISION,
+      `${JSON.stringify(text)} has ${frac.length} fractional digits but this token has ${d}; amounts are never rounded, so give at most ${d}`,
+    );
+  }
+  const magnitude = BigInt(whole) * 10n ** BigInt(d) + BigInt(frac.padEnd(d, "0") || "0");
+  const v = sign ? -magnitude : magnitude;
+  checkRange(v, type, "amount");
+  return v.toString();
+}
+
+/**
+ * Display a base-unit integer as "1.5 ICP": trailing fractional zeros removed, symbol appended.
+ *
+ * @param {string | bigint} value
+ * @param {{ decimals: number | bigint | string, symbol?: string, candid?: string }} opts
+ * @returns {string}
+ */
+export function displayAmount(value, { decimals, symbol, candid = "nat" }) {
+  const d = checkDecimals(decimals);
+  const sym = checkSymbol(symbol);
+  const type = intType(candid, AMOUNT_TYPES, "amount");
+  const v = toBigInt(value, "amount");
+  checkRange(v, type, "amount");
+  const digits = (v < 0n ? -v : v).toString().padStart(d + 1, "0");
+  const whole = digits.slice(0, digits.length - d);
+  const frac = digits.slice(digits.length - d).replace(/0+$/, "");
+  return `${v < 0n ? "-" : ""}${whole}${frac ? `.${frac}` : ""}${sym ? ` ${sym}` : ""}`;
+}

package/src/bytes.mjs

@@ -0,0 +1,131 @@
+// `bytes` (spec §5.3): a blob shown and read as utf8, hex or base64.
+//
+//   utf8    input is plain text encoded as UTF-8; input starting with 0x is read as hex.
+//           Display is the decoded text when the bytes are valid UTF-8 without control
+//           characters, else 0x followed by lowercase hex.
+//   hex     input and display carry a 0x prefix (the prefix is optional on input).
+//   base64  RFC 4648 standard alphabet; padding optional on input, always written on display.
+//   max_len counts bytes after encoding.
+//
+// Two display rules go beyond the literal text so that parse(display(x)) = x always holds and so
+// that nothing misleading is shown (both are listed in docs/proposals/w3a-spec-5-3-clarifications.md):
+//   - utf8 text that itself starts with 0x/0X is displayed as hex, because as text it would be read back as hex;
+//   - besides control characters (Cc), text with format characters (Cf, for example bidirectional
+//     overrides, zero-width joiners and the byte order mark) or line and paragraph separators
+//     (Zl, Zp) is displayed as hex.
+
+import { CODES, fail } from "./errors.mjs";
+import { UNSAFE_DISPLAY_CHAR, bytesToHex, hexToBytes, toBytes } from "./util.mjs";
+
+export const BYTES_ENCODINGS = ["utf8", "hex", "base64"];
+
+/** Bound on the size of a text input (bounded work, spec §11.6). */
+const MAX_BYTES_INPUT_CHARS = 4 * 1024 * 1024;
+const HEX_PREFIX = /^0[xX]/;
+
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const B64_VALUE = (() => {
+  const t = new Int8Array(128).fill(-1);
+  for (let i = 0; i < 64; i++) t[B64.charCodeAt(i)] = i;
+  return t;
+})();
+
+function base64Encode(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const n = (bytes[i] << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+    out += B64[(n >> 18) & 63] + B64[(n >> 12) & 63];
+    out += i + 1 < bytes.length ? B64[(n >> 6) & 63] : "=";
+    out += i + 2 < bytes.length ? B64[n & 63] : "=";
+  }
+  return out;
+}
+
+/** Strict: standard alphabet, canonical padding or none, no stray characters, zero spare bits. */
+function base64Decode(text) {
+  const m = /^([A-Za-z0-9+/]*)(={0,2})$/.exec(text);
+  if (!m) {
+    fail(CODES.BASE64, "not base64: use the standard alphabet (A-Z, a-z, 0-9, + and /) with no spaces, line breaks or URL-safe characters");
+  }
+  const [, body, pad] = m;
+  const rem = body.length % 4;
+  if (rem === 1) fail(CODES.BASE64, "not base64: the length is impossible (one character too many or too few)");
+  if (pad && (rem === 0 || pad.length !== 4 - rem)) fail(CODES.BASE64, "not base64: the '=' padding is wrong");
+  const out = new Uint8Array(Math.floor((body.length * 3) / 4));
+  let acc = 0;
+  let bits = 0;
+  let o = 0;
+  for (let i = 0; i < body.length; i++) {
+    acc = (acc << 6) | B64_VALUE[body.charCodeAt(i)];
+    bits += 6;
+    if (bits >= 8) {
+      out[o++] = (acc >> (bits - 8)) & 255;
+      bits -= 8;
+    }
+    acc &= (1 << bits) - 1;
+  }
+  if (acc !== 0) fail(CODES.BASE64, "not canonical base64: the unused trailing bits must be zero");
+  return out;
+}
+
+function parseHex(text, what) {
+  const bytes = hexToBytes(text.replace(HEX_PREFIX, ""));
+  if (bytes === null) fail(CODES.HEX, `${what} is not hexadecimal: use an even number of digits 0-9 and a-f, for example "0x1a2b" (no spaces)`);
+  return bytes;
+}
+
+export function checkMaxLen(maxLen) {
+  if (maxLen === undefined || maxLen === null) return null;
+  let n = maxLen;
+  if (typeof n === "bigint" || (typeof n === "string" && /^(?:0|[1-9][0-9]*)$/.test(n))) n = Number(n);
+  if (!Number.isSafeInteger(n) || n < 0) fail(CODES.ARG, `max_len must be a non-negative integer, got ${String(maxLen)}`);
+  return n;
+}
+
+/**
+ * @param {string} input
+ * @param {{ encoding: "utf8"|"hex"|"base64", maxLen?: number }} opts  `maxLen` is the tag's max_len, in bytes
+ * @returns {Uint8Array}
+ */
+export function parseBytes(input, { encoding, maxLen } = {}) {
+  if (!BYTES_ENCODINGS.includes(encoding)) fail(CODES.ARG, `bytes encoding must be one of ${BYTES_ENCODINGS.join(", ")}, got ${JSON.stringify(encoding)}`);
+  const max = checkMaxLen(maxLen);
+  if (typeof input !== "string") fail(CODES.TYPE, `bytes input must be a string, got ${typeof input}`);
+  if (input.length > MAX_BYTES_INPUT_CHARS) fail(CODES.TOO_LONG, `bytes input is longer than ${MAX_BYTES_INPUT_CHARS} characters`);
+  let bytes;
+  if (encoding === "utf8") {
+    if (HEX_PREFIX.test(input)) bytes = parseHex(input, "text starting with 0x (read as hex)");
+    else {
+      // TextEncoder would replace a lone surrogate with U+FFFD without saying so.
+      if (!input.isWellFormed()) fail(CODES.UTF8, "the text contains an unpaired surrogate and cannot be encoded as UTF-8");
+      bytes = new TextEncoder().encode(input);
+    }
+  } else if (encoding === "hex") {
+    bytes = parseHex(input, "the value");
+  } else {
+    bytes = base64Decode(input);
+  }
+  if (max !== null && bytes.length > max) fail(CODES.MAX_LEN, `the value is ${bytes.length} bytes after encoding but at most ${max} are allowed`);
+  return bytes;
+}
+
+/**
+ * @param {Uint8Array | number[]} value
+ * @param {{ encoding: "utf8"|"hex"|"base64" }} opts
+ * @returns {string}
+ */
+export function displayBytes(value, { encoding } = {}) {
+  if (!BYTES_ENCODINGS.includes(encoding)) fail(CODES.ARG, `bytes encoding must be one of ${BYTES_ENCODINGS.join(", ")}, got ${JSON.stringify(encoding)}`);
+  const bytes = toBytes(value, "bytes");
+  if (encoding === "hex") return `0x${bytesToHex(bytes)}`;
+  if (encoding === "base64") return base64Encode(bytes);
+  let text;
+  try {
+    // ignoreBOM keeps a leading U+FEFF in the string instead of silently dropping its three bytes
+    text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    return `0x${bytesToHex(bytes)}`;
+  }
+  if (UNSAFE_DISPLAY_CHAR.test(text) || HEX_PREFIX.test(text)) return `0x${bytesToHex(bytes)}`;
+  return text;
+}

package/src/errors.mjs

@@ -0,0 +1,49 @@
+// Every rejection in this package is a FormatError with a stable `code`.
+// Callers (arm C tool layer, the ICRC-21 generator) switch on `code`; `message` is written for a
+// model or a person and says how to fix the input.
+
+export class FormatError extends Error {
+  /**
+   * @param {string} code  one of CODES
+   * @param {string} message
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = "FormatError";
+    this.code = code;
+  }
+}
+
+export const CODES = Object.freeze({
+  // shared
+  TYPE: "E_TYPE", // wrong JavaScript type for an input, for example a number where a decimal string is required
+  SYNTAX: "E_SYNTAX", // the text does not match the grammar
+  RANGE: "E_RANGE", // outside the range of the Candid type or of the representable calendar
+  TOO_LONG: "E_TOO_LONG", // input longer than the bound on work
+  ARG: "E_ARG", // a tag argument is missing or invalid
+  TAG_TYPE: "E_TAG_TYPE", // the tag does not apply to this Candid type
+  TAG_CONFLICT: "E_TAG_CONFLICT", // two formatting tags at one position
+  REF_UNRESOLVED: "E_REF_UNRESOLVED", // a dynamic value was not supplied by the caller
+  // amount
+  EXCESS_PRECISION: "E_EXCESS_PRECISION", // more fractional digits than decimals (never rounded)
+  NEGATIVE: "E_NEGATIVE", // negative input for an unsigned Candid type
+  SYMBOL_MISMATCH: "E_SYMBOL_MISMATCH", // the symbol in the input is not the token's symbol
+  // time
+  INEXACT: "E_INEXACT", // the value cannot be represented exactly in the requested unit
+  CALENDAR_UNIT: "E_CALENDAR_UNIT", // years and months have no fixed length
+  NEEDS_NOW: "E_NEEDS_NOW", // relative time without a `now`
+  // account, subaccount, bytes
+  CHECKSUM: "E_CHECKSUM", // checksum does not match
+  CHECKSUM_MISSING: "E_CHECKSUM_MISSING",
+  NOT_CANONICAL: "E_NOT_CANONICAL", // a valid value written in a non-canonical way
+  PRINCIPAL: "E_PRINCIPAL", // invalid principal text
+  HEX: "E_HEX",
+  BASE64: "E_BASE64",
+  UTF8: "E_UTF8", // text that cannot be encoded as UTF-8 (lone surrogate)
+  LENGTH: "E_LENGTH", // wrong length in bytes
+  MAX_LEN: "E_MAX_LEN", // longer than the tag's max_len
+});
+
+export function fail(code, message) {
+  throw new FormatError(code, message);
+}