# Umotu Architecture Overview

**One chain, two subsystems:** **CometBFT** orders blocks and decides finality; a **Geth-based EVM** executes transactions. The ABCI app is the bridge between them and enforces Umotu-specific rules (stable-as-gas, PaymentTx for PBS, QC threshold).

## Mental model

```
Public mempool/Builders → Proposer (CometBFT) → ABCI (policy/QC gate) → Geth/EVM (execution) → AppHash (state root)
                                       ↑
                              Phone committee (VRF winners) produces BLS QC
```

- **CometBFT (consensus/ordering):** 2s block cadence. Proposers assemble proposals; finality requires a **QC** (aggregate BLS signature) from the **phone committee**.
- **ABCI app (bridge/policy):** verifies QC, enforces **PaymentTx #1** for builder blocks, and exposes the **EVM state root** as CometBFT’s **AppHash**.
- **Geth (execution):** runs EVM transactions, applies Umotu’s fee-routing (e.g., base-fee/tips split), hosts the `NativeMinter` precompile and paymaster logic.
- **Phones & sentinels:** selected by **VRF** each height; verify and **sign** the block; rewards are paid via the **QC pool** per participation.

## What users need to know
- It’s an **EVM chain**. Add the RPC and use your wallet as usual.
- **Stable-as-gas:** pay fees in supported stablecoins; the protocol settles validators in UMT behind the scenes.
- **Finality:** ~2–4s once the QC is in; reorgs are practically nonexistent.

## What developers need to know
- **EVM-equivalent**: same Solidity, ABI, and JSON-RPC as Ethereum (via Geth).
- Differences:
  - Base fee **is not burned**; it is routed per Umotu’s split rules.
  - A **NativeMinter** precompile is available (for EmissionController claims).
  - Optional custom tx type for **stable-as-gas** (paymaster assisted).
  - Block headers carry extra metadata (builder receipt/QC digest) that most dapps can ignore.
- Finality signal: wait for **QC-confirmed commit** (exposed via RPC/event) for “finalized” semantics.

## What validators run
- **CometBFT node** (p2p + consensus).
- **ABCI app** (policy/QC gate, talks to Geth).
- **Geth** (execution engine). Can be embedded or a sidecar process.
- Proposer ↔ coinbase mapping: the CometBFT proposer’s address is used as **EVM coinbase** for fee routing.

## MEV & fee routing (policy hooks)
- **PBS-lite:** builder blocks must include **PaymentTx #1 → QCPool**; phones verify it before signing.
- **Splits:** e.g., BaseFee+Tips 80/20 (proposer/QC); PBS 20/80 (proposer/QC). Pools smooth payouts over epochs to remove spam incentives.
- **OFA (optional):** wallets can route private orderflow with rebate commitments; enforced via PaymentTx too.

## Safety notes
- QC threshold (e.g., 2/3 weighted) is enforced before commit.
- Fraud-evidence paths exist for **punitive slashing** of proposers/sentinels; automatic rollbacks are avoided for operational simplicity.

## Implementation Details

### ABCI++ App responsibilities
- Executes the full block via an embedded geth EVM and returns the EVM state root as CometBFT AppHash.
- Enforces quorum certificates (QCs) and optional builder payment gating prior to accepting a commit.
- Splits and routes execution fees to on-chain reward pools (sentinel and validator) using in-EVM calls.
- Maintains a lightweight, persistent JSON-RPC index for recent blocks/txs to power the built-in RPC shim.

