Skip to content

Commit

Permalink
improve docs and home
Browse files Browse the repository at this point in the history
  • Loading branch information
@riccardobl
riccardobl committed Jan 2, 2024
1 parent f9231ac commit 6d98dbb
Show file tree
Hide file tree
Showing 4 changed files with 73 additions and 55 deletions.
79 changes: 52 additions & 27 deletions API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,22 +7,24 @@
Returns an instance of LiquidWallet.

```javascript
/**
* Return an instance of LiquidWallet
* @returns {Promise<LiquidWallet>} the wallet instance
*/
window.liquid.wallet(): Promise<LiquidWallet>
```

### getWallet (Deprecated)

Returns an instance of LiquidWallet.

```javascript
window.liquid.getWallet(): Promise<LiquidWallet>
```

### 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}>
```

Expand All @@ -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<string>} The txid of the transaction
*/
window.liquid.send(amount: number, assetHash: string, toAddress: string, fee: number): Promise<string>
```

Expand All @@ -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}>
```

Expand All @@ -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<boolean>
```

### getNetworkName (Deprecated)

Returns the network name (e.g., "liquid", "testnet").

```javascript
window.liquid.getNetworkName(): Promise<string>
```

### 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<string>} the network name
*/
window.liquid.networkName(): Promise<string>
```

### 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<string>} the asset hash
*/
window.liquid.BTC(): Promise<string>
```

Expand All @@ -95,6 +106,11 @@ window.liquid.BTC(): Promise<string>
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}>
```

Expand All @@ -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<string>} the url to the icon
*/
window.liquid.assetIcon(assetHash: string): Promise<string>
```

## Examples

Examples are available at [CodePen](https://codepen.io/collection/aMPjgB).
12 changes: 7 additions & 5 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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
<script src="liquidwallet.lib.js" crossorigin></script>
<script src="https://cdn.jsdelivr.net/gh/riccardobl/anser-liquid@releases/{VERSION}/liquidwallet.lib.js"></script>
```

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

Expand Down Expand Up @@ -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
Expand Down
26 changes: 9 additions & 17 deletions src/assets/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -300,7 +300,8 @@ <h2>For developers</h2>
<p>
Explore the
<a href="https://github.com/riccardobl/anser-liquid/blob/master/README.md">documentation</a>
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).
</p>
<br />

Expand All @@ -322,11 +323,7 @@ <h2>For developers</h2>
padding: 1em;
"
>
<span
>See the Pen <a href="https://codepen.io/riccardobl/pen/VwRvpor"> Anser Send</a> by
Riccardo Balbo (<a href="https://codepen.io/riccardobl">@riccardobl</a>) on
<a href="https://codepen.io">CodePen</a>.</span
>
<span>See the Pen <a href="https://codepen.io/riccardobl/pen/VwRvpor"> Anser Send</a> </span>
</p>
<script async src="https://cpwebassets.codepen.io/assets/embed/ei.js"></script>

Expand All @@ -348,11 +345,7 @@ <h2>For developers</h2>
padding: 1em;
"
>
<span
>See the Pen <a href="https://codepen.io/riccardobl/pen/ZEPbKYb"> Anser Send</a> by
Riccardo Balbo (<a href="https://codepen.io/riccardobl">@riccardobl</a>) on
<a href="https://codepen.io">CodePen</a>.</span
>
<span>See the Pen <a href="https://codepen.io/riccardobl/pen/ZEPbKYb"> Anser Send</a></span>
</p>
<script async src="https://cpwebassets.codepen.io/assets/embed/ei.js"></script>

Expand All @@ -374,11 +367,7 @@ <h2>For developers</h2>
padding: 1em;
"
>
<span
>See the Pen <a href="https://codepen.io/riccardobl/pen/XWGmRJK"> Anser Show</a> by
Riccardo Balbo (<a href="https://codepen.io/riccardobl">@riccardobl</a>) on
<a href="https://codepen.io">CodePen</a>.</span
>
<span>See the Pen <a href="https://codepen.io/riccardobl/pen/XWGmRJK"> Anser Show</a></span>
</p>
<script async src="https://cpwebassets.codepen.io/assets/embed/ei.js"></script>
<h2>FAQ</h2>
Expand Down Expand Up @@ -433,7 +422,10 @@ <h3>Q: Can I self-host Anser?</h3>
><i class="fa-solid fa-bug"></i> Report an Issue</a
>
|
<a href="https://github.com/riccardobl"><i class="fa-brands fa-github"></i> Follow on Github</a> |
<a href="https://github.com/riccardobl/anser-liquid"
><i class="fa-brands fa-github"></i> Follow on Github</a
>
|
<a href="https://github.com/sponsors/riccardobl"
><i class="fa-solid fa-circle-dollar-to-slot"></i> Sponsor</a
>
Expand Down
11 changes: 5 additions & 6 deletions src/js/LiquidWallet.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1483,7 +1483,7 @@ if (window) {

/**
* Return an instance of LiquidWallet
* @returns {Promise<LiquidWallet>}
* @returns {Promise<LiquidWallet>} the wallet instance
*/
window.liquid.wallet = async () => {
if (!lq.started) await lq.start();
Expand All @@ -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();
Expand Down Expand Up @@ -1565,7 +1564,7 @@ if (window) {

/**
* Returns the network name (eg. "liquid", "testnet"...)
* @returns {string}
* @returns {Promise<string>} the network name
*/
window.liquid.networkName = async () => {
if (!lq.started) await lq.start();
Expand All @@ -1574,7 +1573,7 @@ if (window) {

/**
* Returns the hash for L-BTC
* @returns string
* @returns {Promise<string>} the asset hash
*/
window.liquid.BTC = async () => {
if (!lq.started) await lq.start();
Expand All @@ -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<string>} the url to the icon
*/
window.liquid.assetIcon = async (assetHash) => {
if (!lq.started) await lq.start();
Expand Down

0 comments on commit 6d98dbb

Please sign in to comment.