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: 'taurus', uri: '//alice' })
const tx = await transferToDomainAccount20Type(
  api,
  0, // Receiver domain (0 is Auto EVM on Taurus 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: 'taurus', uri: '//alice' })
const tx = await transferToDomainAccount32Type(
  api,
  0, // Receiver domain (0 is Auto EVM on Taurus 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: 'taurus', 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: 'taurus' 
  });
 
  // Get balances for domain 0 (Auto EVM on the Taurus 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();
   }