Key env toggles (defaults in parentheses):
- `UMOTU_QC_ENFORCE` (true): require a valid QC per height before commit.
- `UMOTU_QC_THRESHOLD_BPS` (6667): minimum attestation weight in basis points.
- `UMOTU_PBS_REQUIRED` (true): require a builder payment transaction as tx[0].
- `UMOTU_ALLOW_BUILDER_FALLBACK` (true): if the builder payment is missing/invalid, allow fallback to self-build.
- `UMOTU_QC_ACTIVATE_AT`, `UMOTU_PBS_ACTIVATE_AT` (0): absolute heights to start QC/PBS enforcement. Alternatively, use `UMOTU_QC_ACTIVATE_WITHIN` / `UMOTU_PBS_ACTIVATE_WITHIN` to begin enforcement a certain number of blocks after the node catches up; `UMOTU_ACTIVATION_MAX_SKEW_SEC` caps how far block time can drift from wall-clock before scheduling.
- `UMOTU_VALIDATOR_REGISTRY` (0x0): address of ValidatorRegistry for validator set updates. When unset, static set.
- `UMOTU_SENTINEL_REWARDS`, `UMOTU_VALIDATOR_REWARDS`: reward pool contract addresses for fee routing.
- `UMOTU_BASEFEE_SENTINEL_BPS` (8000), `UMOTU_TIPS_SENTINEL_BPS` (8000), `UMOTU_PBS_SENTINEL_BPS` (2000): fee splits to sentinels.
- `UMOTU_BASEFEE_DELAY_SEC` (1800): smoothing delay for base fee payouts to both pools.
- `UMOTU_GENESIS`: path to genesis.json for the embedded EVM (defaults to `infra/genesis.json`).
- `UMOTU_RPC_INDEX` (`/app/data/rpc-index.json`), `UMOTU_RPC_RETENTION` (10000), `UMOTU_RPC_SNAPSHOT_EVERY` (25): JSON-RPC index persistence and retention.

### QC payload and commit gating
- Vote extensions carry an RLP-encoded payload the app decodes and stores per-height. Schema (version 2):
  - `Version: uint8` (supports 1 or 2)
  - `Height: uint64`
  - `Committee: uint32` and `Attested: uint32` (weight counts)
  - `BlockHash: bytes32` (CometBFT block hash)
  - `StateRoot: bytes32` (optional EVM root; informational)
  - `Timestamp: uint64`
  - `Signature: bytes` (aggregate; not yet verified cryptographically in app)
  - `Bitmap: bytes` (committee bitmap)
  - `BuilderReceipt: bytes32` and `BuilderAmount: uint256` (optional, used for PBS-lite matching)
- The app checks:
  - Height match and block-hash match for the commit
  - Attested/Committee satisfies `UMOTU_QC_THRESHOLD_BPS`
  - If builder payments are required, the QC’s `BuilderReceipt/Amount` must match the observed builder payment (see below)

### Builder payment (PBS‑lite)
- If `UMOTU_PBS_REQUIRED=true`, the proposer must include a “PaymentTx” as the first transaction in the block (tx index 0).
- The app extracts `value` from tx[0] and computes a `builderReceipt = keccak256(blockHash || txHash || value)`.
- During commit, the stored `builderReceipt` and `amount` must equal the QC’s `BuilderReceipt` and `BuilderAmount`.
- If the payment is missing or malformed and `UMOTU_ALLOW_BUILDER_FALLBACK=true`, the app continues in self-build mode; otherwise the proposal is rejected.

### Fee routing and pools
- Base fee and tip accounting is computed per block inside the embedded EVM.
- Splits and timing:
  - Base fee: split into sentinel and validator shares. Both are scheduled with an unlock at `now + UMOTU_BASEFEE_DELAY_SEC`.
  - Tips (priority fees): immediate sentinel share deposit.
  - Builder payments: immediate sentinel share deposit.
- On-chain calls made by the app (signatures are concrete in the code):
  - Sentinel pool: `SentinelRewards.deposit(uint256 blockHeight, uint256 totalFees, uint256 sentinelShare)`
  - Validator pool: `ValidatorRewards.deposit(address validator, uint64 unlockAt)` (payable with amount)
- Proposer-to-operator mapping: the CometBFT proposer address is mapped to an operator EVM address via the ValidatorRegistry and used as the validator reward recipient for base-fee shares.

### Validator set integration
- If `UMOTU_VALIDATOR_REGISTRY` is set, the app periodically refreshes the validator set by calling:
  - `ValidatorRegistry.getActiveValidators() -> (operator, consensusKey(bytes32 ed25519), power, stake, joinedAt, jailUntil, unbonding, unbondingEndsAt)[]`
- The ed25519 `consensusKey` is converted to a CometBFT pubkey and drives `ValidatorUpdate`s; a proposer-index map binds the 20-byte CometBFT address to the EVM `operator` address.

### Embedded EVM and AppHash
- The ABCI app runs an in-process geth execution harness that:
  - Loads chain config from `infra/genesis.json` (chainId 9601 by default).
  - Executes all transactions with proper EIP‑1559 base fee mechanics.
  - Commits the StateDB trie root at the end of FinalizeBlock and presents it as `AppHash` to CometBFT.

