# Arquitectura

## Actores

### Enrutador

El router es el contrato que actúa como punto de entrada para todas las llamadas DEX. Es responsable de enrutar todas las llamadas de Jetton con `transfer_notification` op al contrato de pool correcto.

Actúa como soberano sobre el DEX, y puede usarse para bloquear/desbloquear el trading en todos los pools, cambiar las comisiones de un determinado pool o actualizar su propio contrato. El router es el **único** contrato que puede actualizarse. Cada Jetton que pasa por el DEX es propiedad del router. El router no almacena nada sobre los pares.

### Pool

El pool es el contrato que almacena los datos AMM de un determinado par y es responsable de manejar los "swaps" o de proporcionar liquidez para un determinado pool. Para cada par (p. ej., TOKEN/USDT), solo existe un único contrato de pool. El pool también es un `Jetton Minter`, y maneja la acuñación/quema de Jettons de Proveedor de Liquidez. Todos los cálculos de swap/lp se realizan en el contrato del pool.

### Cuenta

El contrato de cuenta almacena información sobre la liquidez proporcionada por el usuario antes de acuñar nueva liquidez. Interactúa solo con un único contrato de pool. Para cada usuario, existe un solo contrato de cuenta para cada pool. El router "enruta" la liquidez temporal al contrato de cuenta correcto. Luego, el contrato de cuenta vuelve a llamar al contrato del pool para acuñar nueva liquidez (una vez que cumple algunos requisitos).

### Wallet (para jettons LP)

El contrato de wallet es una wallet estándar de Jetton y se usa para almacenar el Jetton LP acuñado por los Pools.

## Descripciones de llamadas

### Swap

Supongamos que Alice quiere comprar TOKEN usando USDT. Ella debería iniciar una transferencia simple a su propia Wallet de USDT con un payload personalizado. Una vez que el Router reciba la confirmación de la transferencia, llamará al contrato de Pool para realizar el swap real. Luego, el contrato de Pool devolverá el Jetton TOKEN llamando `pay_to` op al Router.

{% @mermaid/diagram content="graph LR
A((USDT Alice<br/>Wallet)) --> |internal\_transfer|B((USDT Router<br/>Wallet))
B --> |transfer\_notification|C{Router}
C --> |swap|D\[USDT/TOKEN<br/>Pool]
D -.-> |pay\_to|C
C -.-> |transfer|E((TOKEN Router<br/>Wallet))
E -.-> |internal\_transfer|F((TOKEN Alice<br/>Wallet))" %}

### Proporcionar liquidez (ambos importes)

Ahora Alice quiere proporcionar liquidez al par TOKEN/USDT. Este proceso debe hacerse mediante dos llamadas diferentes. Obviamente, dado que las wallets admiten hasta 4 transacciones al mismo tiempo, es posible realizar ambas llamadas al mismo tiempo (al menos, desde la perspectiva del usuario).

Al principio, debe iniciar una transferencia a su propia Wallet de USDT con un payload personalizado. Una vez que el Router reciba la confirmación de la transferencia, llamará al contrato de Pool, y luego el contrato de Pool enroutará la solicitud a su propio contrato de Cuenta. Una vez que la solicitud llega al contrato de Cuenta, la primera fase termina aquí. Esta vez el contrato de Cuenta no genera ninguna transacción.

En Dex v1 es posible proporcionar liquidez usando una proporción diferente a la actual en el pool, por lo que la parte desbalanceada se perderá para el usuario y se distribuirá entre todos los proveedores de liquidez. En Dex v2 siempre se acuña al usuario una cantidad máxima de liquidez, lo que significa que la cantidad desbalanceada de un token se intercambia automáticamente usando la proporción actual de tokens en el pool.

{% @mermaid/diagram content="graph LR
A((USDT Alice<br/>Wallet)) --> |internal\_transfer|B((USDT Router<br/>Wallet))
B --> |transfer\_notification|C{Router}
C --> |provide\_lp|D\[USDT/TOKEN<br/>Pool]
D --> |add\_liquidity|E(USDT/TOKEN<br/>Alice Account)" %}

Ahora, Alice realiza otra transferencia del otro Jetton (en nuestro caso, TOKEN) de la misma manera que antes. Esta vez, el contrato de Cuenta generará un nuevo mensaje al contrato de Pool para acuñar nueva liquidez.

{% @mermaid/diagram content="graph LR
A((TOKEN Alice<br/>Wallet)) --> |internal\_transfer|B((TOKEN Router<br/>Wallet))
B --> |transfer\_notification|C{Router}
C --> |provide\_lp|D\[USDT/TOKEN<br/>Pool]
D --> |add\_liquidity|E(USDT/TOKEN<br/>Alice Account)
E -.-> |cb\_add\_liquidity|D
D -.-> |"internal\_transfer (mint)"|F((LP<br/>USDT/TOKEN<br/>Alice Wallet))" %}

### Proporcionar liquidez (provisión de un solo lado)

Dex v2 admite la provisión de liquidez usando solo un token mediante la ejecución automática de un swap antes de acuñar liquidez

{% @mermaid/diagram content="graph LR
A((TOKEN Alice<br/>Wallet)) --> |internal\_transfer|B((TOKEN Router<br/>Wallet))
B --> |transfer\_notification|C{Router}
C --> |provide\_lp|D\[USDT/TOKEN<br/>Pool]
D --> |add\_liquidity|E(USDT/TOKEN<br/>Alice Account)
E -.-> |cb\_add\_liquidity|D
D -.-> |"internal\_transfer (mint)"|F((LP<br/>USDT/TOKEN<br/>Alice Wallet))" %}

### Crear un pool

#### V1

Para crear un nuevo Pool, solo proporciona la cantidad mínima de liquidez al par (1001 Jettons). Esta liquidez inicial se enviará a `dirección nula`. Cualquier llamada de LP después de esto acuñará Jettons LP para un usuario.

#### V2

Para crear un nuevo Pool, solo proporciona la cantidad mínima de liquidez al par (1001 Jettons). Se reservará una cantidad básica de 1001 tokens lp en el pool en el depósito inicial de liquidez, y el resto irá al usuario.

#### Stableswap

La creación de un pool de stableswap es gestionada directamente por STON.fi y no puede ser realizada por los usuarios.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ston.fi/es/seccion-para-desarrolladores/dex/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.