Architecture

The Infernet SDK is composed of two core sets of contracts.

At it's heart, lies the Coordinator. This contract:

• Is responsible for managing Subscriptions, the core unit of the Infernet SDK
• Manages the node lifecycle (via Manager.sol), allowing nodes to register and activate in the network
• Is what Infernet nodes listen to for details about new or cancelled requests for compute
• Is the authorized middle-man proxy between Infernet nodes and subscribing user contracts

Developers inherit from a set of Consumers in their smart contracts, namely CallbackConsumer and SubscriptionConsumer. These contracts:

• Expose simple functions to create different types of Subscriptions at the Coordinator
• Allow receiving subscription responses via an authorized callback function only from the Coordinator

Subscriptions

Subscriptions are the core units of the Infernet SDK.

What is a subscription?

A subscription is a request (one-time or recurring) made by a user to an Infernet node to process some compute. Users initiate subscriptions; nodes fulfill these subscriptions.

A subscription is referenced by its ID, a monotonically-increasing, unique identifier.

Subscriptions can be created on-chain via the Coordinators createSubscription() function or off-chain from an authorized signer and EIP-712 message (opens in a new tab) via the createSubscriptionDelegatee() function.

For most developers, it is unnecessary to manipulate raw subscriptions, since we expose simple consumer interfaces (CallbackConsumer, SubscriptionConsumer) that developers can inherit to handle the bulk of background logic. Still, it is useful to understand how a subscription works.

Subscriptions in definition

In definition, a subscription is a struct containing nine parameters:

Example subscriptions

It is useful to illustrate some example subscriptions as they would appear as raw structs:

One-time subscription example

My contract is at address(MY_DEFI_CONTRACT). I want MY_DEFI_CONTAINER to be called with MY_DEFI_INPUTS. I want up to 3 nodes to process this computation, only once, and return immediately. I don't want any future computation subscription beyond this one request. The computation I do in my contract when an output is received costs 200_000 gas and I don't want nodes to respond if the gas price is greater than 100 gwei.

// Pseudocode
Subscription({
    owner: address(MY_DEFI_CONTRACT), // Recipient + subscription owner
    frequency: 1, // Processing only once
    period: 0, // Not recurring
    redundancy: 3, // 3 responses for my once frequency
    activeAt: now(), // Immediately active
    containerId: "MY_DEFI_CONTAINER",
    inputs: MY_DEFI_INPUTS,
    maxGasPrice: 100e9, // 100 gwei
    maxGasLimit: 200_000 + DELIVERY_OVERHEAD_WEI, // my gas overhead + response overhead
})

Recurring subscription example

My contract is at address(MY_DEFI_CONTRACT). I want MY_DEFI_CONTAINER to be called with dynamic inputs. I have exposed a getContainerFeatures() function in my contract. I want a response 31 times, once every day, with up to 2 nodes responding each time. The computation I do in my contract when an output is received costs 100_000 gas and I don't want nodes to respond if the gas price is greater than 20 gwei.

// Pseudocode
Subscription({
    owner: address(MY_DEFI_CONTRACT), // Recipient + subscription owner
    frequency: 31, // Processing 31 times
    period: 1 days, // Recurring every day
    redundancy: 2, // 2 responses for each daily frequency
    activeAt: now() + 1 days, // Active at the next period
    containerId: "MY_DEFI_CONTAINER",
    inputs: "", // Using dynamic getContainerFeatures() function exposed in MY_DEFI_CONTRACT
    maxGasPrice: 20e9, // 20 gwei
    maxGasLimit: 100_000 + DELIVERY_OVERHEAD_WEI, // my gas overhead + response overhead
})

Delivery intervals

All fulfilled computation requests are uniquely identified by a combination of three parameters:

• subscriptionId
• interval
• respondingNodeAddress

While the subscriptionId and respondingNodeAddress are self-explanatory, interval is not.

An interval is the current cycle of a subscription. As in, segmenting elapsed time since the start of a subscription (remember, activeAt) by the period of a subscription. For example, where t is current time:

