Enable optional JSON-RPC parameter for state override (#346)

Author: hazim-j

.github/workflows/compliance.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v3
         with:
-          go-version: 1.19
+          go-version: "1.20"
           cache: true
 
       - name: Checkout bundler spec test

.github/workflows/core.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v3
         with:
-          go-version: 1.19
+          go-version: "1.20"
           cache: true
 
       - name: Install dependencies
@@ -36,7 +36,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v3
         with:
-          go-version: 1.19
+          go-version: "1.20"
           cache: true
 
       - name: Lint

.github/workflows/e2e.yml

@@ -44,7 +44,7 @@ jobs:
       - name: Use Go
         uses: actions/setup-go@v3
         with:
-          go-version: 1.19
+          go-version: "1.20"
           cache: true
 
       - name: Checkout account-abstraction

Dockerfile

@@ -1,4 +1,4 @@
-FROM golang:1.19-buster as builder
+FROM golang:1.20-buster as builder
 
 # Create and change to the app directory.
 WORKDIR /app

README.md

@@ -17,7 +17,7 @@ See the `Bundler` documentation at [docs.stackup.sh](https://docs.stackup.sh/doc
 
 ## Prerequisites
 
-- Go 1.19 or later
+- Go 1.20 or later
 - Access to a node with `debug` API enabled for custom tracing.
 
 ## Setup

go.mod

@@ -1,6 +1,6 @@
 module github.com/stackup-wallet/stackup-bundler
 
-go 1.19
+go 1.20
 
 require (
 	github.com/deckarep/golang-set/v2 v2.3.0

pkg/client/rpc.go

@@ -7,6 +7,12 @@ import (
 	"github.com/stackup-wallet/stackup-bundler/pkg/gas"
 )
 
+// Named UserOperation type for jsonrpc package.
+type userOperation map[string]any
+
+// Named StateOverride type for jsonrpc package.
+type optional_stateOverride map[string]any
+
 // RpcAdapter is an adapter for routing JSON-RPC method calls to the correct client functions.
 type RpcAdapter struct {
 	client *Client
@@ -19,12 +25,16 @@ func NewRpcAdapter(client *Client, debug *Debug) *RpcAdapter {
 }
 
 // Eth_sendUserOperation routes method calls to *Client.SendUserOperation.
-func (r *RpcAdapter) Eth_sendUserOperation(op map[string]any, ep string) (string, error) {
+func (r *RpcAdapter) Eth_sendUserOperation(op userOperation, ep string) (string, error) {
 	return r.client.SendUserOperation(op, ep)
 }
 
 // Eth_estimateUserOperationGas routes method calls to *Client.EstimateUserOperationGas.
-func (r *RpcAdapter) Eth_estimateUserOperationGas(op map[string]any, ep string) (*gas.GasEstimates, error) {
+func (r *RpcAdapter) Eth_estimateUserOperationGas(
+	op userOperation,
+	ep string,
+	ov optional_stateOverride,
+) (*gas.GasEstimates, error) {
 	return r.client.EstimateUserOperationGas(op, ep)
 }
 

pkg/jsonrpc/handler.go

@@ -7,13 +7,23 @@ import (
 	"io"
 	"net/http"
 	"reflect"
+	"strings"
 
 	"github.com/gin-gonic/gin"
 	"github.com/stackup-wallet/stackup-bundler/pkg/errors"
 	"golang.org/x/text/cases"
 	"golang.org/x/text/language"
 )
 
+var (
+	optionalTypePrefix = "optional_"
+)
+
+func formatConversionErrMsg(i int, call *reflect.Value) string {
+	s, _ := strings.CutPrefix(call.Type().In(i).Name(), optionalTypePrefix)
+	return fmt.Sprintf("Param [%d] can't be converted to %s", i, s)
+}
+
 func jsonrpcError(c *gin.Context, code int, message string, data any, id any) {
 	c.JSON(http.StatusOK, gin.H{
 		"jsonrpc": "2.0",
@@ -39,6 +49,27 @@ func parseRequestId(data map[string]any) (any, bool) {
 	return nil, false
 }
 
+// hasOptionalInput checks if the API method has defined an optional final input:
+//  1. The input must start with the "optional_" prefix in its name.
+//  2. The input must be of kind Map.
+func hasOptionalInput(numIn int, call *reflect.Value) bool {
+	return numIn > 0 &&
+		strings.HasPrefix(call.Type().In(numIn-1).Name(), optionalTypePrefix) &&
+		call.Type().In(numIn-1).Kind() == reflect.Map
+}
+
+// hasValidParamLength checks if the number of parameters in the request is correct:
+//  1. Ok if the number of params equals number of method inputs.
+//  2. Ok if optional input is defined and number of params is one less the number of method inputs.
+func hasValidParamLength(numParams, numIn int, hasOptional bool) bool {
+	return numParams == numIn || (hasOptional && numParams == numIn-1)
+}
+
+// isOptionalParamUndefined checks if the optional input has been left unset in the request.
+func isOptionalParamUndefined(numParams, numIn int, hasOptional bool) bool {
+	return hasOptional && numParams == numIn-1
+}
+
 // Controller returns a custom Gin middleware that handles incoming JSON-RPC requests via HTTP. It maps the
 // RPC method name to struct methods on the given api. For example, if the RPC request has the method field
 // set to "namespace_methodName" then the controller will make a call to api.Namespace_methodName with the
@@ -99,12 +130,19 @@ func Controller(api interface{}) gin.HandlerFunc {
 			return
 		}
 
-		if call.Type().NumIn() != len(params) {
+		numIn := call.Type().NumIn()
+		numParams := len(params)
+		hasOptional := hasOptionalInput(numIn, &call)
+		if !hasValidParamLength(numParams, numIn, hasOptional) {
 			jsonrpcError(c, -32602, "Invalid params", "Invalid number of params", &id)
 			return
 		}
+		if isOptionalParamUndefined(numParams, numIn, hasOptional) {
+			params = append(params, map[string]any{})
+			numParams++
+		}
 
-		args := make([]reflect.Value, len(params))
+		args := make([]reflect.Value, numParams)
 		for i, arg := range params {
 			switch call.Type().In(i).Kind() {
 			case reflect.Float32:
@@ -114,7 +152,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -128,7 +166,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -150,7 +188,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -171,7 +209,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -192,7 +230,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -213,7 +251,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -234,7 +272,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -251,7 +289,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -265,7 +303,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -279,7 +317,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -300,7 +338,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -321,7 +359,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -342,7 +380,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -363,7 +401,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return
@@ -384,7 +422,7 @@ func Controller(api interface{}) gin.HandlerFunc {
 						c,
 						-32602,
 						"Invalid params",
-						fmt.Sprintf("Param [%d] can't be converted to %v", i, call.Type().In(i).String()),
+						formatConversionErrMsg(i, &call),
 						&id,
 					)
 					return

pkg/state/override.go

@@ -0,0 +1,18 @@
+package state
+
+import (
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+)
+
+type OverrideAccount struct {
+	Nonce     *hexutil.Uint64              `json:"nonce"`
+	Code      *hexutil.Bytes               `json:"code"`
+	Balance   **hexutil.Big                `json:"balance"`
+	State     *map[common.Hash]common.Hash `json:"state"`
+	StateDiff *map[common.Hash]common.Hash `json:"stateDiff"`
+}
+
+// OverrideSet is a set of accounts with customized state that can be applied during eth_call or
+// debug_traceCall.
+type OverrideSet map[common.Address]OverrideAccount

pkg/userop/parse.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"math/big"
 	"reflect"
+	"strings"
 	"sync"
 
 	"github.com/ethereum/go-ethereum/common"
@@ -15,6 +16,9 @@ import (
 var (
 	validate = validator.New()
 	onlyOnce = sync.Once{}
+
+	replaceErrSubStrOld = "\n\n* ''"
+	replaceErrSubStrNew = " UserOperation"
 )
 
 func exactFieldMatch(mapKey, fieldName string) bool {
@@ -100,7 +104,7 @@ func New(data map[string]any) (*UserOperation, error) {
 		return nil, err
 	}
 	if err := decoder.Decode(data); err != nil {
-		return nil, err
+		return nil, errors.New(strings.Replace(err.Error(), replaceErrSubStrOld, replaceErrSubStrNew, 1))
 	}
 
 	// Validate struct