Commissioni TRC20: TronFuel e Paymaster

Il problema: i token senza TRX non si possono muovere

Un transfer TRC20 è una chiamata a uno smart contract. TRON addebita energy e bandwidth per essa, e un indirizzo paga per queste risorse bruciando TRX oppure usando risorse che ha in staking o che gli sono state delegate. Il token in sé non paga mai.

Questo produce una situazione in cui ogni integrazione TRON s’imbatte prima o poi. Un cliente deposita USDT su un indirizzo appena creato. L’indirizzo ora possiede token e nient’altro. Inviare quei token a sua volta fallisce con status 422 e il messaggio balance is not sufficient, perché non c’è TRX per coprire il costo delle risorse. Finanziare in anticipo ogni indirizzo di deposito con TRX funziona, ma immobilizza TRX in indirizzi che potrebbero non essere mai usati.

Sponsorizzare la commissione risolve il problema dall’altro lato. Una terza parte paga il costo delle risorse, e il wallet invia i propri token senza mai possedere TRX.

TronFuel è il modo consigliato

TronFuel è ciò che consigliamo oggi per questo scopo. Noleggia energy all’ingrosso dagli staker invece di bruciare TRX, ed è da lì che viene il risparmio rispetto a un burning semplice. Il contesto è approfondito in Save Up to 60% on TRON TRC-20 Transaction Fees.

TronFuel è un servizio separato. Non ha alcun endpoint dentro l’API Chaingateway, quindi nulla in questa documentazione descrive come chiamarlo. Segui il link sopra per la sua documentazione.

Il Paymaster è deprecato

Il Paymaster di Chaingateway svolgeva lo stesso compito dentro l’API: copriva bandwidth ed energy così un wallet non aveva bisogno di TRX prima di inviare token TRC20, e addebitava il costo su un saldo di credito del tuo account.

Il servizio è deprecato. Le integrazioni che già chiamano gli endpoint Paymaster continuano a funzionare, e gli endpoint sono documentati qui sotto per questo motivo. Non costruire nuove integrazioni su di essi.

Endpoint	Scopo
POST /v2/tron/paymaster	Crea una richiesta di transazione sponsorizzata
GET /v2/tron/paymaster	Elenca le tue richieste e il loro stato
GET /v2/tron/paymaster/{id}	Legge una richiesta
POST /v2/tron/paymaster/estimate	Stima energy, bandwidth e commissione
GET /v2/tron/paymaster/balance	Legge il saldo di credito residuo

Stimare prima il costo

Quanta energy e bandwidth servono a una transazione dipende dal tipo di transazione e dal contratto che chiama, quindi l’importo non è fisso. POST /v2/tron/paymaster/estimate accetta lo stesso corpo della richiesta vera e propria e restituisce quanto costerebbe la transazione.

curl --request POST\
  --url https://api.chaingateway.io/v2/tron/paymaster/estimate\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: YOUR_API_TOKEN'\
  --data '{
    "type": "TRC20",
    "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": "1"
}'

{
  "status": 200,
  "ok": true,
  "message": "Successfully estimated the fees",
  "data": {
    "energy_consumption": 32000,
    "bandwidth_consumption": 368,
    "paymaster_fee": 0.15
  }
}

La commissione viene dedotta dal saldo di credito una volta che la richiesta si conclude. Un saldo che non la copre fa fallire la richiesta. GET /v2/tron/paymaster/balance restituisce quanto rimane.

Creare una richiesta sponsorizzata

type accetta TRX, TRC10, TRC20 e TRC721. Insieme a from, to e amount è obbligatorio. Per TRC20 e TRC721 passi anche contractaddress, per TRC721 e TRC10 il tokenid. La firma funziona come nel resto dell’API: password per un indirizzo Chaingateway protetto da password, privatekey altrimenti. Un callback_url opzionale riceve il risultato.

curl --request POST\
  --url https://api.chaingateway.io/v2/tron/paymaster\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: YOUR_API_TOKEN'\
  --data '{
    "type": "TRC20",
    "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": "1",
    "password": "test123",
    "callback_url": "https://example.com/callback"
}'

La risposta non è un hash di transazione ma l’id della richiesta:

{
  "status": 200,
  "ok": true,
  "message": "Successfully created paymaster request",
  "data": {
    "id": "9c72d676-8180-4cd2-a406-f0f1cd097506"
  }
}

Seguire una richiesta

Interroga GET /v2/tron/paymaster/{id} con quell’id, oppure elenca tutte le richieste con GET /v2/tron/paymaster. Il campo status passa per pending mentre la richiesta è in attesa, processing mentre la transazione è in corso, e completed una volta conclusa. Un fallimento si legge come failed - [reason], con il motivo indicato dopo il trattino. L’hash della transazione risultante compare nel record una volta completata la transazione.

{
  "id": "9cfbfcaf-68b2-47e9-bf55-5b6b4875e84d",
  "type": "TRC20",
  "from": "THG9nncwASg3ub5rvVquocAHwwQbnKZxpH",
  "to": "TPUjdnMrS7XDUFp5W6zgh4QDCW34nXa2x1",
  "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "amount": "200",
  "token_id": null,
  "transaction_hash": "80a223e0cb20ef692fbd23d3cbaf3cc1dfa2b9667aaef70c7da8ca8f707ec28b",
  "status": "success",
  "used_credits": "2.178413",
  "callback_url": "https://api.chaingateway.io/receiver/webhooks/tron",
  "created_at": "2024-09-11T15:28:57.000000Z"
}

Lo staking come terza opzione

Se il TRX è comunque tuo, puoi metterlo in staking una volta e riutilizzare le risorse invece di pagare per ogni transazione. POST /v2/tron/freeze mette in staking TRX per energy o bandwidth, POST /v2/tron/delegate consegna quelle risorse a un altro indirizzo, e POST /v2/tron/undelegate e POST /v2/tron/unfreeze invertono entrambi i passaggi. Un singolo indirizzo in staking può rifornire gli indirizzi di deposito dietro di esso, il che è lo schema adatto a un flusso di pagamento con molti indirizzi riceventi.

L’invio del transfer vero e proprio è trattato in Creare transazioni di token TRC20.