Comprehensive development guide for the Aje blockchain, DeFi, and Web3 infrastructure domain.
Prerequisites#
Required Software#
| Tool | Version | Purpose |
|---|---|---|
| Node.js | >= 20.0 | Runtime for all Aje libraries |
| pnpm | >= 10.0 | Package manager (workspace protocol) |
| Git | >= 2.40 | Version control |
| TypeScript | ^6.0.3 | Compile-time type checking (via catalog) |
Blockchain-Specific Tooling (Optional)#
These tools are not required for library development or unit testing but are needed for integration testing against live or local networks:
| Tool | Purpose |
|---|---|
| Foundry (forge) | Solidity compilation, testing, deployment integration |
| Hardhat | Smart contract testing infrastructure |
| Ganache / Anvil | Local Ethereum node for integration tests |
| Circom | ZK circuit compilation (@aje/zkp) |
| Aiken | Cardano smart contract tooling (@aje/contracts) |
| Sui CLI | Sui/Move development (@aje/sui-move) |
Environment Variables#
No environment variables are required for building or unit-testing Aje
libraries. For integration tests that hit external services, set the following
in your local .env:
# Ethereum RPC (for @aje/chains integration tests)
ETH_RPC_URL=http://localhost:8545
# Solana RPC (for @aje/chains solana module)
SOLANA_RPC_URL=http://localhost:8899
# IPFS (for @aje/storage)
IPFS_API_URL=http://localhost:5001
Project Structure#
The Aje domain contains 29 libraries under libs/aje/. All libraries follow the
same Nx project structure:
libs/aje/
account-abstraction/ # EIP-7702, ERC-7579, ERC-6900, bundler, paymaster
agents/ # AI blockchain agents, x402, safety controls
appchains/ # Rollup-as-a-Service (Conduit, Caldera, AltLayer)
bitcoin/ # Lightning, Ordinals, Runes, Stacks, BitVM, RGB
bridges/ # LayerZero, Wormhole, CCIP, Axelar, Avalanche Warp
chains/ # Multi-chain providers (Ethereum, Solana, Cardano, etc.)
contracts/ # Smart contract compilation, deployment, upgrades, testing
core/ # Foundation: addresses, transactions, ABI, crypto, merkle
database/ # Blockchain data persistence (Drizzle ORM, @oshun/database)
defi/ # AMM, Uniswap, Curve, lending, liquid staking, derivatives
depin/ # DePIN: compute, wireless, IoT, energy, location
gaming/ # MUD, World Engine, game assets, autonomous worlds
governance/ # On-chain governance: Governor, Snapshot, Tally, Aragon
identity/ # DID, Verifiable Credentials, ENS, Lens, Farcaster
intents/ # Intent-based txs: CoW Protocol, UniswapX, Across
nft/ # ERC-721/721A/1155, token-bound accounts, soulbound, dynamic
nodes/ # RPC management, full nodes, validators, light clients
oracles/ # Chainlink, Pyth, RedStone, API3, custom oracles
payments/ # Stablecoins, Circle, fiat ramps, streaming payments
predictions/ # Prediction markets: Polymarket, custom contracts
privacy/ # Privacy pools, FHE, MPC, TEE
restaking/ # EigenLayer, AVS development, LRT protocols
rwa/ # Real-world asset tokenization (ERC-3643, treasuries)
sdk/ # Unified developer SDK: TypeScript, React hooks, CLI
security/ # Static analysis, formal verification, MEV protection
storage/ # IPFS, Filecoin, Arweave decentralized storage
sui-move/ # Sui network, Move language, Sui DeFi, Aptos
wallets/ # HD wallets, MPC, account abstraction, session keys
zkp/ # zk-SNARKs, STARKs, Circom, Semaphore, ZKML
Individual Library Layout#
Each library follows a consistent structure:
libs/aje/<library>/
package.json # Name, version, ESM exports, dependencies
project.json # Nx configuration (build, lint, test targets)
tsconfig.json # Extends tsconfig.base.json, references lib/spec
tsconfig.lib.json # Library compilation config
tsconfig.spec.json # Test compilation config
vitest.config.ts # Vitest test runner configuration
src/
index.ts # Barrel export file
<module>/
index.ts # Module barrel export
<file>.ts # Implementation files
<file>.spec.ts # Co-located test files
Local Development Setup#
Initial Setup#
# Clone the repository
git clone git@github.com:GreyChimp/oshun.git
cd oshun
# Install all dependencies
pnpm install
Infrastructure (Optional)#
Aje libraries are library-only and do not require running services for basic
development. However, @aje/database depends on @oshun/database which uses
PostgreSQL:
# Start PostgreSQL for database library development
docker compose -f docker/docker-compose.dev.yml up -d postgres
Building Libraries#
Build a Single Library#
pnpm nx build @aje/core
Build All Aje Libraries#
pnpm nx run-many --target=build --projects=tag:scope:aje
Build a Library and Its Dependencies#
Nx automatically handles the dependency graph. The @aje/core project.json uses
@nx/js:tsc as the build executor:
{
"build": {
"executor": "@nx/js:tsc",
"outputs": ["{options.outputPath}"],
"options": {
"outputPath": "dist/libs/aje/core",
"main": "libs/aje/core/src/index.ts",
"tsConfig": "libs/aje/core/tsconfig.lib.json",
"assets": []
}
}
}
Build output goes to dist/libs/aje/<library>/.
Verify a Build#
# Check the output exists and contains declarations
ls dist/libs/aje/core/
Testing#
Run Tests for a Single Library#
pnpm nx test @aje/core
Run All Domain Tests#
pnpm nx run-many --target=test --projects=tag:scope:aje
Watch Mode#
# Run vitest in watch mode directly
npx vitest --config libs/aje/core/vitest.config.ts --watch
Test Configuration#
Every library has a vitest.config.ts at its root. The standard configuration
for Aje libraries:
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
globals: true,
environment: 'node',
include: ['src/**/*.spec.ts', 'src/**/*.test.ts'],
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
},
},
});
Key points:
globals: trueenablesdescribe,it,expectwithout imports- Tests are co-located with source in
src/using.spec.tsor.test.tssuffix - Coverage uses the V8 provider and outputs text, JSON, and HTML reports
Coverage#
# Run tests with coverage
npx vitest --config libs/aje/core/vitest.config.ts --coverage
Testing Patterns#
Unit tests should mock external dependencies. The cryptographic libraries
(@noble/*, @scure/*) are deterministic and can be tested with known test
vectors:
import { describe, it, expect } from 'vitest';
import { validateAddress, checksumAddress } from './addresses.js';
describe('validateAddress', () => {
it('validates a correct EVM address', () => {
expect(validateAddress('0x1234...abcd', 'evm')).toBe(true);
});
it('rejects an invalid checksum', () => {
expect(validateAddress('0x1234...ABCD', 'evm')).toBe(false);
});
});
BigNumber arithmetic tests should use toEqual for comparing objects and
verify precision boundaries.
ABI encoding/decoding tests should round-trip encode then decode and compare against known Solidity ABI outputs.
Linting#
Lint a Single Library#
pnpm nx lint @aje/core
Lint All Aje Libraries#
pnpm nx run-many --target=lint --projects=tag:scope:aje
Key Lint Rules#
@typescript-eslint/no-unused-vars: Prefix intentionally unused variables with_no-duplicate-imports: Combine value and type imports on the same line usingimport { foo, type Bar } from '...'- ESM imports must use explicit
.jsextensions for relative paths
Common Development Tasks#
Adding a New Library#
- Create the directory structure:
mkdir -p libs/aje/new-library/src
- Create
project.json:
{
"name": "@aje/new-library",
"$schema": "../../../node_modules/nx/schemas/project-schema.json",
"sourceRoot": "libs/aje/new-library/src",
"projectType": "library",
"tags": ["scope:aje", "layer:domain", "type:lib"],
"targets": {
"build": {
"executor": "@nx/js:tsc",
"outputs": ["{options.outputPath}"],
"options": {
"outputPath": "dist/libs/aje/new-library",
"main": "libs/aje/new-library/src/index.ts",
"tsConfig": "libs/aje/new-library/tsconfig.lib.json",
"assets": []
}
},
"lint": {
"executor": "@nx/eslint:lint"
},
"test": {
"executor": "@nx/vite:test",
"options": {
"configFile": "libs/aje/new-library/vitest.config.ts"
}
}
}
}
- Create
package.json:
{
"name": "@aje/new-library",
"version": "0.1.0",
"private": true,
"type": "module",
"exports": {
".": {
"import": "./src/index.js",
"types": "./src/index.d.ts"
}
},
"peerDependencies": {
"@aje/core": "workspace:*"
},
"devDependencies": {
"vitest": "catalog:"
}
}
-
Create
tsconfig.json,tsconfig.lib.json,tsconfig.spec.jsonfollowing the pattern in@aje/core. -
Create
vitest.config.tswith the standard configuration. -
Add path mapping to
tsconfig.base.jsonif not already covered by the wildcard@aje/*pattern (it is:"@aje/*": ["libs/aje/*/src/index.ts"]). -
Run
pnpm installto resolve workspace links.
Adding a Cryptographic Dependency#
All Aje libraries use the @noble and @scure ecosystem for cryptography.
Never roll custom cryptographic implementations:
{
"dependencies": {
"@noble/hashes": "^1.7.1",
"@noble/curves": "^1.8.1",
"@scure/base": "^1.2.4",
"@scure/bip32": "^1.6.2",
"@scure/bip39": "^1.5.4"
}
}
Only @aje/core and libraries that directly perform cryptographic operations
should list these as direct dependencies. Other libraries should access crypto
through @aje/core exports.
Integrating with Other Domains#
The @aje/database library bridges into the shared @oshun/database
foundation:
{
"peerDependencies": {
"@aje/core": "workspace:*",
"@oshun/database": "workspace:*"
}
}
Import from other domains using their @scope/library path. The
tsconfig.base.json maps @aje/* to libs/aje/*/src/index.ts.
Key Patterns and Conventions#
Dependency Layering#
The domain follows a strict dependency hierarchy:
@aje/coredepends only on@noble/*,@scure/*, and optionally@oshun/types@aje/chainsdepends on@aje/coreas a peer dependency- Higher-level libraries (
@aje/defi,@aje/nft,@aje/bridges, etc.) depend on both@aje/coreand@aje/chainsas peer dependencies @aje/sdkwraps all functionality into a unified developer API
Never introduce circular dependencies. Libraries at the same tier should not depend on each other unless explicitly documented.
ESM Module System#
All Aje libraries use ESM ("type": "module" in package.json):
- Use
.jsextensions in all import/export paths (even for.tsfiles) - Use
export *for barrel exports - Namespace exports use
export * as name from '...'pattern
Example from @aje/defi/src/index.ts:
export * as amm from './amm/index.js';
export * as uniswap from './uniswap/index.js';
export * as curve from './curve/index.js';
export * as lending from './lending/index.js';
Project Tags#
All Aje libraries use these Nx tags:
["scope:aje", "layer:domain", "type:lib"]
These tags enable batch operations:
pnpm nx run-many --target=test --projects=tag:scope:aje
Package Versioning#
All libraries are at 0.1.0 and marked "private": true. Dependencies on
sibling workspace packages use "workspace:*".
Dev dependencies use "catalog:" references to share versions across the
monorepo via the pnpm catalog defined in pnpm-workspace.yaml.
Debugging Tips#
TypeScript Path Resolution Issues#
If imports like @aje/core fail to resolve, verify:
- The
tsconfig.base.jsoncontains the mapping"@aje/*": ["libs/aje/*/src/index.ts"] - The library's
tsconfig.jsonextends../../../tsconfig.base.json - Run
pnpm installto ensure workspace links are current
Build Order Problems#
If a build fails because a dependency has not been built yet, Nx should handle
ordering automatically. Verify implicitDependencies in project.json or add
"dependsOn": ["^build"] to the build target.
Test Failures with Cryptographic Operations#
The @noble and @scure libraries are pure JavaScript and deterministic. If
tests fail:
- Check that test vectors match the expected algorithm (secp256k1 vs ed25519)
- Verify hex string encoding (with or without
0xprefix) - BigNumber comparisons should use
BigIntcomparison, not loose equality
Coverage Not Reflecting Changes#
Delete the coverage output and re-run:
rm -rf coverage/libs/aje/<library>
pnpm nx test @aje/<library>
Nx Cache Issues#
If builds or tests seem stale:
pnpm nx reset
This clears the Nx daemon cache and forces fresh execution.
Viewing the Dependency Graph#
pnpm nx graph --focus=@aje/core
This opens an interactive visualization of the Aje library dependency tree.
Quick Reference#
| Action | Command |
|---|---|
| Install dependencies | pnpm install |
| Build one library | pnpm nx build @aje/<lib> |
| Build all Aje libraries | pnpm nx run-many --target=build --projects=tag:scope:aje |
| Test one library | pnpm nx test @aje/<lib> |
| Test all Aje libraries | pnpm nx run-many --target=test --projects=tag:scope:aje |
| Lint one library | pnpm nx lint @aje/<lib> |
| Lint all Aje libraries | pnpm nx run-many --target=lint --projects=tag:scope:aje |
| View dependency graph | pnpm nx graph --focus=@aje/core |
| Reset Nx cache | pnpm nx reset |