Onchain.Address (onchain v0.5.0)

Ethereum address validation, checksumming, and comparison.

Curated 7-function API wrapping Signet.Hex and Signet.Util with flexible input handling (hex strings or 20-byte binaries) and normalized error tuples.

Error Format

All failable functions return {:error, {:invalid_address, input}} where input is the original value that failed validation. Bang variants raise Signet.Hex.HexError.

Functions

Function	Purpose
`validate/1`	Any input → 20-byte binary
`valid?/1`	Check if input is a valid address
`checksum/1`	EIP-55 checksummed hex string
`checksum!/1`	EIP-55 checksummed hex string (raises)
`normalize/1`	Lowercase 0x-prefixed hex string
`equal?/2`	Compare two addresses (any format)
`zero?/1`	Check if address is the zero address

API Functions

Function	Arity	Description	Param Kinds
`zero?`	1	Check if an address is the zero address (0x0000...0000).	`input: value`
`equal?`	2	Compare two addresses for equality, regardless of format.	`a: value`, `b: value`
`normalize`	1	Return a lowercase 0x-prefixed hex string for an address.	`input: value`
`checksum!`	1	Return the EIP-55 checksummed hex string. Raises on invalid input.	`input: value`
`checksum`	1	Return the EIP-55 checksummed hex string for an address.	`input: value`
`valid?`	1	Check whether the input is a valid Ethereum address.	`input: value`
`validate`	1	Validate and normalize an address to a 20-byte binary.	`input: value`

Summary

Functions

checksum(input)

Return the EIP-55 checksummed hex string for an address.

checksum!(input)

Return the EIP-55 checksummed hex string. Raises on invalid input.

equal?(a, b)

Compare two addresses for equality, regardless of format.

normalize(input)

Return a lowercase 0x-prefixed hex string for an address.

valid?(input)

Check whether the input is a valid Ethereum address.

validate(input)

Validate and normalize an address to a 20-byte binary.

zero?(input)

Check if an address is the zero address (0x0000...0000).

Functions

checksum(input)

@spec checksum(term()) :: {:ok, String.t()} | {:error, {:invalid_address, term()}}

Return the EIP-55 checksummed hex string for an address.

Parameters

input - Hex string (with or without 0x) or 20-byte binary (value)

Returns

EIP-55 checksummed address ({:ok, String.t()} | {:error, {:invalid_address, input}})

# descripex:contract
%{
  params: %{
    input: %{
      description: "Hex string (with or without 0x) or 20-byte binary",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, String.t()} | {:error, {:invalid_address, input}}",
    description: "EIP-55 checksummed address",
    example: "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
  }
}

checksum!(input)

@spec checksum!(term()) :: String.t()

Return the EIP-55 checksummed hex string. Raises on invalid input.

Parameters

input - Hex string (with or without 0x) or 20-byte binary (value)

Returns

EIP-55 checksummed address (string)

# descripex:contract
%{
  params: %{
    input: %{
      description: "Hex string (with or without 0x) or 20-byte binary",
      kind: :value
    }
  },
  returns: %{
    type: :string,
    description: "EIP-55 checksummed address",
    example: "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed"
  }
}

equal?(a, b)

@spec equal?(term(), term()) :: boolean()

Compare two addresses for equality, regardless of format.

Parameters

a - First address (hex string or 20-byte binary) (value)
b - Second address (hex string or 20-byte binary) (value)

Returns

true if both resolve to the same 20-byte address (boolean)

# descripex:contract
%{
  params: %{
    b: %{
      description: "Second address (hex string or 20-byte binary)",
      kind: :value
    },
    a: %{
      description: "First address (hex string or 20-byte binary)",
      kind: :value
    }
  },
  returns: %{
    type: :boolean,
    description: "true if both resolve to the same 20-byte address"
  }
}

normalize(input)

@spec normalize(term()) :: {:ok, String.t()} | {:error, {:invalid_address, term()}}

Return a lowercase 0x-prefixed hex string for an address.

Parameters

input - Hex string (with or without 0x) or 20-byte binary (value)

Returns

Lowercase hex address ({:ok, String.t()} | {:error, {:invalid_address, input}})

# descripex:contract
%{
  params: %{
    input: %{
      description: "Hex string (with or without 0x) or 20-byte binary",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, String.t()} | {:error, {:invalid_address, input}}",
    description: "Lowercase hex address",
    example: "0x5aaeb6053f3e94c9b9a09f33669435e7ef1beaed"
  }
}

valid?(input)

@spec valid?(term()) :: boolean()

Check whether the input is a valid Ethereum address.

Parameters

input - Value to check (value)

Returns

true if valid 20-byte address (boolean)

# descripex:contract
%{
  params: %{input: %{description: "Value to check", kind: :value}},
  returns: %{type: :boolean, description: "true if valid 20-byte address"}
}

validate(input)

@spec validate(term()) :: {:ok, <<_::160>>} | {:error, {:invalid_address, term()}}

Validate and normalize an address to a 20-byte binary.

Parameters

input - Hex string (with or without 0x) or 20-byte binary (value)

Returns

Validated 20-byte binary address ({:ok, <<20 bytes>>} | {:error, {:invalid_address, input}})

# descripex:contract
%{
  params: %{
    input: %{
      description: "Hex string (with or without 0x) or 20-byte binary",
      kind: :value
    }
  },
  returns: %{
    type: "{:ok, <<20 bytes>>} | {:error, {:invalid_address, input}}",
    description: "Validated 20-byte binary address"
  }
}

zero?(input)

@spec zero?(term()) :: boolean()

Check if an address is the zero address (0x0000...0000).

Parameters

input - Hex string or 20-byte binary (value)

Returns

true if the zero address (boolean)

# descripex:contract
%{
  params: %{input: %{description: "Hex string or 20-byte binary", kind: :value}},
  returns: %{type: :boolean, description: "true if the zero address"}
}