Package convex.core.lang

Class Context

java.lang.Object

convex.core.lang.Context

public class Context
extends Object

Representation of CVM execution 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

Modifier and Type	Class	Description
protected static final class	Context.ChainState	Inner class for less-frequently changing CVM state related to Actor execution Should save some allocation / GC on average, since it will change less frequently than the surrounding Context and can be cheaply copied by reference.
static final class	Context.CompilerState	Inner class compiler state.

Field Summary

Fields

Modifier and Type	Field	Description
static final AVector<ACell>	EMPTY_BINDINGS

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Context(Context.ChainState chainState, long juice, long juiceLimit, AVector<ACell> localBindings2, ACell result, int depth, AExceptional exception, AVector<AVector<ACell>> log, Context.CompilerState comp)

Method Summary

Modifier and Type	Method	Description
Context	acceptFunds(long amount)	Accepts offered funds for the given address.
Context	actorCall(ACell target, long offer, ACell functionName, ACell... args)	Executes a call to an Actor.
Context	actorCall(ACell target, long offer, String functionName, ACell... args)	Executes a call to an Actor.
Context	appendLog(AVector<ACell> values)	Appends a log entry for the current address.
boolean	checkJuice(long gulp)	Checks if there is sufficient juice for a given gulp of consumption.
Context	compile(ACell expandedForm)	Compile a form in this Context.
Context	compileAll(ASequence<ACell> forms)	Compiles a sequence of forms in the current context.
Context	completeTransaction(State initialState, ResultContext rc)	Performs key actions at the end of a transaction: Refunds juice Accumulates used juice fees in globals Increments sequence number
Context	consumeJuice(long gulp)	Consumes juice, returning an updated context if sufficient juice remains or an exceptional JUICE error.
static Context	createFake(State state)	Creates an execution context with a default actor address.
static Context	createFake(State state, Address origin)	Creates a "fake" execution context for the given address.
static Context	createInitial(State state, Address origin, long juiceLimit)	Creates an initial execution context with the specified actor as origin, and reserving the appropriate amount of juice.
Context	createPeer(AccountKey accountKey, long initialStake)	Creates a new peer with the specified stake.
Context	define(Symbol key, ACell value)	Defines a value in the environment of the current address
Context	defineWithSyntax(Syntax syn, ACell value)	Defines a value in the environment of the current address, updating the metadata
Context	deploy(ACell... code)	Deploys a new account.
Context	eval(ACell form)	Executes a form in the current context.
Context	evalAs(Address target, ACell form)	Evaluates a form as another Address.
<T extends ACell> Context	exec(AOp<T> op)	Executes an op as a top level instruction (no local bindings)
Context	execute(AOp<?> op)	Executes an Op within this context, returning an updated context.
Context	executeLocalBinding(ACell bindingForm, AOp<?> op)	Execute an op, and bind the result to the given binding form in the lexical environment Binding form may be a destructuring form
Context	expand(ACell form)	Expands a form with the default *initial-expander*
Context	expand(AFn<?> expander, ACell form, AFn<?> cont)
Context	expandCompile(ACell form)	Expand and compile a form in this Context.
Context	fork()	Forks this context, creating a new copy of all local state but clears any exceptional value
Context	forkWithAddress(Address newAddress)	Switches the context to a new address, creating a new execution context.
AccountStatus	getAccountStatus()	Gets the account status for the current Address
AccountStatus	getAccountStatus(Address address)	Gets the account status record, or null if not found
Address	getAddress()	Gets the address of the currently executing Account.
long	getBalance()	Gets the balance for the current Address
long	getBalance(Address address)	Gets the balance for the specified Address
Address	getCaller()	Gets the caller of the currently executing context.
Context.CompilerState	getCompilerState()	Gets the compiler state
int	getDepth()
AHashMap<Symbol,ACell>	getEnvironment()	Gets the current Environment
ErrorValue	getError()	Gets the Error from this Context, or null if not an Error
ACell	getErrorCode()	Gets the error code of this context's return value
AExceptional	getExceptional()	Gets the exceptional value from this context.
Index<Address,ACell>	getHoldings()	Gets the holdings map for the current account.
long	getJuiceAvailable()	Get the juice available in this Context
long	getJuiceLimit()	Get the juice limit in this Context
long	getJuiceUsed()	Get the juice used so far in this Context
AVector<ACell>	getLocalBindings()
AVector<AVector<ACell>>	getLog()	Gets the log map for the current context.
AHashMap<Symbol,AHashMap<ACell,ACell>>	getMetadata()	Gets the metadata for the current Account
long	getOffer()	Get the current offer from this Context
Address	getOrigin()
<R extends ACell> R	getResult()	Gets the result from this context.
ACell	getScope()	Gets the scope of the currently executing context.
State	getState()	Get the latest state from this Context
CVMLong	getTimeStamp()	Gets the current timestamp for this context.
Object	getValue()	Gets the resulting value from this context.
Context	handleStateResults(Context returnContext, boolean rollback)	Handle results at the end of an execution boundary (actor call, transaction etc.)
Context	invoke(AFn<?> fn, ACell... args)	Invokes a function within this context, returning an updated context.
boolean	isError()	Tests if this Context's current status contains an Error.
boolean	isExceptional()	Tests if this Context holds an exceptional result.
boolean	isValidAccount(Address address)	Tests if an Address is valid, i.e.
Context	lookup(Symbol symbol)	Looks up a symbol's value in the current execution context, without any effect on the Context (no juice consumed etc.)
Context	lookupCNS(String name)
Context	lookupDefiningAddress(Address address, Symbol sym)	Looks up the address of the account that defines a given Symbol
Context	lookupDynamic(Address address, Symbol symbol)	Looks up a value in the dynamic environment.
Context	lookupDynamic(Symbol symbol)	Looks up a value in the dynamic environment.
MapEntry<Symbol,ACell>	lookupDynamicEntry(Address address, Symbol sym)	Looks up an environment entry for a specific address without consuming juice.
AFn<ACell>	lookupExpander(ACell form)	Looks up an expander from a form in this context
AHashMap<ACell,ACell>	lookupMeta(Address address, Symbol sym)	Looks up Metadata for the given symbol in this context
AHashMap<ACell,ACell>	lookupMeta(Symbol sym)	Looks up Metadata for the given symbol in this context
ACell	lookupValue(Address address, Symbol sym)	Looks up value for the given symbol in this context
ACell	lookupValue(Symbol sym)	Looks up value for the given symbol in this context
<T extends ACell> T	lookupValue(String symName)	Looks up value for the given symbol in this context
boolean	print(BlobBuilder bb, long limit)
Context	queryAs(Address address, ACell form)	Executes code as if run in the specified account, but always rolling back state changes.
Context	run(ACell code)	Executes a form at the top level.
Context	run(AOp<?> op)	Executes an Op at the top level in a new forked Context.
Context	schedule(long time, AOp<?> op)	Schedules an operation for the specified future timestamp.
Context	setAccountKey(AccountKey publicKey)	Sets the public key for the current account
Context	setController(ACell address)	Sets the controller for the current Account
Context	setDelegatedStake(AccountKey peerKey, long newStake)	Sets the delegated stake on a specified peer to the specified level.
Context	setHolding(Address targetAddress, ACell value)	Sets the holding for a specified target account.
Context	setMemory(long allowance)	Sets the memory allowance for the current account, buying / selling from the pool as necessary to ensure the correct final allowance
Context	setParent(Address address)	Sets the parent for the current Account
Context	setPeerData(AccountKey peerKey, AHashMap<ACell,ACell> data)	Sets peer data.
Context	setPeerStake(AccountKey peerKey, long newStake)	Sets the stake for a given Peer, transferring coins from the current address.
String	toString()
Context	transfer(Address target, long amount)	Transfers funds from the current address to the target.
Context	transferMemoryAllowance(Address target, CVMLong amountToSend)	Transfers memory allowance from the current address to the target.
Context	undefine(Symbol key)	Removes a definition mapping in the environment of the current address
Context	updateBindings(ACell bindingForm, Object args)	Updates local bindings with a given binding form
protected Context	withAccountStatus(Address target, AccountStatus accountStatus)
Context	withArgumentError(String message)
Context	withArityError(String message)
Context	withAssertError(String message)
Context	withBoundsError(long index)
Context	withCastError(int argIndex, ACell[] args, AType klass)
Context	withCastError(int argIndex, AType klass)
Context	withCastError(ACell a, AType klass)
Context	withCastError(ACell a, String message)
Context	withCastError(AType klass)
Context	withCompileError(String message)
Context	withCompilerState(Context.CompilerState comp)
Context	withError(Keyword error)
Context	withError(Keyword errorCode, ACell rs)
Context	withError(Keyword errorCode, AString message)
Context	withError(Keyword errorCode, String message)
Context	withError(ErrorValue error)
Context	withException(long gulp, AExceptional value)
Context	withException(AExceptional exception)
Context	withFundsError(String message)
Context	withJuice(long newJuice)
Context	withJuiceError()	Returns this context with a JUICE error, consuming all juice.
Context	withJuiceLimit(long newJuiceLimit)
Context	withLocalBindings(AVector<ACell> newBindings)	Updates this Context with new local bindings.
Context	withResult(long gulp, ACell value)
Context	withResult(ACell value)	Returns a context updated with the specified result.
Context	withState(State newState)
Context	withSyntaxError(String message)
Context	withUndeclaredError(Symbol sym)
Context	withValue(Object value)	Updates this context with a given value, which may either be a normal result or exceptional value

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

