feat: Extend #[export] with per-function transport/encoding opt-in (scale and ethabi) (#1303)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: vobradovich

Cargo.lock

@@ -623,13 +623,23 @@ The `ethexe` cargo feature enables several features:
 When this feature is active:
 
 - Identifiers for **program constructors** and **exposed service constructors** (methods within a `#[program]` block that return a service) are validated against Solidity reserved keywords. Using a reserved name for these (e.g., `new` for a program constructor, or `function` for an exposed service constructor) will result in a compilation error, preventing naming conflicts in the generated Solidity interface. The comprehensive list of these reserved keywords can be found in the [source code](rs/macros/core/src/shared.rs) (see the `SOL_KEYWORDS` constant).
-- The `#[export]` macro accepts a `payable` argument (`#[export(payable)]`). This allows service methods and program constructors to accept value with a message. If a non-payable method or constructor receives value, the execution will panic.
+- The `#[export]` macro supports **transport selection** and `payable` methods via its arguments:
+  - `#[export(scale)]` — expose the method only through the Gear/SCALE dispatch path.
+  - `#[export(ethabi)]` — expose the method only through the Solidity ABI dispatch path.
+  - `#[export(scale, ethabi)]` — expose through both paths (same as bare `#[export]`).
+  - `#[export(payable)]` or `#[export(ethabi, payable)]` — mark the method as payable. `payable` requires `ethabi` transport; writing `#[export(scale, payable)]` is a compile error.
+
+  Transport flags control **runtime dispatch visibility only**. All exported methods remain in the service's IDL metadata, interface hash, and method metadata regardless of their transport selection. Single-transport methods receive a `@codec: scale` or `@codec: ethabi` annotation in the generated IDL.
+
+  Without the `ethexe` feature, only `#[export]` and `#[export(scale)]` are accepted; the `ethabi` and `payable` flags are unavailable.
+
+  Ethabi-only methods (`#[export(ethabi)]`) do not require their parameter and return types to implement SCALE `Encode`/`Decode`, allowing the use of ABI-native types such as `alloy_primitives::Address` and `alloy_primitives::B256`.
 
 > **NOTE**
 >
 > The accepted value (tokens) depends on whether the `ethexe` feature is enabled. Without the feature, these are native VARA tokens; with the feature, these are ETH.
 
-- The generated IDL is enhanced with structured annotations to signify payable methods, methods that return value, and indexed event fields. Specifically, methods marked with `#[export(payable)]` will have an `@payable` annotation, and methods returning `CommandReply<T>` will have a `@returns_value` annotation. Additionally, event fields marked with `#[indexed]` will have an `@indexed` annotation. This metadata is necessary for the correct generation of Solidity interfaces via the `sails-sol-gen` crate.
+- The generated IDL is enhanced with structured annotations to signify payable methods, methods that return value, transport-restricted methods, and indexed event fields. Specifically, methods marked with `#[export(payable)]` will have an `@payable` annotation, methods returning `CommandReply<T>` will have a `@returns_value` annotation, and single-transport methods will have a `@codec: scale` or `@codec: ethabi` annotation. Additionally, event fields marked with `#[indexed]` will have an `@indexed` annotation. This metadata is necessary for the correct generation of Solidity interfaces via the `sails-sol-gen` crate.
 
 Here is an example demonstrating these features:
 
