OmniFi Tranche docs

Introduction

OmniFi Tranche splits one yield-source pool into two layers and sells them as products with different risk appetites. Senior takes a fixed annual return first; Junior takes everything left over but absorbs losses first.

There are two versions. Single-chain version keeps the tranche structure and settlement entirely inside one chain. Multichain version extends the same tranche structure into a hub-spoke layout, so one product is sold on several chains. Whichever chain you join from, it is the same tranche at the same price; the ledger and settlement live on the hub chain.

The user surface is the same ERC-7540 async vault in both versions. The sections below on what a tranche is and on the ERC-7540 async vault apply to both.

What a tranche is

A tranche is one yield pool divided into layers of differing priority. This system uses two tranches, Senior and Junior.

Waterfall allocation

At every settlement the product total valuation (product NAV) is divided across the tranches. Senior NAV is min(Senior target, product NAV) — the target is principal plus accrued fixed APR. Junior NAV is everything else. Gains fill the Senior target and the whole remainder goes to Junior; losses eat into Junior NAV first.

In the implementation the Senior target accrues at each settlement as target += target × APR × elapsed ÷ 1 year. Interest is applied to the previous target again, so it compounds at the settlement interval. A deposit raises the target by the principal added; a redemption lowers it by the fraction of shares burned.

The waterfall in numbers

Say 1,000 is raised as Senior 800 · Junior 200, the Senior APR is 5%, and the product runs for a year. After a year the Senior target is 840. Whatever the product NAV turns out to be, the rule is the same —everything up to 840 is Senior's, everything above it is Junior's.

One return on one pool of assets splits into two completely different payoff curves. Senior is untouched down to −16% and only starts losing below that; Junior has to clear +4% to make anything, but past that it takes the entire gain. Junior is only 200 of the 1,000, so from Junior's side this is 5x leverage.

Share price

The share price of each tranche is tranche NAV ÷ shares outstanding for that tranche. A deposit gives you deposit ÷ price shares, and a redemption returns share count × price in assets. Deposit principal that has not settled yet is excluded from NAV even once it is deployed, so new money cannot move the price for existing holders.

Risk model

Tranching does not create return — it only re-divides one P&L into two claims ordered by priority. Senior is a threshold structure: capped at a fixed APR, losing nothing until the attachment point is crossed. Junior is leveraged by total ÷ Junior's share of it.

Three conclusions matter. ① Senior's risk is non-linear in α (the Senior share): raising α from 80% to 90% multiplies the loss probability by roughly 9. ② Even with no asset loss, if the yield source pays less than α·r the Junior buffer drains at a fixed rate. ③ α here is endogenous — deposits set it — so a Senior investor should watch the current tranche NAV ratio rather than the fixed APR.

ERC-7540 async vault

In both versions the user entry point is a TrancheVault following the ERC-7540 async vault standard. Deposits and redemptions do not fill immediately; they run in three steps, request → settle → claim.

1. Request — requestDeposit / requestRedeem. Assets or shares move into escrow and the request becomes Pending.
2. Settle — the operator fixes NAV and sets the price. The request becomes Claimable.
3. Claim — the user calls deposit/mint (receive shares) or withdraw/redeem (receive assets). Any time.

No price is needed at request time. The price is fixed at settlement, and claiming is a local operation that picks up the fixed value. That separation is what lets the multichain version absorb cross-chain round-trip latency.

The share token is an ERC-20 separate from the vault (ERC-7575), with ERC-1404 transfer restrictions, so only whitelisted addresses can hold or transfer it. The vault is only an entry point and has no mint authority; only the Manager can mint or burn shares.

Glossary

Structure and components

Every contract is deployed behind an ERC-1967 proxy and can be upgraded. Vault and share are separate (ERC-7575), so replacing the vault logic does not touch holder balances.

Settlement modes — SYNC / ASYNC

Settlement speed is decided at two layers. Adapters declare, separately for deposits and withdrawals, what their yield source actually supports (SYNC = fills immediately, ASYNC = request then wait). Valuation sets, through its deploy parameters (depositMode / redeemMode), the settlement behavior the product promises the user.

There is one constraint: Valuation cannot be faster than its adapters. You cannot promise the user an immediate settlement (SYNC) when the money cannot leave the yield source immediately (ASYNC). With several adapters, the slowest one sets the bound.

In an ASYNC flow, fixing the redemption price and starting the yield-source withdrawal both happen at the operator's settle. If the yield source is ASYNC, two settles are needed — the first fixes the price and starts the withdrawal, and the second, once the withdrawal is ready, makes the request claimable.

How deposits and redemptions work

Deposit

