Quickstart

stellarium-ts is the TypeScript implementation of a Stellarium node. You embed it in a Fastify server, register the resources that live in your process, and optionally bootstrap peers and resources from a node that is already running.

Prerequisites

Node.js 20+
Fastify 5, which you create and pass to the node
RequestScript, the language your resources and requests use

Install the packages

npm install stellarium-ts fastify requestscript

Generate signing keys

Nodes sign the data they publish to peers with an Ed25519 key pair. Generate one:

node --input-type=module -e '
import { generateKeyPairSync } from "node:crypto";

const { publicKey, privateKey } = generateKeyPairSync("ed25519", {
  publicKeyEncoding: { type: "spki", format: "der" },
  privateKeyEncoding: { type: "pkcs8", format: "der" },
});

console.log(JSON.stringify({
  publicKey: publicKey.toString("base64url"),
  privateKey: privateKey.toString("base64url"),
}, null, 2));
'

Create a .env file

Importing StellariumNode loads dotenv, so a .env file in the working directory is applied automatically.

.env

BASE_URL=http://127.0.0.1:3000
SIGNING_PUBLIC_KEY=<publicKey from the previous step>
SIGNING_PRIVATE_KEY=<privateKey from the previous step>
API_KEY=<any secret string>

See Configuration for every variable.

A resource is a host object scripts can call. path and name form its fully qualified name (com.example.Weather). Each function declares RequestScript parameter and return types, and exec runs in your process.Call register before start. start creates the SQLite database, mounts the HTTP API under /v1, and listens.

server.ts

import Fastify from "fastify";
import { StellariumNode } from "stellarium-ts";
import type { StellariumResource } from "stellarium-ts";

const weather: StellariumResource = {
  id: 1,
  baseUrl: process.env.BASE_URL!,
  metadata: {},
  path: "com.example",
  name: "Weather",
  functions: [
    {
      name: "temperature",
      parameters: [{ name: "city", type: "string" }],
      returnType: "int32",
      exec: async (args) => {
        const city = args.find((arg) => arg.name === "city")?.value;
        return city === "Oslo" ? 12 : 20;
      },
    },
  ],
};

const node = new StellariumNode();
await node.register(weather);

const fastify = Fastify({ logger: true });
await node.start(fastify, {
  port: 3000,
  // Omit to run standalone. Set to copy peers and resources
  // from a node that is already up (no /v1 suffix).
  // startingPeer: "http://127.0.0.1:3001",
});

Run a request

Send a RequestScript request to your node’s /v1/run endpoint, authenticated with your API_KEY:

curl -X POST http://127.0.0.1:3000/v1/run \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"source":"request GetTemperature {\n  const weather: com.example.Weather\n  return weather.temperature(city: \"Oslo\")\n}"}'

Response

{ "returnValue": 12 }

Next steps

Join a network

Bootstrap from an existing node with startingPeer.

Charge for a resource

Add a payment manifest to a function.

HTTP API

Every route a node exposes.

Run a local network

Operator, escrow program, and two nodes on localnet.

Getting Started

Concepts

Running a node

Community

Prerequisites

Next steps

Join a network

Charge for a resource

HTTP API

Run a local network

​Prerequisites

​Next steps

Join a network

Charge for a resource

HTTP API

Run a local network

Prerequisites

Next steps