Scheduled Call API

The Alarm service exposes getter functions for all call information that may be important to those scheduling or executing calls.

Properties of a Scheduled Call

  • bytes32 callKey: the unique identifier for this function call.
  • address contractAddress: the address of the contract the function should be called on.
  • address scheduledBy: the address who scheduled the call.
  • uint calledAtBlock: the block number on which the function was called. (0 if the call has not yet been executed.)
  • uint targetBlock: the block that the function should be called on.
  • uint8 gracePeriod: the number of blocks after the targetBlock during which it is stll ok to execute the call.
  • uint nonce: value to differentiate multiple identical calls that should happen simultaneously.
  • uint baseGasPrice: the gas price that was used when the call was scheduled.
  • uint gasPrice: the gas price that was used when the call was executed. (0 if the call has not yet been executed.)
  • uint gasUsed: the amount of gas that was used to execute the function call (0 if the call has not yet been executed.)
  • uint payout: the amount in wei that was paid to the address that executed the function call. (0 if the call has not yet been executed.)
  • uint fee: the amount in wei that was kept to pay the creator of the Alarm service. (0 if the call has not yet been executed.)
  • bytes4 sig: the 4 byte ABI function signature of the function on the contractAddress for this call.
  • bool isCancelled: whether the call was cancelled.
  • bool wasCalled: whether the call was called.
  • bool wasSuccessful: whether the call was successful.
  • bytes32 dataHash: the sha3 hash of the data that should be used for this call.

Call Key

bytes32 callKey

The following functions are available on the Alarm service. The vast majority of them take the callKey which is an identifier used to reference a scheduled call.

The callKey is computed as sha3(scheduledBy, contractAddress, signature, dataHash, targetBlock, gracePeriod, nonce) where:

  • scheduledBy: the address that scheduled the call.
  • contractAddress: the address of the contract that the function should be called on when this call is executed.
  • signature: the byte4 ABI function signature of the function that should be called.
  • dataHash: the bytes32 sha3 hash of the call data that should be used for this scheduled call.
  • targetBlock: the uint256 block number that this call should be executed on.
  • gracePeriod: the uint8 number of blocks after targetBlock during which it is still ok to execute this scheduled call.
  • nonce: the uint256 value that can be used to distinguish between multiple calls with identical data that should occur during the same time. This value only matters if you are registering multiple calls for which all of the other fields are the same.

Contract Address

address contractAddress

The address of the contract that the scheduled function call should be executed on. Retrieved with the getCallContractAddress function.

  • Solidity Function Signature: getCallContractAddress(bytes32 callKey) returns (address)
  • ABI Signature: 0x9c975df

Scheduled By

address scheduledBy

The address of the contract that the scheduled function call should be executed on. Retrieved with the getCallScheduledBy function.

  • Solidity Function Signature: getCallScheduledBy(bytes32 callKey) returns (address)
  • ABI Signature: 0x8b37e656

Called at Block

uint calledAtBlock

The block number that this call was executed. Retrieved with the getCallCalledAtBlock function. Returns 0 if the call has not been executed yet.

  • Solidity Function Signature: getCallCalledAtBlock(bytes32 callKey) returns (uint)
  • ABI Signature: 0xe4098655

Grace Period

uint8 gracePeriod

The number of blocks after the targetBlock that it is still ok to execute this call. Retrieved with the getCallGracePeriod function.

  • Solidity Function Signature: getCallGracePeriod(bytes32 callKey) returns (uint8)
  • ABI Signature: 0x34c19b93

Target Block

uint targetBlock

The block number that this call should be executed on. Retrieved with the getCallTargetBlock function.

  • Solidity Function Signature: getCallTargetBlock(bytes32 callKey) returns (uint)
  • ABI Signature: 0x234917d4

Base Gas Price

uint baseGasPrice

The value of tx.gasprice that was used to schedule this function call. Retrieved with the getCallBaseGasPrice function. Returns 0 if the call has not been executed yet.

  • Solidity Function Signature: getCallBaseGasPrice(bytes32 callKey) returns (uint)
  • ABI Signature: 0x77b19cd5

Gas Price

uint gasPrice

The value of tx.gasprice that was used to execute this function call. Retrieved with the getCallGasPrice function. Returns 0 if the call has not been executed yet.

  • Solidity Function Signature: getCallGasPrice(bytes32 callKey) returns (uint)
  • ABI Signature: 0x78bc6460

Gas Used

uint gasUsed

The amount of gas that was used during execution of this function call. Retrieved with the getCallGasUsed function. Returns 0 if the call has not been executed yet.

  • Solidity Function Signature: getCallGasUsed(bytes32 callKey) returns (uint)
  • ABI Signature: 0x86ae9e4

Signature

bytes4 signature

The ABI function signature that should be used to execute this function call. Retrieved with the getCallSignature function.

  • Solidity Function Signature: getCallSignature(bytes32 callKey) returns (uint)
  • ABI Signature: 0xc88edaed

Was Called

bool wasCalled

Boolean flag for whether or not this function has been called yet. Retrieved with the checkIfCalled function.

  • Solidity Function Signature: checkIfCalled(bytes32 callKey) returns (bool)
  • ABI Signature: 0x2a472ae8

Was Successful

bool wasSuccessful

Boolean flag for whether or not this function call was successful when executed. Retrieved with the checkIfSuccess function.

  • Solidity Function Signature: checkIfSuccess(bytes32 callKey) returns (bool)
  • ABI Signature: 0x6ffc0896

Is Cancelled

bool isCancelled

Boolean flag for whether or not this function call was cancelled. Retrieved with the checkIfCancelled function.

  • Solidity Function Signature: checkIfCancelled(bytes32 callKey) returns (bool)
  • ABI Signature: 0xaa4cc01f

Call Data Hash

bytes32 dataHash

The sha3 hash of the call data that will be used for this function call. Retrieved with the getCallDataHash function.

  • Solidity Function Signature: getCallDataHash(bytes32 callKey) returns (bytes32)
  • ABI Signature: 0xf9f447eb

Call Data

bytes data

The full call data that will be used for this function call. Retrieved with the getCallData function.

  • Solidity Function Signature: getCallData(bytes32 callKey) returns (bytes)
  • ABI Signature: 0x75428615

Payout

uint payout

The amount in wei that was paid to the account that executed this function call. Retrieved with the getCallPayout function. If the function has not been executed this will return 0.

  • Solidity Function Signature: getCallPayout(bytes32 callKey) returns (uint)
  • ABI Signature: 0xa9743c68

Fee

uint fee

The amount in wei that was paid to the creator of the Alarm service. Retrieved with the getCallFee function. If the function has not been executed this will return 0.

  • Solidity Function Signature: getCallFee(bytes32 callKey) returns (uint)
  • ABI Signature: 0xfc300522