On Demand Coretime Library

A TypeScript library and CLI tool for ordering on-demand coretime for parachains on Polkadot relay chains. It monitors chain activity and automatically places coretime orders based on configurable criteria.

Installation

NPM Package

npm install polkadot-ondemand-core

CLI Tool

You can also install the CLI globally:

npm install -g polkadot-ondemand-core
ondemand-coretime --help

Library Usage

Basic Example

import { 
  watch, 
  OrderingMode, 
  RelayChain, 
  OnDemandConfiguration 
} from 'polkadot-ondemand-core';

const config: OnDemandConfiguration = {
  relayChain: RelayChain.Polkadot,
  parachainRpcUrls: ["wss://your-parachain-node:9944"],
  maxBlocks: 10,ts
  accountMnemonic: "your mnemonic phrase here",
  maxAmount: 1000000000,
  maxTransactions: 20,
  parachainId: 2000,
  checkIntervalMs: 5000
};

// Start monitoring and ordering coretime
await watch(config, OrderingMode.Block);

Advanced Usage

import { 
  BlockOrderingStrategy,
  TxPoolOrderingStrategy,
  withWebSocket,
  getRelayChainUrl,
  CoretimeOrderState
} from 'polkadot-ondemand-core';

// Create custom ordering logic
const relayChainUrl = await getRelayChainUrl('polkadot');
const relayClient = await withWebSocket(relayChainUrl);

const orderingState: CoretimeOrderState = {
  ordering: false,
  coreInQueue: false,
  blockCounter: 0,
};

// Use block-based strategy
const blockStrategy = new BlockOrderingStrategy(
  relayClient, 
  config, 
  orderingState
);

await blockStrategy.start();

React/Frontend Integration

import { watch, OrderingMode } from 'polkadot-ondemand-core';
import { useEffect, useState } from 'react';

function CoretimeMonitor() {
  const [isWatching, setIsWatching] = useState(false);
  
  useEffect(() => {
    if (isWatching) {
      const config = {
        // Your configuration
      };
      
      watch(config, OrderingMode.TransactionPool)
        .catch(console.error);
    }
  }, [isWatching]);

  return (
    <button onClick={() => setIsWatching(!isWatching)}>
      {isWatching ? 'Stop' : 'Start'} Coretime Monitoring
    </button>
  );
}

CLI Usage (Development)

Prerequisites

For development, clone the repository and install dependencies:

git clone <repository-url>
cd ondemand
npm install

CLI Commands

Run the CLI to start monitoring and ordering coretime:

• --config <path>: Path to your configuration JSON file (default: ./config.json)
• --mode <mode>: Ordering mode, either block or txpool (default: block)

Order coretime when a maximum number of blocks have passed without parachain activity:

npm run ondemand:block

Order coretime when the transaction pool reaches a certain size:

npm run ondemand:txpool

Global CLI Usage

After installing globally, you can use:

ondemand-coretime --config ./config.json --mode block
ondemand-coretime --config ./config.json --mode txpool

Configuration

Create a config.json file with the following structure:

{
  "relayChain": "polkadot",
  "parachainRpcUrls": ["wss://your-parachain-node:9944"],
  "maxBlocks": 10,
  "accountMnemonic": "your mnemonic phrase here",
  "maxAmount": 1000000000,
  "maxTransactions": 20,
  "parachainId": 2000,
  "checkIntervalMs": 5000
}

• relayChain: Supported values are polkadot, kusama, westend, rococo, paseo
• parachainRpcUrls: Array of WebSocket URLs for your parachain node(s)
• maxBlocks: Maximum number of relay chain blocks before ordering coretime (used in block mode)
• accountMnemonic: Mnemonic for the account that will pay for coretime
• maxAmount: Maximum amount to spend per coretime order
• maxTransactions: Maximum transactions in the pool before ordering (used in txpool mode)
• parachainId: Numeric parachain ID
• checkIntervalMs: Interval (ms) to check the transaction pool

API Reference

Main Functions

• watch(config: OnDemandConfiguration, mode: OrderingMode): Promise<void> - Main function to start monitoring and ordering coretime

Types and Enums

• RelayChain - Supported relay chains (Polkadot, Kusama, Westend, Rococo, Paseo)
• OrderingMode - Ordering strategies (Block, TransactionPool)
• OnDemandConfiguration - Configuration interface for the library
• CoretimeOrderState - Current state tracking interface

Strategy Classes

• CoretimeOrderingStrategy - Abstract base class for ordering strategies
• BlockOrderingStrategy - Orders coretime based on block intervals
• TxPoolOrderingStrategy - Orders coretime based on transaction pool size

Utility Functions

• withWebSocket(urls: string[]): Promise<PolkadotClient> - Create Polkadot client
• getRelayChainUrl(relayChain: string): Promise<string[]> - Get RPC URLs for relay chains
• parseConfiguration(path: string): Promise<OnDemandConfiguration> - Parse config file
• watchCoretimeQueue(client: PolkadotClient, parachainId: number) - Monitor coretime queue

Notes on Forking with On-Demand

If your parachain is forking with the use of this tool, you will need to enable slot-based authoring for your collator(s):

--authoring slot-based

With async backing (or --authoring lookahead), collators may produce two blocks in a row, but due to the nature of coretime, the second block gets abandoned.

Contributing

Contributions are welcome! Please open issues or submit pull requests for improvements or bug fixes.

License

This project is licensed under the MIT License.