5

I have the template pallet in the Substrate node template. This pallet template has a function do_something that store a value in the storage.

I would like to create an RPC call that queries that value in the storage and make it accessible from my node.

How do I do this?

Improve this question
2
  • Thank you so much, that helped a lot! May I ask what is the trick to expose the RPC to the pallet interactor in the frontend? So far I was able to add the RPC call and do something, but I would like to use it from the ffronted ratehr than curl/Postman. Thanks again :)
    – langi667
    Commented Mar 6, 2023 at 14:06
  • Do you mean to interact with it using the polkadotJS UI: polkadot.js.org/apps/#/explorer or just do a RPC call with a frontend in JS?
    – Alex Bean
    Commented Mar 7, 2023 at 10:35

1 Answer 1

Reset to default
14

Remote Procedure Calls, or RPCs, are a way for an external program—for example, a browser or front-end application—to communicate with a Substrate node. Substrate comes with several default RPCs and you can also add your custom RPC calls.

First of all create the custom RPC call in the template pallet and after set up the node for the pallet-template custom RPC.

Add custom RPC in our pallet

Inside the pallet template folder create a new folder called rpc: pallets/template/src/rpc

The RPC call interacts with the pallet-tempate runtime API to call the function that gets the value. For that you need to create a pallet-template-runtime-api. Create a new folder inside the rpc folder: pallets/template/src/rpc/runtime-api

This folder can live anywhere you like, but because it defines an API that is closely related to a particular pallet, it makes sense to include the API definition in the pallet’s directory.

Create the Cargo.toml file for the runtime-api package. In pallets/template/src/rpc/runtime-api/Cargo.toml

[package]
name = "pallet-template-runtime-api"
authors = ["Alex Bean <https://github.com/AlexD10S>"]
version = "1.0.0"
edition = "2021"

[package.metadata.docs.rs]
targets = ["x86_64-unknown-linux-gnu"]

[dependencies]
sp-api = { git = "https://github.com/paritytech/substrate.git", branch = "polkadot-v0.9.28", default-features = false }

[features]
default = ["std"]
std = [
    "sp-api/std",
]

And define the runtime API interface: pallets/template/src/rpc/runtime-api/src/lib.rs

The code to define the API is quite simple, and looks almost like any old Rust trait. The one addition is that it must be placed in the decl_runtime_apis! macro. This macro allows the outer node to query the runtime API at specific blocks. Although this runtime API only provides a single function, you may write as many as you like.

#![cfg_attr(not(feature = "std"), no_std)]

// Here we declare the runtime API. It is implemented it the `impl` block in
// runtime file (the `runtime/src/lib.rs`)
sp_api::decl_runtime_apis! {
    pub trait TemplateApi {
        fn get_value() -> u32;
    }
}

Now define the RPC. Create a folder Cargo.toml in the rpc folder: pallets/template/src/rpc/Cargo.toml

Here import the runtime-api defined before:

pallet-template-runtime-api = { path = "./runtime-api", default-features = false }

And the JSON-RPC library for Rust.

jsonrpsee = { version = "0.15.1", features = ["server", "macros"] }

Full file:

[package]
name = "pallet-template-rpc"
version = "1.0.0"
edition = "2021"
authors = ["Alex Bean <https://github.com/AlexD10S>"]
description = 'RPC methods for the template pallet'

[package.metadata.docs.rs]
targets = ["x86_64-unknown-linux-gnu"]

[dependencies]
codec = { package = "parity-scale-codec", version = "3.0.0", default-features = false, features = [
    "derive",
] }

jsonrpsee = { version = "0.15.1", features = ["server", "macros"] }


# Substrate packages

sp-api = { default-features = false, version = "4.0.0-dev", git = "https://github.com/paritytech/substrate.git", branch = "polkadot-v0.9.28" }
sp-blockchain = { default-features = false, version = "4.0.0-dev", git = "https://github.com/paritytech/substrate.git", branch = "polkadot-v0.9.28" }
sp-runtime = { default-features = false, version = "6.0.0", git = "https://github.com/paritytech/substrate.git", branch = "polkadot-v0.9.28" }

