docs: rewrite and restructure docs

docs/concepts/data-availability.md

@@ -0,0 +1,72 @@
+# Data Availability
+
+Data availability (DA) ensures that all transaction data required to verify the chain's state is accessible to anyone.
+
+## Why DA Matters
+
+Without data availability guarantees:
+
+- Nodes can't verify state transitions
+- Users can't prove their balances
+- The chain's security model breaks down
+
+Evolve uses external DA layers to provide these guarantees, rather than storing all data on L1.
+
+## How Evolve Handles Data Availability
+
+Evolve currently supports two DA modes:
+
+### Local DA
+
+- **Use case**: Development and testing
+- **Guarantee**: None (operator can withhold data)
+- **Latency**: Instant
+
+### Celestia
+
+- **Use case**: Production deployments
+- **Guarantee**: Data availability sampling (DAS)
+- **Latency**: ~12 seconds to finality
+
+## DA Flow
+
+```
+Block Produced
+      │
+      ▼
+┌─────────────────┐
+│   Submitter     │  Queues block for DA
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   DA Layer      │  Stores and orders data
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   Full Nodes    │  Retrieve and verify
+└─────────────────┘
+```
+
+## Namespaces
+
+Evolve uses DA namespaces to organize data:
+
+| Namespace | Purpose |
+|-----------|---------|
+| Header | Block headers |
+| Data | Transaction data |
+| Forced Inclusion | User-submitted transactions |
+
+## Best Practices
+
+- **Development**: Use Local DA for fast iteration
+- **Testnet**: Use Celestia testnet (Mocha or Arabica)
+- **Production**: Use Celestia mainnet or equivalent
+
+## Learn More
+
+- [Local DA Guide](/guides/da-layers/local-da)
+- [Celestia Guide](/guides/da-layers/celestia)
+- [DA Interface Reference](/reference/interfaces/da)

docs/concepts/fee-systems.md

@@ -0,0 +1,157 @@
+# Fee Systems
+
+Evolve chains have two layers of fees: execution fees (paid to process transactions) and DA fees (paid to post data).
+
+## Execution Fees
+
+### EVM (ev-reth)
+
+Uses EIP-1559 fee model:
+
+```
+Transaction Fee = (Base Fee + Priority Fee) × Gas Used
+```
+
+| Component | Destination | Purpose |
+|-----------|-------------|---------|
+| Base Fee | Burned (or redirected) | Congestion pricing |
+| Priority Fee | Sequencer | Incentive for inclusion |
+
+#### Base Fee Redirect
+
+By default, base fees are burned. ev-reth can redirect them to a treasury:
+
+```json
+{
+  "config": {
+    "evolve": {
+      "baseFeeSink": "0xTREASURY",
+      "baseFeeRedirectActivationHeight": 0
+    }
+  }
+}
+```
+
+See [Base Fee Redirect](/ev-reth/features/base-fee-redirect) for details.
+
+### Cosmos SDK (ev-abci)
+
+Uses standard Cosmos SDK fee model:
+
+```
+Transaction Fee = Gas Price × Gas Used
+```
+
+Configure minimum gas prices:
+
+```toml
+# app.toml
+minimum-gas-prices = "0.025stake"
+```
+
+Fees go to the fee collector module and can be distributed via standard Cosmos mechanisms.
+
+## DA Fees
+
+Both execution environments incur DA fees when blocks are posted to the DA layer.
+
+### Cost Factors
+
+| Factor | Impact |
+|--------|--------|
+| Block size | Linear cost increase |
+| DA gas price | Market-driven, varies |
+| Batching | Amortizes overhead |
+| Compression | Reduces data size |
+
+### Who Pays?
+
+The sequencer pays DA fees from their own funds. They recover costs through:
+
+- Priority fees from users
+- Base fee redirect (if configured)
+- External subsidy
+
+### Optimization Strategies
+
+#### Lazy Aggregation
+
+Only produce blocks when there are transactions:
+
+```yaml
+node:
+  lazy-aggregator: true
+  lazy-block-time: 1s  # Max wait time
+```
+
+Reduces empty blocks and DA costs.
+
+#### Batching
+
+ev-node batches multiple blocks into single DA submissions:
+
+```yaml
+da:
+  batch-size-threshold: 100000  # bytes
+  batch-max-delay: 5s
+```
+
+#### Compression
+
+Enable blob compression:
+
+```yaml
+da:
+  compression: true
+```
+
+## Fee Flow Diagram
+
+```
+User Transaction
+      │
+      │ Pays: Gas Price × Gas
+      ▼
+┌─────────────────┐
+│    Sequencer    │
+│                 │
+│ Receives:       │
+│ - Priority fees │
+│ - Base fees*    │
+└────────┬────────┘
+         │
+         │ Pays: DA fees
+         ▼
+┌─────────────────┐
+│    DA Layer     │
+│   (Celestia)    │
+└─────────────────┘
+
+* If base fee redirect is enabled
+```
+
+## Estimating Costs
+
+### Execution Costs
+
+EVM:
+
+```bash
+cast estimate --rpc-url http://localhost:8545 <CONTRACT> "transfer(address,uint256)" <TO> <AMOUNT>
+```
+
+Cosmos:
+
+```bash
+appd tx bank send <FROM> <TO> 1000stake --gas auto --gas-adjustment 1.3
+```
+
+### DA Costs
+
+Depends on:
+
+- DA layer pricing (e.g., Celestia gas price)
+- Data size per block
+- Submission frequency
+
+Use the [Celestia Gas Calculator](/guides/tools/celestia-gas-calculator) for estimates.

