# `Onchain.Decimal`
[🔗](https://github.com/ZenHive/onchain/blob/v0.5.0/lib/onchain/decimal.ex#L1)

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` |

# `div_pow10`

```elixir
@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()`)

```elixir
# 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`

```elixir
@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`)

```elixir
# 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`

```elixir
@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()`)

```elixir
# 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"
  }
}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*