From f274260876d15e4f593a8319a062c26dbb430733 Mon Sep 17 00:00:00 2001
From: Victor Oliva <v.oliva@proton.me>
Date: Sun, 14 Apr 2024 18:51:07 +0200
Subject: [PATCH] Add signers docs

---
 docs/pages/{codegen.mdx => codegen.md}     |  0
 docs/pages/{providers.mdx => providers.md} |  0
 docs/pages/signers.md                      | 85 ++++++++++++++++++++++
 docs/pages/signers.mdx                     |  3 -
 4 files changed, 85 insertions(+), 3 deletions(-)
 rename docs/pages/{codegen.mdx => codegen.md} (100%)
 rename docs/pages/{providers.mdx => providers.md} (100%)
 create mode 100644 docs/pages/signers.md
 delete mode 100644 docs/pages/signers.mdx

diff --git a/docs/pages/codegen.mdx b/docs/pages/codegen.md
similarity index 100%
rename from docs/pages/codegen.mdx
rename to docs/pages/codegen.md
diff --git a/docs/pages/providers.mdx b/docs/pages/providers.md
similarity index 100%
rename from docs/pages/providers.mdx
rename to docs/pages/providers.md
diff --git a/docs/pages/signers.md b/docs/pages/signers.md
new file mode 100644
index 00000000..aa9813bf
--- /dev/null
+++ b/docs/pages/signers.md
@@ -0,0 +1,85 @@
+# Signers
+
+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:
+
+```ts
+interface PolkadotSigner {
+  publicKey: Uint8Array
+  sign: (
+    callData: Uint8Array,
+    signedExtensions: Record<
+      string,
+      {
+        identifier: string
+        value: Uint8Array
+        additionalSigned: Uint8Array
+      }
+    >,
+    metadata: Uint8Array,
+    atBlockNumber: number,
+    hasher?: (data: Uint8Array) => Uint8Array,
+  ) => Promise<Uint8Array>
+}
+```
+
+This interface is generic to signing transactions for the chain.
+
+## `PolkadotSigner` 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`.
+
+```ts
+import { getInjectedExtensions, connectInjectedExtension } from 'polkadot-api/pjs-signer';
+
+// Get the list of installed extensions
+const extensions: string[] = getInjectedExtensions();
+
+// Connect to an extension
+const selectedExtension: InjectedExtension = await connectInjectedExtension(extensions[0]);
+
+// Get accounts registered in the extension
+const accounts: InjectedPolkadotAccount[] = selectedExtension.getAccounts();
+
+// The signer for each account is in the `polkadotSigner` property of `InjectedPolkadotAccount`
+const polkadotSigner = accounts[0].polkadotSigner;
+```
+
+## `PolkadotSigner` from 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`:
+
+```ts
+export function getPolkadotSigner(
+  publicKey: Uint8Array,
+  signingType: "Ecdsa" | "Ed25519" | "Sr25519",
+  sign: (input: Uint8Array) => Promise<Uint8Array> | Uint8Array,
+): PolkadotSigner
+```
+
+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"
+
+const entropy = mnemonicToEntropy(MNEMONIC)
+const miniSecret = entropyToMiniSecret(entropy)
+const derive = sr25519CreateDerive(miniSecret)
+const keypair = derive("//Alice")
+
+const polkadotSigner = getPolkadotSigner(
+    hdkdKeyPair.publicKey,
+    "Sr25519",
+    hdkdKeyPair.sign
+);
+```
+
+
+
diff --git a/docs/pages/signers.mdx b/docs/pages/signers.mdx
deleted file mode 100644
index 3dede016..00000000
--- a/docs/pages/signers.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
-# Signers
-
-signers
\ No newline at end of file