Request Factory

class RequestFactory


The RequestFactory contract is the lowest level API for creating transaction requests. It handles:

  • Validation and Deployment of TransactionRequest contracts
  • Tracking of all addresses that it has deployed.

This contract is designed to allow tuning of all transaction parameters and is probably the wrong API to integrate with if your goal is to simply schedule transactions for later execution. The Request Factory API is likely the right solution for these use cases.


//pragma solidity 0.4.1;

contract RequestFactoryInterface {
    event RequestCreated(address request);

    function createRequest(address[3] addressArgs,
                           uint[11] uintArgs,
                           bytes callData) returns (address);
    function validateRequestParams(address[3] addressArgs,
                                   uint[11] uintArgs,
                                   bytes callData,
                                   uint endowment) returns (bool[7]);
    function createValidatedRequest(address[3] addressArgs,
                                    uint[11] uintArgs,
                                    bytes callData) returns (address);
    function isKnownRequest(address _address) returns (bool);


RequestFactory.RequestCreated(address request)

The RequestCreated event will be logged for each newly created TransactionRequest.

RequestFactory.ValidationError(uint8 error)

The ValidationError event will be logged when an attempt is made to create a new TransactionRequest which fails due to validation errors. The error represents an error code that maps to the following errors.

  • 0 => InsufficientEndowment
  • 0 => ReservedWindowBiggerThanExecutionWindow
  • 0 => InvalidTemporalUnit
  • 0 => ExecutionWindowTooSoon
  • 0 => InvalidRequiredStackDepth
  • 0 => CallGasTooHigh
  • 0 => EmptyToAddress

Function Arguments

Because of the call stack limitations imposed by the EVM, all of the following functions on the RequestFactory contract take their arguments in the form of the following form.

  • address[3] addressArgs
  • uint256[11] uintArgs
  • bytes callData

The arrays map to to the following TransactionRequest attributes.

  • Addresses (address)
    • addressArgs[0] => meta.owner
    • addressArgs[1] => paymentData.donationBenefactor
    • addressArgs[2] => txnData.toAddress
  • Unsigned Integers (uint aka uint256)
    • uintArgs[0]  => paymentData.donation
    • uintArgs[1]  => paymentData.payment
    • uintArgs[2]  => schedule.claimWindowSize
    • uintArgs[3]  => schedule.freezePeriod
    • uintArgs[4]  => schedule.reservedWindowSize
    • uintArgs[5]  => schedule.temporalUnit
    • uintArgs[6]  => schedule.windowStart
    • uintArgs[7]  => schedule.windowSize
    • uintArgs[8]  => txnData.callGas
    • uintArgs[9]  => txnData.callValue
    • uintArgs[10] => txnData.requiredStackDepth


RequestFactory.validateRequestParams(address[3] addressArgs, uint[11] uintArgs, bytes callData, uint endowment) returns (bool[7] result)

The validateRequestParams function can be used to validate the parameters to both createRequest and createValidatedRequest. The additional parameter endowment should be the amount in wei that will be sent during contract creation.

This function returns an array of bool values. A true means that the validation check succeeded. A false means that the check failed. The result array’s values map to the following validation checks.

Check #1: Insufficient Endowment

  • result[0]

Checks that the provided endowment is sufficient to pay for the donation and payment as well as gas reimbursment.

The required minimum endowment can be computed as the sum of the following:

  • callValue to provide the ether that will be sent with the transaction.
  • 2 * payment to pay for maximum possible payment
  • 2 * donation to pay for maximum possible donation
  • 2 * callGas * tx.gasprice to pay for callGas with up to a 2x increase in the network gas price.
  • 2 * 700 * requiredStackDepth * tx.gasprice to pay gas for the stack depth checking with up to a 2x increase in network gas costs.
  • 2 * 180000 * tx.gasprice to pay for the gas overhead involved in transaction execution.

Check #2: Invalid Reserved Window

  • result[1]

Checks that the reservedWindowSize is less than or equal to windowSize + 1.

Check #3: Invalid Temporal Unit

  • result[2]

Checks that the temporalUnit is either 1 to specify block based scheduling, or 2 to specify timestamp based scheduling.

Check #4: Execution Window Too Soon

  • result[3]

Checks that the current now value is not greater than windowStart - freezePeriod.

  • When using block based scheduling, block.number is used for the now value.
  • When using timestamp based scheduling, block.timestamp is used.

Check #5: Invalid Stack Depth Check

  • result[4]

Checks that the requiredStackDepth is less than or equal to 1000.

Check #6: Call Gas too high

  • result[5]

Check that the specified callGas value is not greater than the current gasLimit - 140000 where 140000 is the gas overhead of request execution.

Check #7: Empty To Address

  • result[6]

Checks that the toAddress is not the null address 0x0000000000000000000000000000000000000000.

Creation of Transaction Requests

RequestFactory.createRequest(address[3] addressArgs, uint[11] uintArgs, bytes callData) returns (address)

This function deploys a new TransactionRequest contract. This function does not perform any validation and merely directly deploys the new contract.

Upon successful creation the RequestCreated event will be logged.

RequestFactory.createValidatedRequest(address[3] addressArgs, uint[11] uintArgs, bytes callData) returns (address)

This function first performs validation of the provided arguments and then deploys the new TransactionRequest contract when validation succeeds.

When validation fails, a ValidationError event will be logged for each validation error that occured.

Tracking API

RequestFactory.isKnownRequest(address _address) returns (bool)

This method will return true if the address is a TransactionRequest that was created from this contract.