# Aje — Systems Deep Dive

> The `libs/aje/` area: ~39 Nx libraries that make up Oshun's multi-chain
> **blockchain / Web3 infrastructure** stack — from low-level cryptographic
> primitives and RPC transport up through DeFi, NFT, DePIN, ZK, wallet, and
> merchant-settlement domains.

## What this area is

"Aje" is Oshun's crypto/blockchain platform. Unlike a single SDK, it is a
**fleet of independent Nx libraries** (every `project.json` here is `scope:aje`,
almost all `layer:domain` / `type:lib`; `@aje/rpc` is the one `layer:infra`
node) layered into a dependency graph from primitives upward. Every barrel
`src/index.ts` re-exports a set of feature namespaces (e.g. `@aje/defi` exposes
`amm`, `uniswap`, `curve`, `lending`, `liquidStaking`, `yieldAggregation`,
`derivatives`, `safety`), so a consumer pulls one package and reaches a whole
domain's surface. The code is substantial and real — tens of thousands of lines
per major lib with dense `*.spec.ts` coverage (e.g. `@aje/bitcoin` carries 57
spec files, `@aje/chains` 60, `@aje/governance` 56, `@aje/payments` 46) — not
scaffolding. There are no `README.md` files in the area; the module-level JSDoc
on each `index.ts` is the authoritative description.

The stack divides into roughly three tiers. **Foundation:** `@aje/core`
(addresses, transactions, BigNumber, blocks, keccak/secp256k1/sha crypto, ABI,
Merkle), `@aje/rpc` (the `OshunRpcClient` transport orchestrator),
`@aje/database` (chain-aware schemas + indexer), `@aje/contracts` (Solidity/
Aiken toolchain), `@aje/wallets` + `@aje/account-abstraction` (key management
and ERC-4337/7702/7579), and `@aje/security`. **Chain access:** the big
`@aje/chains` package (Ethereum L1, Arbitrum, Optimism/OP Stack, zkSync, Polygon
& L2s, Avalanche, Cardano, Solana, plus a chain-abstraction layer),
`@aje/bitcoin` (Lightning, Stacks, sBTC, BitVM, Ordinals/Runes/RGB),
`@aje/nodes`, and a cluster of focused **V1 merchant-flow** per-chain clients
under `libs/aje/chains/` (Cardano, Ergo, Litecoin, Monero, Solana, TON, Tron)
that are deliberately watch-only — they own RPC + per-invoice address
derivation + confirmation policy and are explicit in their JSDoc that
signing/key-derivation live in upstream node binaries. **Applications:** DeFi,
NFT, oracles, governance, identity, payments, predictions, intents, bridges,
restaking, storage, RWA, privacy, ZKP, DePIN, gaming, appchains, agents,
Sui/Move, the developer `@aje/sdk`, and the Concordia-facing
`@aje/settlement-escrow`.

The per-chain merchant-flow libraries share a recognizable internal shape: a
`types.ts`, a `provider.ts`/`node-client.ts` HTTP client, a per-invoice address
allocator (CIP-1852, BIP44 xpub, v4r2 subwallet, ed25519, etc.), an
`invoice-observer` / indexer that watches confirmations, and a
`disclosure`/issuer-trust renderer. Once you have read one (e.g.
`@aje/chains-cardano`) you can navigate the rest.

## How it fits the wider system

Within the area, the application libraries compose downward onto the foundation
and chain-access tiers (DeFi/NFT/governance build on `@aje/core` types and
`@aje/chains`/`@aje/rpc` for on-chain reads and writes; `@aje/database` is built
"on `@oshun/database` foundation with `@aje/core` blockchain types" per its
JSDoc). Outside the area, consumption is targeted rather than blanket: the V2
game services (`aje-faction-governance`, `aje-web3-cosmetic-ownership`),
`libs/calliope/nexus`, and the Themis constitution/DAO libraries import
`@aje/governance`, `@aje/nft`, `@aje/wallets`, `@aje/identity`, and
`@aje/contracts`. `@aje/settlement-escrow` is the bridge into the wider Oshun
business layer — it maps `@concordia/contracts` `escrow_release` clauses (Phase
179.7.2.4) into chain-ready deployment plans, the one node here carrying a
`phase:179` tag. Walk the "used by" edges on any node below to see its exact
consumers.

