feat: proposal level decoding APIs (#309)

This pull request introduces new APIs for proposal-level decoding and
includes several changes to the `proposal` and `timelock_proposal`
modules to support these new features. The most important changes
include adding the `DecodeProposal` method to both `Proposal` and
`TimelockProposal` structs, updating tests to cover these new methods,
and importing necessary packages.

### Proposal Decoding Enhancements:

* Added `DecodeProposal` method to `Proposal` struct to decode raw
transactions into human-readable operations. (`proposal.go`)
* Added `DecodeProposal` method to `TimelockProposal` struct to decode
raw transactions into human-readable operations.
(`timelock_proposal.go`)

### Testing Enhancements:

* Added `Test_Proposal_Decode` to test the `DecodeProposal` method for
`Proposal` struct, including various success and failure scenarios.
(`proposal_test.go`)
* Added `Test_TimelockProposal_Decode` to test the `DecodeProposal`
method for `TimelockProposal` struct, including various success and
failure scenarios. (`timelock_proposal_test.go`)

### Dependency Updates:

* Imported necessary packages for decoding and testing, including
`crypto`, `mock`, and `bindings`. (`proposal_test.go`,
`timelock_proposal_test.go`)
[[1]](diffhunk://#diff-f54ef2790620db06a34dcf62d0565c5536ddeb0b22274fafc6d0cff158c9b789R8-R24)
[[2]](diffhunk://#diff-b80686a8969c14a89af64e7ed45e5a1e0dc025880256405d9e48eac6e33722b9R8-R24)

### Documentation:

* Added a changeset file to document the addition of proposal-level
decoding related APIs. (`.changeset/fast-taxis-guess.md`)

---------

Co-authored-by: Gustavo Gama <gustavo.gama@smartcontract.com>

Author: akhilchainani

.changeset/fast-taxis-guess.md

@@ -0,0 +1,5 @@
+---
+"@smartcontractkit/mcms": minor
+---
+
+Add proposal-level decoding related APIs

proposal.go

@@ -348,6 +348,33 @@ func (p *Proposal) GetEncoders() (map[types.ChainSelector]sdk.Encoder, error) {
 	return encoders, nil
 }
 
+// Decode decodes the raw transactions into a list of human-readable operations.
+func (p *Proposal) Decode(decoders map[types.ChainSelector]sdk.Decoder, contractInterfaces map[string]string) ([]sdk.DecodedOperation, error) {
+	decodedOps := make([]sdk.DecodedOperation, len(p.Operations))
+	for i, op := range p.Operations {
+		// Get the decoder for the chain selector
+		decoder, ok := decoders[op.ChainSelector]
+		if !ok {
+			return nil, fmt.Errorf("no decoder found for chain selector %d", op.ChainSelector)
+		}
+
+		// Get the contract interfaces for the contract type
+		contractInterface, ok := contractInterfaces[op.Transaction.ContractType]
+		if !ok {
+			return nil, fmt.Errorf("no contract interfaces found for contract type %s", op.Transaction.ContractType)
+		}
+
+		decodedOp, err := decoder.Decode(op.Transaction, contractInterface)
+		if err != nil {
+			return nil, fmt.Errorf("unable to decode operation: %w", err)
+		}
+
+		decodedOps[i] = decodedOp
+	}
+
+	return decodedOps, nil
+}
+
 // proposalValidateBasic basic validation for an MCMS proposal
 func proposalValidateBasic(proposalObj Proposal) error {
 	validUntil := time.Unix(int64(proposalObj.ValidUntil), 0)

proposal_test.go

@@ -5,18 +5,23 @@ import (
 	"errors"
 	"io"
 	"math"
+	"math/big"
 	"os"
 	"strings"
 	"testing"
 
 	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/crypto"
 	"github.com/go-playground/validator/v10"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/mock"
 	"github.com/stretchr/testify/require"
 
 	"github.com/smartcontractkit/mcms/internal/testutils/chaintest"
 	"github.com/smartcontractkit/mcms/sdk"
 	"github.com/smartcontractkit/mcms/sdk/evm"
+	"github.com/smartcontractkit/mcms/sdk/evm/bindings"
+	"github.com/smartcontractkit/mcms/sdk/mocks"
 	"github.com/smartcontractkit/mcms/types"
 )
 
@@ -804,6 +809,153 @@ func Test_Proposal_TransactionCounts(t *testing.T) {
 	}, got)
 }
 
+func Test_Proposal_Decode(t *testing.T) {
+	t.Parallel()
+
+	// Get ABI
+	timelockAbi, err := bindings.RBACTimelockMetaData.GetAbi()
+	require.NoError(t, err)
+	exampleRole := crypto.Keccak256Hash([]byte("EXAMPLE_ROLE"))
+
+	// Grant role data
+	grantRoleData, err := timelockAbi.Pack("grantRole", [32]byte(exampleRole), common.HexToAddress("0x123"))
+	require.NoError(t, err)
+
+	tests := []struct {
+		name    string
+		setup   func(t *testing.T) (map[types.ChainSelector]sdk.Decoder, map[string]string)
+		give    []types.Operation
+		want    []sdk.DecodedOperation
+		wantErr string
+	}{
+		{
+			name: "success: decodes an operation",
+			setup: func(t *testing.T) (map[types.ChainSelector]sdk.Decoder, map[string]string) {
+				t.Helper()
+				decoders := map[types.ChainSelector]sdk.Decoder{
+					chaintest.Chain1Selector: evm.NewDecoder(),
+				}
+
+				return decoders, map[string]string{"RBACTimelock": bindings.RBACTimelockABI}
+			},
+			give: []types.Operation{
+				{
+					ChainSelector: chaintest.Chain1Selector,
+					Transaction: evm.NewTransaction(
+						common.HexToAddress("0xTestTarget"),
+						grantRoleData,
+						big.NewInt(0),
+						"RBACTimelock",
+						[]string{"grantRole"},
+					),
+				},
+			},
+			want: []sdk.DecodedOperation{
+				&evm.DecodedOperation{
+					FunctionName: "grantRole",
+					InputKeys:    []string{"role", "account"},
+					InputArgs:    []any{[32]byte(exampleRole.Bytes()), common.HexToAddress("0x0000000000000000000000000000000000000123")},
+				},
+			},
+			wantErr: "",
+		},
+		{
+			name: "failure: missing chain decoder",
+			setup: func(t *testing.T) (map[types.ChainSelector]sdk.Decoder, map[string]string) {
+				t.Helper()
+				return map[types.ChainSelector]sdk.Decoder{}, map[string]string{}
+			},
+			give: []types.Operation{
+				{
+					ChainSelector: chaintest.Chain1Selector,
+					Transaction: evm.NewTransaction(
+						common.HexToAddress("0xTestTarget"),
+						grantRoleData,
+						big.NewInt(0),
+						"RBACTimelock",
+						[]string{"grantRole"},
+					),
+				},
+			},
+			want:    nil,
+			wantErr: "no decoder found for chain selector 3379446385462418246",
+		},
+		{
+			name: "failure: missing contract ABI",
+			setup: func(t *testing.T) (map[types.ChainSelector]sdk.Decoder, map[string]string) {
+				t.Helper()
+				decoders := map[types.ChainSelector]sdk.Decoder{
+					chaintest.Chain1Selector: evm.NewDecoder(),
+				}
+
+				return decoders, map[string]string{}
+			},
+			give: []types.Operation{
+				{
+					ChainSelector: chaintest.Chain1Selector,
+					Transaction: evm.NewTransaction(
+						common.HexToAddress("0xTestTarget"),
+						grantRoleData,
+						big.NewInt(0),
+						"RBACTimelock",
+						[]string{"grantRole"},
+					),
+				},
+			},
+			want:    nil,
+			wantErr: "no contract interfaces found for contract type RBACTimelock",
+		},
+		{
+			name: "failure: unable to decode operation",
+			setup: func(t *testing.T) (map[types.ChainSelector]sdk.Decoder, map[string]string) {
+				t.Helper()
+				mockDecoder := mocks.NewDecoder(t)
+				mockDecoder.EXPECT().Decode(mock.Anything, mock.Anything).Return(nil, errors.New("decode error"))
+				decoders := map[types.ChainSelector]sdk.Decoder{
+					chaintest.Chain1Selector: mockDecoder,
+				}
+
+				return decoders, map[string]string{"RBACTimelock": bindings.RBACTimelockABI}
+			},
+			give: []types.Operation{
+				{
+					ChainSelector: chaintest.Chain1Selector,
+					Transaction: evm.NewTransaction(
+						common.HexToAddress("0xTestTarget"),
+						grantRoleData,
+						big.NewInt(0),
+						"RBACTimelock",
+						[]string{"grantRole"},
+					),
+				},
+			},
+			want:    nil,
+			wantErr: "unable to decode operation: decode error",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			proposal := Proposal{
+				BaseProposal: BaseProposal{},
+				Operations:   tt.give,
+			}
+
+			decoders, interfaces := tt.setup(t)
+			got, err := proposal.Decode(decoders, interfaces)
+
+			if tt.wantErr != "" {
+				require.EqualError(t, err, tt.wantErr)
+			} else {
+				require.NoError(t, err)
+				assert.Equal(t, tt.want, got)
+			}
+		})
+	}
+}
+
 func Test_Proposal_TransactionNonces(t *testing.T) {
 	t.Parallel()
 

timelock_proposal.go

@@ -186,6 +186,35 @@ func (m *TimelockProposal) Convert(
 	return result, predecessors, nil
 }
 
+// Decode decodes the raw transactions into a list of human-readable operations.
+func (m *TimelockProposal) Decode(decoders map[types.ChainSelector]sdk.Decoder, contractInterfaces map[string]string) ([][]sdk.DecodedOperation, error) {
+	decodedOps := make([][]sdk.DecodedOperation, len(m.Operations))
+	for i, op := range m.Operations {
+		// Get the decoder for the chain selector
+		decoder, ok := decoders[op.ChainSelector]
+		if !ok {
+			return nil, fmt.Errorf("no decoder found for chain selector %d", op.ChainSelector)
+		}
+
+		for _, tx := range op.Transactions {
+			// Get the contract interfaces for the contract type
+			contractInterface, ok := contractInterfaces[tx.ContractType]
+			if !ok {
+				return nil, fmt.Errorf("no contract interfaces found for contract type %s", tx.ContractType)
+			}
+
+			decodedOp, err := decoder.Decode(tx, contractInterface)
+			if err != nil {
+				return nil, fmt.Errorf("unable to decode operation: %w", err)
+			}
+
+			decodedOps[i] = append(decodedOps[i], decodedOp)
+		}
+	}
+
+	return decodedOps, nil
+}
+
 // timeLockProposalValidateBasic basic validation for an MCMS proposal
 func timeLockProposalValidateBasic(timelockProposal TimelockProposal) error {
 	// Get the current Unix timestamp as an int64