Class Context<T extends ACell>
- Type Parameters:
T
- Result type of Context
Execution context includes: - The current on-Chain state, including the defined execution environment for each Address - Local lexical bindings for the current execution position - The identity (as an Address) for the origin, caller and currently executing actor - Juice and execution depth current status for - Result of the last operation executed (which may be exceptional)
Interestingly, this behaves like Scala's ZIO[Context-Stuff, AExceptional, T]
Contexts maintain checks on execution depth and juice to control against arbitrary on-chain execution. Coupled with limits on total juice and limits on memory allocation per unit juice, this places an upper bound on execution time and space.
Contexts also support returning exceptional values. Exceptional results may come from arbitrary nested depth (which requires a bit of complexity to reset depth when catching exceptional values). We avoid using Java exceptions here, because exceptionals are "normal" in the context of on-chain execution, and we'd like to avoid the overhead of exception handling - may be especially important in DoS scenarios.
"If you have a procedure with 10 parameters, you probably missed some" - Alan Perlis
-
Nested Class Summary
Nested Classes -
Field Summary
Fields -
Method Summary
Modifier and TypeMethodDescriptionacceptFunds(long amount)
Accepts offered funds for the given address.Executes a call to an Actor.Executes a call to an Actor.Appends a log entry for the current address.boolean
checkJuice(long gulp)
Checks if there is sufficient juice for a given gulp of consumption.Compile a form in this Context.compileAll(ASequence<ACell> forms)
Compiles a sequence of forms in the current context.completeTransaction(State initialState, long initialJuice)
Performs key actions at the end of a transaction: Refunds juice Accumulates used juice fees in globalsconsumeJuice(long gulp)
Consumes juice, returning an updated context if sufficient juice remains or an exceptional JUICE error.createAccount(AccountKey key)
Create a new Account with a given AccountKey (may be null for actors etc.)Creates a Blob object representing this object.createFake(State state)
Creates an execution context with a default actor address.createFake(State state, Address origin)
Creates a "fake" execution context for the given address.createInitial(State state, Address origin, long juice)
Creates an initial execution context with the specified actor as origin, and reserving the appropriate amount of juice.createPeer(AccountKey accountKey, long initialStake)
Creates a new peer with the specified stake.Defines a value in the environment of the current addressdefineWithSyntax(Syntax syn, ACell value)
Defines a value in the environment of the current address, updating the metadatadeployActor(ACell code)
Deploys an Actor in this context.Executes a form in the current context.Evaluates a form as another Address.Executes an Op within this context, returning an updated context.executeLocalBinding(ACell bindingForm, AOp<I> op)
Execute an op, and bind the result to the given binding form in the lexical environment Binding form may be a destructuring formExpands a form with the default *initial-expander*expandCompile(ACell form)
Expand and compile a form in this Context.fork()
Forks this context, creating a new copy of all local stateforkWithAddress(Address newAddress)
Switches the context to a new address, creating a new execution context.Gets the account status for the current AddressgetAccountStatus(Address address)
Gets the account status record, or null if not foundGets the address of the currently executing Account.long
long
getBalance(Address address)
Gets the caller of the currently executing context.Gets the compiler stateint
getDepth()
Gets the current EnvironmentgetError()
Gets the Error from this Context, or null if not an ErrorGets the error code of this context's return valueGets the exceptional value from this context.Gets the holdings map for the current account.long
getJuice()
Get the juice available in this ContextgetLog()
Gets the log map for the current context.Gets the metadata for the current Accountlong
getOffer()
Get the current offer from this ContextGets the result from this context.getState()
Get the latest state from this ContextGets the current timestamp for this context.getValue()
Gets the resulting value from this context.handleQueryResult(Context<R> ctx)
Just take result and juice from query.Invokes a function within this context, returning an updated context.boolean
isError()
Tests if this Context's current status contains an Error.boolean
Tests if this Context holds an exceptional result.boolean
isValidAccount(Address address)
Tests if an Address is valid, i.e.Looks up a symbol's value in the current execution context, without any effect on the Context (no juice consumed etc.)Context<?>
lookupDefiningAccount(Address address, Symbol sym)
Looks up the account the defines a given SymbollookupDynamic(Address address, Symbol symbol)
Looks up a value in the dynamic environment.lookupDynamic(Symbol symbol)
Looks up a value in the dynamic environment.lookupDynamicEntry(Address address, Symbol sym)
Looks up an environment entry for a specific address without consuming juice.lookupExpander(ACell form)
Looks up an expander from a form in this contextlookupMeta(Address address, Symbol sym)
Looks up Metadata for the given symbol in this contextlookupMeta(Symbol sym)
Looks up Metadata for the given symbol in this contextlookupValue(Address address, Symbol sym)
Looks up value for the given symbol in this contextlookupValue(Symbol sym)
Looks up value for the given symbol in this contextvoid
print(StringBuilder sb)
Prints this Object to a readable String RepresentationExecutes code as if run in the current account, but always discarding state changes.Executes code as if run in the specified account, but always discarding state changes.Executes a form at the top level in a new forked Context.Executes an Op at the top level in a new forked Context.Schedules an operation for the specified future timestamp.setAccountKey(AccountKey publicKey)
Sets the public key for the current accountsetController(Address address)
Sets the controller for the current AccountsetDelegatedStake(AccountKey peerKey, long newStake)
Sets the delegated stake on a specified peer to the specified level.setHolding(Address targetAddress, ACell value)
Sets the holding for a specified target account.setMemory(long allowance)
Sets the memory allowance for the current account, buying / selling from the pool as necessary to ensure the correct final allowancesetPeerData(AccountKey peerKey, AMap<ACell,ACell> data)
Sets peer data.setPeerStake(AccountKey peerKey, long newStake)
Sets the stake for a given Peer, transferring coins from the current address.Transfers funds from the current address to the target.transferMemoryAllowance(Address target, CVMLong amountToSend)
Transfers memory allowance from the current address to the target.Removes a definition mapping in the environment of the current addressupdateBindings(ACell bindingForm, Object args)
Updates local bindings with a given binding formwithAccountStatus(Address target, AccountStatus accountStatus)
withArgumentError(String message)
withArityError(String message)
withAssertError(String message)
withBoundsError(long index)
withCastError(int argIndex, ACell[] args, AType klass)
withCastError(int argIndex, AType klass)
withCastError(ACell a, AType klass)
withCastError(ACell a, String message)
withCastError(AType klass)
withCompileError(String message)
withError(ErrorValue error)
withException(long gulp, AExceptional value)
withException(AExceptional exception)
withFundsError(String message)
withJuice(long newJuice)
Returns this context with a JUICE error, consuming all juice.withLocalBindings(AVector<ACell> newBindings)
Updates this Context with new local bindings.withResult(long gulp, R value)
withResult(ACell value)
Returns a context updated with the specified result.Updates this context with a given value, which may either be a normal result or exceptional valueMethods inherited from class convex.core.data.AObject
attachEncoding, getEncoding, print
-
Field Details
-
EMPTY_BINDINGS
-
-
Method Details
-
createFake
Creates an execution context with a default actor address. Useful for Testing- Parameters:
state
- State to use for this Context- Returns:
- Fake context
-
createFake
Creates a "fake" execution context for the given address. Not valid for use in real transactions, but can be used to compute stuff off-chain "as-if" the actor made the call.- Parameters:
state
- State to use for this Contextorigin
- Origin address to use- Returns:
- Fake context
-
createInitial
Creates an initial execution context with the specified actor as origin, and reserving the appropriate amount of juice. Juice reserve is extracted from the actor's current balance.- Parameters:
state
- Initial State for Contextorigin
- Origin Address for Contextjuice
- Initial juice for Context- Returns:
- Initial execution context with reserved juice.
-
completeTransaction
Performs key actions at the end of a transaction:- Refunds juice
- Accumulates used juice fees in globals
- Parameters:
initialState
- State before transaction execution (after prepare)initialJuice
- total juice reserved at start of transaction- Returns:
- Updated context
-
withState
-
getState
Get the latest state from this Context- Returns:
- State instance
-
getJuice
public long getJuice()Get the juice available in this Context- Returns:
- Juice available
-
getOffer
public long getOffer()Get the current offer from this Context- Returns:
- Offered amount in Convex copper
-
getEnvironment
Gets the current Environment- Returns:
- Environment map
-
getCompilerState
Gets the compiler state- Returns:
- CompilerState instance
-
getMetadata
Gets the metadata for the current Account- Returns:
- Metadata map
-
consumeJuice
Consumes juice, returning an updated context if sufficient juice remains or an exceptional JUICE error.- Type Parameters:
R
- Result type- Parameters:
gulp
- Amount of jjuice to consume- Returns:
- Updated context with juice consumed
-
checkJuice
public boolean checkJuice(long gulp)Checks if there is sufficient juice for a given gulp of consumption. Does not alter context in any way.- Parameters:
gulp
- Amount of juice to be consumed.- Returns:
- true if juice is sufficient, false otherwise.
-
lookup
Looks up a symbol's value in the current execution context, without any effect on the Context (no juice consumed etc.)- Type Parameters:
R
- Type of value associated with the given symbol- Parameters:
symbol
- Symbol to look up. May be qualified- Returns:
- Context with the result of the lookup (may be an undeclared exception)
-
lookupDynamic
Looks up a value in the dynamic environment. Consumes no juice. Returns an UNDECLARED exception if the symbol cannot be resolved.- Type Parameters:
R
- Result type- Parameters:
symbol
- Symbol to look up- Returns:
- Updated Context
-
lookupDynamic
Looks up a value in the dynamic environment. Consumes no juice. Returns an UNDECLARED exception if the symbol cannot be resolved. Returns a NOBODY exception if the specified Account does not exist- Type Parameters:
R
- Type of value result- Parameters:
address
- Address of account in which to look up valuesymbol
- Symbol to look up- Returns:
- Updated Context
-
lookupMeta
Looks up Metadata for the given symbol in this context- Parameters:
sym
- Symbol to look up- Returns:
- Metadata for given symbol (may be empty) or null if undeclared
-
lookupMeta
Looks up Metadata for the given symbol in this context- Parameters:
address
- Address to use for lookup (may pass null for current environment)sym
- Symbol to look up- Returns:
- Metadata for given symbol (may be empty) or null if undeclared
-
lookupDefiningAccount
Looks up the account the defines a given Symbol- Parameters:
sym
- Symbol to look upaddress
- Address to look up in first instance (null for current address).- Returns:
- AccountStatus for given symbol (may be empty) or null if undeclared
-
lookupValue
Looks up value for the given symbol in this context- Parameters:
sym
- Symbol to look up- Returns:
- Value for the given symbol or null if undeclared
-
lookupValue
Looks up value for the given symbol in this context- Parameters:
address
- Address to look up in (may be null for current environment)sym
- Symbol to look up- Returns:
- Value for the given symbol or null if undeclared
-
lookupDynamicEntry
Looks up an environment entry for a specific address without consuming juice.- Parameters:
address
- Address of Account in which to look up entrysym
- Symbol to look up- Returns:
- Environment entry
-
getAccountStatus
Gets the account status for the current Address- Returns:
- AccountStatus object, or null if not found
-
getHoldings
Gets the holdings map for the current account.- Returns:
- Map of holdings, or null if the current account does not exist.
-
getBalance
public long getBalance() -
getBalance
-
getCaller
Gets the caller of the currently executing context. Will be null if this context was not called from elsewhere (e.g. is an origin context)- Returns:
- Caller of the currently executing context
-
getAddress
Gets the address of the currently executing Account. May be the current actor, or the address of the account that executed this transaction if no Actors have been called.- Returns:
- Address of the current account, cannot be null, must be a valid existing account
-
getResult
Gets the result from this context. Throws an Error if the context return value is exceptional.- Returns:
- Result value from this Context.
-
getValue
Gets the resulting value from this context. May be either exceptional or a normal result.- Returns:
- Either the normal result, or an AExceptional instance
-
getExceptional
Gets the exceptional value from this context. Throws an Error is the context return value is normal.- Returns:
- an AExceptional instance
-
withResult
Returns a context updated with the specified result. Context may become exceptional depending on the result type.- Type Parameters:
R
- Result type- Parameters:
value
- Value- Returns:
- Context updated with the specified result.
-
withValue
Updates this context with a given value, which may either be a normal result or exceptional value- Type Parameters:
R
- Result type- Parameters:
value
- Value- Returns:
- Context updated with the specified result value.
-
withResult
-
withJuiceError
Returns this context with a JUICE error, consuming all juice.- Type Parameters:
R
- Result type- Returns:
- Exceptional Context signalling JUICE error.
-
withException
-
withException
-
execute
Executes an Op within this context, returning an updated context.- Type Parameters:
R
- Return type of the Op- Parameters:
op
- Op to execute- Returns:
- Updated Context
-
run
Executes an Op at the top level in a new forked Context. Handles top level halt, recur and return. Returning an updated context containing the result or an exceptional error.- Type Parameters:
R
- Return type of the Op- Parameters:
op
- Op to execute- Returns:
- Updated Context
-
run
Executes a form at the top level in a new forked Context. Handles top level halt, recur and return. Returning an updated context containing the result or an exceptional error.- Type Parameters:
R
- Return type of the Op- Parameters:
code
- Code to execute- Returns:
- Updated Context
-
invoke
Invokes a function within this context, returning an updated context. Handles function recur and return values. Keeps depth constant upon return.- Type Parameters:
R
- Return type of the function- Parameters:
fn
- Function to executeargs
- Arguments for function- Returns:
- Updated Context
-
executeLocalBinding
Execute an op, and bind the result to the given binding form in the lexical environment Binding form may be a destructuring form- Type Parameters:
I
- Result type of Context- Parameters:
bindingForm
- Binding formop
- Op to execute to get binding values- Returns:
- Context with local bindings updated
-
updateBindings
Updates local bindings with a given binding form- Type Parameters:
R
- Result type of Context- Parameters:
bindingForm
- Binding formargs
- Arguments to bind- Returns:
- Non-exceptional Context with local bindings updated, or an exceptional result if bindings fail
-
print
Description copied from class:AObject
Prints this Object to a readable String Representation -
getLocalBindings
-
withLocalBindings
Updates this Context with new local bindings. Doesn't affact result state (exceptional or otherwise)- Type Parameters:
R
- Return type of Context- Parameters:
newBindings
- New local bindings map to use.- Returns:
- Updated context
-
getAccountStatus
Gets the account status record, or null if not found- Parameters:
address
- Address of account- Returns:
- AccountStatus for the specified address, or null if the account does not exist
-
getDepth
public int getDepth() -
getOrigin
-
define
Defines a value in the environment of the current address- Parameters:
key
- Symbol of the mapping to createvalue
- Value to define- Returns:
- Updated context with symbol defined in environment
-
defineWithSyntax
Defines a value in the environment of the current address, updating the metadata- Parameters:
syn
- Syntax Object to define, containing a Symbol valuevalue
- Value to set of the given Symbol- Returns:
- Updated context with symbol defined in environment
-
undefine
Removes a definition mapping in the environment of the current address- Parameters:
key
- Symbol of the environment mapping to remove- Returns:
- Updated context with symbol definition removed from the environment, or this context if unchanged
-
expandCompile
Expand and compile a form in this Context.- Type Parameters:
R
- Return type of compiled op- Parameters:
form
- Form to expand and compile- Returns:
- Updated Context with compiled Op as result
-
compile
Compile a form in this Context. Form must already be fully expanded to a Syntax Object- Type Parameters:
R
- Return type of compiled op- Parameters:
expandedForm
- Form to compile- Returns:
- Updated Context with compiled Op as result
-
eval
Executes a form in the current context. Ops are executed directly. Other forms will be expanded and compiled before execution, unless *lang* is set, in which case they will be executed via the *lang* function.- Type Parameters:
R
- Return type of evaluation- Parameters:
form
- Form to evaluate- Returns:
- Context containing the result of evaluating the specified form
-
evalAs
Evaluates a form as another Address. Causes TRUST error if the Address is not controlled by the current address.- Type Parameters:
R
- Result type- Parameters:
address
- Address of Account in which to evaluateform
- Form to evaluate- Returns:
- Updated Context
-
query
Executes code as if run in the current account, but always discarding state changes.- Type Parameters:
R
- Result type- Parameters:
form
- Code to execute.- Returns:
- Context updated with only query result and juice consumed
-
queryAs
Executes code as if run in the specified account, but always discarding state changes.- Type Parameters:
R
- Result type- Parameters:
address
- Address of Account in which to execute the queryform
- Code to execute.- Returns:
- Context updated with only query result and juice consumed
-
handleQueryResult
Just take result and juice from query. Log and state not kept.- Type Parameters:
R
-- Parameters:
ctx
-- Returns:
-
compileAll
Compiles a sequence of forms in the current context. Returns a vector of ops in the updated Context. Maintains depth.- Type Parameters:
R
- Return type of compiled op.- Parameters:
forms
- A sequence of forms to compile- Returns:
- Updated context with vector of compiled forms
-
withJuice
-
withCompilerState
-
isExceptional
public boolean isExceptional()Tests if this Context holds an exceptional result. Ops should cancel and return exceptional results unchanged, unless they can handle them.- Returns:
- true if context has an exceptional value, false otherwise
-
isValidAccount
Tests if an Address is valid, i.e. refers to an existing Account- Parameters:
address
- Address to check. May be null- Returns:
- true if Account exists, false otherwise
-
isError
public boolean isError()Tests if this Context's current status contains an Error. Errors are an uncatchable subset of Exceptions.- Returns:
- true if context has an Error value, false otherwise
-
transfer
Transfers funds from the current address to the target. Uses no juice- Parameters:
target
- Target Address, will be created if does not already exist.amount
- Amount to transfer, must be between 0 and Amount.MAX_VALUE inclusive- Returns:
- Context with sent amount if the transaction succeeds, or an exceptional value if the transfer fails
-
transferMemoryAllowance
Transfers memory allowance from the current address to the target. Uses no juice- Parameters:
target
- Target Address, must already existamountToSend
- Amount of memory to transfer, must be between 0 and Amount.MAX_VALUE inclusive- Returns:
- Context with a null result if the transaction succeeds, or an exceptional value if the transfer fails
-
setMemory
Sets the memory allowance for the current account, buying / selling from the pool as necessary to ensure the correct final allowance- Parameters:
allowance
- New memory allowance- Returns:
- Context indicating the price paid for the allowance change (may be zero or negative for refund)
-
acceptFunds
Accepts offered funds for the given address. STATE error if offered amount is insufficient. ARGUMENT error if acceptance is negative.- Type Parameters:
R
- Type of result- Parameters:
amount
- Amount to accept- Returns:
- Updated context, with long amount accepted as result
-
actorCall
public <R extends ACell> Context<R> actorCall(Address target, long offer, String functionName, ACell... args)Executes a call to an Actor. Utility function which convert a java String function name- Type Parameters:
R
- Return type of Actor call- Parameters:
target
- Target Actor addressoffer
- Amount of Convex Coins to offer in Actor callfunctionName
- Symbol of function name defined by Actorargs
- Arguments to Actor function invocation- Returns:
- Context with result of Actor call (may be exceptional)
-
actorCall
public <R extends ACell> Context<R> actorCall(Address target, long offer, ACell functionName, ACell... args)Executes a call to an Actor.- Type Parameters:
R
- Return type of Actor call- Parameters:
target
- Target Actor addressoffer
- Amount of Convex Coins to offer in Actor callfunctionName
- Symbol of function name defined by Actorargs
- Arguments to Actor function invocation- Returns:
- Context with result of Actor call (may be exceptional)
-
deployActor
Deploys an Actor in this context. Argument argument must be an Actor generation code, which will be evaluated in the new Actor account to initialise the Actor Result will contain the new Actor address if successful, an exception otherwise.- Parameters:
code
- Actor initialisation code- Returns:
- Updated Context with Actor deployed, or an exceptional result
-
createAccount
Create a new Account with a given AccountKey (may be null for actors etc.)- Parameters:
key
- New Account Key- Returns:
- Updated context with new Account added
-
withError
-
withError
-
withError
-
withArityError
-
withCompileError
-
withBoundsError
-
withCastError
-
withCastError
-
withCastError
-
withCastError
-
withCastError
-
getErrorCode
Gets the error code of this context's return value- Returns:
- The ErrorType of the current exceptional value, or null if there is no error.
-
getError
Gets the Error from this Context, or null if not an Error- Returns:
- The ErrorType of the current exceptional value, or null if there is no error.
-
withAssertError
-
withFundsError
-
withArgumentError
-
getTimeStamp
Gets the current timestamp for this context. The timestamp is the greatest timestamp of all blocks in consensus (including the currently executing block).- Returns:
- Timestamp in milliseconds since UNIX epoch
-
schedule
Schedules an operation for the specified future timestamp. Handles integrity checks and schedule juice.- Parameters:
time
- Timestamp at which to schedule the op.op
- Operation to schedule.- Returns:
- Updated context, with scheduled time as the result
-
setDelegatedStake
Sets the delegated stake on a specified peer to the specified level. May set to zero to remove stake. Stake will be capped by current balance.- Parameters:
peerKey
- Peer Account key on which to stakenewStake
- Amount to stake- Returns:
- Context with amount of coins transferred to Peer as result (may be negative if stake withdrawn)
-
setPeerStake
Sets the stake for a given Peer, transferring coins from the current address.- Parameters:
peerKey
- Peer Account Key for which to update StakenewStake
- New stake for Peer- Returns:
- Updated Context
-
createPeer
Creates a new peer with the specified stake. The accountKey must not be in the list of peers. The accountKey must be assigend to the current transaction address Stake must be greater than 0. Stake must be less than to the account balance.- Parameters:
accountKey
- Peer Account key to create the PeerStatusinitialStake
- Initial stake amount- Returns:
- Context with final take set
-
setPeerData
Sets peer data.- Parameters:
peerKey
- Peer to set data fordata
- Map of data to set for the peer- Returns:
- Context with final peer data set
-
setHolding
Sets the holding for a specified target account. Returns NOBODY exception if account does not exist.- Parameters:
targetAddress
- Account address at which to set the holdingvalue
- Value to set for the holding.- Returns:
- Updated context
-
setController
Sets the controller for the current Account- Type Parameters:
R
- Result type- Parameters:
address
- New controller Address- Returns:
- Context with current Account controller set
-
setAccountKey
Sets the public key for the current account- Type Parameters:
R
- Result type- Parameters:
publicKey
- New Account Public Key- Returns:
- Context with current Account Key set
-
withAccountStatus
protected <R extends ACell> Context<R> withAccountStatus(Address target, AccountStatus accountStatus) -
forkWithAddress
Switches the context to a new address, creating a new execution context. Suitable for testing.- Type Parameters:
R
- Result type- Parameters:
newAddress
- New Address to use.- Returns:
- Result type of new Context
-
fork
Forks this context, creating a new copy of all local state- Type Parameters:
R
- Result type of new Context- Returns:
- A new forked Context
-
createEncoding
Description copied from class:AObject
Creates a Blob object representing this object. Should be called only after the cached encoding has been checked.- Specified by:
createEncoding
in classAObject
- Returns:
- Blob Encoding of Object
-
appendLog
Appends a log entry for the current address.- Parameters:
values
- Values to log- Returns:
- Updated Context
-
getLog
Gets the log map for the current context.- Returns:
- BlobMap of addresses to log entries created in the course of current execution context.
-
lookupCNS
-
expand
Expands a form with the default *initial-expander*- Parameters:
form
- Form to expand- Returns:
- Syntax Object resulting from expansion.
-
expand
-
lookupExpander
Looks up an expander from a form in this context- Parameters:
form
- Form which might be an expander reference- Returns:
- Expander instance, or null if no expander found
-