@rebarxyz/calculations

Calculation management framework for Rebar on-chain computations.

Overview

This package provides a simple, type-safe way to define and deploy on-chain calculations that automatically update when their inputs change.

Key Features:

• Named variable mapping (no more inline string interpolation)
• Automatic dependency resolution
• Separate code files (.star) for better syntax highlighting
• Type-safe registry with TypeScript autocomplete

Installation

pnpm add @rebarxyz/calculations

Usage

1. Create Calculation Files

Create .star files with your calculation logic using friendly variable names:

# calculations/starlark/nouns/average.star
auctions = last_seven_auctions

if len(auctions) == 0:
    return 0

return sum(auctions) / len(auctions)

2. Define Registry

Create a registry that maps variable names to node addresses:

// calculations/registry.ts
import type { CalculationRegistry } from '@rebarxyz/calculations';

export const CALCULATIONS: CalculationRegistry = {
  'nouns/average': {
    name: 'Average of Last Seven Nouns Auctions',
    file: './starlark/nouns/average.star',
    language: 'starlark',
    inputs: (inv) => ({
      last_seven_auctions: inv['nouns/history'].address
    }),
    valueType: 'float',
    unit: 'wei'
  }
};

3. Deploy Calculations

import { createAllCalculations } from '@rebarxyz/calculations';
import { CALCULATIONS } from './calculations/registry';

// After pipeline creates data nodes
const inventory = await createAllCalculations(
  client,
  CALCULATIONS,
  inventory,
  owner,
  './calculations/registry.ts'
);

How It Works

1. Load: Reads .star file
2. Transform: Replaces variable names with actual node addresses
3. Order: Topologically sorts calculations by dependencies
4. Deploy: Creates calculations on Rebar in correct order

Example

// Registry
'nouns/average': {
  inputs: (inv) => ({
    last_seven: inv['nouns/history'].address  // node123abc...
  })
}

// File: average.star
return sum(last_seven) / len(last_seven)

// After transformation (sent to Rebar):
return sum(node123abc...) / len(node123abc...)

API

createAllCalculations(client, registry, inventory, owner, registryPath?)

Creates all calculations in dependency order.

Returns: Updated inventory with calculation nodes

getCreationOrder(registry, inventory)

Returns calculation keys in topological order.

Returns: string[] - Array of calculation keys

loadCalculation(filePath, def, inventory, registryPath?)

Loads a calculation file and performs variable substitution.

Returns: Promise<string> - Transformed calculation code

License

MIT