Struct Host

pub struct Host(/* private fields */);

Implementations

impl Host

pub fn get_events(&self) -> Result<Events, HostError>

pub fn get_diagnostic_events(&self) -> Result<Events, HostError>

impl Host

pub fn scaddress_from_address( &self, address: AddressObject, ) -> Result<ScAddress, HostError>

impl Host

pub fn with_mut_storage<F, U>(&self, f: F) -> Result<U, HostError>

where F: FnOnce(&mut Storage) -> Result<U, HostError>,

impl Host

pub fn add_ledger_entry( &self, key: &Rc<LedgerKey>, val: &Rc<LedgerEntry>, live_until_ledger: Option<u32>, ) -> Result<(), HostError>

pub fn setup_storage_entry( &self, key: Rc<LedgerKey>, val: Option<(Rc<LedgerEntry>, Option<u32>)>, access_type: AccessType, ) -> Result<(), HostError>

pub fn setup_storage_footprint( &self, footprint: Footprint, ) -> Result<(), HostError>

impl Host

pub fn has_frame(&self) -> Result<bool, HostError>

Returns if the host currently has a frame on the stack.

A frame being on the stack usually indicates that a contract is currently executing, or is in a state just-before or just-after executing.

pub fn with_test_contract_frame<F>( &self, id: Hash, func: Symbol, f: F, ) -> Result<Val, HostError>

where F: FnOnce() -> Result<Val, HostError>,

Pushes a test contract [Frame], runs a closure, and then pops the frame, rolling back if the closure returned an error. Returns the result that the closure returned (or any error caused during the frame push/pop). Used for testing.

pub fn invoke_function(&self, hf: HostFunction) -> Result<ScVal, HostError>

impl Host

pub fn enable_invocation_metering(&self)

Enables invocation metering (it’s disabled by default).

impl Host

pub fn register_test_contract( &self, contract_address: AddressObject, contract_fns: Rc<dyn ContractFunctionSet>, ) -> Result<(), HostError>

pub fn register_test_contract_with_constructor( &self, contract_address: AddressObject, contract_fns: Rc<dyn ContractFunctionSet>, constructor_args: VecObject, ) -> Result<(), HostError>

pub fn call_constructor_for_stored_contract_unsafe( &self, contract_id: &Hash, constructor_args: VecObject, ) -> Result<(), HostError>

impl Host

pub fn metered_hash_xdr( &self, obj: &impl WriteXdr, ) -> Result<[u8; 32], HostError>

pub fn metered_from_xdr<T: ReadXdr>(&self, bytes: &[u8]) -> Result<T, HostError>

impl Host

pub fn with_storage_and_budget(storage: Storage, budget: Budget) -> Self

Constructs a new Host that will use the provided Storage for contract-data access functions such as [Env::get_contract_data].

pub fn build_module_cache_if_needed(&self) -> Result<(), HostError>

pub fn in_storage_recording_mode(&self) -> Result<bool, HostError>

pub fn clear_module_cache(&self) -> Result<(), HostError>

pub fn rebuild_module_cache(&self) -> Result<(), HostError>

pub fn set_source_account( &self, source_account: AccountId, ) -> Result<(), HostError>

pub fn remove_source_account(&self) -> Result<(), HostError>

pub fn source_account_address(&self) -> Result<Option<AddressObject>, HostError>

pub fn switch_to_enforcing_storage(&self) -> Result<(), HostError>

pub fn switch_to_recording_auth( &self, disable_non_root_auth: bool, ) -> Result<(), HostError>

pub fn set_authorization_entries( &self, auth_entries: Vec<SorobanAuthorizationEntry>, ) -> Result<(), HostError>

pub fn set_base_prng_seed(&self, seed: Seed) -> Result<(), HostError>

pub fn set_ledger_info(&self, info: LedgerInfo) -> Result<(), HostError>

pub fn with_ledger_info<F, T>(&self, f: F) -> Result<T, HostError>

where F: FnOnce(&LedgerInfo) -> Result<T, HostError>,

pub fn with_mut_ledger_info<F>(&self, f: F) -> Result<(), HostError>

where F: FnMut(&mut LedgerInfo),

pub fn get_ledger_protocol_version(&self) -> Result<u32, HostError>

pub fn budget_cloned(&self) -> Budget

pub fn charge_budget( &self, ty: ContractCostType, input: Option<u64>, ) -> Result<(), HostError>

pub fn set_shadow_budget_limits( &self, cpu: u64, mem: u64, ) -> Result<(), HostError>

pub fn set_diagnostic_level( &self, diagnostic_level: DiagnosticLevel, ) -> Result<(), HostError>

pub fn enable_debug(&self) -> Result<(), HostError>

pub fn can_finish(&self) -> bool

Returns whether the Host can be finished by calling Host::try_finish.

Returns true if the host reference is unique, refcount = 1.

pub fn try_finish(self) -> Result<(Storage, Events), HostError>

Accept a unique (refcount = 1) host reference and destroy the underlying [HostImpl], returning its finalized components containing processing side effects to the caller as a tuple wrapped in Ok(...).

Use Host::can_finish to determine before calling the function if it will succeed.

impl Host

pub fn set_top_contract_invocation_hook( &self, hook: Option<Rc<dyn for<'a> Fn(&'a Host, ContractInvocationEvent)>>, ) -> Result<(), HostError>

Sets a hook to track top-level contract invocations. The hook triggers right before the top-level contract invocation starts and right after it ends. ‘Top-level contract invocation’ happens when the host creates the first context frame that belongs to a contract, which includes both direct host function calls (call/try_call), and test utilities such as with_test_contract_frame or call_account_contract_check_auth.

pub fn with_budget<T, F>(&self, f: F) -> Result<T, HostError>

where F: FnOnce(Budget) -> Result<T, HostError>,

Helper for mutating the Budget held in this Host, either to allocate it on contract creation or to deplete it on callbacks from the VM or host functions.

pub fn get_contract_instance_live_until_ledger( &self, contract: AddressObject, ) -> Result<u32, HostError>

Returns the ledger number until a contract with given address lives (inclusive).

pub fn get_contract_code_live_until_ledger( &self, contract: AddressObject, ) -> Result<u32, HostError>

Returns the ledger number until contract code entry for contract with given address lives (inclusive).

pub fn get_contract_data_live_until_ledger( &self, key: Val, storage_type: StorageType, ) -> Result<u32, HostError>

Returns the ledger number until a current contract’s data entry with given key and storage type lives (inclusive). Instance storage type is not supported by this function, use get_contract_instance_live_until_ledger instead.

pub fn get_last_invocation_resources(&self) -> Option<InvocationResources>

Returns the resources metered during the last logical contract invocation.

Logical invocations include the direct invoke_host_function calls, call/try_call functions, contract lifecycle management operations.

Take the return value with a grain of salt. The returned resources mostly correspond only to the operations that have happened during the host invocation, i.e. this won’t try to simulate the work that happens in production scenarios (e.g. certain XDR rountrips). This also doesn’t try to model resources related to the transaction size.

The returned value is as useful as the preceding setup, e.g. if a test contract is used instead of a Wasm contract, all the costs related to VM instantiation and execution, as well as Wasm reads/rent bumps will be missed.

impl Host

pub fn get_recorded_auth_payloads( &self, ) -> Result<Vec<RecordedAuthPayload>, HostError>

impl Host

pub fn call_account_contract_check_auth( &self, contract: AddressObject, args: VecObject, ) -> Result<Val, HostError>

Invokes the reserved __check_auth function on a provided contract.

This is useful for testing the custom account contracts. Otherwise, the host prohibits calling __check_auth outside of internal implementation of require_auth[_for_args] calls.

pub fn snapshot_auth_manager(&self) -> Result<AuthorizationManager, HostError>

Returns the current state of the authorization manager.

Use this in conjunction with set_auth_manager to do authorized operations without breaking the current authorization state (useful for preserving the auth state while doing the generic test setup).

pub fn switch_to_recording_auth_inherited_from_snapshot( &self, auth_manager_snapshot: &AuthorizationManager, ) -> Result<(), HostError>

Switches host to the recording authorization mode and inherits the recording mode settings from the provided authorization manager settings in case if it used the recording mode.

