# Hyperliquid copy shadow position engine pattern

Use when extending a read-only Hyperliquid copy-research collector into a shadow-copy simulator.

## Core stance

- Remain strictly read-only: no live orders, no vault deposits, no wallet/API-wallet execution, no signing, no cron/systemd autostart.
- Runtime journals stay outside the repo under `/home/agent/.local/state/CryptoTradingBot/copy_research/`.
- The engine simulates follower exposure from observed leader wallet/vault position changes only.

## Runtime files

```text
copy_research/
  shadow/YYYY-MM-DD/position_decisions.jsonl
  shadow/YYYY-MM-DD/shadow_portfolio.jsonl
  reports/shadow_results/YYYY-MM-DD.json
```

## Models

Keep shadow models separate from generic copy models. Useful dataclasses:

- `ShadowLeaderPosition`
- `ShadowPositionDelta`
- `ShadowCopyDecision`
- `ShadowFollowerPosition`
- `ShadowPortfolioState`
- `ShadowRunSummary`

Every decision should carry read-only guard fields:

```text
read_only=true
live_orders=false
vault_deposits=false
wallet_execution=false
signing_enabled=false
```

## Delta logic

Recognize and journal all of:

- `new_position`
- `increase_position`
- `decrease_position`
- `close_position`
- `flip_position`
- `unchanged_position`

For v0, only `new_position` and `increase_position` should be candidates for shadow-copy. Other deltas are `ignored` and journaled; do not implement complex exit logic until explicitly requested.

## Gate integration

Reuse the existing `copy_pretrade_gate.py` rather than duplicating gate rules. Map granular block reasons into stable journal/report codes:

- `BLOCK_POSITION_TOO_YOUNG`
- `BLOCK_LEADER_TOO_FAR_IN_PROFIT`
- `BLOCK_ENTRY_DISTANCE_TOO_LARGE`
- `BLOCK_SPREAD_TOO_WIDE`
- `BLOCK_DEPTH_TOO_THIN`
- `BLOCK_LIQUIDATION_DISTANCE_TOO_SMALL`
- `BLOCK_FUNDING_EXTREME`
- `BLOCK_DUPLICATE_EXPOSURE`
- `BLOCK_READ_ONLY_GUARD_FAILED`

Allowed decisions must remain shadow-only and produce a simulated follower entry plus cost estimate, not an order intent.

## Cost model

Use the conservative follower formula already in the project:

```text
follower_net_pnl = gross_pnl - entry_fee - exit_fee - spread_cost - modeled_slippage - funding - delay_penalty
```

For entry simulation report at minimum:

- follower simulated entry price
- entry fee pct
- spread cost pct
- modeled slippage pct
- delay penalty pct
- estimated total entry cost pct
- estimated roundtrip cost pct

## CLI behavior

Provide a one-shot CLI only, e.g.:

```bash
PYTHONPATH=. python3 -m src.ctb_copy.run_shadow_once
```

If no wallet snapshots exist, exit successfully with `status=ok_no_wallet_snapshots`. If snapshots exist but no deltas are found, use `status=ok_no_position_deltas`. Do not treat either as a failure.

## Daily report

Add a `Shadow Portfolio v0` section with:

- decisions count
- allowed/blocked/ignored counts
- top block reasons
- symbols/leaders observed
- estimated total notional allowed
- read-only confirmation

If nothing happened, say: `Keine Shadow-Positionen erzeugt: keine aktivierten Wallets oder keine Positionsänderungen.`

## Verification

Before commit/push run:

```bash
PYTHONPATH=. pytest -q
PYTHONPATH=. python3 -m compileall -q src tests
git diff --check
grep -RInE "private_key|secret|api_key|agent_wallet|master_key|CTB_.*SECRET|HYPERLIQUID.*KEY" src/ctb_copy tests/test_ctb_copy_* || true
grep -RInE "create_order|market_open|set_leverage|vaultDeposit|exchange\.order|Account\.from_key|HL_AGENT_PRIVATE_KEY|HL_API_PRIVATE_KEY" src/ctb_copy || true
```