@fintekkers/ledger-models 0.4.38 → 0.4.39

package/node/wrappers/models/utils/decimal.test.ts

@@ -0,0 +1,272 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { Decimal } from 'decimal.js';
+import { DecimalValueProto } from '../../../fintekkers/models/util/decimal_value_pb';
+import { ModelValidationError } from '../errors';
+import { ProtoSerializationUtil } from './serialization';
+import {
+    CompactDecimal,
+    MAX_DIGITS,
+    MAX_SCALE,
+    MAX_UNSCALED_BYTES,
+    decodeDecimal,
+    encodeDecimal,
+    fromDecimalJs,
+    parseDecimalString,
+    setDecimalLogger,
+    toCanonicalString,
+    withField,
+} from './decimal';
+
+/** Codec tests against the shared fixture (LM-306, JS side of LM-294). */
+
+const FIXTURE = JSON.parse(fs.readFileSync(
+    path.join(__dirname, '../../../../../ledger-models-protos/fixtures/decimal_compact.json'), 'utf8'));
+
+interface Case { name: string; string: string; canonical: string; unscaled_hex: string; scale: number; wire_hex: string }
+const CASES: Case[] = FIXTURE.cases;
+
+const hex = (bytes: Uint8Array) => Buffer.from(bytes).toString('hex');
+const unhex = (s: string) => new Uint8Array(Buffer.from(s, 'hex'));
+
+/** Two's-complement big-endian, written independently of the codec. */
+function expectedUnscaled(unscaledHex: string): bigint {
+    const unsigned = BigInt('0x' + unscaledHex);
+    const negative = parseInt(unscaledHex.slice(0, 2), 16) >= 0x80;
+    return negative ? unsigned - (BigInt(1) << BigInt(unscaledHex.length * 4)) : unsigned;
+}
+
+/** Only fields 11 and 12 set. */
+function compactOnly(c: Case): DecimalValueProto {
+    return new DecimalValueProto().setUnscaledValue(unhex(c.unscaled_hex)).setScale(c.scale);
+}
+
+function expectInvalid(fn: () => unknown): void {
+    expect(fn).toThrow(ModelValidationError);
+}
+
+beforeAll(() => {
+    // String-only decodes below would warn once; keep the test output quiet.
+    setDecimalLogger({ warn: jest.fn() });
+});
+
+describe('metric 1: shared fixture', () => {
+    test('fixture limits match the codec', () => {
+        expect(FIXTURE.limits).toEqual({
+            max_digits: MAX_DIGITS, max_scale: MAX_SCALE, max_unscaled_bytes: MAX_UNSCALED_BYTES,
+        });
+        expect(CASES.length).toBeGreaterThanOrEqual(12);
+    });
+
+    test.each(CASES.map(c => [c.name, c] as [string, Case]))('%s encodes to wire_hex and decodes exactly', (_name, c) => {
+        const parsed = parseDecimalString(c.string);
+        expect(parsed).toEqual({ unscaled: expectedUnscaled(c.unscaled_hex), scale: c.scale });
+        expect(toCanonicalString(parsed)).toBe(c.canonical);
+
+        const proto = encodeDecimal(parsed);
+        expect(hex(proto.getUnscaledValue_asU8())).toBe(c.unscaled_hex);
+        expect(proto.getScale()).toBe(c.scale);
+        expect(hex(proto.serializeBinary())).toBe(c.wire_hex);
+
+        // The proto alone is enough to decode (metric 3).
+        const decoded = decodeDecimal(DecimalValueProto.deserializeBinary(unhex(c.wire_hex)));
+        expect(decoded).toEqual({ unscaled: expectedUnscaled(c.unscaled_hex), scale: c.scale });
+    });
+
+    const stringErrors: [string, string][] = FIXTURE.string_errors.map((c: { name: string; string: string }) => [c.name, c.string]);
+    test.each(stringErrors)('string error %s is a ModelValidationError', (_name, s) => {
+        expectInvalid(() => parseDecimalString(s));
+        expectInvalid(() => decodeDecimal(new DecimalValueProto().setArbitraryPrecisionValue(s)));
+    });
+
+    const decodeErrors: [string, any][] = FIXTURE.decode_errors.map((c: any) => [c.name, c]);
+    test.each(decodeErrors)('decode error %s is a ModelValidationError', (_name, c) => {
+        const bytes = c.unscaled_hex_repeat
+            ? unhex(c.unscaled_hex_repeat.hex.repeat(c.unscaled_hex_repeat.count))
+            : unhex(c.unscaled_hex);
+        expectInvalid(() => decodeDecimal(new DecimalValueProto().setUnscaledValue(bytes).setScale(c.scale)));
+    });
+
+    test('the 1702-byte case passes the byte check and fails on digits; 1703 fails on bytes', () => {
+        const message = (n: number) => {
+            try {
+                decodeDecimal(new DecimalValueProto().setUnscaledValue(unhex('7f'.repeat(n))));
+            } catch (e) {
+                return (e as Error).message;
+            }
+            return '';
+        };
+        expect(message(1702)).toContain(`more than ${MAX_DIGITS} digits`);
+        expect(message(1703)).toContain('1703-byte');
+    });
+
+    test('the committed decimal.js (what npm publishes) encodes and decodes fixture cases', () => {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const shipped = require(path.join(__dirname, 'decimal.js'));
+        for (const name of ['zero', 'two_pow_127', 'tiny_fraction']) {
+            const c = CASES.find(x => x.name === name)!;
+            const proto: DecimalValueProto = shipped.encodeDecimal(shipped.parseDecimalString(c.string));
+            expect(hex(proto.serializeBinary())).toBe(c.wire_hex);
+            expect(shipped.decodeDecimal(DecimalValueProto.deserializeBinary(unhex(c.wire_hex))))
+                .toEqual({ unscaled: expectedUnscaled(c.unscaled_hex), scale: c.scale });
+        }
+    });
+
+    test('compact form wins over a conflicting string and does not warn', () => {
+        jest.isolateModules(() => {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const codec = require('./decimal');
+            const warn = jest.fn();
+            codec.setDecimalLogger({ warn });
+            const proto = new DecimalValueProto()
+                .setArbitraryPrecisionValue('9')
+                .setUnscaledValue(unhex('0096'))
+                .setScale(2);
+            expect(codec.toCanonicalString(codec.decodeDecimal(proto))).toBe('1.50');
+            expect(warn).not.toHaveBeenCalled();
+        });
+    });
+
+    test('negative zero from decimal.js encodes to 0x00 at scale 0', () => {
+        const v = fromDecimalJs(new Decimal('-0'));
+        expect(v).toEqual({ unscaled: BigInt(0), scale: 0 });
+        const proto = encodeDecimal(v);
+        expect(hex(proto.getUnscaledValue_asU8())).toBe('00');
+        expect(proto.getScale()).toBe(0);
+        expect(proto.getArbitraryPrecisionValue()).toBe('0');
+    });
+});
+
+describe('metric 3: decodeDecimal takes the proto only', () => {
+    test('a type or field argument does not type-check', () => {
+        const p = encodeDecimal(parseDecimalString('1.50'));
+        // ts-jest type-checks this file: an unused @ts-expect-error fails it.
+        const typeChecked = () => {
+            // @ts-expect-error decodeDecimal takes no type argument
+            decodeDecimal<number>(p);
+            // @ts-expect-error decodeDecimal takes no field argument
+            decodeDecimal(p, 'price');
+        };
+        expect(typeof typeChecked).toBe('function');
+        expect(decodeDecimal.length).toBe(1);
+    });
+
+    test('withField names the field on a codec error', () => {
+        try {
+            withField('price', () => decodeDecimal(new DecimalValueProto()));
+            throw new Error('expected a ModelValidationError');
+        } catch (e) {
+            expect(e).toBeInstanceOf(ModelValidationError);
+            expect((e as ModelValidationError).field).toBe('price');
+        }
+    });
+});
+
+describe('metric 4: one deprecation warning per process', () => {
+    test('a compact-only decode does not warn', () => {
+        jest.isolateModules(() => {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const codec = require('./decimal');
+            const warn = jest.fn();
+            codec.setDecimalLogger({ warn });
+            for (const c of CASES) codec.decodeDecimal(compactOnly(c));
+            expect(warn).toHaveBeenCalledTimes(0);
+        });
+    });
+
+    test('three string-only prices read through the Price wrapper warn exactly once', () => {
+        jest.isolateModules(() => {
+            // The same isolated registry: Price loads this codec instance.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const codec = require('./decimal');
+            const warn = jest.fn();
+            codec.setDecimalLogger({ warn });
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { PriceProto } = require('../../../fintekkers/models/price/price_pb');
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const Price = require('../price/Price').default;
+            const values = ['100.25', '-0.50', '1E+3'];
+            const read = values.map(s => new Price(
+                new PriceProto().setPrice(new DecimalValueProto().setArbitraryPrecisionValue(s))).getPrice());
+            expect(read.map((d: Decimal) => d.toString())).toEqual(['100.25', '-0.5', '1000']);
+            expect(warn).toHaveBeenCalledTimes(1);
+            expect(warn.mock.calls[0][0]).toContain('arbitrary_precision_value');
+        });
+    });
+});
+
+describe('metric 5: writers set both forms', () => {
+    test.each(CASES.map(c => [c.name, c] as [string, Case]))('%s: both forms are set and decode equal', (_name, c) => {
+        const proto = encodeDecimal(parseDecimalString(c.string));
+        expect(proto.getArbitraryPrecisionValue()).toBe(c.canonical);
+        expect(proto.getUnscaledValue_asU8().length).toBeGreaterThan(0);
+
+        const stringOnly = new DecimalValueProto().setArbitraryPrecisionValue(proto.getArbitraryPrecisionValue());
+        const compact = new DecimalValueProto()
+            .setUnscaledValue(proto.getUnscaledValue_asU8())
+            .setScale(proto.getScale());
+        const expected: CompactDecimal = { unscaled: expectedUnscaled(c.unscaled_hex), scale: c.scale };
+        expect(decodeDecimal(stringOnly)).toEqual(expected);
+        expect(decodeDecimal(compact)).toEqual(expected);
+    });
+});
+
+describe('guardrail: lossless', () => {
+    const NODE = path.join(__dirname, '../../..');
+    const SCANNED = [
+        'wrappers/models/utils/decimal.ts',
+        'wrappers/models/utils/serialization.ts',
+        'wrappers/models/price/Price.ts',
+        'wrappers/models/price/price_rules.ts',
+        'wrappers/models/transaction/transaction.ts',
+        'wrappers/models/security/BondSecurity.ts',
+        'wrappers/models/security/Issuance.ts',
+        'wrappers/models/security/MortgageBackedSecurity.ts',
+        'wrappers/models/security/TIPSBond.ts',
+        'wrappers/models/security/FloatingRateNote.ts',
+        'wrappers/models/security/security_rules.ts',
+    ];
+
+    test.each(SCANNED)('%s has no float conversion on the decimal path', (file) => {
+        const lines = fs.readFileSync(path.join(NODE, file), 'utf8').split('\n');
+        const allowed: number[] = [];
+        lines.forEach((line, n) => {
+            // Comment lines don't count.
+            const code = /^\s*(\*|\/\*)/.test(line) ? '' : line.split('//')[0];
+            expect({ file, line: n + 1, code, banned: /parseFloat|parseInt|\.toNumber\(/.test(code) })
+                .toEqual({ file, line: n + 1, code, banned: false });
+            if (/\bNumber\(/.test(code)) allowed.push(n + 1);
+        });
+        // The one documented, range-checked conversion in smallInt().
+        const expectedNumberCalls = file.endsWith('utils/decimal.ts') ? 1 : 0;
+        expect(allowed.length).toBe(expectedNumberCalls);
+        if (expectedNumberCalls) expect(lines[allowed[0] - 1]).toContain('lossless-allow');
+    });
+
+    test('serialize(number) accepts only safe integers', () => {
+        expectInvalid(() => ProtoSerializationUtil.serialize(0.1));
+        expectInvalid(() => ProtoSerializationUtil.serialize(2 ** 53));
+        const proto = ProtoSerializationUtil.serialize(42) as DecimalValueProto;
+        expect(proto.getArbitraryPrecisionValue()).toBe('42');
+        expect(hex(proto.getUnscaledValue_asU8())).toBe('2a');
+        expect(proto.getScale()).toBe(0);
+    });
+
+    test('serialize(Decimal) writes both forms; deserialize returns a Decimal', () => {
+        const proto = ProtoSerializationUtil.serialize(new Decimal('-123.45')) as DecimalValueProto;
+        expect(proto.getArbitraryPrecisionValue()).toBe('-123.45');
+        expect(hex(proto.getUnscaledValue_asU8())).toBe('cfc7');
+
+        const big = CASES.find(c => c.name === 'two_pow_127')!;
+        const read = ProtoSerializationUtil.deserialize(compactOnly(big));
+        expect(read).toBeInstanceOf(Decimal);
+        expect((read as Decimal).toFixed()).toBe(big.canonical);
+    });
+
+    test('a value over the limits is an error, never rounded', () => {
+        expectInvalid(() => fromDecimalJs(new Decimal('1e-5000')));
+        expectInvalid(() => fromDecimalJs(new Decimal('1e+5000')));
+        expectInvalid(() => fromDecimalJs(new Decimal(NaN)));
+        expectInvalid(() => encodeDecimal({ unscaled: BigInt(1), scale: 1.5 }));
+    });
+});

package/node/wrappers/models/utils/decimal.ts

@@ -0,0 +1,335 @@
+import { Decimal } from 'decimal.js';
+import { DecimalValueProto } from '../../../fintekkers/models/util/decimal_value_pb';
+import { ModelValidationError, violation } from '../errors';
+
+/**
+ * Codec for `DecimalValueProto` (LM-306, the JS side of LM-294; see
+ * docs/adr/compact_decimal.md and the Rust reference in
+ * ledger-models-rust/fintekkers/wrappers/models/utils/decimal.rs).
+ *
+ * value = unscaled x 10^-scale, where `unscaled_value` (field 11) is a minimal
+ * two's-complement big-endian integer of any size and `scale` is field 12. A
+ * non-empty `unscaled_value` means the compact form is set and it wins.
+ * Otherwise the deprecated `arbitrary_precision_value` string (field 10) is
+ * read, with a warning logged once per process (LM-307).
+ *
+ * Lossless: no binary floating point on any path (no JS `number` value, no
+ * `parseFloat`). A value that cannot be represented exactly is a
+ * `ModelValidationError`, never rounded. The codec does not know which field
+ * it is decoding: a caller that wants the field named wraps the call in
+ * `withField`.
+ *
+ * Stage 1 (until LM-295): writers set both forms, so readers on older
+ * ledger-models keep working. This module is the only code allowed to touch
+ * the deprecated string field.
+ */
+
+/**
+ * Most decimal digits allowed in the unscaled value, and the largest scale.
+ * The same in every language (see the ADR).
+ */
+export const MAX_DIGITS = 4096;
+export const MAX_SCALE = 4096;
+/**
+ * A minimal unscaled_value longer than this always has more than
+ * `MAX_DIGITS` digits, so it is rejected before it is parsed.
+ */
+export const MAX_UNSCALED_BYTES = 1702;
+
+/** The library release that first writes the compact form. */
+const FIRST_COMPACT_RELEASE = 'v0.4.34';
+
+// No bigint literals: tsconfig targets es2016.
+const ZERO = BigInt(0);
+const ONE = BigInt(1);
+const EIGHT = BigInt(8);
+
+/** An exact decimal: `unscaled x 10^-scale`. `scale` is a count, never a value. */
+export interface CompactDecimal {
+    unscaled: bigint;
+    scale: number;
+}
+
+/** Where the once-per-process deprecation warning goes. Defaults to `console`. */
+export interface DecimalLogger {
+    warn(message: string): void;
+}
+
+let logger: DecimalLogger = console;
+let warned = false;
+
+/** Sends the deprecation warning to `l` from now on. Tests use it to spy. */
+export function setDecimalLogger(l: DecimalLogger): void {
+    logger = l;
+}
+
+/** An unlabelled ModelValidationError: the field is empty until `withField` adds it. */
+function invalid(message: string): ModelValidationError {
+    return new ModelValidationError([violation('', undefined, message)]);
+}
+
+/**
+ * Runs `fn`, labelling any ModelValidationError it throws with `field` (for
+ * example `price`). Violations that already name a field get it as a prefix.
+ */
+export function withField<T>(field: string, fn: () => T): T {
+    try {
+        return fn();
+    } catch (e) {
+        if (!(e instanceof ModelValidationError)) throw e;
+        throw new ModelValidationError(e.violations.map(v => {
+            const labelled = v.clone();
+            labelled.setField(v.getField() ? `${field}.${v.getField()}` : field);
+            return labelled;
+        }));
+    }
+}
+
+/** At most the first 64 characters of `s`, for error messages. */
+function preview(s: string): string {
+    return JSON.stringify(s.slice(0, 64));
+}
+
+function overCap(s: string): ModelValidationError {
+    return invalid(`decimal is over the limit of ${MAX_DIGITS} digits or scale ${MAX_SCALE}: ${preview(s)}`);
+}
+
+/**
+ * The only conversion from bigint to a JS number: `b` must already be
+ * range-checked against MAX_DIGITS / MAX_SCALE, so it is a small integer and
+ * the conversion is exact.
+ */
+function smallInt(b: bigint): number {
+    const limit = BigInt(Math.max(MAX_DIGITS, MAX_SCALE));
+    if (b < -limit || b > limit) {
+        throw invalid(`decimal count ${b} is outside the limits`);
+    }
+    return Number(b); // lossless-allow: range-checked above, |b| <= 4096
+}
+
+function isDigit(c: string | undefined): boolean {
+    return c !== undefined && c >= '0' && c <= '9';
+}
+
+/**
+ * Parses a decimal string, as written to `arbitrary_precision_value`.
+ *
+ * Grammar: `[+-]? (digits [. digits?] | . digits) ([eE] [+-]? digits)?`. No
+ * whitespace, no `NaN` or `Infinity`. The exponent is folded into the scale;
+ * a negative scale becomes scale 0 (`1E+3` is unscaled 1000, scale 0).
+ * Trailing zeros are kept: `1.50` is unscaled 150, scale 2. Anything else, or
+ * a result over `MAX_DIGITS` / `MAX_SCALE`, is a ModelValidationError.
+ */
+export function parseDecimalString(s: string): CompactDecimal {
+    const notADecimal = () => invalid(`decimal is not a finite decimal: ${preview(s)}`);
+    let i = 0;
+    let negative = false;
+    if (s[0] === '-' || s[0] === '+') {
+        negative = s[0] === '-';
+        i = 1;
+    }
+    const intStart = i;
+    while (isDigit(s[i])) i++;
+    const intDigits = s.slice(intStart, i);
+    let fracDigits = '';
+    if (s[i] === '.') {
+        i++;
+        const fracStart = i;
+        while (isDigit(s[i])) i++;
+        fracDigits = s.slice(fracStart, i);
+    }
+    if (intDigits === '' && fracDigits === '') throw notADecimal();
+    let exponent = ZERO;
+    if (s[i] === 'e' || s[i] === 'E') {
+        i++;
+        let expNegative = false;
+        if (s[i] === '-' || s[i] === '+') {
+            expNegative = s[i] === '-';
+            i++;
+        }
+        const expStart = i;
+        while (isDigit(s[i])) i++;
+        if (i === expStart) throw notADecimal();
+        const expDigits = s.slice(expStart, i).replace(/^0+/, '');
+        // Any exponent this long is far past the caps below.
+        if (expDigits.length > 12) throw overCap(s);
+        const magnitude = expDigits === '' ? ZERO : BigInt(expDigits);
+        exponent = expNegative ? -magnitude : magnitude;
+    }
+    if (i !== s.length) throw notADecimal();
+
+    const significant = (intDigits + fracDigits).replace(/^0+/, '');
+    const scale = BigInt(fracDigits.length) - exponent;
+    if (significant === '') {
+        // Zero has no sign and keeps its scale (`0.00` is scale 2); `0E+3` is scale 0.
+        const zeroScale = scale < ZERO ? ZERO : scale;
+        if (zeroScale > BigInt(MAX_SCALE)) throw overCap(s);
+        return { unscaled: ZERO, scale: smallInt(zeroScale) };
+    }
+    const zerosToAppend = scale < ZERO ? -scale : ZERO;
+    if (scale > BigInt(MAX_SCALE) || BigInt(significant.length) + zerosToAppend > BigInt(MAX_DIGITS)) {
+        throw overCap(s);
+    }
+    const magnitude = BigInt(significant + '0'.repeat(smallInt(zerosToAppend)));
+    return {
+        unscaled: negative ? -magnitude : magnitude,
+        scale: smallInt(scale < ZERO ? ZERO : scale),
+    };
+}
+
+/** Plain notation, never an exponent, keeping trailing zeros: unscaled 150 scale 2 is `1.50`. */
+export function toCanonicalString(v: CompactDecimal): string {
+    const negative = v.unscaled < ZERO;
+    const digits = (negative ? -v.unscaled : v.unscaled).toString();
+    const sign = negative ? '-' : '';
+    if (v.scale === 0) return sign + digits;
+    if (digits.length > v.scale) {
+        return `${sign}${digits.slice(0, digits.length - v.scale)}.${digits.slice(digits.length - v.scale)}`;
+    }
+    return `${sign}0.${'0'.repeat(v.scale - digits.length)}${digits}`;
+}
+
+/** Minimal two's-complement big-endian bytes. Zero is the single byte 0x00. */
+function bigIntToBytes(n: bigint): Uint8Array {
+    let hex: string;
+    if (n >= ZERO) {
+        hex = n.toString(16);
+        if (hex.length % 2 === 1) hex = '0' + hex;
+        // A leading byte >= 0x80 would read back as negative.
+        if (/^[89a-f]/.test(hex)) hex = '00' + hex;
+    } else {
+        const magnitude = -n;
+        let length = (magnitude.toString(16).length + 1) >> 1;
+        // The most negative value in `length` bytes is -(2^(8*length - 1)).
+        if (magnitude > ONE << (BigInt(length) * EIGHT - ONE)) length++;
+        hex = ((ONE << (BigInt(length) * EIGHT)) + n).toString(16);
+        hex = '0'.repeat(length * 2 - hex.length) + hex;
+    }
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = (hexValue(hex[2 * i]) << 4) | hexValue(hex[2 * i + 1]);
+    }
+    return out;
+}
+
+function hexValue(c: string): number {
+    return '0123456789abcdef'.indexOf(c);
+}
+
+/** Reads two's-complement big-endian bytes of any length; non-minimal input is fine. */
+function bytesToBigInt(bytes: Uint8Array): bigint {
+    if (bytes.length === 0) return ZERO;
+    let hex = '';
+    for (const b of bytes) hex += (b < 16 ? '0' : '') + b.toString(16);
+    const unsigned = BigInt('0x' + hex);
+    return bytes[0] & 0x80 ? unsigned - (ONE << (BigInt(bytes.length) * EIGHT)) : unsigned;
+}
+
+/**
+ * Decodes the compact form (fields 11 and 12). Rejects a scale over
+ * `MAX_SCALE`, then bytes over `MAX_UNSCALED_BYTES`, then more than
+ * `MAX_DIGITS` digits, before any large allocation (the same order as Rust).
+ */
+function decodeCompact(unscaledValue: Uint8Array, scale: number): CompactDecimal {
+    if (scale > MAX_SCALE) {
+        throw invalid(`decimal has scale ${scale}, over the limit of ${MAX_SCALE}`);
+    }
+    if (unscaledValue.length > MAX_UNSCALED_BYTES) {
+        throw invalid(`decimal has a ${unscaledValue.length}-byte unscaled_value, over the limit of ${MAX_UNSCALED_BYTES} bytes`);
+    }
+    const unscaled = bytesToBigInt(unscaledValue);
+    if ((unscaled < ZERO ? -unscaled : unscaled).toString().length > MAX_DIGITS) {
+        throw invalid(`decimal has more than ${MAX_DIGITS} digits`);
+    }
+    return { unscaled, scale };
+}
+
+/** True when neither form is set: `unscaled_value` and `arbitrary_precision_value` are both empty. */
+export function isUnsetDecimal(p: DecimalValueProto): boolean {
+    return p.getUnscaledValue_asU8().length === 0 && p.getArbitraryPrecisionValue() === '';
+}
+
+/**
+ * Decodes a `DecimalValueProto`. The compact form wins when set. Otherwise
+ * falls back to the deprecated string and logs a deprecation warning, once
+ * per process. Both forms empty is a ModelValidationError; so is a malformed
+ * or over-cap value. Takes the proto only (owner ruling, 12 Oct): label
+ * errors with `withField`.
+ */
+export function decodeDecimal(p: DecimalValueProto): CompactDecimal {
+    const unscaledValue = p.getUnscaledValue_asU8();
+    if (unscaledValue.length > 0) {
+        return decodeCompact(unscaledValue, p.getScale());
+    }
+    const legacy = p.getArbitraryPrecisionValue();
+    if (legacy === '') {
+        throw invalid('decimal is required but unset');
+    }
+    emitDeprecation();
+    return parseDecimalString(legacy);
+}
+
+/**
+ * Encodes both forms (stage 1): fields 11 and 12, plus the canonical string
+ * in field 10 for readers on ledger-models older than v0.4.34.
+ */
+export function encodeDecimal(v: CompactDecimal): DecimalValueProto {
+    if (typeof v.unscaled !== 'bigint') {
+        throw invalid('decimal unscaled value must be a bigint');
+    }
+    if (!Number.isInteger(v.scale) || v.scale < 0 || v.scale > MAX_SCALE) {
+        throw invalid(`decimal scale must be an integer from 0 to ${MAX_SCALE}: ${v.scale}`);
+    }
+    return new DecimalValueProto()
+        .setArbitraryPrecisionValue(toCanonicalString(v))
+        .setUnscaledValue(bigIntToBytes(v.unscaled))
+        .setScale(v.scale);
+}
+
+/**
+ * `p` rewritten in both forms (stage 1), keeping its value and scale. Used
+ * when re-saving a message loaded from older bytes.
+ */
+export function reencodeDecimal(p: DecimalValueProto): DecimalValueProto {
+    return encodeDecimal(decodeDecimal(p));
+}
+
+/**
+ * The value as a decimal.js `Decimal`, built from the canonical string. The
+ * `Decimal` constructor is exact and ignores the global `precision`. A
+ * `Decimal` does not keep trailing zeros, so `1.50` reads back as `1.5`.
+ */
+export function toDecimalJs(v: CompactDecimal): Decimal {
+    return new Decimal(toCanonicalString(v));
+}
+
+/**
+ * The exact value of a decimal.js `Decimal`, from `toFixed()`, which never
+ * rounds when given no argument. A `Decimal` does not keep trailing zeros, so
+ * `new Decimal('1.50')` becomes scale 1: callers that need scale 2 use
+ * `parseDecimalString('1.50')`. Negative zero becomes 0. NaN, Infinity and
+ * values over the limits are a ModelValidationError.
+ */
+export function fromDecimalJs(d: Decimal): CompactDecimal {
+    if (!d.isFinite()) {
+        throw invalid(`decimal is not a finite decimal: ${d.toString()}`);
+    }
+    // Checked before toFixed(), which would write every digit out.
+    if (d.e >= MAX_DIGITS || d.decimalPlaces() > MAX_SCALE) {
+        throw overCap(d.toString());
+    }
+    return parseDecimalString(d.toFixed());
+}
+
+/**
+ * Logs that a decimal was read from the deprecated string, the first time
+ * only in this process.
+ */
+function emitDeprecation(): void {
+    if (warned) return;
+    warned = true;
+    logger.warn(
+        'DecimalValueProto read from deprecated arbitrary_precision_value; '
+        + `writer predates ledger-models ${FIRST_COMPACT_RELEASE}`
+    );
+}

package/node/wrappers/models/utils/decimal.typings.test.d.ts

@@ -0,0 +1 @@
+export {};

package/node/wrappers/models/utils/decimal.typings.test.js

@@ -0,0 +1,39 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Metric 4 (LM-306): the published typings mark the deprecated string
+ * accessors. compile.sh adds the tags after protoc-gen-ts runs.
+ */
+const TYPINGS = path.join(__dirname, '../../../fintekkers/models/util/decimal_value_pb.d.ts');
+test.each(['getArbitraryPrecisionValue', 'setArbitraryPrecisionValue'])('%s is @deprecated', (accessor) => {
+    const lines = fs.readFileSync(TYPINGS, 'utf8').split('\n');
+    const at = lines.findIndex(l => l.trim().startsWith(`${accessor}(`));
+    expect(at).toBeGreaterThan(0);
+    expect(lines[at - 1].trim()).toMatch(/^\/\*\* @deprecated .*\*\/$/);
+});
+//# sourceMappingURL=decimal.typings.test.js.map

package/node/wrappers/models/utils/decimal.typings.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decimal.typings.test.js","sourceRoot":"","sources":["decimal.typings.test.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uCAAyB;AACzB,2CAA6B;AAE7B;;;GAGG;AAEH,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,uDAAuD,CAAC,CAAC;AAE9F,IAAI,CAAC,IAAI,CAAC,CAAC,4BAA4B,EAAE,4BAA4B,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC,QAAQ,EAAE,EAAE;IACtG,MAAM,KAAK,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3D,MAAM,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC;IACrE,MAAM,CAAC,EAAE,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAC9B,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,6BAA6B,CAAC,CAAC;AACxE,CAAC,CAAC,CAAC"}

package/node/wrappers/models/utils/decimal.typings.test.ts

@@ -0,0 +1,16 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Metric 4 (LM-306): the published typings mark the deprecated string
+ * accessors. compile.sh adds the tags after protoc-gen-ts runs.
+ */
+
+const TYPINGS = path.join(__dirname, '../../../fintekkers/models/util/decimal_value_pb.d.ts');
+
+test.each(['getArbitraryPrecisionValue', 'setArbitraryPrecisionValue'])('%s is @deprecated', (accessor) => {
+    const lines = fs.readFileSync(TYPINGS, 'utf8').split('\n');
+    const at = lines.findIndex(l => l.trim().startsWith(`${accessor}(`));
+    expect(at).toBeGreaterThan(0);
+    expect(lines[at - 1].trim()).toMatch(/^\/\*\* @deprecated .*\*\/$/);
+});

package/node/wrappers/models/utils/serialization.d.ts

@@ -9,7 +9,8 @@ import { ProtoEnum } from "./protoEnum";
 import { UUID } from "./uuid";
 import { StringValue } from 'google-protobuf/google/protobuf/wrappers_pb';
 import { Identifier } from "../security/identifier";
+import { Decimal } from "decimal.js";
 export declare class ProtoSerializationUtil {
     static serialize(obj: any): UUIDProto | LocalDateProto | LocalTimestampProto | DecimalValueProto | StringValue | IdentifierProto;
-    static deserialize(obj: any): UUID | Date | ZonedDateTime | Identifier | string | number | ProtoEnum | StrategyAllocationProto;
+    static deserialize(obj: any): UUID | Date | ZonedDateTime | Identifier | string | Decimal | ProtoEnum | StrategyAllocationProto;
 }