@meantjs/format 0.0.0-stage → 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/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# @meantjs/format
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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,6 +1,51 @@
 {
   "name": "@meantjs/format",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+    "url": "git+https://github.com/B3Pay/Meant.git",
+    "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": [
+    "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}` : ""}`;
+}