> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metalntwx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> An introduction to blockchains and how Metal turns transactions into finalized blocks

## Blockchain basics

A **blockchain** is a shared ledger of transactions maintained by a network of
computers. Transactions are collected into **blocks**, with each block linked
to the preceding one. Computers running the blockchain's software are called
**nodes**. They follow the same rules for checking and agreeing on which block
to accept, allowing multiple operators to maintain the same history.

![Clockwise from the top left: a request labelled Tx A enters a candidate block containing Tx A and Tx B. The block is shared with four connected computers, which retain matching copies. The new block joins older blocks. A wallet with a checkmark shows the transaction is complete.](https://mintcdn.com/nexus-ed339086/CdWwGT0bcT9zD-Uw/images/architecture/how-blockchains-work.svg?fit=max\&auto=format\&n=CdWwGT0bcT9zD-Uw\&q=85\&s=a59931f88b01c738ca219d70362a0b78)

How a blockchain records a successful transaction, read clockwise.

## 1. A transaction is requested

When a transfer is requested, a signed instruction called a **transaction** is sent
to the network, asking it to update the ledger. The receiving node checks
whether the transaction is eligible and, if so, holds it in a **transaction pool**
for a future block.

## 2. How a block is proposed

For a transaction to enter the shared ledger, it must be included in a block
accepted by the network. Each block can contain many transactions, giving the
nodes one proposal to evaluate.

The blockchain's rules determine who can propose a block and how it is
accepted. Metal authorizes a set of nodes called **validators** to propose
blocks and vote on their acceptance. Each **consensus round** is an attempt to
agree on a block, with one validator acting as the **proposer**.

Each validator holds pending transactions in its own transaction pool. A
transaction may arrive at validator A while validator B is proposing the next
block. A signs groups of transactions selected from its pool and shares these
**transaction batches** with the other validators. B can then select
transactions from received batches alongside those in its own pool to build
the block.

Building a **candidate block** includes calculating how its transactions would
change the ledger. A **smart contract** is a program run by blockchain nodes,
and running it is called **execution**. For a transfer, the contract checks the
transfer conditions and calculates the balance changes. The updated balances
and other stored information form the proposed **state**.

Other validators need to know which block the proposer built on and what
changes it calculated. The candidate block's **block header** identifies the
preceding block, called its **parent**, and summarizes the transactions and
their results. It does this through **hashes**, which are compact identifiers
calculated from data. One hash identifies the parent. Others act as
**commitments** to the transactions and resulting state. Validators calculate
the hashes themselves and compare them with those recorded in the block
header to detect a mismatch.

## 3–4. Validators check the candidate block and reach agreement

The proposer shares the candidate block's transactions and block header with
the other validators. Each validator executes the transactions independently,
using its own copy of the parent's state as the starting point. If the
proposer claims changes that the transactions do not produce, the validator's
computed hashes will differ from the commitments in the block header. An
honest validator rejects that candidate block. This lets each validator check
the results without trusting the proposer's calculation.

Several candidate blocks could pass these checks, so validators still need
to agree on which one to accept. Metal uses **Simplex consensus**, Commonware's
voting protocol, to reach that agreement. Each signed vote refers to a
**block hash**, which identifies the candidate block and is calculated from
its block header. Simplex requires a **quorum**, the protocol's threshold of
validator votes, to finalize a block. Its voting rules prevent conflicting
final decisions under the assumption that fewer than one-third of validators
are faulty or malicious.

A validator can fail to respond. Metal needs enough responsive validators to
keep finalizing blocks, and Simplex can move to another proposer when a round
cannot complete. If the network cannot collect the required votes,
transactions can remain pending while **finality** stalls.

![Clockwise from the top left: signed transaction batches from other validators and transactions from the proposer's own transaction pool enter block construction. The proposer executes selected transactions against the parent's state and builds a candidate block. A vertical arrow leads down to validators repeating execution and checking the block. Moving left, Simplex votes on the block hash establish agreement, then the finalized block extends its parent.](https://mintcdn.com/nexus-ed339086/CdWwGT0bcT9zD-Uw/images/architecture/transactions-to-finality.svg?fit=max\&auto=format\&n=CdWwGT0bcT9zD-Uw\&q=85\&s=eff65f95162f87db11c1d909c13ca72f)

Metal's transaction-to-block path, read clockwise. Other validators contribute signed batches selected from their transaction pools. The proposer selects from those batches and its own pool. Validators repeat execution before Simplex voting on the block hash.

## 5. The accepted block extends the chain

Finalization adds the block to the history accepted by Metal's validators.
It is now a **canonical block**. Each node records its **finalized head**, the
latest block whose finalization it has applied. Links between blocks make changes to past
contents detectable. Consensus determines which history the network accepts.

## 6. The transaction's outcome is settled

The transfer may credit the intended recipient, place refused funds in
quarantine, or revert. **Finality** establishes which recorded outcome the
network has accepted. A **receipt** reports execution, but can appear before
finality.

## Participation and permissions

Metal separates permission to use applications from permission to operate the
network. Its validators and observer nodes are configured participants. Users
access the chain through an RPC service, subject to that service's access rules.

### Using Metal

An EVM account can hold tokens, submit transactions, and deploy contracts
without joining the validator set. Transactions must satisfy the chain's
admission rules, including a valid signature and sufficient MIP20 funds for
gas. Metal's general transaction admission does not require the sender to be
a registered institution.

Individual applications can impose additional requirements. For MIP20, a send
policy contract can enforce spending rules before calling the token. MIP20
calls the receive policy contract to check the recipient's incoming
rules before crediting funds. The recipient's controller configures those
[receive rules](https://docs.metalntwx.com/learn/mip20/handlers-and-policy.md). A refusal can revert an
ordinary transfer or quarantine its funds. MIP410 shielded payments require
proofs satisfying the pool's registration, sanctions, and policy checks. These
requirements govern use of those payment capabilities.

### Operating the network

Validators propose blocks and vote on finality. Their public keys identify
the set whose votes count toward consensus. Joining that set requires inclusion
in the network's validator configuration.

Observer nodes follow the chain and can serve application requests and forward
transactions to validators. They do not propose blocks or vote. The current
peer network also requires observers to be explicitly configured, so running
the node software alone does not grant access to its peers.

### Changes and administrative authority

Network operators coordinate software and configuration changes. Execution-rule
upgrades activate at scheduled times. Validator-set changes take effect at
epoch boundaries, where an epoch is a fixed range of block heights.
The process for authorizing validator membership changes remains an open
design decision.

Application authorities have narrower powers. A token owner controls minting
where the token supports it. An account controller configures its receive rules
and any spending controls supported by its send policy contract.
The MIP410 authority administers the shielded pool's participation rules and
registries. These roles govern their respective assets and
applications. Consensus votes determine which blocks become final.

## Inside Metal's nodes

Metal uses **Reth** to supply each node's **execution layer**. Reth was
developed for Ethereum, another blockchain that supports smart contracts.
Metal uses **`revm`** to run the **Ethereum Virtual Machine (EVM)**, which defines
how those programs execute. Reusing Reth also supplies state storage and interfaces for
application requests through **JSON-RPC**, the interface applications use to
submit transactions and read results. This avoids the need to build those
services separately.

Each validator keeps its own copy of the state and runs Simplex as its
**consensus layer**. Reth computes proposed changes locally, while Simplex
exchanges votes with other validators. This separation lets Metal reuse an
established contract environment while choosing consensus suited to its
configured validator set.
A node can be preparing another block while learning that an earlier one is
final. The **block service** coordinates execution with consensus decisions.
It directs Reth to build on the parent selected for the consensus round,
arranges candidate block checks, and applies Simplex's finality decisions. Ordering
these operations keeps the node's execution tied to the history selected by
consensus.

![An application connects to a validator or observer node through JSON-RPC. Each validator runs Reth with its own state, a block service, and Simplex. Observer nodes forward transactions, while the validators exchange votes through Simplex.](https://mintcdn.com/nexus-ed339086/CdWwGT0bcT9zD-Uw/images/architecture/validator-network.svg?fit=max\&auto=format\&n=CdWwGT0bcT9zD-Uw\&q=85\&s=53e2cf550cb870f4dc54871325f25e2a)

Each validator runs its own execution layer and consensus layer. An application uses JSON-RPC through a validator or observer node. Inside one validator, the block service carries requests and results between Simplex and Reth.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.