search

JoshOrndorff / recipes

A Hands-On Cookbook for Aspiring Blockchain Chefs
GNU General Public License v3.0
378 stars 187 forks source link

Custom RPC Recipe #330

Closed EthanTheMaster closed 4 years ago

EthanTheMaster commented 4 years ago

Hi, I'm totally new to Substrate and blockchain technologies in general. I've been following the recipes in order, and so far it's been great but I am finding the Custom RPC recipe extremely difficult for me to understand. Typically, when I am having trouble understanding the recipe I refer to the Substrate Knowledge Base but the knowledge base doesn't seem to mention anything about making custom RPCs. To get a better grasp of the material, I think it would be a great improvement if there were some explanations along with the thought process for writing certain bits of code. For example, it'd be nice to know what a service builder is. What is the difference between a light and full client? What is a Substrate client (the Runtime APIs recipe links to the docs which does not explain much)? How is the client constructed and where is the configuration coming from? What is new_full and new_light doing as the code corresponding to those function seem to incorporate a lot of topics that haven't been previously mentioned. If the explanation would be too involved, then perhaps further resources and links could be added or maybe split the recipe similar to the off-chain worker's section. Why is it that let runtime_api_result = api.get_sum(&at) when get_sum() in the Runtime APIs recipe takes no parameters (the Runtime APIs recipe only makes a note about the Block generic type but not about the function requiring a Block)?

Also, the recipe (and corresponding code) seems to be making use of sc_service::ServiceBuilder which exists in an older version of sc_service but not in the newest version. The newest version of sc_service has the function new_full_client. Does this function render the implementation in the recipe obsolete (new_full)?

danforbes commented 4 years ago

Hi @EthanTheMaster - thank you so much for this super insightful Issue :pray: There is a lot to unpack here, so I would love for you to join our Riot technical chat and contact me at @danforbes:matrix.parity.io so we can chat :nerd_face: If you're not keen on joining a (potentially) new chat platform, feel free to reach out to me at dan@parity.io - I'd love to be able to pick your brain a bit.

We have an open Issue for better RPC documentation, and it's something that's been near the top of my list for a while...unfortunately there are many things near the top of that list :sweat_smile: In the meantime, you will actually be able to find a fair amount of information about Substrate RPC calls by referring to the docs for the Polkadot JS family of libraries, which is the de facto client library for Substrate-based chains.

We also recently made some enhancements to our node template that will make it easier to add custom RPCs to Substrate-based chains that are forked off this template. These enhancements haven't made their way into the official Substrate Developer Hub Node Template yet, but you can easily generate a template yourself and use that to hack around.

I recently self-published a short write-up on some changes to our service layer and I agree that we need more official documentation on this topic...in general, I agree with everything you have to say!

Here are some existing projects related to light clients, another topic I agree we need to document better:

We recently added an "Architecture" section to our Knowledge Base, which you may also find helpful.

You are correct that Recipes have not yet been updated to the most recently released version of Substrate, which includes some significant changes to the service layer.

I hope that is helpful and I hope to hear back from you so we can chat some more :nerd_face:

EthanTheMaster commented 4 years ago

Wow, thanks for all the resources. I'll definite refer to those links again in the future, but for now I think I'll continue through the recipe book so that I have a better overview of everything Substrate has to offer. After finishing the recipe book, I'll probably play with the node template (which I wasn't aware of until now!) and try to figure out making custom RPCs. It seems that rpc.rs from the node template PR has a much cleaner implementation than what is present in the recipe book and aligns much more closely to the example code in the jsonrpc repo. Looking there will probably help me figure out the RPC situation, and based on your response I should keep my eyes out on the Substrate repo for the most up to date information.

JoshOrndorff commented 4 years ago

Hi @EthanTheMaster You've correctly noticed that the topic of custom RPCs is not covered well in other parts of the Substrate docs. It is an advanced topic and the recipes was the first thing to cover it.

You asked at a good time though, because the way you add custom RPCs to a node just changed, and I re-wrote that recipe. Please take a look at the latest version. The node template also has better explanatory comments on this topic, thanks in part to your asking about it. Those are available at https://github.com/substrate-developer-hub/substrate-node-template/blob/master/node/src/rpc.rs

I'm going to close this issue because the most actionable parts (update to newer substrate, link better rustdocs, cover in other parts of the docs) have been addressed or ticketed. Please re-open if there is more to do, or open a new issue with specific questions r problems about the RPC node or any other recipe.