Struct soroban_env_host::Host

source · [−]
pub struct Host(_);

Implementations

Converts a RawVal to an ScVal and combines it with the currently-executing [ContractID] to produce a [Key], that can be used to access ledger [Storage].

Records a debug-event from its input in as much detail as possible, then converts its input to a (often coarser-granularity) Status code, and then forms a HostError with it (which also captures a backtrace::Backtrace). This is the method you want to call any time there’s a finer-granularity error type that you want to log the details of and then downgrade fail with.

Helper for the simplest status-only error path.

Helper for the simplest string + general-error path.

Helper for the next-simplest status-and-extended-debug-message error path.

Given a result carrying some error type that can be converted to a DebugError, calls self.err with it when there’s an error. Returns a result over HostError.

If you have an error type T you want to record as a detailed debug event and a less-detailed Status code embedded in a HostError, add an impl From<T> for DebugError over in the events module and call this where the error is generated.

Note: we do not want to impl From<T> for HostError for such types, as doing so will avoid routing them through the host in order to record their extended diagnostic information into the debug buffer. This means you will wind up writing host.map_err(...)? a bunch in code that you used to be able to get away with just writing ...?, there’s no way around this if we want to record the diagnostic information.

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

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.

Records a debug event. This in itself is not necessarily an error; it might just be some contextual event we want to put in a debug log for diagnostic purpopses. The return value from this is therefore () when the event is recorded successfully, even if the event itself represented some other error. This function only returns Err(…) when there was a failure to record the event, such as when budget is exceeded.

Accept a unique (refcount = 1) host reference and destroy the underlying [HostImpl], returning its constituent components to the caller as a tuple wrapped in Ok(...). If the provided host reference is not unique, returns Err(self).

Records a System contract event. topics is expected to be a SCVec length <= 4 that cannot contain Vec, Map, or Bytes with length > 32 On success, returns an SCStatus::Ok.

Trait Implementations

Get the contractID Bytes of the contract which invoked the running contract. Traps if the running contract was not invoked by a contract. Read more

Records a contract event. topics is expected to be a SCVec with length <= 4 that cannot contain Vec, Map, or Bytes with length > 32 On success, returns an SCStatus::Ok. Read more

Get the contractID Bytes of the contract which invoked the running contract. Traps if the running contract was not invoked by a contract. Read more

Convert an i64 to an object containing an i64.

Convert an object containing an i64 to an i64.

Create an empty new map.

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. Read more

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

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

Get the size of a map.

Test for the presence of a key in a map. Returns (SCStatic) TRUE/FALSE.

Given a key, find the first key less than itself in the map’s sorted order. If such a key does not exist, return an SCStatus containing the error code (TBD). Read more

Given a key, find the first key greater than itself in the map’s sorted order. If such a key does not exist, return an SCStatus containing the error code (TBD). Read more

Find the minimum key from a map. If the map is empty, return an SCStatus containing the error code (TBD). Read more

Find the maximum key from a map. If the map is empty, return an SCStatus containing the error code (TBD). Read more

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

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

Creates a new vector with an optional capacity hint c. If c is ScStatic::Void, no hint is assumed and the new vector is empty. Otherwise, c is parsed as an u32 that represents the initial capacity of the new vector. Read more

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

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

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. Read more

Returns length of the vector.

Push a value to the front of a vector.

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

Appends an element to the back of the vector.

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

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

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

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 Read more

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. Read more

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. Read more

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 ScStatic::Void. Read more

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 ScStatic::Void. Read more

Binary search a sorted vector for a given element. If it exists, the high-32 bits of the return value is 0x0001 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 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. Read more

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

Calls a function in another contract with arguments contained in vector args. Returns: Read more

Constructs a BigInt from an u64.

Converts a BigInt to an u64. Traps if the value cannot fit into u64.

Constructs a BigInt from an i64.

Converts a BigInt to an i64. Traps if the value cannot fit into i64.

Performs the + operation.

Performs the - operation.

Performs the * operation.

Performs the / operation. Traps if y is zero.

Performs the % operation. Traps if y is zero.

Performs the & operation.

Performs the | operation.

Performs the ^ operation.

Performs the << operation. Traps if y is negative or larger than the size of u64.

Performs the >> operation. Traps if y is negative or larger than the size of u64.

Returns true if x is equal to the additive identity.

Performs the unary - operation.

Performs the unary ! operation.

Calculates the Greatest Common Divisor (GCD) of x and y.

