Market Maker Protection (MMP)

Fill-Window-Limits und automatisches Stornierungsverhalten für Market Maker.

Jeder Wallet-bezogene MMP-Endpunkt erfordert EIP-712-Authentifizierung. Konfigurationsschreibvorgänge akzeptieren den Wallet-Inhaber oder einen autorisierten Agenten für diese Wallet. Lesevorgänge sind nur dem Inhaber vorbehalten und lehnen Signaturen autorisierter Agenten ab.

MMP gilt für das Handelskonto, dem die Fills gehören. Bei einem Portfolio-Margin-Manager werden Lese- und Schreibvorgänge, die für die Manager-Wallet signiert sind, auf dessen Account.sol-Handelskonto aufgelöst, dasselbe Konto, das auch die Order-Platzierung verwendet. Antworten geben dieses Konto in wallet_address an, und die MMP-Nonce-Sequenz gehört zu diesem Konto.

Für Read-after-Write-Konsistenz senden Sie bei jeder MMP-Mutation X-Hypercall-Fence-Wait: 1. Eine erfolgreiche Antwort enthält dann X-Hypercall-Fence; geben Sie diesen Wert als X-Hypercall-Fence beim authentifizierten GET zurück. Mutationen ohne den Opt-in-Wait-Header geben bewusst keinen Fence zurück.

Überblick

MMP schützt Market Maker vor schnellen nachteiligen Fills, indem es:

1. Kumulative Fill-Metriken innerhalb eines rollierenden Zeitfensters verfolgt
2. Orders storniert, wenn Limits überschritten werden
3. Alle anderen MMP-aktivierten Orders derselben Kombination aus Wallet und Basiswert automatisch storniert

Konfiguration

MMP-Konfiguration festlegen

Endpunkt: POST /mmp-config

Anfrage: SetMmpConfigRequest

{
  "wallet": "0x...",
  "currency": "BTC",
  "interval_ms": 60000,
  "frozen_time_ms": 300000,
  "qty_limit": "1000000",
  "delta_limit": "10.0",
  "vega_limit": "5.0",
  "nonce": 1,
  "signature": "0x..."
}

Felder:

• wallet: Wallet-Adresse
• currency: Währung des Basiswerts (z. B. "BTC", "ETH")
• interval_ms: Länge des rollierenden Fensters in Millisekunden
• frozen_time_ms: Sperrdauer nach dem Auslösen (Millisekunden)
• qty_limit: Optionales Mengenlimit (Kontrakteinheiten), serialisiert als Dezimal-String
• delta_limit: Optionales Delta-Limit, serialisiert als Dezimal-String
• vega_limit: Optionales Vega-Limit, serialisiert als Dezimal-String
• nonce: Nonce zum Replay-Schutz, genau um eins größer als die zuletzt festgeschriebene Nonce, die der authentifizierte Lesevorgang zurückgibt
• signature: EIP-712-SetMmpConfig-Signatur über alle Felder der Anfrage

Antwort: ApiResponse<MmpConfigData>

MMP-Konfiguration abrufen

Endpunkt: GET /mmp-config?wallet=...&currency=...

Query-Parameter:

• wallet (erforderlich)
• currency (optionaler Filter)

Erforderliche Header:

• X-Hypercall-Expires-At-Ms: Unix-Ablaufzeit in Millisekunden, höchstens 60 Sekunden in der Zukunft
• X-Hypercall-Signature: GetMmpConfig-Signatur über wallet, currency (leerer String, wenn weggelassen) und die Header-Ablaufzeit

Der wiederhergestellte Signierer muss der Wallet-Inhaber sein. Signaturen autorisierter Agenten werden für diesen Lesevorgang nicht akzeptiert.

Antwort: MmpConfigResponse

{
  "success": true,
  "data": [
    {
      "wallet_address": "0x...",
      "currency": "BTC",
      "interval_ms": 60000,
      "frozen_time_ms": 300000,
      "qty_limit": "1000000",
      "delta_limit": "10.0",
      "vega_limit": "5.0",
      "enabled": true,
      "nonce": 1
    }
  ]
}

MMP-Konfiguration löschen

Endpunkt: DELETE /mmp-config

Anfrage: DeleteMmpConfigRequest

{
  "wallet": "0x...",
  "currency": "BTC",
  "nonce": 1,
  "signature": "0x..."
}

Antwort: ApiResponse<String>. Ein erfolgreicher Befehl deaktiviert den numerischen Autoritätszustand für Wallet und Basiswert. Mit dem Anfrage-Header X-Hypercall-Fence-Wait: 1 enthält die Antwort X-Hypercall-Fence für den projektionsbasierten Lesevorgang.

MMP-Zustand zurücksetzen

Endpunkt: POST /mmp-config/reset

