Skip to main content

Request-Response lifecycle

This page aims to explain the complete lifecycle of an Oyster Serverless User Request. It covers everything from the initial placement of the request to receiving a callback with the response on the Request Chain. You will be guided through the various steps and coordination among the different actors involved in fulfilling the User request. The following workflow assumes that all necessary contracts have been deployed. It also assumes that Gateways are registered and support the Request Chain and that Executors are registered.

1. Provisioning the function/program​

The user defines the function or program (including the function body) to be executed when serverless calls are made. Currently, serverless functions are shared by including them in the calldata of a transaction on the Common Chain. In the future, support for other highly available storage layers may be added. While anyone can initiate these transactions, they are typically executed by a DAO, protocol, or dApp developer.

2. The User places a Request​

The User places a Request on the Relay contract deployed on the Request Chain specifying the following parameters:

  • Execution environment: See definitions
  • Serverless function: Hash of the transaction corresponding to the code to execute
  • Arguments: Input for the serverless function to be executed as utf-8 encoded string bytes
  • User timeout: Execution time limit for serverless function. It must be greater than GlobalMinTimeout and less than GlobalMaxTimeout
  • Callback contract: A contract address that implements the oysterV1Callback method in order to handle the response
  • Callback gas limit: Gas limit for callback method upon request completion
  • Max gas price: Maximum gas price to be used by gateway for the Response callback
  • Refund account: Address to receive compensation token upon failing to serve the request

In the Request transaction, the user also sends USDC and gas tokens suitable for the Request Chain. The contract evaluates the maximum amount of USDC required for performing the computation based on the UserTimeout. It then escrows this amount and refunds any excess back to the user. The number of gas tokens sent by the user depends on the maximum gas price they set for the callback and the estimated gas consumption of the callback function. Any excess gas tokens are refunded to the user once the callback function is executed.

3. A Gateway is assigned​

A Gateway is tasked with relaying the Request from the Request Chain to the Common Chain and subsequently returning the Response from the Common Chain to the Request Chain. This selection process is conducted entirely off-chain. Using the request ID, Gateways perform a deterministic stake-weighted random selection among themselves to determine which Gateway will be assigned to a specific Request. It is ensured that exactly one Gateway is chosen, provided there is at least one registered Gateway. Currently, a Gateway can be assigned multiple simultaneous Requests, and there is no concept of capacity. The assignment logic operates off-chain, as Gateways register on the Common Chain while Requests may originate from various Request Chains.

The Gateway nodes and their stakes are frozen for a given Epoch. Any state changes, such as the addition or removal of Gateways or adjustments to their stakes, are applied at the start of the next Epoch.

4. The Gateway relays the Request​

The assigned Gateway relays the request to the Jobs contract on the Common Chain. An enclave attestation from the Gateway is required to prove that the Request is valid and was indeed assigned to the concerned Gateway. If the assigned Gateway fails to submit the Request within the RequestRelayTimeout, it is slashed, and other Gateways re-run the assignment process, as described in the previous step. If the request cannot be relayed after two attempts, it is considered a failure. The User then waits until the OverallTimeout for the request and can claim their funds back. Additionally, the User becomes eligible to claim compensation from the slashed stake of the Gateways.

5. An Executor is assigned​

Three Executors are assigned to the Request on the Common Chain through a fully on-chain assignment process. This process is based on the request ID and involves a stake-weighted random selection among Executors with available capacity. If sufficient capacity is not available to assign Executors, the Request is deemed aborted. In this case, the User waits until the OverallTimeout for the request and can then claim their funds back.

6. The Executors perform the computation​

The assigned Executors perform the required computation within the specified UserTimeout. The computation can conclude in two ways: it may finish before the UserTimeout expires, resulting in a valid response, or it may time out with a TimeoutError. The Executor enclaves prepare a signed message that includes the request ID and the response. This message is then submitted to the Jobs contract on the Common Chain. Payments to the Executors are distributed in a 4:3:2 ratio of the total User fee, awarded to the first, second, and last Executor to submit the response, respectively.

If an Executor does not submit a response within the UserTimeout plus a buffer period, the Executor is slashed. If no Executor submits a response at all, the Request is deemed aborted. The User then waits until the OverallTimeout for the request and can subsequently claim their funds back. Additionally, the User becomes eligible to claim compensation from the slashed stake of the Executors.

7. The Gateway relays the Response​

The assigned Gateway relays the Response back to the Relay contract on the Request Chain. The Relay contract then forwards the response to the callback contract associated with the Request. Any revert that occurs during the callback does not affect the entire transaction. Enclave attestations ensure the integrity and provenance of the Response. If the response is not relayed within the ResponseRelayTimeout, the assigned Gateway is slashed, and other Gateways re-run the assignment process. Additionally, Gateways can only submit the response before the OverallTimeout of the Request. Currently, proving a Gateway's failure to relay the response remains an open question, as explained here.

8. Payment is released​

Upon verification of a successful response, payments are released to both the Gateway and the Executor. The Executor is compensated primarily to cover the compute costs, while the Gateway is paid mainly to cover gas expenses.