Mezo TreasuryOS

The treasury operating system for BTC-backed MUSD capital on Mezo.

Mezo lets Bitcoin holders borrow MUSD without selling BTC. Mezo TreasuryOS turns that capital rail into a treasury operating system for institutions: borrow against BTC, preserve liquidity, allocate approved surplus, defend collateral health, and produce board-ready reporting from one policy-governed workspace.

The agent is not trusted. The policy is trusted.

Live Demo • What Is Live • How It Works • Dashboard • Testnet Proof • Roadmap • Docs

TL;DR

Mezo TreasuryOS demonstrates a full BTC treasury workflow on Mezo testnet:

BTC collateral backs a live Mezo MUSD position.
Borrowed MUSD lands inside a client-isolated TreasuryAccount.
The treasury can use part of the borrowed MUSD for operations while preserving a required liquid buffer.
Only policy-approved surplus MUSD can route into Mezo-native sleeves such as MUSD Savings.
Sensitive actions remain controlled by a TreasuryOS-native TreasuryMultisig today, with external custody or contract-wallet owners supported as a production path.
TreasuryAutomationExecutor allows a gas-only keeper to execute only whitelisted, capped defensive actions.
An AI-CFO Agent reads deterministic state, explains tradeoffs, and prepares proposal packets without signing or custody.
A read-only dashboard shows one institutional tenant workspace, policy decisions, and audit trail proof.

Mezo TreasuryOS is not a custody provider, not a generic dashboard, and not a proprietary yield protocol. It is the treasury operating layer on top of Mezo’s BTC-backed MUSD capital rail.

Live Demo

Dashboard: mezo-treasuryos.vercel.app
Local dashboard: make dashboard-data && make dashboard-dev
Network: Mezo Testnet / chain ID 31611
Primary proof command: make scenario-proof
Deployment record: docs/MEZO_TESTNET_DEPLOYMENT.md
Final runbook: docs/FINAL_DEMO_RUNBOOK.md

The hosted dashboard is a read-only one-tenant demo workspace generated from TreasuryOS CLI snapshots and public Mezo testnet contract data. It does not hold keys, request signatures, or broadcast transactions.

Why This Matters

Mezo provides the BTC-backed MUSD capital rail. Mezo TreasuryOS provides the operating layer that makes that capital usable by real treasury teams.

Mezo makes it possible to unlock MUSD liquidity against BTC.

That is the capital rail.

A serious treasury still needs:

internal controls
approval workflows
liquidity buffer management
governed deployment of idle MUSD
automated treasury operations
collateral-health and liquidation-risk management
accounting and reviewer-facing reporting

Without that layer, BTC-backed working capital remains a loose mix of protocol actions, wallet flows, manual approvals, and spreadsheets.

TreasuryOS turns Mezo’s BTC-backed borrowing into a treasury workflow.

Built For

Mezo Hackathon — Bank on Bitcoin / Bitcoin Track

Primary focus area:

BTC Treasury Management & Institutional Services

Secondary fit:

Borrowing & Leverage on BTC — collateral health, repayment, and liquidation-defense controls
Bitcoin Yield & Investment — policy-governed MUSD Savings, Tigris sleeve evaluation, and guarded BTC-yield planning
Paying & Receiving BTC on Mezo — future x402-paid treasury intelligence and reporting APIs

Track alignment:

Focus	TreasuryOS implementation
Corporate treasury solutions	Client-isolated Treasury Accounts with BTC collateral, MUSD debt, operating buffers, and allocation controls
Institutional custody integration	TreasuryOS-native `TreasuryMultisig` today; external custody / contract-wallet ownership path supported
Accounting and reporting tools	Read-only dashboard, CLI snapshots, audit trail, Goldsky scaffold
Compliance/control infrastructure	`TreasuryPolicyEngine`, approval checks, caps, policy decision traces
Multi-sig treasury management	Client `TreasuryMultisig` owns the live TreasuryAccount
Automated treasury operations	`TreasuryAutomationExecutor` plus gas-only keeper with whitelisted, capped defense actions
Robo-advisors for Bitcoin portfolios	AI-CFO Agent writes advisory memos and proposal packets from deterministic state
Risk management tools	Projected CR checks, post-stress CR, defense-capacity model, blocked BTC sleeve decisions

