CLDF Tron Package (#219)

**This PR adds support for the Tron blockchain to the Chainlink
Deployments Framework.**

## Key changes:

- Introduces a new `chain/tron` module with implementation and
integration for Tron chains.
- Adds Tron-specific keystore logic (`chain/tron/keystore`) for account
management and signing.
- Provides utilities for Tron account generation
(`chain/tron/provider/account_generator.go`) supporting default
generator for CTF, random and private-key-based creation.
- Implements a Tron RPC provider (`chain/tron/provider/rpc_provider.go`)
to interact with Tron nodes, including support for deploying and
triggering smart contracts.
- Implements a Tron CTF provider (`chain/tron/provider/ctf_provider.go`)
to interact with Tron nodes in testing environment, including support
for deploying and triggering smart contracts.
- Adds a Tron RPC client wrapper
(`chain/tron/provider/rpcclient/client.go`) with transaction signing,
broadcasting, and confirmation logic.
- Updates core chain management (`chain/blockchain.go`) and tests to
include Tron chains, selectors, and filtering.
- Adds comprehensive unit and integration tests for all new Tron-related
modules.
- Updates dependencies and adds `go.mod`/`go.sum` entries for Tron SDKs
and required packages.
- Use CTF to support running local Tron test nodes for integration
testing.

## Purpose:

This enables CLD to deploy, manage, and interact with smart contracts on
the Tron blockchain in the same unified way as other supported chains
(EVM, Solana, Aptos, Sui, TON).

---------

Co-authored-by: Graham Goh <graham.goh@smartcontract.com>

Author: eduard-cl

.changeset/proud-eagles-see.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+feat: introduce tron chain provider and ctf provider

.gitignore

@@ -33,3 +33,6 @@ node_modules/
 
 # OS generated files
 .DS_Store
+
+# Tron wallet folder generated
+*/tron/provider/wallet/

chain/blockchain.go

@@ -11,13 +11,15 @@ import (
 	"github.com/smartcontractkit/chainlink-deployments-framework/chain/solana"
 	"github.com/smartcontractkit/chainlink-deployments-framework/chain/sui"
 	"github.com/smartcontractkit/chainlink-deployments-framework/chain/ton"
+	"github.com/smartcontractkit/chainlink-deployments-framework/chain/tron"
 )
 
 var _ BlockChain = evm.Chain{}
 var _ BlockChain = solana.Chain{}
 var _ BlockChain = aptos.Chain{}
 var _ BlockChain = sui.Chain{}
 var _ BlockChain = ton.Chain{}
+var _ BlockChain = tron.Chain{}
 
 // BlockChain is an interface that represents a chain.
 // A chain can be an EVM chain, Solana chain Aptos chain or others.
@@ -116,6 +118,11 @@ func (b BlockChains) TonChains() map[uint64]ton.Chain {
 	return getChainsByType[ton.Chain, *ton.Chain](b)
 }
 
+// TronChains returns a map of all Tron chains with their selectors.
+func (b BlockChains) TronChains() map[uint64]tron.Chain {
+	return getChainsByType[tron.Chain, *tron.Chain](b)
+}
+
 // ChainSelectorsOption defines a function type for configuring ChainSelectors
 type ChainSelectorsOption func(*chainSelectorsOptions)
 

chain/blockchain_test.go

@@ -15,6 +15,7 @@ import (
 	"github.com/smartcontractkit/chainlink-deployments-framework/chain/solana"
 	"github.com/smartcontractkit/chainlink-deployments-framework/chain/sui"
 	"github.com/smartcontractkit/chainlink-deployments-framework/chain/ton"
+	"github.com/smartcontractkit/chainlink-deployments-framework/chain/tron"
 )
 
 var evmChain1 = evm.Chain{Selector: chain_selectors.TEST_90000001.Selector}
@@ -23,6 +24,7 @@ var solanaChain1 = solana.Chain{Selector: chain_selectors.TEST_22222222222222222
 var aptosChain1 = aptos.Chain{Selector: chain_selectors.APTOS_LOCALNET.Selector}
 var suiChain1 = sui.Chain{ChainMetadata: sui.ChainMetadata{Selector: chain_selectors.SUI_LOCALNET.Selector}}
 var tonChain1 = ton.Chain{ChainMetadata: ton.ChainMetadata{Selector: chain_selectors.TON_LOCALNET.Selector}}
+var tronChain1 = tron.Chain{ChainMetadata: tron.ChainMetadata{Selector: chain_selectors.TRON_MAINNET.Selector}}
 
 func TestNewBlockChains(t *testing.T) {
 	t.Parallel()
@@ -145,6 +147,7 @@ func TestBlockChainsAllChains(t *testing.T) {
 		evmChain1.Selector, evmChain2.Selector,
 		solanaChain1.Selector, aptosChain1.Selector,
 		suiChain1.Selector, tonChain1.Selector,
+		tronChain1.Selector,
 	}
 
 	assert.Len(t, allChains, len(expectedSelectors))
@@ -246,6 +249,22 @@ func TestBlockChainsGetters(t *testing.T) {
 			},
 			description: "should return all Ton chains",
 		},
+		{
+			name: "TronChains",
+			runTest: func(t *testing.T, chains chain.BlockChains) {
+				t.Helper()
+				tronChains := chains.TronChains()
+				expectedSelectors := []uint64{tronChain1.Selector}
+
+				assert.Len(t, tronChains, len(expectedSelectors), "unexpected number of Tron chains")
+
+				for _, selector := range expectedSelectors {
+					_, exists := tronChains[selector]
+					assert.True(t, exists, "expected Tron chain with selector %d", selector)
+				}
+			},
+			description: "should return all Tron chains",
+		},
 	}
 
 	// Run tests for both value and pointer chains
@@ -285,6 +304,7 @@ func TestBlockChainsListChainSelectors(t *testing.T) {
 				evmChain1.ChainSelector(), evmChain2.ChainSelector(),
 				solanaChain1.ChainSelector(), aptosChain1.ChainSelector(),
 				suiChain1.ChainSelector(), tonChain1.ChainSelector(),
+				tronChain1.ChainSelector(),
 			},
 			description: "expected all chain selectors",
 		},