Anfrage: ResetMmpRequest

{
  "wallet": "0x...",
  "currency": "BTC",
  "nonce": 1,
  "signature": "0x..."
}

Antwort: ApiResponse<String>. Ein erfolgreicher Befehl leert das MMP-Fill-Fenster und den Sperrzustand in der replay-fähigen Autorität. Mit dem Anfrage-Header X-Hypercall-Fence-Wait: 1 enthält die Antwort X-Hypercall-Fence für den projektionsbasierten Lesevorgang.

MMP-Verhalten (wichtig zu verstehen)

Welche Fills zählen

Jeder Fill zählt zum MMP-Fenster jeder Seite, deren Order mmp_enabled=true hat, unabhängig davon, ob diese Order im Orderbuch lag (Maker) oder eingehend war (Taker):

• Ruhende Quotes: Wenn eine eingehende Order gegen Ihre ruhende MMP-aktivierte Order handelt, wird dieser Fill Ihrem Fenster hinzugefügt. Für genau diesen Fall existiert MMP: Eine Serie von Fills gegen Ihre Quotes löst MMP aus und storniert Ihre verbleibenden MMP-aktivierten Quotes auf diesem Basiswert.
• Eingehende Orders: Eine MMP-aktivierte Order, die Liquidität nimmt, zählt ihre eigenen Fills auf dieselbe Weise.
• Combos und implizite Orders: Jeder geschützte Teilnehmer eines Pakets zählt jedes gehandelte Leg, bewertet einmal pro Paket.
• RFQ- und RPI-Fills zählen derzeit noch nicht für MMP. Eine MMP-Sperre blockiert jedoch neue RFQ-Ausführungen für den gesperrten Quote-Anbieter.

Jeder Fill wird aus Ihrer eigenen Sicht gemessen: Ein Fill, der eine Call-Option verkauft, fügt dem Fenster des Verkäufers negatives Delta und dem des Käufers positives Delta hinzu.

Wenn eine Order mmp_enabled=true hat, ihre Wallet aber keine MMP-Konfiguration für diesen Basiswert besitzt, schlägt MMP geschlossen fehl (fail closed): Der erste Fill löst aus und storniert die MMP-aktivierten Orders dieser Wallet auf dem Basiswert. Konfigurieren Sie MMP, bevor Sie Orders markieren.

Reihenfolge der Fill-Verarbeitung

Die MMP-Auswertung erfolgt NACH DEM FILL:

1. Die Engine matcht und akzeptiert zuerst den Fill
2. Anschließend prüft MMP die kumulativen Metriken für jede geschützte Seite des Fills
3. Wenn die Limits einer Seite überschritten werden:
   • MMP wird für die Wallet und den Basiswert dieser Seite ausgelöst
   • Die Engine sendet das Event MmpTriggered
   • Die Engine storniert automatisch alle MMP-aktivierten offenen Orders für diese Kombination aus Wallet und Basiswert
   • War die überschreitende Seite die eingehende Order, wird ihre verbleibende Menge gestoppt und sie wird CANCELED mit dem Grund "MMP triggered during fill processing"
   • War die überschreitende Seite ein ruhender Maker, matcht die eingehende Order weiterhin gegen andere Liquidität; die übrigen MMP-aktivierten Quotes des Makers sind bereits storniert

Konsequenz: Sie können Fills erhalten, die Sie über Ihre konfigurierten Schwellenwerte hinausbringen, bevor MMP auslöst.

Auslösebedingungen

MMP löst aus, wenn irgendein konfiguriertes Limit überschritten wird:

• Mengenlimit: cumulative_qty > qty_limit
• Delta-Limit: |cumulative_delta| > delta_limit
• Vega-Limit: |cumulative_vega| > vega_limit

Kumulative Metriken werden über das rollierende Fenster (interval_ms) berechnet.

Stornierungsverhalten

Wenn MMP auslöst:

1. Eingehende Order, die ausgelöst hat: Die verbleibende Menge wird gestoppt, die Order wird CANCELED mit dem Grund "MMP triggered during fill processing"
2. Ruhende Order, die ausgelöst hat: Der Fill bleibt bestehen; ein etwaiger Rest der Order wird zusammen mit den anderen MMP-aktivierten Orders storniert
3. Andere Orders: Alle MMP-aktivierten offenen Orders derselben Kombination aus Wallet und Basiswert werden automatisch mit dem Grund "Order canceled by MMP trigger" storniert

Hinweis: Nur MMP-aktivierte Orders werden storniert. Orders mit mmp_enabled=false sind nicht betroffen.

Sperrverhalten

Nachdem MMP ausgelöst hat:

