Auto SDKAuto XDM

Auto-XDM Package

Introduction

The Autonomys Auto XDM SDK (@autonomys/auto-xdm) provides functionalities for cross-domain transfer of native tokens.

Features

  • Cross-Domain Transfer: Enable token transfers between consensus and domain wallets.
  • TypeScript Support: Full TypeScript type definitions for an enhanced developer experience.

Installation

Install the package via npm or yarn:

# Using npm
npm install @autonomys/auto-xdm
 
# Using yarn
yarn add @autonomys/auto-xdm

Importing

Import the auto-xdm functions you need into your project:

// Import specific functions
import { 
  transferToConsensus,
  transferToDomainAccount20Type,
  transferToDomainAccount32Type 
} from '@autonomys/auto-xdm';
 
// Or import everything
import * as xdm from '@autonomys/auto-xdm';

Available functions

Transfer functions

Note: All transfer functions return a SubmittableExtrinsic that must be signed and sent. The amount parameter expects the smallest unit of the token (Shannon). For 18 decimals, multiply by 10^18 or use formatTokenAmount from auto-utils. Ensure a sufficient balance in the sending account to cover both the transfer and fees. Cross-domain transfers may take a few blocks to complete.

  • transfer(api, destination, amount): Promise<SubmittableExtrinsic>: Base transfer function for cross-domain transfers.
  • transferToConsensus(api, accountId32, amount): Promise<SubmittableExtrinsic>: Transfer tokens from a domain to the consensus chain.
  • transferToDomainAccount20Type(api, destinationDomainId, accountId20, amount): Promise<SubmittableExtrinsic>: Transfer tokens from the consensus chain to an EVM address.
  • transferToDomainAccount32Type(api, destinationDomainId, accountId32, amount): Promise<SubmittableExtrinsic>: Transfer tokens from the consensus chain to a Substrate address.

Query functions

Note: Monitor transfer status using query functions.

  • chainAllowlist(api): Promise<Codec>: Retrieves the list of allowed chains.
  • channels(api, chainId): Promise<Codec>: Retrieves the list of channels
  • consensusChannels(api): Promise<Codec>: Retrieves the list of consensus channels
  • domainChannels(api, domainId): Promise<Codec>: Retrieves the list of domain channels
  • allCancelledTransfers(api): Promise<Codec>: Retrieves all cancelled transfers.
  • chainTransfers(api): Promise<Codec>: Retrieves all chain transfers.
  • allDomainBalances(api): Promise<Codec>: Retrieves balances across all domains.
  • domainBalances(api, domainId): Promise<Codec>: Retrieves balances for a specific domain.
  • allUnconfirmedTransfers(api): Promise<Codec>: Retrieves pending transfers.

Type definitions

type Amount = BigInt | number | string;
 
type Consensus = {
    type: 'consensus';
};
 
type Domain = {
    type: 'domain';
    domainId: number;
};
 
type ChainOrDomain = Consensus | Domain;

Usage examples

1. Transfer from Consensus to Domain (EVM address)

import { activateWallet } from '@autonomys/auto-utils'
import { transferToDomainAccount20Type } from '@autonomys/auto-xdm'
 
const api = await activateWallet({ networkId: 'chronos', uri: '//alice' })
const tx = await transferToDomainAccount20Type(
  api,
  0, // Receiver domain (0 is Auto EVM on Chronos Testnet)
  '0x1234567890abcdef', // Receiver domain account
  '1000000000000000000',
)

2. Transfer from Consensus to Domain (Substrate address)

import { activateWallet } from '@autonomys/auto-utils'
import { transferToDomainAccount32Type } from '@autonomys/auto-xdm'
 
const api = await activateWallet({ networkId: 'chronos', uri: '//alice' })
const tx = await transferToDomainAccount32Type(
  api,
  0, // Receiver domain (0 is Auto EVM on Chronos Testnet)
  'su1234567890abcdef', // Receiver domain account
  '1000000000000000000',
)

3. Transfer from Domain to Consensus

import { activateWallet } from '@autonomys/auto-utils'
import { transferToConsensus } from '@autonomys/auto-xdm'
 
const api = await activateWallet({ networkId: 'chronos', domainId: 0, uri: '//alice' })
const tx = await transferToConsensus(
  api,
  'su1234567890abcdef', // Receiver consensus account,
  '1000000000000000000',
)

4. Query domain balances

import { activateWallet } from '@autonomys/auto-utils';
import { domainBalances } from '@autonomys/auto-xdm';
 
(async () => {
  const { api } = await activateWallet({ 
    networkId: 'chronos' 
  });
 
  // Get balances for domain 0 (Auto EVM on the Chronos testnet)
  const balances = await domainBalances(api, 0);
  console.log('Domain balances:', balances.toString());
})();

Best practices

  1. Error Handling: Wrap asynchronous calls and transactions in try...catch blocks to handle potential errors gracefully:

    try {
  const tx = await transferToConsensus(api, receiver, amount);
  await tx.signAndSend(account);
} catch (error) {
  console.error('Transfer failed:', error);
}

  2. Amount Formatting: Use appropriate decimal places for token amounts:

    • The amount parameter expects the smallest unit of the token (Shannon).
    • For 18 decimals, multiply by 10^18 or use formatTokenAmount from auto-utils.

  3. API Management: > Always disconnect the API instance after your operations are complete to free up resources:

    try {
  // ... your code ...
} finally {
  await api.disconnect();
}
Auto UtilsPolkadot API