feat: new paymaster pkg. 2 out of 5 method implemented

Author: thiagodeev

internal/tests/tests.go

@@ -18,7 +18,9 @@ var TEST_ENV TestEnv
 type TestEnv string
 
 const (
-	MockEnv           TestEnv = "mock"
+	MockEnv TestEnv = "mock"
+	// Used to run account and rpc tests on the Integration network.
+	// Also, used to run paymaster tests with the Avnu Sepolia paymaster.
 	IntegrationEnv    TestEnv = "integration"
 	TestnetEnv        TestEnv = "testnet"
 	MainnetEnv        TestEnv = "mainnet"

paymaster/errors.go

@@ -0,0 +1,84 @@
+package paymaster
+
+import (
+	"github.com/NethermindEth/starknet.go/client/rpcerr"
+)
+
+// aliases to facilitate usage
+
+type (
+	RPCError      = rpcerr.RPCError
+	StringErrData = rpcerr.StringErrData
+)
+
+// Paymaster-specific errors based on SNIP-29 specification
+//
+//nolint:exhaustruct
+var (
+	ErrInvalidAddress = &RPCError{
+		Code:    150,
+		Message: "An error occurred (INVALID_ADDRESS)",
+	}
+
+	ErrTokenNotSupported = &RPCError{
+		Code:    151,
+		Message: "An error occurred (TOKEN_NOT_SUPPORTED)",
+	}
+
+	ErrInvalidSignature = &RPCError{
+		Code:    153,
+		Message: "An error occurred (INVALID_SIGNATURE)",
+	}
+
+	ErrMaxAmountTooLow = &RPCError{
+		Code:    154,
+		Message: "An error occurred (MAX_AMOUNT_TOO_LOW)",
+	}
+
+	ErrClassHashNotSupported = &RPCError{
+		Code:    155,
+		Message: "An error occurred (CLASS_HASH_NOT_SUPPORTED)",
+	}
+
+	ErrTransactionExecutionError = &RPCError{
+		Code:    156,
+		Message: "An error occurred (TRANSACTION_EXECUTION_ERROR)",
+		Data:    &TxnExecutionErrData{},
+	}
+
+	ErrInvalidTimeBounds = &RPCError{
+		Code:    157,
+		Message: "An error occurred (INVALID_TIME_BOUNDS)",
+	}
+
+	ErrInvalidDeploymentData = &RPCError{
+		Code:    158,
+		Message: "An error occurred (INVALID_DEPLOYMENT_DATA)",
+	}
+
+	ErrInvalidClassHash = &RPCError{
+		Code:    159,
+		Message: "An error occurred (INVALID_ADDRESS)",
+	}
+
+	ErrInvalidID = &RPCError{
+		Code:    160,
+		Message: "An error occurred (INVALID_ID)",
+	}
+
+	ErrUnknownError = &RPCError{
+		Code:    163,
+		Message: "An error occurred (UNKNOWN_ERROR)",
+		Data:    StringErrData(""),
+	}
+)
+
+// TxnExecutionErrData represents the structured data for TRANSACTION_EXECUTION_ERROR
+type TxnExecutionErrData struct {
+	ExecutionError string `json:"execution_error"`
+}
+
+// ErrorMessage implements the RPCData interface
+func (t TxnExecutionErrData) ErrorMessage() string {
+	return t.ExecutionError
+}

paymaster/get_tokens.go

@@ -0,0 +1,34 @@
+package paymaster
+
+import (
+	"context"
+
+	"github.com/NethermindEth/juno/core/felt"
+)
+
+// Get a list of the tokens that the paymaster supports, together with their prices in STRK
+//
+// Parameters:
+//   - ctx: The context.Context object for controlling the function call
+//
+// Returns:
+//   - []TokenData: An array of token data
+//   - error: An error if any
+func (p *Paymaster) GetSupportedTokens(ctx context.Context) ([]TokenData, error) {
+	var response []TokenData
+	if err := p.c.CallContextWithSliceArgs(ctx, &response, "paymaster_getSupportedTokens"); err != nil {
+		return nil, err
+	}
+
+	return response, nil
+}
+
+// Object containing data about the token: contract address, number of decimals and current price in STRK
+type TokenData struct {
+	// Token contract address
+	TokenAddress *felt.Felt `json:"token_address"`
+	// The number of decimals of the token
+	Decimals uint8 `json:"decimals"`
+	// Price in STRK (in FRI units)
+	PriceInStrk string `json:"price_in_strk"` // u256 as a hex string
+}

paymaster/get_tokens_test.go

@@ -0,0 +1,75 @@
+package paymaster
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/NethermindEth/starknet.go/internal/tests"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/mock/gomock"
+)
+
+// Test the 'paymaster_getSupportedTokens' method
+func TestGetSupportedTokens(t *testing.T) {
+	t.Parallel()
+	t.Run("integration", func(t *testing.T) {
+		tests.RunTestOn(t, tests.IntegrationEnv)
+		t.Parallel()
+
+		pm, spy := SetupPaymaster(t)
+		tokens, err := pm.GetSupportedTokens(context.Background())
+		require.NoError(t, err)
+
+		rawResult, err := json.Marshal(tokens)
+		require.NoError(t, err)
+		assert.EqualValues(t, spy.LastResponse(), rawResult)
+	})
+
+	t.Run("mock", func(t *testing.T) {
+		tests.RunTestOn(t, tests.MockEnv)
+		t.Parallel()
+
+		pm := SetupMockPaymaster(t)
+
+		expectedRawResult := `[
+			{
+				"token_address": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
+				"decimals": 18,
+				"price_in_strk": "0x288aa92ed8c5539ae80"
+			},
+			{
+				"token_address": "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
+				"decimals": 18,
+				"price_in_strk": "0xde0b6b3a7640000"
+			},
+			{
+				"token_address": "0x53b40a647cedfca6ca84f542a0fe36736031905a9639a7f19a3c1e66bfd5080",
+				"decimals": 6,
+				"price_in_strk": "0x48e1ecdbbe883b08"
+			},
+			{
+				"token_address": "0x30058f19ed447208015f6430f0102e8ab82d6c291566d7e73fe8e613c3d2ed",
+				"decimals": 6,
+				"price_in_strk": "0x2c3460a7992f8a"
+			}
+		]`
+
+		var expectedResult []TokenData
+		err := json.Unmarshal([]byte(expectedRawResult), &expectedResult)
+		require.NoError(t, err)
+
+		pm.c.EXPECT().
+			CallContextWithSliceArgs(context.Background(), gomock.AssignableToTypeOf(new([]TokenData)), "paymaster_getSupportedTokens").
+			SetArg(1, expectedResult).
+			Return(nil)
+		result, err := pm.GetSupportedTokens(context.Background())
+		assert.NoError(t, err)
+		assert.Equal(t, expectedResult, result)
+
+		rawResult, err := json.Marshal(result)
+		require.NoError(t, err)
+		assert.JSONEq(t, expectedRawResult, string(rawResult))
+	})
+}

