mvx-cross-contract-calls

Files (1)

• SKILL.md

SKILL.md (first lines)

# MultiversX Cross-Contract Calls — Tx Builder API Reference

Complete reference for cross-contract calls, callbacks, back-transfers, and proxies in MultiversX smart contracts (SDK v0.64+).

## Tx Builder Chain

Every cross-contract interaction starts with `self.tx()` and chains builder methods:

```
self.tx()
    .to(address)                        // recipient (ManagedAddress or &ManagedAddress)
    .typed(ProxyType)                   // type-safe proxy (recommended)
    // OR .raw_call("endpoint_name")    // raw call without proxy
    .egld(&amount)                      // payment: EGLD
    // OR .single_esdt(&id, nonce, &amount) // payment: single ESDT
    // OR .payment(payment)             // payment: Payment / EgldOrEsdtTokenPayment
    .gas(gas_limit)                     // explicit gas (required for promises)
    .returns(ReturnsResult)             // result handler(s)
    .sync_call()                        // execution method
```

### Builder Methods

| Category | Method | Description |
|----------|--------|-------------|
| **Target** | `.to(address)` | Set recipient address |
| **Proxy** | `.typed(ProxyType)` | Use generated proxy for type-safe calls |
| **Raw** | `.raw_call("endpoint")` | Manual endpoint call (no proxy) |
| **Payment** | `.egld(&amount)` | Attach EGLD |
| | `.single_esdt(&token_id, nonce, &amount)` | Attach single ESDT |
| | `.esdt(esdt_payment)` | Attach `EsdtTokenPayment` |
| | `.payment(payment)` | Attach any payment type |
| | `.egld_or_single_esdt(&id, nonce, &amount)` | Attach EGLD or ESDT |
| **Gas** | `.gas(amount)` | Set gas limit |
| | `.gas_for_callback(amount)` | Reserve gas for callback |
| **Args** | `.argument(&arg)` | Add single argument (raw calls) |
| | `.arguments_raw(buffer)` | Add pre-encoded arguments |
| **Results** | `.returns(handler)` | Add result handler (can chain multiple) |
| **Callback** | `.callback(closure)` | Set callback for async calls |

### Execution Methods

| Method | Type | Description |
|--------|------|-------------|
| `.sync_call()` | Synchronous | Same-shard atomic. Panics if callee fails. |
| `.sync_call_fallible()` | Synchronous | Same-shard. Returns `Result` on callee error (use with `ReturnsHandledOrError`). |
| `.sync_call_readonly()` | Synchronous | Read-only call. Cannot modify state. |
| `.register_promise()` | Async (v2) | Cross-shard. Requires `.gas()`. Multiple promises per tx OK. |
| `.async_call_and_exit()` | Async (v1) | Legacy. Only 1 per tx. Exits immediately. Prefer `register_promise()`. |
| `.transfer()` | Transfer | Send tokens without calling an endpoint. |

## Simple Transfers (No Endpoint Call)

```rust
// Send EGLD
self.tx().to(&recipient).egld(&amount).transfer();

// Send ESDT
self.tx().to(&recipient).payment(payment.clone()).transfer();

// Send specific ESDT
self.tx().to(&recipient).single_esdt(&token_id, nonce, &amount).transfer();
```

## Synchronous Calls (Same-Shard)

### Typed Proxy Call
```rust
// Basic sync call with typed result
let result: BigUint = self.tx()
    .to(&pool_address)
    .typed(proxy_pool::LiquidityPoolProxy)
    .get_reserve()
    .returns(ReturnsResult)
    .sync_call();
```

### Sync Call with Payment
```rust
self.tx()
    .to(&accumulator_address)
    .typed(proxy_accumulator::AccumulatorProxy)
    .deposit()
    .payment(revenue)
    .returns(ReturnsResult)
    .sync_call();
```

### Multiple Return Values
```rust
// Chain multiple .returns() for multi-value returns
let (result, back_transfers) = self.tx()
    .to(&pool_address)
    .typed(proxy_pool::PoolProxy)
    .withdraw(amount)
    .returns(ReturnsResult)
    .returns(ReturnsBackTransfersReset)
    .sync_call();
```

### Fallible Sync Call
```rust
// Use with ReturnsHandledOrError to not panic on callee error
let outcome: Result<BigUint, u32> = self.tx()
    .to(&address)
    .typed(SomeProxy)
    .some_endpoint()
    .returns(
        ReturnsHandledOrError::new()
            .returns(ReturnsResult)
    )
    .sync_call_fallible();

match outcome {
    Ok(value) => { /* success */ },
    Err(error_code) => { /* callee returned error */ },
}
```

From multiversx/mx-ai-skills, MIT.

More from multiversx/mx-ai-skills