EMPTY_BINDINGS

public static final AVector<ACell> EMPTY_BINDINGS

Constructor Details

Context

protected Context(Context.ChainState chainState,
 long juice,
 long juiceLimit,
 AVector<ACell> localBindings2,
 ACell result,
 int depth,
 AExceptional exception,
 AVector<AVector<ACell>> log,
 Context.CompilerState comp)

Method Details

createFake

public static Context createFake(State state)

Creates an execution context with a default actor address. Useful for Testing

Parameters:

state - State to use for this Context

Returns:

Fake context

createFake

public static Context createFake(State state,
 Address origin)

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 Context

origin - Origin address to use

Returns:

Fake context

createInitial

public static Context createInitial(State state,
 Address origin,
 long juiceLimit)

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 Context

origin - Origin Address for Context

juiceLimit - Initial juice requested for Context

Returns:

Initial execution context with reserved juice.

completeTransaction

public Context completeTransaction(State initialState,
 ResultContext rc)

Performs key actions at the end of a transaction:

• Refunds juice
• Accumulates used juice fees in globals
• Increments sequence number

Parameters:

initialState - State before transaction execution (after prepare)

rc - Juice price of current execution

Returns:

Updated context

withState

public Context withState(State newState)

getState

public State getState()

Get the latest state from this Context

