Struct stacks_rpc_client::clarity::vm::contexts::Environment
pub struct Environment<'a, 'b, 'hooks> {
pub global_context: &'a mut GlobalContext<'b, 'hooks>,
pub contract_context: &'a ContractContext,
pub call_stack: &'a mut CallStack,
pub sender: Option<PrincipalData>,
pub caller: Option<PrincipalData>,
pub sponsor: Option<PrincipalData>,
}Expand description
Environments pack a reference to the global context (which is basically the db), the current contract context, a call stack, the current sender, caller, and sponsor (if one exists). Essentially, the point of the Environment struct is to prevent all the eval functions from including all of these items in their method signatures individually. Because these different contexts can be mixed and matched (i.e., in a contract-call, you change contract context), a single “invocation” will end up creating multiple environment objects as context changes occur.
Fields§
§global_context: &'a mut GlobalContext<'b, 'hooks>§contract_context: &'a ContractContext§call_stack: &'a mut CallStack§sender: Option<PrincipalData>§caller: Option<PrincipalData>§sponsor: Option<PrincipalData>Implementations§
§impl<'a, 'b, 'hooks> Environment<'a, 'b, 'hooks>
impl<'a, 'b, 'hooks> Environment<'a, 'b, 'hooks>
pub fn new(
global_context: &'a mut GlobalContext<'b, 'hooks>,
contract_context: &'a ContractContext,
call_stack: &'a mut CallStack,
sender: Option<PrincipalData>,
caller: Option<PrincipalData>,
sponsor: Option<PrincipalData>
) -> Environment<'a, 'b, 'hooks>
pub fn new( global_context: &'a mut GlobalContext<'b, 'hooks>, contract_context: &'a ContractContext, call_stack: &'a mut CallStack, sender: Option<PrincipalData>, caller: Option<PrincipalData>, sponsor: Option<PrincipalData> ) -> Environment<'a, 'b, 'hooks>
Returns an Environment value & checks the types of the contract sender, caller, and sponsor
Panics
Panics if the Value types for sender (Principal), caller (Principal), or sponsor (Optional Principal) are incorrect.
pub fn nest_as_principal<'c>(
&'c mut self,
sender: PrincipalData
) -> Environment<'c, 'b, 'hooks>
pub fn nest_as_principal<'c>( &'c mut self, sender: PrincipalData ) -> Environment<'c, 'b, 'hooks>
Leaving sponsor value as is for this new context (as opposed to setting it to None)
pub fn nest_with_caller<'c>( &'c mut self, caller: PrincipalData ) -> Environment<'c, 'b, 'hooks>
pub fn eval_read_only_with_rules( &mut self, contract_identifier: &QualifiedContractIdentifier, program: &str, rules: ASTRules ) -> Result<Value, Error>
pub fn eval_raw_with_rules( &mut self, program: &str, rules: ASTRules ) -> Result<Value, Error>
pub fn run_free<F, A>(&mut self, to_run: F) -> Awhere
F: FnOnce(&mut Environment<'_, '_, '_>) -> A,
pub fn run_free<F, A>(&mut self, to_run: F) -> Awhere F: FnOnce(&mut Environment<'_, '_, '_>) -> A,
Used only for contract-call! cost short-circuiting. Once the short-circuited cost has been evaluated and assessed, the contract-call! itself is executed “for free”.
pub fn epoch(&self) -> &StacksEpochId
pub fn epoch(&self) -> &StacksEpochId
This is the epoch of the the block that this transaction is executing within. Note: in the current plans for 2.1, there is also a contract-specific Clarity version which governs which native functions are available / defined. That is separate from this epoch identifier, and most Clarity VM changes should consult that value instead. This epoch identifier is used for determining how cost functions should be applied.
pub fn execute_contract( &mut self, contract: &QualifiedContractIdentifier, tx_name: &str, args: &[SymbolicExpression], read_only: bool ) -> Result<Value, Error>
pub fn execute_contract_allow_private(
&mut self,
contract: &QualifiedContractIdentifier,
tx_name: &str,
args: &[SymbolicExpression],
read_only: bool
) -> Result<Value, Error>
pub fn execute_contract_allow_private( &mut self, contract: &QualifiedContractIdentifier, tx_name: &str, args: &[SymbolicExpression], read_only: bool ) -> Result<Value, Error>
This method is exposed for callers that need to invoke a private method directly. For example, this is used by the Stacks chainstate for invoking private methods on the pox-2 contract. This should not be called by user transaction processing.
pub fn execute_function_as_transaction( &mut self, function: &DefinedFunction, args: &[Value], next_contract_context: Option<&ContractContext> ) -> Result<Value, Error>
pub fn evaluate_at_block( &mut self, bhh: StacksBlockId, closure: &SymbolicExpression, local: &LocalContext<'_> ) -> Result<Value, Error>
pub fn initialize_contract( &mut self, contract_identifier: QualifiedContractIdentifier, contract_content: &str, ast_rules: ASTRules ) -> Result<(), Error>
pub fn initialize_contract_from_ast( &mut self, contract_identifier: QualifiedContractIdentifier, contract_version: ClarityVersion, contract_content: &ContractAST, contract_string: &str ) -> Result<(), Error>
pub fn stx_transfer(
&mut self,
from: &PrincipalData,
to: &PrincipalData,
amount: u128,
memo: &BuffData
) -> Result<Value, Error>
pub fn stx_transfer( &mut self, from: &PrincipalData, to: &PrincipalData, amount: u128, memo: &BuffData ) -> Result<Value, Error>
Top-level STX-transfer, invoked by TokenTransfer transactions. Only commits if the inner stx_transfer_consolidated() returns an (ok true) value. Rolls back if it returns an (err ..) value, or if the method itself fails for some reason (miners should never build blocks that spend non-existent STX in a top-level token-transfer)