• A subscription that started at time 0, repeating indefinitely every 10 seconds is at interval 1 when 0 <= t < 10 and 2 when 10 <= t < 20.
• A subscription that started at time 1500, occuring only once, is at interval 1 when t >= 1500.

To illustrate, here is a subscription with the parameters:

• frequency = 3, so a maximum of 3 intervals
• period = 10, so an interval every 10s
• redundancy = 2, so up to 2 responses per interval

Managing subscriptions

Subscriptions are managed at the Coordinator. Developers rarely have to access these raw functions and should instead opt to use one of the provided Consumer contracts. Still, for reference:

• Coordinator.sol:
  • Exposes createSubscription() that allows creating new subscriptions
  • Exposes cancelSubscription() that allows cancelling a created subscription
  • Exposes getSubscriptionInterval() to easily calculate the current interval for a subscription
  • Exposes the current highest subscription ID via id()
  • Exposes all subscriptions via an ID to subscription mapping: subscriptions()
  • Exposes deliverCompute() to let Infernet nodes fulfill subscriptions
• EIP712Coordinator.sol:
  • Exposes an off-chain delegated subscription creation function: createSubscriptionDelegatee()
  • Exposes deliverComputeDelegatee() to let Infernet nodes atomically create and fulfill a signed, off-chain delegate subscription

Coordinator

The Coordinator is the coordination layer between developer smart contracts and off-chain Infernet nodes.

Coordinator and my contract

Developer smart contracts interface with the Coordinator in two ways:

1. Smart contracts create Subscriptions with the coordinator
2. Smart contracts accept inbound subscription fulfillments from nodes, via the coordinator

Behind the scenes, the Coordinator performs an extensive set of checks and safety measures before delivering responses to developer smart contracts, including:

• Ensuring subscription responses are sent to the right owner
• Ensuring only active subscriptions are fulfilled (remember, activeAt)
• Ensuring current, not stale subscriptions are fulfilled (via period, interval)
• Ensuring only up to frequency responses are sent each interval
• Ensuring unique nodes respond each interval
• Ensuring responses consume under or equal to maxGasLimit gas
• Ensuring responses are submitted at under or equal to maxGasPrice price
• Ensuring responses execute successfully

Coordinator and Infernet nodes

Infernet nodes track state of current subscriptions and deliver subscription output via the Coordinator.

Tracking subscription state

By default, the coordinator exposes view functions like subscriptions() to access the current state of any subscription by its subscription ID. In addition, the Coordinator emits events when:

• SubscriptionCreated — a subscription is created
• SubscriptionCancelled — a subscription is cancelled
• SubscriptionFulfilled — a subscription receives a response

Through syncing to a snapshot block and continuously replaying these events, an off-chain observer like an Infernet node is able to track the state of all subscriptions in the system.

Tracking subscription inputs

Subscription inputs can be exposed to off-chain Infernet nodes in one of two ways:

1. At subscription creation, users can specify arbitrary bytes in the subscription's inputs parameter. These can only be set once (thus, commonly used by the CallbackConsumer) and are read by nodes at the same time they collect subscription state.
2. Developer smart contracts can expose a getContainerInputs() view function that dynamically exposes features based on the subscriptionID, interval, timestamp and caller (fulfilling node). Infernet nodes call this function off-chain when processing a subscription interval for the most up-to-date inputs to consume.

Fulfilling subscriptions

When ready, Infernet nodes perform off-chain computation and fulfill subscription responses at the Coordinator via functions like deliverCompute() or deliverComputeDelegatee(), specifying:

• subscriptionId — the ID of the subscription being fulfilled
• deliveryInterval — the subscription interval a response is being delivered for (must be current)
• input — optional container input bytes
• output — optional container output bytes
• proof — optional execution proof bytes

At the Ritual ML Workflow container layer, developers can return encoded bytes corresponding to rawInput, processedInput, rawOutput, procesedOutput, and proof fields. The Infernet Node simply consumes and packs these parameters into the on-chain input, output, and proof fields.