@@ -673,16 +683,30 @@ pub struct SomeService;
 
 #[service(events = MyEvent)]
 impl SomeService {
+    // Available through both SCALE and Solidity ABI dispatch (default)
     #[export]
     pub async fn do_this(&mut self, p1: u32, _p2: String) -> u32 {
         p1
     }
 
+    // Payable method, available through both dispatch paths
     #[export(payable)]
     pub fn do_this_payable(&mut self, p1: u32) -> u32 {
         p1
     }
 
+    // SCALE dispatch only — not exposed to Solidity callers
+    #[export(scale)]
+    pub fn gear_only(&self) -> u32 {
+        42
+    }
+
+    // Solidity ABI dispatch only — not exposed to Gear/SCALE callers
+    #[export(ethabi)]
+    pub fn eth_only(&self) -> u32 {
+        42
+    }
+
     // This method implicitly `returns_value` because of its return type
     #[export]
     pub fn withdraw(&mut self, amount: u64) -> CommandReply<()> {
@@ -692,6 +716,7 @@ impl SomeService {
 ```
 
 In the example above, `create_payable` is a payable constructor, and `do_this_payable` is a payable service method.
+The `gear_only` method is only reachable via Gear/SCALE messages, while `eth_only` is only reachable via Solidity ABI calls. Both still appear in the service's IDL and contribute to its interface hash.
 The `withdraw` method will have the `@returns_value` annotation in the IDL, and `from` and `to` fields in `MyEvent` will have `@indexed` annotations.
 For more details, you can refer to the full example at [`rs/ethexe/ethapp/src/lib.rs`](rs/ethexe/ethapp/src/lib.rs).
 

README.md

@@ -61,6 +61,8 @@ ethexe = [
     "dep:alloy-primitives",
     "dep:alloy-sol-types",
     "sails-macros/ethexe",
+    "sails-reflect-hash/alloy-primitives",
+    "sails-type-registry/alloy-primitives",
 ]
 gclient = ["dep:gclient", "dep:tokio-stream"]
 gstd = ["dep:gstd", "dep:gear-core"]

rs/Cargo.toml

@@ -24,6 +24,109 @@ fn works_with_basics() {
     insta::assert_snapshot!(result);
 }
 
+#[test]
+fn works_with_explicit_scale_only() {
+    let input = quote! {
+        impl SomeService {
+            #[export(scale)]
+            pub fn scale_method(&self, p1: u32) -> u32 {
+                p1
+            }
+        }
+    };
+
+    let result = gservice(TokenStream::new(), input).to_string();
+    let result = prettyplease::unparse(&syn::parse_str(&result).unwrap());
+
+    insta::assert_snapshot!(result);
+}
+
+#[test]
+fn works_with_explicit_ethabi_only() {
+    let input = quote! {
+        impl SomeService {
+            #[export(ethabi)]
+            pub fn ethabi_method(&self, p1: u32) -> u32 {
+                p1
+            }
+        }
+    };
+
+    let result = gservice(TokenStream::new(), input).to_string();
+    let result = prettyplease::unparse(&syn::parse_str(&result).unwrap());
+
+    insta::assert_snapshot!(result);
+}
+
+#[test]
+fn works_with_explicit_dual_export() {
+    let input = quote! {
+        impl SomeService {
+            #[export(scale, ethabi)]
+            pub fn dual_method(&self, p1: u32) -> u32 {
+                p1
+            }
+        }
+    };
+
+    let result = gservice(TokenStream::new(), input).to_string();
+    let result = prettyplease::unparse(&syn::parse_str(&result).unwrap());
+
+    insta::assert_snapshot!(result);
+}
+
+#[test]
+fn works_with_mixed_transports() {
+    let input = quote! {
+        impl SomeService {
+            #[export(scale)]
+            pub fn scale_only(&self, p1: u32) -> u32 {
+                p1
+            }
+
+            #[export(ethabi)]
+            pub fn ethabi_only(&self, p1: u32) -> u32 {
+                p1
+            }
+
+            #[export(scale, ethabi)]
+            pub fn dual(&self, p1: u32) -> u32 {
+                p1
+            }
+
+            #[export]
+            pub fn default_both(&self, p1: u32) -> u32 {
+                p1
+            }
+        }
+    };
+
+    let result = gservice(TokenStream::new(), input).to_string();
+    let result = prettyplease::unparse(&syn::parse_str(&result).unwrap());
+
+    insta::assert_snapshot!(result);
+}
+
+#[test]
+fn works_with_ethabi_only_non_scale_type() {
+    let input = quote! {
+        impl SomeService {
+            #[export(ethabi)]
+            pub fn abi_method(
+                &self,
+                addr: sails_rs::alloy_primitives::Address,
+            ) -> sails_rs::alloy_primitives::B256 {
+                sails_rs::alloy_primitives::B256::ZERO
+            }
+        }
+    };
+
+    let result = gservice(TokenStream::new(), input).to_string();
+    let result = prettyplease::unparse(&syn::parse_str(&result).unwrap());
+
+    insta::assert_snapshot!(result);
+}
+
 #[test]
 fn works_with_lifetimes_and_generics() {
     let input = quote! {

rs/ethexe/Cargo.lock

@@ -15,6 +15,7 @@ mod service_with_extends_and_lifetimes;
 mod service_with_lifecycles_and_generics;
 mod service_with_reply_with_value;
 mod service_with_trait_bounds;
+mod service_with_transport_selection;
 
 #[tokio::test]
 async fn service_with_basics() {
@@ -324,3 +325,67 @@ async fn service_with_trait_bounds() {
     let result = sails_rs::alloy_sol_types::SolValue::abi_decode(output.as_slice());
     assert_eq!(Ok(42u32), result);
 }
+
+#[test]
+fn service_transport_selection_runtime_dispatch() {
+    use sails_rs::{
+        Encode,
+        alloy_sol_types::SolValue,
+        gstd::services::Service,
+        meta::{Identifiable, ServiceMeta, find_method_data},
+    };
+    use service_with_transport_selection::MyService;
+
+    fn ignore_result(_: &[u8], _: u128) {}
+
+    let methods = <MyService as ServiceMeta>::METHODS;
+    let scale_only = find_method_data(methods, "ScaleOnly", None)
+        .unwrap()
+        .entry_id;
+    let ethabi_only = find_method_data(methods, "EthabiOnly", None)
+        .unwrap()
+        .entry_id;
+    let dual = find_method_data(methods, "Dual", None).unwrap().entry_id;
+    let interface_id = <MyService as Identifiable>::INTERFACE_ID;
+
+    let scale_input = 7u32.encode();
+    let abi_input = (false, 7u32).abi_encode_sequence();
+
+    assert!(
+        MyService
+            .expose(1)
+            .try_handle(interface_id, scale_only, &scale_input, ignore_result)
+            .is_some()
+    );
+    assert!(
+        MyService
+            .expose(1)
+            .try_handle(interface_id, ethabi_only, &scale_input, ignore_result)
+            .is_none()
+    );
+    assert!(
+        MyService
+            .expose(1)
+            .try_handle(interface_id, dual, &scale_input, ignore_result)
+            .is_some()
+    );
+
+    assert!(
+        MyService
+            .expose(1)
+            .try_handle_solidity(interface_id, scale_only, &abi_input)
+            .is_none()
+    );
+    assert!(
+        MyService
+            .expose(1)
+            .try_handle_solidity(interface_id, ethabi_only, &abi_input)
+            .is_some()
+    );
+    assert!(
+        MyService
+            .expose(1)
+            .try_handle_solidity(interface_id, dual, &abi_input)
+            .is_some()
+    );
+}

rs/ethexe/macros-tests/tests/service_insta.rs

@@ -0,0 +1,21 @@
+use sails_rs::prelude::*;
+
+pub struct MyService;
+
+#[sails_rs::service]
+impl MyService {
+    #[export(scale)]
+    pub fn scale_only(&self, p1: u32) -> u32 {
+        p1 + 1
+    }
+
+    #[export(ethabi)]
+    pub fn ethabi_only(&self, p1: u32) -> u32 {
+        p1 + 2
+    }
+
+    #[export(scale, ethabi)]
+    pub fn dual(&self, p1: u32) -> u32 {
+        p1 + 3
+    }
+}

rs/ethexe/macros-tests/tests/service_tests.rs

@@ -62,7 +62,7 @@ impl SomeServiceExposure<SomeService> {
         mut input: &[u8],
         result_handler: fn(&[u8], u128),
     ) -> Option<()> {
-        use sails_rs::gstd::{InvocationIo, CommandReply};
+        use sails_rs::gstd::CommandReply;
         match (interface_id, entry_id) {
             (
                 id,
@@ -76,7 +76,11 @@ impl SomeServiceExposure<SomeService> {
                 let result = self.this(request.p1);
                 let value = 0u128;
                 if !sails_rs::gstd::is_empty_tuple::<bool>() {
-                    <some_service_meta::__ThisParams as sails_rs::gstd::InvocationIo>::with_optimized_encode(
+                    sails_rs::gstd::encode_invocation_payload::<
+                        some_service_meta::__ThisParams,
+                        _,
+                        _,
+                    >(
                         &result,
                         self.route_idx,
                         |encoded_result| result_handler(encoded_result, value),
@@ -96,7 +100,7 @@ impl SomeServiceExposure<SomeService> {
         mut input: &[u8],
         result_handler: fn(&[u8], u128),
     ) -> Option<()> {
-        use sails_rs::gstd::{InvocationIo, CommandReply};
+        use sails_rs::gstd::CommandReply;
         match (interface_id, entry_id) {
             (
                 id,
@@ -110,7 +114,11 @@ impl SomeServiceExposure<SomeService> {
                 let result = self.do_this(request.p1, request.p2).await;
                 let value = 0u128;
                 if !sails_rs::gstd::is_empty_tuple::<u32>() {
-                    <some_service_meta::__DoThisParams as sails_rs::gstd::InvocationIo>::with_optimized_encode(
+                    sails_rs::gstd::encode_invocation_payload::<
+                        some_service_meta::__DoThisParams,
+                        _,
+                        _,
+                    >(
                         &result,
                         self.route_idx,
                         |encoded_result| result_handler(encoded_result, value),