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 catalog (39)#
The 39 tracked Nx projects in aje, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 39 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
domain (38)#
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
keccak25623keccak256Hex23sha25623sha256Hex23sha51223sha512Hex23blake2b23blake2bHex23ripemd16023ripemd160Hex23hash160Hex23doubleSha25623hashMessage23hashMessageHex23 +58 moreBlockchain-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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 settlement escrow adapter — bridges Concordia escrow_release clauses to smart-contract execution (Phase 179.7.2.4).
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).
EscrowChainSchema8OracleSourceSchema8EscrowMilestonePlanSchema8EscrowDeploymentPlanSchema8lanDeployment8nextMilestoneAfter8EscrowChain8OracleSource8EscrowMilestonePlan8EscrowDeploymentPlan8Decentralized 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.
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.
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.
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.
infra (1)#
OshunRpcClient — unified, typed, multi-chain RPC client with retry, fallback, rate limiting, and multi-RPC fan-out
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.
OshunRpcClient14HttpTransport15RpcError16RpcExhaustedError16RpcMethodError16RpcNetworkError16RpcParseError16RpcQuorumError16RpcRateLimitError16RpcTimeoutError16createRateLimiter26NoopRateLimiter26RateLimiter26DEFAULT_RETRY_POLICY27 +19 more