Struct Session

pub struct Session { /* private fields */ }

A running mutation to a state.

Sessions are spawned using a VM instance, and can be used to call contracts with to modify their state. A sequence of these calls may then be commited to, or discarded by simply allowing the session to drop.

New contracts are to be deployed in the context of a session.

Implementations

impl Session

pub fn deploy<'a, A, D>( &mut self, bytecode: &[u8], deploy_data: D, gas_limit: u64, ) -> Result<ContractId, Error>

where A: 'a + for<'b> Serialize<CompositeSerializer<BufferSerializer<&'b mut [u8]>, BufferScratch<&'b mut [u8; 1024]>>>, D: Into<ContractData<'a, A>>,

Deploy a contract, returning its ContractId. The ID is computed using a blake3 hash of the bytecode. Contracts using the memory64 proposal are accepted in just the same way as 32-bit contracts, and their handling is totally transparent.

Since a deployment may execute some contract initialization code, that code will be metered and executed with the given gas_limit.

Errors

It is possible that a collision between contract IDs occurs, even for different contract IDs. This is due to the fact that all contracts have to fit into a sparse merkle tree with 2^32 positions, and as such a 256-bit number has to be mapped into a 32-bit number.

If such a collision occurs, PersistenceError will be returned.

Panics

If deploy_data does not specify an owner, this will panic.

pub fn deploy_raw( &mut self, contract_id: Option<ContractId>, bytecode: &[u8], init_arg: Option<Vec<u8>>, owner: Vec<u8>, gas_limit: u64, ) -> Result<ContractId, Error>

Deploy a contract, returning its ContractId. If ID is not provided, it is computed using a blake3 hash of the bytecode. Contracts using the memory64 proposal are accepted in just the same way as 32-bit contracts, and their handling is totally transparent.

Since a deployment may execute some contract initialization code, that code will be metered and executed with the given gas_limit.

Errors

It is possible that a collision between contract IDs occurs, even for different contract IDs. This is due to the fact that all contracts have to fit into a sparse merkle tree with 2^32 positions, and as such a 256-bit number has to be mapped into a 32-bit number.

If such a collision occurs, PersistenceError will be returned.

pub fn call<A, R>( &mut self, contract: ContractId, fn_name: &str, fn_arg: &A, gas_limit: u64, ) -> Result<CallReceipt<R>, Error>

where A: for<'b> Serialize<CompositeSerializer<BufferSerializer<&'b mut [u8]>, BufferScratch<&'b mut [u8; 1024]>>>, <A as Archive>::Archived: for<'b> CheckBytes<DefaultValidator<'b>>, R: Archive, <R as Archive>::Archived: Deserialize<R, Infallible> + for<'b> CheckBytes<DefaultValidator<'b>>,

Execute a call on the current state of this session.

Calls are atomic, meaning that on failure their execution doesn’t modify the state. They are also metered, and will execute with the given gas_limit. This value should never be 0.

Errors

The call may error during execution for a wide array of reasons, the most common ones being running against the gas limit and a contract panic. Calling the ‘init’ method is not allowed except for when called from the deploy method.

pub fn call_raw<V>( &mut self, contract: ContractId, fn_name: &str, fn_arg: V, gas_limit: u64, ) -> Result<CallReceipt<Vec<u8>>, Error>

where V: Into<Vec<u8>>,

Execute a raw call on the current state of this session.

Raw calls do not specify the type of the argument or of the return. The caller is responsible for serializing the argument as the target contract expects.

For more information about calls see call.

pub fn migrate<'a, A, D, F>( self, contract: ContractId, bytecode: &[u8], deploy_data: D, deploy_gas_limit: u64, closure: F, ) -> Result<Session, Error>

where A: 'a + for<'b> Serialize<CompositeSerializer<BufferSerializer<&'b mut [u8]>, BufferScratch<&'b mut [u8; 1024]>>>, D: Into<ContractData<'a, A>>, F: FnOnce(ContractId, &mut Session) -> Result<(), Error>,

Migrates a contract to a new bytecode, performing modifications to its state as specified by the closure.

The closure takes a contract ID of where the new contract will be available during the migration, and a mutable reference to a session, allowing the caller to perform calls and other operations on the new (and old) contract.

At the end of the migration, the new contract will be available at the given contract ID, and the old contract will be removed from the state.

