PredicatePlugin¶
Description¶
Clients need a way to execute state transitions for a given predicate. However, it’s too slow and complex to execute these state transitions in a virtual version of the EVM. As a result, Predicates MUST supply client-side code, called a predicate plugin, that can compute state transitions. Predicate plugins MUST conform a standard interface as described below.
Information Sources¶
Predicate plugins have access to various external sources of information. Plugins can use this information for various reasons, including the execution of state transitions. All information available to a plugin MUST also be available to the corresponding predicate contract on Ethereum.
Ethereum Contract Queries¶
Predicate plugins have access to any information available on Ethereum. As plugins are effectively native implementations of their contract counter-parts, plugins should be careful not to rely on information not available to the contract (like event logs).
Plasma State Queries¶
Predicate contracts on Ethereum can be fed information about the state of the plasma chain. Predicate plugins are therefore given a reference to StateManager and HistoryManager that permit the plugin to make queries about the existence (or non-existence) of a given StateUpdate in the plasma chain.
Plasma State Updates¶
Predicates MUST be able to insert state updates into the local plasma chain. Most predicates SHOULD NOT use this behavior, but certain predicates may require to function correctly.
API¶
Methods¶
executeStateTransition¶
async function executeStateTransition(
input: StateUpdate,
transaction: Transaction
): Promise<StateUpdate>
Description¶
Executes a transaction and returns the resulting state upate.
Parameters¶
input
-StateUpdate
: Previous StateUpdate that the transaction acts upon.transaction
-Transaction
: Transaction to execute.
Returns¶
Promise<StateUpdate>
: Resulting StateUpdate created by the application of the transaction.
queryState¶
async function queryState(stateUpdate: StateUpdate, method: string, parameters: string[]): Promise<string[]>
Description¶
Performs a query on a given state update.
Parameters¶
stateUpdate
-StateUpdate
: The StateUpdate object to perform a query on.method
-string
: Name of the query method to call.parameters
-string[]
: Additional parameters to the query.
getAdditionalHistoryProof¶
async function getAdditionalHistoryProof
transaction: Transaction
): Promise<HistoryProof>
Description¶
Predicates may specify rely on the existence (or non-existence) of a given StateUpdate in the plasma chain. Whenever this is the case, the client must verify the history proof for that StateUpdate
. This method allows a predicate to specify any additional history proof information that may be necessary to verify these extra StateUpdate
objects.
Parameters¶
transaction
-Transaction
: The Transaction that may require additional proof data.
Returns¶
Promise<HistoryProof>
: The HistoryProof object that contains the extra proof data. May be an empty array if the transaction requires no additional history proof data.
canReplaceTransaction¶
async function canReplaceTransaction(
oldTransaction: Transaction,
newTransaction: Transaction
): Promise<boolean>
Description¶
Plasma blocks are composed of commitments to StateUpdate objects. Each StateUpdate
is computed from a previous StateUpdate
and a Transaction. It’s possible for one transaction to generate the same StateUpdate
as another transaction, and therefore still be a valid component of a history proof, but have significantly less overhead than the other. Clients may wish to “replace” one transaction with another to reduce proof overhead.
Predicates can define an arbitrary heuristic within this method to determine if one transaction is preferable to another.
Parameters¶
oldTransaction
-Transaction
: Original Transaction to be replaced.newTransaction
-Transaction
: New Transaction to replace the original.
Returns¶
boolean
: true
if the newer transaction should replace the older one, false
otherwise.
onTransitionFrom¶
async function onTransitionFrom(
transaction: Transaction,
from: StateUpdate,
to: StateUpdate,
verifiedRanges: Range[]
): Promise<void>
Description¶
Hook called whenever a StateUpdate locked by the predicate has been transitioned away from. Predicates may wish to use this hook to carry out some internal logic.
Parameters¶
transaction
-Transaction
: The Transaction which executed a state transition.from
-StateUpdate
: The old StateUpdate transitioned away from by the transaction.to
-StateUpdate
: The new StateUpdate created by the transaction.verifiedRanges
-Range[]
: Parts of the range described byto
with a fully verified history. It’s possible that a transaction creates a StateUpdate with only a partially verified history. For example, we may have a transaction that sends state objects(0, 100)
but have only verified(0, 50)
. This is considered valid behavior as we simply ignore(50, 100)
until we have its full history.
Returns¶
Promise<void>
: Promise that resolves once the predicate has executed some logic for the hook.
onTransitionTo¶
async function onTransitionTo(
transaction: Transaction,
from: StateUpdate,
to: StateUpdate,
verifiedRanges: Range[]
): Promise<void>
Description¶
Hook called whenever a Transaction creates a new StateUpdate locked by the predicate. Predicates may wish to use this hook to carry out some internal logic.
Parameters¶
transaction
-Transaction
: The Transaction which executed a state transition.from
-StateUpdate
: The old StateUpdate transitioned away from by the transaction.to
-StateUpdate
: The new StateUpdate created by the transaction.verifiedRanges
-Range[]
: Parts of the range described byto
with a fully verified history. It’s possible that a transaction creates a StateUpdate with only a partially verified history. For example, we may have a transaction that sends state objects(0, 100)
but have only verified(0, 50)
. This is considered valid behavior as we simply ignore(50, 100)
until we have its full history.
Returns¶
Promise<void>
: Promise that resolves once the predicate has executed some logic for the hook.