@xrplevm/xchain-sdk

Cross-chain SDK to enable developers to bridge assets between XRPL and the XRPL EVM Sidechain programmatically.

Table of Contents

• Installation
• Features
• Core API
  • Bridge.fromConfig(network, overrides)
  • bridge.transfer(asset, amount, options?)
  • bridge.callContract(asset, destinationContractAddress, payload)
• Configuration
  • Configuration Structure
  • Required Secrets
  • Flow: How Configuration is Used
• Errors
  • Common Error Classes
  • Example Error Codes
    • BridgeErrorCodes
    • XrplEvmErrorCodes
    • XrplErrorCodes
• Examples

Installation

npm install @xrplevm/xchain-sdk
# or
pnpm add @xrplevm/xchain-sdk
# or
yarn add @xrplevm/xchain-sdk

Features

• Bridge assets between XRPL and XRPL EVM Sidechain
• Supports native XRP, issued assets, and EVM tokens
• Simple configuration for multiple networks (mainnet, testnet, devnet)
• TypeScript support

Core API

The Bridge class is the main entry point for interacting with the SDK. It encapsulates the logic for cross-chain operations between XRPL and the XRPL EVM sidechain. You typically create an instance of this class using the static fromConfig method, providing network details and any necessary overrides.

Bridge.fromConfig(network, overrides)

Create a bridge instance with network defaults and optional overrides.

• network: devnet | testnet | mainnet
• overrides (optional):
  • xrpl: override XRPL RPC, gateway, Chain ID, or add a seed
  • xrplevm: override XRPL-EVM RPC, gateway, Chain ID, or add a private key

It will expect you to input at least the private key or seed from the destination chain to build the wallet to sign and submit the transactions.

bridge.transfer(asset, amount, options?)

Perform a cross-chain transfer. The direction (XRPL→EVM or EVM→XRPL) is inferred from the asset type.

Note:
The options object differs depending on the transfer direction. The most relevant options are:

• XRPL → EVM:

  • gasFeeAmount (optional): Custom gas fee for the EVM transaction (default from config)
  • (See XrplTransferOptions for all options)

• EVM → XRPL:

  • interchainGasValue (optional): Gas value (in wei, as a string) for the interchain part of the transfer. Defaults to "0" if not provided.
  • gasValue (optional): Gas price (in wei, as a string) for the EVM transaction.
  • gasLimit (optional): Gas limit (as a string) for the EVM transaction.
  • (See XrplEvmTransferOptions for all options)

Refer to the generated TypeScript definitions for the full list of supported options and types for each direction:

• XrplTransferOptions
• XrplEvmTransferOptions

bridge.transfer(
  asset: BridgeAsset,         // EvmAsset or Xrp/XrplAsset
  amount: number,             // e.g. 1.5
  options: {
    destinationAddress: string;    // recipient on target chain
    doorAddress?: string;         // custom gateway contract
    gasValue?: string;            // XRPL→EVM only
  }
);

bridge.callContract(asset, destinationContractAddress, payload)

Execute a smart contract function on the EVM sidechain, initiated from XRPL, along with transferring an XRPL asset (either native XRP or an issued asset). This allows for more complex cross-chain interactions beyond simple transfers.

• asset: The XrpAsset or XrplIssuedAsset to be transferred from XRPL.
• destinationContractAddress: The address of the smart contract on the EVM sidechain to call.
• payload: Hex-encoded data representing the function call and its arguments for the destination contract.

Refer to the Bridge class source code (src/bridge/bridge.ts) for the exact method signature and return types.

Configuration

The SDK provides sane defaults for all networks (RPC endpoints, Axelar gateway & token service addresses, chain IDs). You can override any value in fromConfig:

Bridge.fromConfig("mainnet", {
    xrplevm: {
        providerUrl: "https://my.custom.rpc",
        privateKey: process.env.EVM_KEY,
    },
    xrpl: {
        providerUrl: "wss://custom.xrpl.rpc",
        keyOrSeed: process.env.XRPL_SEED,
    },
});

Configuration Structure

At the core, the SDK uses the following configuration interfaces:

• AxelarChainConfig :

  • providerUrl: RPC endpoint for the EVM-compatible chain
  • chainId: Chain ID of the EVM network
  • gatewayAddress: Axelar Gateway contract address
  • interchainTokenServiceAddress: Axelar Interchain Token Service contract address

• BridgeConfig :

  • xrpl: XRPL chain configuration, extends AxelarChainConfig with seed.
  • xrplevm: EVM sidechain configuration extends AxelarChainConfig with privateKey

• BridgeConfigOptions: Allows you to override any part of the default config for either chain.

Required Secrets

The configuration enforces that you provide at least the secret (seed or private key) for the source chain. This is required to build the wallet and sign transactions. For XRPL, provide a seed; for EVM, provide a privateKey.

Flow: How Configuration is Used

• Bridge.fromConfig builds the provider for both chains using the configuration (with defaults or your overrides).
• The wallet is built from the secret of the source chain, enabling signing and sending transactions.
• The destination chain provider is also initialized, but the wallet is only required for the source chain.

Errors

The SDK provides descriptive error classes and codes to help you handle issues programmatically. Most errors thrown are subclasses of BridgeError or chain-specific errors like XrplEvmError.

BridgeErrorCodes

• MISSING_WALLET_SECRET — Wallet secret or private key not provided
• INVALID_CONFIG — Configuration is invalid or incomplete

XrplEvmErrorCodes

• NO_EVM_SIGNER — EVM signer is missing
• RPC_UNAVAILABLE — EVM RPC provider is unavailable
• TX_NOT_MINED — EVM transaction was not mined

XrplErrorCodes

• INVALID_SEED — Invalid XRPL wallet seed provided
• NO_RPC_FOR_XRPL_SOURCE — No RPC URL provided for XRPL source

You can catch and inspect these errors to provide better UX or debugging information:

try {
  await bridge.transfer(...);
} catch (err) {
  if (err instanceof BridgeError) {
    console.error('Bridge error:', err.code, err.message);
  }
}

Examples

See the examples/ directory for sample scripts:

• Transfer XRP from XRPL to EVM
• Transfer EVM tokens to XRPL
• Call contracts with token transfers