# local packages
pallet-template-runtime-api = { path = "./runtime-api", default-features = false }

[features]
default = ["std"]
std = [
  "sp-api/std",
  "sp-runtime/std",
  "pallet-template-runtime-api/std"
]

Inside the rpc folder create a src folder with a lib.rs where define the Pallet Template RPC:

First define the RPC interface. Notice that the struct that implements the RPC needs a reference to the client. This is necessary so you can actually call into the runtime.

And the struct is generic over the BlockHash type. This is because it will call a runtime API, and runtime APIs must always be called at a specific block.

#[rpc(client, server)]
pub trait TemplateApi<BlockHash> {
    #[method(name = "template_getValue")]
    fn get_value(&self, at: Option<BlockHash>) -> RpcResult<u32>;
}

/// A struct that implements the `TemplateApi`.
pub struct TemplatePallet<C, Block> {
    // If you have more generics, no need to TemplatePallet<C, M, N, P, ...>
    // just use a tuple like TemplatePallet<C, (M, N, P, ...)>
    client: Arc<C>,
    _marker: std::marker::PhantomData<Block>,
}

impl<C, Block> TemplatePallet<C, Block> {
    /// Create new `TemplatePallet` instance with the given reference to the client.
    pub fn new(client: Arc<C>) -> Self {
        Self { client, _marker: Default::default() }
    }
}

Now the RPC’s implementation. The additional syntax here is related to calling the runtime at a specific block, as well as ensuring that the runtime you’re calling actually has the correct runtime API available.

impl<C, Block> TemplateApiServer<<Block as BlockT>::Hash> for TemplatePallet<C, Block>
where
    Block: BlockT,
    C: Send + Sync + 'static + ProvideRuntimeApi<Block> + HeaderBackend<Block>,
    C::Api: TemplateRuntimeApi<Block>,
{
    fn get_value(&self, at: Option<<Block as BlockT>::Hash>) -> RpcResult<u32> {
        let api = self.client.runtime_api();
        let at = BlockId::hash(at.unwrap_or_else(||self.client.info().best_hash));

        api.get_value(&at).map_err(runtime_error_into_rpc_err)
    }
}

const RUNTIME_ERROR: i32 = 1;

/// Converts a runtime trap into an RPC error.
fn runtime_error_into_rpc_err(err: impl std::fmt::Debug) -> JsonRpseeError {
    CallError::Custom(ErrorObject::owned(
        RUNTIME_ERROR,
        "Runtime error",
        Some(format!("{:?}", err)),
    ))
    .into()
}

The full file in pallets/template/src/rpc/src/lib.rs:

pub use pallet_template_runtime_api::TemplateApi as TemplateRuntimeApi;
use jsonrpsee::{
    core::{Error as JsonRpseeError, RpcResult},
    proc_macros::rpc,
    types::error::{CallError, ErrorObject},
};
use sp_api::ProvideRuntimeApi;
use sp_blockchain::HeaderBackend;
use sp_runtime::{generic::BlockId, traits::Block as BlockT};
use std::sync::Arc;

#[rpc(client, server)]
pub trait TemplateApi<BlockHash> {
    #[method(name = "template_getValue")]
    fn get_value(&self, at: Option<BlockHash>) -> RpcResult<u32>;
}

/// A struct that implements the `TemplateApi`.
pub struct TemplatePallet<C, Block> {
    // If you have more generics, no need to TemplatePallet<C, M, N, P, ...>
    // just use a tuple like TemplatePallet<C, (M, N, P, ...)>
    client: Arc<C>,
    _marker: std::marker::PhantomData<Block>,
}

impl<C, Block> TemplatePallet<C, Block> {
    /// Create new `TemplatePallet` instance with the given reference to the client.
    pub fn new(client: Arc<C>) -> Self {
        Self { client, _marker: Default::default() }
    }
}

