Sponsorizzare commissioni TRC20: TronFuel
Sponsorizzare la commissione significa che una terza parte paga energy e bandwidth consumati da una transazione TRON, così il wallet mittente non ha bisogno di TRX. Consigliamo TronFuel per questo scopo. Il Paymaster di Chaingateway svolgeva lo stesso compito dentro l’API ed è deprecato: le integrazioni esistenti continuano a funzionare, ma le nuove non dovrebbero usarlo.
Perché un wallet TRON con token ma senza TRX non può inviarli?
Sezione intitolata “Perché un wallet TRON con token ma senza TRX non può inviarli?”Un trasferimento TRC20 è una chiamata a uno smart contract. TRON addebita energy e bandwidth per essa, e un indirizzo paga quelle risorse bruciando TRX oppure usando risorse di cui ha fatto staking o che gli sono state delegate. Il token stesso non paga mai.
Ne nasce una situazione in cui ogni integrazione TRON prima o poi si imbatte. Un cliente deposita USDT in un indirizzo appena creato. L’indirizzo contiene ora token e nient’altro. L’invio successivo di quei token fallisce con status 422 e il messaggio balance is not sufficient, perché non c’è TRX per coprire il costo delle risorse. Accreditare TRX su ogni indirizzo di deposito in anticipo funziona, ma vincola TRX in indirizzi che forse non verranno mai usati.
La sponsorizzazione della commissione risolve il problema dall’altro lato. Una terza parte paga il costo delle risorse, e il wallet invia i suoi token senza mai possedere TRX.
Cosa devo usare al posto del Paymaster?
Sezione intitolata “Cosa devo usare al posto del Paymaster?”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 Commissioni di transazione TRC-20 su TRON spiegate.
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 è ancora disponibile?
Sezione intitolata “Il Paymaster è ancora disponibile?”Il Paymaster di Chaingateway svolgeva lo stesso compito dentro l’API: copriva bandwidth ed energy in modo che un wallet non avesse 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 chiamano già gli endpoint Paymaster continuano a funzionare, e per questo gli endpoint sono documentati qui sotto. Non costruire nuove integrazioni su di essi.
| Endpoint | Scopo |
|---|---|
POST /api/v2/tron/paymaster | Creare una richiesta di transazione sponsorizzata |
GET /api/v2/tron/paymaster | Elencare le tue richieste e il loro stato |
GET /api/v2/tron/paymaster/{id} | Leggere una richiesta |
POST /api/v2/tron/paymaster/estimate | Stimare energy, bandwidth e commissione |
GET /api/v2/tron/paymaster/balance | Leggere il saldo di credito rimanente |
Stimare prima il costo
Sezione intitolata “Stimare prima il costo”La quantità di energy e bandwidth necessaria a una transazione dipende dal tipo di transazione e dal contratto che chiama, quindi non è fissa. POST /api/v2/tron/paymaster/estimate accetta lo stesso corpo della richiesta vera e propria e restituisce quanto costerebbe la transazione.
curl --request POST\ --url https://app.chaingateway.io/api/v2/tron/paymaster/estimate\ --header 'Accept: application/json'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer 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 detratta dal saldo di credito quando la richiesta si conclude. Un saldo che non la copre fa fallire la richiesta. GET /api/v2/tron/paymaster/balance restituisce ciò che resta.
Creare una richiesta sponsorizzata
Sezione intitolata “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 altrove nell’API: password per un indirizzo Chaingateway protetto da password, altrimenti privatekey. Un callback_url facoltativo riceve il risultato.
curl --request POST\ --url https://app.chaingateway.io/api/v2/tron/paymaster\ --header 'Accept: application/json'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer 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
Sezione intitolata “Seguire una richiesta”Interroga GET /api/v2/tron/paymaster/{id} con quell’ID, oppure elenca tutte le richieste con GET /api/v2/tron/paymaster. Il campo status passa per pending mentre la richiesta attende, processing mentre la transazione è in corso e completed quando si è conclusa. Un fallimento si legge failed - [reason], con il motivo scritto dopo il trattino. L’hash della transazione risultante compare nel record quando la transazione è completata.
{ "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"}Posso fare staking di TRX invece di pagare per ogni transazione?
Sezione intitolata “Posso fare staking di TRX invece di pagare per ogni transazione?”Se i TRX sono comunque tuoi, puoi farne staking una volta e riutilizzare le risorse invece di pagare per ogni transazione. POST /api/v2/tron/freeze blocca TRX in staking per energy o bandwidth, POST /api/v2/tron/delegate cede quelle risorse a un altro indirizzo, e POST /api/v2/tron/undelegate e POST /api/v2/tron/unfreeze annullano entrambi i passaggi. Un singolo indirizzo in staking può rifornire gli indirizzi di deposito che dipendono da esso, lo schema adatto a un flusso di pagamento con molti indirizzi riceventi.
I quattro endpoint di staking condividono la stessa forma del corpo. I campi address, amount e resource sono obbligatori, e resource è BANDWIDTH o ENERGY. delegate e undelegate aggiungono un receiver obbligatorio. Come in tutta l’API, firmi con password o privatekey.
curl --request POST\ --url https://app.chaingateway.io/api/v2/tron/freeze\ --header 'Accept: application/json'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer YOUR_API_TOKEN'\ --data '{ "address": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH", "amount": 100, "resource": "ENERGY", "password": "test123"}'Una chiamata riuscita restituisce data.result: true e il txid della transazione di staking. Per la delega valgono due regole del file OpenAPI: il saldo deve essere bloccato prima di poter essere delegato, e il ricevente deve essere diverso dall’indirizzo del proprietario. Una chiamata fallita restituisce lo status 422 con il messaggio del nodo, ad esempio no frozenBalance(Energy) quando sblocchi più di quanto hai messo in staking, oppure delegated Resource does not exist quando annulli la delega di qualcosa che non è mai stato delegato. Il modello di risorse di TRON documenta come i TRX in staking diventano energy e bandwidth.
Quale opzione si adatta alla mia integrazione?
Sezione intitolata “Quale opzione si adatta alla mia integrazione?”La tabella confronta le opzioni per ciò che richiedono e per quanto costano.
| Opzione | Cosa serve | Modello di costo | Stato |
|---|---|---|---|
| Accreditare TRX su ogni indirizzo | TRX in ogni indirizzo di deposito | i TRX vengono bruciati a ogni transazione | funziona, vincola TRX |
| TronFuel | il servizio TronFuel separato, fuori dall’API Chaingateway | l’energy viene noleggiata invece di bruciare TRX | consigliato |
| Staking e delega | TRX che puoi bloccare | i TRX in staking forniscono le risorse invece di essere bruciati | funziona |
| Paymaster | saldo di credito sul tuo account Chaingateway | commissione detratta dal saldo di credito | deprecato |
Controlla il saldo TRX di un indirizzo con GET /api/v2/tron/balances/{address} prima di inviare. Un indirizzo senza TRX e senza risorse delegate fallisce con il messaggio balance is not sufficient visto sopra.
L’invio del trasferimento vero e proprio è descritto in Creare transazioni di token TRC20.
- TRON resource model definisce energy, bandwidth, staking e delega.
- TRC20 protocol interface descrive le funzioni del contratto che un trasferimento chiama.