---
title: "Chain configuration"
description: "How a bridge instance is configured for a specific network."
canonical_url: "https://nimiq.dev/bridge/reference/nimiq/chain-config"
---
# Chain configuration

> How a bridge instance is configured for a specific network.

Each bridge contract on Nimiq connects Nimiq to a single other network, and everything it knows about that network comes from its **chain configuration**. The configuration is part of the data a bridge contract is created with. It cannot be changed afterward, so the only way to fix a mistake in it is a new bridge contract.

## Why a bridge needs one

Releasing NIM means accepting a record that another network produced, in that network's format. The Nimiq protocol has no smart contracts, so a bridge contract cannot run code written for that network. Instead, the other network is described to Nimiq once, at creation, with the hash function its record tree uses, the format of its addresses, the contract whose records the bridge accepts, and a small program that reads a burn record. With that description, one account type can serve any network.

Consensus uses the configuration on every release. It reads the burn record with the validation program, and checks the record's source contract and chain id, the hash of the proof and its depth. A mistake in any of these affects every release the bridge makes.

The configuration also matters to anyone who creates or checks a bridge:

- **The creator of a bridge contract** writes it, and has to get it right the first time.
- **Anyone checking an existing bridge** reads it. A bridge account on Nimiq shows its oracle and source chain id, but not its program or the contract it accepts records from. Those are only in the transaction that created it.

## Where it lives

