> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kimia.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How six Anchor programs compose into one fixed-income stack.

Kimia is not a monolith. Every responsibility, matching engine, hedging, tokenization,
AMM, stablecoin, is a separate Anchor program, and the programs talk to each other
via CPI. This makes each piece usable in isolation.

## Program map

<CardGroup cols={2}>
  <Card title="kimia-perp" icon="chart-line" href="/programs/kimia-perp">
    Matching engine, orderbook, funding, liquidation, spot pool.
  </Card>

  <Card title="delta-vault" icon="shield" href="/programs/delta-vault">
    Holds USDC, opens/maintains a SOL-PERP short, mints vault shares.
  </Card>

  <Card title="split-engine" icon="scissors" href="/programs/split-engine">
    Wraps vault shares into `PT` + `YT` with MasterChef-style yield accounting.
  </Card>

  <Card title="yield-amm" icon="arrow-right-arrow-left" href="/programs/yield-amm">
    Yield-space AMM for PT ↔ underlying, with prices that decay into par at maturity.
  </Card>

  <Card title="intent-router" icon="route" href="/programs/intent-router">
    Session state machine that verifies a multi-step fixed-rate lock succeeded.
  </Card>

  <Card title="kusd-mint" icon="coin" href="/programs/kusd-mint">
    Stablecoin with multi-reserve backing and staking-based yield distribution.
  </Card>
</CardGroup>

## Layered view

<img
  src="https://mintcdn.com/kimia/8_9nIplLL0qvcyWo/images/kimia-layered-architecture.png?fit=max&auto=format&n=8_9nIplLL0qvcyWo&q=85&s=a26717fe07cb16e4cee3e6a2ca93a4ff"
  alt="Architecture diagram: frontend and Next.js, intent router with session state machine, protocol layer with split-engine, yield-amm, and kusd-mint, delta vault, Kimia perp, and Pyth Hermes pull oracles for price feeds."
  style={{
maxWidth: '100%',
height: 'auto',
display: 'block',
margin: '24px auto',
borderRadius: '1rem',
}}
  width="976"
  height="701"
  data-path="images/kimia-layered-architecture.png"
/>

## CPI graph

Arrows mean "A invokes B via CPI" between Kimia's own programs. External
programs can CPI in the same way, but note that Kimia does not publish its
program crates to crates.io — consumers add them as `path` or `git`
dependencies in their own `Cargo.toml` with `features = ["cpi"]`.

<img
  src="https://mintcdn.com/kimia/eZh9Dx07_tQazD2y/images/architecture-cpi-graph.png?fit=max&auto=format&n=eZh9Dx07_tQazD2y&q=85&s=2a690494630d388cf9b310aed20b392f"
  alt="Diagram: user opens a multi-tx session with intent-router; the router verifies by reading account state; delta-vault CPIs into kimia-perp for deposit_collateral, spot_swap, place_order, and settle_funding; split-engine reads vault share price from kimia-perp; yield-amm uses kimia-math and vault shares."
  style={{
maxWidth: '100%',
height: 'auto',
display: 'block',
margin: '24px auto',
borderRadius: '1rem',
}}
  width="1101"
  height="426"
  data-path="images/architecture-cpi-graph.png"
/>

## The fixed-rate lock, three transactions

The canonical user flow uses all five programs to turn USDC into a guaranteed fixed rate:

<Steps>
  <Step title="TX1, Deposit into delta-vault">
    User calls `delta-vault::deposit(amount, open_perp=true)`.
    The vault splits the deposit 50/50, swaps one half into wSOL via `spot_swap`,
    and opens a matching SOL-PERP short via `place_order`.
    The user receives **vault shares**.
  </Step>

  <Step title="TX2, Split into PT + YT">
    User calls `split-engine::deposit(vault_shares)`.
    The engine escrows the vault shares and mints PT (1:1) and YT (1:1) to the user.
  </Step>

  <Step title="TX3, Swap YT for underlying on yield-amm">
    User calls `yield-amm::swap(YT → underlying)`.
    YT trades at a discount, the difference between what you paid and what you
    got back is the prepaid yield.
  </Step>

  <Step title="record_step3, Verify achieved rate">
    The intent-router recomputes the achieved APY from the swap receipts and
    reverts if it's below the user's `target_rate`. This is what makes it a
    "fixed-rate intent" instead of a hopeful multi-step script.
  </Step>
</Steps>

## Design principles

<AccordionGroup>
  <Accordion title="One program, one responsibility">
    Matching ≠ hedging ≠ tokenizing. Each program's account model is independently
    auditable, and integrations only need to grok the parts they use.
  </Accordion>

  <Accordion title="Permissionless cranks">
    `update_funding_rate`, `liquidate`, `update_rewards`, and `rebalance` can be
    called by anyone. The protocol pays the liquidator and skims yield for the
    insurance fund, incentives align, no whitelist.
  </Accordion>

  <Accordion title="Reserved margin up-front">
    Open orders lock collateral at placement. You can't over-leverage by spamming
    the orderbook, a position and a resting order compete for the same free
    collateral.
  </Accordion>

  <Accordion title="Round-against-trader everywhere">
    The shared `kimia-math` and `perps-math` crates always round down on the
    user's side. No "\$0.00000001 of free money" arbitrage.
  </Accordion>
</AccordionGroup>
