Pular para o conteúdo principal

Transaction, Settlement, Split e Refund

Transaction​

Uma Transaction representa um acordo financeiro entre duas ou mais Accounts — um processo, não um movimento direto de dinheiro. Ela orquestra os Participants (Accounts com um papel específico, como "comprador" ou "vendedor"), segue uma Workflow Version, e eventualmente resulta em um Settlement.

Settlement não é Payout — leia isto antes de assumir que o dinheiro se move imediatamente​

Settlement nunca "envia fundos" por conta própria. O que executeSettlement() genuinamente faz, sempre, independente da política: calcula o Fee, aplica o Split, e transforma a parte de cada Participant em uma obrigação econômica real — um Payable/Receivable devido a esse beneficiário. Se essa obrigação é paga imediatamente ou mais tarde é uma decisão completamente separada, controlada pela PayoutPolicy:

  • Sob PayoutPolicy.Immediate (o caso comum, e o que todo exemplo funcional deste site usa) — o próprio Settlement dispara a execução real no mesmo momento: sob Self-Custody, isso significa construir um SigningRequest e uma ExecutionLeg por beneficiário (ver Self-Custody), nunca um crédito direto no Ledger.
  • Sob PayoutPolicy.Threshold/Scheduled/Manual — a parte do beneficiário se torna um Payable (um saldo acumulado, devido mas ainda não pago, consultável via getPayableSummary) e só é efetivamente pago mais tarde, quando um PayoutBatch executa. Um PayoutBatch só pode ser criado com trigger = Manual através da API pública hoje — ThresholdCrossed e Scheduled existem no modelo de domínio mas não têm rota pública para disparo ainda; não construa uma integração que assuma que qualquer um dos dois esteja disponível.

Um Payable (o que um beneficiário tem a receber) nunca é a mesma coisa que um saldo on-chain. Sob Self-Custody, uma vez que a ExecutionLeg de um beneficiário confirma, o dinheiro genuinamente saiu da custódia da plataforma — enviado ao ExecutionDestination próprio e registrado desse beneficiário, um endereço totalmente fora do Ishtaran. Não sobra nada no Ledger para manter como saldo Available desse beneficiário; a plataforma registra, em vez disso, Delivered, o histórico acumulado do que foi de fato pago (getPayableSummary().paid), nunca confundido com um saldo disponível no Ledger.

Transmitir (broadcast) a ExecutionLeg de um beneficiário — ou a própria leg do Platform Fee — custa recursos de rede reais (ex.: Energy/Bandwidth da TRON). Esse custo é cobrado separadamente do Platform Fee, de uma NetworkCostPayerAccount registrada uma vez por Organization/AssetNetwork (ver Self-Custody) — sem uma, o primeiro Settlement real com algo a pagar falha antes mesmo de construir um SigningRequest. Platform Fee e Network Execution Fee são dois números diferentes, rastreados de forma independente — nunca assuma que o Fee mostrado em um Settlement já inclui o custo de rede, e nunca assuma que o custo de rede é fixo (ele é cotado na hora, a cada broadcast). Veja Network Execution para quem de fato fornece esse recurso (CUSTOMER_RESOURCES vs ISHTARAN_RESOURCES) e como financiá-lo pela primeira vez.

Partial Settlement​

Um Partial Settlement libera apenas parte do valor reservado de uma Transaction em uma chamada, mantendo o restante reservado para uma chamada posterior. Todo Settlement é balanceado no Ledger — a soma distribuída nunca excede o saldo reservado para aquela chamada, e chamá-lo repetidamente na mesma Transaction reconcilia exatamente para os mesmos totais de uma única chamada pelo valor total.

Split​

O Split define como um valor é distribuído entre múltiplos Participants no momento do Settlement — percentuais ou valores fixos, nunca somando mais que o total liquidado.

Fee e Pricing Policy​

O Platform Fee é o valor cobrado pela plataforma sobre um Settlement, calculado conforme a Pricing Policy configurada para a Organization/Application. O Fee da própria plataforma segue o mesmo modelo de domínio dos clientes — nenhum caminho financeiro especial. Isso é distinto do Network Execution Fee descrito acima — nunca o mesmo número, nunca derivado um do outro.

Refund e Reversal​

Um Refund devolve, total ou parcialmente, um valor já liquidado ou reservado a um Participant de origem — uma reversão econômica dentro do Ledger (um novo lançamento compensatório, via Reversal; um lançamento nunca é apagado). Um Refund não "desfaz", e não consegue desfazer, uma transação que já confirmou on-chain — não existe tal mecanismo, em nenhuma blockchain. O que o Refund de fato reverte é a própria contabilidade econômica da plataforma sobre quem deve o quê.

Workflow é opcional​

O próprio Settlement não tem dependência técnica do estado do Workflow — executeSettlement() verifica apenas o status da própria Transaction (Reserved/PartiallySettled), nunca uma Rule ou Transition de Workflow. Um Workflow é uma forma genuinamente opcional de modelar o ciclo de vida do seu próprio produto (ver Workflows) e orquestrar quando você decide chamar executeSettlement() — nunca um gate imposto pela própria plataforma.

Rotas​