@@ -318,6 +338,12 @@ func TestBlockChainsListChainSelectors(t *testing.T) {
 			expectedIDs: []uint64{tonChain1.Selector},
 			description: "expected Ton chain selectors",
 		},
+		{
+			name:        "with family filter - Tron",
+			options:     []chain.ChainSelectorsOption{chain.WithFamily(chain_selectors.FamilyTron)},
+			expectedIDs: []uint64{tronChain1.Selector},
+			description: "expected Tron chain selectors",
+		},
 		{
 			name:        "with multiple families",
 			options:     []chain.ChainSelectorsOption{chain.WithFamily(chain_selectors.FamilyEVM), chain.WithFamily(chain_selectors.FamilySolana)},
@@ -329,7 +355,7 @@ func TestBlockChainsListChainSelectors(t *testing.T) {
 			options: []chain.ChainSelectorsOption{chain.WithChainSelectorsExclusion(
 				[]uint64{evmChain1.Selector, aptosChain1.Selector}),
 			},
-			expectedIDs: []uint64{evmChain2.Selector, solanaChain1.Selector, suiChain1.Selector, tonChain1.Selector},
+			expectedIDs: []uint64{evmChain2.Selector, solanaChain1.Selector, suiChain1.Selector, tonChain1.Selector, tronChain1.Selector},
 			description: "expected chain selectors excluding 1 and 4",
 		},
 		{
@@ -354,7 +380,7 @@ func TestBlockChainsListChainSelectors(t *testing.T) {
 }
 
 // buildBlockChains creates a new BlockChains instance with the test chains.
-// 2 evm chains, 1 solana chain, 1 aptos chain, 1 sui chain, 1 ton chain.
+// 2 evm chains, 1 solana chain, 1 aptos chain, 1 sui chain, 1 ton chain, 1 tron chain.
 func buildBlockChains() chain.BlockChains {
 	chains := chain.NewBlockChains(map[uint64]chain.BlockChain{
 		evmChain1.ChainSelector():    evmChain1,
@@ -363,6 +389,7 @@ func buildBlockChains() chain.BlockChains {
 		aptosChain1.ChainSelector():  aptosChain1,
 		suiChain1.ChainSelector():    suiChain1,
 		tonChain1.ChainSelector():    tonChain1,
+		tronChain1.ChainSelector():   tronChain1,
 	})
 
 	return chains
@@ -384,6 +411,8 @@ func buildBlockChainsPointers() chain.BlockChains {
 			pointerChains[selector] = &c
 		case ton.Chain:
 			pointerChains[selector] = &c
+		case tron.Chain:
+			pointerChains[selector] = &c
 		default:
 			continue // skip unsupported chains
 		}

chain/tron/keystore/keystore.go

@@ -0,0 +1,69 @@
+package keystore
+
+import (
+	"context"
+	"crypto/ecdsa"
+	"errors"
+
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/fbsobreira/gotron-sdk/pkg/address"
+	"github.com/smartcontractkit/chainlink-common/pkg/loop"
+)
+
+// Keystore is a simple in-memory key store that holds private keys for signing.
+// The `Keys` map holds:
+//   - key (string): the string representation of a Tron address
+//   - value (*ecdsa.PrivateKey): the private key associated with that address
+type Keystore struct {
+	Keys map[string]*ecdsa.PrivateKey
+}
+
+// Assert that *Keystore implements the loop.Keystore interface
+var _ loop.Keystore = &Keystore{}
+
+// NewKeystore initializes a new Keystore with a single ECDSA private key.
+// The key is stored using the derived Tron address as the map key.
+func NewKeystore(privateKey *ecdsa.PrivateKey) (*Keystore, address.Address) {
+	keys := map[string]*ecdsa.PrivateKey{}
+	address := address.PubkeyToAddress(privateKey.PublicKey)
+
+	keys[address.String()] = privateKey
+
+	return &Keystore{Keys: keys}, address
+}
+
+// Sign signs the given hash using the private key associated with the provided ID (address string).
+// If the key does not exist, it returns an error.
+// If the hash is nil (e.g., used as an existence check), it returns nil.
+func (ks *Keystore) Sign(ctx context.Context, id string, hash []byte) ([]byte, error) {
+	privateKey, ok := ks.Keys[id]
+	if !ok {
+		return nil, errors.New("no such key")
+	}
+
+	// If hash is nil, don't perform actual signing. This is used to check key existence.
+	if hash == nil {
+		return nil, nil
+	}
+
+	return crypto.Sign(hash, privateKey)
+}
+
+// ImportECDSA adds a new private key to the Keystore, deriving its Tron address
+// and storing it using that address as the map key.
+func (ks *Keystore) ImportECDSA(privateKey *ecdsa.PrivateKey) address.Address {
+	address := address.PubkeyToAddress(privateKey.PublicKey)
+	ks.Keys[address.String()] = privateKey
+
+	return address
+}
+
+// Accounts returns a list of all address strings currently stored in the Keystore.
+func (ks *Keystore) Accounts(ctx context.Context) ([]string, error) {
+	accounts := make([]string, 0, len(ks.Keys))
+	for id := range ks.Keys {
+		accounts = append(accounts, id)
+	}
+
+	return accounts, nil
+}

chain/tron/keystore/keystore_test.go

@@ -0,0 +1,103 @@
+package keystore
+
+import (
+	"context"
+	"crypto/ecdsa"
+	"testing"
+
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/fbsobreira/gotron-sdk/pkg/address"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func generateKeyPair(t *testing.T) *ecdsa.PrivateKey {
+	t.Helper()
+	key, err := crypto.GenerateKey()
+	require.NoError(t, err)
+
+	return key
+}
+
+func Test_NewKeystore(t *testing.T) {
+	t.Parallel()
+
+	privKey := generateKeyPair(t)
+	ks, addr := NewKeystore(privKey)
+
+	expectedAddr := address.PubkeyToAddress(privKey.PublicKey)
+	require.Contains(t, ks.Keys, expectedAddr.String())
+	assert.Equal(t, privKey, ks.Keys[expectedAddr.String()])
+	assert.Equal(t, expectedAddr, addr)
+}
+
+func Test_Keystore_ImportECDSA(t *testing.T) {
+	t.Parallel()
+
+	ks := &Keystore{Keys: make(map[string]*ecdsa.PrivateKey)}
+	privKey := generateKeyPair(t)
+
+	addr := ks.ImportECDSA(privKey)
+	assert.Equal(t, address.PubkeyToAddress(privKey.PublicKey), addr)
+	assert.Equal(t, privKey, ks.Keys[addr.String()])
+}
+
+func Test_Keystore_Sign(t *testing.T) {
+	t.Parallel()
+
+	privKey := generateKeyPair(t)
+	addrStr := address.PubkeyToAddress(privKey.PublicKey).String()
+
+	ks := &Keystore{
+		Keys: map[string]*ecdsa.PrivateKey{
+			addrStr: privKey,
+		},
+	}
+
+	t.Run("successful sign", func(t *testing.T) {
+		t.Parallel()
+
+		hash := crypto.Keccak256([]byte("test data"))
+
+		sig, err := ks.Sign(context.Background(), addrStr, hash)
+		require.NoError(t, err)
+		require.Len(t, sig, 65) // ECDSA signature length
+	})
+
+	t.Run("key not found", func(t *testing.T) {
+		t.Parallel()
+
+		_, err := ks.Sign(context.Background(), "invalid_address", []byte("hash"))
+		require.Error(t, err)
+		assert.EqualError(t, err, "no such key")
+	})
+
+	t.Run("nil hash returns nil without error", func(t *testing.T) {
+		t.Parallel()
+
+		sig, err := ks.Sign(context.Background(), addrStr, nil)
+		require.NoError(t, err)
+		assert.Nil(t, sig)
+	})
+}
+
+func Test_Keystore_Accounts(t *testing.T) {
+	t.Parallel()
+
+	priv1 := generateKeyPair(t)
+	priv2 := generateKeyPair(t)
+
+	addr1 := address.PubkeyToAddress(priv1.PublicKey).String()
+	addr2 := address.PubkeyToAddress(priv2.PublicKey).String()
+
+	ks := &Keystore{
+		Keys: map[string]*ecdsa.PrivateKey{
+			addr1: priv1,
+			addr2: priv2,
+		},
+	}
+
+	accounts, err := ks.Accounts(context.Background())
+	require.NoError(t, err)
+	assert.ElementsMatch(t, []string{addr1, addr2}, accounts)
+}