Sc 8976 review pull oracle

docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md

@@ -5,10 +5,13 @@ keywords: [pull oracle]
 ---
 # Getting started
 
-Chronicle's pull oracles offer the absolute freshest pricing information on-demand. We provide an [npm module](https://npmjs.com/) interface to simplify use.
+Chronicle's pull oracles offer the absolute freshest pricing information on-demand. We provide an [SDK](https://npmjs.com/) for simple integrations. Authentication is handled via tokens based on the [Ethereum Signed Messages](https://eips.ethereum.org/EIPS/eip-191) protocol.
 
-Authentication is handled via tokens based on the [Ethereum Signed Messages](https://eips.ethereum.org/EIPS/eip-191) protocol. Once we have allow-listed your public signing address on our servers, you will be able to generate auth tokens to retrieve oracle prices.
+:::info
+Your public signing key must be allow-listed on our servers before you can generate tokens.
+:::
 
+Generating authentication tokens on the server:
 ```js
 import { signAuthToken } from '@chronicleprotocol/pull-oracle';
 
@@ -22,12 +25,14 @@ const { token, message } = signAuthToken({
 We highly recommend following best practices for private key generation and storage. Use a unique private key for creating auth tokens. DO NOT re-use this private key for any other purpose!
 :::
 
-Once the auth token is generated on the server, pass it to the client side and register it with the `authenticate` methods of the `pull-oracle` module for automatic inclusion in future requests
+Once the auth token is generated on the server, pass it to the client and register it with the `authenticate` method of the `pull-oracle` module for automatic inclusion in future requests.
 
+Authenticating a user session on the client and fetching prices:
 ```js
-import { authenticate } from '@chronicleprotocol/pull-oracle';
+import { authenticate, getLatestPrices } from '@chronicleprotocol/pull-oracle';
 
-// token is received from server. `authenticate` caches the token in memory so it only needs to be called once per session
+// token is received from the server
+// `authenticate` caches the token in memory so it only needs to be called once per session
 authenticate(token);
 
 const prices = await getLatestPrices([

docs/Developers/Guides/Chronicle Pull Oracles/Types.md

@@ -1,28 +1,30 @@
-# Types
-
-
-
 ---
+sidebar_position: 4
+description: Pull Oracle - Types
+keywords: [pull oracle]
+---
+
+# Types
 
-# Constants
+## Constants
 
-## `Scheme`
+### `Scheme`
 
-Encryption scheme for price messages. Currently there is only one option, however more options may be offered in the future
+Encryption scheme for price messages. Currently there is only one option, however more options may be offered in the future.
 
 ```js
 enum Scheme {
   ECDSA
 }
 ```
 
-`ECDSA`: Price messages are signed with [Elliptic Curve Digital Signature Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) encryption
+- `ECDSA`: Price messages are signed with [Elliptic Curve Digital Signature Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) encryption.
 
 ---
 
-## `AuthTokenCodes`
+### `AuthTokenCodes`
 
-Reponse code for auth token verification
+Response codes for auth token verification.
 
 ```js
 enum AuthTokenCode {
@@ -36,10 +38,10 @@ enum AuthTokenCode {
 }
 ```
 
-`VALID`: Auth token is valid
-`EXPIRED`: Auth token end time has passed
-`NOT_YET_VALID`: Auth token start time has not yet occurred
-`INVALID_SIGNATURE`: The auth token `signer` field and recovered signature do not match
-`INVALID_VERSION`: The auth token is using an unrecognized version
-`MALFORMED_TOKEN`: The auth token has some other error not covered by the other codes
-`SIGNER_NOT_AUTHORIZED`: The token signer is not authorized by Chronicle
+- `VALID`: Auth token is valid
+- `EXPIRED`: Auth token end time has passed
+- `NOT_YET_VALID`: Auth token start time has not yet occurred
+- `INVALID_SIGNATURE`: The auth token `signer` field and recovered signature do not match
+- `INVALID_VERSION`: The auth token is using an unrecognized version
+- `MALFORMED_TOKEN`: The auth token has some other error not covered by the other codes
+- `SIGNER_NOT_AUTHORIZED`: The token signer is not authorized by Chronicle

docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md

@@ -1,7 +1,87 @@
-# `authenticate`
+---
+sidebar_position: 2
+description: Pull Oracle - authenticate
+keywords: [pull oracle]
+---
 
-Validates and caches the auth token for future use with [`getLatestPrices`](./getLatestPrices.md)
+# Authentication
 
-# Returns
+## `signAuthToken`
 
-`boolean`: whether the provided auth token is _currently_ valid
+A server-side function which creates an auth token to be used to [authenticate](#authenticate) [getLatestPrices](./getLatestPrices.md) requests.
+
+### Usage
+
+Generating authentication tokens on the server:
+```js
+import { signAuthToken } from '@chronicleprotocol/pull-oracle';
+
+const { token, message } = signAuthToken({
+  // private key is 0x prefixed 32 byte hex string
+  privateKey: "0xabc..."
+})
+```
+
+### Returns
+
+```js
+{ 
+    token: "...", 
+    message: {
+        description: "Chronicle API token",
+        version: 1,
+        validFrom: 1730992419,
+        validTo: 1730994251,
+        signer: "0x...",
+        nonce: 1077701,
+    } 
+}
+```
+
+- `token`: the authentication token
+- `message`: the authentication token details
+    - `description`: the description of the token
+    - `version`: the authentication API version number
+    - `validFrom`: unix timestamp starting from then the token is valid
+    - `validTo`: unix timestamp until when the auth token is valid
+    - `signer`: the address of the signer
+    - `nonce`: unique number
+
+---
+
+## `authenticate`
+
+A client-side function which validates and caches the auth token which was received from the server for future use with [getLatestPrices](./getLatestPrices.md).
+
+### Usage
+
+```js
+import { authenticate } from '@chronicleprotocol/pull-oracle';
+
+// token is received from the server
+// `authenticate` caches the token in memory so it only needs to be called once per session
+authenticate(token);
+```
+
+### Returns
+
+- `boolean`: whether the provided auth token is _currently_ valid.
+
+---
+
+# `isAuthenticated`
+
+A function to check whether the library has a currently valid auth token previously cached by the [authenticate](#authenticate) function.
+
+### Usage
+
+```js
+import { isAuthenticated } from '@chronicleprotocol/pull-oracle';
+
+// token from the cache is verified
+const isAuthenticated = isAuthenticated()
+```
+
+### Returns
+
+- `boolean`: whether the cached auth token is _currently_ valid.

docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md

@@ -1,25 +1,24 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 description: Pull Oracle - getLatestPrices
 keywords: [pull oracle]
 ---
-# `getLatestPrices`
 
-Fetches the latest price messages for one or more pairs.
+# Getting Prices
 
-# Import
+## `getLatestPrices`
 
-```js
-import { getLatestPrices } from '@chronicleprotocol/pull-oracle';
-```
+A function to fetch the latest price messages for one or more pairs.
 
-# Usage
+### Usage
 
 :::info
-`getLatestPrices` requires that you [`authenticate`](./authenticate.md) with a valid auth token first
+`getLatestPrices` requires that you [authenticate](./authenticate.md#authenticate) with a valid auth token first
 :::
 
 ```js
+import { getLatestPrices } from '@chronicleprotocol/pull-oracle';
+
 const prices = await getLatestPrices([
   { wat: "MKR/USD" },
   { wat: "ETH/USD" }
@@ -28,9 +27,9 @@ const prices = await getLatestPrices([
 
 ---
 
-# Returns
+### Returns
 
-Returns a Promise that provides an array of objects
+Returns a promise that provides an array of objects.
 
 ```js
 [
@@ -54,9 +53,9 @@ Returns a Promise that provides an array of objects
 ]
 ```
 
-# Errors
+### Errors
 
-In the event of an error, the return object will be provided with `error: true` and an [error code](./Types.md#authtokencode)
+In the event of an error, the return object will be provided with `error: true` and an [error code](./Types.md#authtokencode).
 
 ```js
 {
@@ -72,29 +71,76 @@ In the event of an error, the return object will be provided with `error: true`
 
 ---
 
-# Parameters
-
-## wats
+### Parameters
 
+#### `wats`
 - Type: `array`
 
-List of pairs to fetch
+The list of pairs to fetch.
 
 ```js
-[
-  {
-    wat: "ETH/USD"
-  }
-]
+[{ wat: "ETH/USD" }, ...]
 ```
 
-### wat
-- Type `string`
+#### `wat`
+- Type: `string`
 
-A valid [pair](./getPairs)
+A valid [pair](#getpairs).
 
-### scheme
+#### `scheme`
 
 - _Optional_
-- Default: ECDSA
+- Default: `ECDSA`
+- Type: [`Scheme`](./Types.md#scheme)
+
+---
+
+## `getPairs`
+
+Provides a list of valid pairs that prices are available for.
+
+```js
+import { getPairs } from '@chronicleprotocol/pull-oracle';
+
+const pairs = await getPairs({ scheme: 'ECDSA' });
+```
+
+### Parameters
+
+#### `options`
+
+- Type: `object`
+
+The object of options to fetch pairs.
+
+```js
+{ scheme: "ECDSA" }
+```
+
+#### `scheme`
 - Type: [`Scheme`](./Types.md#scheme)
+
+---
+
+### Returns
+
+The keys of the `pairs` field are valid [`wat`](#wat) values.
+
+```js
+{
+  "data": {
+    "scheme": "ECDSA",
+    "pairs": {
+      "ETHX/ETH": {
+        "bar": 13,
+        "validators": [
+          "0x130431b4560Cd1d74A990AE86C337a33171FF3c6",
+          "0x15e6e59F95000e5039CBFF5f23FDa9c03d971F66",
+          ...
+        ]
+      },
+      ...
+    }
+  }
+}
+```