docs: update readme, and add use case examples

README.md

@@ -59,6 +59,9 @@ Note: System refers to System Parachains like Asset Hub.
 
 ### Example Usage
 
+**NOTE:** For more practical usage, and specified examples please look through our `./examples` directory to see more use cases. To
+run these examples: `yarn build:examples && node ./examples/build/examples/<file_to_run>.js`.
+
 ```typescript
 import { AssetsTransferApi, constructApiPromise } from '@substrate/asset-transfer-api';
 
@@ -183,6 +186,72 @@ interface TransferArgsOpts<T extends Format> {
 }
 ```
 
+### Teleport and Reserve Transfer via polkadotXcm pallet
+
+The `AssetsTransferApi.createTransferTransaction` is able to infer what kind of transaction is necessary given the inputs. When sending cross chain transfers the api does a lot of validation to ensure the inputs are valid, and the assets either exist or dont. This process is done through a registry which is maintained in a seperate repo [here](https://github.com/paritytech/asset-transfer-api-registry). If the asset in not in the registry it will then lookup if that asset exists on chain and cache it if necessary. On chain verification is not always possible in respect to the direction the asset is being sent and what the destination chain is since we only maintain one api connection. Therefore, if you would like the inject information into the registry, you can using the `injectedRegistry` option for the `AssetsTransferApi`.
+
+### Transferring assets via xTokens pallet
+
+If the transfer is being sent from a parachain that utilizes the `xTokens` pallet, the API will detect that and construct the transaction that is necessary. It will construct one of three calls: `transferMultiAsset`, `transferMultiAssets`, or `transferMultiAssetWithFee`. This is only application when the intended transfer direction starts from a parachain. The xTokens pallet can be found [here](https://github.com/open-web3-stack/open-runtime-module-library/tree/master/xtokens).
+
+An example would look like:
+```typescript
+api.createTransferTransaction(
+	'1000',
+	'0xc4db7bcb733e117c0b34ac96354b10d47e84a006b9e7e66a229d174e8ff2a063',
+	['xcUSDT'],
+	['1000000'],
+	{
+		format: 'call',
+		isLimited: false,
+		xcmVersion: 2,
+	}
+);
+```
+
+### Foreign Asset Transfers
+
+Sending a foreign asset requires the input `assetIds` in `createTransferTransaction` to include the `multiLocation` of the asset you would like to send. If a multilocation is not passed it will not know if the asset you are sending is a foreign asset. If the `multiLocation` passed in has a `Parachain` id which matches the `destChainId` input for the transfer then the output will be a teleport, otherwise it will be a reserve backed transfer.
+
+An example would look like:
+```typescript
+api.createTransferTransaction(
+	'2125', // Note: the Parchain ID matches the MultiLocations 'Parachain' ID, making this a teleport of assets
+	'5EWNeodpcQ6iYibJ3jmWVe85nsok1EDG8Kk3aFg8ZzpfY1qX',
+	['{"parents":"1","interior":{"X2":[{"Parachain":"2125"},{"GeneralIndex":"0"}]}}'],
+	['1000000000000'],
+	{
+		format: 'call',
+		isLimited: true,
+		xcmVersion: 3,
+	}
+)
+```
+
+If you would like to run an example to understand the output run: `yarn build:examples && node ./examples/build/examples/systemToParaTeleportForeignAssets.js`
+
+### Liquid Pool Asset Transfers
+
+Sending a liquidity token (from the poolAssets pallet) in Asset Hub is as simple as setting the option `transferLiquidToken` to true. That being said, it does have some nuances. A liquidity token transfer must be in the direction of a SystemToPara, and the inputted asset must be a valid integer as a string. The api will error if either of these conditions are not met.
+
+An example would look like:
+```typescript
+api.createTransferTransaction(
+	'2023',
+	'0xF977814e90dA44bFA03b6295A0616a897441aceC',
+	['0'],
+	['100000'],
+	{
+		format: 'call',
+		isLimited: true,
+		xcmVersion: 2,
+		transferLiquidToken: true,
+	}
+);
+```
+
+If you would like to run an example to understand the output run: `yarn build:examples && node ./examples/build/examples/systemToParaLpToken.js`
+
 #### **Local Transactions**
 
 Sending an Asset or Native token locally on a System Parachain is easy. In order to create a transaction, ensure the `destChainId` is the same as the ID of the System Parachain itself. Note, the only System parachains that are supported are `Kusama AssetHub`, `Polkadot AssetHub`, `Westend AssetHub` and as a side affect the only `destChainId` that is supported is `1000`. In addition to that, ensure the length of the `assetId's` array and `amounts` array are 1. As sending assets will only accept one asset at a time. Keep in mind `transfer`, and `transferKeepAlive` are the only supported calls.

docs/classes/AssetsTransferApi.html

@@ -25,7 +25,7 @@ <h4>Hierarchy</h4>
 <ul class="tsd-hierarchy">
 <li><span class="target">AssetsTransferApi</span></li></ul></section><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/AssetsTransferApi.ts#L68">AssetsTransferApi.ts:68</a></li></ul></aside>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/AssetsTransferApi.ts#L68">AssetsTransferApi.ts:68</a></li></ul></aside>
 <section class="tsd-panel-group tsd-index-group">
 <section class="tsd-panel tsd-index-panel">
 <details class="tsd-index-content tsd-index-accordion" open><summary class="tsd-accordion-summary tsd-index-summary">
@@ -83,7 +83,7 @@ <h5><span class="tsd-kind-parameter">opts</span>: <a href="../interfaces/Transfe
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type ">Promise</span><span class="tsd-signature-symbol">&lt;</span><a href="../interfaces/TxResult.html" class="tsd-signature-type tsd-kind-interface">TxResult</a><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type tsd-kind-type-parameter">T</span><span class="tsd-signature-symbol">&gt;</span><span class="tsd-signature-symbol">&gt;</span></h4>
 <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/AssetsTransferApi.ts#L93">AssetsTransferApi.ts:93</a></li></ul></aside></li></ul></section>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/AssetsTransferApi.ts#L93">AssetsTransferApi.ts:93</a></li></ul></aside></li></ul></section>
 <section class="tsd-panel tsd-member"><a id="decodeExtrinsic" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>decode<wbr/>Extrinsic</span><a href="#decodeExtrinsic" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <ul class="tsd-signatures">
@@ -112,7 +112,7 @@ <h5><span class="tsd-kind-parameter">format</span>: <span class="tsd-signature-t
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">string</span></h4>
 <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/AssetsTransferApi.ts#L709">AssetsTransferApi.ts:709</a></li></ul></aside></li></ul></section>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/AssetsTransferApi.ts#L709">AssetsTransferApi.ts:709</a></li></ul></aside></li></ul></section>
 <section class="tsd-panel tsd-member"><a id="fetchFeeInfo" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>fetch<wbr/>Fee<wbr/>Info</span><a href="#fetchFeeInfo" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <ul class="tsd-signatures">
@@ -141,7 +141,7 @@ <h5><span class="tsd-kind-parameter">format</span>: <span class="tsd-signature-t
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type ">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">null</span><span class="tsd-signature-symbol"> | </span><span class="tsd-signature-type ">RuntimeDispatchInfo</span><span class="tsd-signature-symbol"> | </span><span class="tsd-signature-type ">RuntimeDispatchInfoV1</span><span class="tsd-signature-symbol">&gt;</span></h4>
 <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/AssetsTransferApi.ts#L424">AssetsTransferApi.ts:424</a></li></ul></aside></li></ul></section></section></div>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/AssetsTransferApi.ts#L424">AssetsTransferApi.ts:424</a></li></ul></aside></li></ul></section></section></div>
 <div class="col-sidebar">
 <div class="page-menu">
 <div class="tsd-navigation settings">

docs/enums/Direction.html

@@ -20,7 +20,7 @@ <h1>Enumeration Direction</h1></div>
 </div>
 <div class="tsd-comment tsd-typography"></div></section><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/types.ts#L25">types.ts:25</a></li></ul></aside>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/types.ts#L25">types.ts:25</a></li></ul></aside>
 <section class="tsd-panel-group tsd-index-group">
 <section class="tsd-panel tsd-index-panel">
 <details class="tsd-index-content tsd-index-accordion" open><summary class="tsd-accordion-summary tsd-index-summary">
@@ -46,63 +46,63 @@ <h3 class="tsd-anchor-link"><span>Para<wbr/>To<wbr/>Para</span><a href="#ParaToP
 </div>
 <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/types.ts#L41">types.ts:41</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/types.ts#L41">types.ts:41</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member"><a id="ParaToRelay" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>Para<wbr/>To<wbr/>Relay</span><a href="#ParaToRelay" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <div class="tsd-signature"><span class="tsd-kind-enum-member">Para<wbr/>To<wbr/>Relay</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">&quot;ParaToRelay&quot;</span></div>
 <div class="tsd-comment tsd-typography"><p>Parachain to Relay chain.</p>
 </div>
 <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/types.ts#L45">types.ts:45</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/types.ts#L45">types.ts:45</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member"><a id="ParaToSystem" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>Para<wbr/>To<wbr/>System</span><a href="#ParaToSystem" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <div class="tsd-signature"><span class="tsd-kind-enum-member">Para<wbr/>To<wbr/>System</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">&quot;ParaToSystem&quot;</span></div>
 <div class="tsd-comment tsd-typography"><p>Parachain to System parachain.</p>
 </div>
 <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/types.ts#L49">types.ts:49</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/types.ts#L49">types.ts:49</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member"><a id="RelayToPara" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>Relay<wbr/>To<wbr/>Para</span><a href="#RelayToPara" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <div class="tsd-signature"><span class="tsd-kind-enum-member">Relay<wbr/>To<wbr/>Para</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">&quot;RelayToPara&quot;</span></div>
 <div class="tsd-comment tsd-typography"><p>Relay chain to Parachain.</p>
 </div>
 <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/types.ts#L57">types.ts:57</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/types.ts#L57">types.ts:57</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member"><a id="RelayToSystem" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>Relay<wbr/>To<wbr/>System</span><a href="#RelayToSystem" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <div class="tsd-signature"><span class="tsd-kind-enum-member">Relay<wbr/>To<wbr/>System</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">&quot;RelayToSystem&quot;</span></div>
 <div class="tsd-comment tsd-typography"><p>Relay to System Parachain.</p>
 </div>
 <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/types.ts#L53">types.ts:53</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/types.ts#L53">types.ts:53</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member"><a id="SystemToPara" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>System<wbr/>To<wbr/>Para</span><a href="#SystemToPara" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <div class="tsd-signature"><span class="tsd-kind-enum-member">System<wbr/>To<wbr/>Para</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">&quot;SystemToPara&quot;</span></div>
 <div class="tsd-comment tsd-typography"><p>System parachain to Parachain.</p>
 </div>
 <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/types.ts#L29">types.ts:29</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/types.ts#L29">types.ts:29</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member"><a id="SystemToRelay" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>System<wbr/>To<wbr/>Relay</span><a href="#SystemToRelay" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <div class="tsd-signature"><span class="tsd-kind-enum-member">System<wbr/>To<wbr/>Relay</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">&quot;SystemToRelay&quot;</span></div>
 <div class="tsd-comment tsd-typography"><p>System parachain to Relay chain.</p>
 </div>
 <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/types.ts#L33">types.ts:33</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/types.ts#L33">types.ts:33</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member"><a id="SystemToSystem" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>System<wbr/>To<wbr/>System</span><a href="#SystemToSystem" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="#icon-anchor"></use></svg></a></h3>
 <div class="tsd-signature"><span class="tsd-kind-enum-member">System<wbr/>To<wbr/>System</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">&quot;SystemToSystem&quot;</span></div>
 <div class="tsd-comment tsd-typography"><p>System parachain to System parachain chain.</p>
 </div>
 <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/types.ts#L37">types.ts:37</a></li></ul></aside></section></section></div>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/types.ts#L37">types.ts:37</a></li></ul></aside></section></section></div>
 <div class="col-sidebar">
 <div class="page-menu">
 <div class="tsd-navigation settings">

docs/functions/constructApiPromise.html

@@ -37,7 +37,7 @@ <h5><span class="tsd-kind-parameter">opts</span>: <span class="tsd-signature-typ
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type ">Promise</span><span class="tsd-signature-symbol">&lt;</span><a href="../interfaces/ApiInfo.html" class="tsd-signature-type tsd-kind-interface">ApiInfo</a><span class="tsd-signature-symbol">&gt;</span></h4>
 <div class="tsd-comment tsd-typography"></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/d59ab83/src/constructApiPromise.ts#L24">constructApiPromise.ts:24</a></li></ul></aside></li></ul></section></div>
+<li>Defined in <a href="https://github.com/paritytech/asset-transfer-api/blob/aac9e28/src/constructApiPromise.ts#L24">constructApiPromise.ts:24</a></li></ul></aside></li></ul></section></div>
 <div class="col-sidebar">
 <div class="page-menu">
 <div class="tsd-navigation settings">