Returns:

State instance

getJuiceUsed

public long getJuiceUsed()

Get the juice used so far in this Context

Returns:

Juice used

getJuiceAvailable

public long getJuiceAvailable()

Get the juice available in this Context

Returns:

Juice available

getJuiceLimit

public long getJuiceLimit()

Get the juice limit in this Context

Returns:

Juice limit

getOffer

public long getOffer()

Get the current offer from this Context

Returns:

Offered amount in Convex copper

getEnvironment

public AHashMap<Symbol,ACell> getEnvironment()

Gets the current Environment

Returns:

Environment map

getCompilerState

public Context.CompilerState getCompilerState()

Gets the compiler state

Returns:

CompilerState instance

getMetadata

public AHashMap<Symbol,AHashMap<ACell,ACell>> getMetadata()

Gets the metadata for the current Account

Returns:

Metadata map

consumeJuice

public Context consumeJuice(long gulp)

Consumes juice, returning an updated context if sufficient juice remains or an exceptional JUICE error.

Parameters:

gulp - Amount of juice 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

public Context lookup(Symbol symbol)

Looks up a symbol's value in the current execution context, without any effect on the Context (no juice consumed etc.)

Parameters:

symbol - Symbol to look up. May be qualified

Returns:

Context with the result of the lookup (may be an undeclared exception)

lookupDynamic

public Context lookupDynamic(Symbol symbol)

Looks up a value in the dynamic environment. Consumes no juice. Returns an UNDECLARED exception if the symbol cannot be resolved.

Parameters:

symbol - Symbol to look up

Returns:

Updated Context

lookupDynamic

public Context lookupDynamic(Address address,
 Symbol symbol)

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

Parameters:

address - Address of account in which to look up value

symbol - Symbol to look up

Returns:

Updated Context

lookupMeta

public AHashMap<ACell,ACell> lookupMeta(Symbol sym)

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

