Caller Pool

The Alarm service maintains a pool of bonded callers who are responsible for executing scheduled calls. By joining the caller pool, an account is committing to executing scheduled calls in a reliable and consistent manner. Any caller who reliably executes the calls which are allocated to them will make a consistent profit from doing so, while callers who don’t get removed from the pool and forfeit some or all of their bond.

Caller Bonding

In order to execute scheduled calls, callers put up a small amount of ether up front. This bond, is held for the duration that a caller remains in the caller pool.

Minimum Bond

The bond amount is set as the maximum allowed transaction cost for a given block. This value can be retrieved with the getMinimumBond function.

  • Solidity Function Signature: getMinimumBond() returns (uint)
  • ABI Signature: 0x23306ed6

This value can change from block to block depending on the gas price and gas limit.

Depositing your bond

Use the depositBond function on the Caller Pool to deposit ether towards your bond.

  • Solidity Function Signature: depositBond()
  • ABI Signature: 0x741b3c39

Checking bond balance

Use the getBondBalance function to check the bond balance of an account.

  • Solidity Function Signature: getBondBalance(address) returns (uint)
  • ABI Signature: 0x33613cbe

Or to just check the balance of the sender of the transaction.

  • Solidity Function Signature: getBondBalance(address) returns (uint)
  • ABI Signature: 0x3cbfed74

Withdrawing your bond

Use the withdrawBond function on the Caller Pool to withdraw the bond ether.

  • Solidity Function Signature: withdrawBond()
  • ABI Signature: 0xc3daab96

If you are currently in a call pool, either active or queued, you will not be able to withdraw your account balance below the minimum bond amount.

Bond Forfeiture

In the event that a caller fails to execute a scheduled call during their allocated call window, a portion of their bond is forfeited and they are removed from the caller pool. The amount forfeited is equal to the current minimum bond amount.

There are no restrictions on re-entering the caller pool as long as a caller is willing to put up a new bond.

About Pools

The caller pool maintains a lists of caller addresses. Whenever a change is made to the pool, either addition of a new member or removal of an existing member, a new generation is queued to take place of the current generation.

The new generation will be set to begin 160 blocks in the future. During the first 80 blocks of this window, other members may leave or join the generation. The new generation will be frozen for the 80 blocks leading up to it’s starting block. Each new generation overlaps the previous generation by 256 blocks.

For example, if we are currently on block 1000, and a member exits the pool.

  • The new generation will become active at block 1160
  • The new generation will not allow any membership changes after block 1080
  • The current generation will be set to end at block 1416 (1160 + 256)

Each new generation carries over all of the previous members upon creation.

Once the queued generation becomes active, members are once again allowed to enter and exit the pool.

Each time a new generation is created, the ordering of its members is shuffled.

Note

It is worth pointing out that from the block during which you exit the pool, you must still execute the calls that are allocated to you until the current generation has ended. Failing to do so will cause bond forfeiture.

Entering the Pool

An address can enter the caller pool if the following conditions are met.

  • The caller has deposited the minimum bond amount into their bond account.
  • The caller is not already in the active pool, or the next queued pool.
  • The next queued pool does not go active within the next 80 blocks.

To enter the pool, call the enterPool function on the Caller Pool.

  • Solidity Function Signature: enterPool()
  • ABI Signature: 0x50a3bd39

If the appropriate conditions are met, you will be added to the next caller pool. This will create a new generation if one has not already been created. Otherwise you will be added to the next queued generation.

You can use the canEnterPool function to check whether a given address is currently allowed to enter the pool.

  • Solidity Function Signature: canEnterPool(address callerAddress) returns (bool)
  • ABI Signature: 0x8dd5e298

Or to to check for the address sending the transaction.

  • Solidity Function Signature: canEnterPool() returns (bool)
  • ABI Signature: 0xc630f92b

Exiting the Pool

An address can exit the caller pool if the following conditions are met.

  • The caller is in the current active generation.
  • The caller has not already exited or been removed from the queued pool (if it exists)
  • The next queued pool does not go active within the next 80 blocks.

To exit the pool, use the exitPool function on the Caller Pool.

  • Solidity Function Signature: exitPool()
  • ABI Signature: 0x50a3bd39

If all conditions are met, a new caller pool will be queued if one has not already been created and your address will be removed from it.

You can use the canExitPool function to check whether a given address is currently allowed to exit the pool.

  • Solidity Function Signature: canExitPool(address callerAddress) returns (bool)
  • ABI Signature: 0xb010d94a

Alernatively, you can check for the address sending the transaction.

  • Solidity Function Signature: canExitPool(address callerAddress) returns (bool)
  • ABI Signature: 0x5a5383ac