15-Package Monorepo Deep Dive: How We Architected WAIaaS for Scale

Building a 15-package monorepo isn't just about organizing code—it's about creating a foundation that can scale from a single AI agent to thousands of autonomous financial operations. The WAIaaS monorepo architecture demonstrates how to structure a complex blockchain wallet service that serves multiple interfaces while maintaining clean separation of concerns.

Why Monorepo Architecture Matters for Blockchain Services

When you're building a service that needs to handle multiple blockchains, serve different client types (CLI, MCP, REST API), and maintain strict security boundaries, architecture decisions compound quickly. A poorly structured codebase becomes a maintenance nightmare when you're dealing with financial transactions where bugs can cost real money.

The challenge is even greater when your service needs to support AI agents, hardware wallets, web interfaces, and programmatic access simultaneously. Each interface has different requirements, but they all need to share the same core transaction logic and security policies.

The 15-Package Structure

WAIaaS is organized as a 15-package monorepo: actions, adapters, admin, cli, core, daemon, desktop-spike, e2e-tests, mcp, openclaw-plugin, push-relay, sdk, shared, skills, wallet-sdk. This structure reflects the different concerns and deployment targets of a modern blockchain service.

Let's break down how these packages work together:

Core Infrastructure

The core package contains the fundamental types and schemas that everything else builds on. This includes the 21 policy types (SPENDING_LIMIT, WHITELIST, TIME_RESTRICTION, RATE_LIMIT, ALLOWED_TOKENS, CONTRACT_WHITELIST, METHOD_WHITELIST, APPROVED_SPENDERS, APPROVE_AMOUNT_LIMIT, APPROVE_TIER_OVERRIDE, ALLOWED_NETWORKS, X402_ALLOWED_DOMAINS, LENDING_LTV_LIMIT, LENDING_ASSET_WHITELIST, PERP_MAX_LEVERAGE, PERP_MAX_POSITION_USD, PERP_ALLOWED_MARKETS, REPUTATION_THRESHOLD, ERC8128_ALLOWED_DOMAINS, VENUE_WHITELIST, ACTION_CATEGORY_LIMIT) and the 4 security tiers (INSTANT, NOTIFY, DELAY, APPROVAL) that govern how transactions are processed.

The shared package handles cross-cutting concerns like network definitions. It defines 2 chain types (solana, evm) with 18 networks, providing a consistent interface for working with different blockchains.

Transaction Processing Engine

The daemon package is the heart of the system, implementing the 39 REST API route modules and the 7-stage transaction pipeline: stage1-validate, stage2-auth, stage3-policy, stage4-wait, stage5-execute, stage6-confirm, stages. This pipeline ensures that every transaction goes through proper validation, authentication, policy checking, and execution regardless of which interface initiated it.

# The daemon exposes a comprehensive REST API
curl -X POST http://127.0.0.1:3100/v1/transactions/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wai_sess_<token>" \
  -d '{
    "type": "TRANSFER",
    "to": "recipient-address",
    "amount": "0.1"
  }'

DeFi Integration Layer

The actions package contains 15 DeFi protocol providers integrated: aave-v3, across, dcent-swap, drift, erc8004, hyperliquid, jito-staking, jupiter-swap, kamino, lido-staking, lifi, pendle, polymarket, xrpl-dex, zerox-swap. Each provider implements a standardized interface while handling the specifics of its protocol.

This architecture allows the system to support complex operations like cross-chain bridging, liquid staking, and perpetual futures trading through a unified API:

# Execute a Jupiter swap on Solana
curl -X POST http://127.0.0.1:3100/v1/actions/jupiter-swap/swap \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wai_sess_<token>" \
  -d '{
    "inputMint": "So11111111111111111111111111111111111111112",
    "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "amount": "1000000000"
  }'

Client Interfaces

The monorepo supports multiple ways to interact with the system:

The cli package provides a CLI with 20 commands: backup create, backup inspect, backup list, init, mcp setup, notification setup, owner connect, owner disconnect, owner status, quickset, quickstart, restore, session prompt, set-master, start, status, stop, update, wallet create, wallet info.

The mcp package offers 45 MCP tools for AI agent integration, allowing systems like Claude to interact with wallets through natural language.

The sdk package provides both TypeScript and Python interfaces for programmatic access.

The admin package delivers a web-based management interface built with Preact.

Deployment and Development Benefits

This structure enables flexible deployment patterns. The entire system can run as a single Docker container using the ghcr.io/minhoyoo-iotrust/waiaas:latest image with Docker entrypoint supports: auto-provision, Docker Secrets, or individual packages can be deployed separately for microservices architectures.

The monorepo approach provides several key advantages for development:

Shared Dependencies: All packages use the same versions of core dependencies, eliminating version conflicts that can plague multi-repo setups.

Atomic Changes: When you need to modify both the core transaction schema and the API that consumes it, you can do it in a single pull request with confidence that everything stays in sync.

Unified Testing: The 683+ test files across all packages can run together, catching integration issues that might slip through in isolated testing.

Type Safety: TypeScript types flow seamlessly across package boundaries, providing compile-time guarantees that your CLI commands match your API schemas.

Security Through Architecture

The package structure enforces security boundaries at the architectural level. The core package defines policies but doesn't implement them—that's the daemon's job. The SDK packages can only make requests through the API, not directly access wallet keys. The MCP tools operate with session-level permissions, never master-level access.

This separation means that even if one interface has a vulnerability, the core security model remains intact. An agent with MCP access can't escalate to full system control, and a compromised SDK can't bypass policy enforcement.

Scaling Considerations

As usage grows, different packages can be scaled independently. The push-relay package handles notification delivery and can be scaled separately from the main daemon. The admin interface can run on different infrastructure from the transaction processing engine.

The 3 signing channels: push-relay-signing-channel, telegram-signing-channel, wallet-notification-channel can each scale to handle different volumes of approval requests without affecting transaction processing performance.

Quick Start with the Monorepo

Here's how to get the entire system running locally:

1. Clone and start the daemon:

git clone https://github.com/minhoyoo-iotrust/WAIaaS.git
cd WAIaaS
docker compose up -d

2. Install the CLI globally:

npm install -g @waiaas/cli
waiaas init
waiaas start

3. Create wallets and sessions:

waiaas quickset --mode mainnet

4. Set up MCP integration:

waiaas mcp setup --all

5. Test with the SDK:

npm install @waiaas/sdk

Development Workflow

The monorepo structure supports efficient development workflows. You can run tests across all packages, build Docker images, and deploy updates with confidence that all components remain compatible.

The package interdependencies are carefully managed—the daemon depends on core and actions, the sdk depends on shared for network definitions, and the cli orchestrates everything without tight coupling to implementation details.

The WAIaaS monorepo demonstrates that with careful planning, you can build complex systems that remain maintainable and scalable. The key is identifying the right boundaries between packages and ensuring that each package has a clear, focused responsibility.

Ready to explore the codebase? Check out the source at https://github.com/minhoyoo-iotrust/WAIaaS or learn more about the architecture at https://waiaas.ai.