# IPOR Fusion

> IPOR Fusion is an open-source on-chain asset management framework by IPOR Labs. Depositor capital sits in ERC-4626 Plasma Vaults. A vault curator (Atomist) configures which DeFi protocols the vault may use through Fuses, and an off-chain strategist (Alpha) executes allocations by calling the vault. Fusion runs on Ethereum, Arbitrum, Base and other EVM chains. Fusion is a separate product from IPOR Derivatives, IPOR Labs' interest-rate-swap protocol built on the IPOR Index; this file covers Fusion only. Documentation: https://docs.ipor.io. Application: https://app.ipor.io/fusion. Facts below are as of 2026-09-11; the linked sources are authoritative when they differ.

Every page on https://docs.ipor.io is available as plain Markdown by appending .md to its URL; the links below already point at the Markdown versions. For deployed addresses, ABIs and contract source use the code resources listed in this file, not the docs.

The docs site has a router page for agents, Fusion for agents (https://docs.ipor.io/build-on-fusion/fusion-for-agents.md): which interface to use for inspection (MCP), for creating vaults and building calls (Python SDK), for public data (API), and where addresses and ABIs live; read it first when arriving from docs.ipor.io.

Core vocabulary, used consistently across code, docs and this file:

- Plasma Vault: the ERC-4626 vault contract that holds depositor funds. Every interaction with an external protocol goes through the vault. Deposits and withdrawals use the ERC-4626 functions deposit, mint, withdraw and redeem, but each of them is access-controlled (see rules below). Vault shares use the underlying asset's decimals plus 2 (DECIMALS_OFFSET = 2 in PlasmaVaultLib.sol); do not assume a 1:1 share-to-asset scale.
- Fuse: a stateless adapter contract encoding one action on an external protocol (supply, withdraw, borrow, swap, claim). The Plasma Vault executes fuses via delegatecall, so the vault itself holds the resulting positions. Fuses are immutable: a deployed fuse cannot be upgraded. New strategies are composed from already-registered fuses; a new fuse is needed only for an action no registered fuse covers.
- Balance Fuse: a fuse that reports the value of the vault's position in one market, used for share price calculation.
- Market: a numeric ID that groups the fuses and the balance fuse for one protocol integration. The IDs are defined in the IporFusionMarkets library (contracts/libraries/IporFusionMarkets.sol) and mirrored in the SDK as ipor_fusion.IporFusionMarkets.
- Substrate: a per-market allowlist of assets, pools or parameters a fuse is permitted to touch. Substrates are bytes32 values with market-specific layouts: for Aave V3 the substrate is the asset address right-aligned in 32 bytes, other markets use typed layouts. The SDK decodes them in ipor_fusion.substrates; the layouts are documented in the fuse libraries of the contracts repository.
- Atomist: the vault curator. Configures fuses, substrates, fees, limits, price oracle and roles. Holds ATOMIST_ROLE.
- Alpha: the strategist address that rebalances the vault. Holds ALPHA_ROLE and calls PlasmaVault.execute.
- Access Manager: an OpenZeppelin AccessManager based contract (IporFusionAccessManager) that owns all role assignments and execution delays for a vault. Roles are numeric IDs defined in the Roles library (contracts/libraries/Roles.sol): OWNER_ROLE = 1, GUARDIAN_ROLE = 2, ATOMIST_ROLE = 100, ALPHA_ROLE = 200, FUSE_MANAGER_ROLE = 300, CLAIM_REWARDS_ROLE = 600, WHITELIST_ROLE = 800, UPDATE_MARKETS_BALANCES_ROLE = 1000, PRICE_ORACLE_MIDDLEWARE_MANAGER_ROLE = 1200, PUBLIC_ROLE = type(uint64).max. This is a subset; see the library for the full list.
- Withdraw Manager: contract every factory-created vault has (a vault cannot be initialized without one); it runs withdrawal requests, their release by the Alpha, and withdrawal fees.
- Rewards Claim Manager: contract that claims and holds protocol rewards before they are swapped or vested into the vault.
- Fee Manager: contract that accrues and distributes the vault's management and performance fees to the configured recipients.
- Context Manager: contract that lets an approved address execute vault operations on behalf of another via signature-based authentication.
- Price Oracle Middleware: the price source a vault uses to value its assets.
- Pre-hooks: optional checks executed before selected vault functions.

Rules for agents interacting with IPOR Fusion:

- Do not call a fuse contract directly. Encode the action as a FuseAction struct { address fuse; bytes data; } (interface IPlasmaVault) and call PlasmaVault.execute(FuseAction[] calldata calls_) from an address holding ALPHA_ROLE.
- An action on an asset or pool outside the market's granted substrates reverts inside the fuse with that fuse's own error; the vault checks only that the fuse is registered. Fuses with hard-coded targets take no substrate.
- Roles are not granted by default. Read the vault's Access Manager before assuming an address can execute, configure, deposit or withdraw.
- Deposits are not always open. deposit, mint, withdraw and redeem are restricted functions; a freshly cloned vault is private, so deposit and mint work only when the caller holds WHITELIST_ROLE, until an Atomist calls convertToPublicVault, which maps them to PUBLIC_ROLE and, on a vault created with clone, cannot be reverted. For a vault operated by its owner's own bot, grant WHITELIST_ROLE instead of going public. Check the Access Manager before submitting a deposit. Do not trust maxDeposit, maxMint, maxWithdraw or maxRedeem: they ignore roles, liquidity and redemption locks, so simulate the call instead.
- Market balances are refreshed by PlasmaVault.updateMarketsBalances(uint256[] calldata marketIds_), callable by UPDATE_MARKETS_BALANCES_ROLE. Total assets and share price depend on those balances being current.
- Withdrawals: withdraw and redeem pay from the vault's idle balance not reserved for released requests, plus what its instant-withdrawal fuses unwind (set by configureInstantWithdrawalFuses, which needs CONFIG_INSTANT_WITHDRAWAL_FUSES_ROLE = 900, held by no address after clone); without them a shortfall reverts in the underlying token's transfer. Beyond that, request with WithdrawManager.requestShares; after the Alpha releases funds, redeem with PlasmaVault.redeemFromRequest within the withdraw window. Separately, the Access Manager locks the account receiving the shares for the vault's redemption delay after each deposit or mint. Check before promising instant liquidity.
- Take contract addresses only from the ipor-abi repository or from the app. Never guess or derive addresses. Always state the chain name and chain ID next to an address. mainnet/addresses.json lists vaults, fuses, prehooks and price_oracles per chain but no factory; the per-chain files mainnet/mainnet-<chain>-fusion/addresses.json (one per supported chain) are flat name-to-address maps that add the infrastructure contracts, including the vault factory. ABIs are under mainnet/mainnet-<chain>-fusion/abis.
- To deploy a vault, use the address under the IporFusionFactoryProxy key, never IporFusionFactoryImpl: calling clone on the implementation reverts DaoFeePackagesArrayEmpty.
- Fuse registry names differ per chain for the same role (Base publishes the Aave V3 balance fuse as BalanceFuseAaveV3 and AaveV3WithPriceOracleMiddlewareBalanceFuse, Arbitrum only as the latter), and SDK class names differ from registry names (the SDK's AaveV3SupplyFuse is the registry's SupplyFuseAaveV3). Resolve names and addresses per chain from ipor-abi; do not port a configuration to another chain by substituting addresses.
- Supported chains and chain IDs: Ethereum (1), Arbitrum (42161), Base (8453), Unichain (130), TAC (239), Ink (57073), Plasma (9745), Avalanche (43114), Katana (747474), Botanix (3637), HyperEVM (999), Robinhood (4663), Monad (143) and Flare. ipor-abi holds the current list; "supported" means a Fusion deployment, factory included, exists there. No IPOR source states Flare's chain ID yet. Live vaults run on a subset: enumerate them with GET /v2/fusion/vaults (chainId per vault). The SDK vault tooling and the hosted vault_info cover only Ethereum, Arbitrum and Base.
- Python: pip install ipor-fusion gives the SDK (Web3Context, PlasmaVault and fuse classes such as AaveV3SupplyFuse). pipx install 'ipor-fusion[cli]' adds the fusion CLI (for example fusion vault info <address> --chain-id ethereum). The SDK README lists Ethereum, Arbitrum and Base as supported networks. MCP access is described in its own block below.

Notes for generating code with the Python SDK (ipor-fusion):

- Amounts are raw on-chain integers with no decimal scaling: 1 USDC (6 decimals) is 1_000_000. Use the types in ipor_fusion.types (Amount, Shares and others) instead of bare ints.
- Fuse methods are stateless encoders: each returns a FuseAction (fuse address plus calldata) and touches no chain. Nothing happens until PlasmaVault.execute([actions]) runs the batch atomically.
- Every wrapper method returns a Call: .call() runs a read-only eth_call on a view and returns a typed value (it raises on a write-only call); .send() signs locally and needs a private key in the Web3Context; .build_transaction() returns the unsigned transaction dict (needs the signer address and an RPC, no key, no value field); .calldata gives the raw bytes for an external signer.
- VaultSimulator runs an execute batch plus reads through eth_simulateV1 with no broadcast and no local node.
- FusionFactory deploys new vaults with clone; use the IporFusionFactoryProxy address of the chain (see the address rules above). Do not use clone_supervised (contract function cloneSupervised): only the factory's MAINTENANCE_MANAGER_ROLE may call it, and it gives the caller ADMIN_ROLE, full control of the new vault's Access Manager.
- A fresh clone grants its owner only OWNER_ROLE. Before configuring or executing, grant the operating roles through the vault's Access Manager with grant_role(role, account, 0): ATOMIST_ROLE first (it administers the others), then FUSE_MANAGER_ROLE for configuration and ALPHA_ROLE for execute.
- On each market, add_fuses, grant_market_substrates and add_balance_fuse must all happen before the first execute, in any order among themselves, and the vault's price oracle must price the underlying asset, or execute reverts.
- Common reverts on this path: 0x8745fbfd DaoFeePackagesArrayEmpty means clone was sent to the factory implementation, use the proxy; 0x9996b315 AddressEmptyCode means execute touched a market with no balance fuse; 0x068ca9d8 AccessManagedUnauthorized means the caller lacks the role the function requires, including deposit or mint on a private vault without WHITELIST_ROLE.

MCP (Model Context Protocol) servers for AI assistants such as Claude Code, Cursor or Windsurf. Two options, both named ipor-fusion:

- Hosted, no install: https://mcp.ipor.io/mcp is public, unauthenticated and read-only (HTTP transport), so any Fusion vault can be inspected without an RPC key. Claude Code: claude mcp add --transport http ipor-fusion https://mcp.ipor.io/mcp. Generic client config: {"mcpServers": {"ipor-fusion": {"type": "http", "url": "https://mcp.ipor.io/mcp"}}}. Tools: vaults_list, vault_info, vault_oracle_mapping, fusion_addresses_list, fusion_address_names, fusion_address_lookup, market_morpho_blue, market_meta_morpho. Start with vaults_list and vault_info. Read the fusion://invariants resource before writing code that deploys or configures a vault. Caveats: vaults_list takes no filter parameters and returns every vault in one JSON payload, large enough to exhaust an LLM context window; vault_info supports Ethereum (1), Arbitrum (42161) and Base (8453) only; the address-registry tools do not yet cover Monad, HyperEVM, Robinhood or Flare (fusion_address_lookup returns no match there instead of an error), so read ipor-abi directly for those.
- Local, from the SDK: pipx install 'ipor-fusion[mcp]' installs the fusion-mcp server (stdio transport) that exposes the CLI against your own RPC providers and local config. Client config: {"mcpServers": {"ipor-fusion": {"command": "fusion-mcp", "type": "stdio"}}}. Tools: server_info, config_show, config_set_provider, config_set_etherscan_key, vault_info, vault_role_accounts, vault_oracle_mapping, vault_list, vault_add, vault_remove, market_morpho_blue, market_meta_morpho. Configure providers and vaults first (fusion config or the config tools).
- Both servers serve the SDK guide as MCP resources fusion://glossary, fusion://architecture, fusion://invariants and fusion://quickstart, and the prompts quickstart, deploy_vault, analyze_vault, trace_oracle_pricing and explain_fuse (slash commands in clients that support MCP prompts).
- Agent skill: skills/ipor-deploy-vault/SKILL.md in the ipor-fusion.py repository teaches a coding agent the full clone, roles, market, access posture, deposit and execute walk, with the invariants and revert selectors, before it writes vault code. Its text is identical to the fusion://invariants and fusion://quickstart resources.

IPOR Fusion API at https://api.ipor.io (read-only vault and market statistics):

- No API key, no authentication, no query parameters: every input is encoded in the URL path. Responses are pre-rendered JSON files served from a CDN and regenerated on a schedule, so a file's data is as current as its last write; short history buckets (7d) are refreshed most often, the all bucket least often.
- Responses are gzip-encoded; send Accept-Encoding: gzip (curl --compressed).
- Most numbers are decimal strings, some fields are JSON floats or null; parse per field with a decimal library. Token amounts and TVL are decimal-scaled human units, not raw base units. Timestamps are ISO-8601 UTC.
- Enumerate vaults with GET /v2/fusion/vaults: per vault chainId, address, name, asset, netApy, grossApy, rewardsApy, totalAssets, tvl, publicDepositOpened (access posture) and lastReadBlockTimestamp (freshness). Markets: GET /v2/fusion/markets (chainId, protocol, marketId, supply/borrow APYs).
- Time series: GET /v2/fusion/vault-history/{chainId}/{vaultAddress}-{period} and GET /v2/fusion/market-history/{chainId}/{protocol}/{substrate}-{period}. Addresses in these paths must be lowercase; a checksummed address returns 404.

Creating a vault with an AI agent (Fusion Vault Launchpad, https://github.com/IPOR-Labs/fusion-vault-launchpad):

- Clone the repository and follow its AGENTS.md instead of assembling a deployment by hand. One JSON strategy file describes the vault (chain, underlying, fuses, substrates, callback handlers, price feeds, fees, withdrawals, roles, whitelist); the pipeline turns it into a configured vault in 17 idempotent steps and verifies the result from the vault's own contracts.
- A dry-run needs no key. A fork rehearsal on a local anvil fork uses anvil's public test key and then uses the vault: deposit, every declared fuse executed, accounting checked, withdrawal paid. A live deployment needs the human's own funded key in a local .env file.
- Never ask a human for a private key in a conversation. Never broadcast to a live chain without a clean fork rehearsal, a clean plan/run diff, the three sign-offs in the strategy file (roles reviewed, hardening and front-end listing acknowledged) and an explicit human "yes" for that exact file in that session.
- Supported chains: Ethereum (1) and Base (8453). Two worked examples ship: a USDC vault on Aave V3 and a leveraged wstETH/USDC loop on Morpho Blue, both on Base.

## Concepts

- [Fusion introduction](https://docs.ipor.io/build-on-fusion/introduction.md): what Fusion is, the on-chain/off-chain split and who the participants are
- [Architecture overview](https://docs.ipor.io/build-on-fusion/architecture-overview/general.md): vaults, fuses, Atomists, Alphas and the list of supported chains
- [What is a Fusion vault](https://docs.ipor.io/build-on-fusion/architecture-overview/what-is-a-fusion-vault.md): Plasma Vault standards, redemption delay, rewards, fees, configurable versus immutable settings
- [What is a Fuse](https://docs.ipor.io/build-on-fusion/architecture-overview/what-is-a-fuse.md): fuse adapter model
- [What is an Atomist](https://docs.ipor.io/build-on-fusion/architecture-overview/what-is-an-atomist.md): curator responsibilities
- [What is an Alpha](https://docs.ipor.io/build-on-fusion/architecture-overview/what-is-an-alpha.md): strategist responsibilities

## Developer guide

- [Fusion for agents](https://docs.ipor.io/build-on-fusion/fusion-for-agents.md): start-here router for AI agents, choosing between the MCP server, the Python SDK, the API and the deployment registry, with the vault-creation call and the rules for agents
- [Quick start guide](https://docs.ipor.io/build-on-fusion/developer-guide/quick-start-guide.md): first steps for integrators
- [Smart contracts](https://docs.ipor.io/build-on-fusion/developer-guide/smart-contracts.md): contract overview
- [Open-source repository](https://docs.ipor.io/build-on-fusion/developer-guide/open-source-repository.md): how the ipor-fusion repository is organised
- [Developing a fuse](https://docs.ipor.io/build-on-fusion/developer-guide/developing-a-fuse.md): how to write and register a new fuse
- [Balance fuses](https://docs.ipor.io/build-on-fusion/developer-guide/balance-fuses.md): position valuation per market
- [Share price calculation rules](https://docs.ipor.io/build-on-fusion/developer-guide/general-share-price-calculation-rules.md): how total assets and share price are computed
- [Accounting and PPS protection](https://docs.ipor.io/build-on-fusion/developer-guide/accounting-and-pps-protection.md): cached balances, explicit reporting, manipulation resistance
- [Price Oracle Middleware](https://docs.ipor.io/build-on-fusion/developer-guide/price-oracle-middleware.md): price feeds used by vaults
- [Configuring pre-hooks](https://docs.ipor.io/build-on-fusion/developer-guide/configuring-pre-hooks.md): pre-execution checks
- [API](https://docs.ipor.io/build-on-fusion/developer-guide/api.md): the read-only JSON API for vault and market history, endpoints, conventions and the bucket merge rule
- [Security and audits](https://docs.ipor.io/build-on-fusion/developer-guide/security-and-audits.md): audit reports and security process

## Creating a vault with an AI agent

- [Fusion Vault Launchpad on GitHub](https://github.com/IPOR-Labs/fusion-vault-launchpad): toolkit that deploys, verifies and rehearses a Plasma Vault from one JSON strategy file, driven by an AI agent with a human in the loop
- [AGENTS.md](https://raw.githubusercontent.com/IPOR-Labs/fusion-vault-launchpad/main/AGENTS.md): operating guide for agents, rules, autonomy boundary, private-key handling and the lifecycle commands; read first
- [Using the repository with your agent](https://raw.githubusercontent.com/IPOR-Labs/fusion-vault-launchpad/main/docs/09-using-with-your-agent.md): how each agent tool finds the instructions, and a starter prompt
- [The strategy file](https://raw.githubusercontent.com/IPOR-Labs/fusion-vault-launchpad/main/docs/03-strategy-json.md): field reference for the JSON strategy and the chain contexts
- [Deploying](https://raw.githubusercontent.com/IPOR-Labs/fusion-vault-launchpad/main/docs/04-deploy.md): dry-run, fork rehearsal with the rehearsal stage, live broadcast, verification and recovery
- [Hardening](https://raw.githubusercontent.com/IPOR-Labs/fusion-vault-launchpad/main/docs/10-hardening.md): what comes after a verified vault before it takes outside money, and why listing on the app needs the IPOR Labs team

## Operating a vault

- [Vault configuration step by step](https://docs.ipor.io/build-on-fusion/atomists/vault-configuration-step-by-step.md): full Atomist setup checklist
- [Access management](https://docs.ipor.io/build-on-fusion/atomists/vault-configuration-step-by-step/access-management.md): role hierarchy, role IDs, technical roles that must stay at zero delay
- [Timelocks and execution delays](https://docs.ipor.io/build-on-fusion/atomists/vault-configuration-step-by-step/timelocks-and-execution-delays.md): execution delays, grant delays, floors, Guardian veto scope
- [Substrates](https://docs.ipor.io/build-on-fusion/atomists/vault-configuration-step-by-step/substrates.md): per-market allowlists
- [Curating a Fusion vault](https://docs.ipor.io/build-on-fusion/atomists/curating-a-fusion-vault.md): ongoing vault management topics
- [Managing redemption delays](https://docs.ipor.io/build-on-fusion/atomists/curating-a-fusion-vault/managing-redemption-delays.md): Withdraw Manager configuration
- [Deposit caps](https://docs.ipor.io/build-on-fusion/atomists/curating-a-fusion-vault/deposit-caps.md): limiting vault size
- [Public vault listing](https://docs.ipor.io/build-on-fusion/atomists/curating-a-fusion-vault/public-vault-listing.md): requirements for listing a vault in the app
- [Running an Alpha](https://docs.ipor.io/build-on-fusion/alpha/running-an-alpha.md): how strategists execute rebalances
- [Best practices for Alphas](https://docs.ipor.io/build-on-fusion/alpha/running-an-alpha/best-practices-for-alphas.md): operating guide for strategy executors
- [Vault fees](https://docs.ipor.io/fusion-for-depositors/user-guide/vault-fees.md): management and performance fees

## Code, SDKs and addresses

- [ipor-fusion on GitHub](https://github.com/IPOR-Labs/ipor-fusion): Solidity source of Plasma Vault, fuses, managers and libraries
- [Roles.sol](https://github.com/IPOR-Labs/ipor-fusion/blob/main/contracts/libraries/Roles.sol): the complete list of role IDs
- [IporFusionMarkets.sol](https://github.com/IPOR-Labs/ipor-fusion/blob/main/contracts/libraries/IporFusionMarkets.sol): the complete list of market IDs
- [IPlasmaVault.sol](https://github.com/IPOR-Labs/ipor-fusion/blob/main/contracts/interfaces/IPlasmaVault.sol): Plasma Vault interface including the FuseAction struct
- [ipor-abi on GitHub](https://github.com/IPOR-Labs/ipor-abi): ABIs and deployed addresses for every chain, including the full fuse list
- [addresses.json](https://github.com/IPOR-Labs/ipor-abi/blob/main/mainnet/addresses.json): mainnet vaults, fuses, prehooks and price oracles in one file, keyed by chain
- [Base deployment addresses](https://github.com/IPOR-Labs/ipor-abi/blob/main/mainnet/mainnet-base-fusion/addresses.json): per-chain flat address map including the FusionFactory; the same file exists as mainnet-<chain>-fusion/addresses.json for every supported chain
- [ipor-fusion.py on GitHub](https://github.com/IPOR-Labs/ipor-fusion.py): official Python SDK, CLI and MCP server for Plasma Vaults
- [ipor-fusion on PyPI](https://pypi.org/project/ipor-fusion/): the SDK package, with cli and mcp extras
- [ipor-deploy-vault agent skill](https://github.com/IPOR-Labs/ipor-fusion.py/blob/main/skills/ipor-deploy-vault/SKILL.md): step-by-step vault deployment guide for coding agents, with invariants and revert selectors
- [SDK documentation](https://docs.ipor.io/build-on-fusion/alpha/sdk.md): SDK usage for Alphas
- [typescript-examples on GitHub](https://github.com/IPOR-Labs/typescript-examples): TypeScript examples of reading and using Plasma Vaults, with ABIs and helper libraries
- [IPOR Fusion app](https://app.ipor.io/fusion): live vault list, addresses, positions and performance

## Optional

- [Glossary of terms](https://docs.ipor.io/resources/resources/glossary-of-terms.md): definitions used across the docs
- [Cross-chain vault integration, technical overview](https://docs.ipor.io/build-on-fusion/developer-guide/cross-chain-vault-integration-technical-overview.md): how vaults hold positions on other chains
- [Fusion for depositors](https://docs.ipor.io/fusion-for-depositors/introduction.md): end-user explanations of depositing, withdrawing, fees and risks
- [Risks for depositors](https://docs.ipor.io/fusion-for-depositors/user-guide/risks.md): risk disclosures
- [Fusion for institutions](https://docs.ipor.io/fusion-for-institutions/executive-summary-the-prime-brokerage-protocol-of-defi.md): institutional overview
- [DeepWiki for ipor-fusion](https://deepwiki.com/IPOR-Labs/ipor-fusion): auto-generated code walkthrough, secondary and not authoritative
- [DeepWiki for ipor-fusion.py](https://deepwiki.com/IPOR-Labs/ipor-fusion.py): auto-generated overview of the Python SDK components, secondary and not authoritative
- [Fusion Vault Launchpad llms.txt](https://raw.githubusercontent.com/IPOR-Labs/fusion-vault-launchpad/main/llms.txt): the toolkit's own index of its manual, examples and reference files
- [Full documentation index](https://docs.ipor.io/llms.txt): every docs page with its Markdown URL, grouped by section, including IPOR derivatives