Pular para o conteúdo principal

Network Execution

Todo broadcast on-chain real sob Self-Custody — os ExecutionLegs de um Settlement, um Withdrawal, ou um PayoutBatch — consome recursos de rede reais (ex.: Energy/Bandwidth da TRON). Esse custo é rastreado e cobrado de forma completamente separada do Platform Fee: o Platform Fee é a taxa comercial da própria plataforma sobre um Settlement (ver Fee e Pricing Policy); o Network Execution Fee é o que de fato custa colocar bytes em broadcast on-chain. Nunca assuma que um número inclui o outro.

Duas fontes para o recurso: CUSTOMER_RESOURCES vs ISHTARAN_RESOURCES​

Toda Organization tem uma resourcePreference por AssetNetwork, controlando quem de fato paga os recursos on-chain de um broadcast:

ISHTARAN_RESOURCES (o padrão)​

A plataforma fornece o recurso de rede físico para você. Você cobre o custo economicamente — o que é cobrado (totalCharged, em quoteCurrency) pode incluir, além do custo de rede bruto, um componente de reposição/aquisição e o margin da própria Ishtaran (a margem por patrocinar o recurso). NetworkExecutionFee não é um pass-through puro neste modo — não assuma que o valor cobrado é igual ao custo de rede bruto.

CUSTOMER_RESOURCES (SELF)​

Você fornece seus próprios recursos on-chain. Neste modo:

  • O margin da Ishtaran é sempre 0.
  • Não há componente de reposição/swap cobrado pela Ishtaran.
  • Se seus recursos registrados forem insuficientes para uma execução, ela falha fechada — não há fallback silencioso para ISHTARAN_RESOURCES, a menos que você tenha optado explicitamente por allowFallbackToIshtaranResources ao configurar a preferência (ver abaixo).

Alternar entre os dois, e controlar o fallback, é uma única chamada: networkCostPayerAccounts.updateResourcePreference(organizationId, assetNetworkId, resourcePreference, allowFallbackToIshtaranResources) — veja o CORE_API.md § Network Execution Engine de cada SDK para a assinatura exata.

Dois registros, duas coisas diferentes​

Fazer a execução Self-Custody funcionar pela primeira vez exige dois registros separados, fáceis de confundir porque ambos envolvem "pagar pelo custo de rede":

  • ExecutionSource — o endereço a partir do qual ExecutionCustody assina para pagar o custo de rede, e (no modo CUSTOMER_RESOURCES) o endereço cuja capacidade de recurso on-chain é checada. Registrado via executionSources.register(...); sua capacidade disponível é declarada/re-sincronizada via executionSources.syncResourceStake(...) (auto-declarado, sem verificação on-chain nesta versão).
  • NetworkCostPayerAccount — a Account do Ledger debitada pelo custo cobrado (totalCharged, em quoteCurrency) assim que uma cotação é autorizada. Registrado via networkCostPayerAccounts.register(organizationId, assetNetworkId, accountId).

Não confunda nenhum dos dois com ExecutionDestination — um conceito completamente diferente: o endereço no qual um beneficiário recebe fundos (ver Self-Custody).

Também não confunda NetworkCostPayerAccount com a NetworkResourceReserve da própria plataforma: essa é a reserva operacional interna da Ishtaran que sustenta o modo ISHTARAN_RESOURCES — não é algo que você registra, financia ou consulta como integrador, e o modo CUSTOMER_RESOURCES nunca consome dela. Não existe rota pública voltada ao integrador para isso; se você ver rotas /v1/admin/... mencionando-a na referência de API, são operações do Platform Owner, não parte da sua integração.

Primeiro financiamento​

Antes da sua primeira execução real em modo CUSTOMER_RESOURCES (ou antes de sua NetworkCostPayerAccount ter saldo suficiente, em qualquer um dos modos), a plataforma vai recusar executar em vez de falhar no meio de um broadcast: você recebe um erro explícito (NETWORK_EXECUTION_FEE_INSUFFICIENT_BALANCE, ver Errors), nunca um retry silencioso ou um estado parcial.

A correção é sempre a mesma, independentemente do modo: faça um Deposit normal na Account relevante (um depósito on-chain comum, como qualquer outro), espere confirmar, e tente de novo. Não existe um fluxo separado de "recarga" — financiar uma Account usada para custos de Network Execution funciona exatamente como financiar qualquer outra Account na plataforma.

Rotas​