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

@@ -25,33 +25,27 @@ func BuildProposalReport(ctx context.Context, proposalContext ProposalContext, e
 		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
+			calls, err = AnalyzeEVMTransactions(ctx, proposalContext, env, chainSel, []types.Transaction{op.Transaction})
+
 		case chainsel.FamilySolana:
-			dec, err := AnalyzeSolanaTransactions(proposalContext, chainSel, []types.Transaction{op.Transaction})
-			if err != nil {
-				return nil, err
-			}
-			calls = dec
+			calls, err = AnalyzeSolanaTransactions(proposalContext, chainSel, []types.Transaction{op.Transaction})
+
 		case chainsel.FamilyAptos:
-			dec, err := AnalyzeAptosTransactions(proposalContext, chainSel, []types.Transaction{op.Transaction})
-			if err != nil {
-				return nil, err
-			}
-			calls = dec
+			calls, err = AnalyzeAptosTransactions(proposalContext, chainSel, []types.Transaction{op.Transaction})
+
 		case chainsel.FamilySui:
-			dec, err := AnalyzeSuiTransactions(proposalContext, chainSel, []types.Transaction{op.Transaction})
-			if err != nil {
-				return nil, err
-			}
-			calls = dec
+			calls, err = AnalyzeSuiTransactions(proposalContext, chainSel, []types.Transaction{op.Transaction})
+
+		case chainsel.FamilyTon:
+			calls, err = AnalyzeTONTransactions(proposalContext, []types.Transaction{op.Transaction})
 		default:
 			calls = []*DecodedCall{}
 		}
 
+		if err != nil {
+			return nil, err
+		}
+
 		rpt.Operations[i] = OperationReport{
 			ChainSelector: chainSel,
 			ChainName:     chainNameOrUnknown(chainName),
@@ -128,6 +122,19 @@ func BuildTimelockReport(ctx context.Context, proposalCtx ProposalContext, env d
 					Calls:         []*DecodedCall{dec[j]},
 				}
 			}
+		case chainsel.FamilyTon:
+			dec, err := AnalyzeTONTransactions(proposalCtx, 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{

experimental/analyzer/report_builder_test.go

@@ -195,33 +195,44 @@ func TestChainNameOrUnknown(t *testing.T) {
 	require.Equal(t, "<chain unknown>", chainNameOrUnknown(" "))
 }
 
-func TestBuildProposalReport_FamilyBranches(t *testing.T) {
+func TestBuildProposalReport_FamilyErrors(t *testing.T) {
 	t.Parallel()
 
 	tests := []struct {
-		name          string
-		selector      uint64
-		expectedError string
+		name        string
+		selector    uint64
+		expectedMsg string
+		wantErr     bool // if true, expect returned error; if false, error is in Method field (TON behavior)
 	}{
 		{
-			name:          "EVM_missing_registry",
-			selector:      chainsel.ETHEREUM_TESTNET_SEPOLIA.Selector,
-			expectedError: "EVM registry is not available",
+			name:        "EVM_missing_registry",
+			selector:    chainsel.ETHEREUM_TESTNET_SEPOLIA.Selector,
+			expectedMsg: "EVM registry is not available",
+			wantErr:     true,
 		},
 		{
-			name:          "Solana_missing_registry",
-			selector:      chainsel.SOLANA_DEVNET.Selector,
-			expectedError: "failed to analyze solana transaction 0: solana decoder registry is not available",
+			name:        "Solana_missing_registry",
+			selector:    chainsel.SOLANA_DEVNET.Selector,
+			expectedMsg: "failed to analyze solana transaction 0: solana decoder registry is not available",
+			wantErr:     true,
 		},
 		{
-			name:          "Aptos_unmarshal_additional_fields",
-			selector:      chainsel.APTOS_TESTNET.Selector,
-			expectedError: "failed to unmarshal Aptos additional fields: unexpected end of JSON input",
+			name:        "Aptos_unmarshal_additional_fields",
+			selector:    chainsel.APTOS_TESTNET.Selector,
+			expectedMsg: "failed to unmarshal Aptos additional fields: unexpected end of JSON input",
+			wantErr:     true,
 		},
 		{
-			name:          "Sui_unmarshal_additional_fields",
-			selector:      chainsel.SUI_TESTNET.Selector,
-			expectedError: "failed to unmarshal Sui additional fields: unexpected end of JSON input",
+			name:        "Sui_unmarshal_additional_fields",
+			selector:    chainsel.SUI_TESTNET.Selector,
+			expectedMsg: "failed to unmarshal Sui additional fields: unexpected end of JSON input",
+			wantErr:     true,
+		},
+		{
+			name:        "TON_decode_failure",
+			selector:    chainsel.TON_TESTNET.Selector,
+			expectedMsg: "failed to decode TON transaction",
+			wantErr:     false, // TON doesn't unmarshal AdditionalFields, so decode errors go to Method field
 		},
 	}
 
@@ -245,40 +256,56 @@ func TestBuildProposalReport_FamilyBranches(t *testing.T) {
 				},
 			}
 
-			_, err := BuildProposalReport(t.Context(), ctx, deployment.Environment{}, proposal)
-			require.Error(t, err)
-			require.Contains(t, err.Error(), tt.expectedError)
+			report, err := BuildProposalReport(t.Context(), ctx, deployment.Environment{}, proposal)
+			if tt.wantErr {
+				require.Error(t, err)
+				require.Contains(t, err.Error(), tt.expectedMsg)
+			} else {
+				require.NoError(t, err)
+				require.Contains(t, report.Operations[0].Calls[0].Method, tt.expectedMsg)
+			}
 		})
 	}
 }
 