## Entity reference

### @aje/core

Foundation blockchain primitives (`libs/aje/core/src`). Its barrel exports
address handling, transaction types, BigNumber arithmetic, block structures, and
a large cryptographic surface — `keccak256`, `sha256`/`sha512`, `blake2b`,
`ripemd160`, `hash160`, `doubleSha256`, EIP-712 `hashTypedData`, and
`secp256k1Sign`/`Verify`/`ecrecover` — plus ABI encode/decode, events, Merkle
trees, network config, and errors. It is the type-and-utility bedrock the rest
of the Aje stack builds on; 48 source files with 10 spec files.

### @aje/rpc

The one `layer:infra` node (`libs/aje/rpc/src`). It exports `OshunRpcClient`, a
chain-agnostic JSON-RPC orchestrator that routes calls across one or more
transports with retry (`withRetry`/`DEFAULT_RETRY_POLICY`), fallback strategies,
rate-limiting, and multi-RPC fan-out, tracking per-endpoint EMA latency and
recent failures (`EndpointStat`). Typed chain providers (`EthereumRpcProvider`,
`BitcoinRpcProvider`, `AvalancheRpcProvider`, `SolanaRpcProvider`) wrap it and a
full taxonomy of `RpcError` subclasses (`RpcExhaustedError`, `RpcQuorumError`,
`RpcRateLimitError`, …) models failure modes. Real transport logic with 11 spec
files.

### @aje/database

Blockchain-specific persistence (`libs/aje/database/src`), built on
`@oshun/database` with `@aje/core` types per its JSDoc. The barrel namespaces
`coreSchema` (chain config, blocks, transactions, contracts, balances),
`defiSchema` (DEX swaps, pools, lending, yield, portfolio), `walletSchema`
(wallets, DID/identity, history, compliance), `indexer` (block ingestion,
contract indexing, API layer, health monitoring), and `maintenance` (ORM,
migrations, seed data, performance). 35 files with 24 spec files.

### @aje/contracts

A smart-contract development toolkit (`libs/aje/contracts/src`) — not to be
confused with the `@oshun/contracts` Zod package. It namespaces `compilation`
(Solidity compiler management, artifacts, source maps), `deployment` (CREATE2,
factory, multi-chain, verification), `upgradeable` (UUPS/Transparent/Beacon/
Diamond EIP-2535), `openzeppelin`, Uniswap V4 `hooks`, `testing`, `fuzzing`,
Cardano `aiken`, `documentation` (NatSpec), and `gasOptimization`. The
`artifacts.ts` module handles real Solidity unlinked-library `__$…$__`
link-reference placeholders (annotated `// stub:legitimate`, i.e. genuine
bytecode syntax, not a code stub).

### @aje/wallets

Wallet infrastructure (`libs/aje/wallets/src`). The barrel exposes `hdWallet`
(BIP-39/32/44/84/86 multi-chain), `keyManagement` (keystore, Shamir, policies),
`mpc` (TSS/DKG ceremonies), `accountAbstraction` (ERC-4337), `paymaster`
(verifying/token/NFT/subscription), and — per the module JSDoc — hardware
wallet, session keys, social login, and WalletConnect support. 51 files. A
consumer of this package is `libs/calliope/nexus`'s blockchain virtual-item
manager.

### @aje/account-abstraction

Account-abstraction enhancements beyond basic ERC-4337
(`libs/aje/account-abstraction/src`). Namespaces `eip7702` (set-code-for-EOAs
delegation), `erc7715` (grant permissions), `erc7579` (modular smart accounts),
`erc6900` (Alchemy modular accounts), and `advancedAA` infrastructure — keyed to
spec sections §37.26.1–5 in the source. 16 files, 18.5k lines.

### @aje/security

Smart-contract and protocol security tooling (`libs/aje/security/src`):
`staticAnalysis`, `formalVerification`, `mevProtection`, `runtimeProtection`,
`auditTooling`, and `incidentResponse`. The `mev-protection/encryption.ts`
module is a real building-block (its comment explicitly scopes it as a
lightweight encryption primitive, not a faked result). 36 files with 23 spec
files.

### @aje/chains

