Call parameters

Call parameters are:

1. Amount;
2. Asset ID;
3. Gas forwarded.

You can use these to forward coins to a contract. You can configure these parameters by creating an instance of CallParameters and passing it to a chain method called call_params.

For instance, suppose the following contract that uses Sway's msg_amount() to return the amount sent in that transaction.

    #[payable]
    fn get_msg_amount() -> u64 {
        msg_amount()
    }

Then, in Rust, after setting up and deploying the above contract, you can configure the amount being sent in the transaction like this:

        let contract_methods = MyContract::new(contract_id, wallet.clone()).methods();

        let tx_params = TxParameters::default();

        // Forward 1_000_000 coin amount of base asset_id
        // this is a big number for checking that amount can be a u64
        let call_params = CallParameters::new(Some(1_000_000), None, None);

        let response = contract_methods
            .get_msg_amount() // Our contract method.
            .tx_params(tx_params) // Chain the tx params setting method.
            .call_params(call_params)? // Chain the call params setting method.
            .call() // Perform the contract call.
            .await?;

call_params returns a result to ensure you don't forward assets to a contract method that isn't payable. In the following example, we try to forward an amount of 100 of the base asset to non_payable. As its name suggests, non_payable isn't annotated with #[payable] in the contract code. Passing CallParameters with an amount other than 0 leads to an InvalidCallParameters error:

    let err = contract_methods
        .non_payable()
        .call_params(CallParameters::new(Some(100), None, None))
        .expect_err("Should return call params error.");

    assert!(matches!(err, Error::AssetsForwardedToNonPayableMethod));

Note: forwarding gas to a contract call is always possible, regardless of the contract method being non-payable.

You can also use CallParameters::default() to use the default values:

pub const DEFAULT_CALL_PARAMS_AMOUNT: u64 = 0;
// Bytes representation of the asset ID of the "base" asset used for gas fees.
pub const BASE_ASSET_ID: AssetId = AssetId::BASE;

This way:

        let response = contract_methods
            .initialize_counter(42)
            .call_params(CallParameters::default())?
            .call()
            .await?;

The gas_forwarded parameter defines the limit for the actual contract call as opposed to the gas limit for the whole transaction. This means that it is constrained by the transaction limit. If it is set to an amount greater than the available gas, all available gas will be forwarded.

        // Set the transaction `gas_limit` to 10000 and `gas_forwarded` to 4300 to specify that the
        // contract call transaction may consume up to 10000 gas, while the actual call may only use 4300
        // gas
        let tx_params = TxParameters::new(None, Some(10000), None);
        let call_params = CallParameters::new(None, None, Some(4300));

        let response = contract_methods
            .get_msg_amount() // Our contract method.
            .tx_params(tx_params) // Chain the tx params setting method.
            .call_params(call_params)? // Chain the call params setting method.
            .call() // Perform the contract call.
            .await?;

If you don't set the call parameters or use CallParameters::default(), the transaction gas limit will be forwarded instead.