Call a contract on chain B from chain A and attach some tokens

To call chain B from chain A and send some tokens along the way, the user needs to call callContractWithToken on the gateway of chain A, specifying:

• The destination chain, which must be an EVM chain from Chain names.
• The destination contract address, which must inherit from QPExecutable defined in QPExecutable.sol.
• The payload bytes to pass to the destination contract.
• The symbol of the token to transfer, which must be a supported asset (Mainnet | Testnet).
• The amount of the token to transfer.

As per the snippet below:

function callContractWithToken(
    string memory destinationChain,
    string memory contractAddress,
    bytes memory payload,
    string memory symbol,
    uint256 amount
) external;

QPExecutable has an executeWithToken function that will be triggered by the Quantum Portal network on the destination chain after the callContractWithToken function has been executed on the source chain. This will validate the contract call and then invoke your _executeWithToken method, where you should write any custom logic.

The destination contract will be authorized to transfer the ERC-20 identified by the tokenSymbol.

function _executeWithToken(
    string memory sourceChain,
    string memory sourceAddress,
    bytes calldata payload,
    string memory tokenSymbol,
    uint256 amount
) internal virtual {}

Example

Suppose our destination contract wants to forward the token it received to a recipient provided in the payload. It could be done this way.

function _executeWithToken(
    string memory sourceChain,
    string memory sourceAddress,
    bytes calldata payload,
    string memory tokenSymbol,
    uint256 amount
) internal virtual {
    // decode recipient
    address recipient = abi.decode(payload, (address));
    // get ERC-20 address from gateway
    address tokenAddress = gateway.tokenAddresses(tokenSymbol);

    // transfer received tokens to the recipient
    IERC20(tokenAddress).transfer(recipient, amount);
}

The payload passed to callContract (and ultimately to the _execute and _executeWithToken) has type bytes. Use the ABI encoder/decoder convert your data to bytes.

Example of payload encoding in JavaScript (using ethers.js):

const { ethers } = require("ethers");

// encoding a string
const payload = ethers.utils.defaultAbiCoder.encode(
  ["string"],
  ["Hello from contract A"]
);

Example of payload decoding in Solidity:

function _execute(
    string memory sourceChain,
    string memory sourceAddress,
    bytes calldata payload
) internal override {
    // decoding a string
    string memory _message = abi.decode(payload, (string));
}

Learn More: Explore our tutorial on building a decentralized application (dApp) for cross-chain airdrops using Solidity, Next.js, and Quantum Portal’s General Message Passing with callContractWithToken. This tutorial will guide you through the process of distributing tokens across multiple chains: How to Build a Cross-Chain Airdrop DApp With Solidity, Next.js, and Quantum Portal.