Merge branch 'main' into tarik-fa-script

.github/workflows/pr.yml

@@ -16,10 +16,10 @@ jobs:
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
       - name: Checkout files
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Node v16
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: '16.13'
 
@@ -47,10 +47,10 @@ jobs:
 
     steps:
       - name: Checkout files
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Node v16
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: '16.13'
 
@@ -78,10 +78,10 @@ jobs:
 
     steps:
       - name: Checkout files
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Node v16
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: '16.13'
 

.prettierrc.js

@@ -1 +1,6 @@
-module.exports = require('@substrate/dev/config/prettier');
+const config = require('@substrate/dev/config/prettier');
+
+module.exports = {
+    ...config,
+    printWidth: 120,
+}

.yarnrc.yml

@@ -1,3 +1,3 @@
 nodeLinker: node-modules
 
-yarnPath: .yarn/releases/yarn-3.6.2.cjs
+yarnPath: .yarn/releases/yarn-3.6.4.cjs

CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## [0.1.2](https://github.com/paritytech/asset-transfer-api/compare/v0.1.1..v0.1.2)(2023-09-26)
+
+## Fix
+
+- fix: rococo initialization in the registry ([#297](https://github.com/paritytech/asset-transfer-api/pull/297))
+
+NOTE: 
+
+In order to use rococo's asset hub with the `AssetTransferApi` one will need to hardcode the `specName` into the initialization like the following:
+
+```typescript
+new AssetTransferApi(api, `asset-hub-rococo`, xcmVersion);
+```
+
+The reason being, kusama's asset hub and and rococo's asset-hub both share the same specName currently and will cause conflicts. We currently do an overewrite in the registry that the api uses and set the `specName` for rococo's asset hub to be `asset-hub-rococo`. This is on the horizon to get solved on the actual chain itself soon, so this wont be necessary in the coming future. 
+
+## Docs
+
+- docs: Fixed typos ([#296](https://github.com/paritytech/asset-transfer-api/pull/296))
+
+## [0.1.1](https://github.com/paritytech/asset-transfer-api/compare/v0.1.0..v0.1.1)(2023-09-25)
+
+## Features
+
+- feat: add rococo support and to the registry ([#293](https://github.com/paritytech/asset-transfer-api/pull/293))
+
+## Fix
+
+- fix(internal): remove getChainIdBySpecName and add caching system ([#288](https://github.com/paritytech/asset-transfer-api/pull/288))
+- fix(internal): remove all use of MultiLocation, and use correct versioned type. ([#292](https://github.com/paritytech/asset-transfer-api/pull/292))
+- fix: update the registry to the new xcAssets format ([#284](https://github.com/paritytech/asset-transfer-api/pull/284))
+
+## Docs
+
+- docs: Improve README.md ([#291](https://github.com/paritytech/asset-transfer-api/pull/291))
+
+## [0.1.0](https://github.com/paritytech/asset-transfer-api/compare/v0.1.0-beta.5..v0.1.0)(2023-09-19)
+
+## Summary
+
+This release assumes the following is stable, and tested. The api is still not fully featured as we don't have support for certain things which will be listed below. Please review the documentation in the [README.md](https://github.com/paritytech/asset-transfer-api/blob/main/README.md) for any information, and feel free to file an issue if anything is unclear. 
+
+What is not supported:
+
+- ParaToPara
+- ParaToRelay
+- NFTs
+
+What is supported:
+
+- SystemToPara (native assets, foreign assets, liquid pool assets, CrossChain Transfers)
+- SystemToRelay (Native relay token, CrossChain Transfers)
+- RelayToParachain (Native relay token, CrossChain Transfers)
+- RelayToSystem (Native relay token, CrossChain Transfers)
+- SystemToSystem (Native relay token, CrossChain Transfers)
+- ParaToSystem (Asset Hub assets, foreign assets, CrossChain Transfers via either Xtokens, or polkadotXcm pallet).
+    - NOTE: There is a performance bottleneck currently with the construction of xtokens pallet transfers. This is actively being looked into and will be resovled soon.
+- Decoding extrinsics
+- Estimating fees of extrinsics
+- Registry lookup
+
+## Breaking Change
+
+- fix!: replace AssetsTransferApi with AssetTransferApi
+
+## Docs
+
+- docs: enhance the documentation and add inline code examples
+- docs: update readme, and add use case examples
+
+## [0.1.0-beta.5](https://github.com/paritytech/asset-transfer-api/compare/v0.1.0-beta.4..v0.1.0-beta.5)(2023-09-13)
+
+## Features
+
+- feat: support construction of teleports for parachains' primary native assets to AssetHub
+- feat: add disabled options config and function
+
+## Fix
+
+- fix: adjust fetchPalletInstanceId to handle ForeignAssets pallet
+- fix: remove remaining use of parseInt
+
+## Chore
+
+- chore: bump actions/checkout from 3 to 4
+- chore(lint): change print-width for prettier to 120
+
 ## [0.1.0-beta.4](https://github.com/paritytech/asset-transfer-api/compare/v0.1.0-beta.3..v0.1.0-beta.4)(2023-08-30)
 
 ## Features

README.md

@@ -20,31 +20,29 @@
 
 ## Docs
 
-Find full documentation [here](https://paritytech.github.io/asset-transfer-api/), for quick start guide read below. All examples can be found [here](https://github.com/paritytech/asset-transfer-api/tree/main/examples/).
-
-## About
-
-WARNING: This package is in stable beta, and does not support sending assets in all directions. Read **Current Cross-chain Support** for more info.
-
-**BETA**: This package is in stable beta.
+Find the full documentation [here](https://paritytech.github.io/asset-transfer-api/), for quick start guide read below. All examples can be found [here](https://github.com/paritytech/asset-transfer-api/tree/main/examples/).
 
 **Summary**: Asset-transfer-api is a library focused on simplifying the construction of asset transfers for Substrate based chains that involves system parachains like Asset Hub (Polkadot and Kusama). It exposes a reduced set of methods which facilitates users to send transfers to other (para) chains or locally.
 
 ### Current Cross-chain Support
 
 The below chart is focusing on what directions are supported for constructing asset transfers and in what XCM version. The goal is to have everything in green checkmarks. Note that local transfers (intra-chain) are not visualized here.
 
+
 | Direction              | V2                 | V3                 |
 | ---------------------  | ------------------ | ------------------ |
 | System to Parachain    |         ✅         |      ✅            |
 | System to Relay        |         ✅         |      ✅            |
 | Relay to Parachain     |         ✅         |      ✅            |
 | Relay to System        |         ✅         |      ✅            |
-| Parachain to Parachain |         ❌         |      ❌            |
+| Parachain to Parachain |         ✅         |      ✅            |
 | Parachain to Relay     |         ❌         |      ❌            |
 | Parachain to System    |         ✅         |      ✅            |
 | System to System       |         ✅         |      ✅            |
 
+## Note on Parachain to Parachain Support
+Parachain To Parachain support is currently limited to XCM V2, with the exception of Parachain primary asset tx construction (e.g. MOVR, SDN, etc.).
+
 Note: System refers to System Parachains like Asset Hub.
 
 ## Usage
@@ -59,16 +57,19 @@ 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';
+import { AssetTransferApi, constructApiPromise } from '@substrate/asset-transfer-api';
 
 // NOTE: This should all be wrapped in an asynchronous layer.
 
 // This constructs a polkadot-js ApiPromise, it is totally viable for one to construct their
-// own ApiPromise, and pass it into AssetsTransferApi, but keep in mind the `specName`, and `safeXcmVersion` are also necessary.
+// own ApiPromise, and pass it into AssetTransferApi, but keep in mind the `specName`, and `safeXcmVersion` are also necessary.
 const { api, specName, safeXcmVersion } = await constructApiPromise('wss://westmint-rpc.polkadot.io');
 
-const assetsApi = new AssetsTransferApi(api, specName, safeXcmVersion);
+const assetsApi = new AssetTransferApi(api, specName, safeXcmVersion);
 
 const call = assetsApi.createTransferTransaction(
   '2001', // destChainId (If the destination is a relay chain put `0`)
@@ -83,10 +84,10 @@ const call = assetsApi.createTransferTransaction(
 )
 ```
 
-### AssetTransferApi & AssetsTransferApiOpts & TransferArgsOpts
+### AssetTransferApi & AssetTransferApiOpts & TransferArgsOpts
 
 ```Typescript
-// The AssetsTransferApi exposes one method as of now called: `createTransferTransaction`
+// The AssetTransferApi exposes one method as of now called: `createTransferTransaction`
 
 /**
  * Create an XCM transaction to transfer Assets, or native tokens from one
@@ -98,7 +99,7 @@ const call = assetsApi.createTransferTransaction(
  * @param amounts Array of the amounts of each token to transfer
  * @param opts Options
  */
-AssetsTransferApi.createTransferTransaction(
+AssetTransferApi.createTransferTransaction(
   	destChainId: string,
 	destAddr: string,
 	assetIds: string[],
@@ -109,9 +110,9 @@ AssetsTransferApi.createTransferTransaction(
 
 
 ```typescript
-// AssetsTransferApiOpts are the options for the `AssetsTransferApi`
+// AssetTransferApiOpts are the options for the `AssetTransferApi`
 
-type AssetsTransferApiOpts = {
+type AssetTransferApiOpts = {
 	/**
 	 * The injectedRegistry allows you to add custom values to the predefined initialized registry.
 	 * If you would like to see the registry you may visit https://github.com/paritytech/asset-transfer-api-registry/blob/main/registry.json
@@ -183,9 +184,77 @@ interface TransferArgsOpts<T extends Format> {
 }
 ```
 
-#### **Local Transactions**
+### Teleport and Reserve Transfer via polkadotXcm pallet
+
+The `AssetTransferApi.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 don't. This process is done through a registry which is maintained in a separate repo [here](https://github.com/paritytech/asset-transfer-api-registry). If the asset is 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 to inject information into the registry, you can using the `injectedRegistry` option for the `AssetTransferApi`.
+
+### 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 applicable 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,
+	}
+);
+```
+
+If you would like to run an example to understand the output, run: `yarn build:examples && node ./examples/build/examples/paraToSystemTransferMultiAsset.js`
+
+### 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 cross-chain 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.
+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`, `Rococo AssetHub` ([note](https://github.com/paritytech/asset-transfer-api/pull/297#issue-1913578303) on how to use it) and as a side effect 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.
 
 An example would look like:
 ```typescript
@@ -201,33 +270,33 @@ api.createTransferTransaction(
 )
 ```
 
-The api can also send native tokens as well. Similar to the above you would replace the `assetIds` with `['DOT']`, in addition to that you may provide an empty array to denote you want to send the chains native token. 
+The api can also send native tokens as well. Similar to the above you would replace the `assetIds` with `['DOT']`. In addition to that, you may provide an empty array to denote you want to send the chain's native token.
 
-The api can also send local transactions for Relay chains. Its the same principal as above, the only difference being that the `destChainId` woule need to be `'0'`.
+The api can also send local transactions for Relay chains. It is the same principal as above, the only difference being that the `destChainId` would need to be `'0'`.
 
 For more information, refer to the [docs](https://github.com/paritytech/asset-transfer-api/tree/main/docs) in the repository.
 
 ## License
 
-The source code in this repository is distributed under the Apache 2.0 license. See the <LICENSE> file. This source code comes with absolutely no warranty. Use at your own risk.
+The source code in this repository is distributed under the Apache 2.0 license. See the [LICENSE](https://github.com/paritytech/asset-transfer-api/blob/main/LICENSE) file. This source code comes with absolutely no warranty. Use at your own risk.
 
 ## Zombienet Testing
 
 Zombienet is used to launch a complete network including a relay chain, and two parachains. It will create HRMP channels betweens the launched parachains allowing the testing enviornment to send XCM messages and transfer assets. 
 
 ### **Requirements**:
 
-**Zombienet Binary**: You can download the appropriate binary from the zombienet repositor [here](https://github.com/paritytech/zombienet/releases). Ensure that it is in the root of this directory. Note: For macos users if permission is denied to run the binary you can `chmod 755 <file_name>` to allow permissions.
+**Zombienet Binary**: You can download the appropriate binary from the zombienet repository [here](https://github.com/paritytech/zombienet/releases). Ensure that it is in the root of this directory. Note: For macos users if permission is denied to run the binary you can `chmod 755 <file_name>` to allow permissions.
 
 **Test Network Binaries**: You will need the following binaries depending on whether you want to run a small or medium network:
 
-- polkadot: You can find the the releases [here](https://github.com/paritytech/polkadot/releases). (Needed for small, or medium network)
+- polkadot: You can find the releases [here](https://github.com/paritytech/polkadot-sdk/releases). (Needed for small, or medium network)
 - trappist-collator: This binary is compiled along with polkadot above. You can find it [here](https://github.com/paritytech/trappist). (Needed for medium network)
-- polkadot-parachain (ie: cumulus): You can find the releases [here](https://github.com/paritytech/cumulus/releases). (Needed for small, or medium network)
+- polkadot-parachain (ie: cumulus): You can find the releases [here](https://github.com/paritytech/polkadot-sdk/releases). (Needed for small, or medium network)
 
 NOTES: 
 
-- When it comes to picking a version for both `cumulus` and and `polkadot` ensure they are the same. Cumulus will have an extra 0 at the end though. Ex: v0.9.37 (polkadot) -> v0.9.370 (cumulus)
+- When it comes to picking a version for both `cumulus` and `polkadot` ensure they are the same. Cumulus will have an extra 0 at the end though. Ex: v0.9.37 (polkadot) -> v0.9.370 (cumulus)
 
 - You can retrieve the binaries via the release, or by compiling yourself. It's recommended to compile it yourself.
 

bin/README.MD

@@ -1 +1 @@
-This directory should contian all binaries for running zombienet.
+This directory should contain all the binaries for running zombienet.