1. The user calls requestDeposit(assets, controller, owner) — after the 1404 whitelist check, assets move into Manager escrow and, in the same transaction, Valuation deploys them into the adapters. If targetWeights is set it splits by those weights; if not, the whole amount goes to the depositTarget adapter.
2. The operator calls settle(reqId) — the price is fixed at the NAV of that moment and the share count is set.
3. The user calls deposit/mint to claim the shares. There is also a keeperClaim path where a keeper claims on the user's behalf (shares always go to the controller).

Redemption

1. The user calls requestRedeem(shares, controller, owner) — the shares are locked in escrow (not burned).
2. Operator settle — fixes the price and runs the adapter withdrawal plan, splitting the withdrawal across adapters. The SYNC portion realizes immediately; the ASYNC portion issues tickets.
3. Once every ASYNC ticket is ready, a batch claim — the user calls withdraw/redeem to receive the assets. The escrowed shares are burned at that point.

Cancellation

User cancellation is not supported. In both versions, calling cancelDepositRequest / cancelRedeemRequest reverts with CancelNotSupported. Once accepted, a request can only be ended by settlement.

The functions are kept so the ERC-7540 surface matches, but they do nothing, so a front end should not show a cancel button. Reversing a request that has already crossed chains can desynchronize the two ledgers, so multichain blocked it first and single-chain was aligned to the same rule.

A request orphaned by a lost cross-chain message is cleared by the operator with adminClearRequest — from the ledger only (compensating the assets is a separate procedure).

How to use it

Users

1. Get whitelisted (the operator registers you on the WhitelistHook).
2. Approve the base asset (USDC) to the vault with approve.
3. Call requestDeposit on the Senior or the Junior vault.
4. After settle, claim the shares with deposit(assets, receiver). maxDeposit(controller) greater than 0 means there is something to claim.
5. Redemption is the same order — requestRedeem → wait for settle → redeem.

Operators

1. pendingRequests() or pendingDeposits()/pendingRedeems() return the pending requests.
2. isSettleable(reqId) filters them; then call settle or settleBatch.
3. Change weights with setTargetWeights; move funds between protocols with rebalance. Both of those, plus adapter management and drain, are owner-only; the operator account can only settle.

Demo: Single-chain products →

Functions

TrancheVault — user surface (ERC-7540/7575/4626)

Valuation — operator surface

Other

Events

It follows the standard surface events as they are, so it works with general-purpose indexers.

• ERC-7540 — DepositRequest / RedeemRequest, operator approval OperatorSet. No cancel event is emitted, since cancellation is unsupported. The standard event's requestId is always 0 and cannot distinguish requests — for a per-request join key use the Manager's DepositRequested(bytes32 requestId, …) and DepositsApproved/RedeemsApproved.
• ERC-4626 — on claim, Deposit / Withdraw.
• ERC-7575 — on the share side, VaultUpdate (vault replacement notice).
• ERC-20 / 1404 — share Transfer (including mint/burn); whitelist changes are hook-contract events.
• Operations — adapter registration, weight changes, rebalance, drain, pause and the other main operations each have a matching event.

Structure and components

ID scheme

productId — uint64

The top 32 bits are the product class prefix, the low 32 bits the sequence within that class. Always written in hex.

requestId — bytes32

requestId = productId (64 bits) | chainId (64 bits) | seq (128 bits)

Issued by the Manager. Cutting off the top 64 bits gives the full productId including its prefix; the next 64 bits are the EVM chainId of the requesting chain, and the low 128 bits are that Manager's local incrementing sequence. The (productId, chainId) prefix guarantees global uniqueness.

settlementId — uint256

The settlement round number. It increments by 1 on every successful settlement and is the join key for settlement-family events and records. A request that arrives while a settlement is collecting rolls over to the next round.

Tranche key — (chainId, vault)

The pallet identifies a tranche by the pair (chain ID, vault address). There is no separate tranche index field. For the same tranche type the share price is identical across chains; only the supply differs per vault.

Deposit flow

The principle is to centralize allocation decisions on the hub. Requested funds are sent to the hub in full, and each chain receives its own portion back and deploys it according to the plan the hub set.

Previously the requesting chain deployed its own portion first, which mixed funds that had not become shares yet into that chain's NAV and inflated that round's price by other people's money (fixed 2026-08-21). Now the requesting chain goes through the hub like every other chain to get its portion — one more bridge hop, but an accurate price.

