<!-- Source: https://docs.paxeer.app/sdk/ -->

# Cosmos SDK Fork

Paxeer's in-tree Cosmos SDK fork with Paxeer-specific modifications and extensions.

**Source:** `paxeer-network/sdk/`

## Overview

Paxeer vendors a fork of the Cosmos SDK directly in the monorepo under `paxeer-network/sdk/`. This is **not** a published Go module or npm package. It is an in-tree dependency for the `paxd` binary and Paxeer chain modules.

### Why a Fork?

Paxeer maintains a fork to support:

- Custom storage engines (MEMIAVL, Giga)

- EVM integration and pointer contracts

- Fast iteration without waiting for upstream releases

- Paxeer-specific consensus and execution optimizations

- Co-location with Paxeer modules and WASM runtime

## Upstream Base

The fork is based on Cosmos SDK but diverges significantly. It is not compatible with upstream Cosmos SDK releases without careful rebasing and testing.

**Warning:** Do not assume drop-in compatibility with standard Cosmos SDK tooling or libraries. Paxeer's SDK is a custom fork.

## Directory Structure

| Path | Purpose |
| --- | --- |
| `baseapp/` | Application framework (ABCI, routing, ante handlers) |
| `client/` | CLI framework and transaction builders |
| `server/` | Node server, gRPC, REST gateway |
| `types/` | Core SDK types (messages, coins, errors, context) |
| `x/` | Standard Cosmos modules (bank, auth, staking, gov, etc.) |
| `proto/` | Protobuf definitions for SDK modules |
| `store/` | State store abstraction and implementations |
| `simapp/` | Reference application for testing |

## Key Modules

Paxeer's SDK includes standard Cosmos modules:

| Module | Purpose |
| --- | --- |
| `x/auth` | Account authentication and transaction signing |
| `x/bank` | Token transfers and balance management |
| `x/staking` | Proof-of-Stake validator set and delegation |
| `x/distribution` | Staking rewards and fee distribution |
| `x/gov` | On-chain governance and proposals |
| `x/slashing` | Validator penalties for misbehavior |
| `x/crisis` | Invariant checking and chain halts |
| `x/evidence` | Double-sign evidence submission |
| `x/params` | Module parameter management |
| `x/upgrade` | Coordinated chain upgrades |

Plus Paxeer-specific modules under `paxeer-network/modules/`:

- `evm` — EVM execution and JSON-RPC

- `epoch` — Epoch tracking

- `oracle` — Price feeds

- `tokenfactory` — Custom token creation

- `mint` — Token minting

## BaseApp

The core application framework (`baseapp/`) handles:

- ABCI interface to Tendermint consensus

- Message routing to module handlers

- Ante handlers (gas, signatures, nonces)

- Transaction execution and state commits

- Query routing

Paxeer extends BaseApp for EVM transaction routing and concurrent execution (OCC).

## Client & Server

The SDK provides:

- **CLI:** `paxd` command-line interface (transaction builders, queries)

- **gRPC:** Module query and transaction services

- **REST:** HTTP gateway (gRPC-Gateway)

- **Tendermint RPC:** Block and transaction queries

See [REST & gRPC](https://docs.paxeer.app/rest-grpc) for API documentation.

## State Store

The SDK's `store/` abstraction is implemented by Paxeer's custom storage engines:

- **MEMIAVL:** In-memory IAVL tree (legacy)

- **Giga:** High-performance flat key-value store

See [Storage](https://docs.paxeer.app/storage) for engine details.

## Protobuf Definitions

SDK types are defined in `sdk/proto/`. Regenerate Go code with:

```
cd paxeer-network
ignite generate proto-go
```

Requires Ignite CLI v0.23.0. See `paxeer-network/api/README.md`.

## Building Against the SDK

Paxeer modules import the SDK from the in-tree path:

```
import (
    sdk "github.com/sidiora-labs/paxeer-network/sdk/types"
    "github.com/sidiora-labs/paxeer-network/sdk/store"
)
```

No `go.mod` replacement directives are needed because the SDK is part of the monorepo.

## Makefile Targets

The repository Makefile includes SDK-related targets:

```
# Build paxd
make build

# Run tests
make test

# Generate proto
make proto-gen
```

## Documentation

The SDK fork includes upstream Cosmos SDK documentation under `sdk/docs/`. Note that Paxeer-specific modifications may not be fully reflected in those docs.

### Upstream Resources

- [Cosmos SDK Docs](https://docs.cosmos.network/) (upstream, may diverge from Paxeer)

- [Cosmos Tutorials](https://tutorials.cosmos.network/) (upstream concepts apply)

- [GoDoc](https://pkg.go.dev/github.com/cosmos/cosmos-sdk) (upstream SDK, not Paxeer's fork)

**Warning:** Upstream documentation describes the standard Cosmos SDK, not Paxeer's fork. Treat it as reference only.

## Contributing to the Fork

Changes to `paxeer-network/sdk/` affect the entire Paxeer chain. Test thoroughly:

1. Edit code under `sdk/`
2. Rebuild `paxd`: `make build`
3. Run unit tests: `make test`
4. Test with [Docker cluster](https://docs.paxeer.app/docker): `make docker-cluster-start`
5. Run integration tests: `make test-integration`

## Differences from Upstream Cosmos SDK

Paxeer's SDK fork diverges from upstream in several areas:

- Custom storage backends (MEMIAVL, Giga)

- EVM module integration and pointer contracts

- Optimistic concurrency control (OCC) for parallel execution

- Receipt indexing and synthetic transactions

- Paxeer-specific ante handlers and gas metering

- Chain-specific upgrade logic

Do not assume compatibility with standard Cosmos SDK tooling (e.g., CosmJS, Keplr) without testing.

## Go Module Path

```
github.com/sidiora-labs/paxeer-network/sdk
```

This is an internal module within the Paxeer monorepo, not a standalone published module.