Mr Haven — Smart Contracts

Open-source contracts for the Mr Haven time vault protocol on Base.

Maintained by Sovren Software. Vendored lib/ (forge-std, openzeppelin-contracts, permit2) is pinned to deploy-time trees so forge build and forge test run without any submodule init step.

---

Table of Contents

• Architecture
• Mainnet Addresses
• Repository Structure
• Quickstart
• Testing
• Static Analysis
• License
• Contributing
• Security

---

Architecture

Mr Haven is a non-custodial time vault protocol on Base L2. Each user deploys a personal vault (an EIP-1167 minimal-proxy clone of VaultImplementation) via VaultRouter. Vaults hold USDC and earn yield through AaveYieldStrategyV1.

Funds are released according to user-defined plans:

• Scheduled plans (Type 0) — fixed-timestamp execution.
• Inactivity plans (Type 1) — execute when lastActivity + inactivityPeriod is reached. Owner can reset by calling recordActivity(). A challenge system (ChallengeLib) lets beneficiaries assert claims with halving cooldowns.

Recipients are identified by Ethereum address or by email; the email path uses hash-locked escrow (EmailEscrowManager) so beneficiaries can claim via a short-lived signed claim link.

Plan execution is permissioned through a three-tier model:

Tier	Who	When	Reward
1	BotAuth-approved executors	At trigger	none
2	Public executors	Trigger + 1h grace	0.1%

Detailed component descriptions live in docs/.

Key constants

Parameter	Value	Source
Funding fee	25 bps (0.25%)	ProtocolConstants
Scheduled execution fee	55 bps (0.55%)	ProtocolConstants
Inactivity execution fee	100 bps (1.00%)	ProtocolConstants
Partner / treasury split	40% / 60%	PartnerFeeLib
Grace period	1 hour	ProtocolConstants
Virtual share offset	1e6 (ERC4626)	ShareMath
Max batch size	500	ProtocolConstants

---

Mainnet Addresses

Live on Base (chainId 8453).

Core Infrastructure

Contract	Address
VaultRouter	0x8C09a5f79e62D29BeB9d2FA710Ecc4cC17cdE842
VaultImplementation	0xCC797001307F5739dEDb645a5b800256E1429555
PlanExecutor	0x244eA67F2FcaEBeEBeCdFF1cE45a9abB4918E02D
FeeManager	0xFa77354cE60a87996BF068bDc5E4F568D3a9BAC9
BotAuth	0xDb2Ed946EEb042b4c5a4F5530a8d165b42C55b04
PartnerClaimManager	0xdEAf48e4B7953BCb576018D7dc5e7333B3845f76
AutomationAdapter	0x4396a084A8eBD4E7eCa8f6bd3c4AC6aF0375bF89
EmailEscrowManager	0x2E3E2aC4F32A0eEe3b811D302fBB897f1E027b25

Yield

Contract	Address
YieldStrategy impl	0x95528Ff4483CC27ca88a224c9B2f25d6543FC9F6
YieldStrategyManager	0x184A75e08f7be95ad55BF50e515a43432372Ab94

Automation

Contract	Address
BackendExecutor	0x842DD017578278EebAec26d7F450AEF649bF308b
ChainlinkForwarder	0xB1dfB504aA59052dFFc95EA430a18cd2341F1aA7

Treasury / Admin

Contract	Address
Treasury	0x1AdC9040D55572eb23E5B74E0752D46C19c4630b
Multisig	0xF80bc06DF1f596eA5c875b9802dA5a64997Bd996

SecureDocs

Contract	Address
CachedVaultRegistry	0x5F6335828d23B84574fA949A1D85D77600eF22C4
DocumentPackageRegistry	0xFEd4eA505A3823769f28A75e29E442b9b985D05B

Tokens

Token	Address
USDC (Base)	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
aUSDC	0x4e65fE4DbA92790696d040ac24Aa414708F5c0AB

---

Repository Structure

