feat: introduce rpc client logic and examples

CHANGELOG.md

@@ -1,6 +1,5 @@
 # @openzeppelin/relayer-sdk
 
-
 ## 1.6.0 (2025-09-30)
 
 - feat: add plugin error types ([#206](https://github.com/OpenZeppelin/openzeppelin-relayer-sdk/pull/206))

custom-models/plugin-api.ts

@@ -9,12 +9,14 @@
  * normalized to relative paths when copied by scripts/post-generate.js
  */
 
+import { ApiResponseRelayerResponseData } from '../src/models/api-response-relayer-response-data';
+import { ApiResponseRelayerStatusData } from '../src/models/api-response-relayer-status-data';
+import { JsonRpcRequestNetworkRpcRequest } from '../src/models/json-rpc-request-network-rpc-request';
+import { JsonRpcResponseNetworkRpcResult } from '../src/models/json-rpc-response-network-rpc-result';
 import { NetworkTransactionRequest } from '../src/models/network-transaction-request';
-import { TransactionResponse } from '../src/models/transaction-response';
 import { SignTransactionRequest } from '../src/models/sign-transaction-request';
 import { SignTransactionResponse } from '../src/models/sign-transaction-response';
-import { ApiResponseRelayerResponseData } from '../src/models/api-response-relayer-response-data';
-import { ApiResponseRelayerStatusData } from '../src/models/api-response-relayer-status-data';
+import { TransactionResponse } from '../src/models/transaction-response';
 
 /**
  * The result of a sendTransaction call.
@@ -107,6 +109,13 @@ export type Relayer = {
    * @returns The signed transaction XDR and signature.
    */
   signTransaction: (payload: SignTransactionRequest) => Promise<SignTransactionResponse>;
+
+  /**
+   * Performs an RPC call to the relayer.
+   * @param payload - The RPC request payload.
+   * @returns The RPC response.
+   */
+  rpc: (payload: JsonRpcRequestNetworkRpcRequest) => Promise<JsonRpcResponseNetworkRpcResult>;
 };
 
 export interface PluginKVStore {

custom-models/solana-rpc-result.ts

@@ -27,38 +27,42 @@ import type { SignTransactionResult } from './sign-transaction-result';
 import type { TransferTransactionResult } from './transfer-transaction-result';
 
 type TransferTransactionResultWithMethod = TransferTransactionResult & {
-    method: 'transferTransaction';
-}
+  method: 'transferTransaction';
+};
 
 type FeeEstimateResultWithMethod = FeeEstimateResult & {
-    method: 'feeEstimate';
-}
+  method: 'feeEstimate';
+};
 
 type GetFeaturesEnabledResultWithMethod = GetFeaturesEnabledResult & {
-    method: 'getFeaturesEnabled';
-}
+  method: 'getFeaturesEnabled';
+};
 
 type PrepareTransactionResultWithMethod = PrepareTransactionResult & {
-    method: 'prepareTransaction';
-}
+  method: 'prepareTransaction';
+};
 
 type GetSupportedTokensResultWithMethod = GetSupportedTokensResult & {
-    method: 'getSupportedTokens';
-}
+  method: 'getSupportedTokens';
+};
 
 type SignAndSendTransactionResultWithMethod = SignAndSendTransactionResult & {
-    method: 'signAndSendTransaction';
-}
+  method: 'signAndSendTransaction';
+};
 
 type SignTransactionResultWithMethod = SignTransactionResult & {
-    method: 'signTransaction';
-}
-
-
+  method: 'signTransaction';
+};
 
 /**
  * @type SolanaRpcResult
  * @export
  */
-export type SolanaRpcResult = FeeEstimateResultWithMethod | GetFeaturesEnabledResultWithMethod | GetSupportedTokensResultWithMethod | PrepareTransactionResultWithMethod | SignAndSendTransactionResultWithMethod | SignTransactionResultWithMethod | TransferTransactionResultWithMethod;
-
+export type SolanaRpcResult =
+  | FeeEstimateResultWithMethod
+  | GetFeaturesEnabledResultWithMethod
+  | GetSupportedTokensResultWithMethod
+  | PrepareTransactionResultWithMethod
+  | SignAndSendTransactionResultWithMethod
+  | SignTransactionResultWithMethod
+  | TransferTransactionResultWithMethod;

docs/.openapi-generator/FILES

