From de16977eeb00fa63271f20a9094c900e5538b609 Mon Sep 17 00:00:00 2001 From: Brian Belhumeur <225508+BrianBelhumeur@users.noreply.github.com> Date: Thu, 7 Nov 2024 10:31:02 +0100 Subject: [PATCH 01/17] - Initial commit, docs for pull oracles not yet complete --- .../Chronicle Pull Oracles/GettingStarted.md | 37 +++++++ .../Guides/Chronicle Pull Oracles/Types.md | 45 ++++++++ .../Chronicle Pull Oracles/authenticate.md | 7 ++ .../Chronicle Pull Oracles/getLatestPrices.md | 100 ++++++++++++++++++ .../Chronicle Pull Oracles/isAuthenticated.md | 7 ++ 5 files changed, 196 insertions(+) create mode 100644 docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md create mode 100644 docs/Developers/Guides/Chronicle Pull Oracles/Types.md create mode 100644 docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md create mode 100644 docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md create mode 100644 docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md new file mode 100644 index 0000000..03604d9 --- /dev/null +++ b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md @@ -0,0 +1,37 @@ +--- +sidebar_position: 1 +description: Developer documentation for Chronicle's Pull Oracle +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. + +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. + +```js +import { signAuthToken } from '@chronicleprotocol/pull-oracle'; + +const { token, message } = signAuthToken({ + // private key is 0x prefixed 32 byte hex string + privateKey: "0xabc..." +}) +``` + +:::warning +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 + +```js +import { authenticate } 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 +authenticate(token); + +const prices = await getLatestPrices([ + { wat: "MKR/USD" }, + { wat: "ETH/USD" } +]); +``` diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md new file mode 100644 index 0000000..ade4813 --- /dev/null +++ b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md @@ -0,0 +1,45 @@ +# Types + + + +--- + +# Constants + +## `Scheme` + +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 + +--- + +## `AuthTokenCodes` + +Reponse code for auth token verification + +```js +enum AuthTokenCode { + VALID, + EXPIRED, + NOT_YET_VALID, + INVALID_SIGNATURE, + INVALID_VERSION, + MALFORMED_TOKEN, + SIGNER_NOT_AUTHORIZED +} +``` + +`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 diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md new file mode 100644 index 0000000..11ac340 --- /dev/null +++ b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md @@ -0,0 +1,7 @@ +# `authenticate` + +Validates and caches the auth token for future use with [`getLatestPrices`](./getLatestPrices.md) + +# Returns + +`boolean`: whether the provided auth token is _currently_ valid \ No newline at end of file diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md new file mode 100644 index 0000000..2fbc28b --- /dev/null +++ b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md @@ -0,0 +1,100 @@ +--- +sidebar_position: 2 +description: Pull Oracle - getLatestPrices +keywords: [pull oracle] +--- +# `getLatestPrices` + +Fetches the latest price messages for one or more pairs. + +# Import + +```js +import { getLatestPrices } from '@chronicleprotocol/pull-oracle'; +``` + +# Usage + +:::info +`getLatestPrices` requires that you [`authenticate`](./authenticate.md) with a valid auth token first +::: + +```js +const prices = await getLatestPrices([ + { wat: "MKR/USD" }, + { wat: "ETH/USD" } +]); +``` + +--- + +# Returns + +Returns a Promise that provides an array of objects + +```js +[ + { + wat: string, + scheme: string, + bar: number, + messages: [ + { + wat: string, + val: string, + age: number, + r: string, + s: string, + v: string, + validator: Address + } + ], + callData: Hex + } +] +``` + +# Errors + +In the event of an error, the return object will be provided with `error: true` and an [error code](./Types.md#authtokencode) + +```js +{ + "error": true, + "message": "Invalid authorization token: EXPIRED", + "data": { + "wat": "ETH/USD", + "scheme": "ECDSA" + }, + "code": "EXPIRED" +} +``` + +--- + +# Parameters + +## wats + +- Type: `array` + +List of pairs to fetch + +```js +[ + { + wat: "ETH/USD" + } +] +``` + +### wat +- Type `string` + +A valid [pair](./getPairs) + +### scheme + +- _Optional_ +- Default: ECDSA +- Type: [`Scheme`](./Types.md#scheme) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md b/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md new file mode 100644 index 0000000..39c0420 --- /dev/null +++ b/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md @@ -0,0 +1,7 @@ +# `isAuthenticated` + +Indicates whether the library has a currently valid auth token previously cached by [`authenticate`](./authenticate.md) function + +# Returns + +`boolean`: whether the cached auth token is _currently_ valid \ No newline at end of file From ebae2f7de80f4140e7d7985cf52973d09884aa54 Mon Sep 17 00:00:00 2001 From: vponline Date: Thu, 7 Nov 2024 13:30:37 +0200 Subject: [PATCH 02/17] Review for GettingStarted --- .../Guides/Chronicle Pull Oracles/GettingStarted.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md index 03604d9..a788119 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md +++ b/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'; -// 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([ From 2dbccd44c4ccf18aea1ae0982778cbfb54027779 Mon Sep 17 00:00:00 2001 From: vponline Date: Thu, 7 Nov 2024 13:53:36 +0200 Subject: [PATCH 03/17] Review for getLatestPrices --- .../Chronicle Pull Oracles/getLatestPrices.md | 24 +++++++------------ 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md index 2fbc28b..4d2ba99 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md @@ -7,12 +7,6 @@ keywords: [pull oracle] Fetches the latest price messages for one or more pairs. -# Import - -```js -import { getLatestPrices } from '@chronicleprotocol/pull-oracle'; -``` - # Usage :::info @@ -20,6 +14,8 @@ import { getLatestPrices } from '@chronicleprotocol/pull-oracle'; ::: ```js +import { getLatestPrices } from '@chronicleprotocol/pull-oracle'; + const prices = await getLatestPrices([ { wat: "MKR/USD" }, { wat: "ETH/USD" } @@ -56,7 +52,7 @@ Returns a Promise that provides an array of objects # 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 { @@ -78,23 +74,19 @@ In the event of an error, the return object will be provided with `error: true` - Type: `array` -List of pairs to fetch +The list of pairs to fetch. ```js -[ - { - wat: "ETH/USD" - } -] +[{ wat: "ETH/USD" }, ...] ``` ### wat -- Type `string` +- Type: `string` -A valid [pair](./getPairs) +A valid [pair](./getPairs). ### scheme - _Optional_ -- Default: ECDSA +- Default: `ECDSA` - Type: [`Scheme`](./Types.md#scheme) From e41f56fe1e1a0a8ad65310dbb13c559a2fdaa3eb Mon Sep 17 00:00:00 2001 From: vponline Date: Thu, 7 Nov 2024 13:55:06 +0200 Subject: [PATCH 04/17] Review for Types --- .../Guides/Chronicle Pull Oracles/Types.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md index ade4813..d0cc36b 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md @@ -8,7 +8,7 @@ ## `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 { @@ -16,13 +16,13 @@ enum Scheme { } ``` -`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` -Reponse code for auth token verification +Reponse code for auth token verification. ```js enum AuthTokenCode { @@ -36,10 +36,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 From ba0ccfd90c623207e947c5b0b99cfadee0ff90e4 Mon Sep 17 00:00:00 2001 From: vponline Date: Thu, 7 Nov 2024 14:00:02 +0200 Subject: [PATCH 05/17] Review for authenticate --- .../Chronicle Pull Oracles/authenticate.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md index 11ac340..94ae3be 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md @@ -1,7 +1,19 @@ # `authenticate` -Validates and caches the auth token for future use with [`getLatestPrices`](./getLatestPrices.md) +Validates and caches the auth token 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 \ No newline at end of file +`boolean`: whether the provided auth token is _currently_ valid. \ No newline at end of file From 8814e09249d3d00251a34c43bb7107b27cc625ef Mon Sep 17 00:00:00 2001 From: vponline Date: Thu, 7 Nov 2024 14:04:56 +0200 Subject: [PATCH 06/17] Review for isAuthenticated --- .../Chronicle Pull Oracles/isAuthenticated.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md b/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md index 39c0420..eae296c 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md @@ -1,7 +1,18 @@ # `isAuthenticated` -Indicates whether the library has a currently valid auth token previously cached by [`authenticate`](./authenticate.md) function +Indicates whether the library has a currently valid auth token previously cached by [`authenticate`](./authenticate.md) 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 \ No newline at end of file +`boolean`: whether the cached auth token is _currently_ valid. \ No newline at end of file From 09937749f4e785803600df93794ea4cf461131bb Mon Sep 17 00:00:00 2001 From: vponline Date: Thu, 7 Nov 2024 16:57:54 +0200 Subject: [PATCH 07/17] Refactor links --- docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md | 2 +- .../Guides/Chronicle Pull Oracles/getLatestPrices.md | 4 ++-- .../Guides/Chronicle Pull Oracles/isAuthenticated.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md index 94ae3be..a272eab 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md @@ -1,6 +1,6 @@ # `authenticate` -Validates and caches the auth token for future use with [`getLatestPrices`](./getLatestPrices.md). +Validates and caches the auth token for future use with [getLatestPrices](./getLatestPrices.md). # Usage diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md index 4d2ba99..d6d8d08 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md @@ -10,7 +10,7 @@ Fetches the latest price messages for one or more pairs. # Usage :::info -`getLatestPrices` requires that you [`authenticate`](./authenticate.md) with a valid auth token first +`getLatestPrices` requires that you [authenticate](./authenticate.md) with a valid auth token first ::: ```js @@ -26,7 +26,7 @@ const prices = await getLatestPrices([ # Returns -Returns a Promise that provides an array of objects +Returns a promise that provides an array of objects. ```js [ diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md b/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md index eae296c..425738a 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md @@ -1,6 +1,6 @@ # `isAuthenticated` -Indicates whether the library has a currently valid auth token previously cached by [`authenticate`](./authenticate.md) function. +Indicates whether the library has a currently valid auth token previously cached by the [authenticate](./authenticate.md) function. # Usage From 3e0dd97b652faed8958edb0cc4a7583e9ef14145 Mon Sep 17 00:00:00 2001 From: vponline Date: Thu, 7 Nov 2024 17:02:32 +0200 Subject: [PATCH 08/17] Refactor Types --- .../Guides/Chronicle Pull Oracles/Types.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md index d0cc36b..9b29f5e 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md @@ -1,12 +1,8 @@ # 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. @@ -20,9 +16,9 @@ enum Scheme { --- -## `AuthTokenCodes` +### `AuthTokenCodes` -Reponse code for auth token verification. +Response codes for auth token verification. ```js enum AuthTokenCode { From 0d3ac21c35480ba81d7e7b3b25740a3c7950c815 Mon Sep 17 00:00:00 2001 From: vponline Date: Thu, 7 Nov 2024 17:07:49 +0200 Subject: [PATCH 09/17] Fix page orders --- docs/Developers/Guides/Chronicle Pull Oracles/Types.md | 8 +++++++- .../Guides/Chronicle Pull Oracles/authenticate.md | 6 ++++++ .../Guides/Chronicle Pull Oracles/getLatestPrices.md | 3 ++- .../Guides/Chronicle Pull Oracles/isAuthenticated.md | 6 ++++++ 4 files changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md index 9b29f5e..482bfc9 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md @@ -1,3 +1,9 @@ +--- +sidebar_position: 5 +description: Pull Oracle - Types +keywords: [pull oracle] +--- + # Types ## Constants @@ -12,7 +18,7 @@ enum Scheme { } ``` -- `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. --- diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md index a272eab..bba4c0a 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md @@ -1,3 +1,9 @@ +--- +sidebar_position: 2 +description: Pull Oracle - authenticate +keywords: [pull oracle] +--- + # `authenticate` Validates and caches the auth token for future use with [getLatestPrices](./getLatestPrices.md). diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md index d6d8d08..362a1d4 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md @@ -1,8 +1,9 @@ --- -sidebar_position: 2 +sidebar_position: 3 description: Pull Oracle - getLatestPrices keywords: [pull oracle] --- + # `getLatestPrices` Fetches the latest price messages for one or more pairs. diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md b/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md index 425738a..059e59f 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md @@ -1,3 +1,9 @@ +--- +sidebar_position: 4 +description: Pull Oracle - isAuthenticated +keywords: [pull oracle] +--- + # `isAuthenticated` Indicates whether the library has a currently valid auth token previously cached by the [authenticate](./authenticate.md) function. From 1c8fd9f1e981e0c1578a30c1566cb7b8d8eb0d11 Mon Sep 17 00:00:00 2001 From: vponline Date: Fri, 8 Nov 2024 11:47:49 +0200 Subject: [PATCH 10/17] Refactor pages --- .../Chronicle Pull Oracles/GettingStarted.md | 2 +- .../Guides/Chronicle Pull Oracles/Types.md | 2 +- .../Chronicle Pull Oracles/authenticate.md | 72 +++++++++++++++++-- .../Chronicle Pull Oracles/getLatestPrices.md | 22 +++--- .../Chronicle Pull Oracles/isAuthenticated.md | 24 ------- 5 files changed, 81 insertions(+), 41 deletions(-) delete mode 100644 docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md index a788119..d634972 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md @@ -29,7 +29,7 @@ Once the auth token is generated on the server, pass it to the client and regist 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 the server // `authenticate` caches the token in memory so it only needs to be called once per session diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md index 482bfc9..c4fb1cf 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 4 description: Pull Oracle - Types keywords: [pull oracle] --- diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md index bba4c0a..1333f3d 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md @@ -4,11 +4,56 @@ description: Pull Oracle - authenticate keywords: [pull oracle] --- -# `authenticate` +# Authentication -Validates and caches the auth token for future use with [getLatestPrices](./getLatestPrices.md). +## `signAuthToken` -# Usage +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'; @@ -18,8 +63,25 @@ import { authenticate } from '@chronicleprotocol/pull-oracle'; authenticate(token); ``` +### Returns + +- `boolean`: whether the provided auth token is _currently_ valid. + --- -# Returns +# `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 provided auth token is _currently_ valid. \ No newline at end of file +- `boolean`: whether the cached auth token is _currently_ valid. \ No newline at end of file diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md index 362a1d4..d9e431a 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md @@ -4,14 +4,16 @@ description: Pull Oracle - getLatestPrices keywords: [pull oracle] --- -# `getLatestPrices` +# Getting Prices -Fetches the latest price messages for one or more pairs. +## `getLatestPrices` -# Usage +A function to fetch the latest price messages for one or more pairs. + +### 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 @@ -25,7 +27,7 @@ const prices = await getLatestPrices([ --- -# Returns +### Returns Returns a promise that provides an array of objects. @@ -51,7 +53,7 @@ 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). @@ -69,9 +71,9 @@ In the event of an error, the return object will be provided with `error: true` --- -# Parameters +### Parameters -## wats +#### `wats` - Type: `array` @@ -81,12 +83,12 @@ The list of pairs to fetch. [{ wat: "ETH/USD" }, ...] ``` -### wat +#### `wat` - Type: `string` A valid [pair](./getPairs). -### scheme +#### `scheme` - _Optional_ - Default: `ECDSA` diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md b/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md deleted file mode 100644 index 059e59f..0000000 --- a/docs/Developers/Guides/Chronicle Pull Oracles/isAuthenticated.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -sidebar_position: 4 -description: Pull Oracle - isAuthenticated -keywords: [pull oracle] ---- - -# `isAuthenticated` - -Indicates whether the library has a currently valid auth token previously cached by the [authenticate](./authenticate.md) 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. \ No newline at end of file From 3a62c69da7f408a4a57903b7426a9b8dbcaba59d Mon Sep 17 00:00:00 2001 From: vponline Date: Fri, 8 Nov 2024 12:32:24 +0200 Subject: [PATCH 11/17] Add getPairs function info --- .../Chronicle Pull Oracles/getLatestPrices.md | 55 ++++++++++++++++++- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md index d9e431a..09efe91 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md @@ -74,7 +74,6 @@ In the event of an error, the return object will be provided with `error: true` ### Parameters #### `wats` - - Type: `array` The list of pairs to fetch. @@ -86,10 +85,62 @@ The list of pairs to fetch. #### `wat` - Type: `string` -A valid [pair](./getPairs). +A valid [pair](#getpairs). #### `scheme` - _Optional_ - 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", + ... + ] + }, + ... + } + } +} +``` From f337cd86d5f483af4def95abc346a83347a042ed Mon Sep 17 00:00:00 2001 From: Brian Belhumeur <225508+BrianBelhumeur@users.noreply.github.com> Date: Sat, 9 Nov 2024 22:33:52 +0100 Subject: [PATCH 12/17] - rename getLatestPrices to getPrices --- .../Guides/Chronicle Pull Oracles/authenticate.md | 4 ++-- .../Guides/Chronicle Pull Oracles/getLatestPrices.md | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md index 1333f3d..cce4aa9 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md @@ -8,7 +8,7 @@ keywords: [pull oracle] ## `signAuthToken` -A server-side function which creates an auth token to be used to [authenticate](#authenticate) [getLatestPrices](./getLatestPrices.md) requests. +A server-side function which creates an auth token to be used to [authenticate](#authenticate) [getPrices](./getPrices.md) requests. ### Usage @@ -51,7 +51,7 @@ const { token, message } = signAuthToken({ ## `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). +A client-side function which validates and caches the auth token which was received from the server for future use with [getPrices](./getPrices.md). ### Usage diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md index 09efe91..b622d56 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md @@ -1,25 +1,25 @@ --- sidebar_position: 3 -description: Pull Oracle - getLatestPrices +description: Pull Oracle - getPrices keywords: [pull oracle] --- # Getting Prices -## `getLatestPrices` +## `getPrices` A function to fetch the latest price messages for one or more pairs. ### Usage :::info -`getLatestPrices` requires that you [authenticate](./authenticate.md#authenticate) with a valid auth token first +`getPrices` requires that you [authenticate](./authenticate.md#authenticate) with a valid auth token first ::: ```js -import { getLatestPrices } from '@chronicleprotocol/pull-oracle'; +import { getPrices } from '@chronicleprotocol/pull-oracle'; -const prices = await getLatestPrices([ +const prices = await getPrices([ { wat: "MKR/USD" }, { wat: "ETH/USD" } ]); From 84334372b330ed874cf3cfcb876ba3a0888933c2 Mon Sep 17 00:00:00 2001 From: Brian Belhumeur <225508+BrianBelhumeur@users.noreply.github.com> Date: Sat, 9 Nov 2024 22:37:05 +0100 Subject: [PATCH 13/17] - rename getLatestPrices to getPrices --- .../Guides/Chronicle Pull Oracles/GettingStarted.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md index d634972..71a639b 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md @@ -29,13 +29,13 @@ Once the auth token is generated on the server, pass it to the client and regist Authenticating a user session on the client and fetching prices: ```js -import { authenticate, getLatestPrices } from '@chronicleprotocol/pull-oracle'; +import { authenticate, getPrices } 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); -const prices = await getLatestPrices([ +const prices = await getPrices([ { wat: "MKR/USD" }, { wat: "ETH/USD" } ]); From 5e04f9214eff74ed0e599fb62322477f1354e590 Mon Sep 17 00:00:00 2001 From: Brian Belhumeur <225508+BrianBelhumeur@users.noreply.github.com> Date: Sun, 10 Nov 2024 22:10:00 +0100 Subject: [PATCH 14/17] - Updated getLatestPrices to getPrices --- .../Chronicle Pull Oracles/authenticate.md | 18 +++++++++--------- .../{getLatestPrices.md => getPrices.md} | 12 ++++++------ 2 files changed, 15 insertions(+), 15 deletions(-) rename docs/Developers/Guides/Chronicle Pull Oracles/{getLatestPrices.md => getPrices.md} (93%) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md index cce4aa9..90690bc 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md @@ -26,15 +26,15 @@ const { token, message } = signAuthToken({ ```js { - token: "...", - message: { - description: "Chronicle API token", - version: 1, - validFrom: 1730992419, - validTo: 1730994251, - signer: "0x...", - nonce: 1077701, - } + token: "...", + message: { + description: "Chronicle API token", + version: 1, + validFrom: 1730992419, + validTo: 1730994251, + signer: "0x...", + nonce: 1077701, + } } ``` diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md b/docs/Developers/Guides/Chronicle Pull Oracles/getPrices.md similarity index 93% rename from docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md rename to docs/Developers/Guides/Chronicle Pull Oracles/getPrices.md index b622d56..bedbc69 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/getLatestPrices.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/getPrices.md @@ -59,13 +59,13 @@ In the event of an error, the return object will be provided with `error: true` ```js { - "error": true, - "message": "Invalid authorization token: EXPIRED", - "data": { - "wat": "ETH/USD", - "scheme": "ECDSA" + error: true, + message: "Invalid authorization token: EXPIRED", + data: { + wat: "ETH/USD", + scheme: "ECDSA" }, - "code": "EXPIRED" + code: "EXPIRED" } ``` From 01febdf4bc2df91dcf8cfdbb37f1ea70a8a7b38f Mon Sep 17 00:00:00 2001 From: Brian Belhumeur <225508+BrianBelhumeur@users.noreply.github.com> Date: Tue, 26 Nov 2024 15:12:48 +0100 Subject: [PATCH 15/17] - Updated type docs --- .../Chronicle Pull Oracles/GettingStarted.md | 2 +- .../Guides/Chronicle Pull Oracles/Types.md | 136 +++++++++++++++++- .../Chronicle Pull Oracles/authenticate.md | 18 +-- 3 files changed, 134 insertions(+), 22 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md index 71a639b..195ec01 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md @@ -3,7 +3,7 @@ sidebar_position: 1 description: Developer documentation for Chronicle's Pull Oracle keywords: [pull oracle] --- -# Getting started +# Getting Started 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. diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md index c4fb1cf..d3143fa 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md @@ -3,16 +3,128 @@ sidebar_position: 4 description: Pull Oracle - Types keywords: [pull oracle] --- +# Types & Constants -# Types +## Types -## Constants +### `APIResponseError` + +Occurs when the API successfully receives a response from the server, but the response is an error. + +```typescript +interface APIResponseError { + error: true; + data?: any; + message: string; + code: AuthTokenCode | APIErrorCode; +} +``` + +--- + +### `AuthTokenMessage` + +The message returned from [`signAuthToken`](./authenticate.md#signauthtoken). + +```typescript +type AuthTokenMessage { + description: string; + version: number; + validFrom: number; + validTo: number; + signer: Address; + nonce: number; +} +``` + +- `description`: the description of the token +- `version`: the authentication API version number +- `validFrom`: unix epoch timestamp starting from then the token is valid +- `validTo`: unix epoch timestamp until when the auth token is valid +- `signer`: the address of the signer +- `nonce`: unique number + + +--- + +### `PairData` + +The data structure returned from [`getPairs`](./getPairs.md) + +```typescript +type PairData = { + scheme: Scheme; + pairs: Record; +} +``` + +--- + +### `PriceData` + +The data structure returned from [`getPrices`](./getPrices.md) + +```typescript +type PriceData = { + wat: string; + scheme: Scheme; + bar: number; + messages: PriceMessage[]; +} +``` + +--- + +### `PriceMessage` + +The data structure of an individual price message. A batch of price messages makes up a single oracle price. + +```typescript +type PriceMessage { + wat: string; + val: string; + age: number; + r: string; + s: string; + v: string; +} +``` + +--- + +### `PriceRequest` + +The data structure of the argument passed to [`getPrices`](./getPrices.md) + +```typescript +type PriceRequest { + wat: string; + scheme?: Scheme; +} +``` + +--- + +### `ValidatorData` + +The data structure returned from [`getPairs`](./getPairs.md) + +```typescript +type ValidatorData { + scheme: Scheme; + validators: Validator[]; +} +``` + +--- + +# Constants ### `Scheme` Encryption scheme for price messages. Currently there is only one option, however more options may be offered in the future. -```js +```typescript enum Scheme { ECDSA } @@ -26,11 +138,12 @@ enum Scheme { Response codes for auth token verification. -```js +```typescript enum AuthTokenCode { VALID, EXPIRED, NOT_YET_VALID, + DURATION_EXCEEDS_MAX, INVALID_SIGNATURE, INVALID_VERSION, MALFORMED_TOKEN, @@ -41,7 +154,22 @@ 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 +- `DURATION_EXCEEDS_MAX`: The period between auth token start and end times is too long - `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 + +--- + +### `APIErrorCode` + +Response codes for API errors. + +```typescript +enum APIErrorCode { + FAILED_REQUEST +} +``` + +- `FAILED_REQUEST`: The API request failed to receive a valid response from the server diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md index 90690bc..c30bbd2 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md @@ -27,26 +27,10 @@ const { token, message } = signAuthToken({ ```js { token: "...", - message: { - description: "Chronicle API token", - version: 1, - validFrom: 1730992419, - validTo: 1730994251, - signer: "0x...", - nonce: 1077701, - } + message: AuthTokenMessage } ``` -- `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` From 095ae8ac214f2c754430e3301e65ee4a9b5c3c8b Mon Sep 17 00:00:00 2001 From: Brian Belhumeur <225508+BrianBelhumeur@users.noreply.github.com> Date: Thu, 12 Dec 2024 13:54:13 +0100 Subject: [PATCH 16/17] - Wrap up of first draft of pull oracle docs --- .../Chronicle Pull Oracles/GettingStarted.md | 12 +- .../Guides/Chronicle Pull Oracles/Types.md | 91 +++++++++++---- .../Guides/Chronicle Pull Oracles/getPairs.md | 100 +++++++++++++++++ .../Chronicle Pull Oracles/getPrices.md | 104 +++++------------- .../Chronicle Pull Oracles/getValidators.md | 79 +++++++++++++ 5 files changed, 285 insertions(+), 101 deletions(-) create mode 100644 docs/Developers/Guides/Chronicle Pull Oracles/getPairs.md create mode 100644 docs/Developers/Guides/Chronicle Pull Oracles/getValidators.md diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md index 195ec01..490f08f 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md @@ -5,13 +5,13 @@ keywords: [pull oracle] --- # Getting Started -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. +Chronicle's pull oracles offer the absolute freshest pricing information on-demand. We provide an [NPM package](https://www.npmjs.com/package/@chronicleprotocol/pull-oracle) for simple integrations. Authentication is handled via tokens based on the [Ethereum Signed Messages](https://eips.ethereum.org/EIPS/eip-191) protocol. :::info -Your public signing key must be allow-listed on our servers before you can generate tokens. +Your public signing key must be allow-listed on our servers before your tokens will be accepted as valid. ::: -Generating authentication tokens on the server: +### Generating authentication tokens on the server: ```js import { signAuthToken } from '@chronicleprotocol/pull-oracle'; @@ -27,7 +27,7 @@ We highly recommend following best practices for private key generation and stor 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: +### Authenticating a user session on the client and fetching prices: ```js import { authenticate, getPrices } from '@chronicleprotocol/pull-oracle'; @@ -36,7 +36,7 @@ import { authenticate, getPrices } from '@chronicleprotocol/pull-oracle'; authenticate(token); const prices = await getPrices([ - { wat: "MKR/USD" }, - { wat: "ETH/USD" } + { wat: "MKR/USD", blockchain: "ETH" }, + { wat: "ETH/USD", blockchain: "ETH" } ]); ``` diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md index d3143fa..a6c142e 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/Types.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/Types.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 6 description: Pull Oracle - Types keywords: [pull oracle] --- @@ -9,9 +9,9 @@ keywords: [pull oracle] ### `APIResponseError` -Occurs when the API successfully receives a response from the server, but the response is an error. +Occurs when there is an error processing the request. -```typescript +```ts interface APIResponseError { error: true; data?: any; @@ -26,7 +26,7 @@ interface APIResponseError { The message returned from [`signAuthToken`](./authenticate.md#signauthtoken). -```typescript +```ts type AuthTokenMessage { description: string; version: number; @@ -37,24 +37,60 @@ type AuthTokenMessage { } ``` -- `description`: the description of the token +- `description`: the description of the token, e.g. "Chronicle API token" - `version`: the authentication API version number -- `validFrom`: unix epoch timestamp starting from then the token is valid -- `validTo`: unix epoch timestamp until when the auth token is valid +- `validFrom`: unix epoch timestamp starting from then the token is valid, inclusive +- `validTo`: unix epoch timestamp until when the auth token is valid, inclusive - `signer`: the address of the signer - `nonce`: unique number +--- + +### `Blockchain` + +A blockchain identifier of either the `shortName` or `chainId` per [chainid.network](https://chainid.network/chains.json). + +```ts +type Blockchain = string | number; +``` + --- ### `PairData` The data structure returned from [`getPairs`](./getPairs.md) -```typescript +```ts type PairData = { scheme: Scheme; - pairs: Record; + blockchain: Blockchain; + pairs: Pairs; +} +``` + +--- + +### `Pairs` + +The data structure containing pairs. + +```ts +type Pairs = Record; +``` + +Example: +```ts +{ + "BTC/USD": { + bar: 13, + validators: [ + "0xabc123...", + "0xabc123...", + "0xabc123...", + ... + ] + } } ``` @@ -64,7 +100,7 @@ type PairData = { The data structure returned from [`getPrices`](./getPrices.md) -```typescript +```ts type PriceData = { wat: string; scheme: Scheme; @@ -79,7 +115,7 @@ type PriceData = { The data structure of an individual price message. A batch of price messages makes up a single oracle price. -```typescript +```ts type PriceMessage { wat: string; val: string; @@ -96,7 +132,7 @@ type PriceMessage { The data structure of the argument passed to [`getPrices`](./getPrices.md) -```typescript +```ts type PriceRequest { wat: string; scheme?: Scheme; @@ -109,7 +145,7 @@ type PriceRequest { The data structure returned from [`getPairs`](./getPairs.md) -```typescript +```ts type ValidatorData { scheme: Scheme; validators: Validator[]; @@ -118,18 +154,22 @@ type ValidatorData { --- -# Constants +## Constants + +:::info +Note: all enum values are identical to their keys, but only keys are shown here for simplicity +::: + ### `Scheme` Encryption scheme for price messages. Currently there is only one option, however more options may be offered in the future. -```typescript +```ts 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. --- @@ -138,7 +178,7 @@ enum Scheme { Response codes for auth token verification. -```typescript +```ts enum AuthTokenCode { VALID, EXPIRED, @@ -166,10 +206,23 @@ enum AuthTokenCode { Response codes for API errors. -```typescript +```ts enum APIErrorCode { - FAILED_REQUEST + FAILED_REQUEST, + SCHEME_NOT_SUPPORTED, + BLOCKCHAIN_NOT_SUPPORTED, + PAIR_NOT_SUPPORTED, + MISSING_REQUIRED_PARAMETER, + METHOD_NOT_ALLOWED, + INVALID_REQUEST_DATA, } ``` - `FAILED_REQUEST`: The API request failed to receive a valid response from the server +- `SCHEME_NOT_SUPPORTED`: The API request was made for a [Scheme](#scheme) that is not supported +- `BLOCKCHAIN_NOT_SUPPORTED`: The API request was made for a [Blockchain](#blockchain) that is not supported +- `PAIR_NOT_SUPPORTED`: The API request was made for a [Pair](#pair) that is not supported +- `MISSING_REQUIRED_PARAMETER`: The API request was missing a required parameter and was therefore unable to complete +- `METHOD_NOT_ALLOWED`: The HTTP method used to access the API is not allowed +- `INVALID_REQUEST_DATA`: The request data was not parseable or inadequate to complete the request + diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getPairs.md b/docs/Developers/Guides/Chronicle Pull Oracles/getPairs.md new file mode 100644 index 0000000..8e259a1 --- /dev/null +++ b/docs/Developers/Guides/Chronicle Pull Oracles/getPairs.md @@ -0,0 +1,100 @@ +--- +sidebar_position: 4 +description: Pull Oracle - getPairs +keywords: [pull oracle] +--- + +# Getting Pairs + +## `getPairs` + +Returns the pairs supported on a given [`Blockchain`](./Types.md#blockchain), and optionally with a given [`Scheme`](./Types.md#scheme). + +### Usage + +```ts +import { getPairs } from '@chronicleprotocol/pull-oracle'; + +const pairs = await getPairs({ blockchain }); +``` + +--- + +### Returns + +Returns a promise that provides the [`Blockchain`](./Types.md#blockchain), [`Scheme`](./Types.md#scheme), and a [`Pairs`](./Types.md#pairs) object. + +```ts +interface PairData { + blockchain: Blockchain, + scheme: Scheme, + pairs: { + [pair: string]: { + bar: number, + validators: Address[] + }, + ... + } +} +``` + +#### Example + +```ts +{ + blockchain: "ETH", + scheme: "ECDSA", + pairs: { + "BTC/USD": { + bar: 13, + validators: [ + "0xabc123...", + "0xabc123...", + "0xabc123...", + ... + ] + }, + "ETH/USD": { + bar: 13, + validators: [ + "0xabc123...", + "0xabc123...", + "0xabc123...", + ... + ] + }, + ... + } +} +``` + +### Parameters + +#### `blockchain` +- Type: [`Blockchain`](./Types.md#blockchain) + +A blockhain identifier indicating on which chain the pairs are going to be used. + +#### `scheme` +- _Optional_ +- Type: [`Scheme`](./Types.md#scheme) +- Default: `ECDSA` + +The encryption scheme used for price messages of these pairs + +### Errors + +In the event of an error, the return object will be an [`APIResponseError`](./Types.md#apiresponseerror). + +#### Example +```ts +{ + error: true, + message: `VADER blockchain not supported`, + data: { + scheme: "ECDSA", + blockchain: "VADER" + }, + code: APIErrorCode.BLOCKCHAIN_NOT_SUPPORTED +} +``` diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getPrices.md b/docs/Developers/Guides/Chronicle Pull Oracles/getPrices.md index bedbc69..6fa0de3 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/getPrices.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/getPrices.md @@ -8,7 +8,7 @@ keywords: [pull oracle] ## `getPrices` -A function to fetch the latest price messages for one or more pairs. +Fetches the latest price messages for one or more pairs on a given blockchain. ### Usage @@ -16,26 +16,25 @@ A function to fetch the latest price messages for one or more pairs. `getPrices` requires that you [authenticate](./authenticate.md#authenticate) with a valid auth token first ::: -```js +```ts import { getPrices } from '@chronicleprotocol/pull-oracle'; const prices = await getPrices([ - { wat: "MKR/USD" }, - { wat: "ETH/USD" } + { wat: "MKR/USD", blockchain: "ETH" }, + { wat: "ETH/USD", blockchain: "ETH" } ]); ``` ---- - ### Returns -Returns a promise that provides an array of objects. +Returns a promise that provides an array of objects corresponding to the input array of [`wats`](#wats). -```js +```ts [ { wat: string, - scheme: string, + scheme: Scheme, + blockchain: Blockchain, bar: number, messages: [ { @@ -53,24 +52,6 @@ Returns a promise that provides an array of objects. ] ``` -### Errors - -In the event of an error, the return object will be provided with `error: true` and an [error code](./Types.md#authtokencode). - -```js -{ - error: true, - message: "Invalid authorization token: EXPIRED", - data: { - wat: "ETH/USD", - scheme: "ECDSA" - }, - code: "EXPIRED" -} -``` - ---- - ### Parameters #### `wats` @@ -78,69 +59,40 @@ In the event of an error, the return object will be provided with `error: true` The list of pairs to fetch. -```js -[{ wat: "ETH/USD" }, ...] +```ts +[{ wat: "ETH/USD", blockchain: "ETH" }, ...] ``` #### `wat` - Type: `string` -A valid [pair](#getpairs). - -#### `scheme` - -- _Optional_ -- Default: `ECDSA` -- Type: [`Scheme`](./Types.md#scheme) +A valid [pair](./getPairs.md). ---- +#### `blockchain` +- Type: [`Blockchain`](./Types.md#blockchain) -## `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" } -``` +A blockhain identifier indicating on which chain the messages are going to be verified. #### `scheme` +- _Optional_ +- Default: `ECDSA` - Type: [`Scheme`](./Types.md#scheme) ---- +The encryption scheme used for price messages -### Returns +### Errors -The keys of the `pairs` field are valid [`wat`](#wat) values. +In the event of an error, the return object will be provided with `error: true` and an [error code](./Types.md#authtokencode). -```js +```ts { - "data": { - "scheme": "ECDSA", - "pairs": { - "ETHX/ETH": { - "bar": 13, - "validators": [ - "0x130431b4560Cd1d74A990AE86C337a33171FF3c6", - "0x15e6e59F95000e5039CBFF5f23FDa9c03d971F66", - ... - ] - }, - ... - } - } + error: true, + message: "Invalid authorization token: EXPIRED", + data: { + wat: "ETH/USD", + scheme: "ECDSA", + blockchain: "ETH" + }, + code: "EXPIRED" } ``` diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/getValidators.md b/docs/Developers/Guides/Chronicle Pull Oracles/getValidators.md new file mode 100644 index 0000000..85fadfd --- /dev/null +++ b/docs/Developers/Guides/Chronicle Pull Oracles/getValidators.md @@ -0,0 +1,79 @@ +--- +sidebar_position: 5 +description: Pull Oracle - getValidators +keywords: [pull oracle] +--- + +# Getting Validators + +## `getValidators` + +Returns the validators supported on a given [`Blockchain`](./Types.md#blockchain), and optionally with a given [`Scheme`](./Types.md#scheme). + +### Usage + +```ts +import { getValidators } from '@chronicleprotocol/pull-oracle'; + +const validators = await getValidators({ blockchain }); +``` + +--- + +### Returns + +Returns a promise that provides the [`Blockchain`](./Types.md#blockchain), [`Scheme`](./Types.md#scheme), and a [`Validators`](./Types.md#validators) array of addresses. + +```ts +interface ValidatorData { + blockchain: Blockchain; + scheme: Scheme; + validators: Address[]; +} +``` + +#### Example + +```ts +{ + blockchain: "ETH", + scheme: "ECDSA", + validators: [ + "0xabc123...", + "0xabc123...", + "0xabc123...", + ... + ] +} +``` + +### Parameters + +#### `blockchain` +- Type: [`Blockchain`](./Types.md#blockchain) + +A blockhain identifier indicating on which chain the validators are going to be used. + +#### `scheme` +- _Optional_ +- Type: [`Scheme`](./Types.md#scheme) +- Default: `ECDSA` + +The encryption scheme used for price messages of these validators + +### Errors + +In the event of an error, the return object will be an [`APIResponseError`](./Types.md#apiresponseerror). + +#### Example +```ts +{ + error: true, + message: `VADER blockchain not supported`, + data: { + scheme: "ECDSA", + blockchain: "VADER" + }, + code: APIErrorCode.BLOCKCHAIN_NOT_SUPPORTED +} +``` From 1dbdc71c8367821458ca00ac5e58c45a58e49535 Mon Sep 17 00:00:00 2001 From: vponline Date: Fri, 20 Dec 2024 15:45:25 +0200 Subject: [PATCH 17/17] Add await to signAuthToken and parameters --- .../Chronicle Pull Oracles/GettingStarted.md | 2 +- .../Chronicle Pull Oracles/authenticate.md | 22 ++++++++++++++++++- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md index 490f08f..bc71e2e 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/GettingStarted.md @@ -15,7 +15,7 @@ Your public signing key must be allow-listed on our servers before your tokens w ```js import { signAuthToken } from '@chronicleprotocol/pull-oracle'; -const { token, message } = signAuthToken({ +const { token, message } = await signAuthToken({ // private key is 0x prefixed 32 byte hex string privateKey: "0xabc..." }) diff --git a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md index c30bbd2..8e3879c 100644 --- a/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md +++ b/docs/Developers/Guides/Chronicle Pull Oracles/authenticate.md @@ -16,7 +16,7 @@ Generating authentication tokens on the server: ```js import { signAuthToken } from '@chronicleprotocol/pull-oracle'; -const { token, message } = signAuthToken({ +const { token, message } = await signAuthToken({ // private key is 0x prefixed 32 byte hex string privateKey: "0xabc..." }) @@ -31,6 +31,26 @@ const { token, message } = signAuthToken({ } ``` +### Parameters + +```ts +{ privateKey: "0xabc...", duration: 1800 } +``` + +#### `privateKey` + +- Type: `string` + +The `privateKey` for the account signing the auth token. + +#### `duration` + +- _Optional_ +- Default: 1800 +- Type: `number` + +The duration of validity for the auth token in seconds. + --- ## `authenticate`