Fuels-ts

Appearance

Unit conversion ​

Internally, we use Arbitrary-precision arithmetic (also known as Big Number arithmetic) to allow for the handling of large numbers and different assets.

On the Fuel network, we work with 9 decimals to represent amounts under a unit. This differs from chain to chain, so it is important to know the number of decimals used on the chain you are working with.

Note: The package @fuels/assets provides a list of assets and their decimals.

Below we will go over some common use cases for unit conversion.

Using our BN class we can instantiate these numbers.

ts
import { BN } from 'fuels';

const result = new BN('100000000').toString();
// "100000000"
See code in context

Or using our bn utility function.

ts
import { bn } from 'fuels';

const result = bn('100000000').toString();
// "100000000"
See code in context

Contract calls ​

Generally, we will need to convert u64 and u256 numbers to a BN object when passing them to a Sway program from JavaScript. More information on this can be found here.

ts
const MAX_U64 = bn('18446744073709551615');

const { waitForResult } = await contract.functions.echo_u64(MAX_U64).call();
const { value } = await waitForResult();

value.toString();
// "18446744073709551615"
See code in context

Note: If a contract call returns a number that is too large to be represented as a JavaScript number, you can convert it to a string using the toString method instead of toNumber.

Parsing ​

Parsing string-represented numbers (from user input) has never been easier, than using the parseUnits function.

ts
const result = bn.parseUnits('0.000000001').toString();
// "1"
See code in context

We can parse large numbers.

ts
const result = bn.parseUnits('100100').toString();
// "100100000000000"
See code in context

Or numbers formatted for human readability.

ts
const result = bn.parseUnits('100,100.000200001').toString();
// "100100000200001"
See code in context

We can also parse numbers in other units of measure.

ts
import { DECIMAL_GWEI, bn } from 'fuels';

const result = bn.parseUnits('1', DECIMAL_GWEI).toString();
// "1000000000"
See code in context

Formatting ​

We can format common units of measure using the format function.

In the following example, we format a BigNumber representation of one Gwei, into units for the Fuel network (with 3 decimal place precision).

ts
const oneGwei = bn('1000000000');

const result = oneGwei.format();
// "1.000"
See code in context

We can also format numbers in other units of measure by specifying the units variable.

ts
import { DECIMAL_GWEI, bn } from 'fuels';

const twoGwei = bn('2000000000');

const result = twoGwei.format({ units: DECIMAL_GWEI });
// "2.000"
See code in context

A precision variable will allow for the formatting of numbers with a specific number of decimal places.

ts
const oneGwei = bn('1000000000');

const result = oneGwei.format({ precision: 1 });
// "1.0"
See code in context

Format units ​

The formatUnits function is a lesser alternative to the format function, as it will maintain the same precision as the input value.

ts
const oneGwei = bn('1000000000');

const result = oneGwei.formatUnits();
// "1.000000000"
See code in context

We can also format numbers in other units of measure by specifying the units variable.

ts
import { DECIMAL_KWEI, bn } from 'fuels';

const oneKwei = bn('1000000000000000');

const result = oneKwei.formatUnits(DECIMAL_KWEI);
// "1.000000000000000"
See code in context

See also ​