---
title: LayerX Architecture
description: Technical deep-dive into the sequencer, Postgres ledger, Merkle accumulator, settlement worker, and chain anchoring components.

---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

## LayerX architecture

LayerX is a sequencer-based side channel that maintains a Postgres-backed ledger, builds Merkle trees over committed transfers, and anchors roots to Paxeer L1 for independent verifiability.

## System components

### Sequencer

The sequencer is the single entry point for all LayerX transfers. It validates incoming transfer intents, applies them to the ledger, and returns signed receipts synchronously. There is no mempool - transfers are processed in the order they arrive.

The sequencer runs as a single binary (`layerxd`) and exposes the REST API on a configurable port. It does not participate in consensus; finality comes from the L1 anchor.

### Postgres ledger

All account balances and transfer history live in a Postgres database. The ledger is the source of truth for LayerX state. Every transfer is an atomic debit-credit pair recorded in a single transaction.

Schema migrations live in `migrations/` and are applied automatically on startup. The ledger tracks:

- **Accounts** - DID-keyed rows with USDX balance, nonce, and metadata.
- **Transfers** - sender, recipient, amount, timestamp, sequence number, and receipt signature.
- **Deposits** - L1-originated USDL deposits credited as USDX.
- **Withdrawals** - USDX debited for L1 withdrawal settlement.

### Merkle accumulator

After each batch window closes, the sequencer builds a domain-separated Merkle tree over all transfers in that batch. Each leaf is a hash of `(sender_did, recipient_did, amount, seq, timestamp)`. The Merkle root is published to Paxeer L1 alongside the batch metadata.

Merkle inclusion proofs allow any party to verify that a specific transfer was included in a committed batch - without trusting the sequencer.

### Settlement worker

The settlement worker handles two responsibilities:

1. **Batch anchoring** - computes the Merkle root for a closed batch window and submits it to the Paxeer L1 bridge contract.
2. **Withdrawal processing** - processes force-settle requests by computing net positions and initiating L1 transfers.

The worker runs on a configurable interval (default: a few minutes) and is idempotent - re-running it for the same batch produces the same root.

### Chain anchoring

Each batch is anchored to Paxeer L1 (chain ID 125) via a call to the LayerX bridge contract. The anchor includes:

- Batch sequence number
- Merkle root
- Timestamp
- Transfer count

Once anchored, the batch inherits the finality guarantees of Paxeer L1. Anyone can verify the anchor on-chain and cross-reference it against the LayerX API.

## Runtime layout

```
cmd/layerxd/          # Main binary entrypoint
internal/
  sequencer/          # Transfer processing, batch management
  ledger/             # Postgres queries, balance operations
  merkle/             # Tree construction, proof generation
  settlement/         # Batch anchoring, withdrawal processing
  auth/               # DID challenge/verify, principal tokens
  api/                # HTTP handlers, middleware, routing
pkg/
  did/                # DID parsing, Ed25519 key operations
  receipt/            # Receipt signing, domain separation
  usdx/               # USDX amount handling, precision
migrations/           # Postgres schema migrations
```

## Data flow

A typical transfer flows through the system as follows:

1. Agent submits a signed transfer intent via `POST /v1/transfer`.
2. The API layer verifies the DID signature and checks the sender's balance.
3. The sequencer applies the debit-credit pair atomically.
4. A signed receipt is generated and returned to the caller.
5. At batch close, the Merkle accumulator hashes all new transfers into a tree.
6. The settlement worker submits the Merkle root to Paxeer L1.
7. The transfer is now immutably anchored and independently verifiable.