Architecture overview

How a fund is built: an onchain Safe stack with tokenized shares, priced by onchain NAV, complemented by an offchain indexing and automation layer.

Funds use a hybrid architecture. Custody, permissions, share issuance, and valuation live onchain; indexing, APIs, user interfaces, and automation run offchain on top of that onchain state.

The onchain contract stack of a single fund (Onchain Investment Vehicle).

Legacy terminology: older materials may refer to a fund as an Onchain Investment Vehicle (OIV). It's the same underlying Funds infrastructure — the contracts repo is karpatkey/onchain-investment-vehicles.

Onchain components

Every fund is a stack of contracts deployed atomically by the KpkOivFactory. A single fund spans one or more chains and is made up of:

• Portfolio Safe — the fund's vault. It holds all portfolio assets. Its sole owner is the Empty contract (0xA470…4652, deployed at the same address on every chain), so no EOA or multisig can execute transactions on it directly. Every action must flow through the Roles Modifiers.
• Three Zodiac Roles Modifiers — the programmable permission layer in front of the Safes:

  • Exec Roles Modifier — the primary execution layer, enabled as a module on the Portfolio Safe and owned by the fund admin (a Security Council / governance Safe). It is the authoritative gatekeeper of Portfolio Safe execution.
  • Sub Roles Modifier — a nested layer (avatar = Portfolio Safe, target = Exec Roles Modifier) used to route automated/bot transactions through the exec layer. Owned by the Manager Safe.
  • Manager Roles Modifier — guards the Manager Safe's own actions (avatar & target = Manager Safe). Owned by the Manager Safe.
• Manager Safe — the operators' multisig. Fund managers sign here; it holds the OPERATOR role on the shares contract and is the fund's fee receiver.
• kpkShares contract — an ERC-20 token that is both the fund's shares and the onchain interface for subscriptions and redemptions. It is a UUPS proxy backed by an implementation deployed exclusively for that fund, so upgrades are isolated. The shares token lives on one chain (typically mainnet); on other chains a fund deploys only the Safe + modifier stack.
• NAV Calculator (one per chain) — computes the USD value of the Portfolio Safe's portfolio on that chain. It reads balances through balance adapters and prices them through price feeds. See Onchain Accounting.

The kpkShares contract does not compute NAV. NAV is calculated onchain by the NAV Calculator; the resulting share price is submitted by an operator when settling requests (see NAV).

Multichain layout

A fund's Portfolio Safe, Manager Safe, and Roles Modifiers share the same address on every chain — a deterministic CREATE2 property of the factory. The shares token is deployed on a single chain. Assets held across chains are valued by each chain's NAV Calculator and summed off-chain into one global NAV.

Offchain components

The offchain infrastructure complements the onchain system and supports data aggregation, user interfaces, and automated operations:

• Data indexer — tracks shares events and NAV values, indexes them, and denormalises the data into multiple formats consumed by the API and the web application.
• JSON API — exposes current and historical fund data (NAV, supply, positions, policies, user positions) for the web application and external integrations.
• Web application — lets users review performance and portfolio breakdowns, inspect approved policies, and create subscription and redemption requests through a simple interface.
• Automated agents — approve subscription and redemption requests without manual operator intervention, and help keep positions safe (for example, exiting compromised protocols during emergencies). They act through the Sub Roles Modifier, within the bounds set by onchain policies.

Where to go next

Fund deploymentCore concepts