Ethereum Alarm Clock GUI Implementation Guide
This guide is an attempt to provide information to ease the process of an implementation of a graphical front-end on the Ethereum Alarm Clock service. It should be a document that you can consult to understand what parameters you need to include and the user cases to cover while building your interface.
What will be implemented?
A graphical interface to the Ethereum Alarm Clock. User functionalities will include the ability to schedule a transaction in a cohesive flow. It may also include the ability to manually execute a transaction request (althought for the most past this will be done more efficiently by clients such as eac.js
)
Basics
The ethereum alarm clock consists of a collection of smart contracts that interoperate with each other on-chain. Whenever a user schedules a new transaction, it will use these contracts to deploy a new contract that contains all of the execution data set by the user. The contracts keep track of this transaction request
in a database contract that exposes a public API to be queriable by off-chain code.
Servers that are running an execution client will be scanning the blockchain for scheduled transaction requests
and sending claim or execution transactions to them. Clients will be doing most of the execution work "behind the scenes" for users and ideally, they will never have to worry about their transaction being executed on time.
In order to provide incentive to execution clients, when users schedule transactions they will include a payment
variable.
If you would like a complete introduction to the Ethereum Alarm Clock infrastructure, we recommend the official docs.
Schedulers
You will be working with the high-level APIs of the Scheduler contracts. There are two types of Scheduler, a TimestampScheduler
and a BlockScheduler
. The only difference between these two is the unit of time that each accepts for its scheduling paremeters. As you might guess, the TimestampScheduler
requires all input to be as a Unix timestamp while the BlockScheduler
takes in input as Ethereum block numbers. Otherwise, both Schedulers have the same public function schedule()
to accept input. Here is the Solidity interface:
function schedule(address _toAddress,
bytes _callData,
uint[8] _uintArgs)
doReset
public payable returns (address);
Schedule params
The schedule function takes three parameters, an Ethereum address, an array of bytes (a Javascript Buffer
), and an array of eight unsigned integers. The eight unsigned integers are:
- _uintArgs [0] The callGas to be sent with the scheduled transaction.
- _uintArgs [1] The callValue to be sent with the scheduled transaction.
- _uintArgs [2] The execution windowSize.
- _uintArgs [3] The (block or timestamp) of the execution windowStart.
- _uintArgs [4] The gasPrice which will be used to execute this transaction.
- _uintArgs [5] The donation value attached to this transaction.
- _uintArgs [6] The payment value attached to this transaction.
- _uintArgs [7] The requiredDeposit to claim this transaction.
The scheduling party must also send enough value to cover the endowment
of the transaction request. The endowment
is calculated like so:
endowment = payment + donation * 2 + callGas * gasPrice + 180000 * gasPrice + callValue
The endowment
is required because the scheduler of the transaction must pay all the gas costs, as well as cover the value and the payment
and donation
costs up front.
Validation
The Schedulers will use the RequestFactory
contract to perform some verification checks on the input it recieves and bubble up a ValidationError
event if one is encountered. The front-end GUI should be able to read these events if they happen and notify the use why their transaction was not able to go through. However, it may be better if the front-end code employed validation checks to prevent the error ever reaching the blockchain.
Some verification check you will need to be aware of include:
Insufficient Endowment
The amount sent in the transaction must be at least the sum computed as the endowment
.
Call Gas too High
The maximum callGas sent with the transaction is the current_network_gasLimit - 140000
where 140000
is the gas overhead of execution.
Empty To Address
The toAddress
cannot be a null address 0x0000000000000000000000000000000000000000
For a full list of ValidationError
see this page of the docs.
Necessary Options
You will need to present an option for the user to switch between block-based scheduling and timestamp-based scheduling. This could be accomplished by the implementation of a switch or checkbox, or perhaps a drop-down menu.
To be continued...