@@ -10,8 +10,8 @@ Models/ApiResponse_DeletePendingTransactionsResponse.md
 Models/ApiResponse_DeletePendingTransactionsResponse_data.md
 Models/ApiResponse_NotificationResponse.md
 Models/ApiResponse_NotificationResponse_data.md
-Models/ApiResponse_PluginCallResponse.md
-Models/ApiResponse_PluginCallResponse_data.md
+Models/ApiResponse_PluginHandlerError.md
+Models/ApiResponse_PluginHandlerError_data.md
 Models/ApiResponse_RelayerResponse.md
 Models/ApiResponse_RelayerResponse_data.md
 Models/ApiResponse_RelayerStatus.md
@@ -28,6 +28,7 @@ Models/ApiResponse_SignerResponse_data.md
 Models/ApiResponse_String.md
 Models/ApiResponse_TransactionResponse.md
 Models/ApiResponse_TransactionResponse_data.md
+Models/ApiResponse_Value.md
 Models/ApiResponse_Vec_NotificationResponse.md
 Models/ApiResponse_Vec_RelayerResponse.md
 Models/ApiResponse_Vec_SignerResponse.md
@@ -53,10 +54,16 @@ Models/CreateRelayerPolicyRequest_oneOf_1.md
 Models/CreateRelayerPolicyRequest_oneOf_2.md
 Models/CreateRelayerRequest.md
 Models/DeletePendingTransactionsResponse.md
+Models/DisabledReason.md
+Models/DisabledReason_oneOf.md
+Models/DisabledReason_oneOf_1.md
+Models/DisabledReason_oneOf_2.md
+Models/DisabledReason_oneOf_3.md
+Models/DisabledReason_oneOf_4.md
 Models/EvmPolicyResponse.md
 Models/EvmRpcRequest.md
 Models/EvmRpcRequest_oneOf.md
-Models/EvmRpcRequest_oneOf_1.md
+Models/EvmRpcResult.md
 Models/EvmTransactionDataSignature.md
 Models/EvmTransactionRequest.md
 Models/EvmTransactionResponse.md
@@ -100,7 +107,8 @@ Models/OperationSpec_oneOf_2.md
 Models/OperationSpec_oneOf_3.md
 Models/PaginationMeta.md
 Models/PluginCallRequest.md
-Models/PluginCallResponse.md
+Models/PluginHandlerError.md
+Models/PluginMetadata.md
 Models/PrepareTransactionRequestParams.md
 Models/PrepareTransactionResult.md
 Models/RelayerEvmPolicy.md
@@ -153,6 +161,8 @@ Models/SolanaRpcRequest_oneOf_3.md
 Models/SolanaRpcRequest_oneOf_4.md
 Models/SolanaRpcRequest_oneOf_5.md
 Models/SolanaRpcRequest_oneOf_6.md
+Models/SolanaRpcRequest_oneOf_7.md
+Models/SolanaRpcRequest_oneOf_7_params.md
 Models/SolanaRpcResult.md
 Models/SolanaRpcResult_oneOf.md
 Models/SolanaRpcResult_oneOf_1.md
@@ -161,6 +171,7 @@ Models/SolanaRpcResult_oneOf_3.md
 Models/SolanaRpcResult_oneOf_4.md
 Models/SolanaRpcResult_oneOf_5.md
 Models/SolanaRpcResult_oneOf_6.md
+Models/SolanaRpcResult_oneOf_7.md
 Models/SolanaSwapStrategy.md
 Models/SolanaTransactionRequest.md
 Models/SolanaTransactionResponse.md

docs/Apis/PluginsApi.md

@@ -4,14 +4,16 @@ All URIs are relative to *http://localhost*
 
 | Method | HTTP request | Description |
 |------------- | ------------- | -------------|
