LayerX Daemon, Auth, Chain, Accumulator, Store, Ledger, and Types

Overview

LayerX is the always-on settlement fabric for Matrix agents. The layerxd daemon gives each agent a DID-scoped account, mints and tracks a USD-denominated balance called USDX (fully reserved 1:1 by USDL), produces a Merkle-provable signed receipt for every accepted transfer, and batches settlement to Paxeer mainnet (chain 125).

Version: 0.1.0

Runtime Architecture

cmd/layerxd            # the sequencer daemon
internal/config        # env-first + layerx.config.kvx overlay
internal/auth          # ed25519 agent-DID challenge/verify + HMAC principal token
internal/store         # Postgres ledger: accounts, transfers, batches, deposits, withdrawals, holds
internal/accumulator   # domain-separated Merkle leaves + root + inclusion proofs
internal/sig           # the sequencer's ed25519 receipt-signing key
internal/ledger        # atomic Pay + signed receipts + proof reconstruction
internal/settle        # tiered settlement worker (window net + force-settle + anchor + hold sweep)
internal/chain         # Settler interface + Paxeer chain bindings (vault, anchor, ERC-20, router)
internal/ratelimit     # per-client token-bucket rate limiter
internal/events        # SSE event broker for live streaming
internal/server        # HTTP surface (public read + principal write)
pkg/types              # {ok,data,error} envelope + wire contracts
migrations             # forward-only SQL

HTTP Surface (Phase 4: Full-Transparency Model)

The surface is split into two groups:

• Public, unauthenticated READ surface (explorer/RPC): info, supply (reserve proof), batches, anchors, receipts, transfers, accounts, live SSE stream. Anyone can read so receipts/roots are independently verifiable and the reserve is publicly auditable.
• Write/principal surface authorized by DID signature alone: pay/withdraw/hold accept a directly DID-signed intent, or an X-LayerX-Agent principal token as a convenience. The shared transport bearer (LAYERX_TOKEN) is an optional fleet gate, never the public gate.

Public read routes (no auth)

Auth lane (public)

Write/principal surface (DID-signed intent or principal token)

Authentication

DID challenge/verify

1. Agent sends POST /v1/agent/auth/challenge with {did: "did:matrix:label:fingerprint"}
2. Server creates a single-use nonce (24-byte random, base64url, TTL-bound), returns {nonce, message}
3. Agent ed25519-signs the message, sends POST /v1/agent/auth/verify with {did, public_key, nonce, signature}
4. Server verifies: consumes nonce (single-use), verifies ed25519 signature, checks public key matches DID fingerprint
5. Server mints an HMAC-bound principal token (DID + expiry, base64url payload + HMAC signature)

Dual authorization on writes

Every write endpoint accepts either:

• X-LayerX-Agent principal token (convenience), OR
• A directly DID-signed intent (from_did, public_key, nonce, signature) where the signature IS the authorization (invariant i6)

Rate Limiting

Per-client token-bucket rate limiting with three classes:

/healthz and / are exempt. Client IP is extracted from X-Real-IP / X-Forwarded-For when TrustProxy is enabled, or from the transport peer address.

Ledger

Source: internal/ledger/ledger.go

The Ledger ties the store, sequencer signer, and tier policy together.

Pay

Pay(ctx, fromDID, toDID, amountMicro, ref) moves USDX atomically:

1. Classifies the tier (micropayment or material)
2. Inside a single DB transaction: debit sender, credit recipient, insert transfer, compute Merkle leaf + sequencer signature
3. Returns a signed Receipt

CaptureHold

CaptureHold(ctx, holdID, captorDID, amountMicro) consumes an open hold through the same transfer commitment path as Pay, with any remainder returned to the payer.

Receipt reconstruction

Receipt(ctx, seq, callerDID) returns the signed receipt. If the transfer's batch is sealed, it populates the Merkle root + inclusion path (and anchor tx once anchored) so the receipt is independently verifiable.

ReceiptPublic(ctx, seq) is the same but without caller-DID scoping (public explorer read).

Settlement Worker

Source: internal/settle/settle.go

The Worker runs on a configurable window (default 12 hours):

Window settlement (SettleNow)

1. List all unsettled transfers
2. Build Merkle root from leaf hashes
3. Seal the batch in Postgres
4. Anchor the root on Paxeer via chain.Settler.AnchorBatch
5. Mark anchored with the on-chain tx hash

Withdrawal settlement (SettleWithdrawals)

1. List queued withdrawals with mapped EVM addresses
2. Build a deterministic payout root (domain-separated SHA-256 over id + recipient + amount)
3. Seal withdrawals, anchor on Paxeer, mark settled

Hold expiry sweep

Runs every 30 seconds. Returns past-expiry open holds to their payers (fail-open refund).

Crash recovery

RecoverPending and RecoverPendingWithdrawals re-submit sealed-but-unanchored batches at startup. AnchorBatch is idempotent on the root.

Accumulator

Source: internal/accumulator/accumulator.go

Domain-separated Merkle tree for receipt proofs:

Store

Source: internal/store/store.go, internal/store/accounts.go

Postgres-backed via pgxpool.Pool. Forward-only migrations tracked in layerx_schema_migrations.

Key operations

Types

Source: pkg/types/types.go

USDX

Balances are stored as int64 micro-USDX (1 USDX = 1,000,000 micro-USDX). FormatUSDX(micro) renders decimal strings. ParseUSDX(s) is strict: rejects trailing garbage, excess precision, overflow.

Error codes

Settlement tiers