How do I use FixedNumber.fromValue?

[PaulRBerg]

While working with FixedNumber, I got this error after setting the number of decimals to 77:

fractional component exceeds decimals (fault="underflow", operation="parseFixed", code=NUMERIC_FAULT, version=bignumber/5.4.2)

Here's my code:

const foo = "115792089237316195423570985008687907853269984665640564039457584007913129639935";
const decimals = 77;
const result = FixedNumber.fromValue(foo, decimals);
console.log(result.toString());

I then peaked into the guts of the FixedNumber implementation, and noticed that the number of decimals gets overridden to 18 in this function:

ethers.js/packages/bignumber/src.ts/fixednumber.ts

Lines 342 to 364 in 4166b27

	static fromString(value: string, format?: FixedFormat | string | number): FixedNumber {
	if (format == null) { format = "fixed"; }
	const fixedFormat = FixedFormat.from(format);
	const numeric = parseFixed(value, fixedFormat.decimals);
	if (!fixedFormat.signed && numeric.lt(Zero)) {
	throwFault("unsigned value cannot be negative", "overflow", "value", value);
	}
	let hex: string = null;
	if (fixedFormat.signed) {
	hex = numeric.toTwos(fixedFormat.width).toHexString();
	} else {
	hex = numeric.toHexString();
	hex = hexZeroPad(hex, fixedFormat.width / 8);
	}
	const decimal = formatFixed(numeric, fixedFormat.decimals);
	return new FixedNumber(_constructorGuard, hex, decimal, fixedFormat);
	}

That is, even if it's 77 when it enters the fromValue function, it gets set to 18 by the time it is used in fromString.

My request is to document the maximum number of decimals that can be set when working with FixedNumber, plus any other constraints that there might be.

[PaulRBerg]

If the maximum number of decimals is allowed is 18, then I think users should not even be allowed to pass anything greater than that to fromValue.

Update: I've just seen this mentioned in the docs:

and the number of decimals must be no larger than 80

So this is documented. But I will keep this issue open because there might be a bug on these lines:

ethers.js/packages/bignumber/src.ts/fixednumber.ts

Lines 335 to 338 in 4166b27

	if (decimals == null) { decimals = 0; }
	if (format == null) { format = "fixed"; }
	return FixedNumber.fromString(formatFixed(value, decimals), FixedFormat.from(format));

The format that gets created does not take into account the decimals, thus it gets set to 18.

Update 2: The bug does not occur if the number has trailing zeros instead of non-zero decimals:

const foo = "280000000000000000000000000000000000000000000000000000000000000000000000000000";
const decimals = 77;
const result = FixedNumber.fromValue(foo, decimals);
console.log(result.toString()); // prints 2.8

[PaulRBerg]

I went around the bug by explicitly setting the format when calling fromValue:

const result = FixedNumber.fromValue(foo, decimals, "fixed256x77");

Mystery solved. When we pass a number of decimals that is larger than 18 and we don't set the format, the fromValue function assumes the standard format fixed128x18.

[ricmoo]

I think there is some confusion as to what the decimals and format mean.

The decimals indicates the number of decimals to assume the input value is operating under. For example, "10" with 0 decimals is 10, while "10" with 2 decimals is 0.1. It only impacts the interpretation of the value.

The format parameter indicates the internal representation used during fixed-point mathematical operations.

So, the default decimals of 0 and the default format of fixed128x18 indicates that whatever value is passed in should be taken literally and that 18 decimal places are used during maths.

So, the value "123" is represented internally as 123.000_000_000_000_000_000 (underscores added for readability).

Using a value "123" with a decimals of 2 and the default format is represented internally as 1.230_000_000_000_000_000.

Does that make sense?

[PaulRBerg]

It does. Thanks a lot for explaining!

[ricmoo]

Just discussing this with my partner, and this example came up, which might help explain where the logic and names stem from.

const balance = await erc20Contract.getBalance(someAddr);
const decimals = await erc20Contract.decimals();

const value = FixedNumber.fromValue(balance, decimals);

Hopefully that helps future peeps who happen across this issue too. :)