# Aje Domain

> **Aje** - Blockchain, DeFi, and Web3 Infrastructure

Library-only domain providing comprehensive blockchain infrastructure spanning
wallet management, multi-chain network support, DeFi protocols, NFT standards,
smart contract tooling, zero-knowledge proofs, cross-chain bridges, identity
systems, prediction markets, and AI-powered blockchain agents. Named after the
Yoruba orisha of commerce and wealth.

---

## Overview

The Aje domain is the blockchain and Web3 pillar of the Oshun monorepo. It
provides a layered architecture where `@aje/core` defines foundational
cryptographic primitives, address handling, and transaction types, while
higher-level libraries build on that foundation to deliver chain-specific
providers, DeFi protocol integrations, wallet infrastructure, and developer
tooling. Every library in this domain uses audited cryptographic dependencies
from the `@noble` and `@scure` families rather than rolling custom crypto.

---

## Architecture

```
                              @aje/sdk
                         (unified developer SDK)
                                 |
          +----------+-----------+-----------+----------+
          |          |           |           |          |
     @aje/wallets  @aje/defi  @aje/nft  @aje/bridges  @aje/contracts
          |          |           |           |          |
          +----------+-----------+-----------+----------+
                                 |
                            @aje/chains
                    (multi-chain network layer)
                                 |
                            @aje/core
                  (crypto primitives, addresses, ABI)
                                 |
                         @oshun/types
                    (shared monorepo types)
```

All domain libraries depend on `@aje/core` as a peer dependency. Libraries
needing chain interactions additionally depend on `@aje/chains`. The
`@aje/database` library bridges into the shared `@oshun/database` foundation.

---

## Libraries (29)

### `@aje/core` - Core Blockchain Primitives

Foundation library providing multi-chain address handling (EVM, Solana, Cardano,
Bitcoin), transaction type definitions, block structures, ABI encoding/decoding,
cryptographic utilities (hashing, signing, key derivation), BigNumber arithmetic
helpers, Merkle tree implementations, event log parsing, and network
configuration. Uses `@noble/hashes`, `@noble/curves`, `@scure/base`,
`@scure/bip32`, and `@scure/bip39`.

**Key exports:** `addresses`, `transactions`, `bignum`, `blocks`, `crypto`,
`abi`, `events`, `merkle`, `network`, `errors`

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`,
`@scure/bip32`, `@scure/bip39`, peer `@oshun/types`

### `@aje/chains` - Multi-Chain Network Layer

Comprehensive multi-chain infrastructure providing low-level and high-level
interfaces for interacting with multiple blockchain networks. Includes
chain-specific provider modules:

- **ethereum** - JSON-RPC providers, WebSocket subscriptions, Multicall3
  batching, Flashbots integration, debug/trace APIs
- **arbitrum** - L2 provider, gas estimation, L1-L2 messaging, bridge
  interactions, Orbit chains, Stylus WASM contracts
- **optimism** - OP Stack support covering Optimism and Base, gas estimation,
  cross-domain messaging, bridge operations
- **zksync** - zkSync Era with EIP-712 transactions, paymasters, native account
  abstraction, ZK Stack tooling
- **polygon** - Polygon PoS, zkEVM, Linea, Scroll, and Starknet with multi-L2
  providers and cross-L2 routing
- **avalanche** - C/X/P chains, subnet creation, Avalanche Warp Messaging,
  Teleporter, and custom VM development
- **cardano** - UTxO model, Plutus V2/V3 smart contracts, Hydra L2, CIP-1694
  governance
- **solana** - RPC client, transaction building, SPL tokens, Anchor framework,
  Jito MEV protection
- **abstraction** - Chain abstraction layer with unified provider interface,
  chain registry, transaction builder, and address resolver

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`, peer
`@aje/core`

### `@aje/wallets` - Wallet Infrastructure

Comprehensive wallet infrastructure for Web3 applications providing:

- **hdWallet** - BIP-39 mnemonic generation, BIP-32/44/84/86 HD derivation,
  multi-chain key paths
- **keyManagement** - Encrypted keystore, Shamir secret sharing, key rotation
  policies
- **mpc** - Multi-party computation wallets with threshold signature schemes
  (TSS), distributed key generation (DKG), ceremony management
- **accountAbstraction** - ERC-4337 smart accounts, UserOperation building,
  bundler integration
- **paymaster** - Verifying paymaster, token paymaster, NFT-gated sponsorship,
  subscription models
