# What Are the Built-In Contracts (BIC) in Amadeus Protocol?

> Discover Amadeus Protocol's built-in contracts (BIC). Learn how BIC.Sol, BIC.SolBloom, and BIC.Coin offer essential on-chain logic for participation validation, bloom filtering, and token accounting.

- Repository: [Amadeus Protocol/node](https://github.com/amadeusprotocol/node)
- Tags: deep-dive
- Published: 2026-08-20

---

**Amadeus Protocol ships with three core built-in contracts—`BIC.Sol`, `BIC.SolBloom`, and `BIC.Coin`—that provide deterministic, non-overridable on-chain logic for proof-of-participation validation, bloom filtering, and native token accounting.**

The Amadeus Protocol node repository (`amadeusprotocol/node`) implements these modules in Elixir under the `ex/lib/bic/` directory. These built-in contracts (BIC) are compiled directly into the node binary, ensuring the consensus layer relies on audited, immutable logic that user-supplied contracts cannot replace.

## BIC.Sol: Solution and Proof-of-Participation Verification

`BIC.Sol` handles **solution** (SOL) objects that contain validator proof-of-participation, computed tensors, and epoch-specific data. According to the `amadeusprotocol/node` source code, this contract parses multiple SOL layouts—including testnet, pre-295, and post-295 formats—and performs size, hash, and Freivalds-based verification.

### Core Functions in BIC.Sol

The module exposes several key functions defined in [`ex/lib/bic/sol.ex`](https://github.com/amadeusprotocol/node/blob/main/ex/lib/bic/sol.ex):

- `size/0` – Returns the expected binary size of a SOL payload.
- `unpack/1` – Deserializes a mainnet SOL binary into its components.
- `unpack_testnet/1` – Parses the legacy testnet SOL layout.
- `verify_hash/2` – Validates the hash of a SOL object against expected parameters.
- `verify_hash_diff/3` – Checks hash differences with configurable difficulty bits.
- `verify/2` – Runs the full verification pipeline, including Freivalds validation.

### SOL Verification Example

To verify a SOL payload on mainnet, pass the binary and an options map containing the segment VR hash and difficulty bits:

```elixir
sol_bin = <<...>>  # binary SOL data received from a peer

opts = %{segment_vr_hash: vr_hash, diff_bits: 8}

{:ok, _} = BIC.Sol.verify(sol_bin, opts)

```

This call returns `{:ok, _}` when the proof-of-participation data, tensor computations, and hash checks all succeed.

## BIC.SolBloom: Bloom Filter Utilities for Segment VR Hashes

`BIC.SolBloom` provides **BLOOM filter utilities** for SOL objects, enabling the node to perform efficient look-ups of segment-VR hashes during the verification flow. The utilities in [`ex/lib/bic/sol_bloom.ex`](https://github.com/amadeusprotocol/node/blob/main/ex/lib/bic/sol_bloom.ex) create and check bloom bits that the consensus engine consumes for security guarantees.

### Bloom Filter API

The module offers a concise API:

- `bloom/1` – Generates a bloom filter from a list of segment VR hashes.
- `check/2` – Tests whether a given hash is present in an existing bloom filter.

### Bloom Filter Example

```elixir
vr_hashes = [<<...>>, <<...>>]
bloom = BIC.SolBloom.bloom(vr_hashes)

```

After creation, the resulting bloom structure supports fast membership checks without requiring full storage of every hash.

## BIC.Coin: Native Token Accounting

`BIC.Coin` implements the **native coin** contract that tracks validator token balances and the protocol’s economic parameters. Located in [`ex/lib/bic/coin.ex`](https://github.com/amadeusprotocol/node/blob/main/ex/lib/bic/coin.ex), this module supplies deterministic helpers for minting, burning, and balance queries used by the node’s accounting layer.

### Accounting Functions

Key functions include:

- `balance/1` – Returns the native token balance for a given public key.
- `mint/2` – Increases the supply and credits a validator.
- `burn/2` – Destroys tokens and debits a validator.
- `total_supply/0` – Returns the current circulating supply.

### Balance Query Example

```elixir
validator_pk = <<48, ...>>
balance = BIC.Coin.balance(validator_pk)

IO.puts("Validator balance = #{balance}")

```

Because `BIC.Coin` is built into the node, economic state transitions remain consistent across all validators and cannot be altered by external contract deployments.

## Why BIC Modules Are Built Into the Node

These contracts are **built-in** because they are compiled into the node binary and cannot be overridden by user-supplied contracts. The consensus engine relies on this deterministic, audited logic for critical security guarantees, including proof-of-participation validation and token accounting. By embedding `BIC.Sol`, `BIC.SolBloom`, and `BIC.Coin` directly into `amadeusprotocol/node`, the protocol ensures that every validator executes identical code paths for core operations.

## Summary

- **`BIC.Sol`** in [`ex/lib/bic/sol.ex`](https://github.com/amadeusprotocol/node/blob/main/ex/lib/bic/sol.ex) parses and verifies solution objects across multiple layouts using `verify/2`, `unpack/1`, and hash helpers.
- **`BIC.SolBloom`** in [`ex/lib/bic/sol_bloom.ex`](https://github.com/amadeusprotocol/node/blob/main/ex/lib/bic/sol_bloom.ex) generates and checks bloom filters for segment VR hashes via `bloom/1` and `check/2`.
- **`BIC.Coin`** in [`ex/lib/bic/coin.ex`](https://github.com/amadeusprotocol/node/blob/main/ex/lib/bic/coin.ex) manages native token balances and supply through `balance/1`, `mint/2`, `burn/2`, and `total_supply/0`.
- All three modules are compiled into the Amadeus Protocol node, providing immutable, consensus-critical logic that user contracts cannot replace.

## Frequently Asked Questions

### What does BIC stand for in Amadeus Protocol?

**BIC** stands for **Built-In Contracts**. These are Elixir modules that implement core on-chain logic required for the consensus layer and are embedded directly into the node binary.

### Can users override or replace the built-in contracts in Amadeus Protocol?

No. The built-in contracts are compiled into the node binary and cannot be overridden by user-supplied contracts. This design guarantees deterministic, audited behavior for consensus-critical operations such as proof-of-participation validation and token accounting.

### Where are the BIC modules located in the amadeusprotocol/node repository?

All BIC modules live under `ex/lib/bic/`. Specifically, `BIC.Sol` is defined in [`ex/lib/bic/sol.ex`](https://github.com/amadeusprotocol/node/blob/main/ex/lib/bic/sol.ex), `BIC.SolBloom` in [`ex/lib/bic/sol_bloom.ex`](https://github.com/amadeusprotocol/node/blob/main/ex/lib/bic/sol_bloom.ex), and `BIC.Coin` in [`ex/lib/bic/coin.ex`](https://github.com/amadeusprotocol/node/blob/main/ex/lib/bic/coin.ex).

### How does BIC.Sol verify validator proof-of-participation?

`BIC.Sol.verify/2` accepts a binary SOL payload and an options map with parameters such as `segment_vr_hash` and `diff_bits`. It then runs a pipeline that unpacks the SOL, checks its size and hash, and performs Freivalds-based verification to confirm the validator’s proof-of-participation.