Chapter 1: System Overview

What Capxul Is

Capxul is a financial operating system on stablecoin rails. Organizations pay their teams in stablecoins (primarily USDC) via Safe multisig treasuries. Recipients receive funds into individual smart accounts and can route them to external wallets, bank accounts via off-ramp, or mobile money.

V2 migrates from Aragon-based infrastructure to Safe-based infrastructure with a new Convex backend. This is a ground-up redesign of the on-chain layer, the wallet infrastructure, the financial document system, and every integration point.

What V2 Does

The V2 platform supports the complete lifecycle of crypto payroll and treasury management:

Organizations create or connect a Safe treasury on Base, add employees via CSV upload, and fund salary streams. They approve invoices, pay vendors (in USDC or fiat), fund their treasury via fiat on-ramp, and monitor financial health through a live dashboard.
Employees receive salary via continuous USDC streams that accrue to their smart accounts. They claim funds on their own schedule, configure automatic routing (split between bank account, external wallet, and other chains), and access payslips and claim receipts.
Vendors and contractors submit invoices through the platform, receive payments in USDC (or fiat via off-ramp), and track payment status in real time.

Every payment produces verifiable documentation. Every on-chain transaction links to an off-chain financial record via a bidirectional hash. The platform generates payslips, receipts, and invoices that serve as proof of compensation, proof of payment, and input for tax and compliance reporting.

Target Market

Organizations and employees in Nigeria, Ghana, Kenya, and Uganda. The primary users are not crypto-native. They are employees receiving salaries, vendors submitting invoices, and organizations managing treasury. The platform must be usable without crypto knowledge. “Did I get paid?” and “Can I prove it?” are the questions that matter.

Core Principles

Pull-Based Architecture

All funds flow through the employee’s smart account. This is not a feature. It is an invariant.

Salary streams accrue to the smart account. Invoice payouts to vendors land in the vendor’s smart account. The smart account is the employee’s (or vendor’s) financial source of truth. Any downstream routing — send X% to an EOA, Y% to a bank via off-ramp, Z% to another chain via bridge — is configured by the recipient in Convex and executed from the smart account.

Funds never skip the smart account and go directly to an external destination. That is how funds get lost. The smart account is the checkpoint between “payment was made” and “recipient chose what to do with it.”

Infrastructure Sovereignty

Every critical component that touches user funds or keys has a path to self-hosting or is on-chain and immutable:

Smart account contracts (Openfort, GPL-3.0): on-chain, open source
Key management (OpenSigner, MIT): self-hostable
Recovery server (Shield): self-hostable, open source
Safe modules (Payment Module, Zodiac Roles): on-chain, open source
LlamaPay: on-chain, battle-tested since 2022
Auth (Better Auth): self-hosted, open source
Backend (Convex): Capxul-owned data

The one temporary dependency is Openfort’s hosted API, which wraps standard EVM operations and open-source contracts. It is replaceable with Convex actions + viem + permissionless.js on a defined timeline (see Phased Independence).

Facade Pattern

External providers — fiat ramp providers (HoneyCoin), bridge providers (deBridge, Hyperbridge), identity verification providers (Shufti Pro) — are abstracted behind interfaces. The application logic never calls a provider directly. It calls through a facade that:

Selects the appropriate provider based on country, chain, or capability
Normalizes request and response formats
Tracks transaction state in Convex (the source of truth, not the provider)
Supports adding, swapping, or deprecating providers without changing application code

This means replacing HoneyCoin with Paychant, or adding LI.FI alongside deBridge, is a backend configuration change. No frontend code changes. No schema migrations.

Master Architecture

Safe Treasury (Base)
  |
  |-- [Zodiac Roles Modifier] -- permissions layer
  |     |
  |     |-- [Payment Module] -- invoices, one-offs, off-ramp sends, bridge sends
  |     |     emits PaymentExecuted(safe, recipient, token, amount, docHash, paymentType)
  |     |
  |     |-- [LlamaPay] -- salary streaming (vanilla, no fork)
  |           emits CreateStream, WithdrawFromStream
  |
  v
Employee Smart Account (Openfort ERC-4337)
  |
  |-- [Session Key] -- scoped: USDC contract + LlamaPay (on-chain)
  |                    destination enforcement in Convex (off-chain, Path A)
  |                    or via CapxulRouter contract (on-chain, Path B)
  |
  |-- Routes to:
        |-- External EOA (MetaMask, etc.)
        |-- Off-ramp provider deposit address (HoneyCoin)
        |-- Bridge contract (deBridge, LI.FI)
        |-- Stays in smart account

Two Sides

Org side (Safe treasury). A Safe on Base holds USDC. Custom modules and Zodiac infrastructure enable programmatic payment execution without manual multisig signing for every transaction. The Payment Module handles discrete payments. LlamaPay handles streaming payments. Zodiac Roles enforces permissions (spending limits, role-based access, backend service roles).

Employee side (Openfort smart account). Each employee has an ERC-4337 smart account via Openfort. Built-in session keys enable automated routing. The Convex backend orchestrates routing using session keys the employee has granted.

These two sides connect through LlamaPay (streaming) and the Payment Module (discrete payments). In both cases, funds move from the Safe to the employee’s smart account. Then the employee (or automated routing) moves funds outward.

System Layers

The V2 architecture is organized in layers. Each layer is documented in its own chapter:

Layer	What It Does	Chapter
On-chain infrastructure	Safe, Payment Module, LlamaPay, Zodiac Roles	Chapter 2
Smart account infrastructure	Openfort accounts, session keys, auth, recovery	Chapter 3
Payments and streaming	LlamaPay streams, discrete payments, approval flows	Chapter 4
Fiat ramps	Off-ramp (bank/MoMo), on-ramp (virtual accounts)	Chapter 5
Cross-chain	Bridge facade, provider evaluation, multi-chain treasury	Chapter 6
Financial documents	Invoices, payslips, receipts, on-chain anchoring	Chapter 7
Event indexing	Custom indexer, Convex sync, treasury balance tracking	Chapter 8
Dashboard and reporting	Treasury metrics, AP aging, scheduled reports	Chapter 9
Identity verification	KYC/KYB via Shufti Pro, tiered verification	Chapter 10
Independence plan	Phased decoupling from Openfort hosted API	Chapter 11
Implementation roadmap	Unified build timeline across all layers	Chapter 12
Open questions	Canonical list, organized by domain	Chapter 13

Technology Stack

Component	Technology	Notes
Backend	Convex	Document database, real-time subscriptions, scheduled functions, HTTP actions
Auth	Better Auth + magic links	Separate Hono/Express server with SQLite (dev) or Turso/Postgres (prod)
Smart accounts	Openfort V1 (ERC-4337)	GPL-3.0 contracts, built-in session keys, guardian recovery
Key management	OpenSigner (Shamir 2-of-3)	MIT-licensed, self-hostable
Org treasury	Safe (multisig)	With Zodiac Roles Modifier
Streaming payments	LlamaPay (vanilla)	No fork, deployed on Base
Discrete payments	Custom Payment Module	Extends Zodiac Module.sol
Event indexing	Custom Node.js/TypeScript service	viem for chain interaction, hosted on Railway
Fiat ramp	HoneyCoin (at launch)	Provider abstraction supports future providers
Bridge	deBridge (at launch)	Hyperbridge and LI.FI as future additions
Identity verification	Shufti Pro	KYC and KYB, tiered verification
Chain	Base (at launch)	Multi-chain via bridge and child Safes
Package manager	bun (JS/TS)