Holding funds

Reservar é como colocar o dinheiro de Alice dentro de uma caixinha com uma etiqueta: "não gastar — aguardando entrega." O dinheiro é real, é da Alice, mas nem Bob nem a Mercatto conseguem tocar nele ainda. No Sandbox, a Mercatto simula o depósito de Alice chegando e confirmando; em Production isso é uma transferência real que alguém de fato transmite.

Não existe uma chamada explícita de reserve() nesse caminho — confirmar o depósito já basta.

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

O que aconteceu por baixo dos panos

simulateDeposit/simulateConfirmation só existem no Sandbox (SandboxBlockchainConnector) — a Mercatto nunca precisou rodar um nó blockchain de verdade para desenvolver isso. Uma vez confirmado, a Transaction passa por FUNDED até RESERVED sozinha; esses são passos reais, separados, não-instantâneos — uma checagem ingênua de "não está mais aguardando fundos" pode observar FUNDED e seguir em frente cedo demais, e é por isso que o polling acima espera especificamente por RESERVED. Por baixo, a reserva é uma transição real de Ledger: o saldo Available de Alice se move para Reserved, um par balanceado de Ledger Entries, não apenas uma flag de status sem efeito financeiro.