feat: improve signers section (#19)

Co-authored-by: Carlo Sala <[email protected]>

Author: peetzweg

docs/pages/getting-started.mdx

@@ -58,6 +58,7 @@ Now you can create a PolkadotClient with a provider of your choice and start int
 
     // [!include ~/snippets/gettingStarted.ts:usage]
     ```
+
   </Tabs.Content>
   <Tabs.Content value="snmw">
     ```ts
@@ -85,6 +86,7 @@ Now you can create a PolkadotClient with a provider of your choice and start int
 
     // [!include ~/snippets/gettingStarted.ts:usage]
     ```
+
   </Tabs.Content>
   <Tabs.Content value="sm">
     ```ts

docs/pages/recipes/upgrade.md

@@ -41,7 +41,7 @@ function performTransfer() {
   // check if we're running on the next version to run that first
   if (
     await nextApi.tx.Balances.new_fancy_transfer.isCompatible(
-      CompatibilityLevel.Partial
+      CompatibilityLevel.Partial,
     )
   ) {
     nextApi.tx.Balances.new_fancy_transfer({

docs/pages/signers.md

@@ -1,8 +1,10 @@
 # Signers
 
+## `PolkadotSigner`
+
 For transactions, the generated descriptors and its corresponding typed API are needed to create the transaction extrinsics, but for these transactions to be signed, we also need a signer, which is the responsible of taking it the call data and signing it.
 
-Every method on Polkadot-API that needs to sign something, takes in a signer with the following interface:
+Every method on Polkadot-API that needs to sign something, requires a `PolkadotSigner` with the following interface:
 
 ```ts
 interface PolkadotSigner {
@@ -26,7 +28,7 @@ interface PolkadotSigner {
 
 This interface is generic to signing transactions for the chain.
 
-## `PolkadotSigner` from a browser extension
+### From a browser extension
 
 If you want to use a compatible extension as a signer, Polkadot-API has a subpath with a couple of utilities to help with this: `polkadot-api/pjs-signer`.
 
@@ -51,7 +53,7 @@ const accounts: InjectedPolkadotAccount[] = selectedExtension.getAccounts()
 const polkadotSigner = accounts[0].polkadotSigner
 ```
 
-## `PolkadotSigner` from generic signing function
+### From a generic signing function
 
 If you have a signer which takes some arbitrary data and just signs it with one of the supported algorithms, you can create a `PolkadotSigner` with the function `getPolkadotSigner` from `polkadot-api/signer`:
 
@@ -68,16 +70,16 @@ For example, using hdkd from `@polkadot-labs`:
 ```ts
 import { sr25519CreateDerive } from "@polkadot-labs/hdkd"
 import {
-  sr25519,
   DEV_PHRASE,
   entropyToMiniSecret,
   mnemonicToEntropy,
 } from "@polkadot-labs/hdkd-helpers"
+import { getPolkadotSigner } from "polkadot-api/signer"
 
-const entropy = mnemonicToEntropy(MNEMONIC)
+const entropy = mnemonicToEntropy(DEV_PHRASE)
 const miniSecret = entropyToMiniSecret(entropy)
 const derive = sr25519CreateDerive(miniSecret)
-const keypair = derive("//Alice")
+const hdkdKeyPair = derive("//Alice")
 
 const polkadotSigner = getPolkadotSigner(
   hdkdKeyPair.publicKey,

docs/pages/typed.md

@@ -58,12 +58,15 @@ There's also a small utility next to `.getCompatibilityLevel()` to directly chec
 ```ts
 interface IsCompatible {
   (threshold: CompatibilityLevel): Promise<boolean>
-  (threshold: CompatibilityLevel, compatibilityToken: CompatibilityToken): boolean
+  (
+    threshold: CompatibilityLevel,
+    compatibilityToken: CompatibilityToken,
+  ): boolean
 }
 
 // Possible "pseudocode" implementation, to show the equivalence
 function isCompatible(threshold, token) {
-  return getCompatibilityLevel(token) >= threshold;
+  return getCompatibilityLevel(token) >= threshold
 }
 ```
 
@@ -84,7 +87,9 @@ if (await query.isCompatible(CompatibilityLevel.BackwardsCompatible)) {
 const compatibilityToken = await typedApi.compatibilityToken
 
 // And later on we can use it, so that `getCompatibilityLevel` is sync
-if (query.isCompatible(CompatibilityLevel.BackwardsCompatible, compatibilityToken)) {
+if (
+  query.isCompatible(CompatibilityLevel.BackwardsCompatible, compatibilityToken)
+) {
   // do your stuff, the query is compatible
 } else {
   // the call is not compatible!