If the owner of a contract is not set, it will be set to the owner of the contract being replaced. If it is set, then it will be used as the new owner.

Errors

The migration may error during execution for a myriad of reasons. The caller is encouraged to drop the Session should an error occur as it will more than likely be left in an inconsistent state.

Panics

If the owner of the new contract is not set in deploy_data, and the contract being replaced does not exist, this will panic.

pub fn feeder_call<A, R>( &mut self, contract: ContractId, fn_name: &str, fn_arg: &A, gas_limit: u64, feeder: Sender<Vec<u8>>, ) -> Result<CallReceipt<R>, Error>

where A: for<'b> Serialize<CompositeSerializer<BufferSerializer<&'b mut [u8]>, BufferScratch<&'b mut [u8; 1024]>>>, <A as Archive>::Archived: for<'b> CheckBytes<DefaultValidator<'b>>, R: Archive, <R as Archive>::Archived: Deserialize<R, Infallible> + for<'b> CheckBytes<DefaultValidator<'b>>,

Execute a feeder call on the current state of this session.

Feeder calls are used to have the contract be able to report larger amounts of data to the host via the channel included in this call.

These calls should be performed with a large amount of gas, since the contracts may spend quite a large amount in an effort to report data.

pub fn feeder_call_raw<V>( &mut self, contract: ContractId, fn_name: &str, fn_arg: V, gas_limit: u64, feeder: Sender<Vec<u8>>, ) -> Result<CallReceipt<Vec<u8>>, Error>

where V: Into<Vec<u8>>,

Execute a raw feeder call on the current state of this session.

See feeder_call and call_raw for more information of this type of call.

pub fn memory_len( &mut self, contract_id: ContractId, ) -> Result<Option<usize>, Error>

Returns the current length of the memory of the given contract.

If the contract does not exist, it will return None.

pub fn root(&self) -> [u8; 32]

Return the state root of the current state of the session.

The state root is the root of a merkle tree whose leaves are the hashes of the state of of each contract, ordered by their contract ID.

It also doubles as the ID of a commit - the commit root.

pub fn memory_pages( &self, contract: ContractId, ) -> Option<impl Iterator<Item = (usize, &[u8], PageOpening)>>

Returns an iterator over the pages (and their indices) of a contract’s memory, together with a proof of their inclusion in the state.

The proof is a Merkle inclusion proof, and the caller is able to verify it by using verify, and matching the root with the one returned by root.

pub fn commit(self) -> Result<[u8; 32], Error>

Commits the given session to disk, consuming the session and returning its state root.

pub fn with_debug<C, R>(&self, c: C) -> R

where C: FnOnce(&[String]) -> R,

pub fn meta(&self, name: &str) -> Option<Vec<u8>>

Returns the value of a metadata item.

pub fn set_meta<S, V>( &mut self, name: S, value: V, ) -> Result<Option<Vec<u8>>, Error>

where S: Into<Cow<'static, str>>, V: for<'a> Serialize<CompositeSerializer<BufferSerializer<&'a mut [u8]>, BufferScratch<&'a mut [u8; 1024]>>>,

Set the value of a metadata item.

Returns the previous value of the metadata item.

pub fn remove_meta<S>(&mut self, name: S) -> Option<Vec<u8>>

where S: Into<Cow<'static, str>>,

Remove a metadata item.

Returns the value of the removed item (if any).

pub fn serialize_data<V>(value: &V) -> Result<Vec<u8>, Error>

where V: for<'a> Serialize<CompositeSerializer<BufferSerializer<&'a mut [u8]>, BufferScratch<&'a mut [u8; 1024]>>>,

pub fn contract_metadata( &mut self, contract_id: &ContractId, ) -> Option<&ContractMetadata>

Trait Implementations

impl Debug for Session

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

Formats the value using the given formatter.

impl Drop for Session

A session is created by leaking an using Box::leak on a SessionInner. Therefore, the memory needs to be recovered.

fn drop(&mut self)

Executes the destructor for this type.

impl MemoryCreator for Session

fn new_memory( &self, _ty: MemoryType, minimum: usize, _maximum: Option<usize>, _reserved_size_in_bytes: Option<usize>, _guard_size_in_bytes: usize, ) -> Result<Box<dyn LinearMemory>, String>

This new memory is created for the contract currently at the top of the call tree.

impl Send for Session

impl Sync for Session