Submission Snapshot

Area	Status
Mezo testnet deployment	Live
MUSD integration	Live
BTC-backed MUSD position	Live
Client `TreasuryAccount`	Live
TreasuryOS-native `TreasuryMultisig` ownership	Live
`TreasuryAutomationExecutor`	Live; keeper allowlisted and capped
MUSD Savings allocation	Live
Keeper buffer restoration	Live transaction
Keeper idle-MUSD debt repayment	Live transaction
Critical de-risk action	Proposal calldata, not executed on tiny live position
AI-CFO Agent	Implemented; advisory/proposal-only
Dashboard	Read-only one-tenant workspace
Spectrum RPC path	Preferred and reported by health checks
Goldsky	Scaffolded for reporting/indexing
Protocol fees	Deployed, disabled, not wired into treasury execution
Tigris MUSD/mUSDC sleeve	Contract-ready; route-health dependent on current testnet liquidity
Tigris mcbBTC/BTC sleeve	Guarded BTC-correlated yield candidate; blocked in the current testnet demo until liquidity, price-impact, and tiny broadcast validation are acceptable

Detailed BTC sleeve policy and testnet liquidity notes are documented in docs/BTC_RESERVE_AND_YIELD_SLEEVES.md.

What Is Live vs Guarded

Live in the current demo

One multisig-owned client TreasuryAccount
BTC collateral deposited through TreasuryOS
Live MUSD position opened on Mezo testnet
MUSD allocated into MUSD Savings through TreasuryAccount.allocate
Policy proof for blocked unsafe or over-threshold actions
TreasuryAutomationExecutor configured for the client treasury
Keeper restore-buffer transaction through the executor
Keeper idle-MUSD debt-repayment transaction through the executor
AI-CFO opportunity review and advisory memo
Read-only dashboard generated from sanitized snapshots and public testnet data

Guarded, future, or production expansion

Production mainnet deployment with stronger protocol-admin, owner, and custody controls
External custody / contract-wallet proposal export for institutional approval workflows
Goldsky-backed event history and durable audit timeline
Broader Mezo ecosystem allocation coverage as reliable MUSD and BTC yield surfaces become available
Additional external BTC vault integrations on mainnet when accessible
BTC-denominated sleeve execution after controlled validation of liquidity, price impact, receipt accounting, and unwind paths
BTC lock / staking-style positions where withdrawal constraints and principal immobility are explicitly modeled
LP staking and reward-claim support for validated Tigris positions
Client-specific AI-CFO agents with monitor, proposer, reporter, and keeper roles
x402-gated treasury intelligence APIs for paid AI-CFO reports, risk snapshots, audit packs, and accounting exports
MEZO/MUSD subscription credits for monitoring, reporting, and premium treasury analytics

How Mezo TreasuryOS Works

TreasuryOS owns the workflow layer, while Mezo owns the native capital rail.

BTC collateral
  → Mezo-backed MUSD position
  → borrowed MUSD in TreasuryAccount
  → operating use + required liquidity buffer
  → policy-governed surplus allocation
  → keeper defense
  → AI-CFO reporting and audit trail

Core sequence:

A treasury creates an isolated TreasuryAccount.
The account is owned by a TreasuryOS-native TreasuryMultisig in the demo, or by an external custody / contract-wallet owner in production.
The treasury opens a Mezo BTC-backed MUSD position through TreasuryOS.
Borrowed MUSD lands inside the Treasury Account.
Part of the borrowed MUSD can be used for operating needs through the treasury control path.
Policy preserves a required liquid MUSD operating buffer.
Approved surplus can route into Mezo-native sleeves.
Keeper actions remain bounded to defensive workflows.
AI-CFO prepares memos and proposals without custody or signing.
Dashboard and CLI outputs provide reviewer-facing reporting.

