non-trapping host functions for try_from_val

[mootz12]

Context

In the rs-soroban-sdk, try_from_val is expected to be a recoverable conversion API, but some generated SDK conversions still trap or panic for ordinary user-data shape mismatches.

Generated contracttype conversions and some tuple conversions call host/env helpers such as:

• map_unpack_to_slice
• vec_unpack_to_slice
• symbol_index_in_strs

These helpers currently report shape mismatches as host errors. Because soroban_sdk::Env is intentionally infallible, those host errors trap or panic before try_from_val can return Err.

This makes fallback logic unreliable, and is generally unexpected:

#[contracttype]
pub struct DataV1 { a: i64, b: i64 }

#[contracttype]
pub struct DataV2 { a: i64, b: i64, c: i64 }

let raw: Val = env.storage().persistent().get(&DataKey::Data(id)).unwrap();

// this panics!
if let Ok(v2) = DataV2::try_from_val(&env, &raw) {
    v2
} else {
    let v1 = DataV1::try_from_val(&env, &raw).unwrap();
    DataV2::from(v1)
}

Proposal

Introduce new host functions whose successful return value can represent conversion failure.

Functions

/// ### Returns
/// * Ok(Val::VOID) -> if successful
/// * Ok(Error::from_type_and_code(
///       ScErrorType::Value,
///       ScErrorCode::UnexpectedType,
///   ).to_val())
///   -> if conversion failed, e.g. vec length does not match output slice length
/// * Err -> if some other, non conversion related error was thrown
fn try_vec_unpack_to_slice(&self, vec: VecObject, vals: &mut [Val]) -> Result<Val, Self::Error>

/// ### Returns
/// * Ok(Val::VOID) -> if successful
/// * Ok(Error::from_type_and_code(
///       ScErrorType::Value,
///       ScErrorCode::UnexpectedType,
///   ).to_val())
///   -> if conversion failed, e.g. map does not exactly match the requested keys
/// * Err -> if some other, non conversion related error was thrown
fn try_map_unpack_to_slice(
    &self,
    map: MapObject,
    keys: &[&str],
    vals: &mut [Val],
) -> Result<Val, Self::Error>

/// ### Returns
/// * Ok(index.to_val()) -> if successful
/// * Ok(Error::from_type_and_code(
///       ScErrorType::Value,
///       ScErrorCode::UnexpectedType,
///   ).to_val())
///   -> if conversion failed, e.g. enum case does not exist
/// * Err -> if some other, non conversion related error was thrown
fn try_symbol_index_in_strs(&self, sym: Symbol, slices: &[&str]) -> Result<Val, Self::Error>

All try_ conversion functions return the same ScError and Code, similar to try_call. Exact error is not super relevant. The error was chosen so the SDK can return ConversionError.

SDK changes

Once these helpers exist, generated SDK conversions should use them during try_from_val:

• contracttype structs should use map_unpack_to_slice_v2.
• Tuple structs should use try_vec.
• Enums should use try_symbol_index_in_strs.
• Generic tuple TryFromVal implementations in soroban-env-common should also use vec_unpack_to_slice_v2.

Alternatives

SDK-side preflight

The SDK can preflight some cases before calling the current helpers:

• check vec length before vec_unpack_to_slice,
• check map length and expected keys before map_unpack_to_slice,
• scan enum cases in SDK code instead of using symbol_index_in_strs.

This works for some generated contracttype code, but it is incomplete and less efficient. It may not cover generic conversions in soroban-env-common, and map validation requires duplicating host-side logic.