multiversx-cross-contract-calls_skill

Overview

This skill shows how to make cross-contract calls in MultiversX smart contracts using the Tx builder API. It covers transfers, synchronous and asynchronous calls, callbacks, back-transfers handling, and typed proxies to keep calls type-safe. Use it to build robust inter-contract flows that correctly manage payments, gas, and returned tokens.

How this skill works

All cross-contract interactions start from self.tx() and chain builder methods like .to(), .typed() or .raw_call(), payment options, .gas(), .returns(), and an execution method (.sync_call(), .register_promise(), .transfer()). Result handlers capture returned values and back-transfers; callbacks handle async promise results with #[promises_callback]. Always set gas for promises and prefer ReturnsBackTransfersReset to reliably collect returned tokens.

When to use it

• Calling another contract endpoint on the same shard (synchronous operations).
• Issuing cross-shard requests that need callbacks or promises (async register_promise()).
• Sending tokens (EGLD or ESDT) along with a contract call or as a plain transfer.
• Receiving and processing back-transfers from a callee (swaps, withdrawals).
• Using generated typed proxies for type-safe, IDE-friendly endpoint calls.

Best practices

• Prefer typed proxies (.typed(Proxy)) for type safety and clearer arguments/returns.
• Always use ReturnsBackTransfersReset when expecting back-transfers to avoid stale data.
• Set explicit .gas() for async register_promise() and .gas_for_callback() for callbacks.
• Use .returns(ReturnsHandledOrError) with sync_call_fallible() to avoid panics on callee errors.
• Use .transfer() for plain token sends and reserve .payment() for call-attached payments.

Example use cases

• Swap tokens on a DEX and forward resulting back-transfers to the original caller.
• Withdraw liquidity from a pool, then deposit the result into another pool using returned payments.
• Fire a cross-shard delegation call and mint/ refund tokens in a #[promises_callback] based on success or failure.
• Deploy a new contract via a typed proxy and capture the new ManagedAddress with ReturnsNewManagedAddress.
• Make a raw_call to read status or metadata when a proxy is not available.