chore(examples): Allow custom queries in bindings

bindings/go/examples/custom_query/main.go

@@ -0,0 +1,49 @@
+// Copyright (c) 2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"fmt"
+	"log"
+
+	sdk "bindings/iota_sdk_ffi"
+)
+
+func main() {
+	client := sdk.GraphQlClientNewDevnet()
+
+	query := `
+	query CustomQuery($id: UInt53) {
+		epoch(id: $id) {
+			epochId
+			referenceGasPrice
+			totalGasFees
+			totalCheckpoints
+			totalTransactions
+		}
+	}`
+
+	variablesJson := `{"id": 1}`
+	variables := string(variablesJson)
+
+	payload1 := sdk.CustomQuery{
+		Query:     query,
+		Variables: &variables,
+	}
+	res1, err := client.RunCustomQuery(payload1)
+	if err.(*sdk.SdkFfiError) != nil {
+		log.Fatalf("Failed to perform a custom query: %v", err)
+	}
+	fmt.Println(res1)
+
+	payload2 := sdk.CustomQuery{
+		Query:     query,
+		Variables: nil,
+	}
+	res2, err := client.RunCustomQuery(payload2)
+	if err.(*sdk.SdkFfiError) != nil {
+		log.Fatalf("Failed to perform a custom query: %v", err)
+	}
+	fmt.Println(res2)
+}

bindings/go/iota_sdk_ffi/iota_sdk_ffi.go

