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
│   └── Tree.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: Hierarchical double-entry accounting, token-root registration, claim-token registration, transfer routing, and external/native wrap settlement.
• ERC20.sol: Optional canonical-root ERC20 surface layered over LedgerLib state via the Router.
• Tree.sol: Topology/debug surface for account-tree introspection and debugTree(s).
• FloatLib.sol: A custom fixed-point math library for precision arithmetic with dynamic scaling.

Ledger Model

• Canonical root is always registered during initializeLedger(...).
• All registered roots are debit groups.
• Root token kind is encoded as Native, External, Internal, or Claim.
• Internal and claim 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(...).
• Internal root creation uses createInternalToken(...) and is deterministic/idempotent: the same (name, symbol, decimals) maps to the same root.
• Claim root creation uses createClaimToken(...); each claim root references one registered non-claim Ledger leaf account and is deterministic by (name, symbol, decimals, claimAccount).
• Canonical-root ERC20 exposure is optional and provided by modules/ERC20.sol.
• Each root auto-registers a default source leaf derived from the configured source name.
• Account flags are decoded through LedgerLib.AccountKind and LedgerLib.TokenKind; use helpers such as isGroup, isLedger, isCredit, isInternal, isNative, isExternal, isClaim, 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