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

# How It Works

> Understand the 1tx architecture

## Overview

1tx enables **single-transaction, cross-asset deposits** through a router + registry architecture:

1. `SwapDepositRouter.buy()` is the user entry point.
2. `InstrumentRegistry` resolves the instrument ID into an adapter + market.
3. `SwapPoolRegistry` provides the default swap pool when the market asset differs from the router's configured stable token.
4. The router executes the swap through `poolManager.unlock(...)` and `SwapExecutor`.
5. The protocol adapter completes the final deposit through `LendingExecutor`.

## Router Flow

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Router as SwapDepositRouter
    participant Registry as InstrumentRegistry
    participant PoolRegistry as SwapPoolRegistry
    participant PoolManager as Uniswap V4 PoolManager
    participant Adapter as Protocol Adapter

    User->>Router: buy(instrumentId, amount, minDepositedAmount, fastTransfer, maxFee, referralFeeBps, referralWallet)
    Router->>Registry: getInstrument(instrumentId)
    Router->>PoolRegistry: getDefaultSwapPool(stable, marketCurrency)
    Router->>PoolManager: unlock(...) when swap is needed
    PoolManager-->>Router: swapped market currency
    Router->>Adapter: deposit(marketId, amountOut, recipient)
    Adapter-->>User: yield token
```

For withdrawals the same path runs in reverse through `sell()`: the router burns the user's yield token position, exits the lending market, and swaps back into the desired output token when needed.

Both `buy()` and `sell()` accept an optional **referral fee** on the stable amount (up to 5% / 500 bps). Set `referralFeeBps = 0` and `referralWallet = address(0)` to disable it.

## Cross-Chain Deposits

If the target instrument lives on another supported chain, `SwapDepositRouter.buy()` can route through the CCTP bridge path. The router transfers stable tokens to `CCTPBridge`, encodes `instrumentId`, recipient, and minimum output into the bridge payload, and emits `CCTPBridgeInitiated`.

That event starts the backend relay flow:

1. 1tx ingests the source-chain bridge event.
2. 1tx polls Circle IRIS for attestation.
3. 1tx submits `CCTPReceiver.redeem(...)` on the destination chain.
4. `CCTPReceiver` finalizes the bridge and executes `buyFor(...)`.

`sell()` remains local-chain only in the current implementation.

## Security Features

<CardGroup cols={2}>
  <Card title="Atomic Execution" icon="atom">
    All steps succeed or fail together - no partial state
  </Card>

  <Card title="Reentrancy Protection" icon="shield">
    All external calls protected with reentrancy guards
  </Card>

  <Card title="Slippage Control" icon="gauge">
    User can specify max slippage for swaps
  </Card>

  <Card title="Access Control" icon="lock">
    Only authorized adapters can register instruments
  </Card>
</CardGroup>

## Gas Optimization

1tx is optimized for minimal gas costs:

* **Packed Storage:** Instrument IDs encode chain ID + protocol data in 32 bytes
* **Single Transaction:** All operations in one tx (no approve + deposit sequence)
* **Minimal Lookups:** O(1) instrument and pool queries
* **Efficient Swaps:** Leverages Uniswap V4's efficient swap routing

<Tip>
  The router avoids multi-transaction user flows by combining swap and deposit logic into one call, while keeping swap routing and lending execution separated internally.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="lightbulb" href="/concepts/instrument-registry">
    Learn about universal instrument IDs
  </Card>

  <Card title="Atomic Router" icon="bolt" href="/concepts/atomic-router">
    Understand single-transaction execution
  </Card>

  <Card title="Integration Guide" icon="plug" href="/integration/overview">
    Start integrating 1tx
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore REST API
  </Card>
</CardGroup>