pallet-revive: Fix docs.rs (#6896)

- Fixed failing docs.rs build for `pallet-revive-uapi` by fixing a wring
attribute in the manifest (we were using `default-target` instead of
`targets`)
- Removed the macros defining host functions because the cfg attributes
introduced in #6866 won't work on them
- Added an docs.rs specific attribute so that the `unstable-hostfn`
feature tag will show up on the functions that are guarded behind it.

---------

Co-authored-by: command-bot <>

prdoc/pr_6896.prdoc

@@ -0,0 +1,16 @@
+title: 'pallet-revive: Fix docs.rs'
+doc:
+- audience: Runtime Dev
+  description: |-
+    - Fixed failing docs.rs build for `pallet-revive-uapi` by fixing a writing attribute in the manifest (we were using `default-target` instead of `targets`)
+    - Removed the macros defining host functions because the cfg attributes introduced in #6866 won't work on them
+    - Added an docs.rs specific attribute so that the `unstable-hostfn` feature tag will show up on the functions that are guarded behind it.
+crates:
+- name: pallet-contracts-uapi
+  bump: major
+- name: pallet-revive-uapi
+  bump: major
+- name: pallet-revive-fixtures
+  bump: major
+- name: pallet-revive-proc-macro
+  bump: major

substrate/frame/contracts/uapi/Cargo.toml

@@ -21,7 +21,7 @@ codec = { features = [
 ], optional = true, workspace = true }
 
 [package.metadata.docs.rs]
-default-target = ["wasm32-unknown-unknown"]
+targets = ["wasm32-unknown-unknown"]
 
 [features]
 default = ["scale"]

substrate/frame/revive/fixtures/build/_Cargo.toml

@@ -12,7 +12,7 @@ edition = "2021"
 
 # All paths are injected dynamically by the build script.
 [dependencies]
-uapi = { package = 'pallet-revive-uapi', path = "", features = ["unstable-api"], default-features = false }
+uapi = { package = 'pallet-revive-uapi', path = "", features = ["unstable-hostfn"], default-features = false }
 common = { package = 'pallet-revive-fixtures-common', path = "" }
 polkavm-derive = { version = "0.18.0" }
 

substrate/frame/revive/proc-macro/src/lib.rs

@@ -25,6 +25,17 @@ use proc_macro2::{Literal, Span, TokenStream as TokenStream2};
 use quote::{quote, ToTokens};
 use syn::{parse_quote, punctuated::Punctuated, spanned::Spanned, token::Comma, FnArg, Ident};
 
+#[proc_macro_attribute]
+pub fn unstable_hostfn(_attr: TokenStream, item: TokenStream) -> TokenStream {
+	let input = syn::parse_macro_input!(item as syn::Item);
+	let expanded = quote! {
+		#[cfg(feature = "unstable-hostfn")]
+		#[cfg_attr(docsrs, doc(cfg(feature = "unstable-hostfn")))]
+		#input
+	};
+	expanded.into()
+}
+
 /// Defines a host functions set that can be imported by contract wasm code.
 ///
 /// **NB**: Be advised that all functions defined by this macro

substrate/frame/revive/uapi/Cargo.toml

@@ -19,14 +19,16 @@ codec = { features = [
 	"derive",
 	"max-encoded-len",
 ], optional = true, workspace = true }
+pallet-revive-proc-macro = { workspace = true }
 
 [target.'cfg(target_arch = "riscv64")'.dependencies]
 polkavm-derive = { version = "0.18.0" }
 
 [package.metadata.docs.rs]
-default-target = ["riscv64imac-unknown-none-elf"]
+features = ["unstable-hostfn"]
+targets = ["riscv64imac-unknown-none-elf"]
 
 [features]
 default = ["scale"]
 scale = ["dep:codec", "scale-info"]
-unstable-api = []
+unstable-hostfn = []

substrate/frame/revive/uapi/src/host.rs

@@ -12,27 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 use crate::{CallFlags, Result, ReturnFlags, StorageFlags};
-use paste::paste;
+use pallet_revive_proc_macro::unstable_hostfn;
 
 #[cfg(target_arch = "riscv64")]
 mod riscv64;
 
-macro_rules! hash_fn {
-	( $name:ident, $bytes:literal ) => {
-		paste! {
-			#[doc = "Computes the " $name " " $bytes "-bit hash on the given input buffer."]
-			#[doc = "\n# Notes\n"]
-			#[doc = "- The `input` and `output` buffer may overlap."]
-			#[doc = "- The output buffer is expected to hold at least " $bytes " bits."]
-			#[doc = "- It is the callers responsibility to provide an output buffer that is large enough to hold the expected amount of bytes returned by the hash function."]
-			#[doc = "\n# Parameters\n"]
-			#[doc = "- `input`: The input data buffer."]
-			#[doc = "- `output`: The output buffer to write the hash result to."]
-			fn [<hash_ $name>](input: &[u8], output: &mut [u8; $bytes]);
-		}
-	};
-}
-
 /// Implements [`HostFn`] when compiled on supported architectures (RISC-V).
 pub enum HostFnImpl {}
 
@@ -238,7 +222,18 @@ pub trait HostFn: private::Sealed {
 	/// [KeyNotFound][`crate::ReturnErrorCode::KeyNotFound]
 	fn get_storage(flags: StorageFlags, key: &[u8], output: &mut &mut [u8]) -> Result;
 
-	hash_fn!(keccak_256, 32);
+	/// Computes the keccak_256 32-bit hash on the given input buffer.
+	///
+	/// - The `input` and `output` buffer may overlap.
+	/// - The output buffer is expected to hold at least 32 bits.
+	/// - It is the callers responsibility to provide an output buffer that is large enough to hold
+	///   the expected amount of bytes returned by the hash function.
+	///
+	/// # Parameters
+	///
+	/// - `input`: The input data buffer.
+	/// - `output`: The output buffer to write the hash result to.
+	fn hash_keccak_256(input: &[u8], output: &mut [u8; 32]);
 
 	/// Stores the input data passed by the caller into the supplied `output` buffer,
 	/// starting from the given input data `offset`.
@@ -400,7 +395,7 @@ pub trait HostFn: private::Sealed {
 	/// # Parameters
 	///
 	/// - `output`: A reference to the output data buffer to write the block number.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn block_number(output: &mut [u8; 32]);
 
 	/// Stores the block hash of the given block number into the supplied buffer.
@@ -409,7 +404,7 @@ pub trait HostFn: private::Sealed {
 	///
 	/// - `block_number`: A reference to the block number buffer.
 	/// - `output`: A reference to the output data buffer to write the block number.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn block_hash(block_number: &[u8; 32], output: &mut [u8; 32]);
 
 	/// Call into the chain extension provided by the chain if any.
@@ -434,7 +429,7 @@ pub trait HostFn: private::Sealed {
 	/// # Return
 	///
 	/// The chain extension returned value, if executed successfully.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn call_chain_extension(func_id: u32, input: &[u8], output: Option<&mut &mut [u8]>) -> u32;
 
 	/// Call some dispatchable of the runtime.
@@ -461,7 +456,7 @@ pub trait HostFn: private::Sealed {
 	/// - Provide functionality **exclusively** to contracts.
 	/// - Provide custom weights.
 	/// - Avoid the need to keep the `Call` data structure stable.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn call_runtime(call: &[u8]) -> Result;
 
 	/// Checks whether the caller of the current contract is the origin of the whole call stack.
@@ -474,7 +469,7 @@ pub trait HostFn: private::Sealed {
 	///
 	/// A return value of `true` indicates that this contract is being called by a plain account
 	/// and `false` indicates that the caller is another contract.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn caller_is_origin() -> bool;
 
 	/// Checks whether the caller of the current contract is root.
@@ -484,7 +479,7 @@ pub trait HostFn: private::Sealed {
 	///
 	/// A return value of `true` indicates that this contract is being called by a root origin,
 	/// and `false` indicates that the caller is a signed origin.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn caller_is_root() -> u32;
 
 	/// Clear the value at the given key in the contract storage.
@@ -496,7 +491,7 @@ pub trait HostFn: private::Sealed {
 	/// # Return
 	///
 	/// Returns the size of the pre-existing value at the specified key if any.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn clear_storage(flags: StorageFlags, key: &[u8]) -> Option<u32>;
 
 	/// Checks whether there is a value stored under the given key.
@@ -509,7 +504,7 @@ pub trait HostFn: private::Sealed {
 	/// # Return
 	///
 	/// Returns the size of the pre-existing value at the specified key if any.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn contains_storage(flags: StorageFlags, key: &[u8]) -> Option<u32>;
 
 	/// Emit a custom debug message.
@@ -529,7 +524,7 @@ pub trait HostFn: private::Sealed {
 	/// not being executed as an RPC. For example, they could allow users to disable logging
 	/// through compile time flags (cargo features) for on-chain deployment. Additionally, the
 	/// return value of this function can be cached in order to prevent further calls at runtime.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn debug_message(str: &[u8]) -> Result;
 
 	/// Recovers the ECDSA public key from the given message hash and signature.
@@ -546,7 +541,7 @@ pub trait HostFn: private::Sealed {
 	/// # Errors
 	///
 	/// - [EcdsaRecoveryFailed][`crate::ReturnErrorCode::EcdsaRecoveryFailed]
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn ecdsa_recover(
 		signature: &[u8; 65],
 		message_hash: &[u8; 32],
@@ -564,15 +559,49 @@ pub trait HostFn: private::Sealed {
 	/// # Errors
 	///
 	/// - [EcdsaRecoveryFailed][`crate::ReturnErrorCode::EcdsaRecoveryFailed]
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn ecdsa_to_eth_address(pubkey: &[u8; 33], output: &mut [u8; 20]) -> Result;
 
-	#[cfg(feature = "unstable-api")]
-	hash_fn!(sha2_256, 32);
-	#[cfg(feature = "unstable-api")]
-	hash_fn!(blake2_256, 32);
-	#[cfg(feature = "unstable-api")]
-	hash_fn!(blake2_128, 16);
+	/// Computes the sha2_256 32-bit hash on the given input buffer.
+	///
+	/// - The `input` and `output` buffer may overlap.
+	/// - The output buffer is expected to hold at least 32 bits.
+	/// - It is the callers responsibility to provide an output buffer that is large enough to hold
+	///   the expected amount of bytes returned by the hash function.
+	///
+	/// # Parameters
+	///
+	/// - `input`: The input data buffer.
+	/// - `output`: The output buffer to write the hash result to.
+	#[unstable_hostfn]
+	fn hash_sha2_256(input: &[u8], output: &mut [u8; 32]);
+
+	/// Computes the blake2_256 32-bit hash on the given input buffer.
+	///
+	/// - The `input` and `output` buffer may overlap.
+	/// - The output buffer is expected to hold at least 32 bits.
+	/// - It is the callers responsibility to provide an output buffer that is large enough to hold
+	///   the expected amount of bytes returned by the hash function.
+	///
+	/// # Parameters
+	///											*/
+	/// - `input`: The input data buffer.
+	/// - `output`: The output buffer to write the hash result to.
+	#[unstable_hostfn]
+	fn hash_blake2_256(input: &[u8], output: &mut [u8; 32]);
+
+	/// Computes the blake2_128 16-bit hash on the given input buffer.
+	///
+	/// - The `input` and `output` buffer may overlap.
+	/// - The output buffer is expected to hold at least 16 bits.
+	/// - It is the callers responsibility to provide an output buffer that is large enough to hold
+	///   the expected amount of bytes returned by the hash function.
+	/// # Parameters
+	///
+	/// - `input`: The input data buffer.
+	/// - `output`: The output buffer to write the hash result to.
+	#[unstable_hostfn]
+	fn hash_blake2_128(input: &[u8], output: &mut [u8; 16]);
 
 	/// Checks whether a specified address belongs to a contract.
 	///
@@ -583,7 +612,7 @@ pub trait HostFn: private::Sealed {
 	/// # Return
 	///
 	/// Returns `true` if the address belongs to a contract.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn is_contract(address: &[u8; 20]) -> bool;
 
 	/// Lock a new delegate dependency to the contract.
@@ -595,23 +624,23 @@ pub trait HostFn: private::Sealed {
 	///
 	/// - `code_hash`: The code hash of the dependency. Should be decodable as an `T::Hash`. Traps
 	///   otherwise.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn lock_delegate_dependency(code_hash: &[u8; 32]);
 
 	/// Stores the minimum balance (a.k.a. existential deposit) into the supplied buffer.
 	///
 	/// # Parameters
 	///
 	/// - `output`: A reference to the output data buffer to write the minimum balance.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn minimum_balance(output: &mut [u8; 32]);
 
 	/// Retrieve the code hash of the currently executing contract.
 	///
 	/// # Parameters
 	///
 	/// - `output`: A reference to the output data buffer to write the code hash.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn own_code_hash(output: &mut [u8; 32]);
 
 	/// Replace the contract code at the specified address with new code.
@@ -642,7 +671,7 @@ pub trait HostFn: private::Sealed {
 	/// # Panics
 	///
 	/// Panics if there is no code on-chain with the specified hash.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn set_code_hash(code_hash: &[u8; 32]);
 
 	/// Verify a sr25519 signature
@@ -655,7 +684,7 @@ pub trait HostFn: private::Sealed {
 	/// # Errors
 	///
 	/// - [Sr25519VerifyFailed][`crate::ReturnErrorCode::Sr25519VerifyFailed]
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn sr25519_verify(signature: &[u8; 64], message: &[u8], pub_key: &[u8; 32]) -> Result;
 
 	/// Retrieve and remove the value under the given key from storage.
@@ -667,7 +696,7 @@ pub trait HostFn: private::Sealed {
 	/// # Errors
 	///
 	/// [KeyNotFound][`crate::ReturnErrorCode::KeyNotFound]
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn take_storage(flags: StorageFlags, key: &[u8], output: &mut &mut [u8]) -> Result;
 
 	/// Remove the calling account and transfer remaining **free** balance.
@@ -685,7 +714,7 @@ pub trait HostFn: private::Sealed {
 	/// - The contract is live i.e is already on the call stack.
 	/// - Failed to send the balance to the beneficiary.
 	/// - The deletion queue is full.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn terminate(beneficiary: &[u8; 20]) -> !;
 
 	/// Removes the delegate dependency from the contract.
@@ -696,7 +725,7 @@ pub trait HostFn: private::Sealed {
 	///
 	/// - `code_hash`: The code hash of the dependency. Should be decodable as an `T::Hash`. Traps
 	///   otherwise.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn unlock_delegate_dependency(code_hash: &[u8; 32]);
 
 	/// Stores the amount of weight left into the supplied buffer.
@@ -707,7 +736,7 @@ pub trait HostFn: private::Sealed {
 	/// # Parameters
 	///
 	/// - `output`: A reference to the output data buffer to write the weight left.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn weight_left(output: &mut &mut [u8]);
 
 	/// Execute an XCM program locally, using the contract's address as the origin.
@@ -724,7 +753,7 @@ pub trait HostFn: private::Sealed {
 	///
 	/// Returns `Error::Success` when the XCM execution attempt is successful. When the XCM
 	/// execution fails, `ReturnCode::XcmExecutionFailed` is returned
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn xcm_execute(msg: &[u8]) -> Result;
 
 	/// Send an XCM program from the contract to the specified destination.
@@ -742,7 +771,7 @@ pub trait HostFn: private::Sealed {
 	///
 	/// Returns `ReturnCode::Success` when the message was successfully sent. When the XCM
 	/// execution fails, `ReturnErrorCode::XcmSendFailed` is returned.
-	#[cfg(feature = "unstable-api")]
+	#[unstable_hostfn]
 	fn xcm_send(dest: &[u8], msg: &[u8], output: &mut [u8; 32]) -> Result;
 }