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

# Matching

> Il book degli ordini, come è rappresentata la priorità prezzo-tempo e come vi si risolvono la validità dell'ordine e la prevenzione dell'auto-negoziazione.

Il matching è una fase dentro l'[esecuzione del kernel](/it/protocol/architecture/kernel), non un servizio con cui la catena dialoga. Prende gli ordini del blocco nella loro sequenza confermata, li fa scorrere contro il book e produce esecuzioni. Non muove il saldo di nessuno: quello è compito della [stanza di compensazione](/it/protocol/architecture/clearinghouse), e avviene dopo che il matching è finito.

Tenere separate le due cose è ciò che rende il motore testabile. Il matching risponde a *che cosa si è incrociato con che cosa*. La stanza di compensazione risponde a *quanto costa e chi ora deve che cosa a chi*.

<h2 id="the-book">
  Il book
</h2>

Ogni strumento ha il proprio book, tenuto in memoria come tre strutture che cooperano:

<div className="dg" data-dg="matching-book">
  <div className="dg-c" style={{aspectRatio:"720 / 302"}}>
    <svg className="dg-w" viewBox="0 0 720 302" aria-hidden="true">
      <path className="dg-wire dg-soft" d="M 348.60 82.00 L 352.60 82.00" />

      <path className="dg-wire dg-soft" d="M 438.20 82.00 L 442.20 82.00" />

      <path className="dg-wire dg-soft" d="M 527.80 82.00 L 531.80 82.00" />

      <path className="dg-wire dg-soft" d="M 617.40 82.00 L 621.40 82.00" />

      <path className="dg-wire dg--blue" d="M 205.00 68.00 L 238.60 68.00" />

      <path className="dg-head dg--blue" d="M 245.00 68.00 L 238.60 72.40 L 238.60 63.60 Z" />

      <path className="dg-wire dg--sky" d="M 205.00 162.00 L 238.60 162.00" />

      <path className="dg-head dg--sky" d="M 245.00 162.00 L 238.60 166.40 L 238.60 157.60 Z" />
    </svg>

    <div className="dg-band" style={{left:"34.7222%",top:"9.9338%",width:"65.2778%",height:"56.2914%"}}><span className="dg-cap">Slab arena — una regione preallocata di slot per ordini</span></div>
    <div className="dg-b dg--blue" style={{left:"0.0000%",top:"9.9338%",width:"27.7778%",height:"25.1656%"}}><span className="dg-t">Livelli di prezzo</span><span className="dg-s">mappa ordinata, prezzo → livello</span><span className="dg-n">il top del book si trova andando in fondo, non scandendo</span></div>
    <div className="dg-b dg--sky" style={{left:"0.0000%",top:"41.0596%",width:"27.7778%",height:"25.1656%"}}><span className="dg-t">Indice ordini</span><span className="dg-s">id ordine → slot</span><span className="dg-n">annulla e modifica a tempo costante</span></div>
    <div className="dg-b dg--yellow" style={{left:"36.9444%",top:"19.5364%",width:"11.0556%",height:"15.2318%"}}><span className="dg-t">ordine</span></div>
    <div className="dg-b dg--yellow" style={{left:"49.3889%",top:"19.5364%",width:"11.0556%",height:"15.2318%"}}><span className="dg-t">ordine</span></div>
    <div className="dg-b dg--yellow" style={{left:"61.8333%",top:"19.5364%",width:"11.0556%",height:"15.2318%"}}><span className="dg-t">ordine</span></div>
    <div className="dg-b dg--yellow" style={{left:"74.2778%",top:"19.5364%",width:"11.0556%",height:"15.2318%"}}><span className="dg-t">ordine</span></div>
    <div className="dg-b dg--yellow" style={{left:"86.7222%",top:"19.5364%",width:"11.0556%",height:"15.2318%"}}><span className="dg-t">ordine</span></div>
    <div className="dg-b dg-plain dg-left" style={{left:"36.9444%",top:"41.3907%",width:"60.8333%",height:"15.2318%"}}><span className="dg-s">Catena doppiamente concatenata in sequenza di arrivo: la priorità dentro un livello è posizionale, non calcolata.</span></div>
    <div className="dg-b dg-dashed dg-left" style={{left:"0.0000%",top:"74.8344%",width:"100.0000%",height:"20.5298%"}}><span className="dg-t">Perché l'ordine di riuso è fisso</span><span className="dg-s">Gli slot liberati sono riusati in ordine fisso e l'indice ha seed fisso. Non è una scelta di prestazioni: due validatori che li riusano in ordini diversi divergerebbero.</span></div>
    <div className="dg-lbl" style={{left:"31.2500%",top:"17.8808%",width:"15.2778%",whiteSpace:"normal"}}>testa di ogni livello</div>
    <div className="dg-lbl" style={{left:"31.2500%",top:"62.9139%",width:"15.2778%",whiteSpace:"normal"}}>lookup diretto</div>
  </div>
