@moonbeam-network/xcm-sdk 1.0.0-dev.3 → 1.0.0-dev.300

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2022 PureStake
+Copyright 2024 Moonbeam Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -1,18 +1,10 @@
-![Moonbeam](https://docs.moonbeam.network/images/builders/interoperability/xcm/sdk/xcm-sdk-banner.png)
+The Moonbeam XCM SDK enables developers to easily transfer assets between chains, either between parachains or between a parachain and the relay chain, within the Polkadot/Kusama ecosystem. With the SDK, you don't need to worry about determining the multilocation of the origin or destination assets or which extrinsics are used on which networks to send XCM transfers.
 
-The Moonbeam XCM SDK enables developers to easily deposit and withdraw assets to Moonbeam/Moonriver from the relay chain and other parachains in the Polkadot/Kusama ecosystem. With the SDK, you don't need to worry about determining the multilocation of the origin or destination assets or which extrinsics are used on which networks to send XCM transfers. To deposit or withdraw assets, you simply define the asset and origin chain you want to deposit from or withdraw back to, along with the sending account's signer, and the amount to send.
+The XCM SDK offers helper functions that provide a very simple interface to execute XCM transfers between chains in the Polkadot/Kusama ecosystem. In addition, the XCM config package allows any parachain project to add their information in a standard way, so they can be immediately supported by the XCM SDK.
 
 # Documentation
 
-## v1 (current)
-
-- TODO: (coming soon)
-
-## v0 (previous)
-
-- [readme](https://github.com/PureStake/xcm-sdk/tree/v0)
-- [usage](https://docs.moonbeam.network/builders/xcm/xcm-sdk/xcm-sdk/)
-- [references](https://docs.moonbeam.network/builders/xcm/xcm-sdk/reference/)
+You can find the documentation at [https://moonbeam-foundation.github.io/xcm-sdk/latest/](https://moonbeam-foundation.github.io/xcm-sdk/latest/).
 
 # Installation
 
@@ -23,34 +15,72 @@ npm i @moonbeam-network/xcm-sdk
 :warning: You need to have peer dependencies of SDK installed as well.
 
 ```bash
-npm i @polkadot/api @polkadot/api-augment @polkadot/types @polkadot/util @polkadot/util-crypto @polkadot/apps-config ethers
+npm i @polkadot/api @polkadot/util-crypto
 ```
 
 # Usage
 
-- TODO: (coming soon) - in the meantime, see examples below
+The following sections contain basic examples of how to work with the XCM SDK to build transfer data to transfer an asset from one chain to another and how to submit the transfer. For a detailed overview on how to use it, please refer to the [XCM SDK docs](https://moonbeam-foundation.github.io/xcm-sdk/latest/example-usage/xcm).
+
+## Build XCM Transfer Data
+
+```js
+import { Sdk } from '@moonbeam-network/xcm-sdk';
+
+const fromPolkadot = async () => {
+  const transferData = await Sdk()
+    .setAsset(dot)
+    .setSource(polkadot) 
+    .setDestination(moonbeam)
+    .setAddresses({
+      sourceAddress: pair.address,
+      destinationAddress: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
+    });
+};
+
+fromPolkadot();
+```
+
+## Transfer
+
+```js
+...
+
+const hash = await data.transfer({
+  amount: 1,
+  signers: { polkadotSigner: pair }, // Insert the signer, in this case a Substrate key pair
+});
+
+```
 
 # Examples
 
-- [sdk](https://github.com/PureStake/xcm-sdk/blob/main/examples/sdk-simple)
+- [sdk](https://github.com/moonbeam-foundation/xcm-sdk/blob/main/examples/sdk-simple)
 
 ```bash
-git clone git@github.com:PureStake/xcm-sdk.git
+git clone git@github.com:moonbeam-foundation/xcm-sdk.git
 cd xcm-sdk
-npm i
+pnpm install
 cd examples/sdk-simple
 
 # edit index.ts by adding your accounts
 
-npm start
+pnpm run start
 ```
 
 # Contributing
 
+First fork the repository and clone it.
+
+```bash
+git clone git@github.com:YOUR_GITHUB_USERNAME/xcm-sdk.git
+pnpm install
+```
+
+Optionally, you can install the `pre-commit` hook to run the linter and tests before committing:
+
 ```bash
-git clone git@github.com:PureStake/xcm-sdk.git
-npm i
-npm run dev
+pnpm lefthook install
 ```
 
 # Tests
@@ -58,14 +88,49 @@ npm run dev
 ## Unit tests
 
 ```bash
-npm run test
+pnpm run test
 ```
 
 ## Acceptance tests
 
 ```bash
-cp .env.example .env
-# add private key and suri to .env file
+pnpm run test:acc
+```
+
+# Release
+
+To create a dev version go to GitHub actions and run `publish dev versions` workflow.
 
-npm run test:acc
+To create a release version run:
+
+```bash
+pnpm run changeset
+```
+
+# Testing the change in the SDK locally
+
+Build the project:
+
+```bash
+pnpm run build
+```
+
+Link the SDK:
+
+```bash
+pnpm run clean && pnpm run build && pnpm run link
+```
+
+In your project where you would like to test the changes:
+
+```bash
+pnpm link @moonbeam-network/xcm-types @moonbeam-network/xcm-utils @moonbeam-network/xcm-builder @moonbeam-network/xcm-config @moonbeam-network/xcm-sdk
+```
+
+If you need you can link other packages too.
+
+After testing is done, unlink the SDK:
+
+```bash
+pnpm unlink @moonbeam-network/xcm-types @moonbeam-network/xcm-utils @moonbeam-network/xcm-builder @moonbeam-network/xcm-config @moonbeam-network/xcm-sdk
 ```

package/build/index.d.mts

@@ -0,0 +1,236 @@
+import { AssetRoute, FeeConfig, ConfigService } from '@moonbeam-network/xcm-config';
+import * as _moonbeam_network_xcm_types from '@moonbeam-network/xcm-types';
+import { AssetAmount, AnyChain, AnyParachain, ChainAsset, EvmChain, EvmParachain, Asset, Ecosystem, AnyAsset } from '@moonbeam-network/xcm-types';
+import { Signer, SubmittableExtrinsic } from '@polkadot/api/types';
+import { IKeyringPair, ISubmittableResult } from '@polkadot/types/types';
+import { WalletClient, PublicClient, HttpTransport, StateOverride, Hash, Address } from 'viem';
+import { ContractConfig, ExtrinsicConfig, BalanceConfigBuilder, FeeConfigBuilder, AssetMinConfigBuilder, EvmQueryConfig, SubstrateQueryConfig, EventMonitoringConfig } from '@moonbeam-network/xcm-builder';
+import { ApiPromise } from '@polkadot/api';
+import { RuntimeDispatchInfo, EventRecord } from '@polkadot/types/interfaces';
+import { HexString } from '@polkadot/util/types';
+
+type EvmSigner = WalletClient;
+interface Signers {
+    evmSigner?: EvmSigner;
+    polkadotSigner?: Signer | IKeyringPair;
+}
+interface TransferData {
+    destination: DestinationChainTransferData;
+    getEstimate(amount: number | string): AssetAmount;
+    max: AssetAmount;
+    min: AssetAmount;
+    source: SourceChainTransferData;
+    transfer(params: TransferParams): Promise<string>;
+}
+interface TransferParams {
+    amount: number | string;
+    signers: Partial<Signers>;
+    statusCallback?: (status: ISubmittableResult) => void;
+    onSourceFinalized?: () => void;
+    onSourceError?: (error: Error) => void;
+    onDestinationFinalized?: () => void;
+    onDestinationError?: (error: Error) => void;
+}
+interface SourceChainTransferData extends ChainTransferData {
+    destinationFee: AssetAmount;
+    destinationFeeBalance: AssetAmount;
+    feeBalance: AssetAmount;
+    max: AssetAmount;
+}
+interface SovereignAccountBalance {
+    feeAssetBalance: bigint | undefined;
+    transferAssetBalance: bigint;
+}
+interface DestinationChainTransferData extends ChainTransferData {
+    sovereignAccountBalances?: SovereignAccountBalance;
+}
+interface ChainTransferData {
+    balance: AssetAmount;
+    chain: AnyChain;
+    existentialDeposit?: AssetAmount;
+    fee: AssetAmount;
+    min: AssetAmount;
+}
+
+interface GetDestinationDataParams {
+    route: AssetRoute;
+    destinationAddress: string;
+}
+declare function getDestinationData({ route, destinationAddress, }: GetDestinationDataParams): Promise<DestinationChainTransferData>;
+
+interface GetSourceDataParams {
+    route: AssetRoute;
+    destinationAddress: string;
+    destinationFee: AssetAmount;
+    sourceAddress: string;
+}
+declare function getSourceData({ route, destinationAddress, destinationFee, sourceAddress, }: GetSourceDataParams): Promise<SourceChainTransferData>;
+interface GetFeeParams {
+    balance: AssetAmount;
+    feeBalance: AssetAmount;
+    contract?: ContractConfig;
+    chain: AnyParachain;
+    destinationFee: AssetAmount;
+    extrinsic?: ExtrinsicConfig;
+    feeConfig?: FeeConfig;
+    sourceAddress: string;
+}
+declare function getFee({ balance, feeBalance, chain, contract, destinationFee, extrinsic, feeConfig, sourceAddress, }: GetFeeParams): Promise<AssetAmount>;
+interface GetAssetsBalancesParams {
+    address: string;
+    chain: AnyParachain;
+    routes: AssetRoute[];
+    evmSigner?: EvmSigner;
+}
+declare function getAssetsBalances({ address, chain, routes, }: GetAssetsBalancesParams): Promise<AssetAmount[]>;
+
+interface GetBalancesParams {
+    address: string;
+    asset: ChainAsset;
+    builder: BalanceConfigBuilder;
+    chain: AnyChain;
+}
+declare function getBalance({ address, asset, builder, chain, }: GetBalancesParams): Promise<AssetAmount>;
+interface GetMinParams {
+    asset: Asset;
+    builder?: AssetMinConfigBuilder;
+    chain: AnyChain;
+}
+declare function getAssetMin({ asset, builder, chain, }: GetMinParams): Promise<AssetAmount>;
+declare function getMin({ balance, existentialDeposit, fee, min, }: DestinationChainTransferData): AssetAmount;
+interface GetMaxParams {
+    balance: AssetAmount;
+    existentialDeposit?: AssetAmount;
+    fee: AssetAmount;
+    min: AssetAmount;
+}
+declare function getMax({ balance, existentialDeposit, fee, min, }: GetMaxParams): AssetAmount;
+interface GetDestinationFeeParams {
+    address: string;
+    asset: Asset;
+    feeAsset: Asset;
+    destination: AnyChain;
+    fee: number | FeeConfigBuilder;
+    source: AnyChain;
+}
+declare function getDestinationFee({ address, asset, destination, fee, feeAsset, source, }: GetDestinationFeeParams): Promise<AssetAmount>;
+interface ConvertToChainDecimalsParams {
+    asset: AssetAmount;
+    target: ChainAsset;
+}
+declare function convertToChainDecimals({ asset, target, }: ConvertToChainDecimalsParams): AssetAmount;
+declare function getExistentialDeposit(chain: AnyChain): Promise<AssetAmount | undefined>;
+interface GetDestinationFeeBalanceParams {
+    balance: AssetAmount;
+    feeBalance: AssetAmount;
+    route: AssetRoute;
+    sourceAddress: string;
+}
+declare function getDestinationFeeBalance({ balance, feeBalance, route, sourceAddress, }: GetDestinationFeeBalanceParams): Promise<AssetAmount>;
+interface GetExtrinsicFeeParams {
+    address: string;
+    balance: AssetAmount;
+    chain: AnyParachain;
+    extrinsic: ExtrinsicConfig;
+    feeBalance: AssetAmount;
+    feeConfig?: FeeConfig;
+}
+declare function getExtrinsicFee({ address, balance, chain, extrinsic, feeBalance, feeConfig, }: GetExtrinsicFeeParams): Promise<AssetAmount>;
+interface GetContractFeeParams {
+    address: string;
+    balance: AssetAmount;
+    chain: EvmChain | EvmParachain;
+    contract: ContractConfig;
+    destinationFee: AssetAmount;
+    feeBalance: AssetAmount;
+    feeConfig?: FeeConfig;
+}
+declare function getContractFee({ address, balance, chain, contract, destinationFee, feeBalance, feeConfig, }: GetContractFeeParams): Promise<AssetAmount>;
+interface ValidateSovereignAccountBalancesProps {
+    amount: bigint;
+    destinationData: DestinationChainTransferData;
+    sourceData: SourceChainTransferData;
+}
+declare function validateSovereignAccountBalances({ amount, sourceData, destinationData, }: ValidateSovereignAccountBalancesProps): void;
+
+interface SdkOptions {
+    configService?: ConfigService;
+    ecosystem?: Ecosystem;
+}
+declare function Sdk({ configService, ecosystem }?: SdkOptions): {
+    assets: _moonbeam_network_xcm_types.Asset[];
+    setAsset(asset: string | AnyAsset): {
+        sources: AnyChain[];
+        setSource(source: string | AnyChain): {
+            destinations: AnyChain[];
+            setDestination(destination: string | AnyChain): {
+                setAddresses({ sourceAddress, destinationAddress, }: {
+                    sourceAddress: string;
+                    destinationAddress: string;
+                }): Promise<TransferData>;
+            };
+        };
+    };
+};
+declare function getParachainBalances(chain: AnyParachain, address: string, service?: ConfigService): Promise<AssetAmount[]>;
+
+declare class EvmService {
+    readonly chain: EvmChain | EvmParachain;
+    readonly client: PublicClient<HttpTransport>;
+    static create(chain: EvmChain | EvmParachain): EvmService;
+    constructor(chain: EvmChain | EvmParachain);
+    query(query: EvmQueryConfig): Promise<bigint>;
+    read(config: ContractConfig): Promise<unknown>;
+    getFee(address: string, contract: ContractConfig, stateOverride?: StateOverride): Promise<bigint>;
+    getBalance(address: string, contract: ContractConfig): Promise<bigint>;
+    transfer(signer: EvmSigner, contract: ContractConfig): Promise<Hash>;
+}
+
+declare class PolkadotService {
+    #private;
+    readonly api: ApiPromise;
+    readonly chain: AnyParachain;
+    constructor(api: ApiPromise, chain: AnyParachain);
+    static create(chain: AnyParachain): Promise<PolkadotService>;
+    static createMulti(chains: AnyParachain[]): Promise<PolkadotService[]>;
+    get decimals(): number;
+    get existentialDeposit(): AssetAmount;
+    query(config: SubstrateQueryConfig): Promise<bigint>;
+    getExtrinsic(config: ExtrinsicConfig): SubmittableExtrinsic<'promise', ISubmittableResult>;
+    getExtrinsicCallHash(config: ExtrinsicConfig): HexString;
+    getPaymentInfo(account: string, config: ExtrinsicConfig): Promise<RuntimeDispatchInfo>;
+    getFee(account: string, config: ExtrinsicConfig): Promise<bigint>;
+    transfer(account: string, config: ExtrinsicConfig, signer: Signer | IKeyringPair, statusCallback?: (params: ISubmittableResult) => void): Promise<string>;
+}
+
+declare function getAllowanceSlot(owner: string, spender: string, allowanceSlot: number): Address;
+declare const MAX_ALLOWANCE_HEX: `0x${string}`;
+
+interface ListenToDestinationEventsProps {
+    route: AssetRoute;
+    monitoringConfig: EventMonitoringConfig;
+    messageId?: string;
+    onDestinationFinalized?: () => void;
+    onDestinationError?: (error: Error) => void;
+}
+declare function listenToDestinationEvents({ route, monitoringConfig, messageId, onDestinationFinalized, onDestinationError, }: ListenToDestinationEventsProps): Promise<void>;
+interface CreateMonitoringCallbackProps {
+    sourceAddress: string;
+    route: AssetRoute;
+    statusCallback?: (status: ISubmittableResult) => void;
+    onSourceFinalized?: () => void;
+    onSourceError?: (error: Error) => void;
+    onDestinationFinalized?: () => void;
+    onDestinationError?: (error: Error) => void;
+}
+interface ListenToSourceEventsProps extends CreateMonitoringCallbackProps {
+}
+interface ProcessSourceEventsProps extends ListenToSourceEventsProps {
+    events: EventRecord[];
+    unsubscribe?: () => void;
+}
+declare function processSourceEvents({ events, sourceAddress, route, onSourceFinalized, onSourceError, onDestinationFinalized, onDestinationError, unsubscribe, }: ProcessSourceEventsProps): void;
+declare function createMonitoringCallback({ sourceAddress, route, statusCallback, onSourceFinalized, onSourceError, onDestinationFinalized, onDestinationError, }: CreateMonitoringCallbackProps): (status: ISubmittableResult) => void;
+declare function listenToSourceEvents({ route, sourceAddress, onSourceFinalized, onSourceError, onDestinationFinalized, onDestinationError, }: ListenToSourceEventsProps): Promise<void>;
+
+export { type ChainTransferData, type ConvertToChainDecimalsParams, type DestinationChainTransferData, EvmService, type EvmSigner, type GetAssetsBalancesParams, type GetBalancesParams, type GetContractFeeParams, type GetDestinationDataParams, type GetDestinationFeeBalanceParams, type GetDestinationFeeParams, type GetExtrinsicFeeParams, type GetFeeParams, type GetMaxParams, type GetMinParams, type GetSourceDataParams, MAX_ALLOWANCE_HEX, PolkadotService, Sdk, type SdkOptions, type Signers, type SourceChainTransferData, type SovereignAccountBalance, type TransferData, type TransferParams, convertToChainDecimals, createMonitoringCallback, getAllowanceSlot, getAssetMin, getAssetsBalances, getBalance, getContractFee, getDestinationData, getDestinationFee, getDestinationFeeBalance, getExistentialDeposit, getExtrinsicFee, getFee, getMax, getMin, getParachainBalances, getSourceData, listenToDestinationEvents, listenToSourceEvents, processSourceEvents, validateSovereignAccountBalances };