Skip to main content

Getting cTRNG via Orbitport SDK

The Orbitport SDK is a TypeScript SDK that provides a unified interface for accessing cTRNG values. It can work with or without API credentials, automatically falling back to IPFS when credentials are not provided or when the API is unavailable.

Overview​

The Orbitport SDK (@spacecomputer-io/orbitport-sdk-ts) provides:

  • Automatic source selection: Uses API if credentials are provided, otherwise uses IPFS
  • Automatic fallback: Falls back to IPFS if API fails
  • IPFS beacon support: Full support for IPFS beacon features including block traversal
  • Type safety: Full TypeScript support with IntelliSense
  • Error handling: Comprehensive error handling and validation

Installation​

Install the SDK using npm:

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

Or using yarn:

yarn add @spacecomputer-io/orbitport-sdk-ts

Quick Start​

With API Credentials​

When you provide API credentials, the SDK will attempt to use the Orbitport API first, and automatically fall back to IPFS if the API is unavailable:

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

// Initialize with API credentials
const sdk = new OrbitportSDK({
  config: {
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
  },
});

// Get a random value (tries API first, falls back to IPFS)
const result = await sdk.ctrng.random();
console.log(result.data.data); // The cTRNG value

Without API Credentials (IPFS Only)​

You can use the SDK without any credentials to access the IPFS beacon:

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

// Initialize without credentials (uses IPFS only)
const sdk = new OrbitportSDK({
  config: {},
});

// Get a random value from IPFS beacon
const result = await sdk.ctrng.random();
console.log(result.data.data); // The cTRNG value

Basic Usage​

Getting a Random Value​

The simplest way to get a cTRNG value:

const result = await sdk.ctrng.random();
console.log(result.data.data); // Hexadecimal string of random data

Response Structure​

All random() calls return a consistent response structure:

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 hexadecimal string
  signature?: {
    value: string;
    pk: string;
  }; // API only
  timestamp?: string;
  provider?: string;
}

IPFS Beacon Features​

The SDK provides advanced features for working with the IPFS beacon:

Force IPFS Usage​

You can explicitly request IPFS as the source:

// Force use of IPFS beacon
const result = await sdk.ctrng.random({ src: "ipfs" });

Select Specific Array Index​

The IPFS beacon contains an array of cTRNG values. You can select a specific value by index:

// Get the first cTRNG value (index 0)
const first = await sdk.ctrng.random({ 
  src: "ipfs", 
  index: 0 
});

// Get the second cTRNG value (index 1)
const second = await sdk.ctrng.random({ 
  src: "ipfs", 
  index: 1 
});

// Get the third cTRNG value (index 2)
const third = await sdk.ctrng.random({ 
  src: "ipfs", 
  index: 2 
});

Block Traversal​

You can traverse back through the IPFS beacon chain to access historical data:

// Get cTRNG from a specific block (traverse back through the chain)
const blockValue = await sdk.ctrng.random({ 
  src: "ipfs", 
  block: 10012, // Get from block 10012
  index: 1 // Select the 2nd value from that block
});

// Get latest block with specific index
const latestValue = await sdk.ctrng.random({ 
  src: "ipfs", 
  block: "INF", // Latest block (default)
  index: 0 // First value (default)
});

Custom IPFS Beacon Path​

You can use a custom IPFS beacon path:

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

Configuration​

You can customize the SDK configuration:

interface OrbitportConfig {
  clientId?: string; // Optional: Your client ID
  clientSecret?: string; // Optional: Your client secret
  authUrl?: string; // Optional: Auth server URL
  apiUrl?: string; // Optional: API server URL
  timeout?: number; // Optional: Request timeout in ms (default: 30000)
  retryAttempts?: number; // Optional: Retry attempts (default: 3)
  retryDelay?: number; // Optional: Retry delay in ms (default: 1000)
  ipfs?: IPFSConfig; // Optional: Custom IPFS settings
}

interface IPFSConfig {
  gateway?: string; // Default: "https://ipfs.io"
  apiUrl?: string; // Default: "https://ipfs.io"
  timeout?: number;
  defaultBeaconPath?: string; // Default: "/ipns/k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f"
}

Example: Custom Configuration​

const sdk = new OrbitportSDK({
  config: {
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    timeout: 60000, // 60 second timeout
    retryAttempts: 5,
    ipfs: {
      gateway: "https://ipfs.io",
      defaultBeaconPath: "/ipns/k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f"
    }
  }
});

Authentication​

When using the API, the SDK handles authentication automatically:

// Check if token is valid
const isValid = await sdk.auth.isTokenValid();

// Get token information
const tokenInfo = await sdk.auth.getTokenInfo();

Error Handling​

The SDK provides comprehensive error handling:

import { OrbitportSDKError, ERROR_CODES } from "@spacecomputer-io/orbitport-sdk-ts";

try {
  const result = await sdk.ctrng.random();
} catch (error) {
  if (error instanceof OrbitportSDKError) {
    console.log("Error code:", error.code); // e.g., AUTH_FAILED, NETWORK_ERROR
    console.log("Error message:", error.message);
  }
}

IPFS Beacon Integration Details​

The SDK's IPFS integration is designed to provide robustness and verifiability. When using IPFS, the SDK:

  • Fetches from both the IPFS gateway and API node
  • Compares results to ensure data integrity
  • Handles block traversal and array selection automatically
  • Provides detailed debug output when enabled

Default IPFS Configuration​

  • Gateway: https://ipfs.io
  • API: https://ipfs.io
  • Default Beacon: /ipns/k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f

Debug Output​

When debug: true is enabled in configuration, you'll see detailed logs:

[OrbitportSDK] Reading from BOTH IPFS sources:
  - Gateway: https://ipfs.io
  - API: https://ipfs.io
  - Path: /ipns/k2k4r8lvomw737sajfnpav0dpeernugnryng50uheyk1k39lursmn09f
[OrbitportSDK] ✓ Gateway and API agree on sequence/previous

Important Notes​

  • The index parameter is 0-based (first value is index 0)
  • The block parameter can be:
    • "INF" (default) - Get from the latest block
    • A number - Traverse back through the chain to that specific block
  • If the requested index exceeds the array length, it will be automatically adjusted using modulo operation
  • If the requested block is greater than the current block, an error will be thrown
  • Block traversal follows the "previous" chain, so requesting block 10012 will check the latest block, then traverse back until it finds block 10012

Complete Example​

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

async function example() {
  // Initialize SDK (works with or without credentials)
  const sdk = new OrbitportSDK({
    config: {
      // Optional: Add credentials for API access
      // clientId: "your-client-id",
      // clientSecret: "your-client-secret",
    },
  });

  try {
    // Get a random value (automatic source selection)
    const result = await sdk.ctrng.random();
    console.log("Random value:", result.data.data);
    console.log("Source:", result.data.src);

    // Get specific value from IPFS beacon
    const ipfsResult = await sdk.ctrng.random({
      src: "ipfs",
      index: 0, // First value
    });
    console.log("IPFS value:", ipfsResult.data.data);

    // Get value from historical block
    const historicalResult = await sdk.ctrng.random({
      src: "ipfs",
      block: 10000,
      index: 1,
    });
    console.log("Historical value:", historicalResult.data.data);
  } catch (error) {
    console.error("Error:", error);
  }
}

example();

Full Documentation​

For complete API reference, advanced features, and additional examples, see the npm package documentation.

Next Steps​