Pular para o conteúdo principal

Settlement and Split

Agora que a Mercatto sabe que os fones chegaram, ela abre a caixa. A Ishtaran tira sua própria e pequena Platform Fee do topo, depois divide o que sobra exatamente como o pedido especificou lá em Creating an order: 90% para Bob, 10% para a Mercatto.

Gross: 200.00− Platform Fee da Ishtaran (0,9%)1.80Distributable: 198.20Bob — 90%178.38Mercatto — 10%19.82
Números reais de uma execução real — a Fee da Ishtaran nunca está hardcoded neste exemplo; ela é lida do próprio resultado do Settlement.

Código​

examples/marketplace-mercatto/release-order.ts
const executed = await mercatto.settlements.executeSettlement(transactionId);
const settlement = await completeSelfCustodySettlement(mercatto, environmentId, executed.settlementId, executionSigner);
const summary = await mercatto.settlements.getSummary(transactionId);

Resultado​

{
  "status": "COMPLETED",
  "signingRequestId": "…sr…",
  "grossAmount": "200.000000000000000000",
  "platformFeeAmount": "1.800000000000000000",
  "distributableAmount": "198.200000000000000000",
  "feePercentageApplied": "0.900000000000000000",
  "splitAllocations": [
    { "accountId": "…bob…", "amount": "178.380000000000000000", "status": "EXECUTED" },
    { "accountId": "…mercatto…", "amount": "19.820000000000000000", "status": "EXECUTED" }
  ]
}

O que aconteceu por baixo dos panos​

executeSettlement sozinho não movimenta dinheiro e não registra Ledger Entries — sob SelfCustody (DEC-037, o único modelo real de custódia hoje), ele monta um SigningRequest verdadeiro: uma execution leg por beneficiário (Bob, a própria comissão da Mercatto) mais uma leg para a Platform Fee em si, cada uma endereçada usando a ExecutionDestination registrada lá em Seller onboarding — a origem sendo o endereço que efetivamente retém o depósito confirmado de Alice. executeSettlement retorna imediatamente com o Settlement em Executing e signingRequestId preenchido; nada está finalizado ainda.

completeSelfCustodySettlement (examples/marketplace-mercatto/self-custody-settlement.ts) é quem de fato termina o trabalho: busca o SigningRequest, assina cada leg localmente com a própria execution wallet da Mercatto (registrada em Seller onboarding; a chave privada nunca sai desse processo), envia cada assinatura, e — assim que o gate de todas-as-assinaturas da plataforma transmite cada leg — espera cada uma confirmar (Sandbox: simulado, sandbox.simulateBroadcastConfirmation; uma rede real em Production). Só depois que toda leg confirma é que a Ishtaran registra os Ledger Entries e move o Settlement para Completed. "Liquidado" nunca significa "Ledger atualizado" sob SelfCustody — significa que a transferência real foi confirmada. Um Settlement sem nada a executar on-chain (todo beneficiário retido, Fee zero) pula a assinatura inteiramente: signingRequestId é simplesmente null, e completeSelfCustodySettlement resolve na hora.

O percentual da Fee não está hardcoded em lugar nenhum deste exemplo: não existe rota pública para ler a Pricing Policy de antemão (Known Limitations §F.3), então a Mercatto lê o valor de volta a partir do próprio resultado do Settlement, do mesmo jeito que qualquer integrador precisa fazer hoje.

Transmitir essas legs custa recursos de rede reais (Energy/Bandwidth da TRON) — alguém precisa pagar por isso, separadamente da Platform Fee. Logo depois de fazer o onboarding de Bob e Alice (examples/marketplace-mercatto/register-network-cost-payer-account.ts), a Mercatto registra a própria Account de receita como o NetworkCostPayerAccount para este AssetNetwork — uma decisão de negócio real (o custo de rede sai da própria comissão da Mercatto), não um detalhe técnico. Sem isso, esta mesma chamada falharia com 422 antes mesmo de montar um SigningRequest: sob SelfCustody, executeSettlement resolve um NetworkCostPayerAccount e reserva o custo de rede real, cotado (usando o mesmo Network Execution Engine que Withdrawals usa — veja Withdrawal) antes de movimentar o dinheiro de qualquer beneficiário. Esse custo reservado nunca aparece em grossAmount/platformFeeAmount/splitAllocations acima — é uma reserva de Ledger separada contra a própria Account de comissão da Mercatto, liquidada assim que cada leg confirma.

A Account de um beneficiário nem sempre está pronta para receber. Se a Account de Bob estivesse congelada exatamente nesse momento, a alocação dele seria RETAINED em vez de EXECUTED — nenhuma execution leg é construída para uma alocação retida, e o resto do Settlement ainda assim completa normalmente. Veja Failure scenarios para esse caso exato, trabalhado com números reais.

O Settlement não precisa acontecer tudo de uma vez — veja Partial Settlement.