HomeInicio/Docs/Settlement backendsBackends de liquidación

Ledger-neutral settlementLiquidación neutral de libro

Settlement backends

Backends de liquidación

Pacta never moves money directly. Escrow, collateral, and slashing all go through a single SettlementBackend interface, and every settlement implementation satisfies it. Base is Pacta's reference settlement network and default on-chain implementation - not a dependency. This is the design in one line: Base first, with a clean seam for others.

Pacta nunca mueve dinero directamente. La custodia, el colateral y el slashing pasan todos por una única interfaz SettlementBackend, y toda implementación de liquidación la satisface. Base es la red de liquidación de referencia de Pacta y su implementación on-chain por defecto, no una dependencia. El diseño en una línea: Base primero, con una costura limpia para otros.

The interface

La interfaz

One interface, which the core depends on and every backend implements:

Una interfaz, de la que depende el core y que todo backend implementa:

interface SettlementBackend {
  readonly id: string;        // "ledger" | "base-escrow-vault"
  readonly currency: string;  // "USD"    | "USDC"

  openEscrow({ engagementId, buyer, provider, amountMinor }): EscrowHandle;
  fund(handle, amountMinor): SettlementReceipt;

  release(handle, authorization): SettlementReceipt;
  refund(handle, authorization): SettlementReceipt;
  split(handle, buyerMinor, providerMinor, authorization): SettlementReceipt;

  stakeBalance(provider): bigint;
  slash(provider, amountMinor, authorization): SettlementReceipt;
}

Four rules hold in every implementation, and they are what make the seam clean:

Cuatro reglas se cumplen en toda implementación, y son las que mantienen limpia la costura:

• Integer minor units only. Amounts cross the interface as integers - USD cents and USDC base units are both integers. No floats, ever.
• Solo unidades menores enteras. Los montos cruzan la interfaz como enteros: centavos de USD y unidades base de USDC son ambos enteros. Nunca decimales.
• Atomicity. A release either fully happens or fully does not; callers observe no partial state.
• Atomicidad. Una liberación ocurre por completo o no ocurre; quien llama no observa estados parciales.
• Authorization is data, not identity. Authorization carries signatures bound to the agreement hash. The ledger adapter checks them in application code; the vault adapter checks them in the contract. Same input shape, same semantics.
• La autorización es dato, no identidad. Authorization lleva firmas ligadas al hash del acuerdo. El adaptador de libro las comprueba en código; el adaptador de vault, en el contrato. Misma forma de entrada, misma semántica.
• The receipt is uniform. SettlementReceipt has the same fields regardless of backend, with an optional onchain block (tx hash, chain id, block number) that is null on the ledger. Callers never branch on backend type to read a receipt.
• El recibo es uniforme. SettlementReceipt tiene los mismos campos sin importar el backend, con un bloque opcional onchain (hash de tx, chain id, número de bloque) que es null en el libro. Quien llama nunca ramifica por tipo de backend para leer un recibo.

The two adapters that ship

Los dos adaptadores incluidos

Selection is configuration, not code. The MCP tools are identical across backends - an agent cannot tell which one is running:

La selección es configuración, no código. Las herramientas MCP son idénticas entre backends: un agente no puede saber cuál está corriendo:

SETTLEMENT_BACKEND=ledger              # default - no wallet, no chain, no crypto
SETTLEMENT_BACKEND=base-escrow-vault   # reference onchain backend (USDC on Base)

How to write a third backend

Cómo escribir un tercer backend

If you are porting Pacta to another settlement network, this is the whole job. Adding a backend requires implementing one interface and touching no core file:

Si estás portando Pacta a otra red de liquidación, este es todo el trabajo. Añadir un backend requiere implementar una interfaz y no tocar ningún archivo del core:

1. Create a package that implements the eight SettlementBackend methods above. Keep amounts as integer minor units and make each operation atomic.
2. Crea un paquete que implemente los ocho métodos de SettlementBackend de arriba. Mantén los montos como unidades menores enteras y haz atómica cada operación.
3. Verify Authorization signatures against the agreement hash - in your contract if the funds are on-chain, or in code if they are not. Do not invent a new signature scheme; the flow already produced signatures bound to the agreement hash at agreement time.
4. Verifica las firmas de Authorization contra el hash del acuerdo: en tu contrato si los fondos están on-chain, o en código si no. No inventes un esquema de firma nuevo; el flujo ya produjo firmas ligadas al hash del acuerdo al momento de acordar.
5. Return the uniform SettlementReceipt. Populate the optional onchain block (tx hash, chain id, block number) if your backend settles on a chain; leave it null otherwise.
6. Devuelve el SettlementReceipt uniforme. Rellena el bloque opcional onchain (hash de tx, chain id, número de bloque) si tu backend liquida en una cadena; déjalo en null si no.
7. Register a factory via registerSettlementBackend(id, factory) before startup and select it with SETTLEMENT_BACKEND=your-id. No core edit is required, and the reference vault package is a worked example.
8. Registra una fábrica con registerSettlementBackend(id, factory) antes del arranque y selecciónala con SETTLEMENT_BACKEND=tu-id. No hace falta editar el core, y el paquete del vault de referencia es un ejemplo resuelto.

Because the core calls only the interface, the same three example verticals (LandBridge, MedVoyage, Boa Vista) and the same 14 MCP tools work against any conforming backend without a line of change. That property is the point: a new chain adapter is cheap precisely because the neutrality is enforced, not merely promised.

Como el core solo llama a la interfaz, las mismas tres verticales de ejemplo (LandBridge, MedVoyage, Boa Vista) y las mismas 14 herramientas MCP funcionan contra cualquier backend conforme sin una línea de cambio. Esa propiedad es el punto: un nuevo adaptador de cadena es barato precisamente porque la neutralidad se hace cumplir, no solo se promete.