paymaster/is_available.go

@@ -0,0 +1,21 @@
+package paymaster
+
+import "context"
+
+// IsAvailable returns the status of the paymaster service.
+// If the paymaster service is correctly functioning, return true. Else, return false
+//
+// Parameters:
+//   - ctx: The context.Context object for controlling the function call
+//
+// Returns:
+//   - bool: True if the paymaster service is correctly functioning, false otherwise
+//   - error: An error if any
+func (p *Paymaster) IsAvailable(ctx context.Context) (bool, error) {
+	var response bool
+	if err := p.c.CallContextWithSliceArgs(ctx, &response, "paymaster_isAvailable"); err != nil {
+		return false, err
+	}
+
+	return response, nil
+}

paymaster/is_available_test.go

@@ -0,0 +1,42 @@
+package paymaster
+
+import (
+	"context"
+	"strconv"
+	"testing"
+
+	"github.com/NethermindEth/starknet.go/internal/tests"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/mock/gomock"
+)
+
+// Test the 'paymaster_isAvailable' method
+func TestIsAvailable(t *testing.T) {
+	t.Parallel()
+	t.Run("integration", func(t *testing.T) {
+		tests.RunTestOn(t, tests.IntegrationEnv)
+		t.Parallel()
+
+		pm, spy := SetupPaymaster(t)
+		available, err := pm.IsAvailable(context.Background())
+		require.NoError(t, err)
+
+		assert.Equal(t, string(spy.LastResponse()), strconv.FormatBool(available))
+		assert.True(t, available)
+	})
+
+	t.Run("mock", func(t *testing.T) {
+		tests.RunTestOn(t, tests.MockEnv)
+		t.Parallel()
+
+		pm := SetupMockPaymaster(t)
+		pm.c.EXPECT().
+			CallContextWithSliceArgs(context.Background(), gomock.AssignableToTypeOf(new(bool)), "paymaster_isAvailable").
+			SetArg(1, true).
+			Return(nil)
+		available, err := pm.IsAvailable(context.Background())
+		assert.NoError(t, err)
+		assert.True(t, available)
+	})
+}