System Schema

Capital workflow

flowchart LR
    BTC[Client BTC] --> Owner[TreasuryMultisig / custody owner]
    Owner --> TA[TreasuryAccount]
    TA --> Position[Mezo BTC-backed MUSD position]
    Position --> Collateral[BTC collateral]
    Position --> Debt[MUSD debt]
    Debt --> Capital[Borrowed MUSD operating capital]

    Capital --> Ops[Operating disbursements]
    Capital --> Buffer[Required liquid MUSD buffer]
    Capital --> Surplus[Policy-approved surplus]

    Surplus --> Savings[MUSD Savings Vault]
    Surplus --> Tigris[Tigris MUSD/mUSDC]

    Reserve[Idle BTC reserve] --> BTCPolicy[BTCReservePolicy]
    BTCPolicy --> BTCSleeves[BTC-correlated sleeves and future BTC vaults]

    Keeper[Treasury Risk Keeper] --> Defense[Buffer restore / debt repay / collateral defense]
    Defense --> TA

    AICFO[AI-CFO Agent] --> Report[Memo + proposal packet]
    TA --> Dashboard[Read-only dashboard + audit trail]

Control boundary

flowchart TB
    Owner[TreasuryMultisig / external custody owner] --> Account[TreasuryAccount]
    Account --> Policy[TreasuryPolicyEngine]
    Policy --> Allocation[Allocation rules / caps / approvals]
    Policy --> Risk[CR and post-stress checks]

    Keeper[Gas-only Keeper EOA] --> Executor[TreasuryAutomationExecutor]
    Executor --> Policy
    Executor --> Account

    AICFO[AI-CFO Agent] --> Memo[Memo + proposal packet]
    Memo -. approval required .-> Owner

    Dashboard[Read-only dashboard] -. observes .-> Account

Detailed schema: docs/SYSTEM_SCHEMA.md

Architecture

TreasuryOS has three layers.

1. Onchain treasury control layer

TreasuryAccountFactory
TreasuryAccount
TreasuryPolicyEngine
TreasuryMultisig
TreasuryAutomationExecutor
AllocationRouter
MUSDSavingsRateHandler
TigrisStablePoolHandler
BTCReservePolicy
disabled fee infrastructure

2. Offchain treasury operations layer

Spectrum-backed state reads
treasury snapshots
Yield Console
Treasury Risk Keeper
AI-CFO Agent
term-yield planner
BTC sleeve planner
Goldsky scaffold

3. Product interface layer

read-only dashboard
CLI proof flows
audit trail
reporting output
proposal calldata views

Full architecture: docs/ARCHITECTURE.md

Key Control Boundaries

TreasuryOS is designed so automation and AI do not become uncontrolled execution authority.

Actor / component	Can do	Cannot do
AI-CFO Agent	Read state, rank opportunities, write memos, prepare proposal packets	Sign, custody, broadcast, bypass policy
Keeper EOA	Pay gas for whitelisted defensive executor calls	Receive treasury assets, execute arbitrary withdrawals
TreasuryMultisig / custody owner	Execute sensitive treasury actions	Replace policy checks where the account enforces them
TreasuryPolicyEngine	Enforce limits, caps, approval requirements, risk checks	Custody funds
TreasuryAutomationExecutor	Route whitelisted defensive calls after policy validation	Execute arbitrary treasury actions
Dashboard	Display state, proof, links, and policy traces	Request signatures or broadcast transactions

Quick Start

Requirements

Node.js
Foundry (forge, cast, anvil)
Make
Mezo testnet RPC configuration in .env

Install

make install

Build and test

make build
make test

Check Mezo RPC health

make rpc-health

Run final proof commands