public AHashMap<ACell,ACell> lookupMeta(Address address,
 Symbol sym)

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

lookupDefiningAddress

public Context lookupDefiningAddress(Address address,
 Symbol sym)

Looks up the address of the account that defines a given Symbol

Parameters:

address - Address to look up in first instance (null for current address).

sym - Symbol to look up

Returns:

Context with result as the address defining the given symbol (or null if undeclared)

lookupValue

public <T extends ACell> T lookupValue(String symName)

Looks up value for the given symbol in this context

Parameters:

symName - Symbol name to look up, as a Java String for convenience

Returns:

Value for the given symbol or null if undeclared

lookupValue

public ACell lookupValue(Symbol sym)

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

public ACell lookupValue(Address address,
 Symbol sym)

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

public MapEntry<Symbol,ACell> lookupDynamicEntry(Address address,
 Symbol sym)

Looks up an environment entry for a specific address without consuming juice.

Parameters:

address - Address of Account in which to look up entry

sym - Symbol to look up

Returns:

Environment entry

getAccountStatus

public AccountStatus getAccountStatus()

Gets the account status for the current Address

Returns:

AccountStatus object, or null if not found

getHoldings

public Index<Address,ACell> 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()

Gets the balance for the current Address

Returns:

Balance in Convex Coins

getBalance

public long getBalance(Address address)

Gets the balance for the specified Address

Parameters:

address - Address to check balance for

Returns:

Balance in Convex Coins

getCaller

public Address 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

getScope

public ACell getScope()

Gets the scope of the currently executing context. Will be null if no scope was set

Returns:

Caller of the currently executing context

getAddress

public Address 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

public <R extends ACell> R getResult()

Gets the result from this context. Throws an Error if the context return value is exceptional.

Returns:

Result value from this Context.

getValue

public Object 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

public AExceptional getExceptional()

Gets the exceptional value from this context. Throws an Error is the context return value is normal.

Returns:

an AExceptional instance

withResult

public Context withResult(ACell value)

Returns a context updated with the specified result. Context may become exceptional depending on the result type.

Parameters:

value - Value

Returns:

Context updated with the specified result.

withValue

public Context withValue(Object value)

Updates this context with a given value, which may either be a normal result or exceptional value

Parameters:

value - Value

Returns:

Context updated with the specified result value.

withResult

public Context withResult(long gulp,
 ACell value)

withJuiceError

public Context withJuiceError()

Returns this context with a JUICE error, consuming all juice.

Returns:

Exceptional Context signalling JUICE error.

withException

public Context withException(AExceptional exception)

withException

public Context withException(long gulp,
 AExceptional value)

execute

public Context execute(AOp<?> op)

Executes an Op within this context, returning an updated context.

Parameters:

op - Op to execute

Returns:

Updated Context

run

public Context run(AOp<?> op)

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.

Parameters:

op - Op to execute

Returns:

Updated Context

run

public Context run(ACell code)

Executes a form at the top level. Handles top level halt, recur and return. Returning an updated context containing the result or an exceptional error.

Parameters:

code - Code to execute

Returns:

Updated Context

invoke

public Context invoke(AFn<?> fn,
 ACell... args)

Invokes a function within this context, returning an updated context. Handles function recur and return values. Keeps depth constant upon return.

Parameters:

fn - Function to execute

args - Arguments for function

Returns:

Updated Context

executeLocalBinding

public Context executeLocalBinding(ACell bindingForm,
 AOp<?> op)

Execute an op, and bind the result to the given binding form in the lexical environment Binding form may be a destructuring form

Parameters:

bindingForm - Binding form

op - Op to execute to get binding values

Returns:

Context with local bindings updated

updateBindings

public Context updateBindings(ACell bindingForm,
 Object args)

Updates local bindings with a given binding form

Parameters:

bindingForm - Binding form

args - Arguments to bind

Returns:

Non-exceptional Context with local bindings updated, or an exceptional result if bindings fail

print

public boolean print(BlobBuilder bb,
 long limit)

toString

public String toString()

Overrides:

toString in class Object

getLocalBindings

public AVector<ACell> getLocalBindings()

withLocalBindings

public Context withLocalBindings(AVector<ACell> newBindings)

Updates this Context with new local bindings. Doesn't affect result state (exceptional or otherwise)

