Skip to main content

Serverless Subscription

The Oyster Serverless Subscription enables Users to automate periodic serverless requests. This workflow is built upon the Request Response Lifecycle, so understanding that lifecycle is essential before proceeding further. The following steps assume that all necessary contracts have been deployed, Gateways are registered and support the Request Chain, Executors are registered, and the Serverless function has been provisioned.

1. The User places a request​

The User places a Subscription Request on the Subscription 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
  • Max gas price: Maximum gas price to be used by gateway for the Response callback
  • Callback contract: A contract address that implements the oysterV1Callback method in order to handle the response
  • Refund account: Address to receive compensation token upon failing to serve the request
  • Callback gas limit: Gas limit for callback method upon request completion
  • Request time interval: Requests are executed at this time interval
  • Start timestamp: First request will be created at this timestamp
  • Termination timestamp: No requests will be created after this timestamp

In the Subscription Request transaction, the User sends both USDC and gas tokens suitable for the Request Chain. The contract calculates the maximum amount of USDC needed to perform the computation based on the UserTimeout and the expected number of iterations. It 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, the estimated gas usage of the callback function, and the number of expected iterations. Any surplus gas tokens are refunded to the User once the callback function is executed.

2. A Gateway is assigned​

Gateways store the details of all active Serverless subscriptions. For each subscription request, the Gateway initiates the selection mechanism at the time intervals specified by the request. After that, it follows the same lifecycle as described here.

3. The Request is served​

After gateway is assigned to the request instance, it is handled similarly from Gateway relaying the Request to Releasing the Payment.

4. Subscription termination​

A serverless subscription is automatically terminated once the end timestamp is reached. Additionally, the User can choose to terminate the subscription on demand at any point while it is active. Once a subscription is terminated, Gateways will no longer relay requests to the Common Chain for that subscription.