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

# Architecture

> Tulip protocol components, execution paths, and trust boundaries.

Tulip v1 separates canonical on-chain markets, off-chain inference routing, and read-only market telemetry. No single service sits in every execution path.

<Info>
  Version 1 uses Hugging Face as its model registry and inference endpoint vendor. That adapter is the current data-plane implementation, not a permanent protocol restriction. Future versions may add vendor integrations while preserving existing v1 identities and markets.
</Info>

## System map

```text theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
Hugging Face repository + commit + task (v1)
                    │
                    ▼
           TulipModelRegistry
                    │
          ┌─────────┴─────────┐
          ▼                   ▼
  TulipModelCredit    TulipV4MarketFactory
                              │
                 ┌────────────┼────────────┐
                 ▼            ▼            ▼
          Uniswap v4   DynamicFeeHook   LP Locker
          PoolManager

Provider operator ──► ProviderOfferRegistry
                             │
User permit ───────► Tulip Gateway ───────► Hugging Face Endpoint
     │                       │
     └────────────► InferenceEscrow ◄──── signed usage receipt

PoolManager events ──► Tulip Indexer ──► charts and market telemetry
```

## On-chain control plane

The contracts establish:

* Deterministic model identity.
* One canonical credit and pool per model.
* Fixed credit supply.
* Permanently locked launch liquidity.
* Creator-scheduled native LP-fee changes within protocol bounds and a one-hour activation delay.
* Permissionless provider offers and delayed tariff versions.
* Model-bound credit permits and exact offer-bound settlement.

All swap balance changes occur in the canonical Uniswap v4 `PoolManager`.

## Gateway data plane

The Gateway handles actions that contracts cannot perform directly:

* Private endpoint credentials.
* Endpoint capability discovery and health checks.
* Prompt tokenization.
* Offer selection and pre-output failover.
* Maximum-charge reservations.
* OpenAI-compatible request forwarding.
* Usage metering and EIP-712 receipt signing.
* Batched receipt submission.

The Gateway cannot move arbitrary wallet funds. Settlement is limited to credits already deposited in a permit and to charges recomputed by the escrow from an effective on-chain tariff.

## Indexer telemetry plane

The indexer discovers markets from factory events and follows matching `PoolManager` swaps. It provides prices, TVL estimates, volume, trades, and OHLCV candles.

The indexer does not quote, route, approve, or execute swaps. A stale indexer can make charts unavailable but cannot block the AMM.

## Trust boundaries

| Boundary          | Enforced guarantees                                                                                        | Remaining trust                                                                                   |
| ----------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Contracts         | Identity, supply, pool binding, fee bounds, permits, tariff math, receipt replay protection, distributions | Governance keys and implementation risk; production contracts have not been independently audited |
| Uniswap v4        | Pool accounting, swaps, positions, events                                                                  | Robinhood Chain and deployed Uniswap contracts                                                    |
| Gateway           | Endpoint verification, routing, reservation, metering, receipt signing                                     | Correct gateway operation and signer security                                                     |
| Provider          | Endpoint availability and model execution                                                                  | Correct inference and truthful upstream usage                                                     |
| Hugging Face (v1) | Endpoint hosting and repository availability                                                               | Platform availability and provider account configuration                                          |
| Indexer           | Reorg-aware telemetry derived from events                                                                  | Database and RPC freshness                                                                        |

## Failure behavior

* A model market may launch and trade before any provider registers; inference remains unavailable until an eligible offer becomes active.
* A provider outage does not stop credit trading.
* Indexer downtime does not stop swaps or inference settlement.
* A Gateway outage stops new routed inference but not credit custody, permit closure, or AMM trading.
* A paused model blocks eligible inference while its ERC-20 and pool remain on-chain.
* Locked liquidity has no administrative withdrawal path.