# sidestr/spec architecture

> Architecture diagram of the GitHub repository sidestr/spec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sidestr/spec
- Repository: https://github.com/sidestr/spec

## Overview

sidestr is a reference implementation of user-activated sidechains: operators define a chain document, initialize its engine and keys, then produce or sync signed blocks while users enforce the chain rules. The runtime also covers parent-chain pegs, federation, optional asset/pool/market/EVM rules, and announcements. The graph follows documented CLI capabilities and sampled imports/calls; unsampled command handlers and announcement consumers are shown only where the README documents them.

Main entry points: [`siding/lib/engine.mjs`](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/engine.mjs) (Engine loader), [`siding/lib/overlays/index.mjs`](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlays/index.mjs) (Rule selection), [`siding/lib/overlay.mjs`](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlay.mjs) (Sidestr overlay), [`siding/bin/siding.mjs`](https://github.com/sidestr/spec/blob/gh-pages/siding/bin/siding.mjs) (siding CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["Chain operations"]
  node_cli["siding CLI<br/>[siding.mjs]"]
  node_chain_doc["Chain document<br/>[chain.json]"]
  node_engine["Engine loader<br/>[engine.mjs]"]
  node_chain_runtime["Chain runtime<br/>[chain.mjs]"]
  node_announcer["Tip announcement<br/>[announce.mjs]"]
end

subgraph group_validation["Block validation"]
  node_block["Block encoding<br/>[block.mjs]"]
  node_side_overlay["Sidestr overlay<br/>[overlay.mjs]"]
end

subgraph group_parent["Parent chain"]
  node_parent_catalog["Parent definitions<br/>[parents.mjs]"]
  node_parent_rpc["Parent RPC / pegs<br/>[parent.mjs]"]
  node_marker["Peg markers<br/>[marker.mjs]"]
  node_pledge["Pledge desk<br/>[pledge.mjs]"]
  node_pegout["Peg-out rounds<br/>[pegoutround.mjs]"]
end

subgraph group_rules["Chain rules"]
  node_rules_index["Rule selection<br/>[index.mjs]"]
  node_assets["Asset rules<br/>[assets.mjs]"]
  node_pool["Pool rules<br/>[pool.mjs]"]
  node_markets["Market rules<br/>[markets.mjs]"]
  node_evm["EVM rules<br/>[evm.mjs]"]
  node_records["Rule records<br/>[records.mjs]"]
end

subgraph group_federation["Federation"]
  node_federation["Federation signing<br/>[federation.mjs]"]
  node_round["Signer rounds<br/>[round.mjs]"]
end

node_operator(("Operator / user"))
node_parent_node["Parent node"]
node_schema["Schema kernel"]
node_clients["Explorer / wallet"]
node_directory["Chain directory"]

node_operator -->|"runs commands"| node_cli
node_cli -->|"reads chain config"| node_chain_doc
node_cli -->|"loads engine"| node_engine
node_engine -->|"installs overlay"| node_side_overlay
node_engine -->|"selects rules"| node_rules_index
node_engine -->|"resolves parent"| node_parent_catalog
node_engine -->|"loads kernel"| node_schema
node_chain_runtime -->|"uses block codec"| node_block
node_chain_runtime -->|"checks peg-outs"| node_side_overlay
node_side_overlay -->|"validates blocks"| node_block
node_side_overlay -->|"checks parent rules"| node_parent_catalog
node_side_overlay -->|"uses federation"| node_federation
node_parent_rpc -->|"parses markers"| node_marker
node_parent_rpc -->|"calls RPC"| node_parent_node
node_pledge -->|"builds peg marker"| node_marker
node_pegout -->|"uses parent interface"| node_parent_rpc
node_rules_index -->|"creates rule"| node_assets
node_rules_index -->|"creates rule"| node_pool
node_rules_index -->|"creates rule"| node_markets
node_rules_index -->|"creates rule"| node_evm
node_assets -->|"uses records"| node_records
node_pool -->|"uses records"| node_records
node_markets -->|"uses records"| node_records
node_round -->|"uses signatures"| node_federation
node_cli -->|"announces chain"| node_announcer
node_clients -->|"finds chain by announcement"| node_announcer
node_directory -->|"lists announced chains"| node_announcer

click node_cli "https://github.com/sidestr/spec/blob/gh-pages/siding/bin/siding.mjs"
click node_chain_doc "https://github.com/sidestr/spec/blob/gh-pages/siding/chain.json"
click node_engine "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/engine.mjs"
click node_chain_runtime "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/chain.mjs"
click node_block "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/block.mjs"
click node_side_overlay "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlay.mjs"
click node_parent_catalog "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/parents.mjs"
click node_parent_rpc "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/parent.mjs"
click node_marker "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/marker.mjs"
click node_pledge "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/pledge.mjs"
click node_pegout "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/pegoutround.mjs"
click node_announcer "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/announce.mjs"
click node_rules_index "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlays/index.mjs"
click node_assets "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlays/assets.mjs"
click node_pool "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlays/pool.mjs"
click node_markets "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlays/markets.mjs"
click node_evm "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlays/evm.mjs"
click node_records "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/records.mjs"
click node_federation "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/federation.mjs"
click node_round "https://github.com/sidestr/spec/blob/gh-pages/siding/lib/round.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_chain_doc,node_engine,node_chain_runtime,node_announcer,node_operator toneBlue
class node_block,node_side_overlay toneAmber
class node_parent_catalog,node_parent_rpc,node_marker,node_pledge,node_pegout toneMint
class node_rules_index,node_assets,node_pool,node_markets,node_evm,node_records toneRose
class node_federation,node_round,node_parent_node,node_schema,node_clients,node_directory toneIndigo
```

## Components

### Chain operations

- [siding CLI](https://github.com/sidestr/spec/blob/gh-pages/siding/bin/siding.mjs): `siding/bin/siding.mjs`
- [Chain document](https://github.com/sidestr/spec/blob/gh-pages/siding/chain.json): `siding/chain.json`
- [Engine loader](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/engine.mjs): `siding/lib/engine.mjs`
- [Chain runtime](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/chain.mjs): `siding/lib/chain.mjs`
- [Tip announcement](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/announce.mjs): `siding/lib/announce.mjs`

### Block validation

- [Block encoding](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/block.mjs): `siding/lib/block.mjs`
- [Sidestr overlay](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlay.mjs): `siding/lib/overlay.mjs`

### Parent chain

- [Parent definitions](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/parents.mjs): `siding/lib/parents.mjs`
- [Parent RPC / pegs](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/parent.mjs): `siding/lib/parent.mjs`
- [Peg markers](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/marker.mjs): `siding/lib/marker.mjs`
- [Pledge desk](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/pledge.mjs): `siding/lib/pledge.mjs`
- [Peg-out rounds](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/pegoutround.mjs): `siding/lib/pegoutround.mjs`

### Chain rules

- [Rule selection](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlays/index.mjs): `siding/lib/overlays/index.mjs`
- [Asset rules](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlays/assets.mjs): `siding/lib/overlays/assets.mjs`
- [Pool rules](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlays/pool.mjs): `siding/lib/overlays/pool.mjs`
- [Market rules](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlays/markets.mjs): `siding/lib/overlays/markets.mjs`
- [EVM rules](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/overlays/evm.mjs): `siding/lib/overlays/evm.mjs`
- [Rule records](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/records.mjs): `siding/lib/records.mjs`

### Federation

- [Federation signing](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/federation.mjs): `siding/lib/federation.mjs`
- [Signer rounds](https://github.com/sidestr/spec/blob/gh-pages/siding/lib/round.mjs): `siding/lib/round.mjs`

### Other components

- **Operator / user**
- **Parent node**
- **Schema kernel**
- **Explorer / wallet**
- **Chain directory**

## Connections

- Operator / user → siding CLI: runs commands (evidence: `README.md`)
- siding CLI → Chain document: reads chain config (evidence: `siding/bin/siding.mjs`)
- siding CLI → Engine loader: loads engine (evidence: `siding/bin/siding.mjs`)
- Engine loader → Sidestr overlay: installs overlay (evidence: `siding/lib/engine.mjs`)
- Engine loader → Rule selection: selects rules (evidence: `siding/lib/engine.mjs`)
- Engine loader → Parent definitions: resolves parent (evidence: `siding/lib/engine.mjs`)
- Engine loader → Schema kernel: loads kernel (evidence: `siding/lib/engine.mjs`)
- Chain runtime → Block encoding: uses block codec (evidence: `siding/lib/chain.mjs`)
- Chain runtime → Sidestr overlay: checks peg-outs (evidence: `siding/lib/chain.mjs`)
- Sidestr overlay → Block encoding: validates blocks (evidence: `siding/lib/overlay.mjs`)
- Sidestr overlay → Parent definitions: checks parent rules (evidence: `siding/lib/overlay.mjs`)
- Sidestr overlay → Federation signing: uses federation (evidence: `siding/lib/overlay.mjs`)
- Parent RPC / pegs → Peg markers: parses markers (evidence: `siding/lib/parent.mjs`)
- Parent RPC / pegs → Parent node: calls RPC (evidence: `siding/lib/parent.mjs`)
- Pledge desk → Peg markers: builds peg marker (evidence: `siding/lib/pledge.mjs`)
- Peg-out rounds → Parent RPC / pegs: uses parent interface (evidence: `siding/lib/pegoutround.mjs`)
- Rule selection → Asset rules: creates rule (evidence: `siding/lib/overlays/index.mjs`)
- Rule selection → Pool rules: creates rule (evidence: `siding/lib/overlays/index.mjs`)
- Rule selection → Market rules: creates rule (evidence: `siding/lib/overlays/index.mjs`)
- Rule selection → EVM rules: creates rule (evidence: `siding/lib/overlays/index.mjs`)
- Asset rules → Rule records: uses records (evidence: `siding/lib/overlays/assets.mjs`)
- Pool rules → Rule records: uses records (evidence: `siding/lib/overlays/pool.mjs`)
- Market rules → Rule records: uses records (evidence: `siding/lib/overlays/markets.mjs`)
- Signer rounds → Federation signing: uses signatures (evidence: `siding/lib/round.mjs`)
- siding CLI → Tip announcement: announces chain (evidence: `README.md`)
- Explorer / wallet → Tip announcement: finds chain by announcement (evidence: `README.md`)
- Chain directory → Tip announcement: lists announced chains (evidence: `README.md`)