feat: improved XDM functionality in auto-xdm, add integration tests (⚠️ breaking changes)

[jfrank-summit]

XDM API Enhancements and Integration Test Infrastructure

Summary of Changes

This PR introduces significant improvements to the @autonomys/auto-xdm package API and adds comprehensive integration test infrastructure. The changes include:

1. Unified Transfer API: Consolidated multiple transfer functions into a single, more intuitive transporterTransfer function
2. Enhanced Type System: Added comprehensive TypeScript types for better type safety and developer experience
3. New Query Functions: Expanded XDM info capabilities with functions for querying cancelled transfers, unconfirmed transfers, and domain balances
4. Integration Test Infrastructure: Complete Docker-based test environment with helpers and test suites
5. Codec Transformations: New utilities for converting between Rust codec types and TypeScript-friendly types

It got quite large, there will be a follow-up PR to improve integration tests and messenger call function typing.

Motivation and Context

The previous XDM transfer API had multiple functions (transferToConsensus, transferToDomainAccount20Type, transferToDomainAccount32Type) that were difficult to discover and use. The new unified API:

• Provides a single, consistent interface for all transfer operations
• Uses intuitive chain and account type parameters
• Improves type safety with dedicated TypeScript types
• Makes the API more extensible for future chain types

Additionally, the lack of integration tests made it difficult to verify XDM functionality end-to-end. The new integration test infrastructure:

• Validates XDM functionality against real blockchain nodes
• Provides reusable helpers for setting up XDM channels
• Documents patterns for testing cross-domain operations
• Ensures API changes don't break real-world workflows

Implementation Details

API Changes

Old API (Removed):

transferToConsensus(api, accountId32, amount)
transferToDomainAccount20Type(api, domainId, accountId20, amount)
transferToDomainAccount32Type(api, domainId, accountId32, amount)

New API:

transporterTransfer(api, destination, account, amount)
// destination: 'consensus' | { domainId: number }
// account: { accountId32: string } | { accountId20: string }

New Types

• Chain: 'consensus' | { domainId: number } - Chain identifier
• TransferAccount: { accountId32: string } | { accountId20: string } - Account identifier
• Channel: Complete channel configuration with state, nonces, and fees
• ChannelState: 'Initiated' | 'Open' | 'Closed'
• DomainBalance: Domain balance entry
• Transfer: Transfer entry for cancelled/unconfirmed transfers

New Query Functions

• chainAllowlist(api): Query chains allowed to open channels
• channels(api, chain, channelId): Query specific channel configuration
• nextChannelId(api, chain): Get next channel ID for a chain
• domainBalances(api, domainId?): Query domain balances (single or all)
• cancelledTransfers(api, from, to?): Query cancelled transfers
• unconfirmedTransfers(api, from, to?): Query unconfirmed transfers

Integration Test Infrastructure

New Directory Structure:

integration-tests/
├── docker/              # Docker Compose configuration
├── helpers/             # Test utilities (chain setup, XDM setup, wallets)
├── scripts/             # Helper scripts (wait-for-ready)
└── suites/              # Test suites organized by package
    └── auto-xdm/        # XDM-specific tests

Key Features:

• Docker Compose setup with consensus and domain nodes
• Automatic chain readiness detection
• XDM channel setup helper that skips already-completed steps
• Comprehensive test examples for transfers and info queries

Transform Utilities

New transforms.ts module provides internal utilities for:

• Converting ChainId (JSON) to Chain (friendly type)
• Converting Chain to ChainId Codec for storage queries
• Converting Channel Codec to friendly Channel type
• Converting balance Codecs to bigint

Breaking Changes

⚠️ This PR introduces breaking changes to the XDM transfer API, the next release will increment the minor version for the SDK

Removed Functions:

• transfer() - Low-level function accepting Codec
• transferToConsensus() - Replaced by transporterTransfer()
• transferToDomainAccount20Type() - Replaced by transporterTransfer()
• transferToDomainAccount32Type() - Replaced by transporterTransfer()

Follow-ups

• Add integration tests for cancelled transfers
• Improve integration test process for efficiency and speed
• Add integration tests to CI
• Improve messenger call function (initiateChannel, closeChannel) typing

[Copilot]

Pull Request Overview

This PR adds integration tests infrastructure and refactors the XDM (Cross-Domain Messaging) package to provide a more user-friendly API for cross-chain transfers. The changes include:

• Simplified XDM transfer API using friendly Chain and TransferAccount types
• New integration tests infrastructure with Docker Compose setup for testing against real blockchain nodes
• Enhanced type definitions and documentation for XDM functionality
• Updated examples to use the new simplified API

Reviewed Changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
yarn.lock	Added dependencies for integration tests (tsx, ts-jest, esbuild, type definitions) and workspace references
packages/auto-xdm/src/types.ts	New file defining friendly types for chains, accounts, channels, balances, and transfers
packages/auto-xdm/src/transforms.ts	New helpers to convert between JSON representations and friendly types
packages/auto-xdm/src/transfer.ts	Refactored transfer function with simplified API using Chain and TransferAccount types
packages/auto-xdm/src/info.ts	Refactored storage query functions with improved documentation and friendly return types
packages/auto-xdm/README.md	Updated examples to demonstrate new simplified API
integration-tests/*	Complete integration test infrastructure with Docker setup, helpers, and test suites
package.json	Added integration test scripts at root level
examples/auto-xdm-transfers/main.ts	Updated to use new transporterTransfer API

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

Comment @cursor review or bugbot run to trigger another review on this PR

[clostao]

LGTM

[vedhavyas]

skimmed through integration tests.
Rest LGTM