1. Request (entry chain, user tx) — requestDeposit → whitelist check → Manager escrow → requestId issued. The requested amount, in full, is sent to the hub as a DEPOSIT_REQUEST (kind 1) message with the assets attached. (Each product has a minimum request amount; below it the call reverts with BelowMinRequest.)
2. Record and allocate (hub) — the Orchestrator receives it and routes it to Valuation. It writes the pallet ledger with record_investment_request, computes the allocation plan, deploys the hub's portion immediately, and propagates each spoke's portion as an asset-carrying ADAPTER_SUPPLY (kind 7). A deposit that arrives while a settlement is collecting is held by the Orchestrator and deployed only after that round's price is fixed.
3. Deploy (each spoke) — on receipt each chain deploys its portion into local yield sources. That includes the requesting chain.
4. Settle · claim — share issuance and price fixing happen in the settle cycle, and the user can claim any time after that.

Joining from the hub delivers message 1 directly inside the same transaction, with no bridge — the event structure is identical.

Redeem flow

Symmetrically with deposits, withdrawal starts as soon as the request is made. That absorbs an ASYNC yield source's lead time (request → ready → claim) into the gap between request and settlement. The start is immediate; the asset movement is batched at settlement.

1. Request (entry chain) — requestRedeem → shares are locked in escrow → the expected payout is computed at the last fixed price → the local portion's withdrawal starts immediately → reported to the hub as REDEEM_REQUEST (kind 2), including the amount started.
2. Delegate withdrawal (hub) — after writing the ledger, it sends ADAPTER_WITHDRAW (kind 8, flag=1) to every spoke except the requesting chain to start their portion's withdrawal. Each receiving chain computes its own localShareBps of the total expected payout. The hub's portion and any remainder start locally, with no message.
3. Realized amounts collected (at settlement) — each chain sends what it realized to the hub as assets attached to SETTLEMENT_RESPONSE (kind 4).
4. Payout (settlement fixed) — per-request payouts are set at the fixed price, and the per-chain payout allocation is sent down attached to SETTLEMENT_FINALIZE (kind 5). The receiving Manager credits it to the payout reserve (payoutReserve) and flips the requests to claimable.
5. Claim — the user calls withdraw/redeem to receive them. The escrowed shares are burned when the user claims.

settle cycle

The keeper calls the hub Valuation's tryUpdateNAV once per settle interval to start the cycle (if the interval has not elapsed it returns without doing anything). Redemption withdrawals have already started outside this cycle, at request time. settle covers price fixing, share distribution, redemption payouts, and deploying deposits that arrived and were held during collection.

1. Collection starts (hub) — snapshots the hub's own valuation and sends SETTLEMENT_COLLECT (kind 3) to every registered spoke. The work for this round is fixed to the pending queue as of that moment.
2. Response (each spoke) — aggregates its yield-source adapter valuations and replies with the chain NAV and a per-source breakdown (AdapterValuation) in SETTLEMENT_RESPONSE (kind 4). Assets realized from redemption withdrawals are attached here too.
3. Finalize (hub) — collect every chain's response → adjust out unsettled deposit principal → waterfall → compute the fixed price per tranche. It increments the round number first (0 is genesis; real settlements start at 1) and records the adapter breakdown, the tranche settlement and the per-request approvals to the pallet under that number.
4. Distribute (hub → each spoke) — sends the approval list and the fixed price down in SETTLEMENT_FINALIZE (kind 5), chunked if the list is large. The receiving Manager flips those requests to claimable.

Hub state becomes Claimable the moment the approval is recorded (optimistically). If spoke delivery fails, the state is not rolled back — the message is re-sent until it converges, and receive handling is idempotent.

CCCP messages

Every message payload is one CccpPayload struct passed through abi.encode. It decodes with the same ABI regardless of kind, and unused fields are 0 or empty. The second field is always uint64 productId, so any message can be identified by kind and product from a (uint8, uint64) decode alone.

struct CccpPayload {
    uint8   kind;          // 1~10
    uint64  productId;     // uint32 prefix | uint32 seq
    bytes32 requestId;     // 0 outside the request family
    uint256 settlementId;  // 0 outside the settlement family
    uint8   flag;          // kind 8 usage · kind 9 grant/revoke
    address account;       // investor · permission subject
    address vault;
    uint256 amount;
    uint256 aux;
    address[] addrs;
    uint256[] nums;
    bytes   data;          // nested struct arrays (kind 4·5 only, 2-stage encoding)
}

At both the send and the receive end, CccpSent / CccpReceived events record the full original message, so an indexer can trace every cross-chain leg from those two events alone. If the declared send amount differs from the amount actually received, that is the bridge fee gap, and the fee sponsor covers it.

Whitelist · rebalance · allocation propagation

Whitelist

The source of truth for investor eligibility is the hub's TranchePermissions (0x202). When an admin makes one grant_permission call, the pallet records it and calls the Orchestrator directly to send WHITELIST_SYNC (kind 9) to the target vault's chain. Once the receiving chain's WhitelistHook is updated, share transfers and the vault deposit gate open. Revoke takes the same path.

