Skip to main content

Gas Reservation

Gas reservation is the powerful feature of Gear Protocol that enables the new approach programming and modern use cases.

Briefly, a program can send a message using gas that was reserved before instead of using gas from the currently processing message.

One of the key advantage of this feature is an ability of sending messages delayed in time automatically to any actor in the network - a user or another program as well as to itself. In fact, a program is able to execute itself unlimited number of blocks (provided that enough gas for execution is kept available).

A program developer can provide a special function in the program's code which takes some defined amount of gas from the amount available for this program and reserves it. A reservation gets a unique identifier that can be used by a program to get this reserved gas and use it later.

To reserve the amount of gas for further usage use the ReservationId::reserve function:

let reservation_id = ReservationId::reserve(RESERVATION_AMOUNT, TIME)
.expect("Reservation across executions");

You also have to indicate the block count within which the reserve must be used. Gas reservation is not free: the reservation for one block costs some gas. The reserve function returns ReservationId, which one can use for sending a message with that gas. To send a message using the reserved gas:

msg::send_from_reservation(reservation_id, program, payload, value)
.expect("Failed to send message from reservation");

If gas is not needed within the time specified during the reservation, it can be unreserved and the gas will be returned to the user who made the reservation.

id.unreserve().expect("Unreservation across executions");

Programs can have different executions, change state and evaluate somehow, but when it is necessary, a program can send a message with this reserved gas instead of using its own gas.

For example, let's consider the game that works completely on-chain. The players are programs that compete with each other by implementing various playing strategies. Usually, in these types of games, there is a master program that starts the game and controls the move order between the players.

To start the game, someone sends a message to the program. The gas attached to this message is spent on the players' programs, which in turn spend gas on their execution. Since the game can last quite a lot of rounds, the attached gas may not be enough to complete the game. You can send a message asking the program to continue the game, or you can use the gas reservation and make a fully automatic play.

Using gas reservation the program will be able to hold the game without interruption.