Calculates the Lowest Common Multiple (LCM) of x and y.

Calculates x to the power y. Traps if y is negative or larger than the size of u64.

Calculates (p ^ q) mod m. Note that this rounds like mod_floor, not like the % operator, which makes a difference when given a negative p or m. The result will be in the interval [0, m) for m > 0, or in the interval (m, 0] for m < 0. Traps if the q is negative or the m is zero. Read more

Calculates the truncated principal square root of x. Traps if x is negative.

Determines the fewest bits necessary to express x, not including the sign.

Outputs the BigInt’s magnitude in big-endian byte order into a byte array. The sign is dropped.

Outputs the BigInt’s magnitude in the requested base in big-endian digit order into a byte array. The sign is dropped. Radix must be in the range 2…256. Read more

Creates a BigInt from a byte array and i32 sign. Bytes are in big-endian order. Sign is interpreted: -1 as negative, 0 as zero, 1 as positive If sign is 0, then the input bytes are ignored and will return a BigInt of 0. Read more

Creates a BigInt from a byte array buf, an i32 sign and an u32 radix. Each u8 of the byte array is interpreted as one digit of the number and must therefore be less than the radix. The bytes are in big-endian byte order. Radix must be in the range 2..=256. Sign follows same rule as in bigint_from_bytes_be. Read more

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

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

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. Read more

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. Read more

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

Create an empty new Bytes object.

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

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

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. Read more

Returns length of the Bytes object.

Appends an element to the back of the Bytes object.

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

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

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

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 Read more

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. Read more

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. Read more

Get the low threshold for the account with ed25519 public key a (a is Bytes). Traps if no such account exists. Read more

Get the medium threshold for the account with ed25519 public key a (a is Bytes). Traps if no such account exists. Read more

Get the high threshold for the account with ed25519 public key a (a is Bytes). Traps if no such account exists. Read more

Given an ed25519 public key a (a is Bytes) of an account, check if it exists. Returns (SCStatic) TRUE/FALSE. Read more

Get the signer weight for the signer with ed25519 public key s (s is Bytes) on the account with ed25519 public key a (a is Bytes). Returns the master weight if the signer is the master, and returns 0 if no such signer exists. Traps if no such account exists. Read more

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

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

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

Return the network passphrase of the current ledger as Bytes.

Returns the full call stack from the first contract call to the current one as a vector of vectors, where the inside vector contains the contract id as Hash, and a function as a Symbol. Read more

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Used for recovering the concrete type of the Host.

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

Used to clone an environment deeply, not just a handle to it.

Copy a slice of bytes from the caller’s memory into an existing Bytes object the host, returning a new Bytes. Read more

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

Form a new Bytes object in the host from a slice of memory in the caller. Read more

Log a formatted debugging message to the debug log (if present), passing a simplified format string (supporting only positional {} markers) and a single RawVal argument that will be inserted at the marker in the format string. Read more

Log a formatted debugging message to the debug log (if present), passing a simplified format string (supporting only positional {} markers) and a single string-slice argument that will be inserted at the marker in the format string. Read more

Log a formatted debugging message to the debug log (if present), passing a simplified format string (supporting only positional {} markers) and both a RawVal and a string-slice argument, that will each be inserted at markers in the format string. Read more

Log a formatted debugging message to the debug log (if present), passing a simplified format string (supporting only positional {} markers) and both a slice of RawVals and a slice of string-slice argument, that will be sequentially inserted at markers in the format string. Read more

Perform invoke of a host function by specified index.

The maximum number of instructions to run between calls to charge_cpu.

Charge the externals for a given block of instructions having executed.

Charge the externals for a given amount of linear memory being allocated.

Resolve a function. Read more

Resolve a global variable. Read more

Resolve a memory. Read more

Resolve a table. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait. Read more

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait. Read more

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s. Read more

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s. Read more

Get the contractID Bytes of the contract which invoked the running contract. Traps if the running contract was not invoked by a contract. Read more

Records a contract event. topics is expected to be a SCVec with length <= 4 that cannot contain Vec, Map, or Bytes with length > 32 On success, returns an SCStatus::Ok. Read more

Get the contractID Bytes of the contract which invoked the running contract. Traps if the running contract was not invoked by a contract. Read more

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

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

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

Return the network passphrase of the current ledger as Bytes.

Returns the full call stack from the first contract call to the current one as a vector of vectors, where the inside vector contains the contract id as Hash, and a function as a Symbol. Read more