paymaster/main_test.go

@@ -0,0 +1,57 @@
+package paymaster
+
+import (
+	"os"
+	"testing"
+
+	"github.com/NethermindEth/starknet.go/client"
+	"github.com/NethermindEth/starknet.go/internal/tests"
+	"github.com/NethermindEth/starknet.go/mocks"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/mock/gomock"
+)
+
+const avnuPaymasterURL = "https://sepolia.paymaster.avnu.fi"
+
+func TestMain(m *testing.M) {
+	tests.LoadEnv()
+	os.Exit(m.Run())
+}
+
+type MockPaymaster struct {
+	*Paymaster
+	// this should be a pointer to the mock client used in the Paymaster struct.
+	// This is intended to have an easy access to the mock client, without having to
+	// type cast it from the `callCloser` interface every time.
+	c *mocks.MockClient
+}
+
+// Creates a real Sepolia paymaster client and a spy for integration tests.
+func SetupPaymaster(t *testing.T, debug ...bool) (*Paymaster, tests.Spyer) {
+	t.Helper()
+
+	apiKey := os.Getenv("AVNU_API_KEY")
+	require.NotEmpty(t, apiKey, "AVNU_API_KEY is not set")
+	apiHeader := client.WithHeader("x-paymaster-api-key", apiKey)
+
+	pm, err := New(avnuPaymasterURL, apiHeader)
+	require.NoError(t, err, "failed to create paymaster client")
+
+	spy := tests.NewJSONRPCSpy(pm.c, debug...)
+	pm.c = spy
+
+	return pm, spy
+}
+
+// Creates a mock paymaster client.
+func SetupMockPaymaster(t *testing.T) *MockPaymaster {
+	t.Helper()
+
+	pmClient := mocks.NewMockClient(gomock.NewController(t))
+	mpm := &MockPaymaster{
+		Paymaster: &Paymaster{c: pmClient},
+		c:         pmClient,
+	}
+
+	return mpm
+}

paymaster/paymaster.go

@@ -0,0 +1,62 @@
+package paymaster
+
+import (
+	"context"
+	"net/http"
+	"net/http/cookiejar"
+
+	"github.com/NethermindEth/starknet.go/client"
+	"golang.org/x/net/publicsuffix"
+)
+
+// Paymaster is a client for interacting with a paymaster service via the SNIP-29 API.
+// It provides methods to build and execute transactions, check service status, and track transaction status.
+type Paymaster struct {
+	// c is the underlying client for the paymaster service.
+	c callCloser
+}
+
+// Used to assert that the Paymaster struct implements all the paymaster methods.
+// Ref: https://github.com/starknet-io/SNIPs/blob/ea46a8777d8c8d53a43f45b7beb1abcc301a1a69/assets/snip-29/paymaster_api.json
+type paymasterInterface interface {
+	IsAvailable(ctx context.Context) (bool, error)
+	GetSupportedTokens(ctx context.Context) ([]TokenData, error)
+}
+
+var _ paymasterInterface = &Paymaster{} //nolint:exhaustruct
+
+// callCloser is an interface that defines the methods for calling a remote procedure.
+// It was created to match the Client struct from the 'client' package.
+type callCloser interface {
+	CallContext(ctx context.Context, result interface{}, method string, args interface{}) error
+	CallContextWithSliceArgs(ctx context.Context, result interface{}, method string, args ...interface{}) error
+	Close()
+}
+
+// Creates a new paymaster client for the given service URL.
+// Additional options can be passed to the client to configure the connection.
+//
+// Parameters:
+//   - url: The URL of the paymaster service
+//   - options: Additional options to configure the client
+//
+// Returns:
+//   - *Paymaster: A new paymaster client instance
+//   - error: An error if the client creation fails
+func New(url string, options ...client.ClientOption) (*Paymaster, error) {
+	jar, err := cookiejar.New(&cookiejar.Options{PublicSuffixList: publicsuffix.List})
+	if err != nil {
+		return nil, err
+	}
+	httpClient := &http.Client{Jar: jar} //nolint:exhaustruct
+	// prepend the custom client to allow users to override
+	options = append([]client.ClientOption{client.WithHTTPClient(httpClient)}, options...)
+	c, err := client.DialOptions(context.Background(), url, options...)
+	if err != nil {
+		return nil, err
+	}
+
+	paymaster := &Paymaster{c: c}
+
+	return paymaster, nil
+}