• Wallet und Basiswert werden für frozen_time_ms Millisekunden gesperrt
• Während der Sperre ist die Wallet von RPI-Auktionen und RFQs auf diesem Basiswert ausgeschlossen, und Combo- oder implizite Ausführungen, die sie füllen würden, werden abgelehnt
• Ein direkter Fill auf eine MMP-aktivierte Order während der Sperre bleibt dennoch bestehen, löst dann MMP erneut aus und storniert die MMP-aktivierten Orders dieser Wallet auf dem Basiswert
• POST /mmp-config/reset beendet die Sperre vorzeitig

Berechnung der Fill-Metriken

Menge

• Quelle: Fill-size (Kontrakteinheiten)
• Kumulativ: Summe aller Fills im rollierenden Fenster

Delta

• Quelle: Berechnet aus dem Fill-Symbol und dem GreeksCache
• Kumulativ: Summe aller Fill-Deltas im rollierenden Fenster

Vega

• Quelle: Berechnet aus dem Fill-Symbol und dem GreeksCache
• Kumulativ: Summe aller Fill-Vegas im rollierenden Fenster

Rollierendes Fenster

Entfernen aus dem Fenster

Fills, die älter als interval_ms sind, werden automatisch aus dem Fenster entfernt:

• Die Entfernung erfolgt, wenn der nächste Fill verarbeitet wird, bevor der neue Fill hinzugefügt wird
• Kumulative Metriken werden verringert, sobald alte Fills entfernt werden

Zurücksetzen des Fensters

Setzen Sie den MMP-Zustand über POST /mmp-config/reset zurück:

• Leert alle Fills im Fenster
• Setzt die kumulativen Metriken auf null zurück
• Hebt die Sperre der Währung auf

MMP-Events

MmpTriggered-Event

Internes Event (wird derzeit nicht an WS-Clients weitergeleitet):

MmpTriggeredMessage {
    wallet: WalletAddress,
    currency: String,
    reason: String,  // "MMP triggered during fill processing" | "MMP triggered by a resting order fill"
    timestamp: u64,
}

Best Practices

Konfiguration

1. Angemessene Limits festlegen: Basierend auf Ihrer Risikotoleranz und typischen Fill-Größen
2. Währungsspezifische Konfigurationen verwenden: Konfigurieren Sie pro Basiswert (BTC, ETH usw.)
3. MMP-Auslösungen überwachen: Eine hohe Auslöserate kann auf falsch konfigurierte Limits oder ungünstige Marktbedingungen hinweisen

Order-Management

1. MMP gezielt aktivieren: Setzen Sie mmp_enabled=true nur für Orders, die geschützt werden sollen
2. Einheitliche Währung verwenden: Stellen Sie sicher, dass alle Orders für denselben Basiswert dieselbe Währung in der MMP-Konfiguration verwenden
3. MMP-Stornierungen behandeln: Implementieren Sie Logik, um durch MMP ausgelöste Stornierungen zu erkennen und das Quoting anzupassen

Überwachung

1. MMP-Auslösungen verfolgen: Achten Sie auf die Gründe "MMP triggered during fill processing" und "Order canceled by MMP trigger"
2. Fill-Fenster prüfen: Kumulative Fenstermetriken werden noch nicht über die API bereitgestellt; verfolgen Sie Ihre eigenen Fills pro Basiswert
3. Limits anpassen: Löst MMP zu häufig aus, erhöhen Sie die Limits; löst es zu selten aus, senken Sie sie

Häufige Probleme

MMP löst zu häufig aus

Ursachen:

• Limits zu niedrig für typische Fill-Größen
• Ungünstige Marktbedingungen
• Schnelles Quoting, das viele Fills verursacht

Lösungen:

• Erhöhen Sie qty_limit, delta_limit oder vega_limit
• Erhöhen Sie interval_ms, um mehr Fills im Fenster zuzulassen
• Reduzieren Sie die Quoting-Frequenz

MMP löst nicht aus

Ursachen:

• Limits zu hoch
• MMP auf Orders nicht aktiviert (mmp_enabled=false)
• Währungskonflikt (Währung der MMP-Konfiguration != Basiswert der Order)

Lösungen:

• Senken Sie die Limits
• Prüfen Sie, ob mmp_enabled=true auf den Orders gesetzt ist
• Prüfen Sie, ob die Währung der MMP-Konfiguration mit dem Basiswert der Order übereinstimmt

Unerwartete Stornierungen

Symptom: Orders werden mit dem Grund "Order canceled by MMP trigger" storniert, obwohl Sie dies nicht erwartet haben.

Ursache: Eine andere Order derselben Kombination aus Wallet und Basiswert hat MMP ausgelöst.

Lösung: Überprüfen Sie alle MMP-aktivierten Orders für denselben Basiswert, wenn eine davon auslöst.