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

# System flows and trust boundaries

> Trace Tayho requests, signing, indexing, automation, funding, and realtime across their trust boundaries.

# System flows and trust boundaries

## Environment boundary

Testnet and production are separate Railway environments with independent PostgreSQL, Redis,
domains, deployment identity, API credentials, keyrings, and signer pools. No runtime service may
reference data or secrets from the other environment.

```mermaid theme={null}
flowchart LR
  U[Wallet application] --> CF[Cloudflare frontend and edge]
  CF --> API[tayho-api]
  API --> IDX[tayho-indexer]
  API --> ENG[tayho-engine]
  API --> RPC[Read RPC pool]
  ENG --> PG[(Coordination PostgreSQL)]
  ENG --> REDIS[(Redis / BullMQ)]
  REDIS --> REL[tayho-relayer]
  REL --> CHAIN[HyperEVM contracts]
  CHAIN --> IDX
  IDX --> IDB[(Ponder database)]
  IDX --> REDIS
```

The browser signs typed data. The relayer—not the browser or API—signs and broadcasts the final EVM
transaction. Contract checks remain the final authorization boundary.

## Public read

```mermaid theme={null}
sequenceDiagram
  participant C as Client / SDK
  participant A as API
  participant I as Indexer
  participant R as RPC pool
  C->>A: Authenticated GET or unsigned calculation
  alt Indexed history/projection
    A->>I: Bounded private request
    I-->>A: Data + checkpoint
  else Live quote/risk/simulation
    A->>R: Block-pinned eth_call set
    R-->>A: Unsigned result
  end
  A-->>C: JSON + source + request ID
```

The API does not query keeper databases for on-chain history. Live reads never hold or use a signer.

## Relayed immediate action

```mermaid theme={null}
sequenceDiagram
  participant W as Wallet / SDK
  participant A as API
  participant E as Engine
  participant P as PostgreSQL
  participant Q as BullMQ
  participant R as Relayer
  participant C as Contracts
  participant I as Indexer
  W->>A: Signed EIP-712 action + idempotency key
  A->>E: Validated envelope + authenticated project policy
  E->>P: Immutable action, event, job, outbox
  P-->>Q: Stable outbox delivery
  Q->>R: Reference-only job
  R->>C: Revalidate, simulate, sign, broadcast
  C-->>R: Receipt
  R->>P: Confirmed lifecycle
  C-->>I: Canonical logs
  I-->>A: Transaction correlation
  A->>E: Mark indexed
  E-->>W: Receipt-authorized terminal status
```

The database commit precedes queue delivery. Queue loss is recoverable from the outbox. A repeated
signed envelope and idempotency key converges on the same durable action.

## Automatic intent

Limit, stop-loss, and take-profit orders are signed intents. The engine validates and stores the
encrypted terms, maintains trigger indexes and reservations, then emits only a reference job when
conditions are satisfied. The relayer decrypts at execution time, rechecks the live state, simulates,
and broadcasts. OCO and cancellation races resolve through durable lifecycle transitions and
on-chain execution.

The engine cannot broadcast. The relayer cannot accept or rewrite user intent terms. Database grants
and row-level policies enforce this split.

## Funding and oracle maintenance

```mermaid theme={null}
flowchart LR
  H[External outcome/order-book sources] --> MD[tayho-market-data]
  MD --> FO[tayho-oracle]
  MD --> AT[tayho-attester]
  FO -->|funding attestations only| C[Contracts]
  AT -->|depth/resolution attestations only| C
  AU[tayho-automation] -->|permissionless maintenance| C
  C --> IX[tayho-indexer]
```

The funding-oracle role and depth/resolution-attester role use distinct sources, credentials,
signers, and contract allowlists. Automation advances maintenance only after required observations
exist; it does not manufacture attestations.

## Indexing and reorgs

Ponder is the single log-scanning owner:

```mermaid theme={null}
flowchart LR
  RPC[Independent indexer RPC origins] -->|eth_getLogs via Ponder| P[Ponder writer x1]
  P --> DB[(Deployment schema)]
  DB --> V[Stable views schema]
  V --> API[tayho-api]
  V --> AUD[tayho-auditor]
  P -->|canonical events| S[Realtime stream]
```

Ponder applies handlers in EVM order and rolls projection state back on a reorg. There is exactly
one writer for a deployment schema. The auditor reads the indexer projection plus direct bounded
quorum state; it never independently scans log ranges. A delayed indexer can delay `indexed`
terminal correlation without invalidating the engine's receipt-authorized `confirmed` state.

## Realtime

The indexer event pump writes canonical public lifecycle events into the shared bounded stream.
Every API replica uses one stream reader and fans out locally. A new subscription captures a stream
boundary, loads an authoritative snapshot, then releases buffered events. Reconnects replay after a
per-channel cursor; a gap forces `resync_required` and a new snapshot.

Redis Streams provides replay and cross-replica delivery, not authority. REST/indexer/engine
snapshots remain correct after stream loss.

## Observability path

Services emit structured logs, traces, and Prometheus metrics to the private observability service.
`x-request-id` and W3C trace context cross API, upstream, job, transaction, and receipt boundaries.
Health endpoints intentionally expose no resolved signer, credential, or upstream error detail.