A bridge contract is created with its `owner`, the address of its [oracle](https://nimiq.dev/bridge/how-it-works/oracles), the `source_chain_id` of the network it serves, and the `chain_config`. The owner has no authority over the contract once it exists.

```rust
pub struct ChainConfig {
    pub chain_id: u32,
    pub hash_function: AnyHash,
    pub address_format: AddressFormat,
    pub endianness: Endianness,
    pub block_time: Duration,
    pub validation_program: ValidationProgram,
    pub max_proof_depth: u32,
    pub source_contract: Vec<u8>,
}
```

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        chain_id
      </code>
    </td>
    
    <td>
      <code>
        u32
      </code>
    </td>
    
    <td>
      Identifies the other network. Must equal <code>
        source_chain_id
      </code>
      
      , and every record a release carries must name the same chain id
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hash_function
      </code>
    </td>
    
    <td>
      <code>
        AnyHash
      </code>
    </td>
    
    <td>
      The hash function of the relayer's record tree, used for the leaf and every node of a release proof. <code>
        Blake2b
      </code>
      
      , <code>
        Sha256
      </code>
      
       or <code>
        Keccak256
      </code>
      
      . Must match the oracle's hash function
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        address_format
      </code>
    </td>
    
    <td>
      <code>
        AddressFormat
      </code>
    </td>
    
    <td>
      The address format of the other network, one of <code>
        Nimiq
      </code>
      
       or <code>
        Ethereum
      </code>
      
       (20 bytes), <code>
        Bitcoin
      </code>
      
       (20 to 64 bytes), or <code>
        Custom
      </code>
      
      . Used to check <code>
        source_contract
      </code>
      
       at creation
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        endianness
      </code>
    </td>
    
    <td>
      <code>
        Endianness
      </code>
    </td>
    
    <td>
      The byte order of the other network's encodings, <code>
        BigEndian
      </code>
      
       or <code>
        LittleEndian
      </code>
      
      . Informational only. No check reads it. The validation program's <code>
        LoadU64
      </code>
      
       and <code>
        LoadU32
      </code>
      
       operations name the byte order they read in
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        block_time
      </code>
    </td>
    
    <td>
      <code>
        Duration
      </code>
    </td>
    
    <td>
      The average time between blocks on the other network. Informational only. No check depends on it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        validation_program
      </code>
    </td>
    
    <td>
      <code>
        ValidationProgram
      </code>
    </td>
    
    <td>
      The program that reads a burn record. See <a href="#the-validation-program">
        The validation program
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        max_proof_depth
      </code>
    </td>
    
    <td>
      <code>
        u32
      </code>
    </td>
    
    <td>
      The maximum number of record-tree levels in a release proof. Levels added later as the oracle reuses its slots do not count, so a proof <a href="https://nimiq.dev/bridge/how-it-works/oracles#proofs-grow-and-nothing-is-discarded">
        never expires
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        source_contract
      </code>
    </td>
    
    <td>
      <code>
        Vec<u8>
      </code>
    </td>
    
    <td>
      The one contract on the other network whose records this bridge releases, in that network's address format
    </td>
  </tr>
</tbody>
</table>

`source_contract` matters because the relayer commits every record the [forwarder](https://nimiq.dev/bridge/how-it-works/oracles#the-outbound-forwarder) emits, from any contract. A record is releasable only if the source it names equals this value byte for byte.

## The validation program

A burn record reaches Nimiq as bytes. The validation program turns those bytes into the values a release needs. It runs inside consensus, on every release, and whenever a node decides whether to admit a release to its mempool.

The program only **extracts**. It reads values and stores them under fixed names; it never decides whether a release is valid. Consensus makes that decision afterward, by checking the stored values against the bridge contract and the release transaction.

### What a program must store

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      What consensus does with it
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        source_contract
      </code>
    </td>
    
    <td>
      bytes
    </td>
    
    <td>
      Must equal <code>
        source_contract
      </code>
      
       in the configuration
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        amount
      </code>
    </td>
    
    <td>
      integer, in luna
    </td>
    
    <td>
      Must not be zero and must be a valid NIM amount. The release's value and fee must add up to exactly this amount
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        target_address
      </code>
    </td>
    
    <td>
      20 bytes
    </td>
    
    <td>
      The release must be signed by this address and pay it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        target_nonce
      </code>
    </td>
    
    <td>
      integer
    </td>
    
    <td>
      Must be exactly one higher than the last nonce released to <code>
        target_address
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        burn_block_height
      </code>
    </td>
    
    <td>
      integer
    </td>
    
    <td>
      Required, but not used by any check
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        target_chain_id
      </code>
    </td>
    
    <td>
      integer
    </td>
    
    <td>
      Must equal <code>
        source_chain_id
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bridge_address
      </code>
    </td>
    
    <td>
      20 bytes
    </td>
    
    <td>
      Must be the address of the bridge contract executing the release
    </td>
  </tr>
</tbody>
</table>

A program that leaves out any of these, or stores a value of the wrong type, makes every release invalid.

The last two names bind a record to one network and one bridge. `target_chain_id` stops a record from the same contract address on a different network from being accepted. `bridge_address` stops a second bridge that accepts the same source contract from releasing every past burn a second time, starting from empty nonce counters.

### How a program runs

A program is a list of operations that run in order on a stack. Values on the stack are 64-bit integers, 32-bit integers or byte strings.

- **Reads are bounds-checked.** Every read names an offset into the record, and a read that falls outside it fails.
- **Programs always finish.** The only jump moves forward, so there are no loops.
- **Arithmetic is checked.** Overflow, underflow and division by zero fail instead of wrapping around.
- **Values are stored by name.** `Store` saves the top of the stack under a name; `Load` reads it back.

Any failure, whether a read out of range, an overflow, an empty stack or a missing name, ends the program, and the release is [invalid rather than failed](https://nimiq.dev/bridge/how-it-works/burn-and-release#a-release-either-succeeds-or-is-invalid). The bridge is not debited and nobody pays a fee.

### Operations

Stack effects are written as before and after, with the top of the stack on the right. In `[a, b]`, `b` is on top.

<table>
<thead>
  <tr>
    <th>
      Group
    </th>
    
    <th>
      Operations
    </th>
    
    <th>
      Purpose
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="#loading">
        Loading
      </a>
    </td>
    
    <td>
      <code>
        PushConst
      </code>
      
      , <code>
        LoadBytes
      </code>
      
      , <code>
        LoadU64
      </code>
      
      , <code>
        LoadU32
      </code>
      
      , <code>
        LoadAddress
      </code>
      
      , <code>
        LoadEvmU64
      </code>
      
      , <code>
        LoadEvmU64Scaled
      </code>
    </td>
    
    <td>
      Push a constant, or read bytes, integers or a 20-byte address from the record
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#arithmetic">
        Arithmetic
      </a>
    </td>
    
    <td>
      <code>
        Add
      </code>
      
      , <code>
        Sub
      </code>
      
      , <code>
        Mul
      </code>
      
      , <code>
        Div
      </code>
      
      , <code>
        Mod
      </code>
    </td>
    
    <td>
      Calculate with values read from the record
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#comparison">
        Comparison
      </a>
    </td>
    
    <td>
      <code>
        Eq
      </code>
      
      , <code>
        Lt
      </code>
      
      , <code>
        Gt
      </code>
      
      , <code>
        IsZero
      </code>
    </td>
    
    <td>
      Compare two values, or one with zero, producing 1 or 0
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#logic">
        Logic
      </a>
    </td>
    
    <td>
      <code>
        And
      </code>
      
      , <code>
        Or
      </code>
      
      , <code>
        Not
      </code>
    </td>
    
    <td>
      Combine conditions, producing 1 or 0
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#stack">
        Stack
      </a>
    </td>
    
    <td>
      <code>
        Dup
      </code>
      
      , <code>
        Swap
      </code>
      
      , <code>
        Pop
      </code>
    </td>
    
    <td>
      Arrange values for the next operation
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#control-flow">
        Control flow
      </a>
    </td>
    
    <td>
      <code>
        JumpIfZero
      </code>
    </td>
    
    <td>
      Skip a number of operations, forward only
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#named-values">
        Named values
      </a>
    </td>
    
    <td>
      <code>
        Store
      </code>
      
      , <code>
        Load
      </code>
    </td>
    
    <td>
      Save a value under a name, or read it back
    </td>
  </tr>
</tbody>
</table>

#### Loading

<table>
<thead>
  <tr>
    <th>
      Operation
    </th>
    
    <th>
      Stack
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        PushConst(value)
      </code>
    </td>
    
    <td>
      <code>
        [] → [value]
      </code>
    </td>
    
    <td>
      Pushes a 64-bit constant
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        LoadBytes
      </code>
    </td>
    
    <td>
      <code>
        [offset, length] → [bytes]
      </code>
    </td>
    
    <td>
      Reads <code>
        length
      </code>
      
       bytes from the record at <code>
        offset
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        LoadU64(byte order)
      </code>
    </td>
    
    <td>
      <code>
        [offset] → [integer]
      </code>
    </td>
    
    <td>
      Reads an 8-byte integer in the given byte order
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        LoadU32(byte order)
      </code>
    </td>
    
    <td>
      <code>
        [offset] → [integer]
      </code>
    </td>
    
    <td>
      Reads a 4-byte integer in the given byte order
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        LoadAddress
      </code>
    </td>
    
    <td>
      <code>
        [offset] → [bytes]
      </code>
    </td>
    
    <td>
      Reads 20 bytes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        LoadEvmU64
      </code>
    </td>
    
    <td>
      <code>
        [offset] → [integer]
      </code>
    </td>
    
    <td>
      Reads a 32-byte big-endian EVM word. Fails if the value does not fit in 64 bits
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        LoadEvmU64Scaled(divisor)
      </code>
    </td>
    
    <td>
      <code>
        [offset] → [integer]
      </code>
    </td>
    
    <td>
      Reads a 32-byte big-endian EVM word and divides it by <code>
        divisor
      </code>
      
       at full width, dropping any remainder. Fails if the result does not fit in 64 bits
    </td>
  </tr>
</tbody>
</table>

`LoadEvmU64Scaled` is for a token with more decimals than NIM. Dividing before narrowing to 64 bits keeps large amounts readable, where narrowing first would cap them.

#### Arithmetic

<table>
<thead>
  <tr>
    <th>
      Operation
    </th>
    
    <th>
      Stack
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Add
      </code>
    </td>
    
    <td>
      <code>
        [a, b] → [a + b]
      </code>
    </td>
    
    <td>
      Fails on overflow
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Sub
      </code>
    </td>
    
    <td>
      <code>
        [a, b] → [a - b]
      </code>
    </td>
    
    <td>
      Fails if <code>
        b
      </code>
      
       is greater than <code>
        a
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Mul
      </code>
    </td>
    
    <td>
      <code>
        [a, b] → [a × b]
      </code>
    </td>
    
    <td>
      Fails on overflow
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Div
      </code>
    </td>
    
    <td>
      <code>
        [a, b] → [a ÷ b]
      </code>
    </td>
    
    <td>
      Drops any remainder. Fails if <code>
        b
      </code>
      
       is zero
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Mod
      </code>
    </td>
    
    <td>
      <code>
        [a, b] → [a mod b]
      </code>
    </td>
    
    <td>
      Fails if <code>
        b
      </code>
      
       is zero
    </td>
  </tr>
</tbody>
</table>

#### Comparison

<table>
<thead>
  <tr>
    <th>
      Operation
    </th>
    
    <th>
      Stack
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Eq
      </code>
    </td>
    
    <td>
      <code>
        [a, b] → [1 or 0]
      </code>
    </td>
    
    <td>
      1 if <code>
        a
      </code>
      
       equals <code>
        b
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Lt
      </code>
    </td>
    
    <td>
      <code>
        [a, b] → [1 or 0]
      </code>
    </td>
    
    <td>
      1 if <code>
        a
      </code>
      
       is less than <code>
        b
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Gt
      </code>
    </td>
    
    <td>
      <code>
        [a, b] → [1 or 0]
      </code>
    </td>
    
    <td>
      1 if <code>
        a
      </code>
      
       is greater than <code>
        b
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        IsZero
      </code>
    </td>
    
    <td>
      <code>
        [a] → [1 or 0]
      </code>
    </td>
    
    <td>
      1 if <code>
        a
      </code>
      
       is zero
    </td>
  </tr>
</tbody>
</table>

#### Logic

These treat any non-zero value as true and produce 1 or 0. They are logical, not bitwise, so `And` cannot be used to mask bits.

<table>
<thead>
  <tr>
    <th>
      Operation
    </th>
    
    <th>
      Stack
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        And
      </code>
    </td>
    
    <td>
      <code>
        [a, b] → [1 or 0]
      </code>
    </td>
    
    <td>
      1 if both are non-zero
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Or
      </code>
    </td>
    
    <td>
      <code>
        [a, b] → [1 or 0]
      </code>
    </td>
    
    <td>
      1 if either is non-zero
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Not
      </code>
    </td>
    
    <td>
      <code>
        [a] → [1 or 0]
      </code>
    </td>
    
    <td>
      1 if <code>
        a
      </code>
      
       is zero
    </td>
  </tr>
</tbody>
</table>

#### Stack

<table>
<thead>
  <tr>
    <th>
      Operation
    </th>
    
    <th>
      Stack
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Dup
      </code>
    </td>
    
    <td>
      <code>
        [a] → [a, a]
      </code>
    </td>
    
    <td>
      Copies the top value
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Swap
      </code>
    </td>
    
    <td>
      <code>
        [a, b] → [b, a]
      </code>
    </td>
    
    <td>
      Swaps the top two values
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Pop
      </code>
    </td>
    
    <td>
      <code>
        [a] → []
      </code>
    </td>
    
    <td>
      Discards the top value
    </td>
  </tr>
</tbody>
</table>

#### Control flow

<table>
<thead>
  <tr>
    <th>
      Operation
    </th>
    
    <th>
      Stack
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        JumpIfZero(n)
      </code>
    </td>
    
    <td>
      <code>
        [condition] → []
      </code>
    </td>
    
    <td>
      If the condition is zero, skips the next <code>
        n
      </code>
      
       operations
    </td>
  </tr>
</tbody>
</table>

#### Named values

<table>
<thead>
  <tr>
    <th>
      Operation
    </th>
    
    <th>
      Stack
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Store(name)
      </code>
    </td>
    
    <td>
      <code>
        [value] → []
      </code>
    </td>
    
    <td>
      Saves the value under <code>
        name
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Load(name)
      </code>
    </td>
    
    <td>
      <code>
        [] → [value]
      </code>
    </td>
    
    <td>
      Pushes the value saved under <code>
        name
      </code>
      
      . Fails if nothing was saved
    </td>
  </tr>
</tbody>
</table>

The code defines five more operations, `Assert` and four `PushExpected` operations. A bridge contract whose program uses any of them is [rejected at creation](#creation-checks).

## Creation checks

Consensus rejects a bridge contract at creation if its configuration could accept deposits but never release them. A rejected configuration can be corrected and submitted again; an accepted one cannot be fixed at all.

<table>
<thead>
  <tr>
    <th>
      Check
    </th>
    
    <th>
      What it prevents
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        source_chain_id
      </code>
      
       is not zero, and <code>
        chain_id
      </code>
      
       equals it
    </td>
    
    <td>
      Records that can never name the right chain
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        source_contract
      </code>
      
       is a valid address in <code>
        address_format
      </code>
      
      , and not all zero bytes
    </td>
    
    <td>
      A bridge that accepts records from no real contract
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hash_function
      </code>
      
       is <code>
        Blake2b
      </code>
      
      , <code>
        Sha256
      </code>
      
       or <code>
        Keccak256
      </code>
    </td>
    
    <td>
      A hash function the release path does not support. <code>
        Sha512
      </code>
      
       is rejected
    </td>
  </tr>
  
  <tr>
    <td>
      The oracle exists, is an oracle contract, and uses the same hash function
    </td>
    
    <td>
      Proofs that can never match what the oracle stores
    </td>
  </tr>
  
  <tr>
    <td>
      The program contains no <code>
        Assert
      </code>
      
       and no <code>
        PushExpected
      </code>
      
       operation
    </td>
    
    <td>
      Operations that exist for a validation mode releases never use, and that make every release fail
    </td>
  </tr>
</tbody>
</table>

The checks catch the mistakes that are visible in the configuration itself. They cannot catch a program that reads the wrong offsets, or a `source_contract` that is a real address but the wrong one. Such a bridge can fail to release burns, or read them incorrectly, and its configuration can never be corrected.


## Sitemap

See the full [sitemap](https://nimiq.dev/sitemap.md) for all pages.
