Onchain.Decimal (onchain v0.5.0)

Decimal precision helpers for Ethereum token amounts.

Ethereum stores token amounts as raw integers with a separate decimal count (18 for ETH, 6 for USDC, 8 for WBTC). This module converts between raw integers and Decimal.t() values.

All functions are pure math with guards — they cannot fail with valid input types, so there are no error tuples or bang variants.

Functions

Function	Purpose
`to_decimal/2`	Raw integer + decimal places → `Decimal.t()`
`div_pow10/2`	Value / 10^n → `Decimal.t()` (general math op)
`to_basis_points/1`	Decimal ratio → integer basis points

API Functions

Function	Arity	Description	Param Kinds
`to_basis_points`	1	Convert a decimal ratio to integer basis points (truncated toward zero).	`ratio: value`
`div_pow10`	2	Divide a value by 10^n. General-purpose power-of-10 division.	`value: value`, `n: value`
`to_decimal`	2	Convert a raw token integer to a Decimal with the given decimal places.	`value: value`, `decimals: value`

Summary

Functions

div_pow10(value, n)

Divide a value by 10^n. General-purpose power-of-10 division.

to_basis_points(ratio)

Convert a decimal ratio to integer basis points (truncated toward zero).

to_decimal(value, decimals)

Convert a raw token integer to a Decimal with the given decimal places.

Functions

div_pow10(value, n)

@spec div_pow10(integer() | Decimal.t(), non_neg_integer()) :: Decimal.t()

Divide a value by 10^n. General-purpose power-of-10 division.

Parameters

value - Integer or Decimal value to divide (value)
n - Power of 10 to divide by (value)

Returns

Result of value / 10^n (Decimal.t())

# descripex:contract
%{
  params: %{
    value: %{description: "Integer or Decimal value to divide", kind: :value},
    n: %{description: "Power of 10 to divide by", kind: :value}
  },
  returns: %{type: "Decimal.t()", description: "Result of value / 10^n"}
}

to_basis_points(ratio)

@spec to_basis_points(Decimal.t()) :: integer()

Convert a decimal ratio to integer basis points (truncated toward zero).

Parameters

ratio - Decimal ratio (e.g. Decimal.new("0.005") for 50 basis points) (value)

Returns

Basis points as integer (1 bp = 0.0001) (integer)

# descripex:contract
%{
  params: %{
    ratio: %{
      description: "Decimal ratio (e.g. Decimal.new(\"0.005\") for 50 basis points)",
      kind: :value
    }
  },
  returns: %{
    type: :integer,
    description: "Basis points as integer (1 bp = 0.0001)",
    example: "50 for a 0.5% rate"
  }
}

to_decimal(value, decimals)

@spec to_decimal(integer(), non_neg_integer()) :: Decimal.t()

Convert a raw token integer to a Decimal with the given decimal places.

Parameters

value - Raw integer token amount (e.g. wei for ETH) (value)
decimals - Number of decimal places for the token (18 for ETH, 6 for USDC, 8 for WBTC) (value)

Returns

Human-readable token amount (Decimal.t())

# descripex:contract
%{
  params: %{
    decimals: %{
      description: "Number of decimal places for the token (18 for ETH, 6 for USDC, 8 for WBTC)",
      kind: :value
    },
    value: %{
      description: "Raw integer token amount (e.g. wei for ETH)",
      kind: :value
    }
  },
  returns: %{
    type: "Decimal.t()",
    description: "Human-readable token amount",
    example: "Decimal.new(\"1.5\") for 1.5 ETH"
  }
}