Interacting with Runtime Return Values

Users interacting with a Casper network must keep in mind the differences between session and contract code. Session code executes entirely within the context of the initiating account, while contract code executes within the context of its own state. Any action undertaken by a contract must initiate through an outside call, usually via session code.

Developers should note the difference between a caller and an immediate caller. The immediate caller represents the session or contract code that directly accessed the entry point. The caller is the original, initiating session code that started the entire process. There are many cases where contract code may call additional contract code. In this case, the immediate caller may be another instance of contract code. Even in this event, the overall caller will be the initiating session code, while there may be several layers of stacked contract code acting as immediate callers.

Contract code can optionally return a value to their immediate caller via runtime::ret(), whether that immediate caller is another contract code or session code. The returned value may be used within the context of the session or contract code, stored for later use, or discarded if not needed. Use of return values depends entirely on what the developer needs in that instance.

Session code initiates actions on behalf of an account which is considered to be the caller. Therefore, it cannot return anything.

Contract Code

For example, if we create a contract to accept and keep a record of donations, we would use runtime::ret() to define the results that should be passed to the caller as per the following:

#[no_mangle]
pub extern "C" fn donate() {
    let donating_account_key: Key = runtime::get_named_arg(DONATING_ACCOUNT_KEY);
    if let Key::Account(donating_account_hash) = donating_account_key {
        update_ledger_record(donating_account_hash.to_string())
    } else {
        runtime::revert(FundRaisingError::InvalidKeyVariant)
    }
    let donation_purse = *runtime::get_key(FUNDRAISING_PURSE)
        .unwrap_or_revert_with(FundRaisingError::MissingFundRaisingPurseURef)
        .as_uref()
        .unwrap_or_revert();
    let value = CLValue::from_t(donation_purse.into_add()).unwrap_or_revert();
    runtime::ret(value)
}

In this example, the return value is the URef corresponding to the purse used to raise funds, with add permission only. Using this information, the calling code will be able to then transfer funds into the purse, after calling the donate entry point.

Without the addition of the runtime::ret, the purse would not be returned to the caller.

Session Code

The following is an example of session code calling the specified entry point. Keep in mind that the immediate caller does not need to be session code, and the immediate caller could be another instance of contract code.

#[no_mangle]
pub extern "C" fn call() {
    let fundraiser_contract_hash: ContractHash = runtime::get_named_arg(FUNDRAISER_CONTRACT_HASH);
    let donating_account_key: Key = runtime::get_named_arg(DONATING_ACCOUNT_KEY);
    let donation_amount: U512 = runtime::get_named_arg(DONATION_AMOUNT);

    let donating_purse_uref: URef = runtime::call_contract(
        fundraiser_contract_hash,
        ENTRY_POINT_DONATE,
        runtime_args! {
            DONATING_ACCOUNT_KEY => donating_account_key
        },
    );
    system::transfer_from_purse_to_purse(
        account::get_main_purse(),
        donating_purse_uref,
        donation_amount,
        None
    )
        .unwrap_or_revert()
}

This session code calls into a contract's entry point by using runtime::call_contract, supplying the contract_hash to identify the contract to be called, and the name of the entry point to be invoked, in this case donate. It supplies the donating_account_key, which in this case is the account key of the caller. The contract will then provide a return value, in this case donating_purse_uref. To call an entry point, you will need to know the CLType of the return value and identify it within the code.

You can determine the type of the return value by querying the contract object in global state. To query a contract rather than an account, replace the key parameter with the formatted string representation of the contract hash.

This example code takes that returned value and transfers a donation_amount from the calling account's main purse to the established donation purse. It is not necessary for the code to store, or even use, the returned value. Use of the returned value depends on the needs of the developer.