Convert an i64 to an object containing an i64.

Convert an object containing an i64 to an i64.

Create an empty new map.

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. Read more

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

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

Get the size of a map.

Test for the presence of a key in a map. Returns (SCStatic) TRUE/FALSE.

Given a key, find the first key less than itself in the map’s sorted order. If such a key does not exist, return an SCStatus containing the error code (TBD). Read more

Given a key, find the first key greater than itself in the map’s sorted order. If such a key does not exist, return an SCStatus containing the error code (TBD). Read more

Find the minimum key from a map. If the map is empty, return an SCStatus containing the error code (TBD). Read more

Find the maximum key from a map. If the map is empty, return an SCStatus containing the error code (TBD). Read more

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

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

Creates a new vector with an optional capacity hint c. If c is ScStatic::Void, no hint is assumed and the new vector is empty. Otherwise, c is parsed as an u32 that represents the initial capacity of the new vector. Read more

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

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

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. Read more

Returns length of the vector.

Push a value to the front of a vector.

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

Appends an element to the back of the vector.

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

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

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

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 Read more

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. Read more

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. Read more

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 ScStatic::Void. Read more

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 ScStatic::Void. Read more

Binary search a sorted vector for a given element. If it exists, the high-32 bits of the return value is 0x0001 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 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. Read more

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

Calls a function in another contract with arguments contained in vector args. Returns: Read more

Constructs a BigInt from an u64.

Converts a BigInt to an u64. Traps if the value cannot fit into u64.

Constructs a BigInt from an i64.

Converts a BigInt to an i64. Traps if the value cannot fit into i64.

Performs the + operation.

Performs the - operation.

Performs the * operation.

Performs the / operation. Traps if y is zero.

Performs the % operation. Traps if y is zero.

Performs the & operation.

Performs the | operation.

Performs the ^ operation.

Performs the << operation. Traps if y is negative or larger than the size of u64.

Performs the >> operation. Traps if y is negative or larger than the size of u64.

Returns true if x is equal to the additive identity.

Performs the unary - operation.

Performs the unary ! operation.

Calculates the Greatest Common Divisor (GCD) of x and y.

Calculates the Lowest Common Multiple (LCM) of x and y.

Calculates x to the power y. Traps if y is negative or larger than the size of u64.

Calculates (p ^ q) mod m. Note that this rounds like mod_floor, not like the % operator, which makes a difference when given a negative p or m. The result will be in the interval [0, m) for m > 0, or in the interval (m, 0] for m < 0. Traps if the q is negative or the m is zero. Read more

Calculates the truncated principal square root of x. Traps if x is negative.

Determines the fewest bits necessary to express x, not including the sign.

Outputs the BigInt’s magnitude in big-endian byte order into a byte array. The sign is dropped.

Outputs the BigInt’s magnitude in the requested base in big-endian digit order into a byte array. The sign is dropped. Radix must be in the range 2…256. Read more

Creates a BigInt from a byte array and i32 sign. Bytes are in big-endian order. Sign is interpreted: -1 as negative, 0 as zero, 1 as positive If sign is 0, then the input bytes are ignored and will return a BigInt of 0. Read more

Creates a BigInt from a byte array buf, an i32 sign and an u32 radix. Each u8 of the byte array is interpreted as one digit of the number and must therefore be less than the radix. The bytes are in big-endian byte order. Radix must be in the range 2..=256. Sign follows same rule as in bigint_from_bytes_be. Read more

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

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

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. Read more

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. Read more

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

Create an empty new Bytes object.

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

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

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. Read more

Returns length of the Bytes object.

Appends an element to the back of the Bytes object.

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

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

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

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 Read more

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. Read more

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. Read more

Get the low threshold for the account with ed25519 public key a (a is Bytes). Traps if no such account exists. Read more

Get the medium threshold for the account with ed25519 public key a (a is Bytes). Traps if no such account exists. Read more

Get the high threshold for the account with ed25519 public key a (a is Bytes). Traps if no such account exists. Read more

Get the signer weight for the signer with ed25519 public key s (s is Bytes) on the account with ed25519 public key a (a is Bytes). Returns the master weight if the signer is the master, and returns 0 if no such signer exists. Traps if no such account exists. Read more

Given an ed25519 public key a (a is Bytes) of an account, check if it exists. Returns (SCStatic) TRUE/FALSE. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.