# DAG

Most blockchains process transactions in a single line, one block after another. Armchain takes a different approach using a **Directed Acyclic Graph (DAG)**, which lets multiple validators process transactions in parallel. This is one of the key reasons Armchain achieves higher throughput and faster finality.

This page explains how the DAG works and how it connects to block production.

## What is a DAG?

A Directed Acyclic Graph is a data structure where:

* **Directed**: Each edge (reference) has a direction, from a newer event to older events
* **Acyclic**: There are no cycles: you can never follow references and end up where you started
* **Graph**: Unlike a chain (linear), multiple events can exist at the same "level"

## Events

The fundamental unit of the DAG is an **event**. Each validator creates events that contain:

| Field          | Description                            |
| -------------- | -------------------------------------- |
| `Creator`      | Validator ID                           |
| `Sequence`     | Event number for this validator        |
| `Parents`      | References to up to 10 previous events |
| `Transactions` | 0 or more user transactions            |
| `Timestamp`    | Median timestamp                       |
| `Gas Used`     | Sum of gas for transactions            |
| `Signature`    | ML-DSA44 (3,732 bytes)                 |

### Event Creation

A validator creates a new event when:

1. It has transactions to include, **or**
2. A minimum time has passed since the last event (to maintain network liveness)

The validator selects parent events: its own latest event plus events from other validators it has learned about through gossip.

### Parent Selection

| Parameter        | Value |
| ---------------- | ----- |
| Max Parents      | 10    |
| Max Free Parents | 3     |

* A **self-parent** is always included (the validator's own previous event)
* **Other parents** are selected from the latest known events of other validators
* More parents improve DAG connectivity, which speeds up consensus convergence

## DAG Visualization

Consider a network with 4 validators (A, B, C, D):

```
Time ──────────────────────────────────────────►

A:  [A₁] ─────────────── [A₂] ────────────── [A₃]
      │                     │╲                   │
B:  [B₁] ──── [B₂] ───────┘ ╲── [B₃] ─────────┘
      │          │╲                  │╲
C:  [C₁] ──────┘  ╲── [C₂] ───────┘  ╲─ [C₃]
      │               ╱       │              │
D:  [D₁] ── [D₂] ──┘─────── [D₃] ─────────┘
```

Each arrow represents a parent reference. Events reference **multiple** validators, creating a mesh structure.

## From DAG to Blocks

While the DAG provides the raw ordering structure, Armchain still produces **blocks** for EVM compatibility. The process uses **frames** and **Atropos elections**:

### 1. Frame Processing

Events in the DAG are grouped into **frames** (consensus rounds). Within each frame, candidate events are evaluated for finalization.

### 2. Atropos Election

Root events in frame F+1 vote on candidate events in frame F through a weighted voting mechanism. When a candidate reaches quorum (≥ 2/3 of total validator stake weight), it is elected as the **Atropos**, the finalized event for that frame. There is a 1:1 mapping between Atropos events and blocks.

### 3. Block Construction

The Atropos event and all confirmed events from the frame are assembled into a block:

| Frame   | Events                 | Atropos      | Block     |
| ------- | ---------------------- | ------------ | --------- |
| Frame 0 | A₁, B₁, C₁, D₁         | B₁           | Block 1   |
| Frame 1 | A₂, B₂, C₂, D₂         | C₂           | Block 2   |
| Frame N | A₍ₙ₎, B₍ₙ₎, C₍ₙ₎, D₍ₙ₎ | Elected root | Block N+1 |

### 4. EVM Execution

Each block's transactions are sorted by Lamport time and executed sequentially through the EVM, producing state changes, receipts, and logs, exactly as in Ethereum. See [Consensus](/architecture/consensus.md) for the full three-phase block processing lifecycle.

## Vector Clock (VecMT)

Armchain uses a **Vector Clock / Median Timestamp (VecMT)** index to efficiently track event ordering across validators:

* Each validator maintains a vector of the latest sequence numbers it knows about from all other validators
* The **median timestamp** algorithm provides a fork-free ordering
* This enables the aBFT consensus to determine which events are agreed upon

## Advantages of the DAG

### Parallel Processing

Unlike a linear chain where only one block producer creates a block at a time, **all validators create events simultaneously**:

| Model        | Production Pattern                        | Throughput                 |
| ------------ | ----------------------------------------- | -------------------------- |
| Linear chain | A → B → C → D → A → B → ...               | One proposer at a time     |
| DAG          | All validators emit events simultaneously | All validators in parallel |

### Reduced Wasted Work

In PoW and some PoS chains, only one proposer's block is accepted; others are discarded. In Armchain's DAG, **every event contributes to consensus**: no work is wasted.

### Network Resilience

The DAG structure naturally handles:

* **Message reordering**: Events reference parents, so ordering is reconstructed
* **Temporary disconnections**: Validators can create events offline and sync later
* **Variable latency**: No synchronous rounds or timeouts required

## DAG Parameters

| Parameter             | Devnet   | Fakenet    |
| --------------------- | -------- | ---------- |
| Max Parents per Event | 10       | 10         |
| Max Free Parents      | 3        | 3          |
| Default Event Gas     | 28,000   | 28,000     |
| Max Epoch Duration    | 4 hours  | 10 minutes |
| Max Empty Block Skip  | 1 minute | 3 seconds  |

## Querying DAG Data

Armchain exposes DAG-specific APIs via the `dag` namespace:

```bash
# Get DAG event by hash
curl -X POST http://localhost:4000 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"dag_getEvent","params":["0xEVENT_HASH"],"id":1}'

# Get current epoch
curl -X POST http://localhost:4000 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"dag_getEpochStats","params":[],"id":1}'
```

See the [Armchain-Specific APIs](/api-reference/armchain-api.md) for the full DAG API reference.

## Further Reading

* [Consensus (Lachesis aBFT)](/architecture/consensus.md): The consensus algorithm built on the DAG
* [Transaction Lifecycle](/architecture/transaction-lifecycle.md): How transactions flow through the DAG
* [EVM Integration](/architecture/evm.md): How blocks from the DAG feed the EVM


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.armchain.org/architecture/dag.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.