MUTAV Protocol (Solana)
MUTAV is an institutional fiador: it gives Brazilian tenants a rental guarantee (fiança onerosa, Lei 8.245/91 art. 37 II) so they need neither a personal guarantor nor a deposit. Real-estate agencies distribute it through the MUTAV platform. Every guarantee is backed by an on-chain, verifiable BRL guarantee reserve, operated by MUTAV. This repository holds the Solana program that custodies that reserve: it records the cover of every active guarantee, admits guarantee fees and issuer income, pays approved claims to MUTAV's payments account, and refuses any capital movement that would leave the guarantees under-covered. The reserve is operational infrastructure that keeps the guarantees healthy, not a yield product. Anyone can recompute its coverage from public state.
Try it
Live pilot app: reserve.mutav.finance. Built for the Colosseum Crypto World's Fair (Sep 14 – Oct 12, 2026); submitted on 2026-10-12 and now in judging. The demo keeps every page open, including the capital area.
| Page | What it shows |
|---|
/reserve | The app's front page (/ redirects here; MUTAV's landing is mutav.finance). Public transparency: health, coverage, claims timeline, money flows, capital queue, disclosures, every account on Solana Explorer. No wallet needed |
/operator | Operator console. During the pilot MUTAV's team signs by hand with the operator wallet; later mutav-app's backend sends the same instructions with a KMS-held key |
/capital | Capital queue (/investment and /investor redirect here). Demo: the request form is visible to every visitor; on-chain actions stay allowlist-gated (holders can always redeem, ADR 0023). Before launch, set CAPITAL_FORMS_PUBLIC false to show the form only to allowlisted wallets (holders get redeem only). The pilot runs on MUTAV's own capital and is not open to public investment |
/admin | Reserve Admin: Squads v4 proposals (create, approve, execute after the time lock) |
/simulator | Reserve simulator: size the reserve, coverage, yield against Selic |
Status: the program is live on devnet as GhPkq95RkY7PrJLsv74X73s6ozcwf6JqJtjFouqQeZbV, with its upgrade authority and reserve admin held by Squads v4 multisigs. It runs the pilot demo reserve on devnet; test activity is visible, and the live pages read it. Addresses: Devnet addresses. To run every page against a seeded local validator instead, see Pilot app.
Read next: the protocol litepaper (a model for running guarantees on-chain), the Brazil pilot paper (the first deployment), the specification, the architecture decisions and the development provenance.
Where to look in the code:
programs/mutav/src/coverage.rs: the coverage gate, which refuses any capital movement that would leave the guarantees under-covered. It never blocks a claim payment.programs/mutav/src/instructions/: instructions by area: admin/ (config, roles, pause), operator/ (guarantees, guarantee fees, claims), capital/ (the deposit and redemption queue), public/ (permissionless refresh).tests/: LiteSVM integration tests. clients/js/: the Codama client the app reads through.app/: the pilot web app. It holds no keys; wallets sign.
Pilot
The goal of the pilot is to prove that a digital-asset reserve can be run as a viable operation: MUTAV operates it, and anyone can verify it. It runs with real money and real guarantees under a low ceiling of hard on-chain caps (the founders' pilot values, also on devnet, ADR 0028: coverage ratio c = 0.25; R$1M maximum reserve; R$120k maximum cover per guarantee; R$15k / R$20k operator claim payments per call / per 31 days, so a compromised operator key can take at most R$20k in any 31 days, about 2% of the maximum reserve; R$19k stress buffer; BRS only). The reserve holds c × the remaining cover of every guarantee, and never less than the filed claims (ADR 0016). Admins raise the caps only as the pilot proves itself. See docs/spec.md for the full list.
The pilot reserve holds BRS (Nora Finance, 1:1 BRL stablecoin). More assets can be added later through whitelisted, capped adapters: Etherfuse TESOURO (tokenized Brazilian treasury) is the first candidate, pending an Etherfuse BRS path (ADR 0018).
The reserve grows from two sources besides capital: guarantee fees (contribute_fees, net of MUTAV's take) and issuer income, Nora's monthly BRS revenue share to its partners. Nora pays that income into the reserve's income inbox (the vault authority's associated token account for BRS, created at initialize), where it counts toward nothing; each month the operator sweeps the amount on Nora's statement into the reserve with sweep_income, which books it and raises NAV (ADR 0017). It is shown as issuer partnership revenue, separate from fees, and never enters the coverage math.
Scope of this repo
This repo ships the on-chain program, a TypeScript client that composes transactions, and the pilot web app (app/): a demo and transparency app built for the Colosseum hackathon. It holds no keys: the client composes, wallets sign. After the hackathon, the production user-facing surfaces (admin console, investor area, agency transparency page) and the operator automation live in mutav-finance/mutav-app, which consumes the client published from here as @mutav-finance/mutav-protocol-solana.
Layout
mutav-protocol-solana/
├── programs/
│ ├── mutav/ # core program: custody, shares, NAV, exposure registry,
│ │ # coverage gate, async queue, roles, claim payments
│ ├── mutav-adapter-interface/ # crate: shared adapter discriminators and layouts
│ └── mutav-adapter-mock/ # devnet and tests only
├── tests/ # LiteSVM integration tests
├── tests-fork/ # Surfpool mainnet/devnet-fork tests
├── clients/js/ # Codama-generated client (@mutav-finance/mutav-protocol-solana)
├── app/ # pilot web app (Next.js): / → /reserve, /reserve, /operator, /capital, /admin, /simulator
├── scripts/ # devnet bootstrap: initialize, roles, caps, allowlist
└── docs/
├── spec.md # protocol specification (source of business rules)
├── plan.md # implementation plan
├── provenance.md # hackathon development provenance
└── decisions/ # architecture decision records
Quickstart
Toolchain
| Tool | Version |
|---|
Anchor CLI (via avm) | 1.2.0 |
| Solana CLI (Agave) | 4.1.2 |
| Rust | ≥ 1.89 (pinned to 1.94.1 in rust-toolchain.toml) |
| Surfpool | 1.6.0 |
| Bun | current stable |
avm install 1.2.0 && avm use 1.2.0
agave-install init 4.1.2
Build
anchor build
Test
Tests run on LiteSVM. Cap threads and build jobs: several test runners at once will saturate the machine.
anchor build # tests load the compiled programs from target/deploy
RUST_TEST_THREADS=4 CARGO_BUILD_JOBS=4 cargo test -p mutav-tests
Fork tests (Surfpool, against Nora's devnet BRS mint) run separately and on demand: bun tests-fork/happy-path.ts --program-keypair <path>; see tests-fork/README.md.
Client
The client in clients/js is generated from the program IDL with Codama (see clients/js/package.json for the generate and build scripts). Regenerate it after any change to the program interface, and commit the result. Hand-written PDA, read and preview helpers sit next to the generated code; see clients/js/README.md. bun run test:client checks them against vectors exported from the program.
No command in this repo runs in watch mode.
Pilot app
app/ is a Next.js 16 app that shows the reserve working on Solana, live at reserve.mutav.finance: / redirects to /reserve, /reserve public transparency (tabs Overview, Coverage, Claims, Capital, Risks, Verify at sub-routes coverage, claims, capital, risks, verify: health, coverage, claims timeline, flows, every account on Explorer, with snapshot charts), /operator the operator console (with the live coverage-gate preview; /demo redirects there), /capital the allowlist-gated capital queue, /admin Squads v4 proposal builders, and /simulator the reserve simulator. Every action is tagged with the role that signs it: Reserve Admin, Operator or Investor. Every number on screen is read from on-chain accounts through clients/js. Wallets sign; the server composes unsigned transactions and relays signed ones. Details: app/README.md, rules: app/CLAUDE.md, spec: app/docs/spec.md.
Run it locally against a seeded validator (port 3001, since 3000 is often taken):
anchor build # the validator loads target/deploy/mutav.so
cd app
bun install # postinstall builds clients/js if dist/ is missing
bun run localnet:up # start + seed a local validator, write .localnet/env
cp .localnet/env .env.local
NEXT_PUBLIC_CLUSTER=localnet bun run build && PORT=3001 bun run start
bun run localnet:down # stop the validator; asserts nothing is left running
Checks: bun run typecheck && bun run test && NEXT_PUBLIC_CLUSTER=localnet bun run build; the Playwright smoke is bun run e2e (starts and stops its own validator).
Deploying
The scripts in scripts/devnet/ compose instructions; they never open a key file and never sign. Two Squads v4 multisigs hold authority: the admin multisig (squads, its vault is VaultConfig.admin, time lock ≥ 5 min on devnet) and the upgrade multisig (upgradeSquads, its vault is the program upgrade authority, time lock ≥ 1 h on devnet). Every admin step is therefore written as an unsigned Squads proposal (*.json), and members create, approve and execute it in the pilot app's /admin console (reserve.mutav.finance) or the Squads app, signing with their own wallets; mutav-app's apps/admin becomes the signing home later. Roles and the security level each deployment must meet are in docs/security/baseline.md (proposed). Only deploy.ts touches keys: it passes keypair paths, kept outside the repo, to the Solana CLI, and refuses a payer file readable by group or other (chmod 600).
Every script that reads the chain takes a full http(s) --url (cluster monikers such as m or devnet, and empty values, are refused) and checks the RPC's genesis hash: mainnet is always refused, a loopback URL counts as local, and any other URL needs --confirm-cluster devnet and devnet's genesis hash. The cluster must match the config's cluster. They are not built for mainnet: mainnet goes through .github/workflows/release.yml and the spec §14.5 runbook.
# 0. Rehearse everything against a throwaway local validator.
anchor build
bun scripts/devnet/dry-run.ts --program-keypair ~/.config/solana/mutav/mutav-keypair.json
# 1. Fill a copy of scripts/devnet/devnet.example.json outside the repo (every <FILL: …>):
# both multisigs, their exact members, the vaults, roles and money accounts.
# Build with `solana-verify build --library-name mutav --base-image <VERIFY_BASE_IMAGE
# from .github/workflows/release.yml>` and record the executable hash of the verified build.
CFG=~/mutav/devnet.json; RPC=https://api.devnet.solana.com
HASH=$(solana-verify get-executable-hash target/deploy/mutav.so)
# 2. Deploy, then hand the upgrade authority to the upgrade multisig's vault.
# Refuses before any CLI call unless --upgrade-authority equals the config's
# upgradeAuthority and the vault derived from upgradeSquads, and both
# multisigs pass the checks below, and the .so's executable hash equals
# --expected-hash (the verified build). A failed handover prints the retry command.
bun scripts/devnet/deploy.ts --config $CFG --url $RPC --confirm-cluster devnet \
--payer ~/.config/solana/mutav/deployer.json \
--program-keypair ~/.config/solana/mutav/mutav-keypair.json \
--upgrade-authority <UPGRADE_VAULT> --expected-hash $HASH
# 3. Proposals. init.json is for the upgrade multisig (fund its vault with ~0.1 SOL
# first: it pays rent for initialize); the others are for the admin multisig.
# init.ts refuses a reserve mint without 6 decimals or under another token program.
bun scripts/devnet/init.ts --config $CFG --url $RPC --confirm-cluster devnet --out init.json
bun scripts/devnet/allowlist.ts --config $CFG --proofs allowlist-proofs.json --out allowlist.json
# … execute both, then if needed:
# roles.ts also cancels any pending operator or pauser handover the config does not ask for.
# A pending admin is kept if the config names it as `nextAdmin`; otherwise roles.ts refuses unless --cancel-admin is passed.
bun scripts/devnet/roles.ts --config $CFG --out roles.json
bun scripts/devnet/caps.ts --config $CFG --url $RPC --confirm-cluster devnet --out caps.json
# 4. Post-deploy checks. initialize does not set the allowlist root: run this only after
# allowlist.json (and roles.json, if any) has executed.
bun scripts/devnet/verify.ts --config $CFG --url $RPC --confirm-cluster devnet --expected-hash $HASH
Before the devnet deploy, follow Turning on idl-compat at deploy. Tag the deployed commit v1.0.0-devnet with a GitHub release carrying the verified mutav.json, mutav.so and mutav.hash.
Program upgrades go through scripts/release/upgrade-proposal.ts (run by .github/workflows/release.yml), which also takes --expected-hash: it refuses unless the buffer is owned by BPF Loader Upgradeable, its authority is the upgrade vault and its program bytes hash to the expected value (as solana-verify get-buffer-hash), and ProgramData's upgrade authority is the vault.
verify.ts checks:
- the deployed program is the verified build: the ProgramData program bytes hash to
--expected-hash (as solana-verify get-program-hash);
- the upgrade authority is the upgrade multisig's vault;
feature_flags == 0;- admin, operator, pauser and the allowlist root are as configured, with no pending operator, pauser or admin handover, and the guardians are exactly the config's
guardians (none when empty);
- every other
VaultConfig field equals the config file, field by field (c, fee take, every cap including max_nav_move_bps, 6 decimals, mint, token program, money accounts, capital wallet);
- on devnet, the locked devnet values (
scripts/devnet/lib/compare.ts); a max_claim_per_period raised for a large claim payment is reported until it is lowered again;
- the treasury and payments accounts hold the reserve mint and are not owned by the operator;
- the reserve mint is owned by
reserveTokenProgram and has 6 decimals;
- both multisigs are owned by the Squads v4 program, autonomous (
config_authority == Pubkey::default()), with exactly the configured members (each able to vote), exactly the configured threshold, and time_lock ≥ the floor.
bun run check:no-keys scans clients/js/src, app/ and scripts/ for key-handling and signing APIs; the known exceptions (localnet-only tooling, wallet-side signing) are listed in scripts/no-keys-allowlist.txt.
After the deploy, dump the live VaultConfig and VaultState into tests/fixtures/layout/v1/ (spec §14.7).
The devnet example sets caps.maxNavMoveBps = 10000. The NAV-move guard measures the move gross, so on a small demo reserve a guarantee-fee batch or a claim payment would otherwise trip it and halt fulfilment. The inflow-adjusted guard is ADR 0013, which is pending. Until it lands, the admin can clear a tripped guard with clear_fulfil_halt (ADR 0015). Lower the bound for the real pilot.
Devnet addresses
The pilot demo reserve on devnet; test activity is visible. Every address opens on Solana Explorer (devnet), and /api/reserve returns the same set as JSON.
About this deploy:
- It is a test deploy of commit
833c114 (layout v1, the binary on main at the time) built with anchor build under its own program ID. The ID declared in lib.rs, 8scC79jkU7SPM9v6M4nB833R8EeqKknfwdRdjn73Qqv9, is kept for the verified solana-verify release build, so the reserve PDAs above differ from those derived under the declared ID.
- The on-chain program hash matches the build (
fad721d5…e6e7). The release v1.0.0-devnet carries its IDL.
- Its multisig time locks are 60 s (admin) and 120 s (upgrade), a test exception to the devnet floors of ADR 0028 (300 s and 3,600 s). The real pilot keeps 24 h and 7 days.
mutav_adapter_mock is not deployed on devnet.- The operator was rotated on 2026-10-12 through
propose_role / accept_role (the previous test key had been exposed). Transactions before that date are signed by the previous operator, A2gqm8f8…695k.
Documentation
- Protocol litepaper (HTML): Verifiable Guarantees on a Public Chain, a model for running guarantees on-chain and its Solana implementation. Draft for comment (v0.5).
- Brazil pilot paper (HTML): the first deployment: rental guarantees in Brazil, MUTAV as fiador, the pilot configuration and its risks. Draft for comment (v0.1).
- Comments on either paper: open an issue with the
litepaper label, until 2026-11-15.
- Protocol specification: accounts, instructions, invariants, caps, events.
- Implementation plan: task-by-task plan for the hackathon build.
- Architecture decisions: ADRs for the locked design choices.
- Deployments: what is deployed on each cluster (program ID, commit, executable hash, multisigs, parameters).
- Security reviews: internal review and audit reports, dated.
- Demo: storyboard, script and research for the Colosseum product demo video.
- : prior MUTAV work and what was built in the hackathon window.
Security
There are no keys in this repository: no keypairs, no secret keys, no private-key environment variables. The client composes transactions and never signs; the pilot app's connected wallet signs, and its server only relays signed transactions. The operator key is held in KMS by mutav-app, and admin authority is a Squads multisig. Program and deploy keypairs live outside the repo, and *.json keypair files are gitignored.
The program runs on devnet only and is pre-pilot. It has had internal reviews (dated here) and no independent audit; one comes before any outside capital. The demo reserve holds test tokens, and the reserve is not open to public investment. To report a vulnerability, see SECURITY.md.
License
- Code: MIT, Copyright (c) 2026 MUTAV. See LICENSE. Versions up to commit
9c883d5 were published under Apache-2.0 and remain available under those terms.
- Brand: the MUTAV name, logo (
app/public/brand/logo-mutav.svg) and brand assets are not licensed under MIT.
- Fonts: the app and the simulator use Geist, Inter and JetBrains Mono under the SIL Open Font License 1.1.
Acknowledgements
solana-foundation/vault (MIT) and onre-finance/onre-sol (MIT) informed MUTAV's design: the account and authority structure, the async request lifecycle, the mint-extension guard and the upgrade-readiness patterns. No code from either is included. See docs/provenance.md.