- **hardwareWallet** - Ledger and Trezor integration for transaction signing
- **sessionKeys** - Delegated session keys with scoped permissions and
  expiration
- **socialLogin** - OAuth-based embedded wallets for Web2 user onboarding
- **walletConnect** - WalletConnect V2 protocol, session management, deep
  linking
- **institutional** - Institutional custody with multi-signature policies,
  compliance controls, and audit trails

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`,
`@scure/bip32`, `@scure/bip39`, peer `@aje/core`

### `@aje/defi` - DeFi Protocol Integrations

Decentralized finance protocol library covering:

- **amm** - Automated market maker math (constant product, concentrated
  liquidity, weighted pools)
- **uniswap** - Uniswap V2/V3/V4 integration (routing, quoting, position
  management)
- **curve** - Curve Finance StableSwap and CryptoSwap interactions
- **lending** - Aave, Compound, and Morpho lending protocol interfaces
- **liquidStaking** - Lido, Rocket Pool, and other liquid staking derivatives
- **yieldAggregation** - Yield farming strategy aggregation and optimization
- **derivatives** - On-chain derivatives, perpetuals, and options protocols
- **cardanoDefi** - Cardano-native DeFi (Minswap, SundaeSwap, Liqwid)
- **avalancheDefi** - Avalanche DeFi (Trader Joe, Platypus, GMX)
- **safety** - DeFi safety monitoring, rug-pull detection, and risk assessment

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`, peer
`@aje/core`, `@aje/chains`

### `@aje/contracts` - Smart Contract Toolkit

Complete smart contract development toolkit:

- **compilation** - Solidity compiler management, artifact generation, source
  map processing, optimization settings
- **deployment** - CREATE2 deterministic deployment, factory patterns,
  multi-chain deployment, Etherscan verification, deployment manifests
- **upgradeable** - Proxy patterns (UUPS, Transparent, Beacon, Diamond
  EIP-2535), storage layout safety checks
- **openzeppelin** - OpenZeppelin template integration for ERC-20/721/1155,
  access control, governance modules
- **hooks** - Uniswap V4 hook development (swap/liquidity hooks, dynamic fees,
  TWAMM, limit orders)
- **testing** - Testing infrastructure bridging Hardhat and Foundry, cheatcodes,
  custom matchers, fixtures, coverage reporting
- **fuzzing** - Property testing with Echidna and Foundry, invariant checking,
  corpus management, CI/CD integration
- **aiken** - Cardano smart contract development with Aiken language, validator
  scaffolding, minting policies, Lucid integration
- **documentation** - NatSpec parsing, markdown generation, API reference
  creation, changelog management
- **gasOptimization** - Gas profiling, storage analysis, struct packing
  optimization, gas budget enforcement

**Dependencies:** `@noble/hashes`, `@scure/base`, peer `@aje/core`,
`@aje/chains`

### `@aje/nft` - NFT Standards and Marketplace

NFT infrastructure covering all major standards and marketplace interactions:

- **erc721** - ERC-721 minting, transfers, and metadata
- **erc721a** - Gas-optimized batch minting via ERC-721A
- **erc1155** - Multi-token standard for fungible/non-fungible hybrids
- **tokenBound** - Token-bound accounts (ERC-6551) for NFTs owning assets
- **soulbound** - Non-transferable soulbound tokens for credentials
- **dynamic** - Dynamic NFTs with mutable metadata and on-chain state
- **marketplace** - Marketplace integration (OpenSea Seaport, Blur, custom)
- **cardanoNft** - Cardano-native NFT minting and CIP-25/68 metadata
- **metadata** - On-chain and off-chain metadata management, IPFS pinning
- **aiNft** - AI-generated NFT art pipelines and provenance tracking

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`, peer
`@aje/core`, `@aje/chains`

### `@aje/bridges` - Cross-Chain Bridge Infrastructure

Cross-chain bridge protocols and aggregation:

- **layerzero** - LayerZero V2 OApp/OFT development, message passing, executor
  configuration
- **wormhole** - Wormhole cross-chain messaging, token transfers, NTT framework
- **ccip** - Chainlink CCIP token and message transfers, fee estimation
- **axelar** - Axelar General Message Passing, cross-chain token transfers
- **customBridge** - Custom bridge development framework with relay management
- **avalancheWarp** - Avalanche Warp Messaging for subnet-to-subnet
  communication
- **security** - Bridge security validation, proof verification, message
  integrity checking
- **aggregation** - Bridge aggregator for optimal route finding across protocols

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`, peer
`@aje/core`, `@aje/chains`

