Saltar al contenido principal

Holding funds

La reserva es como poner el dinero de Alice dentro de una pequeña caja con una etiqueta: "no gastar — esperando entrega." El dinero es real, es de Alice, pero ni Bob ni Mercatto pueden tocarlo todavía. En Sandbox, Mercatto simula que el depósito de Alice llega y se confirma; en Production esto es una transferencia real que alguien realmente transmite.

DepositCONFIRMEDautomáticoTransactionRESERVED🔒AliceAvailable: 0Reserved: 200
En este flujo no existe ninguna llamada explícita a reserve() — confirmar el depósito es suficiente.

Código​

examples/marketplace-mercatto/pay-order.ts
const observed = await mercatto.sandbox.simulateDeposit(environmentId, depositAddress, assetNetworkId, GROSS_AMOUNT);
await mercatto.sandbox.simulateConfirmation(environmentId, observed.sandboxObservedAddressId, 1, true);

// CREATED -> AWAITING_FUNDS -> FUNDED -> RESERVED are all real, distinct, non-instantaneous
// transitions -- poll for RESERVED specifically, not just "no longer awaiting funds".
let status = (await mercatto.transactions.getState(transactionId)).status;
while (status.name !== 'RESERVED') {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  status = (await mercatto.transactions.getState(transactionId)).status;
}

Resultado​

{ "status": "RESERVED" }

Qué pasó por debajo​

simulateDeposit/simulateConfirmation existen solo en Sandbox (SandboxBlockchainConnector) — Mercatto nunca tuvo que correr un nodo blockchain real para desarrollar esto. Una vez confirmada, la Transaction pasa por FUNDED hasta llegar a RESERVED por sí sola; estos son pasos reales, separados, no instantáneos — una verificación ingenua de "ya no está esperando fondos" puede observar FUNDED y avanzar demasiado pronto, por eso el polling de arriba espera específicamente a RESERVED. Por debajo, la reserva es una transición real del Ledger: el balance Available de Alice se mueve a Reserved, un par balanceado de Ledger Entries, no una bandera de estado sin efecto financiero.