### Built-in JSON‑RPC shim
- Lightweight, read-only JSON‑RPC is exposed via HTTP POST at `/rpc` and WebSocket at `/ws` to aid dev tools.
- Implemented methods include: `eth_chainId`, `eth_blockNumber`, `eth_getBlockByNumber`, `eth_getTransactionByHash`, `eth_getTransactionReceipt`, `eth_getBlockTransactionCountBy{Number,Hash}`, `eth_getTransactionByBlock{Number,Hash}AndIndex`, `eth_call`, `eth_sendRawTransaction` (forwards to CometBFT RPC), `eth_estimateGas` (binary search over gas), `eth_getLogs`/filters, `web3_clientVersion`, `web3_sha3`, `net_*`, `eth_feeHistory`, `eth_maxPriorityFeePerGas`.
- Persistence/retention:
  - Blocks and txs are stored in-memory and snapshotted to `UMOTU_RPC_INDEX` every `UMOTU_RPC_SNAPSHOT_EVERY` heights.
  - Only the most recent `UMOTU_RPC_RETENTION` heights are kept in-memory to bound usage.
- Related env vars: `UMOTU_RPC_FILTER_TTL`, `UMOTU_RPC_LOGS_MAX`, `COMETBFT_RPC` (for broadcasting raw txs).
- Health and metrics endpoints: `/health`, `/healthz` (height + appHash), `/metrics` (Prometheus).

### Genesis toggles
- `infra/genesis.json` includes feature flags for protocol milestones:
  - `umotuNativeMinterBlock` and `umotuTxTypeStableGasBlock` are reserved for enabling the NativeMinter precompile and a custom stable‑gas tx type at specific blocks (present in config; activation handled by execution layer builds).

## Contracts mapped in policy hooks
- ValidatorRegistry: stakes, jails, slashes, and exposes `getActiveValidators()` and `operatorByKey(bytes32)`.
- ValidatorRewards: receives delayed base-fee shares for the current proposer (operator) and supports time-based unlocking per bucket.
- SentinelBond + SentinelRewards: bond management and pro‑rata fee distribution to bonded sentinels; SentinelRewards exposes `deposit(blockHeight,totalFees,sentinelShare)` used by the app.
- ProtocolPaymaster + FXOracle + StableGasRegistry: implement “stable‑as‑gas” via prepay and settlement; not directly used by the ABCI app but relevant for chain semantics and client UX.

## Operational endpoints and ports
- ABCI server: `--abci.laddr` (default `tcp://0.0.0.0:26658`), transport `socket|grpc`.
- HTTP server (RPC/health/metrics): `--http.addr` (default `:8080`), routes `/rpc`, `/ws`, `/health`, `/healthz`, `/metrics`.

## Caveats and current limits
- The QC aggregate signature is carried through and stored but not yet verified cryptographically inside the ABCI app; threshold/height/hash checks and builder payment matching are enforced.
- The JSON‑RPC shim is intentionally minimal and designed for development and light tooling; production nodes should front it with a full JSON‑RPC endpoint when available.

## Example Config

### Testnet (QC enforced, PBS‑lite on, reward pools wired)