### `@aje/zkp` - Zero-Knowledge Proofs

Comprehensive ZK proof library:

- **snarks** - zk-SNARK proof generation and verification (Groth16, PLONK)
- **circom** - Circom circuit compilation, witness generation, trusted setup
- **starks** - zk-STARK proof systems for transparent setup
- **privacy** - Privacy-preserving transaction construction
- **semaphore** - Semaphore identity and signal protocol for anonymous signaling
- **zkml** - Zero-knowledge machine learning proof generation
- **rollups** - ZK rollup proof aggregation and settlement
- **gnark** - Go-based gnark circuit integration
- **plonky** - Plonky2/3 recursive proof systems
- **zkIdentity** - ZK-based identity verification without data disclosure

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`, peer
`@aje/core`, `@aje/chains`

### `@aje/identity` - Blockchain Identity Systems

Decentralized identity infrastructure:

- **did** - W3C DID Document creation, resolution, and management
- **credentials** - Verifiable Credentials (VCs) issuance and verification
- **ens** - Ethereum Name Service resolution, registration, and management
- **lens** - Lens Protocol profile and social graph integration
- **farcaster** - Farcaster protocol identity and hub interactions
- **aggregation** - Cross-platform identity aggregation and linking

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`, peer
`@aje/core`, `@aje/chains`

### `@aje/governance` - On-Chain Governance

DAO and governance protocol integration:

- **governor** - OpenZeppelin Governor contract interaction, proposal lifecycle
- **voting** - Voting power calculation, delegation, and snapshot integration
- **snapshot** - Snapshot off-chain voting with on-chain execution
- **tally** - Tally governance dashboard integration
- **treasury** - Timelock treasury management and fund disbursement
- **aragon** - Aragon DAO framework integration
- **cardanoGovernance** - Cardano CIP-1694 governance actions, DRep delegation

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`, peer
`@aje/core`, `@aje/chains`

### `@aje/oracles` - Oracle Integration

Price feeds and off-chain data infrastructure:

- **chainlinkFeeds** - Chainlink Data Feeds for price and reserve data
- **chainlinkVrf** - Chainlink VRF for provably random number generation
- **chainlinkAutomation** - Chainlink Automation (Keepers) for contract upkeep
- **chainlinkFunctions** - Chainlink Functions for arbitrary off-chain compute
- **pyth** - Pyth Network high-frequency price feeds
- **redstone** - RedStone oracle with on-demand data delivery
- **api3** - API3 dAPI and Airnode integration
- **customOracle** - Custom oracle design framework with request/response model

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`, peer
`@aje/core`, `@aje/chains`

### `@aje/payments` - Payment Protocols

On-chain payment infrastructure:

- **stablecoins** - USDC, USDT, DAI integration with mint/redeem flows
- **circle** - Circle API for USDC minting, transfers, and accounts
- **fiatRamps** - Fiat on/off ramp integration (MoonPay, Ramp, Transak)
- **merchant** - Merchant payment processing with settlement
- **streaming** - Superfluid-style streaming payments and subscriptions
- **cbdc** - Central Bank Digital Currency protocol integration

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`, peer
`@aje/core`, `@aje/chains`

### `@aje/storage` - Decentralized Storage

Content-addressable and permanent storage:

- **ipfs** - IPFS pinning, retrieval, and gateway management
- **filecoin** - Filecoin storage deals and retrieval
- **arweave** - Arweave permanent storage with bundled transactions
- **hybrid** - Hybrid storage strategies combining IPFS, Filecoin, and Arweave
- **nftStorage** - NFT.storage integration for metadata and media

**Dependencies:** `@noble/hashes`, `@scure/base`, peer `@aje/core`

### `@aje/security` - Security Auditing

Smart contract and protocol security tooling:

- **staticAnalysis** - Static analysis integration (Slither, Mythril, Semgrep)
- **formalVerification** - Formal verification tooling (Certora, Halmos)
- **mevProtection** - MEV protection strategies (Flashbots Protect, MEV Blocker)
- **runtimeProtection** - Runtime monitoring and circuit breaker patterns
- **auditTooling** - Audit workflow management and finding tracking
- **incidentResponse** - Security incident response playbooks and automation

**Dependencies:** `@noble/hashes`, peer `@aje/core`, `@aje/chains`

### `@aje/database` - Blockchain Data Persistence

Blockchain-specific database schemas built on the shared `@oshun/database`:

- **coreSchema** - Chain config, blocks, transactions, contracts, balances
- **defiSchema** - DEX swaps, liquidity pools, lending positions, yield,
  portfolio tracking
- **walletSchema** - Wallet records, DID identity, transaction history,
  compliance data
- **indexer** - Block ingestion, contract event indexing, API query layer,
  health monitoring
- **maintenance** - ORM integration, migration tooling, seed data, performance
  tuning

**Dependencies:** peer `@aje/core`, `@oshun/database`

### `@aje/rwa` - Real-World Asset Tokenization

Tokenization infrastructure for traditional assets:

- **securityTokens** - ERC-3643 compliant security token issuance
- **treasuryTokenization** - US Treasury and government bond tokenization
- **realEstate** - Real estate fractionalization and management
- **commodities** - Commodity-backed token issuance
- **compliance** - KYC/AML integration for regulated asset transfers
- **chainlinkRwa** - Chainlink Proof of Reserve for real-world asset backing

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`, peer
`@aje/core`, `@aje/chains`

