From 6d98dbbd7d43845e102d7c58ab9a989a835c17c8 Mon Sep 17 00:00:00 2001 From: Riccardo Balbo Date: Tue, 2 Jan 2024 12:42:45 +0100 Subject: [PATCH] improve docs and home --- API.md | 79 +++++++++++++++++++++++++++--------------- README.md | 12 ++++--- src/assets/index.html | 26 +++++--------- src/js/LiquidWallet.js | 11 +++--- 4 files changed, 73 insertions(+), 55 deletions(-) diff --git a/API.md b/API.md index 8197d55..63a5ba2 100644 --- a/API.md +++ b/API.md @@ -7,22 +7,24 @@ Returns an instance of LiquidWallet. ```javascript +/** +* Return an instance of LiquidWallet +* @returns {Promise} the wallet instance +*/ window.liquid.wallet(): Promise ``` -### getWallet (Deprecated) - -Returns an instance of LiquidWallet. - -```javascript -window.liquid.getWallet(): Promise -``` - ### receive Generates a payment URL and QR code to receive a payment. ```javascript +/** +* Generate a payment url and QR code to receive a payment +* @param {number} amount Hint the amount to receive as floating point number (eg. 0.001) 0 = any (N.B. this is just a hint, the sender can send any amount) +* @param {string} assetHash Asset hash of the asset to receive (NB. this is just a hint, the sender can send any asset). Leave empty for any asset or L-BTC. +* @returns {Promise<{url: string, qr: string}>} A promise that resolves to an object with a payment url and a qr code image url +*/ window.liquid.receive(amount: number, assetHash: string, qrOptions: any): Promise<{url: string, qr: string}> ``` @@ -31,6 +33,14 @@ window.liquid.receive(amount: number, assetHash: string, qrOptions: any): Promis Sends an amount to an address. ```javascript +/** +* Send an amount to an address +* @param {number} amount The amount to send as floating point number (eg. 0.001) +* @param {string} assetHash Asset hash of the asset to send. +* @param {string} toAddress The address to send to +* @param {number} fee The fee in sats per vbyte to use. 0 or empty = auto +* @returns {Promise} The txid of the transaction +*/ window.liquid.send(amount: number, assetHash: string, toAddress: string, fee: number): Promise ``` @@ -39,6 +49,11 @@ window.liquid.send(amount: number, assetHash: string, toAddress: string, fee: nu Estimates the fee for a transaction. ```javascript +/** +* Estimate the fee for a transaction +* @param {number} priority 0 = low, 1 = high +* @returns {Promise<{feeRate: string, blocks: number}>} The fee in sats per vbyte to pay and the number of blocks that will take to confirm +*/ window.liquid.estimateFee(priority: number): Promise<{feeRate: string, blocks: number}> ``` @@ -47,46 +62,42 @@ window.liquid.estimateFee(priority: number): Promise<{feeRate: string, blocks: n Gets the balance of each owned asset. ```javascript +/** +* Get the balance of each owned asset +* @returns {Promise<[{asset: string, value: number}]>} An array of objects with asset and value +*/ window.liquid.balance(): Promise<[{asset: string, value: number}]> ``` ### isAnser -Checks if Anser is loaded. +A boolean that is true if Anser is loaded. ```javascript window.liquid.isAnser: boolean ``` -### isAnser (Deprecated) - -Checks if Anser is loaded. - -```javascript -window.liquid.isAnser(): Promise -``` - -### getNetworkName (Deprecated) - -Returns the network name (e.g., "liquid", "testnet"). - -```javascript -window.liquid.getNetworkName(): Promise -``` - ### networkName -Returns the network name (e.g., "liquid", "testnet"). +Returns a string representing the network name (e.g., "liquid", "testnet"). ```javascript +/** +* Returns the network name (eg. "liquid", "testnet"...) +* @returns {Promise} the network name +*/ window.liquid.networkName(): Promise ``` ### BTC -Returns the hash for L-BTC. +Returns a string representing the hash for L-BTC. ```javascript +/** +* Returns the hash for L-BTC +* @returns {Promise} the asset hash +*/ window.liquid.BTC(): Promise ``` @@ -95,6 +106,11 @@ window.liquid.BTC(): Promise Returns info for the given asset. ```javascript +/** +* Returns info for the given asset +* @param {string} assetHash asset hash +* @returns {Promise<{name: string, ticker: string, precision: number, hash:string}>} The info for this asset +*/ window.liquid.assetInfo(assetHash: string): Promise<{name: string, ticker: string, precision: number, hash:string}> ``` @@ -103,5 +119,14 @@ window.liquid.assetInfo(assetHash: string): Promise<{name: string, ticker: strin Gets the icon for the given asset. ```javascript +/** +* Get the icon for the given asset +* @param {string} assetHash the asset +* @returns {Promise} the url to the icon +*/ window.liquid.assetIcon(assetHash: string): Promise ``` + +## Examples + +Examples are available at [CodePen](https://codepen.io/collection/aMPjgB). diff --git a/README.md b/README.md index 5d3f52e..b5109dc 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Anser: A liquid companion for Alby -![anser](src/assets/screenshot/2.webp) +[![anser](src/assets/screenshot/2.webp)](https://anserliquid.frk.wf) Anser is a client-side web app that uses the [Alby extension](https://getalby.com/)'s liquid integration to provide a simple interface to the Liquid Network. @@ -48,18 +48,20 @@ ghcr.io/riccardobl/anser-liquid:v1.0 ## Using Anser Library in your website -The main way to use Anser Library is to include the [LiquidWallet.js](src/js/LiquidWallet.js) script as a module and instantiate a LiquidWallet object. +One way to use Anser Library is to include the [LiquidWallet.js](src/js/LiquidWallet.js) script as a module and instantiate a LiquidWallet object. However to make things even easier, there is an additional set of simplified APIs that is automatically exported in window.liquid namespace when the script is included as a normal script tag. ```html - + ``` +N.B. Replace {VERSION} with the latest version from the [Release Page](https://github.com/riccardobl/anser-liquid/releases). + The `window.liquid` API provides common functionalities in a more intuitive way. See the documentation [here](/API.md). -You can find the minified version of LiquidWallet.js that can be used both as a module and as a script tag in the [Release Page](https://github.com/riccardobl/anser-liquid/releases). +You can find the minified version of LiquidWallet.js that can be used both as a module and as a script tag in the [Release Page](https://github.com/riccardobl/anser-liquid/releases) or in [JsDelivr](https://www.jsdelivr.com/package/gh/riccardobl/anser-liquid). ## Build and run locally @@ -135,7 +137,7 @@ To enable https you can use a reverse proxy like [nginx](https://www.nginx.com/) The source code is logically divided in 2 parts: -- [src/js/LiquidWallet.js](src/js/LiquidWallet.js) is the backend that handles all the communication with the various APIs and exposes a simple interface that can be used by any app. +- [src/js/LiquidWallet.js](src/js/LiquidWallet.js) serves as the backend component, managing all interactions with various APIs. It provides a streamlined interface that can be easily integrated with any application. - [src/js/ui](src/js/ui) contains everything related to the UI of the web app. The entry point of the web app is diff --git a/src/assets/index.html b/src/assets/index.html index 0113ed2..56dea69 100644 --- a/src/assets/index.html +++ b/src/assets/index.html @@ -300,7 +300,8 @@

