Cerbero-Bite/docs/12-mcp-deribit-changes.md

12 — Modifiche da apportare a mcp-deribit

Premessa

Cerbero Bite, a partire dalla Fase 3, opera in modo completamente autonomo: nessuna conferma interattiva da parte di Adriano nel primo periodo, niente bottoni Telegram, niente coda di approvazione manuale. Quando il rule engine valuta che le condizioni di entrata e di uscita sono soddisfatte, l'engine deve poter inviare l'ordine senza intermediazione umana. Il primo periodo di esercizio sarà condotto su ambiente testnet Deribit, in modo da raccogliere dati di slippage e fill reali senza esporre capitale.

Per realizzare questo flusso sono necessarie due modifiche al servizio mcp-deribit ospitato in CerberoSuite/Cerbero/services/mcp-deribit. Entrambe le modifiche sono additive e non rompono i tool esistenti.

Lo stato corrente del servizio è il seguente:

• place_order esiste, ma è limitato a un singolo strumento per invocazione (PlaceOrderReq.instrument_name); non è atomico per uno spread a due gambe.
• client.py espone l'attributo testnet, letto dal file di credenziali (secrets/deribit.json, campo testnet). Il tool is_testnet riporta correttamente lo stato. Non esiste oggi un modo di sovrascrivere quella scelta a livello di environment del container.

Modifica 1 — Nuovo tool place_combo_order

Obiettivo

Inviare a Deribit un singolo ordine combo a due o più gambe (legs) in modo atomico, evitando il rischio di leg risk tipico delle credit spread (la prima gamba si riempie e la seconda no, oppure si riempie a un prezzo che invalida il rapporto credito/larghezza).

Comportamento attesto

L'endpoint riceve la lista di legs, costruisce o riusa lo strumento combo corrispondente sul lato Deribit (API public/create_combo), quindi invia l'ordine di acquisto netto sul combo (private/buy con tipo limit o market). Il prezzo limite è espresso come prezzo netto del combo (in ETH per le opzioni inverse Deribit), cioè la somma algebrica firmata dei mid-price delle gambe.

L'ordine è soggetto agli stessi guard rail di place_order: verifica core capability, enforce_single_notional, enforce_aggregate, enforce_leverage. Per le opzioni il notional è calcolato come width × n_contracts × spot_index (perdita massima del combo).

Schema della richiesta

class PlaceComboOrderReq(BaseModel):
    legs: list[ComboLegReq]               # 2..4 gambe
    side: Literal["buy", "sell"]          # "sell" = incassa credito
    amount: float                         # numero di contratti combo
    type: Literal["limit", "market"] = "limit"
    price: float | None = None            # prezzo netto in ETH; richiesto se type=limit
    label: str | None = None              # propagato a Deribit per riconciliazione
    time_in_force: Literal["good_til_cancelled", "good_til_day", "fill_or_kill", "immediate_or_cancel"] = "good_til_cancelled"
    post_only: bool = False
    reduce_only: bool = False             # vero per combo di chiusura

class ComboLegReq(BaseModel):
    instrument_name: str                  # ETH-15MAY26-2475-P
    direction: Literal["buy", "sell"]     # direzione della singola gamba
    ratio: int = 1                        # multiplo della size combo (Deribit usa direction/ratio)

Vincoli di validazione:

• len(legs) compreso fra 2 e 4 (esclusi naked e ratio sbilanciati).
• Tutte le gambe hanno la stessa scadenza (expiry). Il payload deve rifiutare combo a scadenze miste.
• Se type == "limit", price è obbligatorio.
• direction di ciascuna gamba e side del combo sono coerenti con la convenzione Deribit (vedi docs Deribit public/create_combo).

Schema della risposta

class PlaceComboOrderResp(BaseModel):
    combo_id: str                         # ETH-15MAY26-2475P_2350P
    order_id: str                         # ID dell'ordine sul combo
    state: str                            # open, filled, rejected, ecc.
    average_price: float | None           # in ETH
    filled_amount: float
    legs: list[ComboLegFill]              # per gamba: instrument, direction, fill price, fees
    raw: dict                             # response Deribit completa per audit

Endpoint

@app.post("/tools/place_combo_order", tags=["writes"])
async def t_place_combo_order(
    body: PlaceComboOrderReq,
    principal: Principal = Depends(require_principal),
):
    _check(principal, core=True)
    return await client.place_combo_order(...)

Estensioni del client (mcp_deribit/client.py)

Aggiungere un metodo place_combo_order che incapsula due chiamate Deribit:

1. public/create_combo con la lista delle gambe; ritorna combo_id (Deribit gestisce idempotenza per pair identico, perciò chiamate ripetute con gli stessi parametri restituiscono lo stesso id).
2. private/buy o private/sell (a seconda di side) sul combo appena creato, con amount, price, type, time_in_force, post_only, reduce_only, label.

In aggiunta: cancel_combo_order(order_id) che oggi può semplicemente delegare a cancel_order (i combo sono cancellabili come ordini normali); è opportuno tracciarlo come metodo distinto per rendere il log dell'audit più leggibile.

Tag MCP

Aggiungere alla lista tools di mount_mcp_endpoint la voce place_combo_order con descrizione "Invia un combo order multi-leg atomico (Bull Put, Bear Call, Iron Condor)".

Test

• Mock del client che simula create_combo + buy e verifica che il body propagato a Deribit rispetti la convenzione direction/ratio.
• Test 403 quando il principal non ha capability core.
• Test di rifiuto per legs a scadenze miste, len(legs) < 2, len(legs) > 4, price mancante con type=limit.

Modifica 2 — Override testnet via environment variable

Obiettivo