CCCP does not guarantee delivery order, so messages carry a propagation nonce. The receiver compares it against the latest nonce per (vault, target address) and discards stale messages — a revoke that arrives before its grant still ends in the right final state.

Rebalance

User ledgers and shares are untouched; only fund capital moves. Moving between chains goes ADAPTER_WITHDRAW (kind 8, flag=0) to the overweight chain → the withdrawn amount collects at the hub via REBALANCE_BRIDGE (kind 6) → redeployed to the underweight chain with ADAPTER_SUPPLY (kind 7).

Allocation weight propagation

Each spoke caches only its own weights (localShareBps and the local adapter split). To change them the operator calls pushAllocation (onlyOwner) on the hub, which propagates ALLOCATION_SYNC (kind 10), and a version counter (weightsVersion) detects staleness. Even if a spoke deployed at the old weights, the hub knows the gap between target and actual and corrects it at the next rebalance.

How to use it

Users

1. Pick an entry chain — hub (testbed) or spoke (Sepolia); it is the same product either way.
2. Get test assets (USDC) from the faucet, and get whitelisted.
3. Call requestDeposit on the vault — from there it is the same 7540 surface as single-chain.
4. Once a settlement round comes around (a few minutes when entering from a spoke), call deposit to claim the shares.
5. Redemption is the same — requestRedeem → wait for settlement → withdraw.

Operations

1. Create the product — register the Valuation address, the tranche layout (APR · priority · vault) and the chain and adapter weights with the pallet's create_product.
2. Grant eligibility — one grant_permission call both records the source of truth and propagates to every chain.
3. Settlement is triggered by the keeper on an interval. Watch progress through events and pallet queries.
4. Weight changes and rebalancing are set_multichain_adapters (replacing the pallet source of truth) followed by starting a rebalance.

Demo: Multichain products → — entry-chain selection, deposit and redeem, a cross-chain tracker, a faucet and an operations panel.

Functions

User surface

The same TrancheVault (ERC-7540/7575/4626) as single-chain — requestDeposit / requestRedeem / deposit / redeem/ view functions are all identical. The only difference is that cancellation is unsupported.

MultichainTrancheManager

ValuationDiamond

Pallet precompiles (hub)

Every product_id parameter is uint64 (converted 2026-08-18).

Events

Every external state-changing function emits an event, and an indexer can reconstruct the whole system state from events alone. The request lifecycle joins on requestId (standardized as the first indexed parameter); the settlement lifecycle joins on settlementId.

Wire chokepoints

Requests · claims

Deployment · withdrawal

Settle

Eligibility · allocation · operations

Full signatures and the per-action emission order are in docs/multichain/events.md in the repository (the source of truth handed to the indexer and node teams).

Current deployments

Four products are running at once. Two are single-chain and two are multichain.

A — multichain USDC

Hub testbed (49088) · spoke Sepolia (11155111), 60/40 allocation. This generation was cleanly redeployed with a SettleFacet that reflects settlementId numbering (0 is genesis; real settlements start at 1). The Orchestrator is reused as it is, since the CCCPClient interface did not change (deployed and activated 2026-08-28).

The full address book is in the multichain/deployments/ deployment records in the repository.

D — multichain basket

Hub testbed (49088) · spoke Robinhood testnet (46630), 60/40 allocation. The structure is the same hub-spoke pattern as A (the Orchestrator is reused); only the Robinhood spoke adapter is swapped for RobinhoodBasketAdapter so that at settlement only the net inflow/outflow difference is traded in one batch on Uniswap V3 (0.05% tier, full-range liquidity) into a mirror basket of the top 8 QQQ names (NVDA, AAPL, GOOGL, MSFT, MU, AMZN, AMD, TSLA) — deployed, pool seeded and registered with the pallet on 2026-08-31. The full address book is in the multichain/deployments/ deployment records in the repository.

B — single-chain JPYC

ETH Sepolia (11155111), base asset JPYC (18 decimals). Two yield-source adapters run in parallel at 50/50 — an in-house source that pays USDC rewards, and Morpho Blue. Deposit and redeem are both SYNC, so a request becomes claimable immediately.

C — single-chain institutional lending

Hub testbed (49088), base asset USDC. One institutional lending escrow adapter (APR 7%, Senior fixed 3%). Deposits are SYNC and redemptions ASYNC (FIFO, in the order loan repayments arrive). Investor eligibility is filtered by an ERC-3643 IdentityRegistry/Compliance pair rather than a WhitelistHook.

The full address book for the two single-chain products is in singlechain/deployments/.