feat(mcms/analyzer): add Solana native programs to decoder registry (#942)

This pull request enhances the Solana analyzer by adding support for
native Solana programs and improving instruction decoding capabilities.
It introduces a registry for Solana native programs, ensures their
decoders are registered by default, and adds comprehensive support for
Anchor IDL instruction decoding.

It also adds Go bindings for some native programs that are not available
by default in the gagliardetto/solana-go library to the
`experimental/analyzer/solana/programs` package.

---
OPT-486

Author: gustavogama-cll

.changeset/moody-ends-bathe.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+feat(mcms/analyzer): add Solana native programs to registry

experimental/analyzer/registry_solana.go

@@ -2,10 +2,22 @@ package analyzer
 
 import (
 	"fmt"
+	"maps"
 
-	"github.com/smartcontractkit/chainlink-deployments-framework/deployment"
+	"github.com/gagliardetto/solana-go"
+
+	computebudget "github.com/gagliardetto/solana-go/programs/compute-budget"
+	"github.com/gagliardetto/solana-go/programs/memo"
+	"github.com/gagliardetto/solana-go/programs/stake"
+	"github.com/gagliardetto/solana-go/programs/system"
+	"github.com/gagliardetto/solana-go/programs/token"
+	"github.com/gagliardetto/solana-go/programs/tokenregistry"
+	"github.com/gagliardetto/solana-go/programs/vote"
 
+	"github.com/smartcontractkit/chainlink-deployments-framework/deployment"
 	"github.com/smartcontractkit/chainlink-deployments-framework/experimental/analyzer/pointer"
+	"github.com/smartcontractkit/chainlink-deployments-framework/experimental/analyzer/solana/programs/loaderv3"
+	verify "github.com/smartcontractkit/chainlink-deployments-framework/experimental/analyzer/solana/programs/otter_verify"
 )
 
 // SolanaDecoderRegistry is an interface for retrieving and managing Solana instruction decoders.
@@ -61,8 +73,38 @@ func (reg environmentSolanaRegistry) AddSolanaInstructionDecoder(typeAndVersion
 	reg.registry[typeAndVersion.String()] = decoder
 }
 
+var nativePrograms = map[solana.PublicKey]deployment.TypeAndVersion{
+	solana.BPFLoaderUpgradeableProgramID: deployment.MustTypeAndVersionFromString("BPFLoaderUpgradeable 1.0.0"),
+	solana.SystemProgramID:               deployment.MustTypeAndVersionFromString("System 1.0.0"),
+	solana.ComputeBudget:                 deployment.MustTypeAndVersionFromString("ComputeBudget 1.0.0"),
+	solana.MemoProgramID:                 deployment.MustTypeAndVersionFromString("Memo 1.0.0"),
+	solana.StakeProgramID:                deployment.MustTypeAndVersionFromString("Stake 1.0.0"),
+	solana.TokenProgramID:                deployment.MustTypeAndVersionFromString("Token 1.0.0"),
+	solana.VoteProgramID:                 deployment.MustTypeAndVersionFromString("Vote 1.0.0"),
+	verify.ProgramID:                     deployment.MustTypeAndVersionFromString("OtterVerify 1.0.0"),
+	tokenregistry.ProgramID():            deployment.MustTypeAndVersionFromString("TokenRegistry 1.0.0"),
+}
+
+var nativeDecoderMappings = map[string]DecodeInstructionFn{
+	nativePrograms[solana.BPFLoaderUpgradeableProgramID].String(): DIFn(loaderv3.DecodeInstruction),
+	nativePrograms[solana.ComputeBudget].String():                 DIFn(computebudget.DecodeInstruction),
+	nativePrograms[solana.MemoProgramID].String():                 DIFn(memo.DecodeInstruction),
+	nativePrograms[solana.StakeProgramID].String():                DIFn(stake.DecodeInstruction),
+	nativePrograms[solana.SystemProgramID].String():               DIFn(system.DecodeInstruction),
+	nativePrograms[solana.TokenProgramID].String():                DIFn(token.DecodeInstruction),
+	nativePrograms[solana.VoteProgramID].String():                 DIFn(vote.DecodeInstruction),
+	nativePrograms[tokenregistry.ProgramID()].String():            DIFn(tokenregistry.DecodeInstruction),
+	nativePrograms[verify.ProgramID].String():                     DIFn(verify.DecodeInstruction),
+}
+
 // NewEnvironmentSolanaRegistry creates a new environmentSolanaRegistry from the provided ABI mappings and domain name.
 func NewEnvironmentSolanaRegistry(env deployment.Environment, decoderMappings map[string]DecodeInstructionFn) (*environmentSolanaRegistry, error) {
+	if decoderMappings == nil {
+		decoderMappings = map[string]DecodeInstructionFn{}
+	} else {
+		decoderMappings = maps.Clone(decoderMappings)
+	}
+
 	addressesByChain, errAddrBook := env.ExistingAddresses.Addresses() //nolint:staticcheck
 	if errAddrBook != nil {
 		return nil, errAddrBook
@@ -84,6 +126,15 @@ func NewEnvironmentSolanaRegistry(env deployment.Environment, decoderMappings ma
 		addressesByChain[address.ChainSelector] = chainAddresses
 	}
 
+	// add native programs and mappings
+	for chainSelector, addresses := range addressesByChain {
+		for pk, contractTypeAndVersion := range nativePrograms {
+			addresses[pk.String()] = contractTypeAndVersion
+		}
+		addressesByChain[chainSelector] = addresses
+	}
+	maps.Insert(decoderMappings, maps.All(nativeDecoderMappings))
+
 	return &environmentSolanaRegistry{
 		registry:         decoderMappings,
 		env:              env,

experimental/analyzer/registry_solana_test.go

@@ -1,8 +1,12 @@
 package analyzer
 
 import (
+	"maps"
+	"slices"
 	"testing"
 
+	"github.com/samber/lo"
+	chainsel "github.com/smartcontractkit/chain-selectors"
 	"github.com/stretchr/testify/require"
 
 	"github.com/smartcontractkit/chainlink-deployments-framework/datastore"
@@ -98,7 +102,8 @@ func Test_EnvironmentSolanaRegistry_GetSolanaInstructionDecoderByAddress(t *test
 			reg, err := NewEnvironmentSolanaRegistry(
 				deployment.Environment{
 					ExistingAddresses: deployment.NewMemoryAddressBook(),
-					DataStore:         ds.Seal()},
+					DataStore:         ds.Seal(),
+				},
 				tt.registry,
 			)
 			require.NoError(t, err)
@@ -162,3 +167,39 @@ func Test_EnvironmentSolanaRegistry_Decoders_ReturnsDefensiveCopy(t *testing.T)
 	require.NoError(t, getErr)
 	require.Nil(t, decoder)
 }
+
+func Test_EnvironmentSolanaRegistry_NilDecoderMappings(t *testing.T) {
+	t.Parallel()
+
+	reg, err := NewEnvironmentSolanaRegistry(deployment.Environment{
+		ExistingAddresses: deployment.NewMemoryAddressBookFromMap(map[uint64]map[string]deployment.TypeAndVersion{
+			chainsel.SOLANA_DEVNET.Selector: {
+				"TestContract1111111111111111111111111111111": deployment.MustTypeAndVersionFromString("TestContract 1.0.0"),
+			},
+		}),
+		DataStore: datastore.NewMemoryDataStore().Seal(),
+	}, nil)
+	require.NoError(t, err)
+	require.NotNil(t, reg)
+
+	require.Equal(t, reg.addressesByChain, deployment.AddressesByChain{ //nolint:testifylint
+		chainsel.SOLANA_DEVNET.Selector: {
+			"TestContract1111111111111111111111111111111":  deployment.MustTypeAndVersionFromString("TestContract 1.0.0"),
+			"BPFLoaderUpgradeab1e11111111111111111111111":  deployment.MustTypeAndVersionFromString("BPFLoaderUpgradeable 1.0.0"),
+			"11111111111111111111111111111111":             deployment.MustTypeAndVersionFromString("System 1.0.0"),
+			"ComputeBudget111111111111111111111111111111":  deployment.MustTypeAndVersionFromString("ComputeBudget 1.0.0"),
+			"MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr":  deployment.MustTypeAndVersionFromString("Memo 1.0.0"),
+			"Stake11111111111111111111111111111111111111":  deployment.MustTypeAndVersionFromString("Stake 1.0.0"),
+			"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA":  deployment.MustTypeAndVersionFromString("Token 1.0.0"),
+			"Vote111111111111111111111111111111111111111":  deployment.MustTypeAndVersionFromString("Vote 1.0.0"),
+			"verifycLy8mB96wd9wqq3WDXQwM4oU6r42Th37Db9fC":  deployment.MustTypeAndVersionFromString("OtterVerify 1.0.0"),
+			"CmPVzy88JSB4S223yCvFmBxTLobLya27KgEDeNPnqEub": deployment.MustTypeAndVersionFromString("TokenRegistry 1.0.0"),
+		},
+	})
+	require.ElementsMatch(t, slices.Collect(maps.Keys(reg.registry)), []string{
+		"Memo 1.0.0", "OtterVerify 1.0.0", "BPFLoaderUpgradeable 1.0.0", "ComputeBudget 1.0.0",
+		"TokenRegistry 1.0.0", "Vote 1.0.0", "Stake 1.0.0", "System 1.0.0", "Token 1.0.0",
+	})
+	decodeFns := lo.FilterValues(reg.registry, func(_ string, fn DecodeInstructionFn) bool { return fn != nil })
+	require.Len(t, decodeFns, len(nativePrograms))
+}

experimental/analyzer/solana/programs/idl/close.go

@@ -0,0 +1,11 @@
+package idl
+
+import (
+	ag_binary "github.com/gagliardetto/binary"
+)
+
+type IDLClose struct{}
+
+func (inst *IDLClose) UnmarshalWithDecoder(decoder *ag_binary.Decoder) error {
+	return nil
+}

experimental/analyzer/solana/programs/idl/create.go

@@ -0,0 +1,19 @@
+package idl
+
+import (
+	ag_binary "github.com/gagliardetto/binary"
+)
+
+// IDLCreate instruction
+type IDLCreate struct{ DataLen uint64 }
+
+func (inst *IDLCreate) UnmarshalWithDecoder(decoder *ag_binary.Decoder) error {
+	{
+		err := decoder.Decode(&inst.DataLen)
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}

experimental/analyzer/solana/programs/idl/createbuffer.go

@@ -0,0 +1,11 @@
+package idl
+
+import (
+	ag_binary "github.com/gagliardetto/binary"
+)
+
+type IDLCreateBuffer struct{}
+
+func (inst *IDLCreateBuffer) UnmarshalWithDecoder(decoder *ag_binary.Decoder) error {
+	return nil
+}

experimental/analyzer/solana/programs/idl/instructions.go

@@ -0,0 +1,103 @@
+package idl
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+
+	ag_binary "github.com/gagliardetto/binary"
+	ag_solanago "github.com/gagliardetto/solana-go"
+)
+
+const ProgramName = "AnchorIDL"
+
+// ProgramID is a zero sentinel since IDL instructions are sent to the target program
+// rather than a dedicated IDL program address.
+var ProgramID ag_solanago.PublicKey
+
+// Discriminator is the fixed 8-byte Anchor discriminator that identifies IDL instructions.
+var Discriminator = []byte{64, 244, 188, 120, 167, 233, 105, 10}
+
+const (
+	InstructionCreate       uint8 = iota // One-time initializer for creating the program's IDL account.
+	InstructionCreateBuffer              // Creates a new IDL account buffer. Can be called several times.
+	InstructionWrite                     // Appends the given data to the end of the IDL account buffer.
+	InstructionSetBuffer                 // Sets a new data buffer for the IdlAccount.
+	InstructionSetAuthority              // Sets a new authority on the IdlAccount.
+	InstructionClose                     // Closes the IDL PDA account.
+	InstructionResize                    // Increases account size for accounts that need over 10kb.
+)
+
+var InstructionImplDef = ag_binary.NewVariantDefinition(
+	ag_binary.Uint8TypeIDEncoding,
+	[]ag_binary.VariantType{
+		{Name: "create", Type: (*IDLCreate)(nil)},
+		{Name: "create_buffer", Type: (*IDLCreateBuffer)(nil)},
+		{Name: "write", Type: (*IDLWrite)(nil)},
+		{Name: "set_buffer", Type: (*IDLSetBuffer)(nil)},
+		{Name: "set_authority", Type: (*IDLSetAuthority)(nil)},
+		{Name: "close", Type: (*IDLClose)(nil)},
+		{Name: "resize", Type: (*IDLResize)(nil)},
+	},
+)
+
+type Instruction struct {
+	ag_binary.BaseVariant
+}
+
+func (inst *Instruction) ProgramID() ag_solanago.PublicKey {
+	return ProgramID
+}
+
+func (inst *Instruction) Accounts() (out []*ag_solanago.AccountMeta) {
+	if gettable, ok := inst.Impl.(ag_solanago.AccountsGettable); ok {
+		return gettable.GetAccounts()
+	}
+
+	return nil
+}
+
+func (inst *Instruction) Data() ([]byte, error) {
+	buf := new(bytes.Buffer)
+	if err := ag_binary.NewBorshEncoder(buf).Encode(inst); err != nil {
+		return nil, fmt.Errorf("unable to encode IDL instruction: %w", err)
+	}
+
+	return buf.Bytes(), nil
+}
+
+func (inst *Instruction) UnmarshalWithDecoder(decoder *ag_binary.Decoder) error {
+	return inst.UnmarshalBinaryVariant(decoder, InstructionImplDef)
+}
+
+func (inst *Instruction) MarshalWithEncoder(encoder *ag_binary.Encoder) error {
+	if err := encoder.WriteUint8(inst.TypeID.Uint8()); err != nil {
+		return fmt.Errorf("unable to write variant type: %w", err)
+	}
+
+	return encoder.Encode(inst.Impl)
+}
+
+// IsInstruction reports whether data starts with the IDL instruction discriminator.
+func IsInstruction(data []byte) bool {
+	return len(data) >= 9 && bytes.Equal(data[:8], Discriminator)
+}
+
+// DecodeInstruction decodes a Solana IDL instruction from the given accounts and data.
+// The data must start with the 8-byte IDL discriminator followed by a 1-byte instruction type.
+func DecodeInstruction(accounts []*ag_solanago.AccountMeta, data []byte) (*Instruction, error) {
+	if !IsInstruction(data) {
+		return nil, errors.New("not a valid IDL instruction: invalid discriminator or insufficient data length")
+	}
+	inst := new(Instruction)
+	if err := ag_binary.NewBorshDecoder(data[8:]).Decode(inst); err != nil {
+		return nil, fmt.Errorf("unable to decode IDL instruction: %w", err)
+	}
+	if v, ok := inst.Impl.(ag_solanago.AccountsSettable); ok {
+		if err := v.SetAccounts(accounts); err != nil {
+			return nil, fmt.Errorf("unable to set accounts for IDL instruction: %w", err)
+		}
+	}
+
+	return inst, nil
+}