### `@aje/nodes` - Node Management

Blockchain node operation and management:

- **rpc** - RPC endpoint management, load balancing, failover
- **fullNode** - Full node deployment and synchronization
- **avalancheNode** - Avalanche node operation for validators and API nodes
- **cardanoNode** - Cardano node operation (relay and block producer)
- **lightClient** - Light client implementations for resource-constrained
  environments
- **validator** - Validator management for PoS networks

**Dependencies:** `@noble/hashes`, `@noble/curves`, `@scure/base`, peer
`@aje/core`, `@aje/chains`

### `@aje/account-abstraction` - Advanced Account Abstraction

Next-generation account abstraction standards:

- **eip7702** - EIP-7702 set-code-for-EOAs delegation for upgrading EOAs to
  smart accounts
- **erc7715** - ERC-7715 permission granting system for dApp interactions
- **erc7579** - ERC-7579 modular smart account standard with pluggable modules
- **erc6900** - ERC-6900 Alchemy modular accounts with plugin architecture
- **advancedAA** - Advanced AA infrastructure including bundler management,
  paymaster routing, and gas abstraction

**Dependencies:** peer `@aje/core`

### `@aje/agents` - AI Blockchain Agents

AI agent infrastructure for autonomous blockchain operations:

- **wallets** - Agent-specific wallet management with spending limits and
  policies
- **execution** - On-chain agent execution with transaction batching and
  simulation
- **communication** - Agent-to-agent messaging protocol with reputation-based
  routing
- **x402** - x402 HTTP payment protocol for machine-to-machine payments
- **ai** - AI model integration for decision-making and strategy evaluation
- **frameworks** - Connectors for agent frameworks (LangChain, AutoGPT, CrewAI)
- **safety** - Agent safety controls including kill switches, spending caps, and
  governance constraints

**Dependencies:** peer `@aje/core`

### `@aje/predictions` - Prediction Markets

Prediction market infrastructure:

- **polymarket** - Polymarket integration for market creation and trading
- **contracts** - Custom prediction market smart contract templates
- **oracles** - Resolution oracle systems for market settlement
- **marketMaking** - Automated market maker for prediction markets
- **analytics** - Market probability tracking and analysis tools

**Dependencies:** peer `@aje/core`

### `@aje/bitcoin` - Bitcoin Ecosystem

Bitcoin-specific implementations including Lightning Network and Layer 2:

- **shared** - Shared Bitcoin utilities, address formats, PSBT handling
- **lightning** - Lightning Network channel management and payments
- **lsp** - Lightning Service Provider (LSP) integration
- **lnApps** - Lightning-native applications (LNURL, Nostr Zaps)
- **stacks** - Stacks smart contract platform (Clarity language)
- **sbtc** - sBTC bridged Bitcoin on Stacks
- **bitvm** - BitVM computation verification protocol
- **ordinals** - Bitcoin Ordinals inscription management
- **runes** - Runes fungible token protocol on Bitcoin
- **rgb** - RGB smart contract protocol
- **otherL2s** - Additional Bitcoin L2s (Liquid, RSK)

**Dependencies:** peer `@aje/core`

### `@aje/depin` - Decentralized Physical Infrastructure

DePIN protocol integration:

- **compute** - Decentralized compute networks (Akash, Render, io.net)
- **wireless** - Wireless networks (Helium, XNET) protocol integration
- **iot** - IoT device management and sensor data verification
- **location** - Decentralized mapping and location services (Hivemapper)
- **energy** - Energy network trading and renewable energy credits
- **storage** - Decentralized storage network operations
- **rewards** - DePIN reward economics and token distribution