impl<C, Block> TemplateApiServer<<Block as BlockT>::Hash> for TemplatePallet<C, Block>
where
    Block: BlockT,
    C: Send + Sync + 'static + ProvideRuntimeApi<Block> + HeaderBackend<Block>,
    C::Api: TemplateRuntimeApi<Block>,
{
    fn get_value(&self, at: Option<<Block as BlockT>::Hash>) -> RpcResult<u32> {
        let api = self.client.runtime_api();
        let at = BlockId::hash(at.unwrap_or_else(||self.client.info().best_hash));

        api.get_value(&at).map_err(runtime_error_into_rpc_err)
    }
}

const RUNTIME_ERROR: i32 = 1;

/// Converts a runtime trap into an RPC error.
fn runtime_error_into_rpc_err(err: impl std::fmt::Debug) -> JsonRpseeError {
    CallError::Custom(ErrorObject::owned(
        RUNTIME_ERROR,
        "Runtime error",
        Some(format!("{:?}", err)),
    ))
    .into()
}

Now modify the pallet implementation to have a function called get_value(), in pallets/template/src/lib.rs Change:

#[pallet::getter(fn something)]

with

#[pallet::getter(fn get_value)]

Set up the node for the pallet-template Custom RPC

Implement now in the runtime of the node the function get_value() declared in the pallet-template-runtime-api

Add the runtime-api pallet in the configuration file of the pallet, in:

runtime/Cargo.toml

# local packages
pallet-template-runtime-api = { path = "./runtime-api", default-features = false }}
And add in the std:

std = [
    ...,
    "pallet-template-runtime-api/std",
]

Add the implementation of the runtime function in the pallet:

runtime/src/lib.rs

impl pallet_template_runtime_api::TemplateApi<Block> for Runtime {
    fn get_value() -> u32 {
        TemplateModule::get_value().unwrap_or(0)
    }
}

Install the RPC in the node To add the node-specific RPC methods modify the files in the node to include the pallet RPC code manually. First adding the new pallet in the configuration file in the node/Config.toml:

pallet-template-rpc = { version = "1.0.0", path = "../pallets/template/rpc" }

Then adding the node-specific RPC methods. Modify the file node/rpc.rs and there include the pallet template RPC code.

 /// Instantiate all full RPC extensions.
pub fn create_full<C, P>(
    deps: FullDeps<C, P>,
) -> Result<RpcModule<()>, Box<dyn std::error::Error + Send + Sync>>
where
    C: ProvideRuntimeApi<Block>,
    C: HeaderBackend<Block> + HeaderMetadata<Block, Error = BlockChainError> + 'static,
    C: Send + Sync + 'static,
    C::Api: substrate_frame_rpc_system::AccountNonceApi<Block, AccountId, Index>,
    C::Api: pallet_transaction_payment_rpc::TransactionPaymentRuntimeApi<Block, Balance>,
    C::Api: pallet_template_rpc::TemplateRuntimeApi<Block>,
    C::Api: BlockBuilder<Block>,
    P: TransactionPool + 'static,
{
    use pallet_transaction_payment_rpc::{TransactionPayment, TransactionPaymentApiServer};
    use substrate_frame_rpc_system::{System, SystemApiServer};
    use pallet_template_rpc::{TemplatePallet, TemplateApiServer};

    let mut module = RpcModule::new(());
    let FullDeps { client, pool, deny_unsafe } = deps;

    module.merge(System::new(client.clone(), pool.clone(), deny_unsafe).into_rpc())?;
    module.merge(TransactionPayment::new(client.clone()).into_rpc())?;
    module.merge(TemplatePallet::new(client).into_rpc())?;

    // Extend this RPC with a custom API by using the following syntax.
    // `YourRpcStruct` should have a reference to a client, which is needed
    // to call into the runtime.
    // `module.merge(YourRpcTrait::into_rpc(YourRpcStruct::new(ReferenceToClient, ...)))?;`

    Ok(module)
}

Run the node and query the RPC using for an example CURL, in the command line:

curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "template_getValue", "params": []}' http://localhost:9933/
Improve this answer
8

Not the answer you're looking for? Browse other questions tagged or ask your own question.