umotu-abci.env
```
# ============================================
# UMOTU-NODE (systemd) configuration
# ============================================

# Path to the EVM genesis file used by the embedded execution layer
UMOTU_GENESIS=/var/lib/umotu/genesis.json
 
# Address of the on-chain ValidatorRegistry contract
UMOTU_VALIDATOR_REGISTRY=0x29d11eF2253eD65545C6E9De2705ba5A6C6Eb3CD
UMOTU_VALIDATOR_REWARDS=0x31588EFE33bf7f26b03A259da3B4493007107D7B
UMOTU_SENTINEL_REWARDS=0x54d7bcCb4105828f6e2CB4F430ac53aA1776f993

# Optional quorum threshold override for phone attestations (basis points, default 6667 = 2/3)
UMOTU_QC_THRESHOLD_BPS=6667

# System addresses and RPC index files
UMOTU_SYSTEM_ADDRESSES=/var/lib/umotu/system-addresses.json
UMOTU_RPC_INDEX=/var/lib/umotu/abci-data/rpc-index.json
UMOTU_RPC_INDEX_DB=/var/lib/umotu/abci-data/rpc-index.pebble
UMOTU_RPC_INDEX_SYNC=false
# Fee distribution settings
UMOTU_BASEFEE_SENTINEL_BPS=8000
UMOTU_TIPS_SENTINEL_BPS=8000
UMOTU_PBS_SENTINEL_BPS=2000
UMOTU_BASEFEE_DELAY_SEC=1800
 
# RPC settings
UMOTU_RPC_RETENTION=10000
UMOTU_RPC_LOGS_MAX=5000
UMOTU_RPC_FILTER_TTL=300
UMOTU_RPC_SNAPSHOT_EVERY=50
UMOTU_RPC_WAIT_RECEIPT_MS=8000

UMOTU_RPC_STORE_RECEIPTS=true
UMOTU_RPC_STORE_LOGS=true
UMOTU_RPC_MEMORY_LOGS=false
# Reduce noisy per-block ABCI logs (launcher-side filtering)
UMOTU_ABCI_LOG_QUIET=false

# Consensus enforcement
UMOTU_QC_ENFORCE=false
UMOTU_PBS_REQUIRED=false
UMOTU_ALLOW_BUILDER_FALLBACK=true
UMOTU_QC_ACTIVATE_AT=
UMOTU_PBS_ACTIVATE_AT=
UMOTU_QC_ACTIVATE_WITHIN=500
UMOTU_PBS_ACTIVATE_WITHIN=500
UMOTU_ACTIVATION_MAX_SKEW_SEC=120

# Builder relay automation
UMOTU_BUILDER_AUTOMATION=true
UMOTU_BUILDER_RELAY_URL=https://builder-relay1.testnet.umotu.com,https://builder-relay2.testnet.umotu.com,https://builder-relay3.testnet.umotu.com,https://builder-relay4.testnet.umotu.com
UMOTU_BUILDER_TOKEN=proposer-token-1
UMOTU_BUILDER_ASSIGN_TIMEOUT_MS=1500
UMOTU_BUILDER_SLASH_INTERVAL_SEC=5
UMOTU_BUILDER_SLASH_TIMEOUT_MS=8000

# Fraud-proof settings
UMOTU_CHALLENGE_WINDOW_SEC=20
UMOTU_DISPUTE_TOKEN=369a665a63ec9ac8e1e818f339de4ee6693c026285f2dec5da6eed0a0cf109d1
# For host/systemd execution, slash-executor runs on localhost:8390
UMOTU_SLASH_WEBHOOK=http://127.0.0.1:8390/slash
UMOTU_SLASH_WEBHOOK_TOKEN=
UMOTU_SLASH_AMOUNT_WEI=
UMOTU_CHALLENGER_REWARD_BPS=
UMOTU_DISPUTE_NONCES=/home/solcal/umotu/infra/dispute-data/dispute-nonces.json
UMOTU_DISPUTE_NONCE_TTL_SEC=86400

# DA settings
UMOTU_DA_SERVICE_URL=http://127.0.0.1:8388
UMOTU_DA_CHUNK_SIZE=
UMOTU_DA_PARITY_CHUNKS=
UMOTU_DA_PROVIDERS=

# Transaction broadcast mode
#UMOTU_TX_BROADCAST_MODE=sync
COMETBFT_RPC=http://127.0.0.1:26657
UMOTU_TX_BROADCAST_MODE=commit   # optional but helps surface errors


UMOTU_COMETBFT_RPC_TIMEOUT_MS=8000
UMOTU_COMETBFT_RPC_RETRY=5
UMOTU_COMETBFT_RPC_RETRY_BACKOFF_MS=250

UMOTU_TX_BROADCAST_MODE=sync

UMOTU_METRICS_APPLY_TX=true
UMOTU_METRICS_ALLOC_SAMPLE_N=100

UMOTU_PREP_LOG=1
UMOTU_PREP_LOG_SKIPS=1
```

Run
```
umotu-abci --abci.laddr tcp://0.0.0.0:26658 --http.addr :8080
```

Notes
- Replace placeholder addresses with deployed contract addresses.
- Ensure CometBFT `proxy_app` points at the ABCI listener (`tcp://127.0.0.1:26658`).
- JSON‑RPC is served at `http://127.0.0.1:8080/rpc`; WebSocket at `/ws`; health/metrics at `/healthz` and `/metrics`.