Permettere di forzare l'ambiente di esecuzione (testnet o mainnet) senza dover riscrivere secrets/deribit.json. Questa flessibilità è essenziale per Cerbero Bite, che gira in un container Docker dedicato e deve poter passare da paper trading a soft launch modificando solo una variabile d'ambiente.

Comportamento attesto

In __main__.py, dopo la lettura del file di credenziali, applicare la seguente precedenza di risoluzione:

1. Se la variabile d'ambiente DERIBIT_TESTNET è valorizzata, la sua conversione booleana (true|false, 1|0, case-insensitive) sovrascrive il campo testnet del file di credenziali.
2. Altrimenti vale il campo testnet del JSON.
3. Se nessuno dei due è presente, default True (precauzione: meglio testnet che mainnet per errore).

Variazione al main

def _resolve_testnet(creds: dict) -> bool:
    env = os.environ.get("DERIBIT_TESTNET")
    if env is not None:
        return env.strip().lower() in {"1", "true", "yes", "on"}
    return bool(creds.get("testnet", True))


client = DeribitClient(
    client_id=creds["client_id"],
    client_secret=creds["client_secret"],
    testnet=_resolve_testnet(creds),
)

Estensione del tool is_testnet

Il tool oggi ritorna {"testnet": bool, "base_url": str}. Aggiungere:

• source: "env" o "credentials" o "default" per indicare l'origine della scelta.
• env_value: valore grezzo letto da DERIBIT_TESTNET (utile per diagnosticare typo nel docker-compose).

In questo modo Cerbero Bite, all'avvio, può chiamare is_testnet, loggare il risultato e, se in disaccordo con la propria configurazione attesa (strategy.yaml o equivalente), armare il kill switch prima che parta qualsiasi ciclo di entry.

Documentazione e compose

• In docker-compose.yml, aggiungere environment: DERIBIT_TESTNET: "true" al servizio mcp-deribit con commento "override secrets/ deribit.json testnet flag".
• In services/mcp-deribit/README.md (se esiste, altrimenti creare), documentare la precedenza e le tre forme accettate di valore booleano.

Test

• Test che monta sia il file di credenziali (con testnet:false) sia l'env var (DERIBIT_TESTNET=true) e verifica che is_testnet riporti True con source="env".
• Test del default a True quando entrambe le sorgenti mancano (file con campo assente, env non settata).

Impatto su Cerbero Bite

Le due modifiche abilitano i seguenti flussi nella Fase 3 di Cerbero Bite:

• Il wrapper clients/deribit.py espone un metodo place_combo_order(short, long, side, n_contracts, limit_price) che inoltra direttamente al nuovo tool. Niente più sequenza di due place_order.
• All'avvio, l'orchestrator (Fase 4) chiama cerbero-deribit.is_testnet e:
  • blocca il boot se l'ambiente non corrisponde a quanto previsto in strategy.yaml (campo nuovo proposto: execution.environment: "testnet" | "mainnet");
  • scrive l'esito in system_state.config_version o in un campo dedicato system_state.environment per renderlo visibile alla GUI.
• Il documento di flusso operativo (docs/06-operational-flow.md) viene aggiornato per rimuovere la fase di conferma utente e introdurre l'auto-execute condizionato alle regole già codificate in core/.

Modifiche correlate ai documenti di Cerbero Bite

Una volta integrate le modifiche al server mcp-deribit, occorrerà allineare i seguenti documenti del progetto Cerbero Bite (sono modifiche editoriali, nessuna implicazione architetturale ulteriore):

• docs/04-mcp-integration.md: rimuovere le sezioni cerbero-memory e cerbero-brain-bridge; aggiungere la voce place_combo_order nella tabella di cerbero-deribit; aggiornare la matrice di degradation in modo che cerbero-deribit resti l'unico hard-fail di esecuzione.
• docs/06-operational-flow.md: sostituire il flusso di conferma Telegram con un flusso di sola notifica e auto-execute.
• docs/02-architecture.md: rimuovere il blocco cerbero-memory ⇆ Cerbero core dal diagramma.
• docs/05-data-model.md: la tabella instructions diventa il log degli ordini Deribit (combo combo_id, order_id, fill price, fees) anziché il tracking di push_user_instruction.
• docs/07-risk-controls.md: kill switch trigger per mismatch testnet/mainnet, da aggiungere alla matrice.
• strategy.yaml: aggiungere il blocco execution.environment: "testnet" con last_review aggiornato.

Out of scope di questo documento

Non sono oggetto di modifica al server mcp-deribit:

• La gestione di ordini combo a più di quattro gambe (i prodotti Cerbero Bite restano due o quattro gambe per Bull Put, Bear Call, Iron Condor).
• L'aggiunta di logica di repricing (incremento di un tick verso ask combinato): è responsabilità di Cerbero Bite via cancel_combo_order + place_combo_order con prezzo aggiornato.
• L'integrazione con cerbero-memory o cerbero-brain-bridge: nessun collegamento, neanche indiretto.

Sequenza di lavoro consigliata

1. Aprire un branch feat/place-combo-order su CerberoSuite/Cerbero.
2. Implementare il metodo client.place_combo_order con relativi test unitari sul client (mock di create_combo + buy).
3. Esporre il tool place_combo_order in server.py con i guard rail e i test FastAPI.
4. Aprire un branch separato feat/deribit-testnet-env per la modifica 2 (più piccola, indipendente dal resto).
5. Aggiornare docker-compose.yml con la variabile d'ambiente.
6. Una volta in main, su Cerbero Bite implementare il wrapper clients/deribit.py con i metodi place_combo_order e cancel_combo_order, scrivere i fake corrispondenti in tests/fixtures/fakes/deribit.py e i test integration in tests/integration/test_deribit_combo.py.