make demo-status
make scenario-proof
make advisor-cfo
make advisor-opportunities
make yield-console-demo
make risk-keeper-demo
make risk-keeper-propose-critical

Run the dashboard locally

make dashboard-data
make dashboard-vercel-check
make dashboard-dev

The public demo flow is wrapped in make targets. Lower-level package scripts exist for service-specific development, but the reviewer path should use the commands above.

Demo Commands

Command	Purpose
`make demo-status`	Prints live demo readiness: RPC, sleeves, keeper, fees, BTC sleeve boundary
`make scenario-proof`	Main read-only scenario matrix with deployed addresses, state, policy proof, keeper txs, AI-CFO summary
`make advisor-cfo`	Generates the AI-CFO recommendation/memo flow from deterministic state
`make advisor-opportunities`	Shows ranked opportunities and blocked reasons
`make yield-console-demo`	Shows buffer, allocatable surplus, sleeve exposure, and policy posture
`make risk-keeper-demo`	Shows keeper state and deterministic recommendation
`make risk-keeper-propose-critical`	Prints critical sleeve-funded repayment proposal calldata
`make dashboard-data`	Generates sanitized dashboard snapshot data
`make dashboard-vercel-check`	Builds/scans the dashboard for static hosting readiness
`make dashboard-dev`	Starts the local read-only dashboard

Deployed Mezo Testnet Stack

Current active deployment: Mezo Testnet, chain ID 31611.

Protocol core

Contract	Address
`TreasuryPolicyEngine`	`0xe437...cC2e7`
`BTCReservePolicy`	`0x4d60...afAe`
`TreasuryAccount` implementation	`0xCc54...BB36`
`TreasuryAccountFactory`	`0xC28e...AcD2`

Client treasury

Contract	Address
Client `TreasuryMultisig`	`0x25a1...Be3`
`TreasuryAccount` clone	`0xaB79...7ac7`
`TreasuryAutomationExecutor`	`0xD5b3...25bF`
`AllocationRouter`	`0xf6FC...338E`
`MUSDSavingsRateHandler`	`0x801E...c0fF`
`TigrisStablePoolHandler`	`0x4B76...E785`

Fee infrastructure

Fee contracts are deployed for future monetization but disabled for the hackathon demo.

Contract	Address
`ProtocolFeeVault`	`0x78c2...EE3d`
`ProtocolFeeManager`	`0x5227...a019`

Full deployment details: docs/MEZO_TESTNET_DEPLOYMENT.md

Live Transaction Proof

Explorer-verifiable transaction proof is available in the hosted dashboard audit trail and docs/FINAL_DEMO_RUNBOOK.md. The detailed runbook includes the live borrow, MUSD Savings allocation, keeper buffer restoration, and keeper debt-repayment transactions plus interpretation notes for the AllocationRouter internal dispatch path.

Dashboard

The dashboard is a read-only Client Treasury Workspace.

It shows:

tenant data snapshot
BTC and MUSD balance sheet
current and post-stress collateral health
policy and control boundaries
keeper recommendation and critical proposal calldata
AI-CFO Agent memo and prepared proposal packet
MUSD allocation/yield console
policy decision trace
audit trail with explorer-verifiable transaction proof
data and infrastructure status

Run locally:

make dashboard-data
make dashboard-dev

Static hosting check:

make dashboard-vercel-check

For Vercel:

Root Directory: dashboard
Framework Preset: Other
Build Command: npm run build
Output Directory: dist

Do not configure private keys, keeper keys, OpenAI keys, or private RPC URLs in the hosted dashboard.

AI-CFO Agent

TreasuryOS includes an AI-CFO workflow without trusting AI with treasury funds.

The AI-CFO Agent combines deterministic TreasuryOS state with optional premium LLM memo generation. The deterministic advisor computes the facts: treasury state, policy results, opportunity ranking, blocked reasons, and proposal details. The LLM layer turns those facts into an investment-committee-style memo for treasury operators.

