Add README FAQ #682
Merged
Add README FAQ #682
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
haerdib
added
F4-documentation
masapr
requested changes
Dec 5, 2023
README.md
Outdated
|
|
||
|
|
||
| ## FAQ | ||
| 1. Q: Everything compiles but my Substrate node does not accept my extrinsic or returns an error even if the extrinsic should be correct. |
There was a problem hiding this comment.
I would try to avoid the usage of words like "my" (especially the substrate node could also not be "mine").
README.md
Outdated
|
|
||
| 3. Q: I want to retrieve a state from my node via the api-client, but I do not get the expected value respective the decoding fails. How come? | ||
|
|
||
| A: When specifying your own state query, you must provide the return type of the state you're trying to retrieve. This is because the api-client only gets bytes from the node and must be able to deserialize these properly. That is not possible without knowing the type to decode to. This type may be for example a simple `u64` for retrieving the `Balance` of an account. But careful: Often, but depending on the pallet configuration, the node returns an additional `Option`. So it's rather an `Option<u64>` than a simple `u64`. Possible pallet configurations are `OptionQuery`, `ResultQuery` and `ValueQuery` (see the [substrate docs "Handling query return values"](https://docs.substrate.io/build/runtime-storage/) for more information). Please check your pallet configuration and adapt the expected return type accordingly in the api-client. And always remember to match the type to your Runtime! If you're fetching events for example, ensure it's the event type provided by your node runtime, not by any other. |
There was a problem hiding this comment.
Not sure it's necessary to go into pallet development here. Isn't it also visible in Polkadot-JS what type is returned? ... I wouldn't assume, that the person using the api-client is also writing the pallets of the node ...
There was a problem hiding this comment.
True. But I think it is still noteworthy because this has already led to confusion in the past. I adapted the text - what do you think?
README.md
Outdated
|
|
||
| Ensure you're using a matching config. If you do not use default parameters as configured in one of the provided configs, you must provide your own config that implements the [Config trait](https://github.com/scs/substrate-api-client/blob/master/primitives/src/config/mod.rs). | ||
|
|
||
| 3. Q: I want to retrieve a state from my node via the api-client, but I do not get the expected value respective the decoding fails. How come? |
There was a problem hiding this comment.
Same as above, I would not assume, that the person asking the question has their own node (instead of "my" I would write "a substrate node"
README.md
Outdated
|
|
||
| 3. Q: I want to retrieve a state from my node via the api-client, but I do not get the expected value respective the decoding fails. How come? | ||
|
|
||
| A: When specifying your own state query, you must provide the return type of the state you're trying to retrieve. This is because the api-client only gets bytes from the node and must be able to deserialize these properly. That is not possible without knowing the type to decode to. This type may be for example a simple `u64` for retrieving the `Balance` of an account. But careful: Often, but depending on the pallet configuration, the node returns an additional `Option`. So it's rather an `Option<u64>` than a simple `u64`. Possible pallet configurations are `OptionQuery`, `ResultQuery` and `ValueQuery` (see the [substrate docs "Handling query return values"](https://docs.substrate.io/build/runtime-storage/) for more information). Please check your pallet configuration and adapt the expected return type accordingly in the api-client. And always remember to match the type to your Runtime! If you're fetching events for example, ensure it's the event type provided by your node runtime, not by any other. |
There was a problem hiding this comment.
The sentence
"But careful: Often, but depending on the pallet configuration, the node returns an additional Option."
has a complicated structure. I would write:
"But careful: Depending on the pallet configuration, the node might return an Option."
masapr
requested changes
Dec 5, 2023
README.md
Outdated
| @@ -175,7 +175,7 @@ _In alphabetical order_ | |||
|
|
|||
|
|
|||
| ## FAQ | |||
| 1. Q: Everything compiles but my Substrate node does not accept my extrinsic or returns an error even if the extrinsic should be correct. | |||
| 1. Q: Everything compiles but the Substrate node does not accept my extrinsic or returns an error even if the extrinsic should be correct. | |||
|
|
|||
| A: First, ensure the api-client and the Substrate node have a matching version. E.g. if you're running your node on `release-polkadot-v1.2.0`, checkout and compile a matching branch of the api-client. We are using the same naming scheme as Parity does. Please note: Not all Polkadot releases are published for all api-client releases. Which Polkadot releases are supported by which api-client release are noted in the [release notes](https://github.com/scs/substrate-api-client/releases). Don't find the release-match you're looking for? Feel free to request it via an issue. | |||
There was a problem hiding this comment.
... same as above "your node"
README.md
Outdated
| @@ -187,6 +187,7 @@ _In alphabetical order_ | |||
|
|
|||
| Ensure you're using a matching config. If you do not use default parameters as configured in one of the provided configs, you must provide your own config that implements the [Config trait](https://github.com/scs/substrate-api-client/blob/master/primitives/src/config/mod.rs). | |||
|
|
|||
| 3. Q: I want to retrieve a state from my node via the api-client, but I do not get the expected value respective the decoding fails. How come? | |||
There was a problem hiding this comment.
Very nice, the whole paragraph is much more understandable now! 🎉
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
closes #561