@@ -1520,6 +1520,15 @@ func uniffiCheckChecksums() {
 	}
 	}
 	{
+	checksum := rustCall(func(_uniffiStatus *C.RustCallStatus) C.uint16_t {
+		return C.uniffi_iota_sdk_ffi_checksum_method_graphqlclient_run_custom_query()
+	})
+	if checksum != 28040 {
+		// If this happens try cleaning and rebuilding your project
+		panic("iota_sdk_ffi: uniffi_iota_sdk_ffi_checksum_method_graphqlclient_run_custom_query: UniFFI API checksum mismatch")
+	}
+	}
+	{
 	checksum := rustCall(func(_uniffiStatus *C.RustCallStatus) C.uint16_t {
 		return C.uniffi_iota_sdk_ffi_checksum_method_graphqlclient_service_config()
 	})
@@ -11397,6 +11406,8 @@ type GraphQlClientInterface interface {
 	// This will return `Ok(None)` if the epoch requested is not available in
 	// the GraphQL service (e.g., due to pruning).
 	ReferenceGasPrice(epoch *uint64) (*uint64, error)
+	// Run a custom query.
+	RunCustomQuery(query CustomQuery) (Value, error)
 	// Get the GraphQL service configuration, including complexity limits, read
 	// and mutation limits, supported versions, and others.
 	ServiceConfig() (ServiceConfig, error)
@@ -12615,6 +12626,38 @@ func (_self *GraphQlClient) ReferenceGasPrice(epoch *uint64) (*uint64, error) {
 	return res, err 
 }
 
+// Run a custom query.
+func (_self *GraphQlClient) RunCustomQuery(query CustomQuery) (Value, error) {
+	_pointer := _self.ffiObject.incrementPointer("*GraphQlClient")
+	defer _self.ffiObject.decrementPointer()
+	 res, err :=uniffiRustCallAsync[SdkFfiError](
+        FfiConverterSdkFfiErrorINSTANCE,
+		// completeFn
+		func(handle C.uint64_t, status *C.RustCallStatus) RustBufferI {
+			res := C.ffi_iota_sdk_ffi_rust_future_complete_rust_buffer(handle, status)
+			return GoRustBuffer {
+		inner: res,
+	}
+		},
+		// liftFn
+		func(ffi RustBufferI) Value {
+			return FfiConverterTypeValueINSTANCE.Lift(ffi)
+		},
+		C.uniffi_iota_sdk_ffi_fn_method_graphqlclient_run_custom_query(
+		_pointer,FfiConverterCustomQueryINSTANCE.Lower(query)),
+		// pollFn
+		func (handle C.uint64_t, continuation C.UniffiRustFutureContinuationCallback, data C.uint64_t) {
+			C.ffi_iota_sdk_ffi_rust_future_poll_rust_buffer(handle, continuation, data)
+		},
+		// freeFn
+		func (handle C.uint64_t) {
+			C.ffi_iota_sdk_ffi_rust_future_free_rust_buffer(handle)
+		},
+	)
+
+	return res, err 
+}
+
 // Get the GraphQL service configuration, including complexity limits, read
 // and mutation limits, supported versions, and others.
 func (_self *GraphQlClient) ServiceConfig() (ServiceConfig, error) {
@@ -23582,6 +23625,45 @@ type FfiDestroyerCoinPage struct {}
 func (_ FfiDestroyerCoinPage) Destroy(value CoinPage) {
 	value.Destroy()
 }
+type CustomQuery struct {
+	Query string
+	Variables *Value
+}
+
+func (r *CustomQuery) Destroy() {
+		FfiDestroyerString{}.Destroy(r.Query);
+		FfiDestroyerOptionalTypeValue{}.Destroy(r.Variables);
+}
+
+type FfiConverterCustomQuery struct {}
+
+var FfiConverterCustomQueryINSTANCE = FfiConverterCustomQuery{}
+
+func (c FfiConverterCustomQuery) Lift(rb RustBufferI) CustomQuery {
+	return LiftFromRustBuffer[CustomQuery](c, rb)
+}
+
+func (c FfiConverterCustomQuery) Read(reader io.Reader) CustomQuery {
+	return CustomQuery {
+			FfiConverterStringINSTANCE.Read(reader),
+			FfiConverterOptionalTypeValueINSTANCE.Read(reader),
+	}
+}
+
+func (c FfiConverterCustomQuery) Lower(value CustomQuery) C.RustBuffer {
+	return LowerIntoRustBuffer[CustomQuery](c, value)
+}
+
+func (c FfiConverterCustomQuery) Write(writer io.Writer, value CustomQuery) {
+		FfiConverterStringINSTANCE.Write(writer, value.Query);
+		FfiConverterOptionalTypeValueINSTANCE.Write(writer, value.Variables);
+}
+
+type FfiDestroyerCustomQuery struct {}
+
+func (_ FfiDestroyerCustomQuery) Destroy(value CustomQuery) {
+	value.Destroy()
+}
 // The result of a dry run, which includes the effects of the transaction and
 // any errors that may have occurred.
 type DryRunResult struct {

bindings/go/iota_sdk_ffi/iota_sdk_ffi.h

@@ -1771,6 +1771,11 @@ uint64_t uniffi_iota_sdk_ffi_fn_method_graphqlclient_protocol_config(void* ptr,
 uint64_t uniffi_iota_sdk_ffi_fn_method_graphqlclient_reference_gas_price(void* ptr, RustBuffer epoch
 );
 #endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_FN_METHOD_GRAPHQLCLIENT_RUN_CUSTOM_QUERY
+#define UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_FN_METHOD_GRAPHQLCLIENT_RUN_CUSTOM_QUERY
+uint64_t uniffi_iota_sdk_ffi_fn_method_graphqlclient_run_custom_query(void* ptr, RustBuffer query
+);
+#endif
 #ifndef UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_FN_METHOD_GRAPHQLCLIENT_SERVICE_CONFIG
 #define UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_FN_METHOD_GRAPHQLCLIENT_SERVICE_CONFIG
 uint64_t uniffi_iota_sdk_ffi_fn_method_graphqlclient_service_config(void* ptr
@@ -5716,6 +5721,12 @@ uint16_t uniffi_iota_sdk_ffi_checksum_method_graphqlclient_protocol_config(void
 #define UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_CHECKSUM_METHOD_GRAPHQLCLIENT_REFERENCE_GAS_PRICE
 uint16_t uniffi_iota_sdk_ffi_checksum_method_graphqlclient_reference_gas_price(void
 
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_CHECKSUM_METHOD_GRAPHQLCLIENT_RUN_CUSTOM_QUERY
+#define UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_CHECKSUM_METHOD_GRAPHQLCLIENT_RUN_CUSTOM_QUERY
+uint16_t uniffi_iota_sdk_ffi_checksum_method_graphqlclient_run_custom_query(void
+
 );
 #endif
 #ifndef UNIFFI_FFIDEF_UNIFFI_IOTA_SDK_FFI_CHECKSUM_METHOD_GRAPHQLCLIENT_SERVICE_CONFIG

bindings/kotlin/build.gradle.kts

@@ -1,5 +1,6 @@
 plugins {
     kotlin("jvm") version "1.9.24"
+    kotlin("plugin.serialization") version "1.9.24"
     application
 }
 
@@ -11,6 +12,7 @@ repositories { mavenCentral() }
 
 dependencies {
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
     implementation("net.java.dev.jna:jna:5.13.0")
 }
 

bindings/kotlin/examples/CustomQuery.kt

@@ -0,0 +1,36 @@
+// Copyright (c) 2025 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import iota_sdk.CustomQuery
+import iota_sdk.GraphQlClient
+import kotlinx.coroutines.runBlocking
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+
+fun main() = runBlocking {
+    val client = GraphQlClient.newDevnet()
+
+    val query =
+            """
+        query CustomQuery(${'$'}id: UInt53) {
+            epoch(id: ${'$'}id) {
+                epochId
+                referenceGasPrice
+                totalGasFees
+                totalCheckpoints
+                totalTransactions
+            }
+        }
+    """.trimIndent()
+
+    val variables = mapOf("id" to 1)
+    val jsonVariables = Json.encodeToString(variables)
+
+    val payload1 = CustomQuery(query = query, variables = jsonVariables)
+    val res1 = client.runCustomQuery(payload1)
+    println(res1)
+
+    val payload2 = CustomQuery(query = query, null)
+    val res2 = client.runCustomQuery(payload2)
+    println(res2)
+}

bindings/kotlin/lib/iota_sdk/iota_sdk_ffi.kt

@@ -2203,6 +2203,8 @@ internal interface UniffiForeignFutureCompleteVoid : com.sun.jna.Callback {
 
 
 
+
+
 
 
 
@@ -2479,6 +2481,8 @@ fun uniffi_iota_sdk_ffi_checksum_method_graphqlclient_protocol_config(
 ): Short
 fun uniffi_iota_sdk_ffi_checksum_method_graphqlclient_reference_gas_price(
 ): Short
+fun uniffi_iota_sdk_ffi_checksum_method_graphqlclient_run_custom_query(
+): Short
 fun uniffi_iota_sdk_ffi_checksum_method_graphqlclient_service_config(
 ): Short
 fun uniffi_iota_sdk_ffi_checksum_method_graphqlclient_set_rpc_server(
@@ -4098,6 +4102,8 @@ fun uniffi_iota_sdk_ffi_fn_method_graphqlclient_protocol_config(`ptr`: Pointer,`
 ): Long
 fun uniffi_iota_sdk_ffi_fn_method_graphqlclient_reference_gas_price(`ptr`: Pointer,`epoch`: RustBuffer.ByValue,
 ): Long
+fun uniffi_iota_sdk_ffi_fn_method_graphqlclient_run_custom_query(`ptr`: Pointer,`query`: RustBuffer.ByValue,
+): Long
 fun uniffi_iota_sdk_ffi_fn_method_graphqlclient_service_config(`ptr`: Pointer,
 ): Long
 fun uniffi_iota_sdk_ffi_fn_method_graphqlclient_set_rpc_server(`ptr`: Pointer,`server`: RustBuffer.ByValue,
@@ -5757,6 +5763,9 @@ private fun uniffiCheckApiChecksums(lib: IntegrityCheckingUniffiLib) {
     if (lib.uniffi_iota_sdk_ffi_checksum_method_graphqlclient_reference_gas_price() != 39065.toShort()) {
         throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
     }
+    if (lib.uniffi_iota_sdk_ffi_checksum_method_graphqlclient_run_custom_query() != 28040.toShort()) {
+        throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
+    }
     if (lib.uniffi_iota_sdk_ffi_checksum_method_graphqlclient_service_config() != 11931.toShort()) {
         throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
     }
@@ -19189,6 +19198,11 @@ public interface GraphQlClientInterface {
      */
     suspend fun `referenceGasPrice`(`epoch`: kotlin.ULong? = null): kotlin.ULong?
 
+    /**
+     * Run a custom query.
+     */
+    suspend fun `runCustomQuery`(`query`: CustomQuery): Value
+
     /**
      * Get the GraphQL service configuration, including complexity limits, read
      * and mutation limits, supported versions, and others.
@@ -20235,6 +20249,30 @@ open class GraphQlClient: Disposable, AutoCloseable, GraphQlClientInterface
     }
 
 
+    /**
+     * Run a custom query.
+     */
+    @Throws(SdkFfiException::class)
+    @Suppress("ASSIGNED_BUT_NEVER_ACCESSED_VARIABLE")
+    override suspend fun `runCustomQuery`(`query`: CustomQuery) : Value {
+        return uniffiRustCallAsync(
+        callWithPointer { thisPtr ->
+            UniffiLib.INSTANCE.uniffi_iota_sdk_ffi_fn_method_graphqlclient_run_custom_query(
+                thisPtr,
+                FfiConverterTypeCustomQuery.lower(`query`),
+            )
+        },
+        { future, callback, continuation -> UniffiLib.INSTANCE.ffi_iota_sdk_ffi_rust_future_poll_rust_buffer(future, callback, continuation) },
+        { future, continuation -> UniffiLib.INSTANCE.ffi_iota_sdk_ffi_rust_future_complete_rust_buffer(future, continuation) },
+        { future -> UniffiLib.INSTANCE.ffi_iota_sdk_ffi_rust_future_free_rust_buffer(future) },
+        // lift function
+        { FfiConverterTypeValue.lift(it) },
+        // Error FFI converter
+        SdkFfiException.ErrorHandler,
+    )
+    }
+
+
     /**
      * Get the GraphQL service configuration, including complexity limits, read
      * and mutation limits, supported versions, and others.
@@ -43268,6 +43306,38 @@ public object FfiConverterTypeCoinPage: FfiConverterRustBuffer<CoinPage> {
 
 
 
+data class CustomQuery (
+    var `query`: kotlin.String, 
+    var `variables`: Value?
+) {
+
+    companion object
+}
+
+/**
+ * @suppress
+ */
+public object FfiConverterTypeCustomQuery: FfiConverterRustBuffer<CustomQuery> {
+    override fun read(buf: ByteBuffer): CustomQuery {
+        return CustomQuery(
+            FfiConverterString.read(buf),
+            FfiConverterOptionalTypeValue.read(buf),
+        )
+    }
+
+    override fun allocationSize(value: CustomQuery) = (
+            FfiConverterString.allocationSize(value.`query`) +
+            FfiConverterOptionalTypeValue.allocationSize(value.`variables`)
+    )
+
+    override fun write(value: CustomQuery, buf: ByteBuffer) {
+            FfiConverterString.write(value.`query`, buf)
+            FfiConverterOptionalTypeValue.write(value.`variables`, buf)
+    }
+}
+
+
+
 /**
  * The result of a dry run, which includes the effects of the transaction and
  * any errors that may have occurred.

bindings/python/examples/coin_balances.py

@@ -5,6 +5,7 @@
 
 import asyncio
 
+
 async def main():
     client = GraphQlClient.new_devnet()