feat: changes the data structure of operations and it's use in proposals (#140)

This is a large change that changes the data structure of operations.
The current implementation promotes confusion with the usage of terms
operations and transactions. This change aims to make the codebase more
readable and maintainable, and provide a clear distinction between
operations and transactions.

Operations are now a separate entity from transactions. Operations are
defined as a piece of work that the MCMS can execute, while transactions
are the low level chain specific data structure that the MCMS can hash,
sign and execute on chain.

Author: jkongie

builder.go

@@ -73,7 +73,7 @@ func NewProposalBuilder() *ProposalBuilder {
 				Kind:          types.KindProposal,
 				ChainMetadata: make(map[types.ChainSelector]types.ChainMetadata),
 			},
-			Transactions: []types.ChainOperation{},
+			Operations: []types.Operation{},
 		},
 	}
 	// Initialize the BaseProposalBuilder with a reference to the base proposal and the builder itself.
@@ -85,16 +85,16 @@ func NewProposalBuilder() *ProposalBuilder {
 	return builder
 }
 
-// AddTransaction adds a transaction to the Proposal.
-func (b *ProposalBuilder) AddTransaction(transaction types.ChainOperation) *ProposalBuilder {
-	b.proposal.Transactions = append(b.proposal.Transactions, transaction)
+// AddOperation adds an operation to the Proposal.
+func (b *ProposalBuilder) AddOperation(op types.Operation) *ProposalBuilder {
+	b.proposal.Operations = append(b.proposal.Operations, op)
 
 	return b
 }
 
-// SetTransactions sets all the transactions of the Proposal.
-func (b *ProposalBuilder) SetTransactions(transaction []types.ChainOperation) *ProposalBuilder {
-	b.proposal.Transactions = transaction
+// SetOperations sets all the operations of the Proposal.
+func (b *ProposalBuilder) SetOperations(ops []types.Operation) *ProposalBuilder {
+	b.proposal.Operations = ops
 
 	return b
 }

builder_test.go

@@ -42,9 +42,9 @@ func TestProposalBuilder(t *testing.T) {
 					SetDescription("Valid Proposal").
 					SetOverridePreviousRoot(false).
 					AddChainMetadata(types.ChainSelector(SepoliaSelector), types.ChainMetadata{StartingOpCount: 0}).
-					AddTransaction(types.ChainOperation{
+					AddOperation(types.Operation{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Operation:     types.Operation{Data: []byte{0x01}},
+						Transaction:   types.Transaction{Data: []byte{0x01}},
 					})
 			},
 			want: &mcms.Proposal{
@@ -58,10 +58,10 @@ func TestProposalBuilder(t *testing.T) {
 						types.ChainSelector(SepoliaSelector): {StartingOpCount: 0},
 					},
 				},
-				Transactions: []types.ChainOperation{
+				Operations: []types.Operation{
 					{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Operation:     types.Operation{Data: []byte{0x01}},
+						Transaction:   types.Transaction{Data: []byte{0x01}},
 					},
 				},
 			},
@@ -75,14 +75,14 @@ func TestProposalBuilder(t *testing.T) {
 					SetDescription("Valid Proposal").
 					SetOverridePreviousRoot(false).
 					AddChainMetadata(types.ChainSelector(SepoliaSelector), types.ChainMetadata{StartingOpCount: 0}).
-					SetTransactions([]types.ChainOperation{
+					SetOperations([]types.Operation{
 						{
 							ChainSelector: types.ChainSelector(SepoliaSelector),
-							Operation:     types.Operation{Data: []byte{0x01}},
+							Transaction:   types.Transaction{Data: []byte{0x01}},
 						},
 						{
 							ChainSelector: types.ChainSelector(SepoliaSelector),
-							Operation:     types.Operation{Data: []byte{0x02}},
+							Transaction:   types.Transaction{Data: []byte{0x02}},
 						},
 					})
 			},
@@ -97,14 +97,14 @@ func TestProposalBuilder(t *testing.T) {
 						types.ChainSelector(SepoliaSelector): {StartingOpCount: 0},
 					},
 				},
-				Transactions: []types.ChainOperation{
+				Operations: []types.Operation{
 					{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Operation:     types.Operation{Data: []byte{0x01}},
+						Transaction:   types.Transaction{Data: []byte{0x01}},
 					},
 					{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Operation:     types.Operation{Data: []byte{0x02}},
+						Transaction:   types.Transaction{Data: []byte{0x02}},
 					},
 				},
 			},
@@ -120,14 +120,14 @@ func TestProposalBuilder(t *testing.T) {
 					SetChainMetadata(map[types.ChainSelector]types.ChainMetadata{
 						types.ChainSelector(SepoliaSelector): {StartingOpCount: 0},
 					}).
-					SetTransactions([]types.ChainOperation{
+					SetOperations([]types.Operation{
 						{
 							ChainSelector: types.ChainSelector(SepoliaSelector),
-							Operation:     types.Operation{Data: []byte{0x01}},
+							Transaction:   types.Transaction{Data: []byte{0x01}},
 						},
 						{
 							ChainSelector: types.ChainSelector(SepoliaSelector),
-							Operation:     types.Operation{Data: []byte{0x02}},
+							Transaction:   types.Transaction{Data: []byte{0x02}},
 						},
 					}).
 					AddSignature(types.Signature{
@@ -152,14 +152,14 @@ func TestProposalBuilder(t *testing.T) {
 						types.ChainSelector(SepoliaSelector): {StartingOpCount: 0},
 					},
 				},
-				Transactions: []types.ChainOperation{
+				Operations: []types.Operation{
 					{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Operation:     types.Operation{Data: []byte{0x01}},
+						Transaction:   types.Transaction{Data: []byte{0x01}},
 					},
 					{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Operation:     types.Operation{Data: []byte{0x02}},
+						Transaction:   types.Transaction{Data: []byte{0x02}},
 					},
 				},
 			},
@@ -172,9 +172,9 @@ func TestProposalBuilder(t *testing.T) {
 					SetDescription("Missing Version").
 					SetOverridePreviousRoot(false).
 					AddChainMetadata(types.ChainSelector(SepoliaSelector), types.ChainMetadata{StartingOpCount: 0}).
-					AddTransaction(types.ChainOperation{
+					AddOperation(types.Operation{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Operation:     types.Operation{Data: []byte{0x01}},
+						Transaction:   types.Transaction{Data: []byte{0x01}},
 					})
 			},
 			want: nil,
@@ -190,9 +190,9 @@ func TestProposalBuilder(t *testing.T) {
 					SetDescription("ValidUntil in Past").
 					SetOverridePreviousRoot(false).
 					AddChainMetadata(types.ChainSelector(SepoliaSelector), types.ChainMetadata{StartingOpCount: 0}).
-					AddTransaction(types.ChainOperation{
+					AddOperation(types.Operation{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Operation:     types.Operation{Data: []byte{0x01}},
+						Transaction:   types.Transaction{Data: []byte{0x01}},
 					})
 			},
 			want: nil,
@@ -212,7 +212,7 @@ func TestProposalBuilder(t *testing.T) {
 			},
 			want: nil,
 			wantErrs: []string{
-				"Key: 'Proposal.Transactions' Error:Field validation for 'Transactions' failed on the 'min' tag",
+				"Key: 'Proposal.Operations' Error:Field validation for 'Operations' failed on the 'min' tag",
 			},
 		},
 		{
@@ -223,9 +223,9 @@ func TestProposalBuilder(t *testing.T) {
 					SetDescription("Missing ChainMetadata").
 					SetOverridePreviousRoot(false).
 					// ChainMetadata is not added
-					AddTransaction(types.ChainOperation{
+					AddOperation(types.Operation{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Operation:     types.Operation{Data: []byte{0x01}},
+						Transaction:   types.Transaction{Data: []byte{0x01}},
 					})
 			},
 			want: nil,

builder_timelock.go

@@ -17,7 +17,7 @@ func NewTimelockProposalBuilder() *TimelockProposalBuilder {
 				ChainMetadata: make(map[types.ChainSelector]types.ChainMetadata),
 			},
 			TimelockAddresses: make(map[types.ChainSelector]string),
-			Transactions:      []types.BatchChainOperation{},
+			Operations:        []types.BatchOperation{},
 		},
 	}
 	builder.BaseProposalBuilder = BaseProposalBuilder[*TimelockProposalBuilder]{
@@ -46,16 +46,16 @@ func (b *TimelockProposalBuilder) SetTimelockAddress(selector types.ChainSelecto
 	return b
 }
 
-// AddTransaction adds a transaction to the timelock proposal.
-func (b *TimelockProposalBuilder) AddTransaction(transaction types.BatchChainOperation) *TimelockProposalBuilder {
-	b.proposal.Transactions = append(b.proposal.Transactions, transaction)
+// AddOperation adds an operation to the timelock proposal.
+func (b *TimelockProposalBuilder) AddOperation(bop types.BatchOperation) *TimelockProposalBuilder {
+	b.proposal.Operations = append(b.proposal.Operations, bop)
 
 	return b
 }
 
 // SetTransactions sets all the transactions of the proposal
-func (b *TimelockProposalBuilder) SetTransactions(transactions []types.BatchChainOperation) *TimelockProposalBuilder {
-	b.proposal.Transactions = transactions
+func (b *TimelockProposalBuilder) SetTransactions(bops []types.BatchOperation) *TimelockProposalBuilder {
+	b.proposal.Operations = bops
 
 	return b
 }

builder_timelock_test.go

@@ -47,9 +47,9 @@ func TestTimelockProposalBuilder(t *testing.T) {
 					SetDelay("24h").
 					AddChainMetadata(types.ChainSelector(SepoliaSelector), types.ChainMetadata{StartingOpCount: 0}).
 					SetTimelockAddress(types.ChainSelector(SepoliaSelector), "0xTimelockAddress").
-					AddTransaction(types.BatchChainOperation{
+					AddOperation(types.BatchOperation{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Batch: []types.Operation{
+						Transactions: []types.Transaction{
 							{
 								Data:             []byte{0x01},
 								To:               "0xContractAddress",
@@ -74,10 +74,10 @@ func TestTimelockProposalBuilder(t *testing.T) {
 				TimelockAddresses: map[types.ChainSelector]string{
 					types.ChainSelector(SepoliaSelector): "0xTimelockAddress",
 				},
-				Transactions: []types.BatchChainOperation{
+				Operations: []types.BatchOperation{
 					{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Batch: []types.Operation{
+						Transactions: []types.Transaction{
 							{
 								Data:             []byte{0x01},
 								To:               "0xContractAddress",
@@ -100,9 +100,9 @@ func TestTimelockProposalBuilder(t *testing.T) {
 					SetDelay("24h").
 					AddChainMetadata(types.ChainSelector(SepoliaSelector), types.ChainMetadata{StartingOpCount: 0}).
 					SetTimelockAddress(types.ChainSelector(SepoliaSelector), "0xTimelockAddress").
-					SetTransactions([]types.BatchChainOperation{{
+					SetTransactions([]types.BatchOperation{{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Batch: []types.Operation{
+						Transactions: []types.Transaction{
 							{
 								Data:             []byte{0x01},
 								To:               "0xContractAddress",
@@ -128,10 +128,10 @@ func TestTimelockProposalBuilder(t *testing.T) {
 				TimelockAddresses: map[types.ChainSelector]string{
 					types.ChainSelector(SepoliaSelector): "0xTimelockAddress",
 				},
-				Transactions: []types.BatchChainOperation{
+				Operations: []types.BatchOperation{
 					{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Batch: []types.Operation{
+						Transactions: []types.Transaction{
 							{
 								Data:             []byte{0x01},
 								To:               "0xContractAddress",
@@ -154,9 +154,9 @@ func TestTimelockProposalBuilder(t *testing.T) {
 					// Missing SetDelay
 					AddChainMetadata(types.ChainSelector(SepoliaSelector), types.ChainMetadata{StartingOpCount: 0}).
 					SetTimelockAddress(types.ChainSelector(SepoliaSelector), "0xTimelockAddress").
-					AddTransaction(types.BatchChainOperation{
+					AddOperation(types.BatchOperation{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Batch: []types.Operation{
+						Transactions: []types.Transaction{
 							{
 								Data:             []byte{0x01},
 								To:               "0xContractAddress",
@@ -181,9 +181,9 @@ func TestTimelockProposalBuilder(t *testing.T) {
 					SetDelay("invalid_duration").
 					AddChainMetadata(types.ChainSelector(SepoliaSelector), types.ChainMetadata{StartingOpCount: 0}).
 					SetTimelockAddress(types.ChainSelector(SepoliaSelector), "0xTimelockAddress").
-					AddTransaction(types.BatchChainOperation{
+					AddOperation(types.BatchOperation{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Batch: []types.Operation{
+						Transactions: []types.Transaction{
 							{
 								Data:             []byte{0x01},
 								To:               "0xContractAddress",
@@ -208,9 +208,9 @@ func TestTimelockProposalBuilder(t *testing.T) {
 					SetDelay("24h").
 					AddChainMetadata(types.ChainSelector(SepoliaSelector), types.ChainMetadata{StartingOpCount: 0}).
 					// Missing SetTimelockAddress
-					AddTransaction(types.BatchChainOperation{
+					AddOperation(types.BatchOperation{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Batch: []types.Operation{
+						Transactions: []types.Transaction{
 							{
 								Data:             []byte{0x01},
 								To:               "0xContractAddress",
@@ -239,7 +239,7 @@ func TestTimelockProposalBuilder(t *testing.T) {
 			},
 			want: nil,
 			wantErrs: []string{
-				"Key: 'TimelockProposal.Transactions' Error:Field validation for 'Transactions' failed on the 'min' tag",
+				"Key: 'TimelockProposal.Operations' Error:Field validation for 'Operations' failed on the 'min' tag",
 			},
 		},
 		{
@@ -253,9 +253,9 @@ func TestTimelockProposalBuilder(t *testing.T) {
 					SetDelay("24h").
 					AddChainMetadata(types.ChainSelector(SepoliaSelector), types.ChainMetadata{StartingOpCount: 0}).
 					SetTimelockAddress(types.ChainSelector(SepoliaSelector), "0xTimelockAddress").
-					AddTransaction(types.BatchChainOperation{
+					AddOperation(types.BatchOperation{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Batch: []types.Operation{
+						Transactions: []types.Transaction{
 							{
 								Data:             []byte{0x01},
 								To:               "0xContractAddress",
@@ -280,9 +280,9 @@ func TestTimelockProposalBuilder(t *testing.T) {
 					SetAction("invalid_action").
 					AddChainMetadata(types.ChainSelector(SepoliaSelector), types.ChainMetadata{StartingOpCount: 0}).
 					SetTimelockAddress(types.ChainSelector(SepoliaSelector), "0xTimelockAddress").
-					AddTransaction(types.BatchChainOperation{
+					AddOperation(types.BatchOperation{
 						ChainSelector: types.ChainSelector(SepoliaSelector),
-						Batch: []types.Operation{
+						Transactions: []types.Transaction{
 							{
 								Data: []byte{0x01},
 								To:   "0xContractAddress",

docs/_sidebar.md

@@ -1,8 +1,9 @@
 - [Key Concepts](/key-concepts.md)
   - [Configuration](key-concepts/configuration.md)
-  - [MCMS Proposal](key-concepts/mcms-proposal.md)
+  - [MCM Proposal](key-concepts/mcm-proposal.md)
   - [TimeLock Proposal](key-concepts/timelock-proposal.md)
-  - [Operations & Chain Metadata](key-concepts/operations-and-chain-metadata.md)
+  - [Chain Metadata](key-concepts/chain-metadata.md)
+  - [Operations](key-concepts/operations.md)
   - [Merkle Tree Signing](key-concepts/merkle.md)
   - [Chain Family SDK](key-concepts/chain-family-sdk.md ':disabled')
 - [Usage](/usage.md)

docs/key-concepts/chain-metadata.md

@@ -0,0 +1,35 @@
+# Chain Metadata
+
+Chain Metadata is shared across all proposal types and contains the information that allow transactions to be hashed and executed for it's respective chain. It is a map of chain-specific configuration for each blockchain involved in the proposal. The key of the object is the chain selector ID, and the value is the metadata object. An entry is required for every chain referenced in the proposal's operations.
+
+<!-- panels:start -->
+<!-- div:left-panel -->
+### Chain Metadata Structure
+
+```json
+{
+  "16015286601757825753": {
+    "startingOpCount": 1,
+    "mcmAddress": "0x0"
+  }
+}
+```
+
+<!-- div:right-panel -->
+
+### Chain Selector ID
+
+**Key** uint64<br/>
+The chain selector ID matching the chain based on the [Chain Selectors](https://github.com/smartcontractkit/chain-selectors) library.
+
+### Metadata Object
+
+**startingOpCount** uint64<br/>
+The starting operation count, typically used for parallel signing processes.
+
+---
+
+**mcmAddress** string<br/>
+The MCM contract address that will process this proposal on the respective chain.
+
+<!-- panels:end -->