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

# Technical Architecture

> Smart contract design, oracle integration and aggregator routing

FlowState consists of three layers: the C1 Pool smart contracts, the oracle integration layer and the aggregator routing interface. Together these deliver oracle-priced, single-sided liquidity that settles on-chain and integrates natively into existing DEX aggregator infrastructure.

The protocol and its predecessor liquidity infrastructure have been in active development for three years by an in-house engineering team. Smart contracts are deployed and live on KyberSwap. A first Hashlock audit is complete, with a round of improvements underway ahead of a second audit round, and adversarial simulation testing throughout.

<Frame caption="The three-layer architecture">
  <img src="https://mintcdn.com/jupiterrain/HHNctcJcMDRRAUNL/images/diagrams/three-layer-architecture.png?fit=max&auto=format&n=HHNctcJcMDRRAUNL&q=85&s=37ec2338c563be5ba1c30bd18fddb4ea" alt="Smart contracts, oracle integration layer, aggregator routing interface" width="1536" height="1024" data-path="images/diagrams/three-layer-architecture.png" />
</Frame>

## What the C1 Pool contract does

Each C1 Pool is a self-contained smart contract instance bound to a specific token. The contract handles four functions:

* **Deposits**. Accepts single-sided token deposits from holders, tracks balances per depositor.
* **Oracle resolution**. Reads the current oracle price at trade execution time, not at deposit time. Depositors always receive the live market rate.
* **Settlement**. Receives buyer payment in the base currency, transfers tokens at oracle price, distributes the fee.
* **Withdrawals**. Returns deposited tokens to the holder if untraded, or returns settlement proceeds if traded.

## How the fee distribution works

A separate distribution contract splits the 1% seller fee at settlement. No batching, no claiming, no end-of-period accounting:

<CardGroup cols={2}>
  <Card title="Aggregator" icon="route">
    **0.30%** of every C1 Pool trade
  </Card>

  <Card title="Token stakers" icon="coins">
    **0.30%** distributed at settlement
  </Card>

  <Card title="BD" icon="handshake">
    **0.30%** to partners bringing volume to C1 Pools
  </Card>

  <Card title="Treasury" icon="building-columns">
    **0.10%** funding protocol development and integrations
  </Card>
</CardGroup>

See [The Fee Model](/concepts/the-fee-model) for the rationale behind the split.

## Oracle integration

C1 Pools reference external oracle price feeds rather than deriving price from internal pool state. This is the architectural decision that eliminates price impact.

### Supported oracle providers

<CardGroup cols={2}>
  <Card title="Pyth Network" icon="bolt">
    High-frequency price feeds with sub-second updates. 400+ feeds across crypto, equities and FX. Used where latency is critical.
  </Card>

  <Card title="Chainlink" icon="link">
    Industry-standard oracle infrastructure with 1,000+ feeds across EVM chains. Established track record across GMX, Synthetix and other major oracle-dependent protocols.
  </Card>
</CardGroup>

<Note>
  Token coverage is bounded by oracle availability. A C1 Pool can be deployed for any token where Pyth or Chainlink provides a price feed. For tokens outside oracle coverage, no C1 Pool can be deployed and AMM routing remains the only option.
</Note>

## How aggregators discover and route to C1 Pools

C1 Pools expose a standardised interface that DEX aggregator smart order routers can query and execute against:

<Frame caption="Aggregator discovery and settlement sequence">
  <img src="https://mintcdn.com/jupiterrain/JesYOocHvG8rTwo-/images/diagrams/aggregator-discovery-sequence.png?fit=max&auto=format&n=JesYOocHvG8rTwo-&q=85&s=43e4b4b092752cbb2bdd27b615a4c3ea" alt="Sequence diagram: aggregator queries registry, requests quote, executes settlement, fee distributes" width="1692" height="929" data-path="images/diagrams/aggregator-discovery-sequence.png" />
</Frame>

<Steps>
  <Step title="Pool registers">
    C1 Pool contracts register with FlowState's liquidity registry on each supported chain.
  </Step>

  <Step title="Aggregator queries">
    DEX aggregators and other buy-side liquidity partners query the registry when scanning available liquidity for a given token pair.
  </Step>

  <Step title="Quote returned">
    The aggregator requests an execution quote from the C1 Pool, including the current oracle price and available depth.
  </Step>

  <Step title="Router selects">
    If the C1 quote is better than all AMM alternatives (which it mathematically will be for thin liquidity tokens), the aggregator routes the trade to the C1 Pool.
  </Step>

  <Step title="Atomic settlement">
    The C1 Pool settles the trade atomically in the same transaction. Fees distribute at settlement.
  </Step>
</Steps>

## EVM and Solana implementations

FlowState is an EVM-only brand. The current EVM implementation supports Ethereum mainnet, Arbitrum, Base and BNB Chain. Solidity smart contracts. Compatible with the full EVM aggregator ecosystem.

The same C1 Pool architecture is being deployed on Solana under a separate brand, **Oasis**, using a purpose-built Rust program optimised for Solana's account model. Pyth is the primary oracle on Solana given its native architecture. Oasis runs on its own roadmap and cap table and is documented separately.

## Security model

* **Audit**: First-round Hashlock smart contract audit complete. A round of improvements is underway ahead of a second audit round. Report available on [Audits & Security](/resources/audits-and-security).
* **Pen testing**: Adversarial simulation testing including oracle manipulation scenarios.
* **Development history**: Three years of continuous in-house development across C1 Pool architecture and predecessor liquidity infrastructure.
* **Upgrade mechanism**: Time-locked upgrade pattern with multi-sig control pre-TGE. Changes to core settlement logic require multi-sig approval and a time-lock delay. Governance transitions to FLOW token holders post-TGE.
* **Access control**: Administrative functions are role-separated. No single key controls fee rates and price feeds simultaneously.

See [Audits & Security](/resources/audits-and-security) for the full security model and audit references.