</div>

| Struttura               | Ruolo                                                                                                                                              |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Livelli di prezzo**   | Una mappa ordinata da prezzo a livello, così il miglior bid e il miglior ask si trovano andando in fondo invece di scandire tutto                  |
| **Catena degli ordini** | Una lista doppiamente concatenata che infila gli ordini nella sequenza di arrivo, così la priorità dentro un livello è posizionale e non calcolata |
| **Indice degli ordini** | Una mappa diretta dall'ID dell'ordine al suo slot, così annullamento e modifica sono a tempo costante invece di una ricerca                        |

Gli ordini risiedono in una **slab arena**: una regione preallocata con allocazione e rilascio a tempo costante. Le operazioni sul book quindi non allocano sul percorso critico, e gli slot liberati vengono riusati in un ordine fisso invece che dove capita all'allocatore. Quest'ultimo dettaglio non è una scelta di prestazioni: se due validatori riusassero gli slot in ordini diversi, tutto ciò che osserva la disposizione degli slot divergerebbe.

La stessa disciplina vale per l'indice degli ordini, il cui seed è fisso e non casuale. Una hash map con seed per processo è una difesa standard contro gli attacchi per collisione; su un percorso di esecuzione di consenso è un fork.

I prezzi sono interi ovunque: unità di subtick, non decimali. Vedi [Precisione](/it/trading/precision) per come questo si traduce in ciò che invii.

<h2 id="priority">
  La priorità
</h2>

La priorità è prima il prezzo, poi la posizione nella catena a quel prezzo. Il «tempo» è la posizione canonica dell'ordine nella sequenza confermata del blocco, non il momento in cui è arrivato a un nodo.

È questo a eliminare la corsa alla latenza dentro il blocco. Due ordini nello stesso blocco hanno una precedenza definita che ogni validatore calcola in modo identico, e nessuna vicinanza a un nodo particolare la cambia. Tra un blocco e l'altro l'arrivo conta ancora, ma l'unità di competizione è il blocco, non il microsecondo.

L'ordine delle fasi del kernel rafforza tutto questo: dentro un blocco gli annullamenti vengono eseguiti prima delle immissioni aggressive, così un prezzo esposto in book non può essere colpito da un ordine arrivato nello stesso blocco del suo annullamento.

<h2 id="matching-an-order">
  Incrociare un ordine
</h2>

<div className="dg" data-dg="matching-walk">
  <div className="dg-c" style={{aspectRatio:"720 / 334"}}>
    <svg className="dg-w" viewBox="0 0 720 334" aria-hidden="true">
      <path className="dg-wire dg--blue" d="M 134.00 144.00 L 155.60 144.00" />

      <path className="dg-head dg--blue" d="M 162.00 144.00 L 155.60 148.40 L 155.60 139.60 Z" />

      <path className="dg-wire dg--sky" d="M 320.00 144.00 L 345.60 144.00" />

      <path className="dg-head dg--sky" d="M 352.00 144.00 L 345.60 148.40 L 345.60 139.60 Z" />

      <path className="dg-wire dg--green" d="M 510.00 144.00 L 535.60 144.00" />

      <path className="dg-head dg--green" d="M 542.00 144.00 L 535.60 148.40 L 535.60 139.60 Z" />

      <path className="dg-wire dg--sky" d="M 633.00 114.00 L 633.00 80.00 L 241.00 80.00 L 241.00 103.60" />

      <path className="dg-head dg--sky" d="M 241.00 110.00 L 236.60 103.60 L 245.40 103.60 Z" />

      <path className="dg-wire dg--green" d="M 633.00 174.00 L 633.00 213.60" />

      <path className="dg-head dg--green" d="M 633.00 220.00 L 628.60 213.60 L 637.40 213.60 Z" />

      <path className="dg-wire dg--sky" d="M 241.00 178.00 L 241.00 213.60" />

      <path className="dg-head dg--sky" d="M 241.00 220.00 L 236.60 213.60 L 245.40 213.60 Z" />
    </svg>

    <div className="dg-b dg--blue" style={{left:"0.0000%",top:"35.3293%",width:"18.0556%",height:"15.5689%"}}><span className="dg-t">Ordine in arrivo</span></div>
    <div className="dg-b dg--yellow dg-round" style={{left:"23.0556%",top:"34.1317%",width:"20.8333%",height:"17.9641%"}}><span className="dg-t">Incrocia il book?</span></div>
    <div className="dg-b dg--sky" style={{left:"49.4444%",top:"35.3293%",width:"20.8333%",height:"15.5689%"}}><span className="dg-t">Consuma il miglior livello opposto</span></div>
    <div className="dg-b dg--green" style={{left:"75.8333%",top:"35.3293%",width:"24.1667%",height:"15.5689%"}}><span className="dg-t">Emette l'esecuzione</span></div>
    <div className="dg-b dg--green" style={{left:"75.8333%",top:"67.0659%",width:"24.1667%",height:"25.7485%"}}><span className="dg-t">Fine</span></div>
    <div className="dg-b dg--sky dg-left" style={{left:"10.5556%",top:"67.0659%",width:"45.8333%",height:"25.7485%"}}><span className="dg-t">Resta in book o è rifiutato, secondo la validità</span><span className="dg-s">GTC resta in book · IOC lo annulla · FOK non esegue nulla se non per intero · post-only è rifiutato invece di incrociare</span></div>
    <div className="dg-lbl" style={{left:"60.6944%",top:"23.9521%",width:"27.7778%",whiteSpace:"normal"}}>residuo — prende il livello dopo</div>
    <div className="dg-lbl" style={{left:"87.9167%",top:"58.9820%"}}>nessun residuo</div>
  </div>