The model can explain and prepare. It cannot sign, custody, broadcast, or bypass policy.

The AI-CFO Agent:

reads TreasuryAccount state, BTC collateral, MUSD debt, idle MUSD, sleeve allocations, and reserve buckets
reads live Mezo opportunities such as MUSD Savings, Tigris MUSD/mUSDC, and mcbBTC/BTC
ranks opportunities by policy fit, liquidity, route health, risk class, approval requirement, and execution readiness
writes treasury admin / investment committee memos
prepares proposal packets and calldata helpers
explains blocked opportunities

It cannot:

hold keys
custody BTC or MUSD
execute arbitrary swaps
bypass policy
move BTC principal without owner or multisig approval

More: docs/AI_CFO_AGENT.md

Treasury Risk Keeper

TreasuryOS protects the BTC-backed MUSD position before chasing yield.

The V1 keeper supports:

projected collateral-ratio checks
post-stress collateral-ratio checks
weighted defense-capacity modeling
idle-MUSD debt repayment
MUSD Savings buffer restoration
sleeve-funded de-risk proposal calldata
guarded idle-BTC collateral top-up path
gas-only keeper execution through TreasuryAutomationExecutor

The keeper can execute only whitelisted, capped defensive actions after policy validation.

More: docs/TREASURY_RISK_KEEPER.md

BTC Reserve And Yield Boundary

TreasuryOS separates:

MUSD operating capital: borrowed working capital that must preserve a liquid MUSD buffer.
BTC-denominated treasury exposure: idle BTC reserve, BTC collateral, and future BTC-correlated yield positions.

The real Tigris mcbBTC/BTC pool is treated as a BTC-correlated sleeve candidate, not a normal MUSD allocation route. The current product correctly blocks it when shallow liquidity, price impact, reserve floors, or validation status make execution unsafe.

More: docs/BTC_RESERVE_AND_YIELD_SLEEVES.md

Documentation

Start here:

docs/SYSTEM_SCHEMA.md — product flow, capital buckets, control boundaries, and demo-proven scenario map
docs/FINAL_DEMO_RUNBOOK.md — exact final demo flow and proof commands
docs/MEZO_TESTNET_DEPLOYMENT.md — active deployed contracts, tx proof, and source verification notes
docs/ARCHITECTURE.md — full technical architecture
docs/TREASURY_RISK_KEEPER.md — bounded automation and defense model
docs/AI_CFO_AGENT.md — advisory agent model and guardrails
docs/BTC_RESERVE_AND_YIELD_SLEEVES.md — BTC sleeve policy and testnet liquidity boundary
docs/PROTOCOL_FEES.md — zero-default fee architecture and future monetization model
docs/DEPLOYMENT.md — deployment modes and ownership paths
docs/ROADMAP.md — post-hackathon product roadmap

Planning and pitch drafts should stay outside the public docs set so the submitted repo stays focused.

Repo Structure

mezo-treasuryos/
├─ config/
├─ contracts/
│  ├─ src/
│  │  ├─ adapters/
│  │  ├─ core/
│  │  ├─ external/
│  │  ├─ fees/
│  │  ├─ interfaces/
│  │  ├─ multisig/
│  │  └─ recovery/
│  ├─ script/
│  ├─ test/
│  └─ foundry.toml
├─ dashboard/
│  ├─ public/
│  │  ├─ data/
│  │  └─ src/
│  └─ scripts/
├─ services/
│  ├─ btc-sleeve-planner/
│  ├─ scenario-proof/
│  ├─ spectrum-state/
│  ├─ treasury-advisor/
│  ├─ treasury-risk-keeper/
│  ├─ term-yield-planner/
│  └─ yield-console/
├─ indexer/
│  └─ goldsky/
├─ deployments/
├─ docs/
├─ Makefile
└─ README.md

From Hackathon Demo To BTC Treasury Platform

TreasuryOS starts as one live Mezo testnet treasury workflow: borrow MUSD against BTC, preserve an operating buffer, allocate approved surplus, defend the position, and report the result.