The large multi-chain access package (`libs/aje/chains/src`, 68 files / 51k
lines / 60 specs). It namespaces `ethereum` (JSON-RPC, providers, WebSocket,
Multicall3, Flashbots, debug/trace), `arbitrum` (Orbit, Stylus), `optimism` (OP
Stack/Base), `zksync` (EIP-712, paymasters, native AA), `polygon` (PoS, zkEVM,
Linea, Scroll, Starknet with cross-L2 routing), `avalanche` (C/X/P, subnets,
AWM/Teleporter), `cardano` (UTxO, Plutus, Hydra, CIP-1694), `solana` (RPC, SPL,
Anchor, Jito), and an `abstraction` layer (unified provider, registry,
transaction builder, address resolver). The `solana/transaction.ts` signature
`sigPlaceholders` are real zeroed signature slots in transaction serialization,
not stubs.

### @aje/chains-abstraction

EVM merchant-flow substrates for Aje crypto payments, §23.1.6
(`libs/aje/chains/abstraction/src`). Exports a per-chain `chain-registry`, a
BIP44 `xpub-watcher`, `multi-rpc-consensus`, a `reorg-depth` policy, an
`ens-refund` resolver, and an `issuer-trust-disclosure` renderer. Seven focused
modules with seven specs — the EVM counterpart to the per-chain merchant clients
below.

### @aje/chains-cardano

Cardano V1 merchant-flow substrate (`libs/aje/chains/cardano/src`). A watch-only
Ogmios / cardano-wallet HTTP client (`node-client`), a CIP-1852 per-invoice
address allocator (`cardano-address`), and a UTXO-polling `invoice-observer`
with ADA-only policy, multi-asset refund proposals, and 15/30-confirmation
tiers. Small and honest: signing is out of scope by design.

### @aje/chains-ergo

Ergo node REST client (`libs/aje/chains/ergo/src`): `types`, `provider`,
`ergo-address`, a `p2pk-allocator`, `invoice-observer`, and a `nipopow-receipt`.
Its JSDoc is explicit that ErgoTree compilation and signing live in upstream
sigma-rust / appkit binaries — this lib covers info/blocks/headers, UTXO box
lookup, transactions, and mempool size only.

### @aje/chains-litecoin

Litecoin Core JSON-RPC client (`libs/aje/chains/litecoin/src`): `types`,
`provider`, `core-client`, and an `rbf-detector`. The wire shape is
bitcoind-22.x compatible, surfacing MWEB fields through `getblock`/
`getrawtransaction` when the node has MWEB enabled; per its JSDoc, key
derivation and PSBT signing live upstream — this client forwards intent and
reads structured responses.

### @aje/chains-monero

Monero JSON-RPC client (`libs/aje/chains/monero/src`) wrapping monerod and
monero-wallet-rpc over HTTP. It exports `provider`, `monerod-client`,
`wallet-rpc`, a `subaddress-allocator`, `confirmation-policy`, `payment-proof`,
`refund-flow`, `telemetry`, and `invariants`. CryptoNote primitives (stealth
addresses, ring signatures, view-key scanning) are explicitly upstream; this
module owns only the RPC client. 12 files, 10 specs.

### @aje/chains-solana

Solana merchant-flow substrate (`libs/aje/chains/solana/src`): an `rpc-client`
with multi-RPC consensus and rate-limit rotation, ed25519 per-invoice
`derivation`, an `indexer` for native SOL + SPL tokens (USDC-SOL/USDT-SOL), a
`solana-pay-url` generator, a `commitment-policy`, and a Tier-B/issuer-trust
`disclosure` renderer. Distinct from the broader `solana` namespace inside
`@aje/chains`; this is the V1 invoice-lifecycle slice.

### @aje/chains-ton

TON HTTP API / toncenter v2 client (`libs/aje/chains/ton/src`): `provider`,
`full-node-client` with health tracking, real v4r2 per-invoice `subwallet`
derivation (using `@ton/core` canonical cell hashing in-process), a native +
jetton `indexer`, a Telegram @wallet `wallet-deeplink` generator, and a Tier-C
`disclosure` renderer. Signing lives in the operator's cold-spend toolchain.

### @aje/chains-tron