**Dependencies:** peer `@aje/core`

### `@aje/gaming` - On-Chain Gaming

Blockchain gaming and autonomous worlds:

- **mud** - MUD framework integration for on-chain game state
- **worldEngine** - World Engine for autonomous world creation
- **assets** - Game asset standards (ERC-721, ERC-1155 with game metadata)
- **economy** - In-game economy design with token mechanics
- **autonomous** - Autonomous world patterns and game loop infrastructure
- **gamingL2s** - Gaming-optimized L2 chains (Ronin, Immutable X, Beam)

**Dependencies:** peer `@aje/core`

### `@aje/appchains` - Rollup-as-a-Service

Application-specific chain deployment:

- **conduit** - Conduit RaaS deployment and management
- **caldera** - Caldera RaaS integration
- **altlayer** - AltLayer restaked rollup deployment
- **da** - Data availability layer integration (Celestia, EigenDA, Avail)
- **sequencer** - Shared sequencer integration (Espresso, Astria)
- **config** - Appchain configuration and parameter tuning

**Dependencies:** peer `@aje/core`

### `@aje/intents` - Intent-Based Architecture

Intent-based transaction systems and solver networks:

- **expression** - Intent expression language and specification format
- **solvers** - Solver network infrastructure and competition framework
- **cow** - CoW Protocol integration for batch auctions
- **uniswapx** - UniswapX order creation and Dutch auction mechanics
- **across** - Across Protocol cross-chain intent bridging
- **essential** - Essential intent infrastructure and registry

**Dependencies:** peer `@aje/core`

### `@aje/restaking` - Liquid Restaking

EigenLayer restaking and AVS development:

- **eigenlayer** - EigenLayer core restaking contracts and operator management
- **avs** - Actively Validated Service (AVS) development framework
- **lrt** - Liquid Restaking Token (LRT) protocol integration (EtherFi, Puffer,
  Kelp)

**Dependencies:** peer `@aje/core`

### `@aje/privacy` - Privacy Infrastructure

Compliance-friendly privacy technologies:

- **privacyPools** - Privacy pools with association sets for compliant privacy
- **advancedPrivacy** - Advanced privacy techniques (FHE, MPC, TEE integration)

**Dependencies:** peer `@aje/core`

### `@aje/sui-move` - Sui and Move Ecosystem

Sui blockchain and Move language tooling:

- **suiNetwork** - Sui network client, object model, and transaction building
- **moveLanguage** - Move language tooling, compilation, and testing
- **suiDefi** - Sui DeFi protocol integration (Cetus, Turbos, DeepBook)
- **aptos** - Aptos blockchain integration and Move interoperability

**Dependencies:** peer `@aje/core`

### `@aje/sdk` - Unified Developer SDK

Developer-facing SDK wrapping all Aje functionality:

- **core** - Core TypeScript/JavaScript SDK with ergonomic API
- **react** - React hooks and components for Web3 integration
- **python** - Python SDK code generation from TypeScript types
- **cli** - CLI tools for contract interaction and chain operations
- **docs** - Documentation generation utilities

**Dependencies:** peer `@aje/core`, `@aje/chains`

---

## Technology Stack

| Component    | Technology                                               |
| ------------ | -------------------------------------------------------- |
| Language     | TypeScript (ESM)                                         |
| Runtime      | Node.js                                                  |
| Build        | Nx with `@nx/js:tsc`                                     |
| Testing      | Vitest                                                   |
| Cryptography | `@noble/hashes`, `@noble/curves`, `@scure/base/bip32/39` |
| Validation   | Zod schemas in select libraries                          |
| Database     | `@oshun/database` (PostgreSQL via Drizzle ORM)           |

---

## Development

```bash
# Test a specific library
pnpm nx test @aje/core

# Build all Aje libraries
pnpm nx run-many --target=build --projects=tag:scope:aje

# Lint a library
pnpm nx lint @aje/core

# Run tests across the entire domain
pnpm nx run-many --target=test --projects=tag:scope:aje
```

### Configuration

- **Project tags:** `["scope:aje", "layer:domain", "type:lib"]`
- **Build executor:** `@nx/js:tsc` with `@nx/vite:test` for testing
- **vitest.config.ts** requires explicit `resolve.alias` for `@oshun/*`
  dependencies
- All libraries use ESM (`"type": "module"`) with `.js` extension imports