mr-haven-v1-contracts/
├── src/v1/                    # Production contract source
│   ├── core/                  # MrHavenTimeVault, PlanExecutor, VaultRouter,
│   │                          # AutomationAdapter, BotAuth, VaultStorageLayout
│   ├── escrow/                # EmailEscrowManager, PartnerClaimManager
│   ├── fees/                  # StandardFeeManager
│   ├── governance/            # FlexibleTimelock
│   ├── interfaces/            # External integration surface (12 files, MIT)
│   ├── libraries/             # Business-logic libraries (20 files, MIT)
│   ├── policy/                # PolicyEngine
│   ├── strategies/            # AaveYieldStrategyV1, YieldStrategyManager
│   ├── types/                 # PlanTypes
│   ├── vesting/               # VestingModule
│   └── mocks/                 # Test mocks
│
├── test/                      # Foundry test suite (MIT)
│   ├── BaseTest.sol           # Shared fixtures
│   ├── unit/                  # Unit tests (vault, router, adapter, fees)
│   ├── gas/                   # Gas benchmarks (Aave-V4-style snapshots)
│   └── v1/                    # Integration / security / fuzz / invariant
│
├── script/                    # Foundry deploy & admin scripts
│   ├── deploy/                # DeployV1_Mainnet, DeployV1_Testnet, etc.
│   ├── admin/                 # ProposeTreasuryChange, RedeployFeeManager
│   ├── helpers/               # RegisterVault
│   └── archive/               # Historical V8 deploy scripts
│
├── docs/                      # Architecture notes & deployment guides
├── audits/                    # Public audit reports (as released)
├── tools/                     # Static-analysis runners and helpers
│
├── lib/                       # Vendored deps (pinned to deploy-time trees)
│   ├── forge-std/
│   ├── openzeppelin-contracts/
│   └── permit2/
│
├── snapshots/                 # Gas snapshots tracked in git
├── foundry.toml               # Foundry configuration
├── remappings.txt             # Foundry import remappings
├── Makefile                   # Common build/test/analysis targets
├── slither.config.json        # Slither static-analysis config
├── .solhint.json              # Solhint linter config
├── .prettierrc                # Prettier formatter config
├── .editorconfig
├── .env.example               # Environment template
├── LICENSE                    # AGPL-3.0 (protocol)
├── LICENSE-MIT                # MIT (interfaces, libraries, tests)
├── CONTRIBUTING.md
└── SECURITY.md

---

Quickstart

Prerequisites

• Foundry — install with curl -L https://foundry.paradigm.xyz | bash && foundryup. Any recent stable Foundry release works; the version used at deploy time is recorded in foundry.lock.

Clone and build

git clone git@github.com:sovren-software/mr-haven-v1-contracts.git
cd mr-haven-v1-contracts
forge build

Vendored dependencies are pinned at deploy-time trees — no git submodule init needed.

Run tests

forge test

Fork tests skip cleanly when BASE_RPC_URL is unset. To run them, copy the template and populate with a non-rate-limited endpoint:

cp .env.example .env
$EDITOR .env  # set BASE_RPC_URL
forge test

---

Testing

Current state: 852+ unit, integration, fuzz, and invariant tests passing.

Test layout

Path	Scope
test/unit/	Per-component unit tests (vault, router, adapter, fees)
test/v1/core/	Core contract integration
test/v1/escrow/	EmailEscrowManager flows
test/v1/fees/	Fee accounting + partner routing
test/v1/policy/	PolicyEngine
test/v1/strategies/	AaveYieldStrategyV1 + YieldStrategyManager
test/v1/features/	Acceleration, response window, challenge mode
test/v1/integration/	Multi-contract flows (inactivity E2E, budget enforcement)
test/v1/fuzz/	Property-based fuzz tests
test/v1/invariant/	Invariant suites
test/v1/fork/	Mainnet-fork tests (require BASE_RPC_URL)
test/v1/pattern-b/	B2 split / delegatecall patterns
test/gas/	Gas benchmarks + snapshots

Targeted runs

# Specific contract
forge test --match-contract VaultRouterTest -vvv

# Gas report
forge test --gas-report

# Refresh snapshot
forge snapshot

Makefile has shortcuts for common runs (make build, make test, make gas-report, make gas-snapshot).

---

Static Analysis

Tooling lives in tools/ and is configured at the repo root:

# Install local tools (slither, aderyn, mythril)
bash tools/install-security-tools.sh

# Run individual analyzers
bash tools/analyze-slither.sh
bash tools/analyze-aderyn.sh
bash tools/analyze-mythril.sh

# Run all
bash tools/analyze-all.sh

Reports land under reports/ (gitignored). Slither configuration is in slither.config.json; Gambit mutation-testing configuration is in tools/gambit.json.

Public audit history is published under audits/ as it becomes available for release.

---

License

This repository is dual-licensed:

Layer	License	Files
Protocol implementation	GNU AGPL-3.0-or-later (LICENSE)	src/v1/{core,escrow,fees,governance,policy,strategies,types,vesting,mocks}/, script/
Integration surface	MIT (LICENSE-MIT)	src/v1/{interfaces,libraries}/, test/

Each .sol file declares its applicable license via an SPDX-License-Identifier header on the first line. The header is authoritative.

In practice this means:

• Builders integrating with Mr Haven through interface signatures, type definitions, or the protocol libraries can vendor those files into MIT-licensed projects without copyleft obligations.
• Forks of the protocol implementation must be released under AGPL-3.0-or-later, including modifications served over a network.
• Internal commercial use of unmodified contracts is unrestricted.

Vendored dependencies under lib/ (forge-std, openzeppelin-contracts, permit2) retain their upstream licenses.

Copyright © 2025–2026 Sovren Software. "Mr Haven" is a trademark of Sovren Software.

---

Contributing

See CONTRIBUTING.md. The repository is a frozen V1.0.2 archive; we are not currently accepting external pull requests pending CLA infrastructure. Issues and security disclosures are welcome.

---

Security

Vulnerabilities holding live user funds — please follow SECURITY.md. Do not open public issues for security-sensitive findings.

Contact: security@sovren.software