Skip to main content

Holding funds

Reservation is like putting Alice's money inside a little box with a label on it: "do not spend — waiting for delivery." The money is real, it's Alice's, but neither Bob nor Mercatto can touch it yet. In Sandbox, Mercatto simulates Alice's deposit landing and confirming; in Production this is a real transfer someone actually broadcasts.

DepositCONFIRMEDautomaticTransactionRESERVED🔒AliceAvailable: 0Reserved: 200
No explicit reserve() call exists in this path — confirming the deposit is enough.

Code​

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;
}

Result​

{ "status": "RESERVED" }

What happened under the hood​

simulateDeposit/simulateConfirmation exist only in Sandbox (SandboxBlockchainConnector) — Mercatto never had to run a real blockchain node to develop this. Once confirmed, the Transaction moves through FUNDED to RESERVED on its own; these are real, separate, non-instantaneous steps — a naive check for "not still awaiting funds" can observe FUNDED and move on too early, which is why the polling above waits for RESERVED specifically. Underneath, reservation is a real Ledger transition: Alice's Available balance moves to Reserved, a balanced pair of Ledger Entries, not a status flag with no financial effect.