-func TestBuildTimelockReport_FamilyBranches(t *testing.T) {
+func TestBuildTimelockReport_FamilyErrors(t *testing.T) {
 	t.Parallel()
 
 	tests := []struct {
-		name          string
-		selector      uint64
-		expectedError string
+		name        string
+		selector    uint64
+		expectedMsg string
+		wantErr     bool // if true, expect returned error; if false, error is in Method field (TON behavior)
 	}{
 		{
-			name:          "EVM_missing_registry",
-			selector:      chainsel.ETHEREUM_TESTNET_SEPOLIA.Selector,
-			expectedError: "EVM registry is not available",
+			name:        "EVM_missing_registry",
+			selector:    chainsel.ETHEREUM_TESTNET_SEPOLIA.Selector,
+			expectedMsg: "EVM registry is not available",
+			wantErr:     true,
 		},
 		{
-			name:          "Solana_missing_registry",
-			selector:      chainsel.SOLANA_DEVNET.Selector,
-			expectedError: "failed to analyze solana transaction 0: solana decoder registry is not available",
+			name:        "Solana_missing_registry",
+			selector:    chainsel.SOLANA_DEVNET.Selector,
+			expectedMsg: "failed to analyze solana transaction 0: solana decoder registry is not available",
+			wantErr:     true,
 		},
 		{
-			name:          "Aptos_unmarshal_additional_fields",
-			selector:      chainsel.APTOS_TESTNET.Selector,
-			expectedError: "failed to unmarshal Aptos additional fields: unexpected end of JSON input",
+			name:        "Aptos_unmarshal_additional_fields",
+			selector:    chainsel.APTOS_TESTNET.Selector,
+			expectedMsg: "failed to unmarshal Aptos additional fields: unexpected end of JSON input",
+			wantErr:     true,
 		},
 		{
-			name:          "Sui_unmarshal_additional_fields",
-			selector:      chainsel.SUI_TESTNET.Selector,
-			expectedError: "failed to unmarshal Sui additional fields: unexpected end of JSON input",
+			name:        "Sui_unmarshal_additional_fields",
+			selector:    chainsel.SUI_TESTNET.Selector,
+			expectedMsg: "failed to unmarshal Sui additional fields: unexpected end of JSON input",
+			wantErr:     true,
+		},
+		{
+			name:        "TON_decode_failure",
+			selector:    chainsel.TON_TESTNET.Selector,
+			expectedMsg: "failed to decode TON transaction",
+			wantErr:     false, // TON doesn't unmarshal AdditionalFields, so decode errors go to Method field
 		},
 	}
 
@@ -302,9 +329,16 @@ func TestBuildTimelockReport_FamilyBranches(t *testing.T) {
 				},
 			}
 
-			_, err := BuildTimelockReport(t.Context(), proposalCtx, deployment.Environment{}, proposal)
-			require.Error(t, err)
-			require.Contains(t, err.Error(), tt.expectedError)
+			report, err := BuildTimelockReport(t.Context(), proposalCtx, deployment.Environment{}, proposal)
+			if tt.wantErr {
+				require.Error(t, err)
+				require.Contains(t, err.Error(), tt.expectedMsg)
+			} else {
+				require.NoError(t, err)
+				for _, op := range report.Batches[0].Operations {
+					require.Contains(t, op.Calls[0].Method, tt.expectedMsg)
+				}
+			}
 		})
 	}
 }
@@ -372,14 +406,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 +429,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
+}