Fetch cTRNG values

Get cosmic random numbers through the Orbitport SDK or directly from the public IPFS beacon.

This guide covers how to fetch cTRNG (cosmic True Random Number Generation) values: through the SDK with API + IPFS fallback, through the SDK in IPFS-only mode, and directly from the public IPFS beacon without any dependencies.

Install the SDK

npm i @spacecomputer-io/orbitport-sdk-ts

Fetch a value (API with IPFS fallback)

If you have credentials, the SDK will hit the Orbitport API first and fall back to the IPFS beacon automatically if the API is unreachable.

import { OrbitportSDK } from "@spacecomputer-io/orbitport-sdk-ts";

const sdk = new OrbitportSDK({
  config: {
    clientId: process.env.ORBITPORT_CLIENT_ID,
    clientSecret: process.env.ORBITPORT_CLIENT_SECRET,
  },
});

const result = await sdk.ctrng.random();
console.log(result.data.data); // hex string of random bytes
console.log(result.data.src);  // "trng", "rng", or "ipfs"

If you don't have credentials yet, follow the Authentication guide to create an account and get a Client ID and Secret.

Response structure

Every random() call returns a ServiceResult<CTRNGResponse>:

interface ServiceResult<CTRNGResponse> {
  data: CTRNGResponse;
  metadata: {
    timestamp: number;
    request_id?: string;
  };
  success: boolean;
}

interface CTRNGResponse {
  service: string;    // "trng", "rng", or "ipfs-beacon"
  src: string;        // "trng", "rng", or "ipfs"
  data: string;       // the random value as a hex string
  signature?: {
    value: string;
    pk: string;
  };                  // present only for API responses
  timestamp?: string;
  provider?: string;
}

The signature field appears only when the value comes from the API -- it is the satellite's cryptographic signature over the random data. IPFS-sourced values do not include a per-call signature.

Use the SDK without credentials

You can skip auth entirely and read straight from the public IPFS beacon:

const sdk = new OrbitportSDK({ config: {} });

const result = await sdk.ctrng.random();
console.log(result.data.data);

In this mode, the SDK never contacts the API. It reads the latest beacon block from both an IPFS gateway and an IPFS API node and compares them for integrity.

Force IPFS as the source

Even with credentials configured, you can require an IPFS read via the src option:

const result = await sdk.ctrng.random({ src: "ipfs" });

Select an array index

The IPFS beacon publishes an array of cTRNG values per block (currently 3, may grow). Pick a specific value with index:

const first  = await sdk.ctrng.random({ src: "ipfs", index: 0 });
const second = await sdk.ctrng.random({ src: "ipfs", index: 1 });
const third  = await sdk.ctrng.random({ src: "ipfs", index: 2 });

index is 0-based. Out-of-bounds indices wrap via modulo against the array length, so requests never fail on length.

Traverse historical blocks

Each beacon block links to the previous one via a previous field, forming a chain. Use block to walk back through it:

// Fetch a value from block 10012, second item in the array.
const historical = await sdk.ctrng.random({
  src: "ipfs",
  block: 10012,
  index: 1,
});

block accepts:

"INF" (default) -- the latest block.
A number -- traverses the previous chain back to that sequence number.

Requesting a block above the current head throws.

Use a custom beacon path

If you operate your own IPFS beacon or want to point the SDK at a different one:

const result = await sdk.ctrng.random({
  src: "ipfs",
  beaconPath: "/ipns/your-custom-beacon-cid",
});

Default IPFS configuration:

Setting	Default
Gateway	`https://ipfs.io`
API	`https://ipfs.io`
Beacon path	`/ipns/k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f`

Override any of these via OrbitportConfig.ipfs.

Hit the IPFS beacon directly (no SDK)

The IPFS beacon is a public IPNS address that publishes a fresh block every 60 seconds. No credentials are needed -- you can read it with curl, fetch, or any HTTP client.

Beacon URL

https://ipfs.io/ipns/k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f

Fetch with curl

curl https://ipfs.io/ipns/k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f

Fetch with fetch

async function fetchCTRNGFromIPFS() {
  const response = await fetch(
    "https://ipfs.io/ipns/k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f"
  );
  const data = await response.json();

  console.log("Sequence:", data.data.sequence);
  console.log("Timestamp:", data.data.timestamp);
  console.log("cTRNG values:", data.data.ctrng);

  return data.data.ctrng[0];
}

Beacon block shape

{
  "previous": "/ipfs/bafkreial7oeangta7hakknhzsjzja4k2sehnsykx2u7bm6wdz46ug42me4",
  "data": {
    "sequence": 87963,
    "timestamp": 1769179239,
    "ctrng": [
      "88943046891c6c971f185c7cd69a350d850fca480facf549777efc4602ec94a6",
      "802a5afa3b09c360ec56cbe67cb615e038f307c905d199993e28ce38c21e9108",
      "dbbe94501ed32c55acb4ad4512da0c3871f497930c4d2d9061bbe7bd634458fc"
    ]
  }
}

Field	Description
`previous`	CID of the previous block. Follow it to traverse history.
`data.sequence`	Sequence number of this block.
`data.timestamp`	Unix timestamp when the block was created.
`data.ctrng`	Array of cTRNG hex strings. Currently 3 values per block.

The beacon publishes a new block every 60 seconds, so values you fetch may be up to a minute old. For lower-latency access, use the authenticated API or the SDK.

Next steps

Authentication -- get credentials for the API.
Use the KMS -- create keys, encrypt, decrypt, and sign with managed keys.
Cosmic Randomness -- learn where the randomness comes from.

Fetch cTRNG values

On this page