This is similar to switch_to_recording_auth, but should be preferred to use in conjunction with snapshot_auth_manager, such that the recording mode settings are not overridden.

pub fn set_auth_manager( &self, auth_manager: AuthorizationManager, ) -> Result<(), HostError>

Replaces authorization manager with the provided new instance.

Use this in conjunction with snapshot_auth_manager to do authorized operations without breaking the current authorization state (useful for preserving the auth state while doing the generic test setup).

pub fn get_authenticated_authorizations( &self, ) -> Result<Vec<(ScAddress, SorobanAuthorizedInvocation)>, HostError>

impl Host

pub const TEST_PRNG_SEED: &'static [u8; 32] = b"12345678901234567890123456789012"

pub fn set_test_prng(&self)

pub fn current_test_protocol() -> u32

pub fn set_test_ledger_info_with_current_test_protocol(&self)

pub fn test_host() -> Self

pub fn test_host_with_prng() -> Self

pub fn test_host_with_recording_footprint() -> Self

pub fn test_budget(self, cpu: u64, mem: u64) -> Self

pub fn enable_model( self, ty: ContractCostType, const_cpu: u64, lin_cpu: u64, const_mem: u64, lin_mem: u64, ) -> Self

pub fn test_scvec<T: AsScVal>(&self, vals: &[T]) -> Result<ScVec, HostError>

pub fn test_vec_obj<T: AsScVal>( &self, vals: &[T], ) -> Result<VecObject, HostError>

pub fn test_vec_val<T: AsScVal>(&self, vals: &[T]) -> Result<Val, HostError>

pub fn test_bin_scobj(&self, vals: &[u8]) -> Result<ScVal, HostError>

pub fn test_bin_obj(&self, vals: &[u8]) -> Result<BytesObject, HostError>

pub fn register_test_contract_wasm_from_source_account( &self, contract_wasm: &[u8], account: AccountId, salt: [u8; 32], ) -> Result<AddressObject, HostError>

pub fn register_test_contract_wasm(&self, contract_wasm: &[u8]) -> AddressObject

pub fn new_recording_fuzz_host( contract_wasms: &[&[u8]], data_keys: &BTreeMap<ScVal, (StorageType, bool)>, n_signers: usize, ) -> (Host, Vec<AddressObject>, Vec<SigningKey>)

pub fn switch_fuzz_host_to_enforcing( &self, data_keys: &BTreeMap<ScVal, (StorageType, bool)>, signing_keys: &[SigningKey], )

Trait Implementations

impl AsBudget for &Host

fn as_budget(&self) -> &Budget

impl AsBudget for Host

fn as_budget(&self) -> &Budget

impl Clone for Host

fn clone(&self) -> Host

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Compare<AccountId> for Host

type Error = HostError

fn compare(&self, a: &AccountId, b: &AccountId) -> Result<Ordering, Self::Error>

impl Compare<ContractDataDurability> for Host

type Error = HostError

fn compare( &self, a: &ContractDataDurability, b: &ContractDataDurability, ) -> Result<Ordering, Self::Error>

impl Compare<ContractExecutable> for Host

type Error = HostError

fn compare( &self, a: &ContractExecutable, b: &ContractExecutable, ) -> Result<Ordering, Self::Error>

impl Compare<CreateContractArgs> for Host

type Error = HostError

fn compare( &self, a: &CreateContractArgs, b: &CreateContractArgs, ) -> Result<Ordering, Self::Error>

impl Compare<CreateContractArgsV2> for Host

type Error = HostError

fn compare( &self, a: &CreateContractArgsV2, b: &CreateContractArgsV2, ) -> Result<Ordering, Self::Error>

impl Compare<Duration> for Host

type Error = HostError

fn compare(&self, a: &Duration, b: &Duration) -> Result<Ordering, Self::Error>

impl Compare<Hash> for Host

type Error = HostError

fn compare(&self, a: &Hash, b: &Hash) -> Result<Ordering, Self::Error>

impl Compare<I256> for Host

type Error = HostError

fn compare(&self, a: &I256, b: &I256) -> Result<Ordering, Self::Error>

impl Compare<Int128Parts> for Host

type Error = HostError

fn compare( &self, a: &Int128Parts, b: &Int128Parts, ) -> Result<Ordering, Self::Error>

impl Compare<Int256Parts> for Host

type Error = HostError

fn compare( &self, a: &Int256Parts, b: &Int256Parts, ) -> Result<Ordering, Self::Error>

impl Compare<LedgerKeyAccount> for Host

type Error = HostError

fn compare( &self, a: &LedgerKeyAccount, b: &LedgerKeyAccount, ) -> Result<Ordering, Self::Error>

impl Compare<LedgerKeyContractCode> for Host

type Error = HostError

fn compare( &self, a: &LedgerKeyContractCode, b: &LedgerKeyContractCode, ) -> Result<Ordering, Self::Error>

impl Compare<LedgerKeyTrustLine> for Host

type Error = HostError

fn compare( &self, a: &LedgerKeyTrustLine, b: &LedgerKeyTrustLine, ) -> Result<Ordering, Self::Error>

impl<K, V> Compare<MeteredOrdMap<K, V, Host>> for Host

where K: DeclaredSizeForMetering, V: DeclaredSizeForMetering, Host: Compare<K, Error = HostError> + Compare<V, Error = HostError>,

type Error = HostError

fn compare( &self, a: &MeteredOrdMap<K, V, Host>, b: &MeteredOrdMap<K, V, Host>, ) -> Result<Ordering, Self::Error>

impl<Elt: MeteredClone> Compare<MeteredVector<Elt>> for Host

where Host: Compare<Elt, Error = HostError>,

type Error = HostError

fn compare( &self, a: &MeteredVector<Elt>, b: &MeteredVector<Elt>, ) -> Result<Ordering, Self::Error>

impl Compare<PublicKey> for Host

type Error = HostError

fn compare(&self, a: &PublicKey, b: &PublicKey) -> Result<Ordering, Self::Error>

impl Compare<ScAddress> for Host

type Error = HostError

fn compare(&self, a: &ScAddress, b: &ScAddress) -> Result<Ordering, Self::Error>

impl Compare<ScError> for Host

type Error = HostError

fn compare(&self, a: &ScError, b: &ScError) -> Result<Ordering, Self::Error>

impl Compare<ScNonceKey> for Host

type Error = HostError

fn compare( &self, a: &ScNonceKey, b: &ScNonceKey, ) -> Result<Ordering, Self::Error>

impl Compare<TimePoint> for Host

type Error = HostError

fn compare(&self, a: &TimePoint, b: &TimePoint) -> Result<Ordering, Self::Error>

impl Compare<TrustLineAsset> for Host

type Error = HostError

fn compare( &self, a: &TrustLineAsset, b: &TrustLineAsset, ) -> Result<Ordering, Self::Error>

impl Compare<U256> for Host

type Error = HostError

fn compare(&self, a: &U256, b: &U256) -> Result<Ordering, Self::Error>

impl Compare<UInt128Parts> for Host

type Error = HostError

fn compare( &self, a: &UInt128Parts, b: &UInt128Parts, ) -> Result<Ordering, Self::Error>

impl Compare<UInt256Parts> for Host

type Error = HostError

fn compare( &self, a: &UInt256Parts, b: &UInt256Parts, ) -> Result<Ordering, Self::Error>

impl Compare<Uint256> for Host

type Error = HostError

fn compare(&self, a: &Uint256, b: &Uint256) -> Result<Ordering, Self::Error>

impl Compare<bool> for Host

type Error = HostError

fn compare(&self, a: &bool, b: &bool) -> Result<Ordering, Self::Error>

impl Compare<i128> for Host

type Error = HostError

fn compare(&self, a: &i128, b: &i128) -> Result<Ordering, Self::Error>

impl Compare<i32> for Host

type Error = HostError

fn compare(&self, a: &i32, b: &i32) -> Result<Ordering, Self::Error>

impl Compare<i64> for Host

type Error = HostError

fn compare(&self, a: &i64, b: &i64) -> Result<Ordering, Self::Error>

impl Compare<u128> for Host

type Error = HostError

fn compare(&self, a: &u128, b: &u128) -> Result<Ordering, Self::Error>

