CavalRe Contracts

This repository contains the core smart contracts powering CavalRe, a modular, accounting-driven architecture for onchain capital markets. Contracts are organized into clearly separated modules, libraries, utilities, and illustrative examples.

Repository Structure

cavalre-contracts/
├── modules/
│   ├── ERC20.sol
│   ├── Module.sol
│   ├── Router.sol
│   └── Ledger.sol
├── libraries/
│   ├── ERC20Lib.sol
│   ├── FloatLib.sol
│   ├── FloatStrings.sol
│   ├── LedgerLib.sol
│   ├── ModuleLib.sol
│   ├── RandomLib.sol
│   ├── RouterLib.sol
│   └── TreeLib.sol
├── utilities/
│   ├── Initializable.sol
│   └── ReentrancyGuard.sol
├── interfaces/
│   └── ILedger.sol
├── examples/
│   ├── ERC20.sol
│   ├── ERC4626.sol
│   ├── Sentry.sol
│   └── Token.sol
├── tests/
│   ├── modules/
│   ├── libraries/
│   └── examples/
└── docs/
    └── api/               # generated by forge doc

Core Concepts

• Module.sol: Abstract base contract that all modules inherit, defining the shared interface and access to storage.
• Router.sol: The immutable entrypoint that delegates calls to upgradeable modules via delegatecall.
• Ledger.sol: A hierarchical double-entry accounting system with a canonical root at address(this) plus additional token roots registered in the same contract.
• ERC20.sol: Optional canonical-root ERC20 surface layered over LedgerLib state via the Router.
• FloatLib.sol: A custom fixed-point math library for precision arithmetic with dynamic scaling.

Ledger Model

• Canonical root is always registered during initializeLedger(...).
• Internal roots are self-wrapped at creation, so the root address is immediately an ERC20 surface.
• Native and external roots can be registered first, then optionally wrapped later via createWrapper(...).
• Canonical-root ERC20 exposure is optional and provided by modules/ERC20.sol.
• Account/root flags include isGroup, isCredit, isInternal, isNative, isWrapper, and isRegistered.

Installation

To use CavalRe contracts in your project via Git:

npm install https://github.com/CavalRe/cavalre-contracts.git

Then add this to your remappings.txt:

@cavalre/=node_modules/cavalre-contracts/

This allows you to import contracts like:

import {Module} from "@cavalre/modules/Module.sol";
import {Ledger} from "@cavalre/modules/Ledger.sol";

Philosophy

CavalRe's smart contracts are built with the following principles:

• Accounting-first architecture — balances are structured and provable
• Modular and upgradeable — contracts are composed through the Router and can be swapped as independent modules
• Auditable separation of concerns — no monolithic contracts, everything is isolated and testable

Development

Build/test/docs:

forge build
forge test
forge doc

Documentation:

• Docs Index

License

MIT