From 3c5f166d90bab30230b132feee934200674af498 Mon Sep 17 00:00:00 2001
From: Victor Oliva <v.oliva@proton.me>
Date: Thu, 11 Apr 2024 16:37:30 +0200
Subject: [PATCH] Add providers section

---
 docs/pages/providers.mdx | 51 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

diff --git a/docs/pages/providers.mdx b/docs/pages/providers.mdx
index b2f7d91a..5c504ee4 100644
--- a/docs/pages/providers.mdx
+++ b/docs/pages/providers.mdx
@@ -1,3 +1,52 @@
 # Providers
 
-providers
\ No newline at end of file
+The entry point of Polkadot-API, `createClient(provider)` requires one `JsonRpcProvider`, which lets Polkadot-API communicate with a node. It's a function with the following shape:
+
+```ts
+interface JsonRpcProvider {
+    (onMessage: (message: string) => void) => JsonRpcConnection;
+}
+
+interface JsonRpcConnection {
+    send: (message: string) => void;
+    disconnect: () => void;
+}
+```
+
+Calling it will initiate a connection. Messages coming from the service will come through the `onMessage` call, and the returned connection handle can be used to send messages or terminate the connection.
+
+Polkadot-API offers a couple of providers for some of the most used ways of connecting to a chain:
+
+- `WebSocketProvider(uri: string)` from `polkadot-api/ws-provider/web` or `polkadot-api/ws-provider/node` to connect through WebSocket.
+- `getSmProvider(chain: smoldot.Chain)` from `polkadot-api/sm-provider` to connect through Smoldot.
+
+The `JsonRpcProvider` interface is designed so that it can be easily enhanced: You can wrap any JsonRpcProvider with another one that adds in more features, such as logging, statistics, or error recovery.
+
+## Logs provider
+
+Polkadot-API has a subpackage `polkadot-api/logs-provider` that can be used to create a provider that will replay node messages from a log file (`logsProvider`), along with a provider enhancer that can be used to generate the logs consumed by `logsProvider`: `withLogsRecorder`.
+
+```ts
+// 1. recording logs
+import { createClient } from 'polkadot-api';
+import { withLogsRecorder } from 'polkadot-api/logs-provider';
+import { WebSocketProvider } from 'polkadot-api/ws-provider/node';
+
+const wsProvider = WebSocketProvider("wss://example.url");
+// Using console.log to output each line, but you could e.g. write it directly to a
+// file or push into an array
+const provider = withLogsRecorder(line => console.log(line), wsProvider);
+const client = createClient(provider);
+```
+
+```ts
+// 2. replaying logs
+import { createClient } from 'polkadot-api';
+import { logsProvider } from 'polkadot-api/logs-provider';
+import logs from './readLogs';
+
+const provider = logsProvider(logs);
+const client = createClient(provider);
+```
+
+This can be useful to debug specific scenarios without needing to depend on an external source.