Parameters:

newBindings - New local bindings map to use.

Returns:

Updated context

getAccountStatus

public AccountStatus getAccountStatus(Address address)

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

public Address getOrigin()

define

public Context define(Symbol key,
 ACell value)

Defines a value in the environment of the current address

Parameters:

key - Symbol of the mapping to create

value - Value to define

Returns:

Updated context with symbol defined in environment

defineWithSyntax

public Context defineWithSyntax(Syntax syn,
 ACell value)

Defines a value in the environment of the current address, updating the metadata

Parameters:

syn - Syntax Object to define, containing a Symbol value

value - Value to set of the given Symbol

Returns:

Updated context with symbol defined in environment

undefine

public Context undefine(Symbol key)

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

public Context expandCompile(ACell form)

Expand and compile a form in this Context.

Parameters:

form - Form to expand and compile

Returns:

Updated Context with compiled Op as result

compile

public Context compile(ACell expandedForm)

Compile a form in this Context. Form must already be fully expanded to a Syntax Object

Parameters:

expandedForm - Form to compile

Returns:

Updated Context with compiled Op as result

eval

public Context eval(ACell form)

Executes a form in the current context. Ops are executed directly. Other forms will be expanded and compiled before execution, according to `compile` as defined in the current environment

Parameters:

form - Form to evaluate

Returns:

Context containing the result of evaluating the specified form

exec

public <T extends ACell> Context exec(AOp<T> op)

Executes an op as a top level instruction (no local bindings)

Type Parameters:

T - Type of Op result

Parameters:

op - Op to execute

Returns:

Updated Context

evalAs

public Context evalAs(Address target,
 ACell form)

Evaluates a form as another Address. Causes TRUST error if the Address is not controlled by the current address.

Parameters:

target - Address of Account in which to evaluate

form - Form to evaluate

Returns:

Updated Context

queryAs

public Context queryAs(Address address,
 ACell form)

Executes code as if run in the specified account, but always rolling back state changes.

Parameters:

address - Address of Account in which to execute the query

form - Code to execute.

Returns:

Context updated with only query result and juice consumed

compileAll

public Context compileAll(ASequence<ACell> forms)

Compiles a sequence of forms in the current context. Returns a vector of ops in the updated Context. Maintains depth.

Parameters:

forms - A sequence of forms to compile

Returns:

Updated context with vector of compiled forms

withJuice

public Context withJuice(long newJuice)

withJuiceLimit

public Context withJuiceLimit(long newJuiceLimit)

withCompilerState

public Context withCompilerState(Context.CompilerState comp)

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

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

isValidAccount

public boolean isValidAccount(Address address)

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

transfer

public Context transfer(Address target,
 long amount)

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

public Context transferMemoryAllowance(Address target,
 CVMLong amountToSend)

Transfers memory allowance from the current address to the target. Uses no juice

Parameters:

target - Target Address, must already exist

amountToSend - 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

public Context setMemory(long allowance)

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

public Context acceptFunds(long amount)

Accepts offered funds for the given address. STATE error if offered amount is insufficient. ARGUMENT error if acceptance is negative.

Parameters:

amount - Amount to accept

Returns:

Updated context, with long amount accepted as result

actorCall

public Context actorCall(ACell target,
 long offer,
 String functionName,
 ACell... args)

Executes a call to an Actor. Utility function which convert a java String function name

Parameters:

target - Target Actor address or scope vector

offer - Amount of Convex Coins to offer in Actor call

functionName - Symbol of function name defined by Actor

args - Arguments to Actor function invocation

Returns:

Context with result of Actor call (may be exceptional)

actorCall

public Context actorCall(ACell target,
 long offer,
 ACell functionName,
 ACell... args)

Executes a call to an Actor.

Parameters:

target - Target Actor address

offer - Amount of Convex Coins to offer in Actor call

functionName - Symbol of function name defined by Actor

args - Arguments to Actor function invocation

Returns:

Context with result of Actor call (may be exceptional)

handleStateResults

public Context handleStateResults(Context returnContext,
 boolean rollback)

Handle results at the end of an execution boundary (actor call, transaction etc.)

Parameters:

returnContext - Context containing return from child transaction / call

rollback - If true, always rolls back state effects

Returns:

Updated parent context

deploy

public Context deploy(ACell... code)

Deploys a new account. Arguments must be an account setup code, which will be evaluated in the new account. Result will contain the new address if successful, an exception otherwise.

Parameters:

code - Account initialisation code

Returns:

Updated Context with account deployed, or an exceptional result

withError

public Context withError(Keyword error)

withError

public Context withError(Keyword errorCode,
 String message)

withError

public Context withError(Keyword errorCode,
 AString message)

withError

public Context withError(Keyword errorCode,
 ACell rs)

withError

public Context withError(ErrorValue error)

withArityError

public Context withArityError(String message)

withCompileError

public Context withCompileError(String message)

withSyntaxError

public Context withSyntaxError(String message)

withUndeclaredError

public Context withUndeclaredError(Symbol sym)

withBoundsError

public Context withBoundsError(long index)

withCastError

public Context withCastError(int argIndex,
 AType klass)

withCastError

public Context withCastError(int argIndex,
 ACell[] args,
 AType klass)

withCastError

public Context withCastError(ACell a,
 AType klass)

withCastError

public Context withCastError(AType klass)

withCastError

public Context withCastError(ACell a,
 String message)

getErrorCode

public ACell 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

public ErrorValue 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

public Context withAssertError(String message)

withFundsError

public Context withFundsError(String message)

withArgumentError

public Context withArgumentError(String message)

getTimeStamp

public CVMLong 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

public Context schedule(long time,
 AOp<?> op)

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

public Context setDelegatedStake(AccountKey peerKey,
 long newStake)

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 stake

newStake - Amount to stake

Returns:

Context with amount of coins transferred to Peer as result (may be negative if stake withdrawn)

setPeerStake

public Context setPeerStake(AccountKey peerKey,
 long newStake)

Sets the stake for a given Peer, transferring coins from the current address.

Parameters:

peerKey - Peer Account Key for which to update Stake

newStake - New stake for Peer

Returns:

Updated Context

createPeer

public Context createPeer(AccountKey accountKey,
 long initialStake)

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 PeerStatus

initialStake - Initial stake amount

Returns:

Context with final take set

setPeerData

public Context setPeerData(AccountKey peerKey,
 AHashMap<ACell,ACell> data)

Sets peer data.

Parameters:

peerKey - Peer to set data for

data - Map of data to set for the peer

Returns:

Context with final peer data set

setHolding

public Context setHolding(Address targetAddress,
 ACell value)

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 holding

value - Value to set for the holding.

Returns:

Updated context

setController

public Context setController(ACell address)

Sets the controller for the current Account

Parameters:

address - New controller Address / scoped reference

Returns:

Context with current Account controller set

setParent

public Context setParent(Address address)

Sets the parent for the current Account

Parameters:

address - New parent Address

Returns:

Context with current Account parent set

setAccountKey

public Context setAccountKey(AccountKey publicKey)

Sets the public key for the current account

Parameters:

publicKey - New Account Public Key

Returns:

Context with current Account Key set

withAccountStatus

protected Context withAccountStatus(Address target,
 AccountStatus accountStatus)

forkWithAddress

public Context forkWithAddress(Address newAddress)

Switches the context to a new address, creating a new execution context. Suitable for testing.

Parameters:

newAddress - New Address to use.

Returns:

Result type of new Context

fork

public Context fork()

Forks this context, creating a new copy of all local state but clears any exceptional value

Returns:

A new forked Context

appendLog

public Context appendLog(AVector<ACell> values)

Appends a log entry for the current address.

Parameters:

values - Values to log

Returns:

Updated Context

getLog

public AVector<AVector<ACell>> getLog()

Gets the log map for the current context.

Returns:

Index of addresses to log entries created in the course of current execution context.

lookupCNS

public Context lookupCNS(String name)

expand

public Context expand(ACell form)

Expands a form with the default *initial-expander*

Parameters:

form - Form to expand

Returns:

Syntax Object resulting from expansion.

expand

public Context expand(AFn<?> expander,
 ACell form,
 AFn<?> cont)

lookupExpander

public AFn<ACell> lookupExpander(ACell form)

Looks up an expander from a form in this context

Parameters:

form - Form which might be an expander reference (either a symbol or (lookup...) form)

Returns:

Expander instance, or null if no expander found