impl Compare<u32> for Host

type Error = HostError

fn compare(&self, a: &u32, b: &u32) -> Result<Ordering, Self::Error>

impl Compare<u64> for Host

type Error = HostError

fn compare(&self, a: &u64, b: &u64) -> Result<Ordering, Self::Error>

impl Convert<&Object, ScValObject> for Host

type Error = HostError

fn convert(&self, ob: &Object) -> Result<ScValObject, Self::Error>

impl<'a> Convert<&ScValObjRef<'a>, Object> for Host

type Error = HostError

fn convert(&self, ob: &ScValObjRef<'a>) -> Result<Object, Self::Error>

impl Convert<Object, ScValObject> for Host

type Error = HostError

fn convert(&self, ob: Object) -> Result<ScValObject, Self::Error>

impl<'a> Convert<ScValObjRef<'a>, Object> for Host

type Error = HostError

fn convert(&self, ob: ScValObjRef<'a>) -> Result<Object, Self::Error>

impl Debug for Host

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Host

fn default() -> Self

Returns the “default value” for a type.

impl EnvBase for Host

type Error = HostError

The type of error returned from the environment when the environment itself fails “unrecoverably”, or at least in a way that the user is not expected to be able to recover from, such as an internal logic error, exceeding the execution budget, or being passed malformed input in a way that the user-facing API does not anticipate or allow for. This type is returned from all environment-interface methods, and will only ever take on two possible concrete types: either Infallible (in the Guest) or HostError (in the Host).

fn error_from_error_val(&self, e: Error) -> Self::Error

Convert a crate::Error into EnvBase::Error. This is similar to adding + From<crate::Error> to the associated type bound for EnvBase::Error but it allows us to restrict that conversion in downstream crates, which is desirable to keep “conversions that panic” (as the guest definition of EnvBase::Error does) out of the common crate and avoid accidentally triggering them in the host. It also gives the Env an opportunity to log or enrich the error with context (both of which happen in Host).

fn check_obj_integrity(&self, obj: Object) -> Result<(), HostError>

Check that an Object handle is good according to the current Env. For general Val-validity checking one should use Val::good().

fn escalate_error_to_panic(&self, e: Self::Error) -> !

Reject an error from the environment, turning it into a panic but on terms that the environment controls (eg. enriching or logging it). This should only ever be called by client-side / SDK local-testing code, never in the Host.

fn augment_err_result<T>( &self, x: Result<T, Self::Error>, ) -> Result<T, Self::Error>

If x is Err(...), ensure as much debug information as possible is attached to that error; in any case return “essentially the same” x – either Ok(...) or Err(...) – just with extra error context.

fn tracing_enabled(&self) -> bool

Return true if the environment wants to receive trace calls and and returns using Self::trace_env_call and Self::trace_env_ret.

fn trace_env_call( &self, fname: &'static str, args: &[&dyn Debug], ) -> Result<(), HostError>

A general interface for tracing all env-method calls, intended to be called from macros that do dispatch on all such methods.

fn trace_env_ret( &self, fname: &'static str, res: &Result<&dyn Debug, &HostError>, ) -> Result<(), HostError>

A general interface for tracing all env-method returns, intended to be called from macros that do dispatch on all such methods.

fn check_same_env(&self, other: &Self) -> Result<(), Self::Error>

Used to check two environments are the same, returning Error if not.

fn bytes_copy_from_slice( &self, b: BytesObject, b_pos: U32Val, slice: &[u8], ) -> Result<BytesObject, HostError>

Clone an existing Bytes object in the host, replacing the portion of its memory with bytes supplied by slice, returning the new object. The replaced portion of the original object’s memory begins at b_pos and extends for the same length as the new slice.

fn bytes_copy_to_slice( &self, b: BytesObject, b_pos: U32Val, slice: &mut [u8], ) -> Result<(), HostError>

Copy a slice of bytes from a Bytes object in the host into a slice in the caller’s memory.

fn string_copy_to_slice( &self, b: StringObject, b_pos: U32Val, slice: &mut [u8], ) -> Result<(), HostError>

Copy a slice of bytes from a String object in the host into a slice in the caller’s memory.

fn symbol_copy_to_slice( &self, s: SymbolObject, b_pos: U32Val, slice: &mut [u8], ) -> Result<(), HostError>

Copy a slice of bytes from a Symbol object in the host into the caller’s memory.

fn bytes_new_from_slice(&self, mem: &[u8]) -> Result<BytesObject, HostError>

Form a new Bytes host object from a slice of client memory.

fn string_new_from_slice(&self, s: &[u8]) -> Result<StringObject, HostError>

Form a new String host object from a slice of client memory.

fn symbol_new_from_slice(&self, s: &[u8]) -> Result<SymbolObject, HostError>

Form a new Symbol host object from a slice of client memory.

fn map_new_from_slices( &self, keys: &[&str], vals: &[Val], ) -> Result<MapObject, HostError>

Form a new Map host object from a slice of symbol-names and a slice of values. Keys must be in sorted order.

fn map_unpack_to_slice( &self, map: MapObject, keys: &[&str], vals: &mut [Val], ) -> Result<Void, HostError>

Unpack a Map host object with a specified set of keys to a slice of Vals. Keys must be in sorted order and must match the key set of the unpacked object exactly.

fn vec_new_from_slice(&self, vals: &[Val]) -> Result<VecObject, Self::Error>

Form a new Vec host object from a slice of values.

fn vec_unpack_to_slice( &self, vec: VecObject, vals: &mut [Val], ) -> Result<Void, Self::Error>

Form a new Vec host object from a slice of values. The values slice must be the same length as the host object.

fn symbol_index_in_strs( &self, sym: Symbol, slices: &[&str], ) -> Result<U32Val, Self::Error>

Return the index of a Symbol in an array of &strs, or error if not found.

fn log_from_slice(&self, msg: &str, vals: &[Val]) -> Result<Void, HostError>

Log a string and set of values as a diagnostic event, if diagnostic events are enabled. When running on host, logs directly; when running on guest, redirects through log_from_linear_memory.

fn check_protocol_version_lower_bound( &self, lower: u32, ) -> Result<(), Self::Error>

Check the current ledger protocol version against a provided lower bound, error if protocol version is out-of-bound.

fn check_protocol_version_upper_bound( &self, upper: u32, ) -> Result<(), Self::Error>

Check the current ledger protocol version against a provided upper bound, error if protocol version is out-of-bound.

fn check_val_integrity(&self, val: Val) -> Result<(), Self::Error>

Check that a Val is good according to the current Env. This is a superset of calling Val::good as it also checks that if the Val is an Object, that the Object is good according to Self::check_obj_integrity.

fn env_call_hook( &self, _fname: &'static str, _args: &[String], ) -> Result<(), Self::Error>

👎Deprecated: replaced by trace_env_call

fn env_ret_hook( &self, _fname: &'static str, _res: &Result<String, &Self::Error>, ) -> Result<(), Self::Error>

👎Deprecated: replaced by trace_env_ret

impl ResourceLimiter for Host

fn memory_growing( &mut self, current: usize, desired: usize, maximum: Option<usize>, ) -> Result<bool, MemoryError>

Notifies the resource limiter that an instance’s linear memory has been requested to grow.

fn table_growing( &mut self, current: u32, desired: u32, maximum: Option<u32>, ) -> Result<bool, TableError>

Notifies the resource limiter that an instance’s table has been requested to grow.

fn instances(&self) -> usize

The maximum number of instances that can be created for a Store.

fn tables(&self) -> usize

The maximum number of tables that can be created for a Store.

fn memories(&self) -> usize

The maximum number of linear memories that can be created for a Store

fn memory_grow_failed(&mut self, _error: &MemoryError)

Notifies the resource limiter that growing a linear memory, permitted by the memory_growing method, has failed.

fn table_grow_failed(&mut self, _error: &TableError)

Notifies the resource limiter that growing a linear memory, permitted by the table_growing method, has failed.

impl VmCallerEnv for Host

type VmUserState = Host

fn log_from_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, msg_pos: U32Val, msg_len: U32Val, vals_pos: U32Val, vals_len: U32Val, ) -> Result<Void, HostError>

Emit a diagnostic event containing a message and sequence of Vals.

fn obj_cmp( &self, _vmcaller: &mut VmCaller<'_, Host>, a: Val, b: Val, ) -> Result<i64, HostError>

Compare two objects, or at least one object to a non-object, structurally. Returns -1 if a<b, 1 if a>b, or 0 if a==b.

fn contract_event( &self, _vmcaller: &mut VmCaller<'_, Host>, topics: VecObject, data: Val, ) -> Result<Void, HostError>

Records a contract event. topics is expected to be a SCVec with length <= 4 that cannot contain Vec, Map, or Bytes with length > 32.

fn get_ledger_version( &self, _vmcaller: &mut VmCaller<'_, Host>, ) -> Result<U32Val, Self::Error>

Return the protocol version of the current ledger as a u32.

fn get_ledger_sequence( &self, _vmcaller: &mut VmCaller<'_, Host>, ) -> Result<U32Val, Self::Error>

Return the sequence number of the current ledger as a u32.

fn get_ledger_timestamp( &self, _vmcaller: &mut VmCaller<'_, Host>, ) -> Result<U64Val, Self::Error>

Return the timestamp number of the current ledger as a u64.

fn fail_with_error( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, error: Error, ) -> Result<Void, Self::Error>

Causes the currently executing contract to fail immediately with a provided error code, which must be of error-type ScErrorType::Contract. Does not actually return.

fn get_ledger_network_id( &self, _vmcaller: &mut VmCaller<'_, Host>, ) -> Result<BytesObject, Self::Error>

Return the network id (sha256 hash of network passphrase) of the current ledger as Bytes. The value is always 32 bytes in length.

fn get_current_contract_address( &self, _vmcaller: &mut VmCaller<'_, Host>, ) -> Result<AddressObject, HostError>

Get the Address object for the current contract.

fn get_max_live_until_ledger( &self, _vmcaller: &mut VmCaller<'_, Host>, ) -> Result<U32Val, Self::Error>

Returns the max ledger sequence that an entry can live to (inclusive).

fn obj_from_u64( &self, _vmcaller: &mut VmCaller<'_, Host>, u: u64, ) -> Result<U64Object, HostError>

Convert a u64 to an object containing a u64.

fn obj_to_u64( &self, _vmcaller: &mut VmCaller<'_, Host>, obj: U64Object, ) -> Result<u64, HostError>

Convert an object containing a u64 to a u64.

fn obj_from_i64( &self, _vmcaller: &mut VmCaller<'_, Host>, u: i64, ) -> Result<I64Object, HostError>

Convert an i64 to an object containing an i64.

fn obj_to_i64( &self, _vmcaller: &mut VmCaller<'_, Host>, obj: I64Object, ) -> Result<i64, HostError>

Convert an object containing an i64 to an i64.

fn timepoint_obj_from_u64( &self, _vmcaller: &mut VmCaller<'_, Host>, u: u64, ) -> Result<TimepointObject, HostError>

Convert a u64 to a Timepoint object.

fn timepoint_obj_to_u64( &self, _vmcaller: &mut VmCaller<'_, Host>, obj: TimepointObject, ) -> Result<u64, HostError>

Convert a Timepoint object to a u64.

fn duration_obj_from_u64( &self, _vmcaller: &mut VmCaller<'_, Host>, u: u64, ) -> Result<DurationObject, HostError>

Convert a u64 to a Duration object.

fn duration_obj_to_u64( &self, _vmcaller: &mut VmCaller<'_, Host>, obj: DurationObject, ) -> Result<u64, HostError>

Convert a Duration object a u64.

fn obj_from_u128_pieces( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, hi: u64, lo: u64, ) -> Result<U128Object, Self::Error>

Convert the high and low 64-bit words of a u128 to an object containing a u128.

fn obj_to_u128_lo64( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, obj: U128Object, ) -> Result<u64, Self::Error>

Extract the low 64 bits from an object containing a u128.

fn obj_to_u128_hi64( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, obj: U128Object, ) -> Result<u64, Self::Error>

Extract the high 64 bits from an object containing a u128.

fn obj_from_i128_pieces( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, hi: i64, lo: u64, ) -> Result<I128Object, Self::Error>

Convert the high and low 64-bit words of an i128 to an object containing an i128.

fn obj_to_i128_lo64( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, obj: I128Object, ) -> Result<u64, Self::Error>

Extract the low 64 bits from an object containing an i128.

fn obj_to_i128_hi64( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, obj: I128Object, ) -> Result<i64, Self::Error>

Extract the high 64 bits from an object containing an i128.

fn obj_from_u256_pieces( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, hi_hi: u64, hi_lo: u64, lo_hi: u64, lo_lo: u64, ) -> Result<U256Object, Self::Error>

Convert the four 64-bit words of a u256 (big-endian) to an object containing a u256.

fn u256_val_from_be_bytes( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, bytes: BytesObject, ) -> Result<U256Val, HostError>

Create a U256 Val from its representation as a byte array in big endian.

fn u256_val_to_be_bytes( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, val: U256Val, ) -> Result<BytesObject, HostError>

Return the memory representation of this U256 Val as a byte array in big endian byte order.

fn obj_to_u256_hi_hi( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, obj: U256Object, ) -> Result<u64, HostError>

Extract the highest 64-bits (bits 192-255) from an object containing a u256.

fn obj_to_u256_hi_lo( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, obj: U256Object, ) -> Result<u64, HostError>

Extract bits 128-191 from an object containing a u256.

fn obj_to_u256_lo_hi( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, obj: U256Object, ) -> Result<u64, HostError>

Extract bits 64-127 from an object containing a u256.

fn obj_to_u256_lo_lo( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, obj: U256Object, ) -> Result<u64, HostError>

Extract the lowest 64-bits (bits 0-63) from an object containing a u256.

fn obj_from_i256_pieces( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, hi_hi: i64, hi_lo: u64, lo_hi: u64, lo_lo: u64, ) -> Result<I256Object, Self::Error>

Convert the four 64-bit words of an i256 (big-endian) to an object containing an i256.

fn i256_val_from_be_bytes( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, bytes: BytesObject, ) -> Result<I256Val, HostError>

Create a I256 Val from its representation as a byte array in big endian.

fn i256_val_to_be_bytes( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, val: I256Val, ) -> Result<BytesObject, HostError>

Return the memory representation of this I256 Val as a byte array in big endian byte order.

fn obj_to_i256_hi_hi( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, obj: I256Object, ) -> Result<i64, HostError>

Extract the highest 64-bits (bits 192-255) from an object containing an i256.

fn obj_to_i256_hi_lo( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, obj: I256Object, ) -> Result<u64, HostError>

Extract bits 128-191 from an object containing an i256.

fn obj_to_i256_lo_hi( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, obj: I256Object, ) -> Result<u64, HostError>

Extract bits 64-127 from an object containing an i256.

fn obj_to_i256_lo_lo( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, obj: I256Object, ) -> Result<u64, HostError>

Extract the lowest 64-bits (bits 0-63) from an object containing an i256.

fn u256_add( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: U256Val, rhs_val: U256Val, ) -> Result<U256Val, Self::Error>

Performs checked integer addition. Computes lhs + rhs, returning ScError if overflow occurred.

fn u256_sub( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: U256Val, rhs_val: U256Val, ) -> Result<U256Val, Self::Error>

Performs checked integer subtraction. Computes lhs - rhs, returning ScError if overflow occurred.

fn u256_mul( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: U256Val, rhs_val: U256Val, ) -> Result<U256Val, Self::Error>

Performs checked integer multiplication. Computes lhs * rhs, returning ScError if overflow occurred.

fn u256_div( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: U256Val, rhs_val: U256Val, ) -> Result<U256Val, Self::Error>

Performs checked integer division. Computes lhs / rhs, returning ScError if rhs == 0 or overflow occurred.

fn u256_rem_euclid( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: U256Val, rhs_val: U256Val, ) -> Result<U256Val, Self::Error>

Performs checked Euclidean modulo. Computes lhs % rhs, returning ScError if rhs == 0 or overflow occurred.

fn u256_pow( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: U256Val, rhs_val: U32Val, ) -> Result<U256Val, Self::Error>

Performs checked exponentiation. Computes lhs.exp(rhs), returning ScError if overflow occurred.

fn u256_shl( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: U256Val, rhs_val: U32Val, ) -> Result<U256Val, Self::Error>

Performs checked shift left. Computes lhs << rhs, returning ScError if rhs is larger than or equal to the number of bits in lhs.

fn u256_shr( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: U256Val, rhs_val: U32Val, ) -> Result<U256Val, Self::Error>

Performs checked shift right. Computes lhs >> rhs, returning ScError if rhs is larger than or equal to the number of bits in lhs.

fn i256_add( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: I256Val, rhs_val: I256Val, ) -> Result<I256Val, Self::Error>

Performs checked integer addition. Computes lhs + rhs, returning ScError if overflow occurred.

fn i256_sub( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: I256Val, rhs_val: I256Val, ) -> Result<I256Val, Self::Error>

Performs checked integer subtraction. Computes lhs - rhs, returning ScError if overflow occurred.

fn i256_mul( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: I256Val, rhs_val: I256Val, ) -> Result<I256Val, Self::Error>

Performs checked integer multiplication. Computes lhs * rhs, returning ScError if overflow occurred.

fn i256_div( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: I256Val, rhs_val: I256Val, ) -> Result<I256Val, Self::Error>

Performs checked integer division. Computes lhs / rhs, returning ScError if rhs == 0 or overflow occurred.

fn i256_rem_euclid( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: I256Val, rhs_val: I256Val, ) -> Result<I256Val, Self::Error>

Performs checked Euclidean modulo. Computes lhs % rhs, returning ScError if rhs == 0 or overflow occurred.

fn i256_pow( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: I256Val, rhs_val: U32Val, ) -> Result<I256Val, Self::Error>

Performs checked exponentiation. Computes lhs.exp(rhs), returning ScError if overflow occurred.

fn i256_shl( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: I256Val, rhs_val: U32Val, ) -> Result<I256Val, Self::Error>

Performs checked shift left. Computes lhs << rhs, returning ScError if rhs is larger than or equal to the number of bits in lhs.

fn i256_shr( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs_val: I256Val, rhs_val: U32Val, ) -> Result<I256Val, Self::Error>

Performs checked shift right. Computes lhs >> rhs, returning ScError if rhs is larger than or equal to the number of bits in lhs.

fn map_new( &self, _vmcaller: &mut VmCaller<'_, Host>, ) -> Result<MapObject, HostError>

Create an empty new map.

fn map_put( &self, _vmcaller: &mut VmCaller<'_, Host>, m: MapObject, k: Val, v: Val, ) -> Result<MapObject, HostError>

Insert a key/value mapping into an existing map, and return the map object handle. If the map already has a mapping for the given key, the previous value is overwritten.

fn map_get( &self, _vmcaller: &mut VmCaller<'_, Host>, m: MapObject, k: Val, ) -> Result<Val, HostError>

Get the value for a key from a map. Traps if key is not found.

fn map_del( &self, _vmcaller: &mut VmCaller<'_, Host>, m: MapObject, k: Val, ) -> Result<MapObject, HostError>

Remove a key/value mapping from a map if it exists, traps if doesn’t.

fn map_len( &self, _vmcaller: &mut VmCaller<'_, Host>, m: MapObject, ) -> Result<U32Val, HostError>

Get the size of a map.

fn map_has( &self, _vmcaller: &mut VmCaller<'_, Host>, m: MapObject, k: Val, ) -> Result<Bool, HostError>

Test for the presence of a key in a map. Returns Bool.

fn map_key_by_pos( &self, _vmcaller: &mut VmCaller<'_, Host>, m: MapObject, i: U32Val, ) -> Result<Val, HostError>

Get the key from a map at position i. If i is an invalid position, return ScError.

fn map_val_by_pos( &self, _vmcaller: &mut VmCaller<'_, Host>, m: MapObject, i: U32Val, ) -> Result<Val, HostError>

Get the value from a map at position i. If i is an invalid position, return ScError.

fn map_keys( &self, _vmcaller: &mut VmCaller<'_, Host>, m: MapObject, ) -> Result<VecObject, HostError>

Return a new vector containing all the keys in a map. The new vector is ordered in the original map’s key-sorted order.

fn map_values( &self, _vmcaller: &mut VmCaller<'_, Host>, m: MapObject, ) -> Result<VecObject, HostError>

Return a new vector containing all the values in a map. The new vector is ordered in the original map’s key-sorted order.

fn map_new_from_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, keys_pos: U32Val, vals_pos: U32Val, len: U32Val, ) -> Result<MapObject, HostError>

Return a new map initialized from a pair of equal-length arrays, one for keys and one for values, given by a pair of linear-memory addresses and a length in Vals.

fn map_unpack_to_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, map: MapObject, keys_pos: U32Val, vals_pos: U32Val, len: U32Val, ) -> Result<Void, HostError>

Copy Vals from map to the array vals_pos, selecting only the keys identified by the array keys_pos. Both arrays have len elements and are identified by linear-memory addresses.

fn vec_new( &self, _vmcaller: &mut VmCaller<'_, Host>, ) -> Result<VecObject, HostError>

Creates an empty new vector.

fn vec_put( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, i: U32Val, x: Val, ) -> Result<VecObject, HostError>

Update the value at index i in the vector. Return the new vector. Trap if the index is out of bounds.

fn vec_get( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, i: U32Val, ) -> Result<Val, HostError>

Returns the element at index i of the vector. Traps if the index is out of bound.

fn vec_del( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, i: U32Val, ) -> Result<VecObject, HostError>

Delete an element in a vector at index i, shifting all elements after it to the left. Return the new vector. Traps if the index is out of bound.

fn vec_len( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, ) -> Result<U32Val, HostError>

Returns length of the vector.

fn vec_push_front( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, x: Val, ) -> Result<VecObject, HostError>

Push a value to the front of a vector.

fn vec_pop_front( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, ) -> Result<VecObject, HostError>

Removes the first element from the vector and returns the new vector. Traps if original vector is empty.

fn vec_push_back( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, x: Val, ) -> Result<VecObject, HostError>

Appends an element to the back of the vector.

fn vec_pop_back( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, ) -> Result<VecObject, HostError>

Removes the last element from the vector and returns the new vector. Traps if original vector is empty.

fn vec_front( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, ) -> Result<Val, HostError>

Return the first element in the vector. Traps if the vector is empty

fn vec_back( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, ) -> Result<Val, HostError>

Return the last element in the vector. Traps if the vector is empty

fn vec_insert( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, i: U32Val, x: Val, ) -> Result<VecObject, HostError>

Inserts an element at index i within the vector, shifting all elements after it to the right. Traps if the index is out of bound

fn vec_append( &self, _vmcaller: &mut VmCaller<'_, Host>, v1: VecObject, v2: VecObject, ) -> Result<VecObject, HostError>

Clone the vector v1, then moves all the elements of vector v2 into it. Return the new vector. Traps if number of elements in the vector overflows a u32.

fn vec_slice( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, start: U32Val, end: U32Val, ) -> Result<VecObject, HostError>

Copy the elements from start index until end index, exclusive, in the vector and create a new vector from it. Return the new vector. Traps if the index is out of bound.

fn vec_first_index_of( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, x: Val, ) -> Result<Val, Self::Error>

Get the index of the first occurrence of a given element in the vector. Returns the u32 index of the value if it’s there. Otherwise, it returns Void.

fn vec_last_index_of( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, x: Val, ) -> Result<Val, Self::Error>

Get the index of the last occurrence of a given element in the vector. Returns the u32 index of the value if it’s there. Otherwise, it returns Void.

fn vec_binary_search( &self, _vmcaller: &mut VmCaller<'_, Host>, v: VecObject, x: Val, ) -> Result<u64, Self::Error>

Binary search a sorted vector for a given element. If it exists, the high 32 bits of the return value is 0x0000_0001 and the low 32 bits contain the u32 index of the element. If it does not exist, the high 32 bits of the return value is 0x0000_0000 and the low-32 bits contain the u32 index at which the element would need to be inserted into the vector to maintain sorted order.

fn vec_new_from_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, vals_pos: U32Val, len: U32Val, ) -> Result<VecObject, HostError>

Return a new vec initialized from an input slice of Vals given by a linear-memory address and length in Vals.

fn vec_unpack_to_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, vec: VecObject, vals_pos: U32Val, len: U32Val, ) -> Result<Void, HostError>

Copy the Vals of a vec into an array at a given linear-memory address and length in Vals.

fn put_contract_data( &self, _vmcaller: &mut VmCaller<'_, Host>, k: Val, v: Val, t: StorageType, ) -> Result<Void, HostError>

fn has_contract_data( &self, _vmcaller: &mut VmCaller<'_, Host>, k: Val, t: StorageType, ) -> Result<Bool, HostError>

fn get_contract_data( &self, _vmcaller: &mut VmCaller<'_, Host>, k: Val, t: StorageType, ) -> Result<Val, HostError>

fn del_contract_data( &self, _vmcaller: &mut VmCaller<'_, Host>, k: Val, t: StorageType, ) -> Result<Void, HostError>

fn extend_contract_data_ttl( &self, _vmcaller: &mut VmCaller<'_, Host>, k: Val, t: StorageType, threshold: U32Val, extend_to: U32Val, ) -> Result<Void, HostError>

If the entry’s TTL is below threshold ledgers, extend live_until_ledger_seq such that TTL == extend_to, where TTL is defined as live_until_ledger_seq - current ledger. If attempting to extend the entry past the maximum allowed value (defined as the current ledger + max_entry_ttl - 1), and the entry is Persistent, its new live_until_ledger_seq will be clamped to the max; if the entry is Temporary, the function traps.

fn extend_current_contract_instance_and_code_ttl( &self, _vmcaller: &mut VmCaller<'_, Host>, threshold: U32Val, extend_to: U32Val, ) -> Result<Void, HostError>

If the TTL for the current contract instance and code (if applicable) is below threshold ledgers, extend live_until_ledger_seq such that TTL == extend_to, where TTL is defined as live_until_ledger_seq - current ledger. If attempting to extend past the maximum allowed value (defined as the current ledger + max_entry_ttl - 1), the new live_until_ledger_seq will be clamped to the max.

fn extend_contract_instance_ttl( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, contract: AddressObject, threshold: U32Val, extend_to: U32Val, ) -> Result<Void, Self::Error>

If the TTL for the provided contract instance is below threshold ledgers, extend live_until_ledger_seq such that TTL == extend_to, where TTL is defined as live_until_ledger_seq - current ledger. If attempting to extend past the maximum allowed value (defined as the current ledger + max_entry_ttl - 1), the new live_until_ledger_seq will be clamped to the max.

fn extend_contract_instance_and_code_ttl( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, contract: AddressObject, threshold: U32Val, extend_to: U32Val, ) -> Result<Void, Self::Error>

If the TTL for the provided contract instance and code (if applicable) is below threshold ledgers, extend live_until_ledger_seq such that TTL == extend_to, where TTL is defined as live_until_ledger_seq - current ledger. If attempting to extend past the maximum allowed value (defined as the current ledger + max_entry_ttl - 1), the new live_until_ledger_seq will be clamped to the max.

fn extend_contract_code_ttl( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, contract: AddressObject, threshold: U32Val, extend_to: U32Val, ) -> Result<Void, Self::Error>

If the TTL for the provided contract’s code (if applicable) is below threshold ledgers, extend live_until_ledger_seq such that TTL == extend_to, where TTL is defined as live_until_ledger_seq - current ledger. If attempting to extend past the maximum allowed value (defined as the current ledger + max_entry_ttl - 1), the new live_until_ledger_seq will be clamped to the max.

fn create_contract( &self, _vmcaller: &mut VmCaller<'_, Host>, deployer: AddressObject, wasm_hash: BytesObject, salt: BytesObject, ) -> Result<AddressObject, HostError>

Creates the contract instance on behalf of deployer. deployer must authorize this call via Soroban auth framework, i.e. this calls deployer.require_auth with respective arguments. wasm_hash must be a hash of the contract code that has already been uploaded on this network. salt is used to create a unique contract id. Returns the address of the created contract.

fn create_contract_with_constructor( &self, _vmcaller: &mut VmCaller<'_, Host>, deployer: AddressObject, wasm_hash: BytesObject, salt: BytesObject, constructor_args: VecObject, ) -> Result<AddressObject, HostError>

Creates the contract instance on behalf of deployer. Created contract must be created from a Wasm that has a constructor. deployer must authorize this call via Soroban auth framework, i.e. this calls deployer.require_auth with respective arguments. wasm_hash must be a hash of the contract code that has already been uploaded on this network. salt is used to create a unique contract id. constructor_args are forwarded into created contract’s constructor (__constructor) function. Returns the address of the created contract.

fn create_asset_contract( &self, _vmcaller: &mut VmCaller<'_, Host>, serialized_asset: BytesObject, ) -> Result<AddressObject, HostError>

Creates the instance of Stellar Asset contract corresponding to the provided asset. serialized_asset is stellar::Asset XDR serialized to bytes format. Returns the address of the created contract.

fn get_contract_id( &self, _vmcaller: &mut VmCaller<'_, Host>, deployer: AddressObject, salt: BytesObject, ) -> Result<AddressObject, HostError>

Get the id of a contract without creating it. deployer is address of the contract deployer. salt is used to create a unique contract id. Returns the address of the would-be contract.

fn get_asset_contract_id( &self, _vmcaller: &mut VmCaller<'_, Host>, serialized_asset: BytesObject, ) -> Result<AddressObject, HostError>

Get the id of the Stellar Asset contract corresponding to the provided asset without creating the instance. serialized_asset is stellar::Asset XDR serialized to bytes format. Returns the address of the would-be asset contract.

fn upload_wasm( &self, _vmcaller: &mut VmCaller<'_, Host>, wasm: BytesObject, ) -> Result<BytesObject, HostError>

Uploads provided wasm bytecode to the network and returns its identifier (SHA-256 hash). No-op in case if the same Wasm object already exists.

fn update_current_contract_wasm( &self, _vmcaller: &mut VmCaller<'_, Host>, hash: BytesObject, ) -> Result<Void, HostError>

Replaces the executable of the current contract with the provided Wasm code identified by a hash. Wasm entry corresponding to the hash has to already be present in the ledger. The update happens only after the current contract invocation has successfully finished, so this can be safely called in the middle of a function.

fn call( &self, _vmcaller: &mut VmCaller<'_, Host>, contract_address: AddressObject, func: Symbol, args: VecObject, ) -> Result<Val, HostError>

Calls a function in another contract with arguments contained in vector args. If the call is successful, returns the result of the called function. Traps otherwise.

fn try_call( &self, _vmcaller: &mut VmCaller<'_, Host>, contract_address: AddressObject, func: Symbol, args: VecObject, ) -> Result<Val, HostError>

Calls a function in another contract with arguments contained in vector args, returning either the result of the called function or an Error if the called function failed. The returned error is either a custom ContractError that the called contract returns explicitly, or an error with type Context and code InvalidAction in case of any other error in the called contract (such as a host function failure that caused a trap). try_call might trap in a few scenarios where the error can’t be meaningfully recovered from, such as running out of budget.

fn serialize_to_bytes( &self, _vmcaller: &mut VmCaller<'_, Host>, v: Val, ) -> Result<BytesObject, HostError>

Serializes an (SC)Val into XDR opaque Bytes object.

fn deserialize_from_bytes( &self, _vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, ) -> Result<Val, HostError>

Deserialize a Bytes object to get back the (SC)Val.

fn string_copy_to_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, s: StringObject, s_pos: U32Val, lm_pos: U32Val, len: U32Val, ) -> Result<Void, HostError>

Copies a slice of bytes from a String object specified at offset s_pos with length len into the linear memory at position lm_pos. Traps if either the String object or the linear memory doesn’t have enough bytes.

fn symbol_copy_to_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, s: SymbolObject, s_pos: U32Val, lm_pos: U32Val, len: U32Val, ) -> Result<Void, HostError>

Copies a slice of bytes from a Symbol object specified at offset s_pos with length len into the linear memory at position lm_pos. Traps if either the String object or the linear memory doesn’t have enough bytes.

fn bytes_copy_to_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, b_pos: U32Val, lm_pos: U32Val, len: U32Val, ) -> Result<Void, HostError>

Copies a slice of bytes from a Bytes object specified at offset b_pos with length len into the linear memory at position lm_pos. Traps if either the Bytes object or the linear memory doesn’t have enough bytes.

fn bytes_copy_from_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, b_pos: U32Val, lm_pos: U32Val, len: U32Val, ) -> Result<BytesObject, HostError>

Copies a segment of the linear memory specified at position lm_pos with length len, into a Bytes object at offset b_pos. The Bytes object may grow in size to accommodate the new bytes. Traps if the linear memory doesn’t have enough bytes.

fn bytes_new_from_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, lm_pos: U32Val, len: U32Val, ) -> Result<BytesObject, HostError>

Constructs a new Bytes object initialized with bytes copied from a linear memory slice specified at position lm_pos with length len.

fn string_new_from_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, lm_pos: U32Val, len: U32Val, ) -> Result<StringObject, HostError>

Constructs a new String object initialized with bytes copied from a linear memory slice specified at position lm_pos with length len.

fn symbol_new_from_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, lm_pos: U32Val, len: U32Val, ) -> Result<SymbolObject, HostError>

Constructs a new Symbol object initialized with bytes copied from a linear memory slice specified at position lm_pos with length len.

fn symbol_index_in_linear_memory( &self, vmcaller: &mut VmCaller<'_, Host>, sym: Symbol, lm_pos: U32Val, len: U32Val, ) -> Result<U32Val, HostError>

Return the index of a Symbol in an array of linear-memory byte-slices, or trap if not found.

fn bytes_new( &self, _vmcaller: &mut VmCaller<'_, Host>, ) -> Result<BytesObject, HostError>

Create an empty new Bytes object.

fn bytes_put( &self, _vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, iv: U32Val, u: U32Val, ) -> Result<BytesObject, HostError>

Update the value at index i in the Bytes object. Return the new Bytes. Trap if the index is out of bounds.

fn bytes_get( &self, _vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, iv: U32Val, ) -> Result<U32Val, HostError>

Returns the element at index i of the Bytes object. Traps if the index is out of bound.

fn bytes_del( &self, _vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, i: U32Val, ) -> Result<BytesObject, HostError>

Delete an element in a Bytes object at index i, shifting all elements after it to the left. Return the new Bytes. Traps if the index is out of bound.

fn bytes_len( &self, _vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, ) -> Result<U32Val, HostError>

Returns length of the Bytes object.

fn string_len( &self, _vmcaller: &mut VmCaller<'_, Host>, b: StringObject, ) -> Result<U32Val, HostError>

Returns length of the String object.

fn symbol_len( &self, _vmcaller: &mut VmCaller<'_, Host>, b: SymbolObject, ) -> Result<U32Val, HostError>

Returns length of the Symbol object.

fn bytes_push( &self, _vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, u: U32Val, ) -> Result<BytesObject, HostError>

Appends an element to the back of the Bytes object.

fn bytes_pop( &self, _vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, ) -> Result<BytesObject, HostError>

Removes the last element from the Bytes object and returns the new Bytes. Traps if original Bytes is empty.

fn bytes_front( &self, _vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, ) -> Result<U32Val, HostError>

Return the first element in the Bytes object. Traps if the Bytes is empty

fn bytes_back( &self, _vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, ) -> Result<U32Val, HostError>

Return the last element in the Bytes object. Traps if the Bytes is empty

fn bytes_insert( &self, _vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, i: U32Val, u: U32Val, ) -> Result<BytesObject, HostError>

Inserts an element at index i within the Bytes object, shifting all elements after it to the right. Traps if the index is out of bound

fn bytes_append( &self, _vmcaller: &mut VmCaller<'_, Host>, b1: BytesObject, b2: BytesObject, ) -> Result<BytesObject, HostError>

Clone the Bytes object b1, then moves all the elements of Bytes object b2 into it. Return the new Bytes. Traps if its length overflows a u32.

fn bytes_slice( &self, _vmcaller: &mut VmCaller<'_, Host>, b: BytesObject, start: U32Val, end: U32Val, ) -> Result<BytesObject, HostError>

Copies the elements from start index until end index, exclusive, in the Bytes object and creates a new Bytes from it. Returns the new Bytes. Traps if the index is out of bound.

fn compute_hash_sha256( &self, _vmcaller: &mut VmCaller<'_, Host>, x: BytesObject, ) -> Result<BytesObject, HostError>

fn compute_hash_keccak256( &self, _vmcaller: &mut VmCaller<'_, Host>, x: BytesObject, ) -> Result<BytesObject, HostError>

Returns the keccak256 hash of given input bytes.

fn verify_sig_ed25519( &self, _vmcaller: &mut VmCaller<'_, Host>, k: BytesObject, x: BytesObject, s: BytesObject, ) -> Result<Void, HostError>

fn recover_key_ecdsa_secp256k1( &self, _vmcaller: &mut VmCaller<'_, Host>, msg_digest: BytesObject, signature: BytesObject, recovery_id: U32Val, ) -> Result<BytesObject, HostError>

Recovers the SEC-1-encoded ECDSA secp256k1 public key that produced a given 64-byte signature over a given 32-byte msg_digest for a given recovery_id byte. Warning: The msg_digest must be produced by a secure cryptographic hash function on the message, otherwise the attacker can potentially forge signatures. The signature is the ECDSA signature (r, s) serialized as fixed-size big endian scalar values, both r, s must be non-zero and s must be in the lower range. Returns a BytesObject containing 65-bytes representing SEC-1 encoded point in uncompressed format. The recovery_id is an integer value 0, 1, 2, or 3, the low bit (0/1) indicates the parity of the y-coordinate of the public_key (even/odd) and the high bit (3/4) indicate if the r (x-coordinate of k x G) has overflown during its computation.

fn verify_sig_ecdsa_secp256r1( &self, _vmcaller: &mut VmCaller<'_, Host>, public_key: BytesObject, msg_digest: BytesObject, signature: BytesObject, ) -> Result<Void, HostError>

Verifies the signature using an ECDSA secp256r1 public_key on a 32-byte msg_digest. Warning: The msg_digest must be produced by a secure cryptographic hash function on the message, otherwise the attacker can potentially forge signatures. The public_key is expected to be 65 bytes in length, representing a SEC-1 encoded point in uncompressed format. The signature is the ECDSA signature (r, s) serialized as fixed-size big endian scalar values, both r, s must be non-zero and s must be in the lower range.

fn bls12_381_check_g1_is_in_subgroup( &self, _vmcaller: &mut VmCaller<'_, Host>, pt: BytesObject, ) -> Result<Bool, HostError>

Checks if the input G1 point is in the correct subgroup.

fn bls12_381_g1_add( &self, _vmcaller: &mut VmCaller<'_, Host>, p0: BytesObject, p1: BytesObject, ) -> Result<BytesObject, HostError>

Adds two BLS12-381 G1 points given in bytes format and returns the resulting G1 point in bytes format. G1 serialization format: concat(be_bytes(X), be_bytes(Y)) and the most significant three bits of X encodes flags, i.e. bits(X) = [compression_flag, infinity_flag, sort_flag, bit_3, .. bit_383]. This function does NOT perform subgroup check on the inputs.

fn bls12_381_g1_mul( &self, _vmcaller: &mut VmCaller<'_, Host>, p0: BytesObject, scalar: U256Val, ) -> Result<BytesObject, HostError>

Multiplies a BLS12-381 G1 point by a scalar (Fr), and returns the resulting G1 point in bytes format.

fn bls12_381_g1_msm( &self, _vmcaller: &mut VmCaller<'_, Host>, vp: VecObject, vs: VecObject, ) -> Result<BytesObject, HostError>

Performs multi-scalar-multiplication (inner product) on a vector of BLS12-381 G1 points (Vec<BytesObject>) by a vector of scalars (Vec<U256Val>), and returns the resulting G1 point in bytes format.

fn bls12_381_map_fp_to_g1( &self, _vmcaller: &mut VmCaller<'_, Host>, fp: BytesObject, ) -> Result<BytesObject, HostError>

Maps a BLS12-381 field element (Fp) to G1 point. The input is a BytesObject containing Fp serialized in big-endian order

fn bls12_381_hash_to_g1( &self, _vmcaller: &mut VmCaller<'_, Host>, mo: BytesObject, dst: BytesObject, ) -> Result<BytesObject, HostError>

Hashes a message to a BLS12-381 G1 point, with implementation following the specification in Hashing to Elliptic Curves (ciphersuite ‘BLS12381G1_XMD:SHA-256_SSWU_RO_’). dst is the domain separation tag that will be concatenated with the msg during hashing, it is intended to keep hashing inputs of different applications separate. It is required 0 < len(dst_bytes) < 256. DST must be chosen with care to avoid compromising the application’s security properties. Refer to section 3.1 in the RFC on requirements of DST.

fn bls12_381_check_g2_is_in_subgroup( &self, _vmcaller: &mut VmCaller<'_, Host>, pt: BytesObject, ) -> Result<Bool, HostError>

Checks if the input G2 point is in the correct subgroup.

fn bls12_381_g2_add( &self, _vmcaller: &mut VmCaller<'_, Host>, p0: BytesObject, p1: BytesObject, ) -> Result<BytesObject, HostError>

Adds two BLS12-381 G2 points given in bytes format and returns the resulting G2 point in bytes format. G2 serialization format: concat(be_bytes(X_c1), be_bytes(X_c0), be_bytes(Y_c1), be_bytes(Y_c0)), and the most significant three bits of X_c1 are flags i.e. bits(X_c1) = [compression_flag, infinity_flag, sort_flag, bit_3, .. bit_383]. This function does NOT perform subgroup check on the inputs.

fn bls12_381_g2_mul( &self, _vmcaller: &mut VmCaller<'_, Host>, p0: BytesObject, scalar_le_bytes: U256Val, ) -> Result<BytesObject, HostError>

Multiplies a BLS12-381 G2 point by a scalar (Fr), and returns the resulting G2 point in bytes format.

fn bls12_381_g2_msm( &self, _vmcaller: &mut VmCaller<'_, Host>, vp: VecObject, vs: VecObject, ) -> Result<BytesObject, HostError>

Performs multi-scalar-multiplication (inner product) on a vector of BLS12-381 G2 points (Vec<BytesObject>) by a vector of scalars (Vec<U256Val>) , and returns the resulting G2 point in bytes format.

fn bls12_381_map_fp2_to_g2( &self, _vmcaller: &mut VmCaller<'_, Host>, fp2: BytesObject, ) -> Result<BytesObject, HostError>

Maps a BLS12-381 quadratic extension field element (Fp2) to G2 point. Fp2 serialization format: concat(be_bytes(c1), be_bytes(c0))

fn bls12_381_hash_to_g2( &self, _vmcaller: &mut VmCaller<'_, Host>, msg: BytesObject, dst: BytesObject, ) -> Result<BytesObject, HostError>

Hashes a message to a BLS12-381 G2 point, with implementation following the specification in Hashing to Elliptic Curves (ciphersuite ‘BLS12381G2_XMD:SHA-256_SSWU_RO_’). dst is the domain separation tag that will be concatenated with the msg during hashing, it is intended to keep hashing inputs of different applications separate. It is required 0 < len(dst_bytes) < 256. DST must be chosen with care to avoid compromising the application’s security properties. Refer to section 3.1 in the RFC on requirements of DST.

fn bls12_381_multi_pairing_check( &self, vmcaller: &mut VmCaller<'_, Host>, vp1: VecObject, vp2: VecObject, ) -> Result<Bool, HostError>

performs pairing operation on a vector of G1 (Vec<BytesObject>) and a vector of G2 points (Vec<BytesObject>) , return true if the result equals 1_fp12

fn bls12_381_fr_add( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs: U256Val, rhs: U256Val, ) -> Result<U256Val, Self::Error>

performs addition (lhs + rhs) mod r between two BLS12-381 scalar elements (Fr), where r is the subgroup order

fn bls12_381_fr_sub( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs: U256Val, rhs: U256Val, ) -> Result<U256Val, Self::Error>

performs subtraction (lhs - rhs) mod r between two BLS12-381 scalar elements (Fr), where r is the subgroup order

fn bls12_381_fr_mul( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs: U256Val, rhs: U256Val, ) -> Result<U256Val, Self::Error>

performs multiplication (lhs * rhs) mod r between two BLS12-381 scalar elements (Fr), where r is the subgroup order

fn bls12_381_fr_pow( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs: U256Val, rhs: U64Val, ) -> Result<U256Val, Self::Error>

performs exponentiation of a BLS12-381 scalar element (Fr) with a u64 exponent i.e. lhs.exp(rhs) mod r, where r is the subgroup order

fn bls12_381_fr_inv( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lhs: U256Val, ) -> Result<U256Val, Self::Error>

performs inversion of a BLS12-381 scalar element (Fr) modulo r (the subgroup order)

fn dummy0( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, ) -> Result<Val, Self::Error>

A dummy function taking 0 arguments and performs no-op. This function is for test purpose only, for measuring the roundtrip cost of invoking a host function, i.e. host->Vm->host.

fn protocol_gated_dummy( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, ) -> Result<Val, Self::Error>

A dummy function for testing the protocol gating. Takes 0 arguments and performs no-op. Essentially this function is always protocol-gated out since it has min_supported_protocol == max_supported_protocol == 19, thus having no effect on any protocol (Soroban starts at protocol 20). This is required for testing the scenario where ledger protocol version > host function max supported version, and the ledger protocol version must be <= the env version (which starts at 20, and is a compile-time, non-overridable constant).

fn require_auth_for_args( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, address: AddressObject, args: VecObject, ) -> Result<Void, Self::Error>

Checks if the address has authorized the invocation of the current contract function with the provided arguments. Traps if the invocation hasn’t been authorized.

fn require_auth( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, address: AddressObject, ) -> Result<Void, Self::Error>

Checks if the address has authorized the invocation of the current contract function with all the arguments of the invocation. Traps if the invocation hasn’t been authorized.

fn authorize_as_curr_contract( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, auth_entries: VecObject, ) -> Result<Void, HostError>

Authorizes sub-contract calls for the next contract call on behalf of the current contract. Every entry in the argument vector corresponds to InvokerContractAuthEntry contract type that authorizes a tree of require_auth calls on behalf of the current contract. The entries must not contain any authorizations for the direct contract call, i.e. if current contract needs to call contract function F1 that calls function F2 both of which require auth, only F2 should be present in auth_entries.

fn address_to_strkey( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, address: AddressObject, ) -> Result<StringObject, Self::Error>

Converts a provided address to Stellar strkey format (‘G…’ for account or ‘C…’ for contract). Prefer directly using the Address objects whenever possible. This is only useful in the context of custom messaging protocols (e.g. cross-chain).

fn strkey_to_address( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, strkey_obj: Val, ) -> Result<AddressObject, Self::Error>

Converts a provided Stellar strkey address of an account or a contract (‘G…’ or ‘C…’ respectively) to an address object. strkey can be either BytesObject or StringObject (the contents should represent the G.../C... string in both cases). Any other valid or invalid strkey (e.g. ‘S…’) will trigger an error. Prefer directly using the Address objects whenever possible. This is only useful in the context of custom messaging protocols (e.g. cross-chain).

fn prng_reseed( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, seed: BytesObject, ) -> Result<Void, Self::Error>

Reseed the frame-local PRNG with a given BytesObject, which should be 32 bytes long.

fn prng_bytes_new( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, length: U32Val, ) -> Result<BytesObject, Self::Error>

Construct a new BytesObject of the given length filled with bytes drawn from the frame-local PRNG.

fn prng_u64_in_inclusive_range( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, lo: u64, hi: u64, ) -> Result<u64, Self::Error>

Return a u64 uniformly sampled from the inclusive range [lo,hi] by the frame-local PRNG.

fn prng_vec_shuffle( &self, _vmcaller: &mut VmCaller<'_, Self::VmUserState>, vec: VecObject, ) -> Result<VecObject, Self::Error>

Return a (Fisher-Yates) shuffled clone of a given vector, using the frame-local PRNG.