Tron Full Node + Solidity Node HTTP API client (`libs/aje/chains/tron/src`),
scoped to the subset Aje needs for USDT-TRC20 settlement: `node-client`,
`usdt-trc20` handling, `tron-address`, and a `disclosure` renderer. Covers
latest block, block-by-number, account (incl. TRC-20 balances), transaction
info, and broadcast; signing and key derivation live in upstream wallet
processes.

### @aje/bitcoin

The largest Bitcoin-ecosystem package (`libs/aje/bitcoin/src`, 81 files / 57
specs). The barrel namespaces `btcpay`, `shared`, `lightning`, `lsp` (Lightning
service providers), `lnApps`, `stacks`, `sbtc`, `bitvm`, `ordinals`, `runes`,
`rgb`, and `otherL2s`. This is the full Bitcoin Layer-2 and metaprotocol surface
in one library.

### @aje/nodes

Node operation and access (`libs/aje/nodes/src`): `rpc`, `fullNode`,
`avalancheNode`, `cardanoNode`, `lightClient`, and `validator`. Six namespaces,
50 files, 21 specs — the operator-facing counterpart to the read-only chain
clients.

### @aje/defi

Decentralized-finance protocols (`libs/aje/defi/src`, 82 files / 26k lines).
Namespaces `amm`, `uniswap`, `curve`, `lending`, `liquidStaking`,
`yieldAggregation`, `derivatives`, `cardanoDefi`, `avalancheDefi`, and `safety`.
The `amm/constant-product.ts` carries the genuine Uniswap-V2 fee math
(`getAmountOut` with `FEE_DENOMINATOR = 10000n`, the 0.3% `amountInWithFee`
formula, `MINIMUM_LIQUIDITY = 1000n`), alongside concentrated-liquidity,
stableswap, weighted-pool, oracle, router, and MEV-protection modules.

### @aje/nft

NFT infrastructure (`libs/aje/nft/src`): `erc721`, `erc721a` (gas-optimized
batch mint), `erc1155`, `tokenBound` (ERC-6551), `soulbound`, `dynamic`,
`marketplace`, `cardanoNft`, `metadata`, and `aiNft`. 71 files, 10 specs;
consumed by the V2 web3-cosmetic-ownership service and `libs/calliope/nexus`.

### @aje/oracles

Oracle integrations (`libs/aje/oracles/src`): the Chainlink family
(`chainlinkFeeds`, `chainlinkVrf`, `chainlinkAutomation`, `chainlinkFunctions`),
plus `pyth`, `redstone`, `api3`, and a `customOracle` builder. 52 files, 8
specs.

### @aje/governance

On-chain governance (`libs/aje/governance/src`, 71 files / 56 specs): `governor`
(OZ Governor), `voting`, `snapshot` (off-chain signaling), `tally`, `treasury`,
`aragon`, and `cardanoGovernance`. It is the most externally consumed Aje node —
used by V2's faction-governance service and the Themis constitution / DAO /
governance-execution-bridge libraries.

### @aje/identity

Decentralized identity (`libs/aje/identity/src`): `did`, verifiable
`credentials`, `ens`, `lens`, `farcaster`, and an `aggregation` layer that
unifies them. 42 files, 6 specs; imported by `libs/themis/integrations`.

### @aje/payments

Payments and settlement (`libs/aje/payments/src`, 59 files / 46 specs):
`stablecoins`, `circle` (USDC/CCTP), `fiatRamps`, `merchant`, `streaming`
(Sablier/Superfluid-style), and `cbdc`. The application-tier complement to the
low-level per-chain merchant-flow clients.

### @aje/predictions

Prediction-market infrastructure (`libs/aje/predictions/src`, §37.25):
`polymarket` integration, prediction-market `contracts`, resolution `oracles`,
`marketMaking` infrastructure, and `analytics`. 16 files, 19k lines, 5 specs.

### @aje/intents

Intent-based architecture and solver networks (`libs/aje/intents/src`, §37.22):
`expression` (intent specification), `solvers` (solver-network infrastructure),
`cow` (CoW Protocol), `uniswapx`, `across` (Across Protocol bridging), and
Essential intent infrastructure. 47 files, 25k lines.

### @aje/bridges

Cross-chain bridge infrastructure (`libs/aje/bridges/src`): `layerzero` (V2),
`wormhole`, `ccip` (Chainlink), `axelar`, `customBridge` development,
`avalancheWarp` (AWM), bridge `security`, and `aggregation` (multi-bridge
routing). 29 files, 9 specs.

