Cron subscriptions via SDK

Simplified Subscriptions to System Events via the typescript SDK

Starting from @somnia-chain/[email protected], the typescript SDK introduces two new convenience functions to streamline creating subscriptions for system-generated events: BlockTick and Schedule. These functions reduce boilerplate by handling the underlying SubscriptionData structure and precompile interactions for you, while still allowing customization of gas fees, guarantees, and other parameters.

For a deeper understanding of how these system events work under the hood (including event signatures and behaviors), refer to the System Events documentation.

Block Tick Subscription

The BlockTick event triggers at the start of every block if no specific block number is provided, or at a targeted block if specified.

Using the SDK

Use createOnchainBlockTickSubscription to set up the subscription with minimal code:

import { SDK } from '@somnia-chain/reactivity';

// Assuming you have an instance of SomniaReactivity SDK
const reactivity = new SDK(/* your config */);

async function setupBlockTick() {
  try {
    const txHash = await reactivity.createOnchainBlockTickSubscription({
      // Optional: Specify a future block number; omit for every block
      // blockNumber: BigInt(123456789),
      handlerContractAddress: '0xYourHandlerContractAddress',
      // Optional: Override default handler selector (defaults to onEvent)
      // handlerFunctionSelector: '0xYourSelector',
      priorityFeePerGas: BigInt(1000000000), // 1 nanoSomi
      maxFeePerGas: BigInt(20000000000), // 20 nanoSomi
      gasLimit: BigInt(100000),
      isGuaranteed: true, // Ensure delivery even if delayed
      isCoalesced: false // Handle each event separately
    });
    console.log('Subscription created with tx hash:', txHash);
  } catch (error) {
    console.error('Error creating subscription:', error);
  }
}

setupBlockTick();

This returns the transaction hash on success or an error if the subscription fails.

Equivalent in Solidity

For comparison, here's the lower-level Solidity equivalent (as in the core docs):

ISomniaReactivityPrecompile.SubscriptionData
    memory subscriptionData = ISomniaReactivityPrecompile
        .SubscriptionData({
            eventTopics: [BlockTick.selector, bytes32(0), bytes32(0), bytes32(0)], // Or specify blockNumber in topics[1]
            emitter: SomniaExtensions.SOMNIA_REACTIVITY_PRECOMPILE_ADDRESS,
            handlerContractAddress: address(this),
            handlerFunctionSelector: ISomniaEventHandler.onEvent.selector,
            /* Add gas params, isGuaranteed, isCoalesced here */
    });
// Then call subscribe(subscriptionData) on the precompile

Schedule Event (One-Off Cron Job)

The Schedule event is ideal for one-time future actions. Key notes:

• Timestamp must be in the future (at least 12 seconds from n ow).

• It's a one-off subscription—automatically deleted after triggering.

• Use milliseconds (e.g., via currentmillis.com).

Using the SDK

Use scheduleOnchainCronJob for a simple setup:

import { SDK } from '@somnia-chain/reactivity';

// Assuming you have an instance of SomniaReactivity
const reactivity = new SDK(/* your config */);

async function setupSchedule() {
  try {
    const txHash = await reactivity.scheduleOnchainCronJob({
      timestampMs: 1794395471011, // e.g., Nov 11, 2026, 11:11:11.011
      handlerContractAddress: '0xYourHandlerContractAddress',
      // Optional: Override default handler selector (defaults to onEvent)
      // handlerFunctionSelector: '0xYourSelector',
      priorityFeePerGas: BigInt(1000000000), // 1 nanoSomi
      maxFeePerGas: BigInt(20000000000), // 2 nanoSomi
      gasLimit: BigInt(100000),
      isGuaranteed: true, // Ensure delivery even if delayed
      isCoalesced: false // N/A for one-off, but included for consistency
    });
    console.log('Cron job scheduled with tx hash:', txHash);
  } catch (error) {
    console.error('Error scheduling cron job:', error);
  }
}

setupSchedule();

This returns the transaction hash on success or an error if the subscription fails.

Equivalent in Solidity

For comparison, here's the lower-level Solidity equivalent (as in the core docs):

ISomniaReactivityPrecompile.SubscriptionData
    memory subscriptionData = ISomniaReactivityPrecompile
        .SubscriptionData({
            eventTopics: [Schedule.selector, bytes32(uint256(1794395471011)), bytes32(0), bytes32(0)],
            emitter: SomniaExtensions.SOMNIA_REACTIVITY_PRECOMPILE_ADDRESS,
            handlerContractAddress: address(this),
            handlerFunctionSelector: ISomniaEventHandler.onEvent.selector,
            /* Add gas params, isGuaranteed, isCoalesced here */
    });
// Then call subscribe(subscriptionData) on the precompile

These SDK functions default the emitter to SOMNIA_REACTIVITY_PRECOMPILE_ADDRESS and handle event topics automatically, ensuring your handler only responds to genuine system events.

To get started, update your typescript SDK package to @somnia-chain/[email protected] or later and integrate these functions into your dApp. If you need more advanced customizations (e.g., additional filters like origin or caller), you can still use the full SoliditySubscriptionData type directly with the createSoliditySubscription SDK function (scheduleOnchainCronJob is calling that internally).

See Solidity on-chain Reactivity Tutorial for a tutorial on how to create a regular subscription to any event emitted by any smart contract.