For developers

Explore the documentation - for comprehensive details, and experiment with the examples provided below. + for comprehensive details or experiment with the examples provided below (nb. it is advised to + run the test using testnet).


@@ -322,11 +323,7 @@

For developers

padding: 1em; " > - See the Pen Anser Send by - Riccardo Balbo (@riccardobl) on - CodePen. + See the Pen Anser Send

@@ -348,11 +345,7 @@

For developers

padding: 1em; " > - See the Pen Anser Send by - Riccardo Balbo (@riccardobl) on - CodePen. + See the Pen Anser Send

@@ -374,11 +367,7 @@

For developers

padding: 1em; " > - See the Pen Anser Show by - Riccardo Balbo (@riccardobl) on - CodePen. + See the Pen Anser Show

FAQ

@@ -433,7 +422,10 @@

Q: Can I self-host Anser?

> Report an Issue | - Follow on Github | + Follow on Github + | Sponsor diff --git a/src/js/LiquidWallet.js b/src/js/LiquidWallet.js index 21361e1..c2131a7 100644 --- a/src/js/LiquidWallet.js +++ b/src/js/LiquidWallet.js @@ -1483,7 +1483,7 @@ if (window) { /** * Return an instance of LiquidWallet - * @returns {Promise} + * @returns {Promise} the wallet instance */ window.liquid.wallet = async () => { if (!lq.started) await lq.start(); @@ -1501,8 +1501,7 @@ if (window) { * Generate a payment url and QR code to receive a payment * @param {number} amount Hint the amount to receive as floating point number (eg. 0.001) 0 = any (N.B. this is just a hint, the sender can send any amount) * @param {string} assetHash Asset hash of the asset to receive (NB. this is just a hint, the sender can send any asset). Leave empty for any asset or L-BTC. - * @returns {Promise<{url: string, qr: string}>} A promise that resolves to an object with a url and a qr string. - * @returns + * @returns {Promise<{url: string, qr: string}>} A promise that resolves to an object with a payment url and a qr code image url */ window.liquid.receive = async (amount /*float*/, assetHash, qrOptions) => { if (!lq.started) await lq.start(); @@ -1565,7 +1564,7 @@ if (window) { /** * Returns the network name (eg. "liquid", "testnet"...) - * @returns {string} + * @returns {Promise} the network name */ window.liquid.networkName = async () => { if (!lq.started) await lq.start(); @@ -1574,7 +1573,7 @@ if (window) { /** * Returns the hash for L-BTC - * @returns string + * @returns {Promise} the asset hash */ window.liquid.BTC = async () => { if (!lq.started) await lq.start(); @@ -1594,7 +1593,7 @@ if (window) { /** * Get the icon for the given asset * @param {string} assetHash the asset - * @returns {string} an url to the icon + * @returns {Promise} the url to the icon */ window.liquid.assetIcon = async (assetHash) => { if (!lq.started) await lq.start();