### @aje/restaking

EigenLayer restaking and AVS development (`libs/aje/restaking/src`):
`eigenlayer` (restaking core), `avs` (actively-validated-service development),
and `lrt` (liquid restaking tokens). Three namespaces, 10 files, 3 specs.

### @aje/storage

Decentralized storage (`libs/aje/storage/src`): `ipfs`, `filecoin`, `arweave`, a
`hybrid` strategy layer, and `nftStorage`. 33 files, 5 specs — the storage
backend the NFT/metadata libraries pin to.

### @aje/rwa

Real-world-asset tokenization (`libs/aje/rwa/src`, 61 files / 48 specs):
`securityTokens`, `treasuryTokenization`, `realEstate`, `commodities`,
`compliance`, and `chainlinkRwa` (proof-of-reserve / NAV feeds). One of the more
heavily tested application libs.

### @aje/privacy

Compliance-friendly privacy infrastructure (`libs/aje/privacy/src`):
`privacyPools` (Privacy Pools association-set model) and `advancedPrivacy`. The
smallest application lib — 7 files, 2 specs — but real, not a scaffold.

### @aje/zkp

Zero-knowledge-proof toolkit (`libs/aje/zkp/src`, 71 files / 23k lines):
`snarks` (Groth16, PLONK, aggregation, trusted setup — see
`snarks/groth16.ts`/`plonk.ts`/`setup.ts`), `circom`, `starks`, `privacy`,
`semaphore`, `zkml`, `rollups`, `gnark`, `plonky`, and `zkIdentity`. A broad
ZK-stack surface across multiple proving systems.

### @aje/depin

Decentralized Physical Infrastructure Networks (`libs/aje/depin/src`, §37.21, 22
files / 31k lines): `compute`, `wireless`, `iot` (sensors), `location`
(mapping), `energy` (grid trading), `storage`, and DePIN rewards/economics. Few
files but very dense — the largest per-file footprint in the area.

### @aje/gaming

On-chain games and autonomous worlds (`libs/aje/gaming/src`, §37.24): `mud` (MUD
framework), `worldEngine`, game `assets`, game `economy`, `autonomous` world
patterns, and `gamingL2s`. 19 files, 25k lines.

### @aje/appchains

Rollup-as-a-Service and appchain deployment (`libs/aje/appchains/src`, §37.23):
`conduit`, `caldera`, `altlayer` (restaked rollups), `da` (data-availability
layers), `sequencer` (shared sequencing), and `config`. 19 files, 21k lines.

### @aje/agents

AI-agent infrastructure for blockchain operations (`libs/aje/agents/src`,
§37.20): agent `wallets`, on-chain `execution`, agent-to-agent `communication`,
the `x402` payment protocol, `ai` model integration, agent `frameworks`
connectors, and `safety`/governance controls. 22 files, 28k lines, 7 specs.

### @aje/sui-move

Sui and Move ecosystem utilities (`libs/aje/sui-move/src`): `suiNetwork`,
`moveLanguage` (Move toolchain), `suiDefi`, and `aptos` integration. 13 files, 4
specs — a non-EVM ecosystem slice parallel to the Cardano and Solana coverage
elsewhere in the area.

### @aje/sdk

The developer-facing SDK (`libs/aje/sdk/src`, 47 files / 34k lines — the highest
line count in the area): a `core` TypeScript/JS SDK, `react` hooks, `python` SDK
generation, a `cli`, and `docs` utilities. It packages the rest of the Aje stack
into an external-developer surface; 33 spec files.

### @aje/settlement-escrow

The Concordia bridge node (`libs/aje/settlement-escrow/src`), the one entity
tagged `phase:179`. A small (199-line) but real Zod-validated adapter:
`escrow-adapter.ts` maps `@concordia/contracts` `escrow_release` clauses to a
chain-ready `EscrowDeploymentPlan` — `planDeployment(...)` produces milestone
checksums, total-release verification (`superRefine`), supported-chain/oracle
enums (`EscrowChainSchema`, `OracleSourceSchema`), arbitration-backstop binding,
and `nextMilestoneAfter(...)`. This is the seam where Aje's on-chain settlement
meets the wider Oshun business layer (§179.7.2.4).