# `Cartouche.RecoveryBit`
[🔗](https://github.com/ZenHive/onchain-stack/blob/cartouche-v0.9.1/packages/cartouche/lib/cartouche/recovery_bit.ex#L1)

There are a number of ways to look at recovery bits. Either:

* `:base`: In the range `{0,1}`, which are the outputs of a signer library
* `:ethereum`: In the range `{27,28}`, as defined in the yellow paper
* `:eip155`: In the range `{35+chain_id*2,35+chain_id*2+1}`, as defined in EIP-155

This module provides tools between switching through these choices.

EIP-155 conversion takes an explicit `chain_id`. Omitting it falls back to
`config :cartouche, :chain_id` (via `Cartouche.Chain.chain_id_value/1`). A
signature from a different chain than the one supplied (or configured)
raises `Invalid EIP-155 Signature` naming both `recovery_bit` and `chain_id`.

## API Functions
| Function | Arity | Description | Param Kinds |
| --- | --- | --- | --- |
| `recover_base` | 2 | Convert a recovery bit from any supported convention into base form. | `v: value`, `chain_id: value` |
| `normalize_signature` | 3 | Normalize the recovery bytes of a packed `r <> s <> v` Ethereum signature. | `signature: value`, `rec_type: value`, `chain_id: value` |
| `normalize` | 3 | Convert a recovery bit into the requested recovery-bit convention. | `recovery_bit: value`, `rec_type: value`, `chain_id: value` |

# `rec_type`

```elixir
@type rec_type() :: :base | :ethereum | :eip155
```

# `normalize`

```elixir
@spec normalize(non_neg_integer(), rec_type(), integer() | atom() | nil) ::
  non_neg_integer() | no_return()
```

Normalizes a binary-encoded signature to the given requested type,
i.e. `:base`, `:ethereum`, or `:eip155`.

## Examples

    iex> Cartouche.RecoveryBit.normalize(28, :ethereum)
    28

    iex> Cartouche.RecoveryBit.normalize(1, :ethereum)
    28

    iex> Cartouche.RecoveryBit.normalize(27, :base)
    0

# `normalize_signature`

```elixir
@spec normalize_signature(Cartouche.signature(), rec_type(), integer() | atom() | nil) ::
  Cartouche.signature() | no_return()
```

Normalizes a binary-encoded signature to the given requested type,
i.e. `:base`, `:ethereum`, or `:eip155`.

## Examples

    iex> Cartouche.RecoveryBit.normalize_signature(<<1::256, 2::256, 28>>, :ethereum)
    <<1::256, 2::256, 28>>

    iex> Cartouche.RecoveryBit.normalize_signature(<<1::256, 2::256, 1>>, :ethereum)
    <<1::256, 2::256, 28>>

    iex> Cartouche.RecoveryBit.normalize_signature(<<1::256, 2::256, 27>>, :base)
    <<1::256, 2::256, 0>>

# `recover_base`

```elixir
@spec recover_base(non_neg_integer(), integer() | atom() | nil) :: 0 | 1 | no_return()
```

Normalizes a recovery bit to be either 0 or 1.

EIP-155 values are reduced against `chain_id`. Omitting it falls back to
`config :cartouche, :chain_id`. A `v` from a different chain raises
`Invalid EIP-155 Signature` naming both `recovery_bit` and `chain_id`.

## Examples

    iex> Cartouche.RecoveryBit.recover_base(0)
    0

    iex> Cartouche.RecoveryBit.recover_base(1)
    1

    iex> Cartouche.RecoveryBit.recover_base(27)
    0

    iex> Cartouche.RecoveryBit.recover_base(28)
    1

    iex> Cartouche.RecoveryBit.recover_base(2)
    ** (FunctionClauseError) no function clause matching in Cartouche.RecoveryBit.recover_base/2

---

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