docs/concepts/finality.md

@@ -0,0 +1,55 @@
+# Finality
+
+Finality determines when a transaction is irreversible. Evolve has a multi-stage finality model.
+
+## Finality Stages
+
+```
+Transaction Submitted
+        │
+        ▼
+┌───────────────────┐
+│  Soft Confirmed   │  ← Block produced, gossiped via P2P
+└─────────┬─────────┘
+          │
+          ▼
+┌───────────────────┐
+│   DA Finalized    │  ← DA layer confirms inclusion
+└───────────────────┘
+```
+
+### Soft Confirmation
+
+When a block is produced and gossiped via P2P:
+
+- **Latency**: Milliseconds (block time)
+- **Guarantee**: Sequencer has committed to this ordering
+- **Risk**: Sequencer could equivocate (produce conflicting blocks)
+
+### DA Finalized
+
+When the DA layer confirms the block is included:
+
+- **Latency**: ~6 seconds (Celestia)
+- **Guarantee**: Block data is permanently available and ordered
+- **Risk**: None (assuming DA layer security)
+
+## Choosing Finality Thresholds
+
+| Use Case | Recommended Finality |
+|----------|---------------------|
+| Display balance | Soft confirmation |
+| Accept payment | Soft confirmation |
+| Process withdrawal | DA finalized |
+| Bridge transfer | DA finalized |
+
+## Configuration
+
+Block time affects soft confirmation latency:
+
+```yaml
+node:
+  block-time: 100ms
+```
+
+DA finality depends on the DA layer. Celestia provides ~6 second finality.

docs/concepts/p2p-networking.md

@@ -0,0 +1,60 @@
+# P2P
+
+Every node (both full and light) runs a P2P client using [go-libp2p][go-libp2p] P2P networking stack for gossiping transactions in the chain's P2P network. The same P2P client is also used by the header and block sync services for gossiping headers and blocks.
+
+Following parameters are required for creating a new instance of a P2P client:
+
+* P2PConfig (described below)
+* [go-libp2p][go-libp2p] private key used to create a libp2p connection and join the p2p network.
+* chainID: identifier used as namespace within the p2p network for peer discovery. The namespace acts as a sub network in the p2p network, where peer connections are limited to the same namespace.
+* datastore: an instance of [go-datastore][go-datastore] used for creating a connection gator and stores blocked and allowed peers.
+* logger
+
+```go
+// P2PConfig stores configuration related to peer-to-peer networking.
+type P2PConfig struct {
+	ListenAddress string // Address to listen for incoming connections
+	Seeds         string // Comma separated list of seed nodes to connect to
+	BlockedPeers  string // Comma separated list of nodes to ignore
+	AllowedPeers  string // Comma separated list of nodes to whitelist
+}
+```
+
+A P2P client also instantiates a [connection gator][conngater] to block and allow peers specified in the `P2PConfig`.
+
+It also sets up a gossiper using the gossip topic `<chainID>+<txTopicSuffix>` (`txTopicSuffix` is defined in [p2p/client.go][client.go]), a Distributed Hash Table (DHT) using the `Seeds` defined in the `P2PConfig` and peer discovery using go-libp2p's `discovery.RoutingDiscovery`.
+
+A P2P client provides an interface `SetTxValidator(p2p.GossipValidator)` for specifying a gossip validator which can define how to handle the incoming `GossipMessage` in the P2P network. The `GossipMessage` represents message gossiped via P2P network (e.g. transaction, Block etc).
+
+```go
+// GossipValidator is a callback function type.
+type GossipValidator func(*GossipMessage) bool
+```
+
+The full nodes define a transaction validator (shown below) as gossip validator for processing the gossiped transactions to add to the mempool, whereas light nodes simply pass a dummy validator as light nodes do not process gossiped transactions.
+
+```go
+// newTxValidator creates a pubsub validator that uses the node's mempool to check the
+// transaction. If the transaction is valid, then it is added to the mempool
+func (n *FullNode) newTxValidator() p2p.GossipValidator {
+```
+
+```go
+// Dummy validator that always returns a callback function with boolean `false`
+func (ln *LightNode) falseValidator() p2p.GossipValidator {
+```
+
+## References
+
+[1] [client.go][client.go]
+
+[2] [go-datastore][go-datastore]
+
+[3] [go-libp2p][go-libp2p]
+
+[4] [conngater][conngater]
+
+[client.go]: https://github.com/evstack/ev-node/blob/main/pkg/p2p/client.go
+[go-datastore]: https://github.com/ipfs/go-datastore
+[go-libp2p]: https://github.com/libp2p/go-libp2p
+[conngater]: https://github.com/libp2p/go-libp2p/tree/master/p2p/net/conngater