diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 5d5ba09..2b7f885 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -12,8 +12,17 @@ export default defineConfig({ ], sidebar: [ + { + text: 'Introduction', + collapsed: false, + items: [ + { text: 'What is ShadeJS?', link: 'what-is-shadejs' }, + { text: 'Getting Started', link: 'getting-started' }, + ] + }, { text: 'Examples', + collapsed: false, items: [ { text: 'Swap', link: '/swap' }, { text: 'Oracle', link: '/oracle' }, diff --git a/docs/batch-query.md b/docs/batch-query.md index f929bb2..2abfb4b 100644 --- a/docs/batch-query.md +++ b/docs/batch-query.md @@ -2,7 +2,7 @@ This page demonstrates how to query using a smart contract batch query router. The purposes of a query router is to combine multiple queries to one or more contracts into a single http request. This reduces load on the node infrastructure and is faster for retrieving data than would otherwise be obtained by individual contract queries. -The batch query function is generalized to work with any contract queries. Miscellaneous Shade.js services already implement the batch query router, for example the Pairs Info Query +The batch query function is generalized to work with any contract queries. Miscellaneous ShadeJS services already implement the batch query router, for example the Pairs Info Query ## Performance @@ -19,7 +19,7 @@ All of the following results are run with 500 total queries ::: warning This testing was completed with a limited sample size and optimal batch size has -not yet determined. There is also an unknown variable of the quality of the infrastructure being used to perform these queries. It is encouraged to perform your own optimization testing when working with a batch query router. +not yet determined. There is also an unknown variable of the quality of the infrastructure you would be using to perform these queries. It is encouraged to perform your own optimization testing when working with a batch query router. ::: ## Batch Query diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..b9de667 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,84 @@ +# Getting Started + +## Installation + +::: code-group + +```sh [npm] +$ npm add TBD_LIBRARY_NAME +``` + +```sh [yarn] +$ yarn add TBD_LIBRARY_NAME +``` +::: + +## Example Query + +### Standard Syntax +```js +/* +* Queries the configuration for the swap pair +*/ +async function queryPairConfig({ + contractAddress, + codeHash, + lcdEndpoint, + chainId, +}:{ + contractAddress: string, + codeHash?: string, // recommended for fastest query performance + lcdEndpoint?: string, // defaults to public endpoint + chainId?: string, // defaults to mainnet +}): Promise +``` +::: warning +The LCD endpoint is an optional property. We provide one as a default inside ShadeJS to get you started quickly on Secret Network mainnet using a public API. It is still recommended that you provide your own because performance of the default endpoint is not guaranteed. +::: +```js +try{ + const output = await queryPairConfig({ + contractAddress: '[PAIR_CONTRACT_ADDRESS]', + }) + // do something with the successful output +} catch { + // do something with the error +} +``` +### RxJS Syntax + +Under the hood, ShadeJS uses RxJS as an observables library to build asynchronous functions. The async functions provided for interacting with the blockchain have an RxJS version as an alternative, and users can decide which one to use based on their preference. +::: tip +The standard async/await syntax funcion is designed as a simple wrapper function around the RxJS, so either way you are calling the RxJS version! +::: + +```js +/* +* Queries the configuration for the swap pair +*/ +function queryPairConfig$({ + contractAddress, + codeHash, + lcdEndpoint, + chainId, +}:{ + contractAddress: string, + codeHash?: string, + lcdEndpoint?: string, + chainId?: string, +}): Observable +``` +```js +queryPairConfig$({ + contractAddress: '[PAIR_CONTRACT_ADDRESS]', +}).subscribe({ + next: () => { + // do something with the successful output + }, + error: () => { + // do something with the error + } +}) + +``` + diff --git a/docs/oracle.md b/docs/oracle.md index dfcb418..dcff737 100644 --- a/docs/oracle.md +++ b/docs/oracle.md @@ -20,9 +20,6 @@ async function queryPrice({ chainId?: string, }) : Promise ``` -::: warning -It is recommended that you provide your own LCD endpoint, although we do provide a default mainnet option. Performance of the default endpoint is not guaranteed. -::: **output** @@ -76,9 +73,6 @@ async function queryPrices({ chainId?: string, }) : Promise ``` -::: warning -It is recommended that you provide your own LCD endpoint, although we do provide a default mainnet option. Performance of the default endpoint is not guaranteed. -::: **output** diff --git a/docs/swap.md b/docs/swap.md index f58a6e4..c5c722e 100644 --- a/docs/swap.md +++ b/docs/swap.md @@ -8,6 +8,9 @@ This page demonstrates how to query the ShadeSwap contracts **input** ```js +/* +* Queries the configuration for the swap factory +*/ async function queryFactoryConfig({ contractAddress, codeHash, @@ -20,9 +23,6 @@ async function queryFactoryConfig({ chainId?: string, // defaults to mainnet }): Promise ``` -::: warning -It is recommended that you provide your own LCD endpoint, although we do provide a default mainnet option. Performance of the default endpoint is not guaranteed. -::: **output** diff --git a/docs/what-is-shadejs.md b/docs/what-is-shadejs.md new file mode 100644 index 0000000..9cd3250 --- /dev/null +++ b/docs/what-is-shadejs.md @@ -0,0 +1,6 @@ +# What is ShadeJS? + +ShadeJS is a typescript SDK for interacting with Shade Protocol and Secret Network smart contracts. It is designed as a wrapper for Secret.js and abstracts the complexity of secret client management (for queries), as well as providing simple-to-use typescript interfaces for the inputs and outputs of contracts. In addition, it implements multi-query optimizations in order to obtain large on-chain data sets in a highly efficient manner. + +## Out of Scope +In its current state, ShadeJS does NOT include services to execute contracts via a Secret Signing Client. This is becuase signing transactions requires a complex integration with multiple types of wallets. However, ShadeJS DOES include message creator functions for executions that can be easily imported into your project, so that you can call them from your own signing client manager. \ No newline at end of file