-| [**callPlugin**](PluginsApi.md#callPlugin) | **POST** /api/v1/plugins/{plugin_id}/call | Calls a plugin method. |
+| [**callPlugin**](PluginsApi.md#callPlugin) | **POST** /api/v1/plugins/{plugin_id}/call | Execute a plugin and receive the sanitized result |
 
 
 <a name="callPlugin"></a>
 # **callPlugin**
-> ApiResponse_PluginCallResponse callPlugin(plugin\_id, PluginCallRequest)
+> ApiResponse_Value callPlugin(plugin\_id, PluginCallRequest)
 
-Calls a plugin method.
+Execute a plugin and receive the sanitized result
+
+    Logs and traces are only returned when the plugin is configured with &#x60;emit_logs&#x60; / &#x60;emit_traces&#x60;. Plugin-provided errors are normalized into a consistent payload (&#x60;code&#x60;, &#x60;details&#x60;) and a derived message so downstream clients receive a stable shape regardless of how the handler threw.
 
 ### Parameters
 
@@ -22,7 +24,7 @@ Calls a plugin method.
 
 ### Return type
 
-[**ApiResponse_PluginCallResponse**](../Models/ApiResponse_PluginCallResponse.md)
+[**ApiResponse_Value**](../Models/ApiResponse_Value.md)
 
 ### Authorization
 

docs/Apis/SignersApi.md

@@ -116,7 +116,7 @@ Signer routes implementation
 
 <a name="updateSigner"></a>
 # **updateSigner**
-> ApiResponse_SignerResponse updateSigner(signer\_id, body)
+> ApiResponse_SignerResponse updateSigner(signer\_id, request\_body)
 
 Updates an existing signer.
 
@@ -125,7 +125,7 @@ Updates an existing signer.
 |Name | Type | Description  | Notes |
 |------------- | ------------- | ------------- | -------------|
 | **signer\_id** | **String**| Signer ID | [default to null] |
-| **body** | **Object**|  | |
+| **request\_body** | [**Map**](../Models/AnyType.md)|  | |
 
 ### Return type
 

docs/Models/ApiResponse_BalanceResponse.md

@@ -5,6 +5,7 @@
 |------------ | ------------- | ------------- | -------------|
 | **data** | [**ApiResponse_BalanceResponse_data**](ApiResponse_BalanceResponse_data.md) |  | [optional] [default to null] |
 | **error** | **String** |  | [optional] [default to null] |
+| **metadata** | [**PluginMetadata**](PluginMetadata.md) |  | [optional] [default to null] |
 | **pagination** | [**PaginationMeta**](PaginationMeta.md) |  | [optional] [default to null] |
 | **success** | **Boolean** |  | [default to null] |
 

docs/Models/ApiResponse_DeletePendingTransactionsResponse.md

@@ -5,6 +5,7 @@
 |------------ | ------------- | ------------- | -------------|
 | **data** | [**ApiResponse_DeletePendingTransactionsResponse_data**](ApiResponse_DeletePendingTransactionsResponse_data.md) |  | [optional] [default to null] |
 | **error** | **String** |  | [optional] [default to null] |
+| **metadata** | [**PluginMetadata**](PluginMetadata.md) |  | [optional] [default to null] |
 | **pagination** | [**PaginationMeta**](PaginationMeta.md) |  | [optional] [default to null] |
 | **success** | **Boolean** |  | [default to null] |
 

docs/Models/ApiResponse_NotificationResponse.md

@@ -5,6 +5,7 @@
 |------------ | ------------- | ------------- | -------------|
 | **data** | [**ApiResponse_NotificationResponse_data**](ApiResponse_NotificationResponse_data.md) |  | [optional] [default to null] |
 | **error** | **String** |  | [optional] [default to null] |
+| **metadata** | [**PluginMetadata**](PluginMetadata.md) |  | [optional] [default to null] |
 | **pagination** | [**PaginationMeta**](PaginationMeta.md) |  | [optional] [default to null] |
 | **success** | **Boolean** |  | [default to null] |
 

docs/Models/ApiResponse_PluginHandlerError.md

@@ -0,0 +1,13 @@
+# ApiResponse_PluginHandlerError
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **data** | [**ApiResponse_PluginHandlerError_data**](ApiResponse_PluginHandlerError_data.md) |  | [optional] [default to null] |
+| **error** | **String** |  | [optional] [default to null] |
+| **metadata** | [**PluginMetadata**](PluginMetadata.md) |  | [optional] [default to null] |
+| **pagination** | [**PaginationMeta**](PaginationMeta.md) |  | [optional] [default to null] |
+| **success** | **Boolean** |  | [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

docs/Models/ApiResponse_PluginHandlerError_data.md

@@ -0,0 +1,10 @@
+# ApiResponse_PluginHandlerError_data
+## Properties
+
+| Name | Type | Description | Notes |
+|------------ | ------------- | ------------- | -------------|
+| **code** | **String** |  | [optional] [default to null] |
+| **details** | [**oas_any_type_not_mapped**](.md) |  | [optional] [default to null] |
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+

docs/Models/ApiResponse_RelayerResponse.md

@@ -5,6 +5,7 @@
 |------------ | ------------- | ------------- | -------------|
 | **data** | [**ApiResponse_RelayerResponse_data**](ApiResponse_RelayerResponse_data.md) |  | [optional] [default to null] |
 | **error** | **String** |  | [optional] [default to null] |
+| **metadata** | [**PluginMetadata**](PluginMetadata.md) |  | [optional] [default to null] |
 | **pagination** | [**PaginationMeta**](PaginationMeta.md) |  | [optional] [default to null] |
 | **success** | **Boolean** |  | [default to null] |
 

docs/Models/ApiResponse_RelayerResponse_data.md

@@ -5,6 +5,7 @@
 |------------ | ------------- | ------------- | -------------|
 | **address** | **String** |  | [optional] [default to null] |
 | **custom\_rpc\_urls** | [**List**](RpcConfig.md) |  | [optional] [default to null] |
+| **disabled\_reason** | [**DisabledReason**](DisabledReason.md) |  | [optional] [default to null] |
 | **id** | **String** |  | [default to null] |
 | **name** | **String** |  | [default to null] |
 | **network** | **String** |  | [default to null] |

docs/Models/ApiResponse_RelayerStatus.md

@@ -5,6 +5,7 @@
 |------------ | ------------- | ------------- | -------------|
 | **data** | [**ApiResponse_RelayerStatus_data**](ApiResponse_RelayerStatus_data.md) |  | [optional] [default to null] |
 | **error** | **String** |  | [optional] [default to null] |
+| **metadata** | [**PluginMetadata**](PluginMetadata.md) |  | [optional] [default to null] |
 | **pagination** | [**PaginationMeta**](PaginationMeta.md) |  | [optional] [default to null] |
 | **success** | **Boolean** |  | [default to null] |
 

docs/Models/ApiResponse_SignDataResponse.md

@@ -5,6 +5,7 @@
 |------------ | ------------- | ------------- | -------------|
 | **data** | [**ApiResponse_SignDataResponse_data**](ApiResponse_SignDataResponse_data.md) |  | [optional] [default to null] |
 | **error** | **String** |  | [optional] [default to null] |
+| **metadata** | [**PluginMetadata**](PluginMetadata.md) |  | [optional] [default to null] |
 | **pagination** | [**PaginationMeta**](PaginationMeta.md) |  | [optional] [default to null] |
 | **success** | **Boolean** |  | [default to null] |
 

docs/Models/ApiResponse_SignTransactionResponse.md

@@ -5,6 +5,7 @@
 |------------ | ------------- | ------------- | -------------|
 | **data** | [**ApiResponse_SignTransactionResponse_data**](ApiResponse_SignTransactionResponse_data.md) |  | [optional] [default to null] |
 | **error** | **String** |  | [optional] [default to null] |
+| **metadata** | [**PluginMetadata**](PluginMetadata.md) |  | [optional] [default to null] |
 | **pagination** | [**PaginationMeta**](PaginationMeta.md) |  | [optional] [default to null] |
 | **success** | **Boolean** |  | [default to null] |
 

docs/Models/ApiResponse_SignerResponse.md

@@ -5,6 +5,7 @@
 |------------ | ------------- | ------------- | -------------|
 | **data** | [**ApiResponse_SignerResponse_data**](ApiResponse_SignerResponse_data.md) |  | [optional] [default to null] |
 | **error** | **String** |  | [optional] [default to null] |
+| **metadata** | [**PluginMetadata**](PluginMetadata.md) |  | [optional] [default to null] |
 | **pagination** | [**PaginationMeta**](PaginationMeta.md) |  | [optional] [default to null] |
 | **success** | **Boolean** |  | [default to null] |
 

docs/Models/ApiResponse_String.md

@@ -5,6 +5,7 @@
 |------------ | ------------- | ------------- | -------------|
 | **data** | **String** |  | [optional] [default to null] |
 | **error** | **String** |  | [optional] [default to null] |
+| **metadata** | [**PluginMetadata**](PluginMetadata.md) |  | [optional] [default to null] |
 | **pagination** | [**PaginationMeta**](PaginationMeta.md) |  | [optional] [default to null] |
 | **success** | **Boolean** |  | [default to null] |