The platform roadmap is broader: AI-assisted BTC treasury management, automated yield and risk operations, institutional reporting, compliance-ready controls, and paid treasury intelligence.

Platform area	Next expansion	Product value	Boundary
AI-CFO robo-advisor	Client-specific AI-CFO agents with what-if planning, policy-scored recommendations, proposal packets, and post-action reports	Turns TreasuryOS into an active treasury operator assistant	AI does not sign, custody, or bypass policy
Automated treasury operations	Scheduled buffer reviews, debt repayment, collateral defense, surplus sweep proposals, and policy-triggered escalation	Reduces manual treasury work and improves risk response	Routine actions stay capped; elevated actions require owner approval
Yield optimization	More Mezo-native MUSD/BTC sleeves, Tigris routes, BTC vaults, lock/staking-style positions, and unwind-aware allocation	Helps treasuries earn on approved surplus without blindly chasing APY	Route, liquidity, price-impact, and withdrawal constraints must pass policy
Borrowing and risk management	Credit-line style monitoring, collateral-ratio alerts, stress tests, liquidation-defense planning, and de-risk execution paths	Makes BTC-backed leverage safer for operating treasuries	Risk-reducing actions prioritized before yield
Accounting and reporting	Report packs, audit trails, policy decision history, approval evidence, and accounting exports	Makes TreasuryOS useful for finance teams, auditors, and institutional diligence	Reports reflect observed onchain state and deterministic snapshots
Compliance-ready controls	Destination allowlists, role policies, approval thresholds, KYB/client metadata, and restricted operating disbursements	Supports institutional treasury workflows beyond raw DeFi usage	Internal control infrastructure, not legal-compliance overclaiming
Mezo ecosystem expansion	Broader MUSD and BTC opportunity coverage as production-grade surfaces become available	Turns TreasuryOS into a routing and control layer for Mezo treasury capital	Integrations added only after safety and unwind validation
x402-paid treasury intelligence	Paid AI-CFO reports, risk snapshots, audit packs, strategy simulations, and agent-readable APIs	Creates a monetization layer for treasury intelligence	Payments gate intelligence and reporting, not custody or emergency execution

Future: x402-paid treasury intelligence

x402 is a future monetization layer for TreasuryOS intelligence: AI-CFO reports, risk snapshots, audit packs, strategy simulations, accounting exports, and agent-readable APIs.

The boundary is strict: x402 gates intelligence and reporting, not custody, collateral defense, or emergency execution.

Full roadmap: docs/ROADMAP.md

Product Boundaries

Mezo TreasuryOS is intentionally not:

a custody provider
a replacement for Mezo’s core borrow infrastructure
a replacement for institutional custody onboarding
a generic DeFi yield optimizer
an autonomous AI trader
a production-ready BTC sleeve allocator
a production financial advisor

V1 is a working Mezo testnet product prototype that proves the institutional treasury workflow and control architecture.

Final Takeaway

Mezo TreasuryOS turns Bitcoin-backed borrowing into institutional working-capital infrastructure.

A BTC treasury should not have to choose between idle Bitcoin, selling BTC, or manually operating DeFi positions through spreadsheets and private scripts. Mezo TreasuryOS gives that treasury a governed workspace to borrow MUSD, preserve liquidity, allocate approved surplus, defend collateral health, and produce board-ready reporting.

The result is not an AI trader or a yield wrapper. It is a control layer for Bitcoin working capital: multisig-owned, policy-enforced, keeper-defended, AI-explained, and explorer-verifiable.

License

MIT — see LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 81 Commits
config		config
contracts		contracts
dashboard		dashboard
deployments		deployments
docs		docs
indexer/goldsky		indexer/goldsky
services		services
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
package.json		package.json
pnpm-workspace.yaml		pnpm-workspace.yaml

Folders and files

Latest commit

History

Repository files navigation