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/
│   ├── dispatcher/
│   ├── ledger/
│   └── tree/
├── math/
│   ├── FloatLib.sol
│   └── FloatStrings.sol
├── utilities/
│   ├── Initializable.sol
│   ├── MemoryLib.sol
│   ├── RandomLib.sol
│   └── ReentrancyGuard.sol
├── examples/
│   ├── ERC20.sol
│   ├── ERC4626.sol
│   ├── LedgerERC20.sol
│   ├── LedgerERC20Lib.sol
│   ├── Sentry.sol
│   └── Token.sol
├── tests/
│   ├── modules/
│   ├── libraries/
│   └── examples/
└── docs/
    └── api/               # generated by forge doc

Core Concepts

• Dispatchable.sol: Abstract base contract for modules installed behind a dispatcher.
• Dispatcher.sol: Immutable entrypoint that delegates calls to installed modules via delegatecall.
• Ledger.sol: Hierarchical double-entry accounting, native/external root registration, transfer routing, and external/native wrap settlement.
• LedgerTokenFactory.sol: Deterministic internal and share token-root creation.
• ShareTokenLib / ShareTokenView: Internal share operations and application-controlled settlement composition; ShareToken adds backing/conversion views to ERC20 behavior. See share tokens.
• LedgerERC20.sol: Optional canonical-root ERC20 surface layered over LedgerLib state via the Dispatcher.
• TreeView.sol: Topology/debug surface for account-tree introspection and debugTree(s).
• FloatLib.sol: 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.
• Ledger uses typed token kinds (Unregistered, Native, External, Internal); shares are internal tokens with backing registered in ShareTokenLib's own namespace. Packed addresses always identify parents; every ledger packs ROOT_ADDRESS.
• Internal and share token roots are self-wrapped at creation, so the root address is immediately an ERC20 surface.
• Native and external roots do not get separate wrapper surfaces.
• External root registration uses Ledger.addExternalToken(address[]).
• Internal root creation uses LedgerTokenFactory.createInternalTokens(TokenMetadata[]) and is deterministic/idempotent: the same (name, symbol, decimals, version) maps to the same root.
• Share token root creation uses LedgerTokenFactory.createShareTokens(ShareTokenConfig[]); each share token root references one registered absolute Ledger leaf account outside its own token tree and is deterministic by (name, symbol, decimals, version).
• LedgerView exposes root-registry pagination through rootCount(), rootAt(index), and roots(start, limit).
• Canonical-root ERC20 exposure is optional and illustrated by examples/LedgerERC20.sol.
• Each root auto-registers LedgerLib.SOURCE_ADDRESS / Source as the default credit source leaf; address(0) is reserved for ERC20 mint/burn event projection.
• Ledger decodes typed account and token kinds. ShareTokenLib stores immutable backing references; ShareTokenView.isShareToken(token) and backingAccount(token) read that registration.

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 {Dispatchable} from "@cavalre/modules/dispatcher/Dispatchable.sol";
import {Ledger} from "@cavalre/modules/ledger/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 Dispatcher 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