Architecture

Architecture overview

Last updated: 2026-07-23

BabyChain is split into four logical layers that are also four separately deployable components. Each layer talks to the ones above and below it over the network, and that is exactly how they are deployed.

Read this page first. Every other architecture page assumes you understand these four layers. If you only have five minutes, look at the diagram, the at-a-glance table, and "What is not in the diagram" — the rest is reference.

At a glance

Layer	Component	Port(s)	Source
Core ledger	`chain/` (BabyChain node, fork of `cosmos/evm` v0.7.0)	8545 (JSON-RPC), 8546 (WebSocket), 26657 (CometBFT), 1317 (REST)	`chain/babychain_local.sh`
Network access	`gateway/` (Postgres indexer, read API, OpenResty RPC proxy)	3000 (read API), 8080 (RPC proxy)	`gateway/docker-compose.yml`
Application	`pay/` (BabyFX Pay: invoice API, settlement, webhooks, sweep)	4000 (API)	`pay/docker-compose.yml`
Application	`explorer/` (Blockscout, local dev only)	4001 (frontend), 4002 (backend)	`explorer/docker-compose.yml`
Application	`monitoring/` (Prometheus + Grafana, local dev only)	9090 (Prom), 3001 (Grafana)	`monitoring/docker-compose.yml`
Application	`sdk/js-sdk/` (TypeScript SDK; `pos-android/`, `woocommerce/`, `shopify/` are stubs)	n/a (library)	`sdk/js-sdk/package.json`
Out of scope	`bridge/`, `testnet/`, `mainnet/`	n/a	intentionally empty; see the README in each dir
Client	`wallet/` (BabyWallet, Expo / React Native, non-custodial)	n/a (mobile)	separate repo

Layered view

flowchart TB
    subgraph Client["Client"]
        W["BabyWallet
(Expo/React Native)"]
        MM["MetaMask / any EVM wallet"]
    end

    subgraph Edge["Network access - gateway/"]
        RPC["OpenResty RPC proxy
:8080
(rate limit, batch cap, debug block)"]
        IDX["Postgres indexer
(polls chain)"]
        API["Read API
:3000"]
    end

    subgraph Core["Core ledger - chain/"]
        JSON["JSON-RPC + WebSocket
:8545 / :8546"]
        REST["REST
:1317"]
        CBT["CometBFT consensus
:26657
(PoA, ~1s finality)"]
    end

    subgraph App["Application layer"]
        PAY["pay/
:4000
(invoices, settlement,
webhooks, sweep)"]
        EXP["explorer/
:4001/:4002
(local Blockscout)"]
        MON["monitoring/
:9090/:3001
(Prometheus, Grafana)"]
    end

    subgraph Store["Data plane"]
        DB[("PostgreSQL
SyncDB")]
    end

    subgraph Out["Out of scope"]
        BR["bridge/"]
        TN["testnet/"]
        MN["mainnet/"]
    end

    W -->|eth_* JSON-RPC| RPC
    MM -->|eth_* JSON-RPC| RPC
    RPC --> JSON
    JSON <--> CBT
    JSON --> REST
    IDX -->|poll| JSON
    IDX --> DB
    API --> DB
    PAY -->|read/write| DB
    PAY -->|eth_sendRawTransaction| JSON
    EXP --> JSON
    MON --> JSON
    MON --> API

    classDef client fill:#dbeafe,stroke:#2563eb
    classDef edge fill:#e0e7ff,stroke:#4f46e5
    classDef core fill:#fef3c7,stroke:#d97706
    classDef app fill:#dcfce7,stroke:#16a34a
    classDef store fill:#fce7f3,stroke:#be185d
    classDef out fill:#f1f5f9,stroke:#64748b,stroke-dasharray: 3 3
    class W,MM client
    class RPC,IDX,API edge
    class JSON,REST,CBT core
    class PAY,EXP,MON app
    class DB store
    class BR,TN,MN out

What is not in the diagram

No cross-chain bridge. There is no Ethereum or BNB Chain gateway. All settlement is native to BabyChain.

A Blockscout instance is in the local stack at explorer/ (frontend :4001, backend :4002). It is the dev-only Blockscout; production deployment is in infra/ (TBD). The gateway indexer is still a narrow, normalized store and is not Blockscout.

No public faucet service. The faucet key exists in the local single-validator bootstrap but is not exposed as an HTTP service.

Source

README.md (the monorepo root) is the canonical short overview.
chain/RUN_GUIDE.md is the operational guide for the chain layer.
IMPLEMENTATION_PLAN.md Section 1 is the original architecture description.