</div>

Il motore consuma ripetutamente la testa del lato opposto, emettendo un'esecuzione per ogni maker che prende, finché l'ordine in arrivo non è esaurito o il book non incrocia più. Che cosa succede al residuo lo decide la validità dell'ordine:

* **GTC** — il residuo resta in book.
* **IOC** — il residuo viene annullato.
* **FOK** — se l'ordine non può essere eseguito per intero, non viene eseguito niente.
* **ALO** — post-only (solo maker): se l'ordine prendesse liquidità, viene rifiutato invece di incrociare.

Le esecuzioni portano con sé l'attribuzione fin da quando vengono prodotte. Ogni esecuzione registra dove si colloca nella sequenza di esecuzioni del proprio strumento, e quelle posizioni per strumento vengono risolte in un unico ordinamento su tutto il blocco quando l'output viene assemblato. È questo che permette, più tardi, di risalire da un evento all'esatta transazione e all'esatto punto del blocco che l'ha causato.

<h2 id="self-trade-prevention">
  Prevenzione dell'auto-negoziazione
</h2>

Quando un ordine in arrivo si incrocerebbe con liquidità in book dello stesso titolare, l'incrocio viene soppresso invece che eseguito. Quale lato cede è configurabile:

| Modalità         | Comportamento                                                  |
| ---------------- | -------------------------------------------------------------- |
| **Expire taker** | L'ordine in arrivo viene annullato                             |
| **Expire maker** | L'ordine in book viene annullato e l'ordine in arrivo prosegue |
| **Expire both**  | Entrambi vengono annullati                                     |

I maker annullati in questo modo vengono raccolti durante il matching e rimossi come parte dello stesso blocco, così nel book non resta un ordine già soppresso.

Per questo controllo la titolarità si risolve al livello di conto che il book traccia. Vedi [Prevenzione dell'auto-negoziazione](/it/trading/self-trade-prevention) per la prospettiva lato trading.

<h2 id="what-matching-does-not-do">
  Che cosa il matching non fa
</h2>

Non calcola le commissioni, non realizza il P\&L, non aggiusta le posizioni e non controlla il margine. Quelle cose avvengono dopo il matching, nella [stanza di compensazione](/it/protocol/architecture/clearinghouse), guidate dalle esecuzioni che il matching ha prodotto.

Non decide nemmeno se un ordine avesse il diritto di esistere. L'adeguatezza del margine, i limiti sugli ordini aperti, i vincoli reduce-only e la conversione da mercato a limite sono risolti prima che un ordine arrivi al book. Quando il motore di matching vede un ordine, la domanda è solo dove collocarlo nel book.

<h2 id="where-to-go-next">
  Dove proseguire
</h2>

<CardGroup cols={2}>
  <Card title="Stanza di compensazione" href="/it/protocol/architecture/clearinghouse">
    Che cosa succede a saldi e posizioni una volta che le esecuzioni esistono.
  </Card>

  <Card title="Tipi di ordine" href="/it/trading/order-types">
    La prospettiva lato trading: che cosa puoi inviare e come si comporta ciascun tipo.
  </Card>

  <Card title="Book degli ordini" href="/it/trading/order-book">
    Profondità, livelli e come leggere il book da trader.
  </Card>

  <Card title="IntentionKernel" href="/it/protocol/architecture/kernel">
    Dove sta il matching nell'esecuzione del blocco.
  </Card>
</CardGroup>