Ton analyzer

.changeset/khaki-geese-poke.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+Adds TON blockchain analyzer support

experimental/analyzer/report_builder.go

@@ -22,34 +22,9 @@ func BuildProposalReport(ctx context.Context, proposalContext ProposalContext, e
 		}
 		chainName, _ := GetChainNameBySelector(chainSel)
 
-		var calls []*DecodedCall
-		switch family {
-		case chainsel.FamilyEVM:
-			dec, err := AnalyzeEVMTransactions(ctx, proposalContext, env, chainSel, []types.Transaction{op.Transaction})
-			if err != nil {
-				return nil, err
-			}
-			calls = dec
-		case chainsel.FamilySolana:
-			dec, err := AnalyzeSolanaTransactions(proposalContext, chainSel, []types.Transaction{op.Transaction})
-			if err != nil {
-				return nil, err
-			}
-			calls = dec
-		case chainsel.FamilyAptos:
-			dec, err := AnalyzeAptosTransactions(proposalContext, chainSel, []types.Transaction{op.Transaction})
-			if err != nil {
-				return nil, err
-			}
-			calls = dec
-		case chainsel.FamilySui:
-			dec, err := AnalyzeSuiTransactions(proposalContext, chainSel, []types.Transaction{op.Transaction})
-			if err != nil {
-				return nil, err
-			}
-			calls = dec
-		default:
-			calls = []*DecodedCall{}
+		calls, err := analyzeTransactions(ctx, proposalContext, env, family, chainSel, []types.Transaction{op.Transaction})
+		if err != nil {
+			return nil, err
 		}
 
 		rpt.Operations[i] = OperationReport{
@@ -74,68 +49,22 @@ func BuildTimelockReport(ctx context.Context, proposalCtx ProposalContext, env d
 		}
 		chainName, _ := GetChainNameBySelector(chainSel)
 
+		dec, err := analyzeTransactions(ctx, proposalCtx, env, family, chainSel, batch.Transactions)
+		if err != nil {
+			return nil, err
+		}
+
 		ops := make([]OperationReport, len(batch.Transactions))
-		switch family {
-		case chainsel.FamilyEVM:
-			dec, err := AnalyzeEVMTransactions(ctx, proposalCtx, env, chainSel, batch.Transactions)
-			if err != nil {
-				return nil, err
+		for j := range batch.Transactions {
+			var calls []*DecodedCall
+			if j < len(dec) && dec[j] != nil {
+				calls = []*DecodedCall{dec[j]}
 			}
-			for j := range dec {
-				ops[j] = OperationReport{
-					ChainSelector: chainSel,
-					ChainName:     chainNameOrUnknown(chainName),
-					Family:        family,
-					Calls:         []*DecodedCall{dec[j]},
-				}
-			}
-		case chainsel.FamilySolana:
-			dec, err := AnalyzeSolanaTransactions(proposalCtx, chainSel, batch.Transactions)
-			if err != nil {
-				return nil, err
-			}
-			for j := range dec {
-				ops[j] = OperationReport{
-					ChainSelector: chainSel,
-					ChainName:     chainNameOrUnknown(chainName),
-					Family:        family,
-					Calls:         []*DecodedCall{dec[j]},
-				}
-			}
-		case chainsel.FamilyAptos:
-			dec, err := AnalyzeAptosTransactions(proposalCtx, chainSel, batch.Transactions)
-			if err != nil {
-				return nil, err
-			}
-			for j := range dec {
-				ops[j] = OperationReport{
-					ChainSelector: chainSel,
-					ChainName:     chainNameOrUnknown(chainName),
-					Family:        family,
-					Calls:         []*DecodedCall{dec[j]},
-				}
-			}
-		case chainsel.FamilySui:
-			dec, err := AnalyzeSuiTransactions(proposalCtx, chainSel, batch.Transactions)
-			if err != nil {
-				return nil, err
-			}
-			for j := range dec {
-				ops[j] = OperationReport{
-					ChainSelector: chainSel,
-					ChainName:     chainNameOrUnknown(chainName),
-					Family:        family,
-					Calls:         []*DecodedCall{dec[j]},
-				}
-			}
-		default:
-			for j := range batch.Transactions {
-				ops[j] = OperationReport{
-					ChainSelector: chainSel,
-					ChainName:     chainNameOrUnknown(chainName),
-					Family:        family,
-					Calls:         nil,
-				}
+			ops[j] = OperationReport{
+				ChainSelector: chainSel,
+				ChainName:     chainNameOrUnknown(chainName),
+				Family:        family,
+				Calls:         calls,
 			}
 		}
 
@@ -150,6 +79,24 @@ func BuildTimelockReport(ctx context.Context, proposalCtx ProposalContext, env d
 	return rpt, nil
 }
 
+// analyzeTransactions dispatches to the appropriate chain-family analyzer.
+func analyzeTransactions(ctx context.Context, proposalCtx ProposalContext, env deployment.Environment, family string, chainSel uint64, txs []types.Transaction) ([]*DecodedCall, error) {
+	switch family {
+	case chainsel.FamilyEVM:
+		return AnalyzeEVMTransactions(ctx, proposalCtx, env, chainSel, txs)
+	case chainsel.FamilySolana:
+		return AnalyzeSolanaTransactions(proposalCtx, chainSel, txs)
+	case chainsel.FamilyAptos:
+		return AnalyzeAptosTransactions(proposalCtx, chainSel, txs)
+	case chainsel.FamilySui:
+		return AnalyzeSuiTransactions(proposalCtx, chainSel, txs)
+	case chainsel.FamilyTon:
+		return AnalyzeTONTransactions(proposalCtx, txs)
+	default:
+		return []*DecodedCall{}, nil
+	}
+}
+
 func chainNameOrUnknown(n string) string {
 	if n == "" || strings.TrimSpace(n) == "" {
 		return "<chain unknown>"

experimental/analyzer/report_builder_test.go

@@ -195,6 +195,9 @@ func TestChainNameOrUnknown(t *testing.T) {
 	require.Equal(t, "<chain unknown>", chainNameOrUnknown(" "))
 }
 
+// TestBuildProposalReport_FamilyErrors tests error handling when analyzers fail during
+// preprocessing (e.g., missing registry, invalid AdditionalFields). These are hard errors
+// that prevent the analyzer from proceeding.
 func TestBuildProposalReport_FamilyBranches(t *testing.T) {
 	t.Parallel()
 
@@ -252,6 +255,38 @@ func TestBuildProposalReport_FamilyBranches(t *testing.T) {
 	}
 }
 
+// TestBuildProposalReport_TONDecodeFailure tests TON's graceful decode error handling.
+// Unlike other analyzers, TON doesn't require AdditionalFields for decoding (it only needs
+// tx.Data and tx.ContractType), so it proceeds directly to the decode stage. Decode failures
+// are handled gracefully by placing the error in the Method field rather than returning an error,
+// allowing the proposal to continue processing.
+func TestBuildProposalReport_TONDecodeFailure(t *testing.T) {
+	t.Parallel()
+
+	ctx := &DefaultProposalContext{
+		AddressesByChain: deployment.AddressesByChain{},
+		renderer:         NewMarkdownRenderer(),
+	}
+	proposal := &mcms.Proposal{
+		Operations: []types.Operation{
+			{
+				ChainSelector: types.ChainSelector(chainsel.TON_TESTNET.Selector),
+				Transaction: types.Transaction{
+					To:   "0x1234567890123456789012345678901234567890",
+					Data: []byte{0x01, 0x02, 0x03, 0x04},
+				},
+			},
+		},
+	}
+
+	report, err := BuildProposalReport(t.Context(), ctx, deployment.Environment{}, proposal)
+	require.NoError(t, err)
+	require.Contains(t, report.Operations[0].Calls[0].Method, "failed to decode TON transaction")
+}
+
+// TestBuildTimelockReport_FamilyErrors tests error handling when analyzers fail during
+// preprocessing (e.g., missing registry, invalid AdditionalFields). These are hard errors
+// that prevent the analyzer from proceeding.
 func TestBuildTimelockReport_FamilyBranches(t *testing.T) {
 	t.Parallel()
 
@@ -309,6 +344,37 @@ func TestBuildTimelockReport_FamilyBranches(t *testing.T) {
 	}
 }
 
+// TestBuildTimelockReport_TONDecodeFailure tests TON's graceful decode error handling.
+// Unlike other analyzers, TON doesn't require AdditionalFields for decoding (it only needs
+// tx.Data and tx.ContractType), so it proceeds directly to the decode stage. Decode failures
+// are handled gracefully by placing the error in the Method field rather than returning an error,
+// allowing the proposal to continue processing.
+func TestBuildTimelockReport_TONDecodeFailure(t *testing.T) {
+	t.Parallel()
+
+	proposalCtx := &DefaultProposalContext{
+		AddressesByChain: deployment.AddressesByChain{},
+		renderer:         NewMarkdownRenderer(),
+	}
+	proposal := &mcms.TimelockProposal{
+		Operations: []types.BatchOperation{
+			{
+				ChainSelector: types.ChainSelector(chainsel.TON_TESTNET.Selector),
+				Transactions: []types.Transaction{
+					{To: "0x1111111111111111111111111111111111111111", Data: []byte{0x01, 0x02, 0x03, 0x04}},
+					{To: "0x2222222222222222222222222222222222222222", Data: []byte{0x05, 0x06, 0x07, 0x08}},
+				},
+			},
+		},
+	}
+
+	report, err := BuildTimelockReport(t.Context(), proposalCtx, deployment.Environment{}, proposal)
+	require.NoError(t, err)
+	for _, op := range report.Batches[0].Operations {
+		require.Contains(t, op.Calls[0].Method, "failed to decode TON transaction")
+	}
+}
+
 // Test native token transfer integration with report builder
 func TestBuildProposalReport_NativeTransfer(t *testing.T) {
 	t.Parallel()
@@ -372,14 +438,14 @@ func TestBuildProposalReport_DefaultCase(t *testing.T) {
 		renderer:         NewMarkdownRenderer(),
 	}
 
-	// Use a TON chain selector - TON family is not handled in the switch statement
+	// Use a TRON chain selector - TRON family is not handled in the switch statement
 	// so it will trigger the default case
-	tonChainSelector := chainsel.TON_LOCALNET.Selector
+	tronChainSelector := chainsel.TRON_DEVNET.Selector
 
 	proposal := &mcms.Proposal{
 		Operations: []types.Operation{
 			{
-				ChainSelector: types.ChainSelector(tonChainSelector),
+				ChainSelector: types.ChainSelector(tronChainSelector),
 				Transaction: types.Transaction{
 					To:   "0x1234567890123456789012345678901234567890",
 					Data: []byte{0x01, 0x02, 0x03, 0x04},
@@ -395,8 +461,8 @@ func TestBuildProposalReport_DefaultCase(t *testing.T) {
 	require.Len(t, report.Operations, 1)
 
 	operation := report.Operations[0]
-	require.Equal(t, tonChainSelector, operation.ChainSelector)
-	require.Equal(t, "ton-localnet", operation.ChainName) // TON chain has a known name
-	require.Equal(t, "ton", operation.Family)             // TON family
-	require.Empty(t, operation.Calls)                     // Default case sets calls to empty slice
+	require.Equal(t, tronChainSelector, operation.ChainSelector)
+	require.Equal(t, chainsel.TRON_DEVNET.Name, operation.ChainName) // TRON chain has a known name
+	require.Equal(t, chainsel.FamilyTron, operation.Family)          // TRON family
+	require.Empty(t, operation.Calls)                                // Default case sets calls to empty slice
 }

experimental/analyzer/sui_analyzer_test.go

@@ -4,10 +4,11 @@ import (
 	"encoding/json"
 	"testing"
 
+	"github.com/stretchr/testify/require"
+
 	chainsel "github.com/smartcontractkit/chain-selectors"
 	mcmssuisdk "github.com/smartcontractkit/mcms/sdk/sui"
 	"github.com/smartcontractkit/mcms/types"
-	"github.com/stretchr/testify/require"
 
 	"github.com/smartcontractkit/chainlink-deployments-framework/deployment"
 )

experimental/analyzer/ton_analyzer.go

@@ -0,0 +1,60 @@
+package analyzer
+
+import (
+	"fmt"
+
+	"github.com/smartcontractkit/chainlink-ton/pkg/bindings"
+	"github.com/smartcontractkit/mcms/sdk"
+	"github.com/smartcontractkit/mcms/sdk/ton"
+	"github.com/smartcontractkit/mcms/types"
+)
+
+// AnalyzeTONTransactions decodes a slice of TON transactions and returns their decoded representations.
+func AnalyzeTONTransactions(ctx ProposalContext, txs []types.Transaction) ([]*DecodedCall, error) {
+	decoder := ton.NewDecoder(bindings.Registry)
+	decodedTxs := make([]*DecodedCall, len(txs))
+	for i, op := range txs {
+		analyzedTransaction, err := AnalyzeTONTransaction(ctx, decoder, op)
+		if err != nil {
+			return nil, fmt.Errorf("failed to analyze TON transaction %d: %w", i, err)
+		}
+		decodedTxs[i] = analyzedTransaction
+	}
+
+	return decodedTxs, nil
+}
+
+// AnalyzeTONTransaction decodes a single TON transaction using the MCMS TON decoder.
+//
+// Unlike Aptos/Sui analyzers, this function does not unmarshal AdditionalFields because
+// the TON decoder only requires tx.Data (BOC cell) and tx.ContractType (metadata).
+// AdditionalFields in TON is only used by the encoder/timelock_converter for the Value field.
+//
+// On decode failure, this function returns a DecodedCall with the error in the Method field
+// instead of returning an error. This allows the proposal to continue processing even if
+// a single transaction fails to decode.
+func AnalyzeTONTransaction(_ ProposalContext, decoder sdk.Decoder, mcmsTx types.Transaction) (*DecodedCall, error) {
+	decodedOp, err := decoder.Decode(mcmsTx, mcmsTx.ContractType)
+	if err != nil {
+		// Don't return an error to not block the whole proposal decoding because of a single transaction decode failure.
+		// Instead, put the error message in the Method field so it's visible in the report.
+		errStr := fmt.Errorf("failed to decode TON transaction: %w", err)
+
+		return &DecodedCall{
+			Address: mcmsTx.To,
+			Method:  errStr.Error(),
+		}, nil
+	}
+
+	namedArgs, err := toNamedFields(decodedOp)
+	if err != nil {
+		return nil, fmt.Errorf("failed to convert decoded operation to named arguments: %w", err)
+	}
+
+	return &DecodedCall{
+		Address: mcmsTx.To,
+		Method:  decodedOp.MethodName(),
+		Inputs:  namedArgs,
+		Outputs: []NamedField{},
+	}, nil
+}